What is wonk CLAUDE.md?

Project instructions for Wonk, a Rust command-line tool that searches code for AI coding agents. It combines structure-aware parsing, a database index, text search, result ranking, and output limits.

Building, testing, formatting, linting, and understanding how Wonk indexes code, searches it, ranks results, and limits the returned context.

They give contributors the commands and architecture needed to change the search tool without breaking its checks or data flow.

How etr/wonk configures Claude Code

Reuse

Borrowing it

Nothing to install: this file belongs to etr/wonk. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/etr/wonk/main/CLAUDE.md

Clone the repo

git clone --depth 1 https://github.com/etr/wonk

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/etr/wonk/claude-md/github.svg)](https://agentmods.dev/instructions/etr/wonk/claude-md)

Your own site

<a href="https://agentmods.dev/instructions/etr/wonk/claude-md"><img src="https://agentmods.dev/badge/instructions/etr/wonk/claude-md/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/instructions/etr/wonk/claude-md"><img src="https://agentmods.dev/badge/instructions/etr/wonk/claude-md.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 1,820 This file is loaded in full into every session.

When invoked 1,820 The same file — it is already loaded in full.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.01820	$0.01820
Opus 5.5	$0.00728	$0.00728
Sonnet 5.5	$0.00364	$0.00364
Haiku 4.5	$0.00182	$0.00182

Measured 1mo ago against content hash 408cc22e9f55, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

wonk CLAUDE.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 1mo ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

CLAUDE.md · 87 lines

How it starts

The opening of the file, as written. The whole thing — 87 lines — stays where its author put it; the contents beside it link to each section on GitHub.

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Development Commands

cargo build                    # Build debug binary
cargo build --release          # Build release binary
cargo test                     # Run all tests
cargo test <test_name>         # Run a single test by name
cargo test --lib               # Run only unit tests (no integration tests)
cargo fmt --check              # Check formatting (CI enforced)
cargo fmt                      # Auto-format code
cargo clippy -- -D warnings    # Lint with warnings-as-errors (CI enforced)

CI enforces RUSTFLAGS="-D warnings" — all warnings are errors.

Architecture

Wonk is a structure-aware code search CLI for LLM coding agents. It combines tree-sitter parsing, SQLite indexing, and ripgrep-based text search to return ranked, deduplicated results that minimize token consumption.

Data Flow

CLI (clap) → Router → { SQLite index | grep search } → Ranker → Budget → Output
                                    ↑
                              Daemon (notify → pipeline → SQLite)

Module Responsibilities

Module	Role
`cli.rs`	Clap-derived argument parsing, delegates to `router::dispatch()`
`router.rs`	Query dispatch — routes commands to index or grep fallback, auto-initializes index on first use
`indexer.rs`	Tree-sitter parsing — extracts symbols, references, and imports for 12 languages
`db.rs`	SQLite layer — schema (WAL mode), repo root detection, index path computation
`pipeline.rs`	Index build orchestration — parallel file walk + parse + batch insert; incremental re-indexing for daemon; provider-neutral embedding build pipeline (chunking → batch embed → vector storage)
`walker.rs`	File enumeration with gitignore/wonkignore support; worktree-aware boundary detection
`search.rs`	Text search wrapping the `grep` crate (ripgrep internals)
`semantic.rs`	Brute-force cosine similarity search — parallel dot product via rayon, top-N ranking, resolution of symbol IDs to SemanticResult structs; BFS dependency graph traversal for `--from`/`--to` reachability scoping
`cluster.rs`	K-Means clustering engine — auto-k selection via silhouette scoring, cluster member resolution from SQLite
`ranker.rs`	Classifies results (Definition > CallSite > Import > Other > Comment > Test), deduplicates re-exports; RRF fusion via `fuse_rrf()` for `--semantic` blending
`output.rs`	Dual format: grep-compatible (stdout+stderr) or NDJSON (stdout)
`embedding.rs`	Embedding provider abstraction, Ollama API client, symbol chunking engine, and vector storage — bundled offline default plus opt-in sync Ollama client, context-rich chunks, provider-isolated BLOB storage, and query-time provider fallback (unreachable Ollama → bundled, never across mismatched vector spaces)
`show.rs`	Source body retrieval — queries symbol index by name with optional file/kind/exact filters, reads source file lines line..end_line per match, falls back to signature when end_line is absent; shallow mode for containers shows signature + child signatures without bodies
`summary.rs`	Structural summary engine — queries SQLite to aggregate file count, line count, symbol counts by kind, language breakdown, and dependency count for a path; supports three detail levels (rich/light/symbols), recursive depth traversal, symbol listing with location metadata, and `--tree` scope-grouped display (absorbed former `wonk ls`)
`llm.rs`	LLM description generation and caching — content hash computation from (symbol.id, file.hash) pairs, prompt construction from structural metrics, Ollama `/api/generate` sync client, SQLite cache get/store for `wonk summary --semantic`
`impact.rs`	Symbol change detection — Tree-sitter re-parse vs. indexed symbols for Added/Modified/Removed; git CLI wrapper for `--since` file listing; scoped change detection via `ChangeScope` enum and `detect_changes()` with git diff hunk-to-symbol mapping
`daemon.rs`	Background file watcher — double-fork daemonization, PID file, SIGTERM handler, embedding worker thread, daemon status table
`watcher.rs`	Filesystem event classification and debouncing via `notify`
`config.rs`	Layered TOML config: built-in defaults → `~/.wonk/config.toml` → `<repo>/.wonk/config.toml`
`context.rs`	Unified symbol context — aggregates definition, callers, importers, type users, callees, imports, flow participation, and children from type_edges into a single `SymbolContext` response
`blast.rs`	Blast radius analysis — depth-annotated BFS from a target symbol, severity tiers (WILL BREAK / LIKELY AFFECTED / MAY NEED TESTING), risk level assessment, inheritance integration via type_edges, test file exclusion; qualifying upstream queries are answered from the precomputed reach table by default with BFS as the fallback beyond the built depth or when the table is stale/disabled
`callgraph.rs`	Call graph traversal — BFS callers/callees expansion and callpath shortest-path finder via caller_id JOIN, cycle detection via visited HashSet, depth cap enforcement
`flows.rs`	Entry point detection and flow tracing — SQL anti-join for functions/methods with no indexed callers, forward BFS callee expansion with depth/branching/min-confidence controls
`reach.rs`	Precomputed upstream reachability — bounded-depth reach table built inside the index transaction, name-keyed BFS mirroring blast's traversal, per-source fan-out cap with truncation markers, stale/absent-table BFS fallback, and the edge-eligibility predicate shared with blast (AR-021)
`history.rs`	Bounded git-history mining — one `git log` pass over the newest N commits into per-commit detail, aggregate churn + co-change tables recomputed from that detail, watermark-driven refresh (`wonk update` authoritative, daemon best-effort)
`topology.rs`	Symbol-graph topology — deterministic HITS hub/authority + label-propagation communities recomputed on update and at the daemon interval; read-only staleness helpers (the query path never recomputes)
`contracts.rs`	Service-contract detection across 12 languages (HTTP routes/clients, env, queues, websocket, jobs, gRPC, GraphQL, OpenAPI) + cross-repo workspace link resolution
`review.rs`	Diff-scoped review engine — rule families A (breaking change), B (coverage gap), C (cross-repo contract impact), D (suppressions), blast-radius-driven with confidence/severity filters
`feedback.rs`	Usage-feedback capture — slate recording of ranked-search result features, result identities (content-anchored, SHA-256), event store with prune/retention
`learning.rs`	Contrastive weight learning — bounded, decaying learned_weights over signal names and flattened descriptive features, session/observation gates, watermark-driven chunked replay, gated query-path overlay, per-result preferences
`mcp.rs`	MCP server — JSON-RPC 2.0 over stdio, exposes the query tools for AI coding assistants; multi-repo support via optional `repo` parameter and lazy-loaded connections
`budget.rs`	Token budget tracking (~4 chars/token heuristic)

Read the full file on GitHub · 87 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

1mo ago Changed · +7 lines · +378 tokens per session 408cc22e9f55
1mo ago Changed · +13 tokens per session 09662850cd35
2mo ago First seen · 80 lines · 1,429 tokens per session scan A 15a7311b9d5c

Subscribe to this mod's changes

wonk CLAUDE.md is an instructions file published in the GitHub repository etr/wonk (10 stars, last pushed 1mo ago), licensed MIT. It adds 1,820 tokens to every session, about $0.0073 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

LLM Rust cli code-search developer-tools mcp

wonk CLAUDE.md next to 6 instructions from other repositories
Mod	Type	Stars	Last push	Licence	Scan	Tokens	Works with
wonk CLAUDE.mdetr/wonk	Instructions file	10	1mo ago	MIT	A	1,820	Claude Code
vscode buildNext.instructions.mdmicrosoft/vscode	Instructions file	195k	yesterday	MIT	A	9,719	GitHub Copilot
next.js AGENTS.mdvercel/next.js	Instructions file	143k	yesterday	MIT	A	7,461	Codex, OpenCode
langchain AGENTS.mdlangchain-ai/langchain	Instructions file	149k	yesterday	MIT	A	4,680	Codex, OpenCode
vscode oss-third-party-notices.instructions.mdmicrosoft/vscode	Instructions file	195k	yesterday	MIT	A	5,516	GitHub Copilot
vscode copilot-instructions.mdmicrosoft/vscode	Instructions file	195k	yesterday	MIT	A	3,093	GitHub Copilot
deepseek-harness AGENTS.mddeepseek-ai/deepseek-harness	Instructions file	274k	2d ago	MIT	A	4,313	Codex, OpenCode

wonk: Instructions file for Claude Code