---
## Requirements
- **Python 3.10+**
- **uv** — install via `curl -LsSf https://astral.sh/uv/install.sh | sh`
- **API keys** (optional — regex search works without any):
- Embeddings: [VoyageAI](https://dash.voyageai.com/) (recommended) | [OpenAI](https://platform.openai.com/api-keys) | [Ollama](https://ollama.ai/) (local)
- LLM: Claude Code CLI or Codex CLI (no key needed) | [Anthropic](https://console.anthropic.com/) | [OpenAI](https://platform.openai.com/api-keys) | [Grok](https://console.x.ai)
---
## 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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
uv tool install chunkhound
```
## Try it
```bash
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:
```json
{
"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](https://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.
```bash
# 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.
- [Docs](https://chunkhound.ai/docs/getting-started/)
- [Contributing](https://chunkhound.ai/docs/contributing/)
- [Discord](https://discord.gg/BAepHEXXnX)
- [Issues](https://github.com/chunkhound/chunkhound/issues)
## License
MIT
