agentgrep find¶

The agentgrep find command enumerates the on-disk prompt and history stores agentgrep can read — Codex session files, Claude Code JSONL transcripts, Cursor SQLite databases, Gemini history. Use it to inspect what agentgrep sees before running a search, or to feed a catalog into another tool.

The flag grammar mirrors fd: the positional PATTERN is treated as a regex by default, with -F (literal), -g (glob), and --exact modifiers; -t filters by record kind; -e filters by file extension; -l switches to a long-format output; -0 separates output with NUL for xargs -0 consumers. -g matches against the file basename by default; --full-path opts into matching the absolute path (fd’s -p).

The default output is one path per line — the fd-faithful shape. Display output collapses the current user’s home directory to ~; use --absolute-path or -0/--print0 when a downstream shell tool needs real filesystem paths. Use -l/--list-details to add metadata (agent, kind, store, adapter_id) as tab-separated columns.

Examples¶

List every store agentgrep can read (no positional pattern needed — fd parity):

$ agentgrep find

Narrow to one agent:

$ agentgrep find codex

Filter by literal substring (the legacy default before fd alignment):

$ agentgrep find -F sessions

Glob the file basename:

$ agentgrep find -g '*.jsonl'

Glob the absolute path (fd’s -p parity):

$ agentgrep find -g '*/sessions/*.jsonl' --full-path

Restrict to one record kind and one file extension:

$ agentgrep find -t prompts -e jsonl

Long format for column-aware downstream tools:

$ agentgrep find -l

NUL-separated output for xargs -0:

$ agentgrep find -0 | xargs -0 -n1 ls -l

Open the Textual explorer pre-filled with the find query:

$ agentgrep find -t prompts --ui

Silence the source-discovery spinner:

$ agentgrep find --no-progress codex

Live streaming¶

find consumes the Event-stream engine directly — text, NDJSON, and --print0 output emit each record as the engine discovers it, with stdout flushed when stdout is a TTY. Text output remains privacy-collapsed for display; --print0 emits raw paths for shell consumers. --json and --list-details buffer because their output shape benefits from the full record list up front.

Command¶

Usage¶

usage: agentgrep find [-h]
                      [--agent {codex,claude,cursor-cli,cursor-ide,gemini,antigravity-cli,antigravity-ide,grok,pi,opencode,vscode,all}]
                      [-g | -F | --exact] [-i | -s]
                      [-t {prompts,history,sessions,all}] [-e EXT] [-l] [-0]
                      [-a] [--full-path] [--limit N]
                      [--progress {auto,always,never}] [--no-progress]
                      [--json | --ndjson | --ui]
                      [pattern]

Positional Arguments¶

pattern¶

Optional pattern matched against agent/store/adapter/path

Default: None

Options¶

--agent¶

Limit results to a specific agent; repeatable

Default: []
Choices: codex, claude, cursor-cli, cursor-ide, gemini, antigravity-cli, antigravity-ide, grok, pi, opencode, vscode, all

-t, --type¶

Restrict to a record kind (default: all)

Default: None
Choices: prompts, history, sessions, all

-e, --extension EXT¶

Filter by extension (repeatable, e.g. -e jsonl -e db)

Default: []

-l, --list-details¶

Long format: agent, kind, store, adapter_id, path

Default: False

-0, --print0¶

Separate output records with NUL instead of newline

Default: False

-a, --absolute-path¶

Print real absolute paths instead of privacy-collapsed display paths

Default: False

--full-path¶

With -g, match the glob against the absolute path instead of the file basename (fd's -p)

Default: False

--limit N¶

Limit the number of results

Default: None
Type: int

--progress¶

Show source-discovery progress on stderr

Default: auto
Choices: auto, always, never

--no-progress¶

Silence the stderr progress spinner (alias for --progress=never)

Default: None

-g, --glob¶

Treat PATTERN as a shell glob (fnmatch)

Default: False

-F, --fixed-strings¶

Treat PATTERN as a literal substring (legacy default)

Default: False

--exact¶

Require PATTERN to equal the adapter_id exactly

Default: False

-i, --ignore-case¶

Force case-insensitive matching (default smart-case)

Default: False

-s, --case-sensitive¶

Force case-sensitive matching

Default: False

--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 every discovered store:

$ agentgrep find --json

The envelope carries a list of FindRecord entries. Each record carries an agent tag, the absolute path, the store kind, and discovery metadata.

--json is the right mode when the caller wants to parse the entire catalog at once — for example a wrapping agent that decides which stores to read before issuing a search call.

NDJSON output¶

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

$ agentgrep find --ndjson | jq -r '.path'

Each line is a single FindRecord. Use this mode when piping into jq, into another CLI, or into a non-MCP agent that consumes the catalog incrementally.

Filtering by agent¶

--agent is repeatable and limits discovery to specific backends:

$ agentgrep find --agent claude --agent codex

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

Query language¶

find accepts the same Lucene-style field syntax as the other subcommands. Source-level field predicates (agent:, path:, store:, mtime:) prune sources before they’re emitted. path: matches real absolute paths and also accepts current-user ~ prefixes:

$ agentgrep find agent:codex

$ agentgrep find 'path:~/.codex agent:codex'

$ agentgrep find 'mtime:>2026-01-01'

Record-level fields (type:, timestamp:, model:, role:) are accepted by the parser but don’t filter find output since find emits one record per source. Use agentgrep grep if you need record-level filtering. See Query language for the full grammar.