Get ChunkHound running

Install the CLI, pick your stack, index your code. Three commands, two minutes.

Install

# Skip if you already have uv
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install chunkhound

# Skip if you already have uv
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install chunkhound

Verify the install resolved on your shell:

chunkhound --version

Choose your editor, embedding provider, and LLM. Copy the three commands below and run them from your project root.

For local or proxied OpenAI-compatible LLM backends like Ollama or vLLM, keep the generated llm.model value in place. ChunkHound requires an explicit model name for custom base_url endpoints, including per-role overrides that resolve to OpenAI-compatible providers.

Pick your stack

+ any MCP-compatible

+ any OpenAI-compatible

echo .chunkhound.json >> .gitignore
cat > .chunkhound.json <<'CHUNKHOUND_EOF'
{
  "embedding": {
    "provider": "voyageai",                // embedding service identifier
    "model": "voyage-3.5",                 // model name
    "api_key": "<YOUR_VOYAGE_API_KEY>"     // replace with your API key
  },
  "llm": {
    "provider": "anthropic",               // which provider runs `chunkhound research`
    "api_key": "<YOUR_ANTHROPIC_API_KEY>"  // replace with your API key
  }
}
CHUNKHOUND_EOF

mkdir -p .cursor
cat > .cursor/mcp.json <<'CHUNKHOUND_EOF'
{
  "mcpServers": {
    "ChunkHound": {
      "command": "chunkhound",
      "args": [
        "mcp"
      ]
    }
  }
}
CHUNKHOUND_EOF

.chunkhound.json holds your API keys

The first command adds it to .gitignore so you don't commit secrets. Replace the <YOUR_*_API_KEY> placeholders with real keys before running. Local OpenAI-compatible backends still need an explicit model. Need Azure OpenAI, a self-hosted endpoint, or a proxy?


                        {"provider":"voyageai","model":"voyage-3.5","api_key":"<YOUR_VOYAGE_API_KEY>"}


                        {"provider":"openai","model":"text-embedding-3-small","api_key":"<YOUR_OPENAI_API_KEY>"}


                        {"provider":"openai","model":"qwen3-embedding","base_url":"http://localhost:11434/v1","rerank_model":"qwen3-reranker","rerank_format":"cohere"}


                        {"provider":"openai","model":"Qwen/Qwen3-Embedding-0.6B","base_url":"http://localhost:8000/v1","rerank_model":"Qwen/Qwen3-Reranker-0.6B","rerank_format":"cohere"}


                        {"provider":"anthropic","api_key":"<YOUR_ANTHROPIC_API_KEY>"}


                        {"provider":"openai","api_key":"<YOUR_OPENAI_API_KEY>"}


                        {"provider":"codex-cli"}


                        {"provider":"claude-code-cli"}


                        {"provider":"gemini","api_key":"<YOUR_GEMINI_API_KEY>"}


                        {"provider":"grok","api_key":"<YOUR_XAI_API_KEY>"}


                        {"provider":"openai","model":"qwen3-coder:30b","base_url":"http://localhost:11434/v1"}


                        {"provider":"openai","model":"Qwen/Qwen3-Coder-30B-A3B-Instruct","base_url":"http://localhost:8000/v1"}


                        {"provider":"opencode-cli"}

mkdir -p .cursor
cat > .cursor/mcp.json <<'CHUNKHOUND_EOF'
{
  "mcpServers": {
    "ChunkHound": {
      "command": "chunkhound",
      "args": [
        "mcp"
      ]
    }
  }
}
CHUNKHOUND_EOF

claude mcp add ChunkHound -- chunkhound mcp

mkdir -p .vscode
cat > .vscode/mcp.json <<'CHUNKHOUND_EOF'
{
  "servers": {
    "ChunkHound": {
      "type": "stdio",
      "command": "chunkhound",
      "args": [
        "mcp"
      ]
    }
  }
}
CHUNKHOUND_EOF

cat > opencode.json <<'CHUNKHOUND_EOF'
{
  "mcp": {
    "ChunkHound": {
      "type": "local",
      "command": [
        "chunkhound",
        "mcp"
      ]
    }
  }
}
CHUNKHOUND_EOF

codex mcp add ChunkHound -- chunkhound mcp

mkdir -p ~/.codeium/windsurf
cat > ~/.codeium/windsurf/mcp_config.json <<'CHUNKHOUND_EOF'
{
  "mcpServers": {
    "ChunkHound": {
      "command": "chunkhound",
      "args": [
        "mcp"
      ]
    }
  }
}
CHUNKHOUND_EOF

mkdir -p .roo
cat > .roo/mcp.json <<'CHUNKHOUND_EOF'
{
  "mcpServers": {
    "ChunkHound": {
      "command": "chunkhound",
      "args": [
        "mcp"
      ]
    }
  }
}
CHUNKHOUND_EOF

cat > settings.json <<'CHUNKHOUND_EOF'
{
  "context_servers": {
    "chunkhound": {
      "command": "chunkhound",
      "args": [
        "mcp"
      ]
    }
  }
}
CHUNKHOUND_EOF

Index and verify

Run these four commands in order. Each one verifies a different layer of the stack: database, regex search, embeddings, then LLM.

1. Index the project

chunkhound index .

Expected output

Indexed 412 files, 6,841 chunks
Database: .chunkhound/db/chunks.db

File and chunk counts will differ; the Indexed prefix and the .chunkhound/db/chunks.db path are stable.

2. Confirm regex search

chunkhound search --regex "import"

Expected output

Found 1,284 matches
src/main.py:1: import os

A match count and at least one truncated result line. Zero matches with no error usually means the --db path is wrong — see Configuration for the canonical database path rules.

3. Confirm semantic search

chunkhound search "authentication flow"

Expected output

score   file:line                          snippet
0.81    src/auth/session.py:42             def login(...)
0.74    src/auth/middleware.py:18          class AuthMiddleware

A ranked list with a score column. If regex worked but this didn't, your embedding provider credentials are missing or wrong.

4. Confirm research

chunkhound research "How does authentication work?"

Expected output

Authentication is handled by src/auth/session.py, which...

A short natural-language answer that cites real files. If search worked but this didn't, your LLM provider credentials are missing or wrong, or the LLM CLI you picked isn't on PATH.

Use it from your agent

Your agent already has ChunkHound — the editor command from Pick your stack registered it as an MCP tool. The biggest unlock is calling code_research before writing code, not after.

code_research synthesises a cited markdown report covering architecture, key locations, and cross-file flows. One call usually replaces 5–10 manual searches.

Example prompts

The pattern is one line. Paste it into your editor chat with a topic of your own:

Use chunkhound research to ...

A few directions to start with:

explain how authentication works end to end, with file:line citations
map every caller of the email subsystem and the helpers they share
trace the login flow from form submit to Set-Cookie
find every file-upload handler and compare their size limits, MIME validation, and storage targets
diagnose duplicate webhook deliveries by tracing the handler outward through retries, queues, and idempotency keys

Need just a file or symbol? Ask the agent to use chunkhound search instead — it's faster and skips the LLM.

MCP integration

ChunkHound exposes code_research, search, and a handful of other tools as an MCP server; your editor connected to it via the command in Pick your stack.

Where to next

Configuration

Full config shape, provider details, indexing controls, and environment-variable overrides.

CLI Reference

Every command, every flag, and the syntax for advanced indexing and research workflows.

Stuck? Ask in Discord or open an issue.