ChunkHound Tutorial

Understanding ChunkHound

ChunkHound transforms your codebase into a searchable knowledge base for AI assistants. It provides two powerful search methods:

Semantic search - Natural language queries that understand meaning and context
Regex search - Precise pattern matching for exact code structures

The Index Command - Your Knowledge Base

Why Index Separately?

For large codebases, indexing is a separate step that provides significant benefits:

Performance

Index once, search many times Initial indexing takes time, but subsequent searches are instant

Smart Diffing

Only processes changed files Preserves embeddings for unchanged code

Fix Command

Repairs inconsistencies chunkhound index detects and fixes database drift

Enterprise Ready

Battle-tested scaling Used on codebases with 75k+ LOC

Example: Initial Index

$ chunkhound index /path/to/large-codebase
Scanning 10,000 files...
Processing 8,234 Python files, 1,766 TypeScript files...
✓ 45,000 chunks indexed
✓ Embeddings: 45,000 generated
⏱️  Time: 34m 30s

Example: Incremental Update

$ chunkhound index  # After editing 3 files
Detecting changes...
✓ 3 files modified, 8,234 files unchanged
✓ 150 chunks updated
✓ Embeddings: 150 generated, 45,000 reused
⏱️  Time: 18 seconds

Choosing Your Server Mode

Use Case	Mode	Command
Personal development	stdio	`chunkhound mcp`
Team/production use	HTTP	`chunkhound mcp --http`

stdio Mode - Let Your IDE Handle It

Your IDE starts/stops the server automatically. The index stays in memory for instant searches. Perfect for personal development with a single IDE.

chunkhound mcp /path/to/project

HTTP Mode - Shared Server

You start the server once, multiple IDEs can connect. Ideal for teams or when switching between multiple git worktrees.

chunkhound mcp /path/to/project --http --port 8000
# Connect IDEs to http://localhost:8000

Production Usage

ChunkHound is production-ready and actively tested. For detailed configuration options, see the Configuration Guide:

Enterprise Scale

75k+ LOC indexed

Proven on massive monorepos with complex dependency graphs

Real-World Testing

Enterprise Validated

Tested on multiple enterprise projects and GoatDB’s TypeScript codebase. See Configuration for production setup.

Multi-Language Support

20+ Languages

Python, TypeScript, Go, Rust, Java, C++, and more via Tree-sitter

AI-Built Architecture

100% AI-Generated

Entire codebase written by AI agents, using cAST algorithm for intelligent code chunking

Next Steps

Now that you understand ChunkHound’s core concepts:

Start using it - Index your codebase and connect your AI assistant
Advanced configuration - Advanced configuration options
Technical deep dive - Understand the architecture