query-protocol.md

Darc Query Protocol

Darc's machine-readable CLI surfaces are for coding agents, desktop clients, scripts, and other tools that need stable handles into local agent-history evidence.

For archive and query reads, use Darc commands instead of:

• opening index.sqlite directly
• parsing human-oriented CLI output
• deriving analytics from raw transcript payloads outside Darc

The current machine-readable surface is:

• darc list
• darc show
• darc search
• darc stats
• darc resolve
• darc status --json
• darc upgrade --check --json

The historical darc.query.* names are schema ids, not a separate darc query ... CLI namespace.

Response Envelopes

Successful JSON commands write one envelope to stdout:

{
  "schema": "darc.query.search.turns.v1",
  "generated_at": "2026-04-06T12:00:00Z",
  "darc_version": "0.1.0",
  "data": {}
}

Fields:

• schema: stable schema id for the payload shape
• generated_at: UTC ISO 8601 timestamp generated by the CLI
• darc_version: Darc package version that emitted the response
• data: command-specific payload

Runtime and argument failures return a non-zero exit status and write a structured error envelope to stderr:

{
  "schema": "darc.error.v1",
  "generated_at": "2026-04-06T12:00:00Z",
  "darc_version": "0.1.0",
  "error": {
    "code": "unknown_session",
    "message": "No session matched prefix `11111111`.",
    "details": {
      "session": "11111111",
      "looks_like_prefix": true
    },
    "causes": []
  }
}

Stable error codes:

• invalid_arguments: rejected flags, missing arguments, or invalid combinations
• missing_required_identity: required identity such as session id, turn ordinal, or query was not supplied
• conflicting_identity_arguments: positional and flag forms supplied incompatible values for the same identity
• status_check_failed: status --json --check produced a report but at least one sync-check plan failed
• invalid_session_id: supplied session id or prefix is not a valid UUID shape
• unknown_session: no indexed session matched the full UUID or prefix
• ambiguous_session: a prefix or full id matched multiple provider/project candidates

darc status --json --check and darc status --workspace --json --check may also write a status report to stdout before returning status_check_failed on stderr.

Command Overview

Need	Command	Schema
List configured projects	darc list projects	darc.query.workspace.v1
Show workspace summary	darc show workspace	darc.query.workspace.v1
Check active project	darc status --json	darc.status.project.v1
Check whole workspace	darc status --workspace --json	darc.status.workspace.v1
Browse sessions	darc list sessions	darc.query.sessions.v1
Skim turns in a session	darc list turns <SESSION_ID>	darc.query.turns.v1
Rank or pivot files	darc list files ...	darc.query.files.v1 or darc.query.session_files.v1
Search indexed turns	darc search <QUERY>	darc.query.search.turns.v1
Open one turn	darc show turn <SESSION_ID> <TURN_ORDINAL>	darc.query.turn.v1
Open a bounded session bundle	darc show session <SESSION_ID>	darc.query.session_bundle.v1
Resolve a session prefix	darc resolve session <PREFIX>	darc.query.resolve_session.v1
Inspect workspace metrics	darc stats workspace	darc.query.insights.workspace.v1
Inspect project metrics	darc stats project	darc.query.insights.project.v1
Inspect one turn's metrics	darc stats turn <SESSION_ID> <TURN_ORDINAL>	darc.query.insights.turn.v1
Check release availability	darc upgrade --check --json	darc.upgrade.check.v1

Run darc help <command> for full flag syntax. The protocol contract is the JSON envelope, schema id, identity fields, pagination fields, and semantic rules documented here.

Recommended Workflows

Compact-first agent investigation:

darc status --json
darc list sessions --limit 5
darc search "staged init" --limit 5
darc list turns 11111111 --view oneline --limit 10
darc show turn 11111111 0 --step-limit 10

Open a bounded session bundle after choosing a candidate:

darc show session 11111111 --turn-limit 5 --step-limit 10

Verify exact text without regex escaping:

darc search \
  --mode literal \
  --query "--output-last-message" \
  --exclude-field tool-arguments

Search command output or logs for forensic work:

darc search \
  --mode regex \
  --query "panic: .*" \
  --include-tool-output \
  --since 7d

Pivot through files:

darc list files --limit 20
darc list sessions --touching "src/**/*.rs" --limit 10
darc list files --co-touched-with src/auth/session.rs --limit 10
darc list files --session 11111111

Use explicit color policy for terminal tools:

darc search --color always "staged init" --limit 5 | less -R
darc search --color never "staged init" --limit 5

Shared Rules

Most read commands are project-scoped. When --project-id is omitted, Darc resolves the active project from the current directory. Project-wide provider filters default to all providers when --provider is omitted.

Session-scoped commands accept a full UUID or an unambiguous UUID prefix. Pass --provider, --project-id, or a longer prefix when the identity is ambiguous.

Shared options:

• --root <path> reads from a custom Darc root
• --color <auto|always|never> controls terminal-only ANSI JSON coloring on read commands
• --limit and --offset page list/search results and default to 10 and 0 where supported
• --limit 0 returns an empty page with has_more, which is useful for cheap existence probes
• --since is an inclusive lower bound and --until is an exclusive upper bound
• relative time filters use <days>d, such as 7d; absolute filters use ISO 8601 timestamps

Shared-index scope:

• Session-oriented reads are local-only by default. This includes darc list sessions, darc search, darc list turns, darc list files --session, darc show session, darc show turn, and darc stats turn.
• --shared is shorthand for --scope shared where supported.
• --scope local|shared|all chooses local sessions, imported shared sessions, or both.
• --author <user-id|email|display-name> restricts imported shared sessions by their recorded provenance author and implies shared scope when no explicit --scope is supplied. The stable user_id is derived from the export signing key; recorded emails and display names are convenience labels from the exporter's Git config, not authenticated identity.
• Project-wide file pivots and workspace/project stats are aggregate surfaces and do not yet expose shared scope flags.

Field conventions:

• field names are snake_case
• stable enum values are lowercase
• timestamps are UTC ISO 8601 unless a field explicitly documents local-day semantics
• nullable values are explicit null
• list fields use empty arrays instead of being omitted
• ordering is deterministic where practical

Client compatibility:

• branch on schema, not darc_version
• new fields may be added within a schema version
• clients should ignore unknown fields
• breaking changes after stabilization should use a new schema id, such as ...v2

Search Modes

darc search is turn-scoped. Every hit includes session_id and turn_ordinal so callers can follow up with darc show turn or darc show session.

Mode	Query shape	Use when
keyword	terms such as "panic unwrap"	broad discovery over Darc's derived per-turn text
literal	exact plain text	matching exact strings without regex escaping
regex	Rust regular expression	matching patterns, error variants, or stack traces
file-name	basename text such as lib.rs	finding turns associated with a file name
file-path	project-relative glob such as docs/**/*.md	finding turns associated with paths matching a glob
path-fragment	path text such as query-protocol	finding turns associated with a path substring or prefix

Keyword search uses Darc's derived per-turn search index. It includes user messages, final answers, commentary, tool names, delegation summaries, and similar compact evidence. It does not include raw tool outputs.

Literal and regex search inspect derived evidence rows. By default, they skip bulky tool_output evidence. Pass --include-tool-output for forensic searches through command output, logs, stack traces, and similar text.

Literal and regex searches accept repeatable --field and --exclude-field filters. Accepted field names include:

• user-message
• final-answer
• commentary
• reasoning-summary
• tool-name
• tool-arguments
• tool-output
• delegation-summary
• delegation-metadata
• hook-summary
• attachment-metadata
• provider-response-item-metadata

File search modes populate matched_paths. Literal and regex modes populate matches. Both previews are bounded by caller-controlled limits:

• --matched-path-limit <n> or --include-all-matched-paths
• --match-limit <n>

Payload Notes

Session and turn list payloads expose best-effort model, token, runtime, and patch-count fields for lightweight clients. These fields may be null when older or provider-specific transcripts did not report stable values.

Session summary payloads include provenance:

• origin_kind: local or shared
• user_id, user_name, and user_email: author metadata for imported shared sessions, otherwise null
• origin_remote: canonical non-secret remote/branch provenance key for imported shared sessions
• imported_at: UTC import timestamp for imported shared sessions

Session-list and search payloads include origin_scope and author so clients can distinguish local-only, shared-only, and mixed result sets.

Token fields preserve provider semantics where possible. reasoning_token_count is a subset of output tokens, not an additional token bucket to add on top of output_token_count.

File analytics are Darc-derived heuristics from normalized tool calls and observed command text. They are not syscall-level traces. Commands such as git, cargo, inline scripts, shell loops, or helper scripts may touch files without naming every path explicitly.

In-project absolute paths, repo-relative paths, and ./-prefixed paths are normalized to one project-scoped display path when Darc can resolve the project root. Out-of-project accesses are not exposed in project-scoped file pivots.

darc show turn and darc show session default to --view narrative, which omits bulky tool arguments, tool outputs, and raw payload blobs. Use --view full for full normalized steps, and --include-raw only when raw debug fields are needed.

Indexed session data is best-effort redacted before storage. Redaction targets common secret formats, credential-like JSON fields, authorization headers, signed URL parameters, local home-directory prefixes, and bulky encoded blobs. Raw provider session archives and raw SQLite index files remain local implementation data; future sharing flows should export fresh redacted indexed projections rather than copying migrated cache files.

Insights payloads use host-local civil days for daily aggregates. Timestamp fields such as started_at and latest_turn_at remain UTC ISO 8601 strings.

darc upgrade --check --json contacts GitHub Releases and reports the latest available Darc release metadata. On network, HTTP, argument, or release-metadata failures, it writes darc.error.v1 to stderr.

Schema Reference

Current schema ids:

• darc.query.workspace.v1: workspace summary, configured projects, and active project metadata
• darc.status.project.v1: active project status and optional sync-check plan
• darc.status.workspace.v1: workspace-wide status and optional sync-check plans
• darc.query.sessions.v1: paginated session summaries for one project
• darc.query.turns.v1: paginated turn summaries for one session
• darc.query.files.v1: project-scoped top-file, path, and co-touch pivots
• darc.query.session_files.v1: paginated file touches for one session
• darc.query.search.turns.v1: paginated turn search hits
• darc.query.turn.v1: one bounded turn detail
• darc.query.session_bundle.v1: one session summary, bounded turn details, and capped session-file preview
• darc.query.resolve_session.v1: UUID or UUID-prefix resolution
• darc.query.insights.workspace.v1: workspace-level aggregate metrics
• darc.query.insights.project.v1: project-level aggregate metrics
• darc.query.insights.turn.v1: one-turn tool, file, token, runtime, and patch metrics
• darc.upgrade.check.v1: release availability check
• darc.error.v1: structured JSON error envelope

The v1 schemas are the active development contract. Darc Desktop and agent workflows should treat them as stable enough for integration work, but the project may still make additive changes before final stabilization.