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.

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",),
    search_type="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
Tutorial

Run the CLI from first search to structured output.

Tutorial
How to

Common workflows for search, discovery, progress, and scripting.

How to
Reference

Python API and MCP reference entry points.

Reference
Examples

CLI and MCP request examples.

Examples