ChunkHound

A local-first semantic code search tool with vector and regex capabilities, designed for AI assistants.

Documentation

Your entire engineering context, deeply understood.

Open-source codebase intelligence that gives agents and teams cited context across current code, git history, and technical web research.

Local-first · Dozens of languages & file types · Cited answers · Git history research · Pinpoint web research

Getting Started · Configuration · CLI Reference

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 (recommended) | OpenAI | Ollama (local)
- LLM: Claude Code CLI or Codex CLI (no key needed) | Anthropic | OpenAI | Grok

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