agentgrep¶

Read-only search for local AI agent prompts and opt-in conversations across Codex, Claude Code, Cursor, Gemini, Grok, Pi, and OpenCode.

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 prompt and conversation records.

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 prompt records by literal term or regular expression, with explicit opt-in for conversations.

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_conversations · inspect_stores

agentgrep¶

Dependency cooldowns

Dependency cooldowns

What you can do¶

Prompt Search¶

Discovery readonly¶

MCP guidance¶