Examples¶

CLI search¶

Search only Codex prompt records and stop after ten matches:

$ uv run agentgrep grep "database migration" --agent codex --limit 10

Prefer records from the current project while keeping global matches visible:

$ uv run agentgrep search --here "database migration"

CLI discovery¶

List Cursor CLI sources as structured JSON when you want to script the result:

$ uv run agentgrep find cursor-cli --agent cursor-cli --json

MCP search call¶

Call search readonly when a client needs normalized result records rather than terminal text. Add cwd, repo, or branch when the client wants the same project-aware filtering described in Project context:

{
  "tool": "search",
  "arguments": {
    "terms": ["database migration"],
    "agent": "codex",
    "scope": "prompts",
    "cwd": "~/work/django-project",
    "limit": 10
  }
}

This request uses prompt effort because its prompt-only scope omits effort. For bounded conversation search, set effort to targeted and omit scope so MCP infers all. An explicit scope="prompts" with targeted effort is rejected. Targeted results remain approximate; use exhaustive when you need every eligible readable conversation backend.

Python search query¶

Use RecordOrigin on SearchQuery when code builds the same filter directly before calling run_search_query(). Prefer run_search_result() when you also need terminal status, coverage, diagnostics, or next actions:

import agentgrep

query = agentgrep.SearchQuery(
    terms=("database migration",),
    scope="prompts",
    any_term=False,
    regex=False,
    case_sensitive=False,
    agents=("codex",),
    limit=10,
    origin_filter=agentgrep.RecordOrigin(cwd="~/work/django-project"),
)

assert query.origin_filter == agentgrep.RecordOrigin(cwd="~/work/django-project")

MCP discovery call¶

Call find readonly when a client needs source metadata before choosing a search:

{
  "tool": "find",
  "arguments": {
    "pattern": "sessions",
    "agent": "codex",
    "limit": 50
  }
}

MCP resource reads¶

Read resources when the client needs passive metadata without running a tool:

agentgrep://capabilities
agentgrep://sources
agentgrep://sources/codex