This release is a pre-release and may not be stable for production use.
agentgrep
Read-only search for local AI agent prompts and opt-in conversations across Codex, Claude Code, Cursor, Gemini, Antigravity, Grok, Pi, OpenCode, and VS Code.
agentgrep provides a CLI and an MCP server over the same discovery +
parsing layer:
- A terminal CLI (
agentgrep) with a Textual TUI for interactive browsing of normalized records. - An MCP server (
agentgrep-mcp) that exposes search, discovery, catalog, and validation tools to any client that speaks Model Context Protocol.
Requires Python 3.14+. Runs on Linux and macOS; native Windows is not supported, but Windows Subsystem for Linux (WSL) is.
[!WARNING] Alpha. Releases carry an
-alphaprerelease tag. The API is not settled, and any release may change or remove exported identifiers without a deprecation period. Pin an exact version. Not recommended for production.
Install
$ uvx agentgrep --help
Other install methods (pipx, uv add, pip install) and full setup snippets live in the installer widget on agentgrep.org/cli/.
CLI quickstart
Search fast prompt-history stores — ranked by relevance, deduped, with newest as the stable tie-break:
$ agentgrep search "deploy"
Use prompt matches to search selected conversations. Targeted search attempts at most 25 conversations by default and reports approximate coverage:
$ agentgrep search "deploy" --deep
Search prompt records across every readable conversation backend:
$ agentgrep search "deploy" --exhaustive
Search prompts and conversations together in one explicit deep sweep:
$ agentgrep search "deploy" --exhaustive --scope all
Prefer ripgrep-shaped flags? grep mirrors rg / ag against the
same records:
$ agentgrep grep "deploy" --scope conversations
Stream JSON so a non-MCP agent or shell pipeline can consume the results:
$ agentgrep find --json
Open the read-only Textual explorer, seeded with a query:
$ agentgrep ui "deploy"
--json and --ndjson make every command pipe-friendly, and any
search-shaped subcommand takes --ui to hand the same query to the
explorer (e.g. agentgrep grep "deploy" --ui). Agents that don't
speak MCP can drive the CLI directly; see
https://agentgrep.org/cli/ for the per-subcommand reference.
Results and JSON/NDJSON payloads write to stdout; progress and diagnostics
write to stderr, so a piped command never sees the spinner. search exits
0 for at least one result and 1 for none; grep follows rg's
convention and adds 2 for a search error such as invalid regex. See
https://agentgrep.org/cli/ for the exit codes of each command.
MCP server: quickest setup
In Claude Code:
$ claude mcp add agentgrep -- uvx --from agentgrep agentgrep-mcp
For Claude Desktop / Codex / Cursor / Gemini snippets, see https://agentgrep.org/mcp/.
Library quickstart
from pathlib import Path
import agentgrep
backends = agentgrep.select_backends()
query = agentgrep.SearchQuery(
terms=("hello",),
scope="prompts",
any_term=False,
regex=False,
case_sensitive=False,
agents=agentgrep.AGENT_CHOICES,
limit=10,
effort="prompt",
)
result = agentgrep.run_search_result(Path.home(), query, backends=backends)
for record in result.records:
print(record.agent, record.title or record.path)
print(result.summary.status.state, result.summary.coverage)
Links
- Documentation: https://agentgrep.org/
- Source: https://github.com/tony/agentgrep
- Issues: https://github.com/tony/agentgrep/issues
- Changelog: CHANGES
- License: MIT
1 maintainer
Release files for agentgrep 0.1.0a52
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| agentgrep-0.1.0a52.tar.gz | 1.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agentgrep-0.1.0a52-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.6 MB
Release files / agentgrep-0.1.0a52.tar.gz
| Download URL | agentgrep-0.1.0a52.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5a9bc844ea6869aab51c0a82f32cb563deda95aa0f1e90a2bb14c5c73bc9092b
|
|
BLAKE2b-256 checksum How to use checksums |
56a1ab505852224a27b1e3100143fdc0e922e6b1e8106d22fbde29070278abde
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 12, 2026.
Transparency logRelease files / agentgrep-0.1.0a52-py3-none-any.whl
| Download URL | agentgrep-0.1.0a52-py3-none-any.whl |
|---|---|
| Size | 542.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d901acda9b22f68a6dd875d0320a93e4e8b7ae7e5d94898d84cc929a31045590
|
|
BLAKE2b-256 checksum How to use checksums |
d5ab5fe05def3e0127f0a614531fa34fb75fd22c829e2feec90e95737cf49c68
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 12, 2026.
Transparency log
