# Wonk

> Structure-aware code search that cuts LLM token burn. Tree-sitter indexing, ranked results, grep-compatible output.

- **Type:** MCP server
- **Install:** `agentstack add mcp-etr-wonk`
- **Verified:** Pending review
- **Seller:** [etr](https://agentstack.voostack.com/s/etr)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [etr](https://github.com/etr)
- **Source:** https://github.com/etr/wonk

## Install

```sh
agentstack add mcp-etr-wonk
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Wonk

[](https://github.com/etr/wonk/actions/workflows/ci.yml)
[](https://crates.io/crates/wonk)
[](LICENSE)

**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.

rg Blueprint (225 lines)wonk search Blueprint (213 lines)

```
./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

| Mode | What it does |
|------|-------------|
| `wonk search ` | Full-text search ranked by code structure. Definitions first, tests last, re-exports collapsed. Add `--semantic` for hybrid RRF fusion. |
| `wonk sym` / `sig` / `show` / `ref` | Direct symbol lookup. Find definitions, view signatures, read full source, or trace references — no regex needed. |
| `wonk ask ` | Semantic search via Ollama embeddings. Natural-language queries over code meaning. Requires Ollama + nomic-embed-text. |

## 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.

| Category | Baseline (avg) | Wonk (avg) | Reduction | Quality (B→W) |
|----------|---------------:|-----------:|----------:|--------------:|
| symbol_location | 100k | 61k | 33% | 0.85→0.85 |
| reference_tracing | 96k | 57k | 28% | 0.92→0.88 |
| architecture | 162k | 101k | 29% | 0.90→0.96 |
| multi_step | 143k | 104k | 23% | 0.93→0.93 |
| structural | 130k | 69k | 46% | 0.95→0.88 |

**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)

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

### Cargo

```sh
cargo install wonk
```

### Building from source

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

## Quick start

```sh
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](#mcp-server).

**Claude Code plugin** — the [wonk plugin](https://github.com/etr/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](#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

| Task | Command |
|------|---------|
| Find a definition | `wonk sym X` or `wonk show X` |
| Full context (def + callers + callees) | `wonk context X --budget 4000` |
| Trace forward call graph | `wonk callees X --depth 3` |
| Shortest path A → B | `wonk callpath A B` |
| Impact of a change | `wonk blast X` or `wonk changes --blast` |
| Module overview | `wonk summary src/api --depth 1` |

## Claude Code plugin

The [wonk plugin](https://github.com/etr/wonk-plugin) integrates wonk into [Claude Code](https://docs.anthropic.com/en/docs/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.

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

See the [wonk-plugin repo](https://github.com/etr/wonk-plugin) for alternative installation methods.

## MCP server

Wonk includes a built-in [MCP](https://modelcontextprotocol.io/) server for AI coding assistants. Add to your `.mcp.json`:

```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

| Command | Description |
|---------|-------------|
| **Search** | |
| `search ` | Full-text search with smart ranking, dedup, `--semantic` fusion |
| `ask ` | Semantic search via embedding similarity |
| **Symbol lookup** | |
| `sym ` | Symbol definitions by name, kind, or exact match |
| `ref ` | Find references to a symbol |
| `sig ` | Show function/method signatures |
| `show ` | Show full source body (`--shallow` for containers) |
| **Code structure** | |
| `ls [path]` | List files and symbols (`--tree` for structure) |
| `deps ` | Show file dependencies (imports) |
| `rdeps ` | Show reverse dependencies |
| `summary ` | Structural summary with optional `--semantic` description |
| **Call graph** | |
| `callers ` | Find callers with transitive `--depth` expansion |
| `callees ` | Find callees with transitive `--depth` expansion |
| `callpath  ` | Shortest call chain between two symbols |
| **Program analysis** | |
| `flows [entry]` | Detect entry points and trace execution flows |
| `blast ` | Blast radius with severity tiers and risk levels |
| `changes` | Changed symbols with optional `--blast` / `--flows` chaining |
| `context ` | Full symbol context: callers, callees, flows, children |
| `impact ` | Symbol-level change impact analysis |
| **Semantic** | |
| `cluster ` | Cluster symbols by semantic similarity (K-Means) |
| **Index management** | |
| `init` | Build index (auto-runs on first query) |
| `update` | Rebuild index |
| `status` | Show index stats |
| `repos list\|clean` | Manage tracked repositories |
| **Daemon** | |
| `daemon start\|stop\|status\|list` | Manage background file watcher |
| **Integration** | |
| `mcp serve` | Start MCP server (JSON-RPC 2.0 over stdio) |

Full flag reference: [`docs/commands.md`](docs/commands.md)

## Comparison with alternatives

| | wonk | ripgrep | ctags/LSP |
|---|---|---|---|
| Structural ranking | Definitions first, tests last | No ranking | N/A |
| Deduplication | Re-export collapsing | None | N/A |
| Call graph | Callers, callees, callpath, blast radius | No | LSP only (running server) |
| Semantic search | Embedding similarity (Ollama) | No | No |
| Token budget | `--budget N` caps output | No | No |
| Setup | Single binary, auto-indexes | Single binary | Language server per language |
| MCP server | 22 tools built-in | No | Via adapter |
| Output | grep-compatible + JSON + TOON | grep + JSON | Protocol-specific |

## Output formats

**grep** (default) -- standard grep-compatible format, pipe-friendly:
```
src/main.rs:42:fn main() {}
```

**json** (`--format json`) -- NDJSON, one object per line:
```json
{"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](https://ollama.ai/)** -- 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`.

Full reference: [`docs/configuration.md`](docs/configuration.md)

## Acknowledgments

Built with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [Groundwork](https://github.com/etr/groundwork).

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [etr](https://github.com/etr)
- **Source:** [etr/wonk](https://github.com/etr/wonk)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-etr-wonk
- Seller: https://agentstack.voostack.com/s/etr
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.