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.

wonk CLAUDE.md — Instructions file by etr

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add instructions/etr/wonk/claude-md

Clone the repo

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

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

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

Security scan A 0 findings. Scan, not verified.

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	$0.01429	$0.01429
Opus 5	$0.00714	$0.00714
Sonnet 5	$0.00286	$0.00286
Haiku 4.5	$0.00143	$0.00143

Measured 2d ago against content hash 15a7311b9d5c, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, 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 2d 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 · 80 lines

How it starts

The opening of the file, as written. The whole thing — 80 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; embedding build pipeline (chunking → Ollama 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`	Ollama API client, symbol chunking engine, and vector storage — sync HTTP client for embedding generation, context-rich text chunk formatting for `nomic-embed-text`, BLOB storage/retrieval with bytemuck zero-copy deserialization
`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
`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
`mcp.rs`	MCP server — JSON-RPC 2.0 over stdio, exposes 18 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 · 80 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.

2d 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,429 tokens to every session, about $0.0071 per session on Opus 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.

Data and AI Databases LLM Testing cli code-search developer-tools mcp rust

codesage AGENTS.md

Instructions for iliaal/codesage, covering codesage, build, sanity check before pushing, crate map and search pipeline.

iliaal/codesage · 6,686 tokens

codesage CLAUDE.md

Instructions for iliaal/codesage, a project described as: Code intelligence engine for AI coding agents. Structural graph queries plus semantic search, exposed via CLI and MCP.

iliaal/codesage · 3 tokens

agentgateway copilot-instructions.md

Copilot instructions for agentgateway/agentgateway: Do not check for, speculate about, or report compilation errors during code review. Compilation diagnostics from review are frequently incorrect; rely on CI to detect and report compilation failures.

agentgateway/agentgateway · 41 tokens

wonk CLAUDE.md