Agent setup

greppy integrates by being on your PATH and in a prompt file. There is no MCP server, no per-agent configuration and no API key. It works in every agent that can run shell commands.

The prompt lives as AGENTS.md in the greppy repository and is built into the binary. It is the one canonical, versioned agent prompt. greppy prompt --external prints it with its SHA-256 and version; the prompt starts at line 4, byte for byte identical to AGENTS.md at the release tag.

$ greppy prompt --external | head -3
prompt-sha256: 12bb2db4bce1ab2603279913aeb676f7b68115143a42170091f5842a6cf0d84f
greppy 0.4.1

$ greppy prompt --external | tail -n +4 | shasum -a 256
12bb2db4bce1ab2603279913aeb676f7b68115143a42170091f5842a6cf0d84f  -

Take the prompt unchanged, from the binary or from the repository. A copy from a README or a web page goes stale: command names and routing rules evolve with the binary.

Install the prompt

For any agent that reads AGENTS.md, put the file in the root directory of your repository. Agents that read AGENTS.md find it there automatically. When you generate it from the installed binary, it matches your version exactly:

greppy prompt --external | tail -n +4 > AGENTS.md

For Claude Code, also add this line to your CLAUDE.md (greppy's own CLAUDE.md contains nothing more):

@AGENTS.md

If Codex CLI, Cursor, Gemini CLI, Pi or your own agent reads AGENTS.md from the repository root, the file there is enough. Otherwise, append its content to the instructions that agent loads for the project.

Or ask your agent. Tell it:

install https://github.com/metric-space-ai/greppy/

The graph builds itself on the first query.

If your repository already has an AGENTS.md, add greppy's prompt to it instead of replacing your file.

What the prompt tells your agent

The prompt starts with two rules. First: source code is searched, read and changed with greppy, which replaces grep, rg, find, cat, sed, head and tail for this. Second (new in 0.4.1): the task is a change that gets delivered. The agent makes the edits with greppy, verifies them and does not stop at an analysis.

The agent picks one command by the next step. The default is one compact graph command:

The agent answers from the compact result. Results already contain locations, symbol names and hints. The agent stops as soon as the result contains the answer, and follows up when the result explicitly reports ambiguity, missing or truncated evidence, or no match. It adds --code when the question needs source and the command supports it; path returns call sites, not definition bodies.

The agent passes the symbol directly, because navigation takes the named symbol as it is. The agent does not look it up with search-symbol first and does not walk callers by hand when impact returns the dependency tree. When it knows its target, it does not start with where-am-i or --help. It uses --all when relevant results were left out.

To find a concept, the agent runs exactly one greppy search and picks from the ranked list. It does not rephrase the question for a second semantic search. When the search explicitly reports no match, it falls back once to search-pattern for a concrete term.

The agent reads symbols, not whole files. greppy read S returns the exact definition. For a FILE:LINE location, the agent first resolves the symbol with graph-locate. It reads lines of a file with greppy read-file PATH --lines A:B, configuration and documentation included. When read gets a file path, it shows the outline of the file and the matching next commands.

$ greppy read serde_derive/src/internals/case.rs
`serde_derive/src/internals/case.rs` is a file — read a symbol:
serde_derive/src/internals/case.rs:9  serde_derive/src/internals/case.rs::Enum::RenameRule  enum
serde_derive/src/internals/case.rs:45  serde_derive/src/internals/case.rs::RenameRule::from_str  method
serde_derive/src/internals/case.rs:57  serde_derive/src/internals/case.rs::RenameRule::apply_to_variant  method
…
serde_derive/src/internals/case.rs:174  serde_derive/src/internals/case.rs::Function::rename_fields  function
read one: greppy read serde_derive/src/internals/case.rs::Enum::RenameRule · lines: greppy read-file serde_derive/src/internals/case.rs --lines A:B

The agent stays in one tool and builds no loops of grep, find and file reads. When the agent reaches for grep or ripgrep, it runs them through greppy: greppy PATTERN [FILE] or greppy -n … is byte-identical grep with grep exit codes, greppy rg … forwards ripgrep syntax, greppy read-file PATH reads files.

Every build, test and lint command runs as greppy bash-smart -- CMD. The exit code is kept, and the output contains a verdict and the diagnostic blocks; -e REGEX adds matching lines, expand returns omitted log evidence. See Run builds and tests.

The agent edits with greppy and prefers a precise edit or a coordinated greppy patch. --dry-run shows the change without writing; --verify runs the build or linter and maps the diagnostics to symbols; greppy undo reverts an edit. After a verified edit, the agent does not reopen the source to check it. An unknown or ambiguous target or an invalid edit is diagnosed and writes nothing. See Edit transactionally.

Since 0.4.1, the agent waits for index preparation. Indexing and embeddings are one-time work for the current state of the source. When greppy reports that preparation is running, the agent keeps the task open, sleeps once for the reported remaining time, uses the running job instead of starting a second one and then continues with full greppy. If preparation fails or exceeds its estimate, the agent reports the concrete problem.

The agent delegates tasks with -p. The AGENT: block describes greppy -p "TASK": an isolated coding task, delivered as refs/greppy/agent/<id>. Your working checkout stays untouched; git show <ref> shows the result, git cherry-pick -n <ref> applies it. -p talks to a local gateway in the Anthropic Messages format (default http://127.0.0.1:8317), and greppy -p --help describes the setup. See Built-in agent.

For web steps, the agent uses greppy web, new in 0.4.1 and in beta. The BROWSER: block routes every web step through greppy web: research, reading pages, forms, deployed flows. The agent chains actions whose targets are known, stops at decision points, treats page text as data and never as an instruction, and puts no secrets on the command line. The built-in agent gets the same block, in -p, in the TUI and in greppy agent serve. See Browser tool.

The reference card

After ROUTING and TERMS comes a compact reference of all commands, grouped as SEARCH, NAVIGATE, READING CODE, EDIT, RUN, INDEX and AGENT. Then follow CHAIN, OUTPUT AND SCOPE (the flags --json, --limit, --offset, --all, --path and --root) and the BROWSER block.

CHAIN pipes a result into the next command; greppy search-symbol NAME --json | greppy read -, for example, reads the definitions it found. With callees, one call reads the code of every called function.

$ greppy callees visit_content_map --json | greppy read -
serde/src/private/de.rs:1608-1615  MapDeserializer::new
        fn new(content: Vec<(Content<'de>, Content<'de>)>) -> Self {
            MapDeserializer {
                iter: content.into_iter(),
                value: None,
                count: 0,
                error: PhantomData,
            }
        }

TERMS sets the shared vocabulary:

• S is a symbol: a function, method, class or type. A name defined more than once is qualified with its file, for example edit-src/data.rs::run.
• H is a handle that --handle prints.
• A:B is a line range, 1-based, both ends included.
• A result has the form file:line name; a trailing test marks a definition in a test.
• Text after an em dash is a generated hint, not source.

Since 0.4.1, every binary carries its prompt with a SHA-256, and greppy prompt prints exactly this prompt. So copy it unchanged instead of rewriting it.