CLI¶

The agentgrep CLI is the fastest path to your local AI agent prompt and history archives from a terminal. It wraps the same read-only discovery and parsing layer the MCP server exposes — search, find stores, filter by agent — and lets you pipe everything through --json or --ndjson so any script or non-MCP agent can consume the results.

With uvx run installed:

$ uvx agentgrep --help

Then run it from the terminal:

$ uvx agentgrep search "deploy"

$ uvx agentgrep search --agent claude --json "deploy"

$ uvx agentgrep find --json

With uvx run installed:

$ uvx --exclude-newer P7D --exclude-newer-package agentgrep=2099-01-01 agentgrep --help

Then run it from the terminal:

$ uvx --exclude-newer P7D --exclude-newer-package agentgrep=2099-01-01 agentgrep search "deploy"

$ uvx --exclude-newer P7D --exclude-newer-package agentgrep=2099-01-01 agentgrep search --agent claude --json "deploy"

$ uvx --exclude-newer P7D --exclude-newer-package agentgrep=2099-01-01 agentgrep find --json

With uvx run installed:

$ uvx --no-config agentgrep --help

Then run it from the terminal:

$ uvx --no-config agentgrep search "deploy"

$ uvx --no-config agentgrep search --agent claude --json "deploy"

$ uvx --no-config agentgrep find --json

With pipx run installed:

$ pipx run agentgrep --help

Then run it from the terminal:

$ pipx run agentgrep search "deploy"

$ pipx run agentgrep search --agent claude --json "deploy"

$ pipx run agentgrep find --json

With pipx run installed:

$ pipx run agentgrep --help

Then run it from the terminal:

$ pipx run agentgrep search "deploy"

$ pipx run agentgrep search --agent claude --json "deploy"

$ pipx run agentgrep find --json

pip has no per-package cooldown override, so this snippet runs without cooldown enforcement. Switch to the `uvx run` or `uv add` tab — they apply the cooldown to transitive deps via `--exclude-newer` while exempting agentgrep itself via `--exclude-newer-package`.

With pipx run installed:

$ pipx run agentgrep --help

Then run it from the terminal:

$ pipx run agentgrep search "deploy"

$ pipx run agentgrep search --agent claude --json "deploy"

$ pipx run agentgrep find --json

With uv add installed:

$ uv add agentgrep

Then run it from the terminal:

$ uv run agentgrep search "deploy"

$ uv run agentgrep search --agent claude --json "deploy"

$ uv run agentgrep find --json

With uv add installed:

$ uv add --exclude-newer P7D --exclude-newer-package agentgrep=2099-01-01 agentgrep

Then run it from the terminal:

$ uv run agentgrep search "deploy"

$ uv run agentgrep search --agent claude --json "deploy"

$ uv run agentgrep find --json

With uv add installed:

$ uv add --no-config agentgrep

Then run it from the terminal:

$ uv run agentgrep search "deploy"

$ uv run agentgrep search --agent claude --json "deploy"

$ uv run agentgrep find --json

$ pip install --user --upgrade agentgrep

Then run it from the terminal:

$ agentgrep search "deploy"

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

$ agentgrep find --json

$ pip install --user --upgrade agentgrep

Then run it from the terminal:

$ agentgrep search "deploy"

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

$ agentgrep find --json

$ pip install --user --upgrade agentgrep

Then run it from the terminal:

$ agentgrep search "deploy"

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

$ agentgrep find --json

agentgrep search

Search prompts and history across every configured agent.

agentgrep search

agentgrep find

Discover the on-disk stores agentgrep can read.

agentgrep find

Use from another agent¶

The CLI is a first-class consumer for any agent that doesn’t speak MCP. Two flags govern machine-readable output:

--json emits a single JSON document with an envelope carrying the record list. Best when the caller wants to parse the whole result at once.
--ndjson streams one JSON object per line. Best for piping into jq, into another CLI, or into an agent that consumes results incrementally.

Both flags work on search and find. See JSON output and JSON output for the record shapes.

Agents that already speak MCP should prefer agentgrep-mcp — same discovery and parsing surface, but exposed as MCP tools with typed schemas.

Examples¶

search is the default subcommand, so agentgrep bliss is equivalent to agentgrep search bliss:

$ agentgrep bliss

Combine multiple terms with an agent filter:

$ agentgrep serene bliss --agent codex

Stream history matches as NDJSON:

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

List stores for one agent as JSON:

$ agentgrep find cursor --json

Command: `agentgrep`¶

Usage¶

usage: agentgrep [-h] [--color {auto,always,never}] {search,find} ...

Options¶

--color¶

when to use colors: auto (default), always, or never

Default: auto
Choices: auto, always, never

CLI¶

Use from another agent¶

Examples¶

Command: agentgrep¶

Usage¶

Options¶

Command: `agentgrep`¶