feat(dx): [POC] add ChunkHound for AI-powered code search (CLI-first) by guicheffer · Pull Request #425 · app-vox/vox

guicheffer · 2026-03-16T19:35:19Z

Summary

[POC] Introduces ChunkHound as a local RAG (Retrieval-Augmented Generation) layer for AI-assisted development. Instead of Claude reading files one by one to understand the codebase, it can now query a local semantic index via CLI — getting precise, chunked, line-referenced results in milliseconds.

CLI-first approach:

chunkhound search "query" - semantic search via Bash (transparent, fast)
chunkhound search --regex "pattern" - regex pattern matching
MCP mode still available (.mcp.json.example) for deep research with chunkhound research

What's included:

make install → installs ChunkHound, configures git hooks, indexes codebase
make dev-start/dev-stop → manages Ollama (for semantic search, macOS only)
make start/stop → manages app dev processes
Git hooks (post-checkout, post-merge) keep index fresh automatically
AGENTS.md instructs Claude to use ChunkHound CLI before reading files

How it works

Developer workflow

flowchart TD
    A[make install] -->|installs| B[chunkhound via uv]
    A -->|runs| C[npm install]
    A -->|configures| D[git hooks]
    A -->|runs| E[make index]

    E --> F{macOS + Ollama\nnomic-embed-text?}
    F -->|yes| G[indexes with embeddings\nsemantic + regex]
    F -->|no| H[indexes without embeddings\nregex only]

    I[make dev-start] -->|optional| J[starts Ollama\nfor semantic search]

    K[claude .] -->|reads| L[AGENTS.md]
    L --> M[Claude uses chunkhound CLI\nvia Bash tool]
    M --> N[chunkhound search\nreturns ranked chunks]
    N --> O[Claude reads only\nrelevant files]

Behind the scenes

flowchart LR
    subgraph idx["Indexing  —  make index"]
        A[256 source files] --> B[ChunkHound\nAST chunker]
        B --> C[2850 chunks\nfile · line · type]
        C --> D[DuckDB\n.chunkhound/db]
        C --> E[Ollama\nnomic-embed-text]
        E -->|2765 vectors\ncosine-comparable| D
    end

    subgraph query["Query  —  during Claude session via CLI"]
        F[you ask Claude\nsomething] --> G[Claude runs\nchunkhound search]
        G -->|semantic| H[Ollama embeds query\ncosine similarity]
        G -->|regex| I[pattern match\nagainst chunk text]
        H --> J[top-N chunks\nwith score + file:line]
        I --> J
        J --> K[Claude reads only\nrelevant files]
    end

    D --> H
    D --> I

Why CLI over MCP?

CLI (default)	MCP (optional)
✅ Transparent - commands visible in conversation	⚠️ Hidden - tool calls in background
✅ Fast - no IPC overhead	❌ Slower - process serialization
✅ No locks - single process per command	⚠️ Lock conflicts - long-running server
✅ Flexible - easy flag adjustment	⚠️ Fixed - tool schema constraints
❌ No deep research	✅ `research` tool (uses Claude as LLM)

MCP mode available: Copy .mcp.json.example to .mcp.json and restart Claude Code for deep research capability.

What's included

File	Purpose
`Makefile`	`make install` + `make index` with Ollama lifecycle, `make dev-start`/`dev-stop`
`.chunkhound.json`	Embedding config (Ollama, `nomic-embed-text`, local endpoint)
`.chunkhound.json.example`	Config example
`.mcp.json.example`	Optional MCP config for deep research mode
`.githooks/post-checkout`	Re-indexes on branch switch (background, non-blocking)
`.githooks/post-merge`	Re-indexes after pull/merge (background, non-blocking)
`AGENTS.md`	Instructs Claude to use ChunkHound CLI with decision tree and examples
`README.md`	Developer workflow documentation
`.gitignore`	Excludes `.chunkhound/` (generated) and `.mcp.json` (optional)

Setup (macOS only for semantic search)

Semantic search requires Ollama. Regex search works everywhere with no extra setup.

# One-time setup
make install

# Start Ollama (optional, for semantic search)
make dev-start

# Start app
make start

# Stop app
make stop

# Stop Ollama (optional)
make dev-stop

Developer workflow

# First time
git clone https://github.com/app-vox/vox.git
cd vox
make install           # installs deps + indexes codebase
make dev-start         # optional: starts Ollama for semantic search
make start             # starts app with hot reload

# Daily work
make start             # starts app (runs install if needed)
# ... develop ...
make stop              # stops app processes

# With Claude Code
claude .
# Claude automatically uses "chunkhound search" CLI
# Semantic search works if Ollama is running
# Falls back to regex-only if not

Test plan

Code standards

i18n — N/A (no user-facing strings in the app)
Validation — All linters pass

- Adds ChunkHound indexing to make install with auto-detection of Ollama - Starts/stops Ollama automatically during indexing on macOS - Falls back to regex-only on non-macOS or when Ollama is unavailable - Exposes search_regex and search_semantic as MCP tools for Claude Code - Installs git hooks (post-checkout, post-merge) to keep index fresh - Adds .mcp.json for automatic MCP server configuration - Adds .chunkhound.json with Ollama embedding config (nomic-embed-text)

github-actions · 2026-03-16T19:37:15Z

CI Summary

Check	Status
Typecheck	✅ Passed
Lint	✅ Passed
Lint CSS	✅ Passed
Design Tokens	✅ Passed
Test	✅ Passed
Build	✅ Passed

Run #1065

github-actions · 2026-03-16T19:39:56Z

✅⚠️MegaLinter analysis: Success with warnings

Descriptor	Linter	Files	Errors	Warnings	Elapsed time
✅ JSON	jsonlint	1	0	0	0.13s
✅ JSON	npm-package-json-lint	yes	no	no	3.12s
✅ JSON	prettier	1	0	0	2.33s
✅ JSON	v8r	1	0	0	2.7s
⚠️ MARKDOWN	markdownlint	2	26	0	0.95s
⚠️ MARKDOWN	markdown-table-formatter	2	1	0	0.36s
✅ REPOSITORY	checkov	yes	no	no	27.97s
✅ REPOSITORY	devskim	yes	no	no	2.7s
✅ REPOSITORY	dustilock	yes	no	no	1.45s
✅ REPOSITORY	gitleaks	yes	no	no	1.66s
✅ REPOSITORY	git_diff	yes	no	no	0.26s
✅ REPOSITORY	grype	yes	no	no	47.45s
✅ REPOSITORY	kics	yes	no	no	2.6s
✅ REPOSITORY	kingfisher	yes	no	no	5.47s
✅ REPOSITORY	secretlint	yes	no	no	5.04s
✅ REPOSITORY	syft	yes	no	no	2.41s
✅ REPOSITORY	trivy	yes	no	no	20.1s
✅ REPOSITORY	trivy-sbom	yes	no	no	3.14s
✅ REPOSITORY	trufflehog	yes	no	no	4.92s

Detailed Issues

⚠️ MARKDOWN / markdown-table-formatter - 1 error

2 files contain markdown tables to format:
- AGENTS.md
- README.md

⚠️ MARKDOWN / markdownlint - 26 errors

AGENTS.md:9 error MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
AGENTS.md:171:401 error MD013/line-length Line length [Expected: 400; Actual: 552]
AGENTS.md:179:27 error MD060/table-column-style Table column style [Table pipe does not align with header for style "aligned"]
AGENTS.md:180:23 error MD060/table-column-style Table column style [Table pipe does not align with header for style "aligned"]
AGENTS.md:181:33 error MD060/table-column-style Table column style [Table pipe does not align with header for style "aligned"]
AGENTS.md:182:59 error MD060/table-column-style Table column style [Table pipe does not align with header for style "aligned"]
AGENTS.md:183:42 error MD060/table-column-style Table column style [Table pipe does not align with header for style "aligned"]
AGENTS.md:184:33 error MD060/table-column-style Table column style [Table pipe does not align with header for style "aligned"]
AGENTS.md:185:31 error MD060/table-column-style Table column style [Table pipe does not align with header for style "aligned"]
AGENTS.md:186:31 error MD060/table-column-style Table column style [Table pipe does not align with header for style "aligned"]
AGENTS.md:187:25 error MD060/table-column-style Table column style [Table pipe does not align with header for style "aligned"]
AGENTS.md:188:28 error MD060/table-column-style Table column style [Table pipe does not align with header for style "aligned"]
AGENTS.md:193:17 error MD060/table-column-style Table column style [Table pipe is missing space to the left for style "compact"]
AGENTS.md:193:25 error MD060/table-column-style Table column style [Table pipe is missing space to the left for style "compact"]
AGENTS.md:193:1 error MD060/table-column-style Table column style [Table pipe is missing space to the right for style "compact"]
AGENTS.md:193:17 error MD060/table-column-style Table column style [Table pipe is missing space to the right for style "compact"]
README.md:109:11 error MD060/table-column-style Table column style [Table pipe is missing space to the left for style "compact"]
README.md:109:17 error MD060/table-column-style Table column style [Table pipe is missing space to the left for style "compact"]
README.md:109:44 error MD060/table-column-style Table column style [Table pipe is missing space to the left for style "compact"]
README.md:109:62 error MD060/table-column-style Table column style [Table pipe is missing space to the left for style "compact"]
README.md:109:84 error MD060/table-column-style Table column style [Table pipe is missing space to the left for style "compact"]
README.md:109:1 error MD060/table-column-style Table column style [Table pipe is missing space to the right for style "compact"]
README.md:109:11 error MD060/table-column-style Table column style [Table pipe is missing space to the right for style "compact"]
README.md:109:17 error MD060/table-column-style Table column style [Table pipe is missing space to the right for style "compact"]
README.md:109:44 error MD060/table-column-style Table column style [Table pipe is missing space to the right for style "compact"]
README.md:109:62 error MD060/table-column-style Table column style [Table pipe is missing space to the right for style "compact"]

See detailed reports in MegaLinter artifacts
Set VALIDATE_ALL_CODEBASE: true in mega-linter.yml to validate all sources, not only the diff

Show us your support by starring ⭐ the repository

Changes ChunkHound integration from MCP server to CLI-first workflow for better transparency and flexibility. **What changed:** - ChunkHound now uses CLI (`chunkhound search`) instead of MCP tools by default - AGENTS.md updated with clear decision tree and examples - Makefile: `make dev-start`/`dev-stop` for Ollama, `make start`/`stop` for app - MCP mode still available via `.mcp.json.example` (optional, for deep research) - Simplified config: only embeddings in `.chunkhound.json` (no LLM needed for CLI) **Why CLI over MCP:** - Faster: no MCP server overhead - Transparent: commands visible in conversation - Flexible: easy to adjust flags/filters - No lock conflicts: no competing processes **MCP alternative:** For deep research with `chunkhound research`, copy `.mcp.json.example` to `.mcp.json` and restart Claude Code. MCP mode gives ChunkHound access to Claude Code's LLM for complex synthesis. **Developer workflow:** ```bash make install # setup once (installs deps + indexes) make dev-start # start Ollama (optional, for semantic search) make start # start app (alias: make dev) make stop # stop app processes ``` Co-Authored-By: Claude (global.anthropic.claude-sonnet-4-6[1m]) <noreply@anthropic.com>

guicheffer added enhancement New feature or request feature New feature implementation labels Mar 16, 2026

guicheffer self-assigned this Mar 16, 2026

guicheffer changed the title ~~feat(dx): add ChunkHound for AI-powered code search via MCP~~ feat(dx): [POC] add ChunkHound for AI-powered code search (CLI-first) Mar 18, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(dx): [POC] add ChunkHound for AI-powered code search (CLI-first)#425

feat(dx): [POC] add ChunkHound for AI-powered code search (CLI-first)#425
guicheffer wants to merge 2 commits intomainfrom
poc/chunkhound-exploration

guicheffer commented Mar 16, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 16, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 16, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

guicheffer commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How it works

Developer workflow

Behind the scenes

Why CLI over MCP?

What's included

Setup (macOS only for semantic search)

Developer workflow

Test plan

Code standards

Uh oh!

github-actions bot commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CI Summary

Uh oh!

github-actions bot commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅⚠️MegaLinter analysis: Success with warnings

Detailed Issues

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

guicheffer commented Mar 16, 2026 •

edited

Loading

github-actions bot commented Mar 16, 2026 •

edited

Loading

github-actions bot commented Mar 16, 2026 •

edited

Loading