Metadata-Version: 2.4
Name: chunkhound_native
Version: 6.0.0
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

<p align="center">
    <a href="https://chunkhound.ai">
    <picture>
        <source media="(prefers-color-scheme: dark)"
        srcset="site/public/logo-light.svg">
        <img src="site/public/logo.svg"
        alt="ChunkHound" width="140">
    </picture>
    </a>
</p>

<p align="center">
    <a href="https://chunkhound.ai">
    <picture>
        <source media="(prefers-color-scheme: dark)"
        srcset="site/public/wordmark-text-dark.svg">
        <img src="site/public/wordmark-text.svg"
        alt="ChunkHound" width="300">
    </picture>
    </a>
</p>

<p align="center">
  <strong>Your entire engineering context, deeply understood.</strong>
</p>

<p align="center">
  Open-source codebase intelligence that gives agents and teams cited context across current code, git history, and technical web research.
</p>

<!-- Keep in sync with site/src/components/Hero.astro amplifier line -->
<p align="center">
  Local-first · Dozens of languages & file types · Cited answers · Git history research · Pinpoint web research
</p>

<p align="center">
  <a href="https://github.com/chunkhound/chunkhound/actions/workflows/ci.yml"><img src="https://github.com/chunkhound/chunkhound/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/chunkhound/"><img src="https://img.shields.io/pypi/v/chunkhound.svg" alt="PyPI"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
  <img src="https://img.shields.io/badge/100%25%20AI-Generated-ff69b4.svg" alt="100% AI Generated">
  <a href="https://discord.gg/BAepHEXXnX"><img src="https://img.shields.io/badge/Discord-Join_Community-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
</p>

<p align="center">
  <a href="https://chunkhound.ai/docs/getting-started/">Getting Started</a>
  ·
  <a href="https://chunkhound.ai/docs/configuration/">Configuration</a>
  ·
  <a href="https://chunkhound.ai/docs/cli-reference/">CLI Reference</a>
</p>

---

## 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

