Wonk

Structure-aware code search that cuts LLM token burn by 37%.

Wonk indexes your codebase with Tree-sitter to understand code structure — definitions, call graphs, imports, and scopes — then ranks search results so definitions surface first and tests sort last. A built-in MCP server exposes 22 tools for AI coding assistants, and a background daemon keeps the index fresh. Single static binary, zero runtime dependencies.

Before / after

Searching for Blueprint in the Flask repo -- ripgrep returns 225 lines of unsorted noise (changelogs, docs, tests, definitions all mixed together). Wonk returns the same matches ranked and deduplicated: definitions first, usages next, comments and tests last, with re-exports collapsed into (+N other locations) annotations.

./src/flask/app.py:1119:  ...Blueprint`
./src/flask/app.py:1427:  ...Blueprint...
./src/flask/blueprints.py:10:from ...
./src/flask/blueprints.py:11:from ...
./src/flask/blueprints.py:18:class Blueprint...
./src/flask/__init__.py:3:from ...
./src/flask/debughelpers.py:8:from ...
./src/flask/debughelpers.py:146:  ...Blueprint
  ... 217 more unsorted lines ...

-- definitions --
src/flask/blueprints.py:18:class Blueprint(...)
  (+13 other locations)
src/flask/sansio/blueprints.py:119:class Blueprint(...)
  (+13 other locations)
-- usages --
src/flask/debughelpers.py:146:  ...Blueprint
src/flask/sansio/app.py:374:  self.blueprints: ...
  ... sorted by relevance ...
-- tests --
tests/test_blueprints.py:9:  ...

Same data, structured for an LLM context window -- definitions surface instantly instead of buried on line 67.

The problem

LLM coding agents grep aggressively. A single query can stuff hundreds of noisy, unranked lines into the context window -- raw matches with no sense of what is a definition, what is a test, and what is a re-export. That is wasted tokens and wasted money.

How it works

Wonk pre-indexes your codebase with Tree-sitter so it understands code structure: definitions vs. usages, symbol kinds, scopes, imports, and dependencies. When you search, results come back ranked, deduplicated, and grouped by relevance -- definitions first, tests last. The index stays fresh via a background file watcher, and a built-in MCP server exposes 22 tools for AI coding assistants.

┌─────────┐    ┌────────┐    ┌──────────────────────────┐    ┌────────┐    ┌────────┐
│  Query  │───>│ Router │───>│  SQLite index             │───>│ Ranker │───>│ Budget │──> Output
│ (CLI or │    │        │    │  (symbols, refs, imports,  │    │ Def >  │    │--bud-  │
│   MCP)  │    │        │    │   deps, call edges)        │    │ Use >  │    │ get N  │
└─────────┘    │        │───>│  grep fallback             │───>│ Test   │    └────────┘
               └────────┘    └──────────────────────────┘    └────────┘
                                          ▲
                                ┌─────────┴──────────┐
                                │  Daemon (notify)    │
                                │  keeps index fresh  │
                                └────────────────────┘

Search modes

Features at a glance

Search

• Smart ranking: definitions first, tests last, re-exports deduplicated
• Semantic search via Ollama embeddings (wonk ask)
• Hybrid RRF fusion blends structural + semantic results (--semantic)

Code intelligence

• Symbol lookup, signatures, and full source display (sym, sig, show)
• Call graph traversal: callers, callees, shortest call path
• Blast radius analysis with severity tiers and risk levels
• Execution flow tracing from entry points
• Changed symbol detection with blast/flow chaining

Architecture

• Single static binary -- SQLite, tree-sitter grammars, and grep engine bundled
• 12 languages: TypeScript/TSX, JavaScript, Python, Rust, Go, Java, C, C++, Ruby, PHP, C#
• Background daemon keeps index fresh via filesystem watcher
• Worktree isolation -- separate index per git worktree
• 22 MCP tools for AI coding assistants (JSON-RPC 2.0 over stdio)
• Token budget (--budget N) caps output and preserves top-ranked results

Benchmarks

25 code-understanding tasks across 5 real-world repos (ripgrep, tokio, httpx, pydantic, fastify), 5 runs each, median reported. Measures Claude Code token consumption with vs without wonk.

Overall: 37.4% total reduction (median per-task 29.7%, best 68.5%). Quality maintained at 0.90 vs 0.91 baseline.

Installation

curl (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/etr/wonk/main/install.sh | sh

Cargo

cargo install wonk

Building from source

git clone https://github.com/etr/wonk.git && cd wonk
cargo build --release
# Binary: target/release/wonk

Quick start

cd your-project
wonk search "handleRequest"       # ranked full-text search
wonk sym "UserService"            # find symbol definitions
wonk callers "dispatch"           # who calls this?
wonk blast "processPayment"       # what breaks if this changes?
wonk changes --blast --flows      # changed symbols + impact analysis
wonk ask "error handling logic"   # semantic search (requires Ollama)

Indexing happens automatically on first use.

How agents use wonk

Wonk's primary audience is AI coding agents. Three integration paths:

MCP server — wonk mcp serve exposes 22 JSON-RPC tools over stdio. Agents call wonk_search, wonk_sym, wonk_callers, wonk_blast, etc. with structured parameters and JSON responses. See MCP server.

Claude Code plugin — the wonk plugin bundles the MCP server, a skill that teaches Claude when to prefer wonk over grep/glob, and a session hook. See Claude Code plugin.

CLI via Bash tool — agents run wonk commands directly. Use --format toon -q for compact output and --budget N to cap token consumption.

Workflow patterns

Claude Code plugin

The wonk plugin integrates wonk into Claude Code as a native tool provider. It bundles the MCP server, an agent skill that teaches Claude when to prefer wonk over grep/glob, and a session hook that keeps the index fresh.

# Recommended: install via Groundwork Marketplace
claude plugin marketplace add https://github.com/etr/groundwork-marketplace
claude plugin install wonk

See the wonk-plugin repo for alternative installation methods.

MCP server

Wonk includes a built-in MCP server for AI coding assistants. Add to your .mcp.json:

{
  "mcpServers": {
    "wonk": {
      "command": "wonk",
      "args": ["mcp", "serve"]
    }
  }
}

22 tools exposed: search, sym, ref, sig, show, deps, rdeps, callers, callees, callpath, summary, flows, blast, changes, context, ask, cluster, impact, init, update, status, repos. All tools accept an optional repo parameter for multi-repo setups.

Commands

Full flag reference: docs/commands.md

Comparison with alternatives

Output formats

grep (default) -- standard grep-compatible format, pipe-friendly:

src/main.rs:42:fn main() {}

json (--format json) -- NDJSON, one object per line:

{"file":"src/main.rs","line":42,"col":1,"content":"fn main() {}"}

toon (--format toon) -- compact, indentation-based, minimal punctuation:

file: src/main.rs
line: 42
content: fn main() {}

Supported languages

TypeScript (TSX), JavaScript (JSX), Python, Rust, Go, Java, C, C++, Ruby, PHP, C#

Optional dependencies

Wonk's core features work out of the box with zero external dependencies. Advanced features require:

• Ollama -- for semantic search and AI-generated summaries. Pull nomic-embed-text (embeddings) and llama3.2:3b (summaries).
• git -- only needed for wonk impact --since and wonk changes --scope compare. Most likely already installed.

Configuration

Layered TOML config: built-in defaults < ~/.wonk/config.toml < <repo>/.wonk/config.toml.

Full reference: docs/configuration.md

Acknowledgments

Built with Claude Code and Groundwork.

License

MIT