agentgrep¶

Read-only search for local AI agent prompts and history across Codex, Claude Code, Cursor, Gemini, and Grok.

Warning

Pre-alpha. APIs may change. Feedback welcome.

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

With uvx installed:

$ claude mcp add agentgrep -- uvx --from agentgrep agentgrep-mcp

With uvx installed:

$ claude mcp add agentgrep -- uvx --exclude-newer P7D --exclude-newer-package agentgrep=2099-01-01 --from agentgrep agentgrep-mcp

With uvx installed:

$ claude mcp add agentgrep -- uvx --no-config --from agentgrep agentgrep-mcp

With uvx installed:

$ claude mcp add agentgrep --scope user -- uvx --from agentgrep agentgrep-mcp

With uvx installed:

$ claude mcp add agentgrep --scope user -- uvx --exclude-newer P7D --exclude-newer-package agentgrep=2099-01-01 --from agentgrep agentgrep-mcp

With uvx installed:

$ claude mcp add agentgrep --scope user -- uvx --no-config --from agentgrep agentgrep-mcp

With uvx installed:

$ claude mcp add agentgrep --scope project -- uvx --from agentgrep agentgrep-mcp

With uvx installed:

$ claude mcp add agentgrep --scope project -- uvx --exclude-newer P7D --exclude-newer-package agentgrep=2099-01-01 --from agentgrep agentgrep-mcp

With uvx installed:

$ claude mcp add agentgrep --scope project -- uvx --no-config --from agentgrep agentgrep-mcp

With pipx installed:

$ claude mcp add agentgrep -- pipx run --spec agentgrep agentgrep-mcp

With pipx installed:

$ claude mcp add agentgrep -- pipx run --spec agentgrep agentgrep-mcp

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

With pipx installed:

$ claude mcp add agentgrep -- pipx run --spec agentgrep agentgrep-mcp

With pipx installed:

$ claude mcp add agentgrep --scope user -- pipx run --spec agentgrep agentgrep-mcp

With pipx installed:

$ claude mcp add agentgrep --scope user -- pipx run --spec agentgrep agentgrep-mcp

With pipx installed:

$ claude mcp add agentgrep --scope user -- pipx run --spec agentgrep agentgrep-mcp

With pipx installed:

$ claude mcp add agentgrep --scope project -- pipx run --spec agentgrep agentgrep-mcp

With pipx installed:

$ claude mcp add agentgrep --scope project -- pipx run --spec agentgrep agentgrep-mcp

With pipx installed:

$ claude mcp add agentgrep --scope project -- pipx run --spec agentgrep agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ claude mcp add agentgrep -- agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ claude mcp add agentgrep -- agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ claude mcp add agentgrep -- agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ claude mcp add agentgrep --scope user -- agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ claude mcp add agentgrep --scope user -- agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ claude mcp add agentgrep --scope user -- agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ claude mcp add agentgrep --scope project -- agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ claude mcp add agentgrep --scope project -- agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ claude mcp add agentgrep --scope project -- agentgrep-mcp

With uvx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "uvx",
            "args": ["--from", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With uvx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "agentgrep=2099-01-01", "--from", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With uvx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "uvx",
            "args": ["--from", "agentgrep", "agentgrep-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: claude_desktop_config.json

With pipx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "pipx",
            "args": ["run", "--spec", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With pipx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "pipx",
            "args": ["run", "--spec", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

With pipx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "pipx",
            "args": ["run", "--spec", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: claude_desktop_config.json

Install the packages first:

$ pip install --user --upgrade agentgrep

Then use this config:

{
    "mcpServers": {
        "agentgrep": {
            "command": "agentgrep-mcp"
        }
    }
}

Config file: claude_desktop_config.json

Install the packages first:

$ pip install --user --upgrade agentgrep

Then use this config:

{
    "mcpServers": {
        "agentgrep": {
            "command": "agentgrep-mcp"
        }
    }
}

Config file: claude_desktop_config.json

Install the packages first:

$ pip install --user --upgrade agentgrep

Then use this config:

{
    "mcpServers": {
        "agentgrep": {
            "command": "agentgrep-mcp"
        }
    }
}

Config file: claude_desktop_config.json

With uvx installed:

$ codex mcp add agentgrep -- uvx --from agentgrep agentgrep-mcp

With uvx installed:

$ codex mcp add agentgrep -- uvx --exclude-newer P7D --exclude-newer-package agentgrep=2099-01-01 --from agentgrep agentgrep-mcp

With uvx installed:

$ codex mcp add agentgrep -- uvx --no-config --from agentgrep agentgrep-mcp

With uvx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.agentgrep]
command = "uvx"
args = ["--from", "agentgrep", "agentgrep-mcp"]

With uvx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.agentgrep]
command = "uvx"
args = ["--exclude-newer", "P7D", "--exclude-newer-package", "agentgrep=2099-01-01", "--from", "agentgrep", "agentgrep-mcp"]

With uvx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.agentgrep]
command = "uvx"
args = ["--from", "agentgrep", "agentgrep-mcp"]
env = { UV_NO_CONFIG = "1" }

With pipx installed:

$ codex mcp add agentgrep -- pipx run --spec agentgrep agentgrep-mcp

With pipx installed:

$ codex mcp add agentgrep -- pipx run --spec agentgrep agentgrep-mcp

With pipx installed:

$ codex mcp add agentgrep -- pipx run --spec agentgrep agentgrep-mcp

With pipx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.agentgrep]
command = "pipx"
args = ["run", "--spec", "agentgrep", "agentgrep-mcp"]

With pipx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.agentgrep]
command = "pipx"
args = ["run", "--spec", "agentgrep", "agentgrep-mcp"]

With pipx installed:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.agentgrep]
command = "pipx"
args = ["run", "--spec", "agentgrep", "agentgrep-mcp"]

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ codex mcp add agentgrep -- agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ codex mcp add agentgrep -- agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ codex mcp add agentgrep -- agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.agentgrep]
command = "agentgrep-mcp"

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.agentgrep]
command = "agentgrep-mcp"

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

Codex's CLI doesn't support project scope yet — paste this into .codex/config.toml at the repo root.

[mcp_servers.agentgrep]
command = "agentgrep-mcp"

With uvx installed:

$ gemini mcp add --scope user agentgrep uvx -- --from agentgrep agentgrep-mcp

With uvx installed:

$ gemini mcp add --scope user agentgrep uvx -- --exclude-newer P7D --exclude-newer-package agentgrep=2099-01-01 --from agentgrep agentgrep-mcp

With uvx installed:

$ gemini mcp add --scope user agentgrep uvx -- --no-config --from agentgrep agentgrep-mcp

With uvx installed:

$ gemini mcp add --scope project agentgrep uvx -- --from agentgrep agentgrep-mcp

With uvx installed:

$ gemini mcp add --scope project agentgrep uvx -- --exclude-newer P7D --exclude-newer-package agentgrep=2099-01-01 --from agentgrep agentgrep-mcp

With uvx installed:

$ gemini mcp add --scope project agentgrep uvx -- --no-config --from agentgrep agentgrep-mcp

With pipx installed:

$ gemini mcp add --scope user agentgrep pipx -- run --spec agentgrep agentgrep-mcp

With pipx installed:

$ gemini mcp add --scope user agentgrep pipx -- run --spec agentgrep agentgrep-mcp

With pipx installed:

$ gemini mcp add --scope user agentgrep pipx -- run --spec agentgrep agentgrep-mcp

With pipx installed:

$ gemini mcp add --scope project agentgrep pipx -- run --spec agentgrep agentgrep-mcp

With pipx installed:

$ gemini mcp add --scope project agentgrep pipx -- run --spec agentgrep agentgrep-mcp

With pipx installed:

$ gemini mcp add --scope project agentgrep pipx -- run --spec agentgrep agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ gemini mcp add --scope user agentgrep agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ gemini mcp add --scope user agentgrep agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ gemini mcp add --scope user agentgrep agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ gemini mcp add --scope project agentgrep agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ gemini mcp add --scope project agentgrep agentgrep-mcp

Install the packages first:

$ pip install --user --upgrade agentgrep

Then register:

$ gemini mcp add --scope project agentgrep agentgrep-mcp

With uvx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "uvx",
            "args": ["--from", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With uvx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "agentgrep=2099-01-01", "--from", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With uvx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "uvx",
            "args": ["--from", "agentgrep", "agentgrep-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With uvx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "uvx",
            "args": ["--from", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With uvx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "uvx",
            "args": ["--exclude-newer", "P7D", "--exclude-newer-package", "agentgrep=2099-01-01", "--from", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With uvx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "uvx",
            "args": ["--from", "agentgrep", "agentgrep-mcp"],
            "env": { "UV_NO_CONFIG": "1" }
        }
    }
}

Config file: ~/.cursor/mcp.json

With pipx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "pipx",
            "args": ["run", "--spec", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With pipx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "pipx",
            "args": ["run", "--spec", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With pipx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "pipx",
            "args": ["run", "--spec", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: .cursor/mcp.json (in repo)

With pipx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "pipx",
            "args": ["run", "--spec", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With pipx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "pipx",
            "args": ["run", "--spec", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

With pipx installed:

{
    "mcpServers": {
        "agentgrep": {
            "command": "pipx",
            "args": ["run", "--spec", "agentgrep", "agentgrep-mcp"]
        }
    }
}

Config file: ~/.cursor/mcp.json

Install the packages first:

$ pip install --user --upgrade agentgrep

Then use this config:

{
    "mcpServers": {
        "agentgrep": {
            "command": "agentgrep-mcp"
        }
    }
}

Config file: .cursor/mcp.json (in repo)

Install the packages first:

$ pip install --user --upgrade agentgrep

Then use this config:

{
    "mcpServers": {
        "agentgrep": {
            "command": "agentgrep-mcp"
        }
    }
}

Config file: .cursor/mcp.json (in repo)

Install the packages first:

$ pip install --user --upgrade agentgrep

Then use this config:

{
    "mcpServers": {
        "agentgrep": {
            "command": "agentgrep-mcp"
        }
    }
}

Config file: .cursor/mcp.json (in repo)

Install the packages first:

$ pip install --user --upgrade agentgrep

Then use this config:

{
    "mcpServers": {
        "agentgrep": {
            "command": "agentgrep-mcp"
        }
    }
}

Config file: ~/.cursor/mcp.json

Install the packages first:

$ pip install --user --upgrade agentgrep

Then use this config:

{
    "mcpServers": {
        "agentgrep": {
            "command": "agentgrep-mcp"
        }
    }
}

Config file: ~/.cursor/mcp.json

Install the packages first:

$ pip install --user --upgrade agentgrep

Then use this config:

{
    "mcpServers": {
        "agentgrep": {
            "command": "agentgrep-mcp"
        }
    }
}

Config file: ~/.cursor/mcp.json

Quickstart

Run a first search and inspect the result shape.

Getting Started

CLI

Search and find from the terminal. Pipe --json / --ndjson for scripts and agents.

CLI

TUI

Interactive Textual explorer for browsing prompts and history.

TUI

MCP

Tools, resources, and prompts for MCP clients.

MCP

Library

Tutorial, how-to, reference, and examples for the Python library.

Library

Client Setup

Config snippets for local MCP clients.

MCP Clients

Configuration

Search behavior, privacy, output, and progress controls.

Configuration

Backends

Per-agent store layouts, record schemas, and support matrix.

Backends

What you can do¶

Prompt Search¶

Find full prompt and history records by literal term or regular expression.

search

Discovery readonly¶

List the stores, session files, and SQLite databases that agentgrep can read.

find

MCP guidance¶

Use prompts for common agent workflows:

search_prompts · search_history · inspect_stores

agentgrep¶

Dependency cooldowns

Dependency cooldowns

What you can do¶

Prompt Search¶

Discovery readonly¶

MCP guidance¶