ada query — Query Session Data
The ada query command lets you query captured session data — traces, transcripts, screenshots, and metadata.
ada query <bundle> <subcommand> [options]Session Selectors
The <bundle> argument accepts:
@latest— the most recent session- Session ID — e.g.
session_2026_01_24_14_56_19_a1b2c3 - Bundle path — a direct path to a session directory or
.adabundle
Subcommands
summary
Show session summary statistics — event counts, time range, and modules.
ada query @latest summary
ada query @latest summary --format json| Flag | Short | Default | Description |
|---|---|---|---|
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
events
List trace events with optional filters.
ada query @latest events --limit 100
ada query @latest events --thread 0 --function "viewDidLoad" --limit 50
ada query @latest events --since-ns 1000000000 --until-ns 2000000000 --limit 100 --format json| Flag | Short | Default | Description |
|---|---|---|---|
--thread | -t | (all) | Filter by thread ID |
--function | (none) | Filter by function name (substring match) | |
--limit | -l | 1000 | Maximum number of events to return |
--offset | -o | 0 | Number of events to skip |
--since-ns | (none) | Filter events with timestamp ≥ value (nanoseconds) | |
--until-ns | (none) | Filter events with timestamp ≤ value (nanoseconds) | |
--with-values | (off) | Include register values (x0-x7) from ATF detail lane | |
--format | -f | text | Output format (text, json, line, or chrome-trace) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
timeline
Show multi-thread interleaved timeline with call depth visualization.
ada query @latest timeline [options]| Flag | Short | Default | Description |
|---|---|---|---|
--thread | -t | (none) | Filter by thread ID |
--function | (none) | Filter by function name (substring match) | |
--limit | -l | 10000 | Maximum number of events to return |
--since-ns | (none) | Filter events with timestamp ≥ value (nanoseconds) | |
--until-ns | (none) | Filter events with timestamp ≤ value (nanoseconds) | |
--with-values | (off) | Include register values (x0-x7) from ATF detail lane | |
--format | -f | dtrace-flowindent | Output format (dtrace-flowindent, json, or line) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
reverse
Reverse-trace matched functions newest-to-oldest (rr-style).
ada query @latest reverse <function_pattern> [options]| Flag | Short | Default | Description |
|---|---|---|---|
--thread | -t | (none) | Filter by thread ID |
--limit | -l | 1000 | Maximum number of matching events to return |
--since-ns | (none) | Filter events with timestamp ≥ value (nanoseconds) | |
--until-ns | (none) | Filter events with timestamp ≤ value (nanoseconds) | |
--with-values | true | Include register values (x0-x7) — enabled by default for reverse | |
--format | -f | text | Output format (text, json, or line) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
functions
List all traced functions with their IDs.
ada query @latest functions
ada query @latest functions --format json| Flag | Short | Default | Description |
|---|---|---|---|
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
threads
List all traced threads.
ada query @latest threads
ada query @latest threads --format json| Flag | Short | Default | Description |
|---|---|---|---|
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
calls
Find calls to a specific function (substring match).
ada query @latest calls "viewDidLoad"
ada query @latest calls "viewDidLoad" --limit 50 --format json| Flag | Short | Default | Description |
|---|---|---|---|
--limit | -l | 1000 | Maximum number of results |
--format | -f | text | Output format (text, json, line, or chrome-trace) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
time-info
Show session time bounds and duration.
ada query @latest time-info
ada query @latest time-info --format json| Flag | Short | Default | Description |
|---|---|---|---|
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
capabilities
Show available query capabilities and tool requirements.
ada query @latest capabilities| Flag | Short | Default | Description |
|---|---|---|---|
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
transcribe info
Get voice transcript metadata without loading the full content.
ada query @latest transcribe info
ada query @latest transcribe info --format json| Flag | Short | Default | Description |
|---|---|---|---|
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
transcribe words
Get word-level timestamps for a time range.
ada query @latest transcribe words [options]| Flag | Short | Default | Description |
|---|---|---|---|
--since | (none) | Start time in seconds | |
--until | (none) | End time in seconds | |
--prompt | (none) | Initial prompt to guide transcription | |
--token-filter | (none) | Filter which token kinds appear in the tokens array | |
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
transcribe segments
Get transcript segments with pagination. The first query runs whisper-cli and caches results to transcript.json inside the session bundle. Subsequent queries reuse the cache.
ada query @latest transcribe segments --limit 100 --format json
ada query @latest transcribe segments --since 10 --until 30| Flag | Short | Default | Description |
|---|---|---|---|
--offset | -o | 0 | Number of segments to skip |
--limit | -l | 20 | Maximum number of segments to return |
--since | (none) | Filter segments starting at or after this time (seconds) | |
--until | (none) | Filter segments ending at or before this time (seconds) | |
--format | -f | text | Output format (text or json) |
screenshot extract
Extract screenshots from the screen recording at a specific time or over a time range. Supports nanosecond-precision timestamps, per-window cropping, and post-extraction filtering (dedup, anomaly detection, dirty-rects).
ada query @latest screenshot extract --time 15.5 --output /tmp/screen.png
ada query @latest screenshot extract --from 10 --to 30 --output /tmp/frames/
ada query @latest screenshot extract --time-ns 5000000000 --output /tmp/at5s.png
ada query @latest screenshot extract --from-ns 1000000000 --to-ns 3000000000 --output /tmp/range/
ada query @latest screenshot extract --from 0 --to 60 --filter --output /tmp/filtered/| Flag | Short | Default | Description |
|---|---|---|---|
--time | -t | (none) | Time in seconds to extract a single frame from |
--time-ns | (none) | Time in session-relative nanoseconds to extract a single frame from | |
--from | (none) | Start time in seconds for range extraction | |
--to | (none) | End time in seconds for range extraction | |
--from-ns | (none) | Start time in session-relative nanoseconds for range extraction | |
--to-ns | (none) | End time in session-relative nanoseconds for range extraction | |
--every | 1 | Extract every Nth frame in range mode (default: all frames) | |
--output | -o | (none) | Output file path (single mode) or directory (range mode) |
--crop-to-window-id | (none) | Crop each extracted frame to the bounds of a target-owned window | |
--filter | (none) | Post-process extracted range frames with a screenshot filter | |
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
Dedup filter flags
These flags apply when --filter dedup is active.
| Flag | Default | Description |
|---|---|---|
--dedup-delta-e | 1 | Per-pixel Oklab Delta-E threshold for dedup filter |
--dedup-delta-e-fraction | 0.001 | Maximum fraction of pixels allowed to exceed dedup-delta-e |
Anomaly filter flags
These flags apply when --filter anomaly is active (or when --filter is used in the unified workflow).
| Flag | Default | Description |
|---|---|---|
--anomaly-lambda | 1 | Bridge-term weight for anomaly triplet scoring |
--anomaly-prominence | 3 | Local-MAD prominence threshold for anomaly peaks |
--anomaly-window-frames | 10 | Radius, in frames, for local-MAD anomaly normalization |
--anomaly-peak-bridge-gap | 1 | Maximum number of UNKEPT frames to fill between two kept neighbours |
--anomaly-peak-widen-radius | 1 | Neighbor radius kept around each detected peak |
--anomaly-cursor-mask-endpoints | false | Gate residual pixels by intersection of cursor masks at source/center/target frames |
--anomaly-lum-weight | 1 | Luminance residual weight for anomaly scoring |
--anomaly-chroma-weight | 0.5 | Chroma residual weight for anomaly scoring |
--anomaly-edge-weight | 1 | Sobel-edge residual weight for anomaly scoring |
--anomaly-flow-model | raft-small | Optical-flow model used by —filter anomaly (default: raft-small) |
--anomaly-flow-execution-provider | coreml | Execution provider (default: coreml on Apple Silicon) |
--anomaly-multi-scale-lags | 1,3 | Triplet temporal lags for anomaly scoring (default: 1,3) |
--anomaly-cursor-mask-alpha | 0.75 | Cursor-mask strength (default: 0.75) |
--anomaly-cursor-mask-sigma | 20 | Cursor-mask Gaussian sigma in flow-grid pixels |
--anomaly-cursor-interp-window | 0.5 | Maximum gap for linear cursor interpolation |
--anomaly-cursor-hold-window | 0.3 | Maximum endpoint distance for nearest-hold cursor fallback |
--anomaly-event-prior-weight | 2.5 | Post-MAD input-event prior weight |
--anomaly-event-prior-sigma | 0.25 | Gaussian sigma for the post-MAD input-event prior |
Dirty-rects filter flags
These flags apply when --filter dirty-rects is active.
| Flag | Default | Description |
|---|---|---|
--dirty-rects-cursor-padding | 4 | Padding around cursor bbox for dirty-rects filter |
--dirty-rects-min-area | 16 | Minimum dirty-rect area below which rect is ignored |
--dirty-rects-pts-tolerance | 0.0083 | Tolerance (seconds) between frame time and PTS |
--dirty-rects-cursor-history-frames | 4 | Size of cursor-containment union window |
--dirty-rects-fallback | anomaly | Fallback filter when session lacks frame_events.jsonl |
screenshot key-moment
Extract key moment screenshots — visually distinct frames detected by change-ratio analysis.
ada query @latest screenshot key-moment --output /tmp/keyframes/
ada query @latest screenshot key-moment --change-threshold 0.05 --settle-interval 3.0 --output /tmp/keyframes/| Flag | Short | Default | Description |
|---|---|---|---|
--output | -o | (none) | Output directory for extracted keyframes and manifest.json (required) |
--change-threshold | 0.10 | Minimum change ratio to trigger a key moment (default: 0.10) | |
--settle-interval | 5.0 | Seconds of stable non-zero change before declaring key moment (default: 5.0) | |
--crop-window | false | Produce per-window cropped PNGs alongside full-frame output | |
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
screenshot ocr
Extract a merged keyword list from screenshot images using platform-native OCR.
ada query @latest screenshot ocr /tmp/keyframes/*.png --format json
ada query @latest screenshot ocr frame1.png frame2.png --min-confidence 0.8 --dedup| Flag | Short | Default | Description |
|---|---|---|---|
--output | -o | (none) | Write output to file instead of stdout |
--min-confidence | (none) | Filter OCR observations below this confidence | |
--dedup | (off) | Deduplicate identical text at similar positions across frames | |
--max-output-bytes | 0 | Truncate output exceeding this byte limit | |
--format | -f | json | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
video-info
Show screen recording video info (fps, frame count, codec).
ada query @latest video-info
ada query @latest video-info --format json| Flag | Short | Default | Description |
|---|---|---|---|
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
input-events
Stream recorded user input events in a time window.
ada query @latest input-events --since 10 --until 30
ada query @latest input-events --kind "mouse_down,key_down" --format json| Flag | Short | Default | Description |
|---|---|---|---|
--since | (none) | Start of time window in seconds from session start | |
--until | (none) | End of time window in seconds from session start | |
--since-ns | (none) | Filter events with session-relative timestamp ≥ value (nanoseconds) | |
--until-ns | (none) | Filter events with session-relative timestamp ≤ value (nanoseconds) | |
--kind | (all) | Comma-separated event kinds to include | |
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
windows
Query the target-process window-snapshots sidecar written by ada-recorder at screen-recording frame cadence.
windows list
Catalog distinct target windows across an interval.
ada query @latest windows list --since 0 --until 60| Flag | Short | Default | Description |
|---|---|---|---|
--since | (none) | Start of interval in seconds from session start | |
--until | (none) | End of interval in seconds from session start | |
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
windows at
Return the frame-aligned snapshot nearest to each query time.
ada query @latest windows at --at 5.0
ada query @latest windows at --at 1.0,2.5,10.2| Flag | Short | Default | Description |
|---|---|---|---|
--at | (none) | Query time(s) in seconds from session start | |
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
windows key
Return the single focused window at a given time.
ada query @latest windows key --at 15.0| Flag | Short | Default | Description |
|---|---|---|---|
--at | (none) | Query time in seconds from session start | |
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
witness-intervals
Compute evidence-witness time intervals from issue data on stdin.
echo '{"issues": [...]}' | ada query @latest witness-intervals --mode round-1
echo '{"issues": [...]}' | ada query @latest witness-intervals --mode round-2 --merge-gap-sec 1.0| Flag | Short | Default | Description |
|---|---|---|---|
--mode | (none) | Which round to compute: round-1 or round-2 | |
--merge-gap-sec | 0.5 | Gap between adjacent Round-1 intervals (seconds) that gets absorbed | |
--format | -f | json | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
trace-spans
Report contiguous spans of trace activity and gaps between them.
ada query @latest trace-spans
ada query @latest trace-spans --gap-threshold 500000000 --format json| Flag | Short | Default | Description |
|---|---|---|---|
--gap-threshold | 100000000 | Minimum gap size in nanoseconds to split spans (default: 100ms) | |
--since-ns | (none) | Filter events with session-relative timestamp ≥ value (nanoseconds) | |
--until-ns | (none) | Filter events with session-relative timestamp ≤ value (nanoseconds) | |
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
keywords
Extract domain keywords from trace symbols.
ada query @latest keywords
ada query @latest keywords --limit 30 --format json| Flag | Short | Default | Description |
|---|---|---|---|
--limit | -n | 15 | Maximum number of keywords to output |
--format | -f | text | Output format (text or json) |
--reading-model | (none) | Model reading this output; enables token-aware pagination | |
--page | -p | (none) | Page number (1-indexed). Requires --reading-model |
--cache-dir | (none) | Cache directory for stdout output (enables pagination without regeneration) |
Output Formats
Most subcommands support --format (-f):
text(default) — human-readable outputjson— structured output for programmatic useline— one entry per line (eventsandcallsonly)
This is how the /analyze skill consumes trace data.