duckgrep

Grep finds strings. duckgrep answers questions.

Give your coding agent a live, queryable model of your codebase (definitions, callers, imports, history), so structural questions take one query instead of a search loop.

What it saves

We measured duckgrep with Claude Code (Sonnet 5.5) on 494 structural questions from 25 open-source Python and Rust repos: who calls this, what reaches it through one more caller, what imports this module. In every setup the model and tools were the same; the only difference was the MCP server. Each agent also had the same one-line instruction to use its tool.

12–19% less work and a quarter less cost, with answers just as accurate.

• Why: duckgrep answers "who calls this, and from which function" in one call. A grep hit gives a line, and the agent then has to read around it to find the function.
• Without the instruction, agents still chose duckgrep for 75% of these questions. They cut tool calls by 12–19% and cost by 14–18%.

Where it doesn't help: finding where to fix a bug from an issue report (230 SWE-bench tasks). The issue usually names something one grep finds, so there's nothing to save. Carrying the tool's description added 11–13% tokens on Python; they're cached, so cost stayed flat.

_{3,620 runs in all, made on 2026-10-02 with Claude Code 2.1.287. Changes compare each setup with Claude Code alone, task by task, with tool calls and round trips compared as 1 + n. † marks a difference that doesn't hold after correcting for all 160 comparisons. Every duckgrep change in calls, round trips, tokens and cost holds; the correct-answer rates differ by no more than chance in any setup. Full tables, the method and the harness are in bench/RESULTS.md and bench/eval.}

Why it matters

Coding agents find their way around a codebase with chains of grep → read file → grep again. That works for "where is this string." But the questions that matter when changing code are structural: who calls this, what does it call, what breaks if I change it, what's dead. Each one turns into a loop of searches, file reads and guesses, paid for in turns and tokens.

• It answers structural questions, not text matches. "Who calls this, and from which function?" is one query, not a search loop. On django, finding every call to get_or_create and the function it sits in took 22 calls (one grep, then 21 file reads to find the enclosing functions) and 58 KB of output. duckgrep answered it in one query and 9 KB.
• It answers questions no tool author anticipated. Code-navigation tools give agents a fixed menu: find definition, find references. duckgrep gives them a query language. "Public functions in pricing/ with no callers outside their module" isn't a feature anyone built; the agent just writes the query.
• It joins code with its history. The call graph, git churn and authorship sit in the same place, so an agent can ask "what's risky to change here," which text search can't answer.
• It's trustworthy mid-edit. The index refreshes before every query, so it reflects the agent's latest edits. Every call-graph edge says how it was resolved, so the agent knows when to trust the graph and when to go read the code.

How it works

duckgrep parses the repo with tree-sitter into a single DuckDB file and exposes it as one read-only query(sql) MCP tool. The tool's description carries the whole schema, so the agent can write a correct query on its first call.

SELECT * FROM callers('Session.request') WHERE resolution <> 'name';

-- everything that reaches a function within 3 hops
WITH RECURSIVE up(p, q, d) AS (
  SELECT path, qualname, 0 FROM symbols WHERE qualname = 'SQLCompiler.execute_sql'
  UNION SELECT e.src_path, e.src_scope, d + 1 FROM edges e JOIN up ON e.dst_path = up.p AND e.dst_qualname = up.q
  WHERE d < 3 AND e.resolution NOT IN ('name', 'ambiguous', 'unresolved') AND e.src_scope <> '')
SELECT p, q, min(d) FROM up GROUP BY p, q;

-- hottest files by churn that define classes
SELECT * FROM file_churn WHERE path IN (SELECT path FROM symbols WHERE kind = 'class')
ORDER BY n_commits DESC LIMIT 10;

Languages: Python, TypeScript/TSX, JavaScript, Go, Rust. Every other text file is still indexed for grep(). Built on DuckDB and tree-sitter.

Install

uv tool install duckgrep

Claude Code

claude mcp add duckgrep -- duckgrep mcp

The server answers at once and builds the index in the background; the first call waits for it. After that, every call runs an incremental refresh, so results reflect the agent's latest edits with no hooks.

Tell your agent to use it

Agents reach for grep out of habit. Add this to your CLAUDE.md (or your agent's instructions). It's the line the numbers above were measured with:

The repository in the current directory is indexed by duckgrep. To find code, call its query tool before Grep, Glob or Read: SELECT * FROM defs('name') finds where a symbol is defined, callers('name') who calls it, and grep('regex') searches the text and names each match's enclosing function. Read a file once you know where to look.

CLI

-C DIR sets the repo root, used as given.

duckgrep index                      # build / update (.duckgrep/index.duckdb, self-gitignored)
duckgrep def Session                # where defined
duckgrep callers Session.request    # who references it, with the calling function
duckgrep callees Session.request    # what it references
duckgrep outline sessions.py        # symbols in a file
duckgrep grep '(?i)retry'           # regex + enclosing symbol
duckgrep source Session.request     # the code
duckgrep q "SELECT ..."             # anything
duckgrep schema                     # what the agent sees

FAQ

Roadmap and contributing

• docs/roadmap.md: what's next and the known gaps.
• CHANGELOG.md: what changed in each release.
• CONTRIBUTING.md: how to set up, test and benchmark.

License

Apache License 2.0. See LICENSE.