API Reference

Core data types, discovery functions, and the search pipeline used by every surface (CLI, TUI, MCP).

Core data

class agentgrep.PrivatePath
class
class
class agentgrep.PrivatePath

Bases: PosixPath

Path subclass that hides the user’s home directory in textual output.

static __new__(cls, *args, **kwargs)
staticmethod method
staticmethod method
static __new__(cls, *args, **kwargs)

Create a privacy-aware path.

Parameters:
Return type:

PrivatePath

classmethod _collapse_home(value)
classmethod method
classmethod method
classmethod _collapse_home(value)

Collapse the user’s home directory to ~ when value is inside it.

Parameters:

value (str)

Return type:

str

agentgrep.format_display_path(path, *, directory=False)
function
function
agentgrep.format_display_path(path, *, directory=False)

Return a privacy-safe display path.

Parameters:
Return type:

str

class agentgrep.BackendSelection
class
class
class agentgrep.BackendSelection

Bases: object

Selected optional subprocess backends.

find_tool: str | None
attribute
attribute
find_tool: str | None
grep_tool: str | None
attribute
attribute
grep_tool: str | None
json_tool: str | None
attribute
attribute
json_tool: str | None
__init__(find_tool, grep_tool, json_tool)
method
method
__init__(find_tool, grep_tool, json_tool)
Parameters:
Return type:

None

class agentgrep.SearchQuery
class
class
class agentgrep.SearchQuery

Bases: object

Compiled search configuration.

compiled carries the parsed-query predicates from agentgrep.query. When None (the default), the engine takes its legacy code path — pure-text queries and flag-only invocations stay on the fast path with no extra evaluation cost. When set, iter_search_events consults compiled.source_predicate to prune sources before any file is opened, and matches_record() consults compiled.record_predicate after the existing text match. match_surface lets line-oriented callers such as grep require a match in record text while fuzzy search and filtering can keep using the metadata-rich haystack.

terms: tuple[str, ...]
attribute
attribute
terms: tuple[str, ...]
scope: SearchScope
attribute
attribute
scope: SearchScope
any_term: bool
attribute
attribute
any_term: bool
regex: bool
attribute
attribute
regex: bool
case_sensitive: bool
attribute
attribute
case_sensitive: bool
agents: tuple[AgentName, ...]
attribute
attribute
agents: tuple[AgentName, ...]
limit: int | None
attribute
attribute
limit: int | None
dedupe: bool
attribute
attribute
dedupe: bool
compiled: CompiledQuery | None
attribute
attribute
compiled: CompiledQuery | None
match_surface: SearchMatchSurface
attribute
attribute
match_surface: SearchMatchSurface
__init__(terms, scope, any_term, regex, case_sensitive, agents, limit, dedupe=True, compiled=None, match_surface='haystack')
method
method
__init__(terms, scope, any_term, regex, case_sensitive, agents, limit, dedupe=True, compiled=None, match_surface='haystack')
Parameters:

  • terms (tuple[str, ...])

  • scope (SearchScope)

  • any_term (bool)

  • regex (bool)

  • case_sensitive (bool)

  • agents (tuple[AgentName, ...])

  • limit (int | None)

  • dedupe (bool)

  • compiled (CompiledQuery | None)

  • match_surface (SearchMatchSurface)

Return type:

None

class agentgrep.SourceHandle
class
class
class agentgrep.SourceHandle

Bases: object

A discovered, parseable source file or SQLite database.

agent: Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
attribute
attribute
agent: Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
store: str
attribute
attribute
store: str
adapter_id: str
attribute
attribute
adapter_id: str
path: Path
attribute
attribute
path: Path
path_kind: Literal['history_file', 'session_file', 'sqlite_db', 'store_file']
attribute
attribute
path_kind: Literal['history_file', 'session_file', 'sqlite_db', 'store_file']
source_kind: Literal['json', 'jsonl', 'sqlite', 'text', 'opaque']
attribute
attribute
source_kind: Literal['json', 'jsonl', 'sqlite', 'text', 'opaque']
search_root: Path | None
attribute
attribute
search_root: Path | None
mtime_ns: int
attribute
attribute
mtime_ns: int
coverage: StoreCoverage
attribute
attribute
coverage: StoreCoverage
version_detection: SourceVersionDetection | None
attribute
attribute
version_detection: SourceVersionDetection | None
__init__(agent, store, adapter_id, path, path_kind, source_kind, search_root, mtime_ns, coverage=StoreCoverage.DEFAULT_SEARCH, version_detection=None)
method
method
__init__(agent, store, adapter_id, path, path_kind, source_kind, search_root, mtime_ns, coverage=StoreCoverage.DEFAULT_SEARCH, version_detection=None)
Parameters:

  • agent (AgentName)

  • store (str)

  • adapter_id (str)

  • path (Path)

  • path_kind (PathKind)

  • source_kind (SourceKind)

  • search_root (Path | None)

  • mtime_ns (int)

  • coverage (StoreCoverage)

  • version_detection (SourceVersionDetection | None)

Return type:

None

class agentgrep.SearchRecord
class
class
class agentgrep.SearchRecord

Bases: object

Normalized prompt/history record.

kind: Literal['prompt', 'history']
attribute
attribute
kind: Literal['prompt', 'history']
agent: Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
attribute
attribute
agent: Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
store: str
attribute
attribute
store: str
adapter_id: str
attribute
attribute
adapter_id: str
path: Path
attribute
attribute
path: Path
text: str
attribute
attribute
text: str
title: str | None
attribute
attribute
title: str | None
role: str | None
attribute
attribute
role: str | None
timestamp: str | None
attribute
attribute
timestamp: str | None
model: str | None
attribute
attribute
model: str | None
session_id: str | None
attribute
attribute
session_id: str | None
conversation_id: str | None
attribute
attribute
conversation_id: str | None
metadata: dict[str, object]
attribute
attribute
metadata: dict[str, object]
__init__(kind, agent, store, adapter_id, path, text, title=None, role=None, timestamp=None, model=None, session_id=None, conversation_id=None, metadata={})
method
method
__init__(kind, agent, store, adapter_id, path, text, title=None, role=None, timestamp=None, model=None, session_id=None, conversation_id=None, metadata={})
Parameters:
Return type:

None

class agentgrep.FindRecord
class
class
class agentgrep.FindRecord

Bases: object

Normalized discovery record for agentgrep find.

kind: Literal['find']
attribute
attribute
kind: Literal['find']
agent: Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
attribute
attribute
agent: Literal['codex', 'claude', 'cursor-cli', 'cursor-ide', 'gemini', 'antigravity-cli', 'antigravity-ide', 'grok', 'pi', 'opencode', 'windsurf', 'vscode']
store: str
attribute
attribute
store: str
adapter_id: str
attribute
attribute
adapter_id: str
path: Path
attribute
attribute
path: Path
path_kind: Literal['history_file', 'session_file', 'sqlite_db', 'store_file']
attribute
attribute
path_kind: Literal['history_file', 'session_file', 'sqlite_db', 'store_file']
metadata: dict[str, object]
attribute
attribute
metadata: dict[str, object]
__init__(kind, agent, store, adapter_id, path, path_kind, metadata={})
method
method
__init__(kind, agent, store, adapter_id, path, path_kind, metadata={})
Parameters:
Return type:

None

Search control and progress

class agentgrep.SearchControl
class
class
class agentgrep.SearchControl

Bases: object

Thread-safe cooperative controls for an active search.

__init__()
method
method
__init__()
Return type:

None

request_answer_now()
method
method
request_answer_now()

Request that search return the results collected so far.

Return type:

None

answer_now_requested()
method
method
answer_now_requested()

Return whether search should stop and answer with partial results.

Return type:

bool

class agentgrep.SearchProgress
class
class
class agentgrep.SearchProgress

Bases: Protocol

Progress reporter used by search internals.

start(query)
method
method
start(query)

Mark search start.

Parameters:

query (SearchQuery)

Return type:

None

sources_discovered(count)
method
method
sources_discovered(count)

Report discovered source count.

Parameters:

count (int)

Return type:

None

prefilter_started(root)
method
method
prefilter_started(root)

Report root prefilter start.

Parameters:

root (Path)

Return type:

None

sources_planned(planned, total)
method
method
sources_planned(planned, total)

Report selected source count.

Parameters:
Return type:

None

source_started(index, total, source)
method
method
source_started(index, total, source)

Report source scan start.

Parameters:
Return type:

None

source_finished(index, total, source, records, matches)
method
method
source_finished(index, total, source, records, matches)

Report source scan completion.

Parameters:
Return type:

None

result_added(count)
method
method
result_added(count)

Report deduped result count.

Parameters:

count (int)

Return type:

None

record_added(record)
method
method
record_added(record)

Report a newly deduped record (streaming consumers only).

Parameters:

record (SearchRecord)

Return type:

None

finish(result_count)
method
method
finish(result_count)

Report search completion.

Parameters:

result_count (int)

Return type:

None

answer_now(result_count)
method
method
answer_now(result_count)

Report early search completion with partial results.

Parameters:

result_count (int)

Return type:

None

interrupt()
method
method
interrupt()

Report interrupted search.

Return type:

None

close()
method
method
close()

Release any progress resources.

Return type:

None

__init__(*args, **kwargs)
method
method
__init__(*args, **kwargs)
_abc_impl = <_abc._abc_data object>
attribute
attribute
_abc_impl = <_abc._abc_data object>
_is_protocol = True
attribute
attribute
_is_protocol = True
class agentgrep.NoopSearchProgress
class
class
class agentgrep.NoopSearchProgress

Bases: object

Silent search progress reporter.

start(query)
method
method
start(query)

Ignore search start.

Parameters:

query (SearchQuery)

Return type:

None

sources_discovered(count)
method
method
sources_discovered(count)

Ignore discovered source count.

Parameters:

count (int)

Return type:

None

prefilter_started(root)
method
method
prefilter_started(root)

Ignore root prefilter start.

Parameters:

root (Path)

Return type:

None

sources_planned(planned, total)
method
method
sources_planned(planned, total)

Ignore selected source count.

Parameters:
Return type:

None

source_started(index, total, source)
method
method
source_started(index, total, source)

Ignore source scan start.

Parameters:
Return type:

None

source_finished(index, total, source, records, matches)
method
method
source_finished(index, total, source, records, matches)

Ignore source scan completion.

Parameters:
Return type:

None

result_added(count)
method
method
result_added(count)

Ignore deduped result count.

Parameters:

count (int)

Return type:

None

record_added(record)
method
method
record_added(record)

Ignore newly deduped record.

Parameters:

record (SearchRecord)

Return type:

None

finish(result_count)
method
method
finish(result_count)

Ignore search completion.

Parameters:

result_count (int)

Return type:

None

answer_now(result_count)
method
method
answer_now(result_count)

Ignore early search completion.

Parameters:

result_count (int)

Return type:

None

interrupt()
method
method
interrupt()

Ignore interrupted search.

Return type:

None

close()
method
method
close()

Nothing to release.

Return type:

None

class agentgrep.ConsoleSearchProgress
class
class
class agentgrep.ConsoleSearchProgress

Bases: object

Human progress reporter for potentially long searches.

_SPINNER_FRAMES: ClassVar[str] = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'
attribute
attribute
_SPINNER_FRAMES: ClassVar[str] = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'
__init__(*, enabled, stream=None, tty=None, color_mode='auto', refresh_interval=0.1, heartbeat_interval=10.0, answer_now_hint=False)
method
method
__init__(*, enabled, stream=None, tty=None, color_mode='auto', refresh_interval=0.1, heartbeat_interval=10.0, answer_now_hint=False)
Parameters:
Return type:

None

start(query)
method
method
start(query)

Begin progress reporting for query.

Parameters:

query (SearchQuery)

Return type:

None

sources_discovered(count)
method
method
sources_discovered(count)

Report discovered source count.

Parameters:

count (int)

Return type:

None

prefilter_started(root)
method
method
prefilter_started(root)

Report root prefilter start.

Parameters:

root (Path)

Return type:

None

sources_planned(planned, total)
method
method
sources_planned(planned, total)

Report selected source count.

Parameters:
Return type:

None

source_started(index, total, source)
method
method
source_started(index, total, source)

Report source scan start.

Parameters:
Return type:

None

source_finished(index, total, source, records, matches)
method
method
source_finished(index, total, source, records, matches)

Report source scan completion.

Parameters:
Return type:

None

source_progress(index, total, source, records, matches)
method
method
source_progress(index, total, source, records, matches)

Report in-source scan progress.

Parameters:
Return type:

None

result_added(count)
method
method
result_added(count)

Report deduped result count.

Parameters:

count (int)

Return type:

None

record_added(record)
method
method
record_added(record)

Ignore the per-record broadcast; counter is tracked via result_added.

Parameters:

record (SearchRecord)

Return type:

None

set_status(phase, *, current=None, total=None, detail=None)
method
method
set_status(phase, *, current=None, total=None, detail=None)

Update the current progress status.

Parameters:
Return type:

None

finish(result_count)
method
method
finish(result_count)

Finish progress reporting.

Parameters:

result_count (int)

Return type:

None

answer_now(result_count)
method
method
answer_now(result_count)

Finish progress reporting with a partial-answer status.

Parameters:

result_count (int)

Return type:

None

close()
method
method
close()

Stop any active progress renderer.

Return type:

None

interrupt()
method
method
interrupt()

Stop progress rendering while preserving the current status.

Return type:

None

_ensure_tty_thread()
method
method
_ensure_tty_thread()
Return type:

None

_stop_tty_thread()
method
method
_stop_tty_thread()
Return type:

None

_tty_loop()
method
method
_tty_loop()
Return type:

None

_render_tty(frame)
method
method
_render_tty(frame)
Parameters:

frame (str)

Return type:

None

_clear_tty_line()
method
method
_clear_tty_line()
Return type:

None

_write_tty_summary_line()
method
method
_write_tty_summary_line()
Return type:

None

_write_tty_line(line)
method
method
_write_tty_line(line)
Parameters:

line (str)

Return type:

None

_emit_heartbeat_if_due()
method
method
_emit_heartbeat_if_due()
Return type:

None

_emit_line(line)
method
method
_emit_line(line)
Parameters:

line (str)

Return type:

None

_summary(*, max_width=None)
method
method
_summary(*, max_width=None)
Parameters:

max_width (int | None)

Return type:

str

_terminal_width()
method
method
_terminal_width()
Return type:

int

_snapshot()
method
method
_snapshot()
Return type:

ProgressSnapshot

_start_line(label)
method
method
_start_line(label)
Parameters:

label (str)

Return type:

str

_heartbeat_line(label, elapsed)
method
method
_heartbeat_line(label, elapsed)
Parameters:
Return type:

str

_finish_line(result_count, elapsed)
method
method
_finish_line(result_count, elapsed)
Parameters:
Return type:

str

_answer_now_line(result_count)
method
method
_answer_now_line(result_count)
Parameters:

result_count (int)

Return type:

str

_status_text()
method
method
_status_text()
Return type:

str

_elapsed_seconds()
method
method
_elapsed_seconds()
Return type:

float

class agentgrep.SearchRuntime
class
class
class agentgrep.SearchRuntime

Bases: object

Reusable, explicit runtime state for one search frontend/session.

source_scan_cache: SourceScanCache | None
attribute
attribute
source_scan_cache: SourceScanCache | None
classmethod with_source_scan_cache(*, max_entries=512)
classmethod method
classmethod method
classmethod with_source_scan_cache(*, max_entries=512)

Return a runtime with a bounded source-scan cache.

Parameters:

max_entries (int)

Return type:

SearchRuntime

clear_caches()
method
method
clear_caches()

Clear every cache owned by this runtime.

Return type:

None

__init__(source_scan_cache=None)
method
method
__init__(source_scan_cache=None)
Parameters:

source_scan_cache (SourceScanCache | None)

Return type:

None

class agentgrep.SourceScanCache
class
class
class agentgrep.SourceScanCache

Bases: object

Bounded, in-process cache for reusable source-scan results.

__init__(*, max_entries=_SOURCE_SCAN_CACHE_MAX_ENTRIES)
method
method
__init__(*, max_entries=_SOURCE_SCAN_CACHE_MAX_ENTRIES)
Parameters:

max_entries (int)

Return type:

None

clear()
method
method
clear()

Clear cached scans and reset counters.

Return type:

None

stats()
method
method
stats()

Return privacy-safe cache counters.

Return type:

SourceScanCacheStats

_lookup(key)
method
method
_lookup(key)

Return a cached source scan entry, recording hit/miss counters.

Parameters:

key (_SourceScanCacheKey)

Return type:

_SourceScanCacheEntry | None

_remember(key, result)
method
method
_remember(key, result)

Store a completed source scan in the bounded cache.

Parameters:

  • key (_SourceScanCacheKey)

  • result (SourceScanResult)

Return type:

None

class agentgrep.SourceScanCacheStats
class
class
class agentgrep.SourceScanCacheStats

Bases: object

Privacy-safe counters for one source-scan cache.

entries: int
attribute
attribute
entries: int
hits: int
attribute
attribute
hits: int
misses: int
attribute
attribute
misses: int
stores: int
attribute
attribute
stores: int
evictions: int
attribute
attribute
evictions: int
to_payload()
method
method
to_payload()

Return a JSON-ready cache summary.

Return type:

dict[str, int]

__init__(entries, hits, misses, stores, evictions)
method
method
__init__(entries, hits, misses, stores, evictions)
Parameters:
Return type:

None