Library¶

Use agentgrep as a Python library from your own scripts and tools. The same search, discovery, parsing, serialization, and path-privacy layer powers the terminal CLI and the MCP server, so anything you can do from the command line you can drive directly in code. Search results may carry RecordOrigin; its path fields use the same PrivatePath display layer as source paths, and remote URLs are serialized without credentials.

Install¶

Pick an install method below — the snippet copies straight into your terminal, and the runnable quickstart mirrors the same search query you’d run from the CLI.

Save this as example.py. The PEP 723 inline-metadata header declares agentgrep as a dependency, so uv resolves and runs the script in an ephemeral environment:

# /// script
# requires-python = ">=3.14"
# dependencies = [
#   "agentgrep",
# ]
# ///

from pathlib import Path

import agentgrep

backends = agentgrep.select_backends()
query = agentgrep.SearchQuery(
    terms=("hello",),
    scope="all",
    any_term=False,
    regex=False,
    case_sensitive=False,
    agents=agentgrep.AGENT_CHOICES,
    limit=10,
)
for record in agentgrep.run_search_query(Path.home(), query, backends=backends):
    print(record.agent, record.title or record.path)

Then run it:

$ uv run example.py

With uv add installed:

$ uv add agentgrep

Then drive the library from Python:

from pathlib import Path

import agentgrep

backends = agentgrep.select_backends()
query = agentgrep.SearchQuery(
    terms=("hello",),
    scope="all",
    any_term=False,
    regex=False,
    case_sensitive=False,
    agents=agentgrep.AGENT_CHOICES,
    limit=10,
)
for record in agentgrep.run_search_query(Path.home(), query, backends=backends):
    print(record.agent, record.title or record.path)

$ pip install --user --upgrade agentgrep

Then drive the library from Python:

from pathlib import Path

import agentgrep

backends = agentgrep.select_backends()
query = agentgrep.SearchQuery(
    terms=("hello",),
    scope="all",
    any_term=False,
    regex=False,
    case_sensitive=False,
    agents=agentgrep.AGENT_CHOICES,
    limit=10,
)
for record in agentgrep.run_search_query(Path.home(), query, backends=backends):
    print(record.agent, record.title or record.path)