ChunkHound: Cited Codebase Context for Agents, Built on DuckDB and Tree-sitter

The context gap ChunkHound targets

The README opens with a blunt claim: AI writes code blind. The argument is that an agent can produce a plausible function while missing how behaviour flows across files, what changed on a branch, and which external constraints apply. The same gap shows up for humans reviewing a large pull request or drafting release notes. ChunkHound's answer is to assemble cited context before anyone edits, reviews, debugs, or explains software. The project names four workflows: research before editing, understanding large PRs and releases, tracing bugs and incidents, and reconciling code with external docs. That list is narrower than a general chat-with-your-repo tool, and the narrowness is the point. Each workflow maps to a specific query shape in the CLI, which is covered below. The audience is engineering teams already using coding agents and reviewers who need implementation-backed explanation rather than guesses. It is not aimed at someone who wants a hosted search box over a monorepo.

Tree-sitter chunks, DuckDB storage, provider-backed retrieval

The repository topics name the moving parts: tree-sitter, duckdb, mcp-server, rag, semantic-search. The README confirms the language coverage comes via Tree-sitter and lists Python, JavaScript, TypeScript, Java, Go, Rust, and C/C++ among dozens of supported languages and file types. Parsing with Tree-sitter means chunks follow syntax structure rather than fixed character windows, which is what makes a query like "JWT refresh token validation" return a function rather than a paragraph of surrounding comments. Indexing is described as local-first, so the parse and the store stay on your machine; the README explicitly offers local providers for zero-code-egress setups. DuckDB is the storage layer implied by the topic tags, though the README does not document the schema or table layout, so treat any claim about how chunks are keyed as unverified. Retrieval is layered: regex search needs nothing, semantic search needs an embedding provider, and deep research needs an LLM plus an embedding provider with reranking support. Web research reuses the same stack. That layering is the most useful thing to understand before installing, because it determines which commands will actually work on day one.

Install and first index

The install path is a single uv command:

uv tool install chunkhound

The prerequisites are Python 3.10 or newer and uv itself, installed via the documented shell script. Then two commands get you to a grounded answer:

chunkhound index . chunkhound research "How does authentication work?"

The README is explicit that regex search works without any API keys, semantic search requires an embedding provider, and deep research requires an LLM provider plus an embedding provider with reranking support. So `chunkhound index .` followed by a plain search is the zero-key path. For anything beyond that, create `.chunkhound.json` in the project root. The README gives this example:

{ "embedding": { "provider": "voyageai", "api_key": "your-key" }, "llm": { "provider": "claude-code-cli" } }

Note the asymmetry in the provider list. Embeddings come from VoyageAI (recommended in the README), OpenAI, or Ollama for local. LLMs come from Claude Code CLI or Codex CLI with no key needed, or from Anthropic, OpenAI, or Grok. The CLI-first LLM options are the cheapest way to try deep research, since they reuse a subscription you may already have. The README also points to a getting-started page for editor integration and advanced configuration, and the topic list includes mcp-server, so an MCP integration exists, but the supplied material does not document its configuration keys.

Git history is the differentiated query surface

Most code search tools index the working tree. ChunkHound also searches code changes across git history, and the README's examples show what that unlocks. `chunkhound search "authentication changes" --last-n 20` scopes a query to the last twenty commits. `chunkhound search "database migration" --commit-hash abc1234` pins a query to one commit. `chunkhound research "Draft changelog bullets for billing since v2.4" --commit-range v2.4..HEAD` turns a tag range into draft release notes. `chunkhound research "Why did auth session handling change on each side?" --commit-range main..feature/auth` is aimed at merge conflicts, where the question is genuinely about two divergent histories rather than one current state. The flags --last-n, --commit-hash, and --commit-range are the concrete interface here. This is a different retrieval problem from semantic search over a snapshot, and it is the part of the tool that a plain vector store over source files does not replicate. If your team's pain is large PRs and release notes rather than finding a function by description, this is the feature to evaluate first.

The provider stack is the real adoption cost

ChunkHound is MIT-licensed and installs as a Python tool, so the software itself is free. The cost sits in the provider stack. Deep research needs an embedding provider with reranking support and an LLM. That means either API spend or a local model setup. Ollama is listed for embeddings, which supports the zero-code-egress path, but the README does not state which Ollama models satisfy the reranking requirement, so that combination needs testing before you rely on it. The recommended embedding provider is VoyageAI, which is a paid third-party service, and using it means source code leaves your machine at index time. The README frames local-first indexing as keeping search and indexing under your control, and that framing is accurate for the storage layer, but it does not mean the whole pipeline is offline unless you choose local providers for every stage. Read the provider matrix before you assume the privacy story applies to your configuration. There is also a maintenance signal worth noting: the README carries a 100% AI Generated badge, and the release cadence visible in the supplied material shows three releases between May and July 2026, with the most recent push in September 2026. Fast movement on a young tool cuts both ways.

Where ChunkHound is the wrong tool

Three cases stand out. First, if you need exact string matching over a known codebase, you already have ripgrep, and the README concedes that regex search works without providers. Adding an index and a provider stack buys you nothing for that job. Second, if your repository is small enough to read in an editor session, the indexing step and the provider configuration are overhead relative to just opening the files. Third, and more subtly, deep research depends on an embedding provider with reranking support plus an LLM, so the answer quality is a function of models you choose, not of ChunkHound alone. Two teams on the same repository with different providers will get different results. The supplied material gives no evaluation of answer accuracy, no benchmark, and no failure-rate data, so there is no basis for claiming the citations are always correct. Citations make answers checkable; they do not make them right. Treat every research output as a starting point that a human verifies against the cited source, which is presumably the intent anyway. One more gap: the README describes Autodoc as generating shareable docs from code-backed research, but does not document its command surface in the supplied text.

How it differs from a general-purpose code RAG stack

The obvious alternative is assembling your own pipeline: Tree-sitter for parsing, a vector database for embeddings, and an LLM with a retrieval prompt. That approach is well understood and gives you full control over chunking strategy, embedding model, and reranking. The difference is scope. A hand-rolled stack typically indexes the current working tree and answers questions about it. ChunkHound additionally treats git history as a first-class query dimension through --last-n, --commit-hash, and --commit-range, and it folds web research into the same command surface via `chunkhound websearch`, as shown in the Stripe webhook retry example. Replicating that means building commit-range indexing, a web retrieval path, and a citation format that ties both back to local code. That is a real amount of work, and it is the honest argument for using ChunkHound rather than a generic stack. The counter-argument is transparency: with a hand-rolled pipeline you know exactly which chunks were embedded and how reranking is applied, whereas the supplied material does not document ChunkHound's chunking or reranking internals. If you need to audit retrieval behaviour, the custom route is more inspectable.

Licence, upgrades, and what to verify before adopting

The licence is MIT, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are preserved. That is a permissive arrangement and it is the same licence your own dependencies likely use. It does not, however, govern the providers you connect: VoyageAI, Anthropic, OpenAI, and Grok each have their own terms, and sending code to them at index time is a separate decision from the MIT grant on the tool. The supplied material does not state whether ChunkHound's index format is stable across versions, and with three releases between May and July 2026, an index written by one version may not be readable by the next. The practical implication is that `chunkhound index .` may need to be re-run after an upgrade, and on a large repository that is a real time cost. Verify that before you build automation around a stale index. Also verify which Ollama models satisfy the reranking requirement if you are pursuing the local-only path, since the README does not name any. And check the getting-started page for the MCP server configuration if agent integration is your goal, because the supplied README does not document those keys.

Editorial conclusion

Adopt ChunkHound if you want cited, local-first context for a repository and you are willing to supply an embedding provider (VoyageAI, OpenAI, or Ollama) plus an LLM (Claude Code CLI, Codex CLI, Anthropic, OpenAI, or Grok). Do not adopt it if regex-only search is all you need, since that path already works with no keys at all. Before committing, verify three things: that the Tree-sitter coverage for your language produces useful chunks, that your chosen embedding provider supports the reranking the README says deep research requires, and that indexing your repository fits your time budget. Start with `chunkhound index .` and one `chunkhound research` question before wiring it into anything else.

Official sources

1. chunkhound/chunkhound on GitHub
2. License: MIT
3. Project website
4. README
5. Releases