Tools¶

agentgrep’s tools are read-only. They return structured Pydantic models and protect private paths before serialization.

Prompt and History Search¶

`search`¶

search

Search normalized prompts or history across local agent stores.

Returns:: SearchToolResponse

Use when you need full prompt or history records matching one or more terms.

Returns: query metadata plus normalized records with agent, store, adapter, path, text, title, role, timestamp, model, session ID, conversation ID, and metadata.

Example:

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

Parameters

Parameter	Type	Required	Default	Description
`terms`	t.Annotated[list[str], Field(min_length=1, description='One or more literal or regex search terms.')]	yes	—	—
`agent`	t.Annotated[AgentSelector, Field(description='Limit search to one agent or search all agents.')]	no	`'all'`	—
`search_type`	t.Annotated[SearchTypeName, Field(description='Search prompts, history, or both.')]	no	`'prompts'`	—
`any_term`	t.Annotated[bool, Field(description='Match any term instead of requiring all terms.')]	no	`False`	—
`regex`	t.Annotated[bool, Field(description='Treat search terms as regular expressions.')]	no	`False`	—
`case_sensitive`	t.Annotated[bool, Field(description='Perform case-sensitive matching.')]	no	`False`	—
`limit`	t.Annotated[int \| `None`, Field(default=20, ge=1, description='Maximum number of search results to return.')]	no	`20`	—

Time-Windowed Activity¶

`recent_sessions`¶

recent_sessions

Return sources modified in the last N hours, newest-first.

Returns:: RecentSessionsResponse

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

Parameter	Type	Required	Default	Description
`agent`	t.Annotated[AgentSelector, Field(description='Limit discovery to one agent or scan every agent.')]	no	`'all'`	—
`hours`	t.Annotated[int, Field(default=24, ge=1, le=24 * 30, description=’Look back this many hours (max 30 days).’, examples=[1, 24, 168])]	no	`24`	—
`limit`	t.Annotated[int \| `None`, Field(default=10, ge=1, description='Maximum number of sources to return.')]	no	`10`	—

Store Discovery¶

`find`¶

find

Find known agent stores, session files, and SQLite databases.

Returns:: FindToolResponse

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

Returns: query metadata plus source records with agent, store, adapter, protected path, path kind, and metadata.

Example:

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

Parameters

Parameter	Type	Required	Default	Description
`pattern`	t.Annotated[str \| `None`, Field(default=`None`, description='Optional substring filter against discovered paths and adapters.')]	no	—	—
`agent`	t.Annotated[AgentSelector, Field(description='Limit discovery to one agent or search all agents.')]	no	`'all'`	—
`limit`	t.Annotated[int \| `None`, Field(default=50, ge=1, description='Maximum number of discovered sources to return.')]	no	`50`	—

Structured Source Listing¶

`list_sources`¶

list_sources

List discovered sources with structured path-kind/source-kind filters.

Returns:: ListSourcesResponse

Use when you want a structured listing of discovered sources with optional path-kind / source-kind filters.

Parameters

Parameter	Type	Required	Default	Description
`agent`	t.Annotated[AgentSelector, Field(description='Limit discovery to one agent or scan every agent.')]	no	`'all'`	—
`path_kind_filter`	t.Annotated['history_file', 'session_file', 'sqlite_db' \| `None`, Field(default=`None`, description='Filter by path kind.')]	no	—	—
`source_kind_filter`	t.Annotated['json', 'jsonl', 'sqlite' \| `None`, Field(default=`None`, description='Filter by on-disk source kind.')]	no	—	—
`limit`	t.Annotated[int \| `None`, Field(default=`None`, ge=1, description='Maximum number of sources to return.')]	no	—	—

Required-Pattern Filtering¶

`filter_sources`¶

filter_sources

Filter discovered sources by required substring pattern.

Returns:: FindToolResponse

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

Parameters

Parameter	Type	Required	Default	Description
`pattern`	t.Annotated[str, Field(min_length=1, description='Required substring pattern.', examples=['state', '.jsonl'])]	yes	—	—
`agent`	t.Annotated[AgentSelector, Field(description='Limit discovery to one agent or scan every agent.')]	no	`'all'`	—
`limit`	t.Annotated[int \| `None`, Field(default=50, ge=1, description='Maximum number of sources to return.')]	no	`50`	—

Discovery Counts¶

`summarize_discovery`¶

summarize_discovery

Aggregate counts of discovered sources by agent, format, and kind.

Returns:: DiscoverySummaryResponse

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

Parameters

Parameter	Type	Required	Default	Description
`agent`	t.Annotated[AgentSelector, Field(description='Limit discovery to one agent or scan every agent.')]	no	`'all'`	—

Catalog readonly¶

`list_stores`¶

list_stores

List on-disk agent stores from the agentgrep catalog.

Returns:: ListStoresResponse

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

Parameters

Parameter	Type	Required	Default	Description
`agent`	t.Annotated[str, Field(default='all', description="Filter to one agent or 'all' for every catalog entry.", examples=['all', 'claude', 'cursor'])]	no	`'all'`	—
`role_filter`	t.Annotated[str \| `None`, Field(default=`None`, description="Filter to one StoreRole value (e.g. 'primary_chat').", examples=['primary_chat', 'prompt_history'])]	no	—	—
`search_default_only`	t.Annotated[bool, Field(default=False, description='Return only stores that are searched by default.')]	no	`False`	—

`get_store_descriptor`¶

get_store_descriptor

Return the catalog descriptor for a single store by id.

Returns:: StoreDescriptorModel

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

Parameters

Parameter	Type	Required	Default	Description
`store_id`	t.Annotated[str, Field(min_length=1, description="Store id (e.g. 'claude.projects.session').", examples=['claude.projects.session', 'codex.history'])]	yes	—	—

`inspect_record_sample`¶

inspect_record_sample

Read the first N records from one adapter+path for schema inspection.

Returns:: InspectSampleResponse

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

Parameters

Parameter	Type	Required	Default	Description
`adapter_id`	t.Annotated[str, Field(min_length=1, description="Adapter id (e.g. 'claude.projects_jsonl.v1').", examples=['claude.projects_jsonl.v1', 'codex.history_json.v1'])]	yes	—	—
`source_path`	t.Annotated[str, Field(min_length=1, description='Absolute path to the source file.')]	yes	—	—
`sample_size`	t.Annotated[int, Field(default=1, ge=1, le=20, description='Number of records to return (1-20).')]	no	`1`	—

Diagnostics¶

`validate_query`¶

validate_query

Dry-run a query against sample text without searching files.

Returns:: ValidateQueryResponse

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

Parameters

Parameter	Type	Required	Default	Description
`terms`	t.Annotated[list[str], Field(min_length=1, description='One or more literal or regex search terms.', examples=[['alpha'], ['foo.*bar']])]	yes	—	—
`sample_text`	t.Annotated[str, Field(description='Sample text to test the query against.')]	yes	—	—
`regex`	t.Annotated[bool, Field(description='Treat terms as regular expressions.')]	no	`False`	—
`case_sensitive`	t.Annotated[bool, Field(description='Perform case-sensitive matching.')]	no	`False`	—
`any_term`	t.Annotated[bool, Field(description='Match any term instead of requiring all terms.')]	no	`False`	—

Tools¶

Prompt and History Search¶

search¶

Time-Windowed Activity¶

recent_sessions¶

Store Discovery¶

find¶

Structured Source Listing¶

list_sources¶

Required-Pattern Filtering¶

filter_sources¶

Discovery Counts¶

summarize_discovery¶

Catalog readonly¶

list_stores¶

get_store_descriptor¶

inspect_record_sample¶

Diagnostics¶

validate_query¶

`search`¶

`recent_sessions`¶

`find`¶

`list_sources`¶

`filter_sources`¶

`summarize_discovery`¶

`list_stores`¶

`get_store_descriptor`¶

`inspect_record_sample`¶

`validate_query`¶