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.
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
Metadata
1 maintainer
Release files for agentgrep 0.1.0a53
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| agentgrep-0.1.0a53.tar.gz | 1.1 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agentgrep-0.1.0a53-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.6 MB
Release files / agentgrep-0.1.0a53.tar.gz
| Download URL | agentgrep-0.1.0a53.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
db8684258ffa31bf9050cba50f9c1d6962bee2d7283f1fd9fa6eb249bddac445
|
|
BLAKE2b-256 checksum How to use checksums |
6a6f8c2617ec489e7019aa4699e755508ab2535c8e6456610964fe66f4fd98ae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Oct 24, 2026.
Transparency logRelease files / agentgrep-0.1.0a53-py3-none-any.whl
| Download URL | agentgrep-0.1.0a53-py3-none-any.whl |
|---|---|
| Size | 542.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
105f2a5aa80a6277b7ec205a989a09764b96775363dfc51b60cb2f216d3a266d
|
|
BLAKE2b-256 checksum How to use checksums |
33651182a08aee89dadabdfefc516720444d3f9fbfddaf2a62aa30ea20d52c55
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Oct 24, 2026.
Transparency logSecurity for agentgrep 0.1.0a53
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.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for agentgrep-0.1.0a53.tar.gz
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 Oct 24, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
