Session Bundle Format

An ADA session bundle is a directory containing all captured data from a single debugging session. This page documents the directory layout, metadata schemas, and conventions that tools need to understand when reading session data.

Directory Layout

~/.ada/sessions/<session_id>/
├── session.json                    # Session metadata
├── manifest.json                   # Bundle manifest (entry point for queries)
├── trace/                          # Trace data root
│   └── <trace_session>/
│       ├── manifest.json           # ATF manifest (threads, modules)
│       ├── thread_<id>/
│       │   ├── index.atf           # Index lane (lightweight events)
│       │   └── detail.atf          # Detail lane (optional, rich events)
│       └── ...
├── screen.mp4                      # Screen recording (optional)
└── voice.wav                       # Voice recording (optional)

Session ID Format

Session IDs follow the pattern:

session_YYYY_MM_DD_HH_MM_SS_<hex>

For example: session_2026_01_24_14_56_19_a1b2c3

The hex suffix is derived from the high-precision timestamp at creation time, providing uniqueness when multiple sessions start in the same second.

session.json

Top-level session metadata, written when a capture starts and updated when it completes.

{
  "session_id": "session_2026_01_24_14_56_19_a1b2c3",
  "session_path": "/Users/dev/.ada/sessions/session_2026_01_24_14_56_19_a1b2c3",
  "start_time": "2026-01-24T14:56:19.123456Z",
  "end_time": "2026-01-24T15:02:30.654321Z",
  "app_info": {
    "name": "Calculator",
    "bundle_id": "com.apple.calculator"
  },
  "status": "complete",
  "pid": 12345,
  "capture_pid": 67890
}

Field	Type	Description
`session_id`	string	Unique session identifier
`session_path`	string	Absolute path to the session directory
`start_time`	string	ISO 8601 timestamp when capture started
`end_time`	string?	ISO 8601 timestamp when capture ended (null while running)
`app_info.name`	string	Name extracted from the binary filename
`app_info.bundle_id`	string?	macOS `CFBundleIdentifier` if available
`status`	enum	`"running"`, `"complete"`, or `"failed"`
`pid`	u32?	PID of the traced target process
`capture_pid`	u32?	PID of the `ada capture` process itself

manifest.json (Bundle Manifest)

Written when capture completes. This is the entry point used by ada query.

{
  "version": 1,
  "created_at_ms": 1737730579123,
  "finished_at_ms": 1737730950654,
  "session_name": "session_2026_01_24_14_56_19_a1b2c3",
  "trace_root": "trace",
  "trace_session": "trace/session_1737730579_Calculator/12345",
  "screen_path": "screen.mp4",
  "voice_path": "voice.wav",
  "detail_when_voice": true
}

Paths are relative to the session directory.

ATF manifest.json (Trace Manifest)

Located inside the trace session directory (e.g. trace/<trace_session>/manifest.json). Describes the threads and modules captured during tracing.

{
  "threads": [
    { "id": 0, "has_detail": true },
    { "id": 1, "has_detail": false }
  ],
  "time_start_ns": 1000000000,
  "time_end_ns": 5000000000,
  "modules": [
    {
      "module_id": 0,
      "path": "/Applications/Calculator.app/Contents/MacOS/Calculator",
      "uuid": "550E8400-E29B-41D4-A716-446655440000",
      "base_address": "0x100000000",
      "dsym_path": null
    }
  ]
}

Field	Type	Description
`threads[].id`	u32	Thread ID
`threads[].has_detail`	bool	Whether this thread has a detail file
`time_start_ns`	u64	Earliest event timestamp (nanoseconds)
`time_end_ns`	u64	Latest event timestamp (nanoseconds)
`modules[].module_id`	u32	Module ID (0 = main executable)
`modules[].path`	string	Full path to the binary
`modules[].uuid`	string?	Mach-O UUID for dSYM matching
`modules[].base_address`	string?	Runtime base address (hex)
`modules[].dsym_path`	string?	Path to dSYM bundle if known

Session Resolution

When you pass a bundle argument to ada query, it resolves as follows:

@latest — Reads ~/.ada/sessions/, finds the most recent session by start_time, returns its directory path
Session ID (e.g. session_2026_01_24_14_56_19_a1b2c3) — Looks up $ADA_SESSIONS_DIR/<id>/ or ~/.ada/sessions/<id>/
Direct path — Uses the path as-is, expecting it to contain manifest.json

Media Files

File	Format	Description
`screen.mp4`	H.264 MP4	Screen recording of the target app
`voice.wav`	PCM WAV	Voice recording

Voice transcription is performed lazily on first ada query ... transcribe call. The result is cached as transcript.json inside the session directory.