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 — ranked search, grep, 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. Bare agentgrep (no subcommand) prints a colorized directory of choices listing every subcommand with example invocations — the same tmuxp / vcspull pattern. See TUI for the interactive Textual explorer.

Note

Versions before 0.1.0a5 silently rewrote agentgrep <terms> as agentgrep grep <terms> and bare agentgrep as agentgrep ui. Both shortcuts are gone — every subcommand must be named explicitly. agentgrep bliss is now an invalid choice error rather than a grep; reach for agentgrep grep bliss.

With uvx run installed: 

$ uvx agentgrep --help

Then run it from the terminal:

$ uvx agentgrep search "deploy"

$ uvx agentgrep search "deploy" --scope all

$ uvx agentgrep search "deploy" --ui
agentgrep grep

Content search with rg/ag-shaped flags, output, and exit codes.

agentgrep grep
agentgrep search

Ranked, deduped search grouped by session — best matches first.

agentgrep search
agentgrep find

Enumerate on-disk stores with fd-shaped flag grammar.

agentgrep find
agentgrep ui

Interactive Textual explorer for browsing prompts and conversations.

TUI
API Reference

CLI argument types, serialization helpers, and command entry points.

API Reference

–ui overlay

Every search-shaped subcommand accepts --ui: pass it to open the Textual explorer pre-filled with the same query you’d otherwise run as a one-shot. This is the tig-shaped overlay model — agentgrep grep -i foo --ui is to agentgrep grep -i foo what tig log is to git log.

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 command-specific JSON document carrying records or events. Search output includes the engine-owned terminal summary. Best when the caller wants to parse the whole result at once.

  • --ndjson emits one JSON object per line. For grep’s scan-ordered stream, direct terminal output flushes accepted matches; use PYTHONUNBUFFERED=1 when a downstream process must observe each piped event immediately.

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

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

Examples

Ranked search — deduped and grouped by session:

$ agentgrep search "deploy"

Prefer matches from the current project:

$ agentgrep search --here "deploy"

Search a bounded set of conversations selected from prompt matches:

$ agentgrep search "deploy" --deep

Search prompt records across every readable conversation backend:

$ agentgrep search "deploy" --exhaustive

Return prompt and conversation records in one exhaustive sweep:

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

Search prompts with rg-shaped flags:

$ agentgrep grep bliss

Combine multiple patterns with an agent filter:

$ agentgrep grep serene bliss --agent codex

Snippet-first output with highlighted matches:

$ agentgrep grep --style pretty deploy

Stream full-conversation matches as NDJSON:

$ agentgrep grep prompt history --scope conversations --ndjson

List stores for one agent as JSON:

$ agentgrep find cursor-cli --json

Open the directory of choices:

$ agentgrep

Command: agentgrep

Usage

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

Options

--color

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

Default
auto
Choices
auto, always, never
--version

show the released version (plus the git ref in a checkout) and exit