arul28/ade/ade-search

ADE search

What it is

ade search queries deterministic full-text indexes maintained by ADE. Chat queries include project-backed chats from every project registered with the machine brain. Other kinds — terminal/CLI scrollback, PRs, commits, branches, lanes, workspace files, Linear issues, and proof artifacts — come from the active project. Personal/no-project chats are intentionally excluded and stay on the separate personal-chat surface.

This policy is identical for session-bound agents and unbound human shells; search does not silently narrow chat hits to the caller's own session. It is not a grep over .ade/: the runtime keeps each project index fresh and the machine router combines bounded chat result pages. Each project contributes at most its first 200 matches to one aggregate query; resultsTruncated: true (and the text-mode bounded: line) means you should narrow the query rather than assuming the tail was exhaustive. Every hit carries a deep link back to the exact ADE surface.

Use it instead of poking at .ade/ade.db, replaying git log, or asking the user "which chat was that in". It answers "where did this happen in ADE" across kinds in one call.

Command forms

ade search "<query>"                       # ranked results as JSON (default)
ade search "<query>" --text                # aligned rows + count summary
ade search "<query>" --kind chat,terminal  # restrict to kinds
ade search "<query>" --lane fix-login      # restrict to a lane (id or name)
ade search "<query>" --limit 20            # cap result count
ade search "<query>" --cursor <nextCursor> # next page from a prior query
ade search --status --text                 # index doc counts + backfill state
ade search --rebuild --text                # rebuild the index (CTO-only)

ade search refuses an option it does not know. Global options such as --project-root go before the command: ade --project-root <path> search "<query>".

Query syntax

The query string is passed through to the index. It supports:

Inline kind: / lane: filters and the --kind / --lane flags can be mixed; the flags are the scriptable form and validate their input.

Kind values: lane, chat, terminal, pr, commit, branch, file, linear, artifact. --kind takes a comma-separated list and rejects unknown kinds with a usage error (exit 2).

Result kinds and where they deep-link

Each result also carries laneId/laneName, sessionId, and updatedAt; the deepLink is an ade://… URL you can hand to ade open. Machine-routed results additionally carry projectId, projectName, and projectRoot so same-named lanes and chats remain distinguishable.

Output modes

• --json (default): the full SearchQueryResult — results[] (each with

kind, id, title, snippet, matchRanges, laneId, laneName, sessionId, deepLink, updatedAt, and machine-routed project fields), totalByKind, nextCursor, and project coverage metadata. Use this when you need the deep link or want to page.

• --text: aligned KIND PROJECT TITLE SNIPPET ID rows when project

metadata is present, then a N results (chat 3, terminal 2, …) summary from totalByKind, and a more: --cursor <value> line when another page exists. Use this for a quick human-readable scan.

Exit codes are script-friendly: 0 when the query matched at least one result, 1 when it matched nothing (so ade search "x" >/dev/null && … works), and 2 on a usage error such as an unknown --kind.

When to use which

• "Which chat discussed X?" → ade search "X" --kind chat --text, then

ade open <deepLink> or read a bounded window with ade chat read <session> --limit 20 --max-chars 8000 --text. Use --page --cursor <nextCursor> only when you need older content.

• "Which terminal ran the failing command?" →

ade search "<command or error>" --kind terminal --text; the result offset drops you at the failure in scrollback.

• "Find the PR discussing Y." → ade search "Y" --kind pr --text.
• "Where in this lane did we touch Z?" →

ade search "Z" --lane <lane> --text across files, commits, and chats.

• Index looks stale or empty → ade search --status --text to see

docCount, per-kind counts, and backfillComplete; rebuild with ade search --rebuild only if backfill is genuinely broken.

Reach for ade search before grepping .ade/ internals or asking the user to locate something. Remember the boundary: chats span registered projects; non-chat kinds use the active project; personal chats are excluded.