Quickstart

Get ChunkHound running in 5 minutes. This guide will take you from installation to your first semantic search.

Prerequisites

Before installing ChunkHound, ensure you have:

Python 3.10+ - Check with python --version
uv package manager - Modern Python package manager (recommended)

Installation

Step 1: Install uv (if you don’t have it)

macOS and Linux
Windows

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 2: Install ChunkHound

uv tool install chunkhound

That’s it! ChunkHound is now available as a global command.

Verify Installation

chunkhound --version
# Should show: chunkhound x.x.x

Configuration

Choose your embedding provider, then let ChunkHound’s interactive setup wizard handle the configuration.

Best choice for most users - fastest, most accurate, and cost-effective.

Setup steps:

Get an API key from VoyageAI Console
Set environment variable (optional): export VOYAGE_API_KEY="pa-your-key"
Run chunkhound index - the wizard will detect your key or prompt for it

The setup wizard will automatically configure VoyageAI and test the connection.

Good choice if you already have OpenAI credits or prefer their ecosystem.

Setup steps:

Get an API key from OpenAI Platform
Set environment variable (optional): export OPENAI_API_KEY="sk-your-key"
Run chunkhound index - the wizard will detect your key or prompt for it

The setup wizard will help you choose between text-embedding-3-large (quality) or text-embedding-3-small (speed).

Best results - Qwen3 embedding and reranker models outperform all other providers if you have the hardware to run them.

Setup steps:

Install and start Ollama:

# Install Ollama (see https://ollama.ai/)
# Pull the best embedding and reranker models
ollama pull dengcao/Qwen3-Embedding-8B:Q5_K_M
ollama pull dengcao/Qwen3-Reranker-4B:Q5_K_M
ollama serve  # Keep this running

Run chunkhound index - the wizard will auto-detect Ollama and available models

The setup wizard will automatically configure the embedding model. The reranker model enhances search accuracy when used with a compatible reranking service.

Advanced: Custom Configuration

For CI/CD pipelines, custom providers, or when the setup wizard doesn’t detect your configuration, create a .chunkhound.json file manually:

{
  "embedding": {
    "provider": "voyageai",
    "api_key": "pa-your-voyage-key"
  }
}

{
  "embedding": {
    "provider": "openai",
    "api_key": "sk-your-openai-key"
  }
}

{
  "embedding": {
    "provider": "openai",
    "base_url": "http://localhost:11434/v1",
    "model": "dengcao/Qwen3-Embedding-8B:Q5_K_M",
    "api_key": "dummy-key",
    "rerank_model": "dengcao/Qwen3-Reranker-4B:Q5_K_M",
    "rerank_url": "http://localhost:8000/rerank"
  }
}

Note: Reranking requires a separate service (like vLLM) running the reranker model.

Index Your Codebase

Navigate to your project and create the searchable index:

cd /path/to/your/project
chunkhound index

You’ll see output like:

Scanning 3,847 files...
Processing 2,983 Python files, 864 JavaScript files...
✓ 62,419 chunks indexed
✓ Embeddings: 62,419 generated
⏱️  Time: 8m 42s

Respects .gitignore

ChunkHound automatically ignores files in your .gitignore

Incremental Updates

Re-running chunkhound index only processes changed files

29 languages

Supports Python, JavaScript, TypeScript, Go, Rust, Java, C++, and more

Connect to Your AI Assistant

Configure ChunkHound as an MCP server so your AI assistant can search your code:

Easiest setup - Claude Code handles everything automatically:

# Run this in your project directory
claude mcp add ChunkHound chunkhound mcp

That’s it! Your AI assistant can now search your codebase.

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "chunkhound": {
      "type": "stdio",
      "command": "chunkhound",
      "args": ["mcp", "/path/to/your/project"]
    }
  }
}

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "chunkhound": {
      "command": "chunkhound",
      "args": ["mcp", "/path/to/your/project"]
    }
  }
}

Test Your Setup

Quick Verification

Try asking your AI assistant:

“Can you search for any authentication functions in this codebase?”

Or:

“Find all the database models and show me their relationships”

If ChunkHound is working, your AI will be able to find and understand your code patterns instantly.

Manual Testing (Optional)

You can also test ChunkHound directly from the command line:

chunkhound search "class.*Authentication"

chunkhound search "user login and password validation"

You’re Ready!

🎉 ChunkHound is now connected to your AI assistant. Your AI can:

Find existing code before writing new functions
Understand your architecture before making changes
Follow your patterns and coding style
Cross-reference code with documentation

Next Steps: Enable Code Research (Optional)

Want even deeper insights? ChunkHound’s Code Research feature provides comprehensive architectural analysis by exploring your codebase semantically.

What Code Research adds:

Map complete flows - “How does authentication work?” → comprehensive report with all components
Find architectural patterns - Discover rate limiting, caching, error handling strategies
Prevent duplicate work - Find existing implementations before building new ones

Quick setup:

Claude Code CLI or Codex CLI - FREE with your existing subscription (recommended)
OpenAI or Ollama - Alternative options for users without CLI subscriptions

See the Code Research Setup guide for detailed configuration instructions.

Quick example:

# After LLM configuration
chunkhound research "how does rate limiting work?"

Or via your AI assistant:

“Research our rate limiting implementation”