Tools¶

Use when you need prompt records matching one or more terms. Pass scope="conversations" for full conversation, assistant, tool, and event records, or scope="all" for both surfaces.

Returns: request metadata, run status, result stats, page metadata, and normalized records with ref, agent, store, adapter, path, text, title, role, timestamp, model, session ID, conversation ID, and metadata. When page.next_cursor is present, pass it back as cursor to continue the same search without rebuilding the request.

Example:

{
  "tool": "search",
  "arguments": {
    "terms": ["release notes"],
    "agent": "all",
    "scope": "prompts",
    "limit": 20
  }
}

Parameters

Use when you want the most-recently modified sources for an agent — newest-first, optionally bounded by a time window.

Returns: the cutoff timestamp plus source records ordered by mtime_ns descending.

Parameters

Use when you need to inspect which stores, session files, and databases agentgrep can read.

Returns: request metadata, run status, result stats, page metadata, and source records with ref, agent, store, adapter, protected path, path kind, and metadata. When page.next_cursor is present, pass it back as cursor to continue the same discovery scan.

Example:

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

Parameters

Use when you want a structured listing of discovered sources with optional path-kind, source-kind, and coverage filters. By default this matches the default-search surface; pass include_non_default=true or set coverage_filter to inspect inventory-only stores such as Codex SQLite DBs or Claude session memory. Each returned source includes searchable, search_by_default, searchable_reason, inspectable, and version_detection, which records the strategy and evidence agentgrep used to identify the app/data version for that concrete file or DB.

Parameters

Use when you want to narrow discovered sources by required substring pattern (a stricter find).

Parameters

Use when you want aggregate counts of discovered sources by agent, format, and path-kind.

Parameters

Use when you want the canonical catalog of on-disk stores agentgrep knows about — including stores that are not searched by default.

Parameters

Use when you need the full descriptor (role, format, upstream reference, schema notes) for a single store id.

Parameters

Use when you want a few raw records from one adapter+path to validate parser output or discover schema variations.

Parameters

Use when you have a ref returned by search or find and need to inspect the matching result or sample records from that source without reconstructing local paths.

Parameters

Use when you want to dry-run a literal pattern against sample text before issuing a broad cross-agent search.

Parameters