agentgrep

The top-level package contains the CLI parser, search pipeline, terminal progress renderer, and serializer helpers used by the command-line interface and MCP server.

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.SearchArgs
class
class
class agentgrep.SearchArgs

Bases: object

Typed arguments for agentgrep search.

terms: tuple[str, ...]
attribute
attribute
terms: tuple[str, ...]
agents: tuple[Literal['codex', 'claude', 'cursor', 'gemini'], ...]
attribute
attribute
agents: tuple[Literal['codex', 'claude', 'cursor', 'gemini'], ...]
search_type: Literal['prompts', 'history', 'all']
attribute
attribute
search_type: Literal['prompts', 'history', 'all']
any_term: bool
attribute
attribute
any_term: bool
regex: bool
attribute
attribute
regex: bool
case_sensitive: bool
attribute
attribute
case_sensitive: bool
limit: int | None
attribute
attribute
limit: int | None
output_mode: Literal['text', 'json', 'ndjson', 'ui']
attribute
attribute
output_mode: Literal['text', 'json', 'ndjson', 'ui']
color_mode: Literal['auto', 'always', 'never']
attribute
attribute
color_mode: Literal['auto', 'always', 'never']
progress_mode: Literal['auto', 'always', 'never']
attribute
attribute
progress_mode: Literal['auto', 'always', 'never']
__init__(terms, agents, search_type, any_term, regex, case_sensitive, limit, output_mode, color_mode, progress_mode)
method
method
__init__(terms, agents, search_type, any_term, regex, case_sensitive, limit, output_mode, color_mode, progress_mode)
Parameters:

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

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

  • search_type (SearchType)

  • any_term (bool)

  • regex (bool)

  • case_sensitive (bool)

  • limit (int | None)

  • output_mode (OutputMode)

  • color_mode (ColorMode)

  • progress_mode (ProgressMode)

Return type:

None

class agentgrep.FindArgs
class
class
class agentgrep.FindArgs

Bases: object

Typed arguments for agentgrep find.

pattern: str | None
attribute
attribute
pattern: str | None
agents: tuple[Literal['codex', 'claude', 'cursor', 'gemini'], ...]
attribute
attribute
agents: tuple[Literal['codex', 'claude', 'cursor', 'gemini'], ...]
limit: int | None
attribute
attribute
limit: int | None
output_mode: Literal['text', 'json', 'ndjson', 'ui']
attribute
attribute
output_mode: Literal['text', 'json', 'ndjson', 'ui']
color_mode: Literal['auto', 'always', 'never']
attribute
attribute
color_mode: Literal['auto', 'always', 'never']
__init__(pattern, agents, limit, output_mode, color_mode)
method
method
__init__(pattern, agents, limit, output_mode, color_mode)
Parameters:

  • pattern (str | None)

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

  • limit (int | None)

  • output_mode (OutputMode)

  • color_mode (ColorMode)

Return type:

None

class agentgrep.SearchQuery
class
class
class agentgrep.SearchQuery

Bases: object

Compiled search configuration.

terms: tuple[str, ...]
attribute
attribute
terms: tuple[str, ...]
search_type: Literal['prompts', 'history', 'all']
attribute
attribute
search_type: Literal['prompts', 'history', 'all']
any_term: bool
attribute
attribute
any_term: bool
regex: bool
attribute
attribute
regex: bool
case_sensitive: bool
attribute
attribute
case_sensitive: bool
agents: tuple[Literal['codex', 'claude', 'cursor', 'gemini'], ...]
attribute
attribute
agents: tuple[Literal['codex', 'claude', 'cursor', 'gemini'], ...]
limit: int | None
attribute
attribute
limit: int | None
__init__(terms, search_type, any_term, regex, case_sensitive, agents, limit)
method
method
__init__(terms, search_type, any_term, regex, case_sensitive, agents, limit)
Parameters:
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', 'gemini']
attribute
attribute
agent: Literal['codex', 'claude', 'cursor', 'gemini']
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']
attribute
attribute
path_kind: Literal['history_file', 'session_file', 'sqlite_db']
source_kind: Literal['json', 'jsonl', 'sqlite']
attribute
attribute
source_kind: Literal['json', 'jsonl', 'sqlite']
search_root: Path | None
attribute
attribute
search_root: Path | None
mtime_ns: int
attribute
attribute
mtime_ns: int
__init__(agent, store, adapter_id, path, path_kind, source_kind, search_root, mtime_ns)
method
method
__init__(agent, store, adapter_id, path, path_kind, source_kind, search_root, mtime_ns)
Parameters:

  • agent (AgentName)

  • store (str)

  • adapter_id (str)

  • path (Path)

  • path_kind (PathKind)

  • source_kind (SourceKind)

  • search_root (Path | None)

  • mtime_ns (int)

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', 'gemini']
attribute
attribute
agent: Literal['codex', 'claude', 'cursor', 'gemini']
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', 'gemini']
attribute
attribute
agent: Literal['codex', 'claude', 'cursor', 'gemini']
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']
attribute
attribute
path_kind: Literal['history_file', 'session_file', 'sqlite_db']
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

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()
method
method
_summary()
Return type:

str

_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

Serialization and CLI

agentgrep.serialize_search_record(record)
function
function
agentgrep.serialize_search_record(record)

Serialize a search record to a JSON-compatible mapping.

Parameters:

record (SearchRecord)

Return type:

SearchRecordPayload

agentgrep.serialize_find_record(record)
function
function
agentgrep.serialize_find_record(record)

Serialize a find record to a JSON-compatible mapping.

Parameters:

record (FindRecord)

Return type:

FindRecordPayload

agentgrep.serialize_source_handle(source)
function
function
agentgrep.serialize_source_handle(source)

Serialize a source handle to a JSON-compatible mapping.

Parameters:

source (SourceHandle)

Return type:

SourceHandlePayload

agentgrep.build_envelope(command, query_data, results)
function
function
agentgrep.build_envelope(command, query_data, results)

Build a JSON envelope.

Parameters:
Return type:

EnvelopePayload

agentgrep.run_search_command(args)
function
function
agentgrep.run_search_command(args)

Execute agentgrep search.

Parameters:

args (SearchArgs)

Return type:

int

agentgrep.run_find_command(args)
function
function
agentgrep.run_find_command(args)

Execute agentgrep find.

Parameters:

args (FindArgs)

Return type:

int

agentgrep.main(argv=None)
function
function
agentgrep.main(argv=None)

Run the CLI.

Parameters:

argv (Sequence[str] | None)

Return type:

int