agentgrep search¶

The agentgrep search command searches normalized prompts and history records across every configured agent backend (Codex, Claude Code, Cursor, Gemini). Search is read-only — agentgrep never mutates the source stores.

Examples¶

A literal single-term search:

$ agentgrep search bliss

Combine multiple terms with an agent filter:

$ agentgrep search serene bliss --agent codex

Stream history matches as NDJSON for piping:

$ agentgrep search prompt history --type history --ndjson

Emit a single JSON document for one-shot consumers:

$ agentgrep search serenity --json

Browse interactively in the Textual TUI:

$ agentgrep search design --ui

Command¶

Usage¶

usage: agentgrep search [-h] [--agent {codex,claude,cursor,gemini,all}]
                        [--type {prompts,history,all}] [--any] [--regex]
                        [--case-sensitive] [--limit N]
                        [--progress {auto,always,never}] [--json | --ndjson |
                        --ui]
                        [terms ...]

Positional Arguments¶

terms¶

Keywords or regex patterns

Default: None

Options¶

--agent¶

Limit results to a specific agent; repeatable

Default: []
Choices: codex, claude, cursor, gemini, all

--type¶

Record type to search (default: prompts)

Default: prompts
Choices: prompts, history, all

--any¶

Match any term instead of requiring all terms

Default: False

--regex¶

Treat terms as regular expressions

Default: False

--case-sensitive¶

Perform case-sensitive matching

Default: False

--limit N¶

Limit the number of results

Default: None
Type: int

--progress¶

Show search progress on stderr

Default: auto
Choices: auto, always, never

--json¶

Emit one JSON document

Default: False

--ndjson¶

Emit one JSON object per line

Default: False

--ui¶

Launch a read-only UI

Default: False

JSON output¶

Pass --json to emit a single JSON document containing the matching records:

$ agentgrep search --json "deploy"

The envelope carries a list of normalized SearchRecord entries. Each record carries an agent tag (codex / claude / cursor / gemini), the source path, the matching text excerpt, and session metadata when available.

--json is the right mode when the caller wants to parse the entire result at once — for example a wrapping agent that scores or post-processes records before presenting them.

NDJSON output¶

Pass --ndjson to stream one JSON object per line:

$ agentgrep search --ndjson "deploy" | jq '.agent'

Each line is a single SearchRecord. This mode is the right pick for piping into jq, into another CLI, or into a non-MCP agent that consumes results incrementally.

Interactive UI¶

Pass --ui to launch the Textual TUI instead of streaming records to stdout:

$ agentgrep search --ui "deploy"

The TUI is read-only — it renders the same records the JSON modes emit, but lets you scroll, filter, and inspect record bodies interactively. --ui is mutually exclusive with --json and --ndjson.

Filtering by agent¶

--agent is repeatable and limits the search to specific backends:

$ agentgrep search --agent claude --agent codex "deploy"

Pass --agent all (or omit the flag) to search every available backend.