Token-efficient code recon for AI agents. A scout you run before
read.
agrep is a CLI that extracts function signatures, type declarations, and
doc comments from source files, so an AI agent can understand what a file
exposes without reading every byte of it.
Agents exploring an unfamiliar codebase spend a meaningful slice of their
token budget on Read — loading whole files to find one symbol's body.
agrep was built to cut that by extracting a file's structural surface so
the agent can locate what it needs and read only that part.
What it actually saves, measured against a no-tool baseline across 15 tasks × 3 runs on a real Go codebase (Claude Sonnet 4.6 via Claude Code CLI):
- Single-file deep dive (locate a method, read its body),
5 tasks: +13.7% tokens, +9.7% cost on aggregate, and +16–25% per
task on the cases where
agrepremoves a follow-upReadturn (B1, B2, B5). This is the tool's clean, repeatable win. - Pure structural lookup, 4 tasks: mixed —
agrepsaves ~+24% when it removes a turn (agrep signatures order.goanswers directly), but loses ~−20–36% on directory-wide queries wheregrep -rnis faster and more trusted. - Aggregate across the mixed 15-task suite: +5.4% on cost, +16.9% on
tokens vs baseline — a net loss. Multi-file comprehension tasks
(trace a flow, explain a feature end-to-end) regress badly because
agrepadds turns there without removing any.
So: agrep is a real win on single-file locate-then-read workflows
go install github.com/kypkk/agrep@latestagrep uses a tree-sitter binding that requires cgo, so a working C compiler must be available at install time (Apple clang, gcc, or MSVC).
Two subcommands:
agrep signatures <file> [--format=human|agent|json] [--all]
agrep find <predicate> --in <dir>
Lists every top-level symbol in one file — functions, methods (with
receivers), structs, interfaces, type aliases — with signatures and line
numbers. --format=agent for dense one-line-per-entity output; --all to
include unexported.
$ agrep signatures internal/parser/golang.go --format=agent
struct 11 GoParser {p *sitter.Parser}
func 16 NewGoParser() *GoParser
method 23 (g *GoParser) Parse(src []byte) (*Tree, error)
Cross-file structural search. At least one predicate is required:
--has-method, --has-receiver, --returns, --takes (substring,
case-insensitive); --implements, --kind (exact). Flags combine with
AND. --limit N / --all for pagination.
$ agrep find --has-method=Parse --in=.
1 types with method Parse:
GoParser internal/parser/golang.go:11
func (g *GoParser) Parse(src []byte) (*Tree, error) :23
Run agrep --help / agrep <subcommand> --help for the full flag
reference. JSON output schema:
docs/json-schema.md.
agrep v0 is Go-only. The codebase is structured behind a
language-agnostic parser.Parser interface so additional languages plug
in without touching the analyzer or formatters — but no other languages
ship today.
The signatures subcommand extracts:
- Top-level functions and methods (with receivers)
- Struct types (fields, including multi-name and embedded)
- Interface types (method signatures)
- Type aliases (
type X = Y) and named types (type X Y) - Doc comments (
//line comments immediately above an entity)
Not yet captured (planned, additive when added):
- Struct field tags
- Block-comment doc (
/* */) - Constants and package-level variables
- Generic type parameters on type declarations (functions are covered)
- Interface type-element constraints (
~int | string)
agrep parses source with tree-sitter and walks the AST. Tree-sitter is fast, error-recovering, and language-agnostic — the same engine handles dozens of languages with small per-language grammar packages.
The pipeline:
file.go ──► parser.GoParser ──► analyzer.ExtractSignatures
│
└─► analyzer.ExtractTypes
│
└─► format.{Human,Agent,JSON}
Each stage lives in its own internal/ package and is independently
testable.
MIT.