agentgrep search¶

Examples¶

Rank prompts by relevance to a multi-term query (terms are AND-matched):

$ agentgrep search streaming parser

Search selected conversations related to prompt matches:

$ agentgrep search "deploy" --deep

Search prompt records across every readable conversation backend:

$ agentgrep search "deploy" --exhaustive

Search prompts and conversations together in one exhaustive sweep:

$ agentgrep search "deploy" --exhaustive --scope all

Prefer records from the project you are standing in:

$ agentgrep search --here deploy

Hard-filter by recorded working directory:

$ agentgrep search --cwd ~/work/django-project deploy

Keep only strong matches by raising the score bar:

$ agentgrep search --threshold 70 migration

Skip ranking and grouping for a flat, globally newest-first list:

$ agentgrep search --no-rank --no-group caching

Take just the top results:

$ agentgrep search bliss --limit 5

Hand the same query to the Textual explorer:

$ agentgrep search bliss --ui

Stream machine-readable results for a script or non-MCP agent:

$ agentgrep search bliss --ndjson

Ranking and relevance¶

By default search scores every matched record against your query with rapidfuzz’s WRatio and sorts best-first. The default --threshold 0 shows every match; raise it to drop weak ones:

$ agentgrep search --threshold 70 release

A high threshold can filter everything out. A no-match terminal message does not distinguish threshold filtering from other output filters. Pass --no-rank to bypass scoring entirely and return records globally newest-first. This may still buffer until the engine knows the global frontier; grep instead preserves scan order so it can stream:

$ agentgrep search --no-rank release

Deduplication and grouping¶

AI conversation stores replay the same text across a session. To keep one chatty session from dominating, search deduplicates repeated record text per session before ranking — the same session deduplication grep applies, minus the --no-dedupe escape hatch. Survivors are then grouped by session, with the best match opening each group. Pass --no-group for a flat ranked list with no session headings:

$ agentgrep search --no-group caching

Search depth and result scope¶

search opens only dedicated prompt-history stores by default. This fast path returns user-authored prompts without walking conversation backends.

Pass --deep to use matching prompt evidence to select and search a bounded set of conversations. It attempts at most 25 distinct conversations by default; change that request-local work bound with --conversation-limit. Targeted results report status.state="approximate" and separate eligible, selected, and completed conversation counts:

$ agentgrep search "docs deploy" --deep

$ agentgrep search "docs deploy" --deep --conversation-limit 10

The default of 25 is an unmeasured routing-policy value, not a result limit or completeness claim. Repeated prompt evidence for one proven conversation uses one slot. Unresolved or ambiguous selected locators consume a slot and are not backfilled. Targeted routing is currently available for Codex, Claude Code, Grok, and Antigravity CLI; other conversation backends require exhaustive effort.

Pass --exhaustive to search every readable conversation backend:

$ agentgrep search "docs deploy" --exhaustive

--exhaustive with an omitted CLI scope keeps prompt scope, so the command above projects prompt records from every readable transcript. Depth controls which storage backends may be read. --scope separately controls returned record kinds. Pass --scope conversations for full conversation, session, assistant, tool, and event records, or combine exhaustive reads with --scope all for both surfaces:

$ agentgrep search "docs deploy" --exhaustive --scope all

For compatibility, explicit conversation and all scopes already imply the exhaustive reads those records require. A prompt-only scope cannot be combined with --deep.

A depth: (alias effort:) query-language field selects the same read policy inline, composable with other predicates in one query — deep is accepted as a synonym for targeted:

$ agentgrep search 'depth:exhaustive scope:all docs deploy'

--deep/--exhaustive and an inline depth:/effort: term cannot both appear in one command; pick one. See Query language for the full field.

Project context¶

When a backend records where a prompt came from, search can use that RecordOrigin to find the right project history. --here keeps global results visible but boosts records from the current checkout; --only-here hard-filters to that checkout and can be used without text terms. The detector preserves the logical $PWD, so a symlinked checkout is treated the same way the shell sees it.

$ agentgrep search --here deploy

Use explicit filters when you know the project path or branch you want:

$ agentgrep search --cwd ~/work/django-project deploy

$ agentgrep search --branch main agent:codex

--cwd and --repo accept relative paths and ~; blank values are ignored. Origin filters compose with the user query without changing the meaning of punctuation-heavy literals, URLs, or phrases. The same fields are available inline as cwd:, repo:, worktree:, branch:, project:, and cwd_hash:; see Origin fields.

--here affects ranking only, so it is rejected with --no-rank and with --ui. Use --only-here when you want the Textual explorer to open on current-project results.

Output¶

The default output is ranked, grouped text for terminal reading. For scripts and non-MCP agents, two machine-readable modes mirror grep:

• --json emits one JSON document with top-level query, results, and engine-owned summary fields. Best when the caller parses the whole result at once.

• --ndjson emits one JSON object per line and ends with the equivalent summary after the globally ordered result set is ready. Best when a caller needs line-delimited records rather than a single JSON document.

$ agentgrep search bliss --json

When a backend exposes project context, each serialized SearchRecord can include an origin object with cwd, repo, worktree, branch, remote, and cwd_hash fields. Path values use the same display-safe layer as path; credentialed remotes are stripped before output, and local file:// remotes are omitted. Filters compare against the recorded origin before display rewriting, so privacy formatting does not change match behavior.

Interactive UI¶

Pass --ui to open the Textual explorer pre-filled with the search query — the tig-shaped overlay model, where agentgrep search bliss --ui is to agentgrep search bliss what tig log is to git log.

$ agentgrep search bliss --ui

Query language¶

search accepts the same Lucene-style field syntax as grep and find — mix field predicates with text inline:

$ agentgrep search agent:codex bliss

The predicates (agent:, path:, timestamp:, cwd:, repo:, branch:, and more) prune and filter sources around the text terms. See Query language for the full grammar.

Progress¶

A stderr progress spinner (when stderr is a TTY) signals a search is still running on slow stores. Silence it with --no-progress or the equivalent --progress=never:

$ agentgrep search --no-progress bliss

Progress always writes to stderr, so it never collides with stdout — agentgrep search bliss | jq won’t see the spinner in the piped buffer.

Command¶

usage: agentgrep search [-h]
                        [--agent {codex,claude,cursor-cli,cursor-ide,gemini,antigravity-cli,antigravity-ide,grok,pi,opencode,vscode,all}]
                        [--scope {prompts,conversations,all}] [--deep |
                        --exhaustive] [--conversation-limit N]
                        [--case-sensitive] [--cwd PATH] [--repo PATH]
                        [--branch NAME] [--here | --only-here] [--limit N]
                        [--threshold N] [--no-group] [--no-rank]
                        [--progress {auto,always,never}] [--no-progress]
                        [--json | --ndjson | --ui]
                        [TERM ...]

Exit codes¶

agentgrep search returns:

• 0 — at least one ranked result survived

• 1 — no matches, including when --threshold filtered them all out

search has no separate runtime-error exit code — unlike grep, whose 2 covers invalid-regex and unreadable-store errors. Malformed flags are still rejected by argparse before the search starts.