Requirements
- Python 3.10+
- uv — install via
curl -LsSf https://astral.sh/uv/install.sh | sh
- API keys (optional — regex search works without any):
AI writes code blind
Agents can generate code, but they still miss the context that makes software safe to change: how behavior flows across files, what changed across a branch or release, and which external constraints matter.
Reviewers, support, and product teams hit the same wall when large PRs, merge conflicts, bugs, and release notes need implementation-backed explanation instead of guesses.
ChunkHound turns current code, git history, and technical web research into cited context before anyone edits, reviews, debugs, or explains software.
Deep understanding for four context-heavy jobs
ChunkHound applies codebase understanding to the workflows where missing context hurts most.
Research before editing
Give coding agents grounded architecture context, relevant files, recent changes, and external constraints before they write code.
Understand large PRs and releases
Turn branch diffs, commit ranges, tags, and specific commits into cited engineering briefs for review, release notes, and changelog drafts.
Trace bugs and incidents
Turn symptoms, stack traces, and customer reports into likely code paths, recent changes, and external constraints.
Reconcile code with external docs
Pinpoint the technical docs, APIs, issues, and articles your implementation depends on, then connect that external evidence to local code research.
What you can ask
Ground an agent before edits
chunkhound research "How does authentication work?"
chunkhound search "JWT refresh token validation"
chunkhound research "What changed in auth recently?" --last-n 20
Understand a large PR or release
chunkhound research "Summarize the behavior changes on this branch for reviewers" --commit-range main..HEAD
chunkhound research "Draft changelog bullets for billing since v2.4" --commit-range v2.4..HEAD
chunkhound search "database migration" --commit-hash abc1234
Get context before resolving conflicts
chunkhound research "Why did auth session handling change on each side?" --commit-range main..feature/auth
chunkhound search "session refresh conflict" --last-n 50
Trace a bug with external constraints
chunkhound research "why would webhook retries fail?"
chunkhound research "what changed in webhook handling this week?" --last-n 30
chunkhound websearch "Stripe webhook retry schedule"
Explain product behavior
chunkhound research "What happens when a user cancels a subscription?"
chunkhound research "What changed in billing since v2.4?" --commit-range v2.4..HEAD
What powers deep understanding
- Semantic code search — find relevant code by meaning, not only exact text
- Cited code research — explain behavior across files with source citations
- Git history research — ask by last N commits, commit hash, tag, branch, or range to understand large PRs and releases
- Pinpoint web research — bring cited external docs, APIs, issues, and articles into the same workflow as local code research
- Autodoc — generate shareable docs from code-backed research
- Local-first indexing — keep code search and indexing under your control
- Python, JavaScript, TypeScript, Java, Go, Rust, C/C++, and more via Tree-sitter
Install
uv tool install chunkhound
Try it
chunkhound index .
chunkhound research "How does authentication work?"
Index once, ask a real architecture question, and get a grounded answer with citations. Regex search works without providers. Semantic search requires an embedding provider. Deep research requires an LLM provider and an embedding provider with reranking support; web research uses the same provider stack. Choose local providers for zero-code-egress setups.
For a full configurable setup, create .chunkhound.json in your project root:
{
"embedding": { "provider": "voyageai", "api_key": "your-key" },
"llm": { "provider": "claude-code-cli" }
}
For editor integration, all provider options, and advanced configuration:
→ chunkhound.ai/docs/getting-started
Search git history
In addition to searching your indexed codebase, ChunkHound can search
code changes across git history — useful for understanding what changed
in a PR, a release, or since a specific commit.
# Last N commits
chunkhound search "authentication changes" --last-n 20
# Changes introduced by a specific commit
chunkhound search "database migration" --commit-hash abc1234
# Custom git range
chunkhound search "API changes" --commit-range v2.0..HEAD
# Deep research over recent changes
chunkhound research "what changed in the auth module?" --last-n 50
--vector-source controls scope: diff (default, changed code only),
both (merges diff + DB), db (ignore diff).
Good fit
ChunkHound is especially useful for:
- large repos and monorepos
- multi-language codebases
- legacy systems
- local-only or security-sensitive environments
- engineering teams that want agents, support, and product questions grounded in the same code index
Community
ChunkHound is MIT licensed, open source, and community built.
License
MIT
