Metadata-Version: 2.5
Name: chunkhound
Version: 6.0.0a1
Summary: Local-first codebase intelligence for AI assistants via MCP
Project-URL: Homepage, https://github.com/chunkhound/chunkhound
Project-URL: Repository, https://github.com/chunkhound/chunkhound
Project-URL: Issues, https://github.com/chunkhound/chunkhound/issues
Project-URL: Documentation, https://chunkhound.ai
Project-URL: Changelog, https://github.com/chunkhound/chunkhound/releases
Author: Ofri Wolfus
License-File: LICENSE
Keywords: AI agents,CAST algorithm,MCP,code search,semantic search,vector search
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: <3.15,>=3.10
Requires-Dist: aiohttp>=3.12.15
Requires-Dist: anthropic<1.0.0,>=0.96.0
Requires-Dist: chunkhound-native>=5.2.0
Requires-Dist: duckdb==1.5.4
Requires-Dist: google-genai>=1.51.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: lancedb>=0.25.3
Requires-Dist: lark>=1.1.0
Requires-Dist: loguru>=0.6.0
Requires-Dist: markdownify>=1.0
Requires-Dist: mcp>=1.16.0
Requires-Dist: msgpack>=1.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: openai>=1.0.0
Requires-Dist: packaging>=21.0
Requires-Dist: pandas>=2.3.0
Requires-Dist: pathspec>=0.12.1
Requires-Dist: psutil>=5.8.0
Requires-Dist: pyarrow<24.0.0,>=23.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.12.0
Requires-Dist: pygit2>=1.12.0
Requires-Dist: pylance>=0.31.0
Requires-Dist: pymupdf>=1.27.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rapidyaml>=0.11.0
Requires-Dist: readchar>=4.2.1
Requires-Dist: rich>=13.0.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: starlette>=0.48.0
Requires-Dist: tiktoken>=0.9.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: tree-sitter-bash>=0.25.0
Requires-Dist: tree-sitter-c-sharp>=0.23.1
Requires-Dist: tree-sitter-c>=0.24.1
Requires-Dist: tree-sitter-cpp>=0.23.4
Requires-Dist: tree-sitter-css>=0.25.0
Requires-Dist: tree-sitter-elixir>=0.3.4
Requires-Dist: tree-sitter-go>=0.25.0
Requires-Dist: tree-sitter-groovy>=0.1.2
Requires-Dist: tree-sitter-haskell>=0.23.1
Requires-Dist: tree-sitter-html>=0.23.2
Requires-Dist: tree-sitter-java>=0.23.5
Requires-Dist: tree-sitter-javascript>=0.25.0
Requires-Dist: tree-sitter-json>=0.24.8
Requires-Dist: tree-sitter-kotlin>=1.1.0
Requires-Dist: tree-sitter-language-pack<1.0.0,>=0.7.3
Requires-Dist: tree-sitter-lua>=0.4.0
Requires-Dist: tree-sitter-make>=0.1.0
Requires-Dist: tree-sitter-markdown>=0.5.1
Requires-Dist: tree-sitter-php>=0.24.0
Requires-Dist: tree-sitter-python>=0.25.0
Requires-Dist: tree-sitter-rust>=0.24.0
Requires-Dist: tree-sitter-sql>=0.3.0
Requires-Dist: tree-sitter-toml>=0.7.0
Requires-Dist: tree-sitter-typescript>=0.23.2
Requires-Dist: tree-sitter-zig>=1.1.0
Requires-Dist: tree-sitter>=0.25.0
Requires-Dist: uvicorn>=0.37.0
Requires-Dist: voyageai>=0.2.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: xxhash>=3.0.0
Requires-Dist: zendriver==0.15.3
Requires-Dist: zstandard>=0.23.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-rerunfailures>=13.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-rerunfailures>=13.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.1.0; extra == 'test'
Requires-Dist: pytest>=7.4.0; extra == 'test'
Description-Content-Type: text/markdown

<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
