ChunkHound

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

<p align="center"> <strong>Local first codebase intelligence</strong> </p>

<p align="center"> <a href="https://github.com/chunkhound/chunkhound/actions/workflows/smoke-tests.yml"><img src="https://github.com/chunkhound/chunkhound/actions/workflows/smoke-tests.yml/badge.svg" alt="Tests"></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>

Your AI assistant searches code but doesn't understand it. ChunkHound researches your codebase—extracting architecture, patterns, and institutional knowledge at any scale. Integrates via MCP.

Features

• cAST Algorithm - Research-backed semantic code chunking
• Multi-Hop Semantic Search - Discovers interconnected code relationships beyond direct matches
• Semantic search - Natural language queries like "find authentication code"
• Regex search - Pattern matching without API keys
• Local-first - Your code stays on your machine
• 30 languages with structured parsing
  • Programming (via Tree-sitter): Python, JavaScript, TypeScript, JSX, TSX, Java, Kotlin, Groovy, C, C++, C#, Go, Rust, Haskell, Swift, Bash, MATLAB, Makefile, Objective-C, PHP, Vue, Svelte, Zig
  • Configuration: JSON, YAML, TOML, HCL, Markdown
  • Text-based (custom parsers): Text files, PDF
• MCP integration - Works with Claude, VS Code, Cursor, Windsurf, Zed, etc
• Real-time indexing - Automatic file watching, smart diffs, seamless branch switching

Documentation

Visit chunkhound.github.io for complete guides:

• Tutorial
• Configuration Guide
• Architecture Deep Dive

Requirements

• Python 3.10+
• uv package manager
• API keys (optional - regex search works without any keys)
  • Embeddings: VoyageAI (recommended) | OpenAI | Local with Ollama
  • LLM (for Code Research): Claude Code CLI or Codex CLI (no API key needed) | Anthropic | OpenAI

Installation

# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install ChunkHound
uv tool install chunkhound

Quick Start

1. Create .chunkhound.json in project root

{
  "embedding": {
    "provider": "voyageai",
    "api_key": "your-voyageai-key"
  },
  "llm": {
    "provider": "claude-code-cli"
  }
}

Note: Use "codex-cli" instead if you prefer Codex. Both work equally well and require no API key.

2. Index your codebase

chunkhound index

For configuration, IDE setup, and advanced usage, see the documentation.

Why ChunkHound?

Approach	Capability	Scale	Maintenance
Keyword Search	Exact matching	Fast	None
Traditional RAG	Semantic search	Scales	Re-index files
Knowledge Graphs	Relationship queries	Expensive	Continuous sync
ChunkHound	Semantic + Regex + Code Research	Automatic	Incremental + realtime

Ideal for:

• Large monorepos with cross-team dependencies
• Security-sensitive codebases (local-only, no cloud)
• Multi-language projects needing consistent search
• Offline/air-gapped development environments

Stop recreating code. Start with deep understanding.

License

MIT