ChunkHound Codebase Intelligence
Local-first, cited research across source code, Git history, and technical web sources.
The project documents local-first indexing and offers local providers such as Ollama; CI defaults to contents: read and elevates permissions only for scoped deployment or deprecation jobs, so least privilege is reasonably addressed. Full credit is withheld because the supplied source does not define runtime filesystem scope, network controls, or sandbox boundaries. CLI operations are explicitly user-invoked and release deprecation requires approval through a maintainers environment, but there is no evidence of per-operation confirmation before indexing, overwriting generated assets, or making remote requests. The README distinguishes local search, semantic search, deep research, and web research provider requirements and mentions a zero-code-egress configuration; it does not disclose the exact fields sent to remote providers, retention behavior, or telemetry. API-key requirements are stated, but the example places a plaintext key in a project-root .chunkhound.json and no secret redaction, permission validation, or log filtering is shown. Dependency declarations include some exact bounds and compatibility explanations, and CI installs from a lock; deductions apply for the very large dependency surface, widespread lower-bound-only constraints, drift between requirements.txt and pyproject.toml, and absence of vulnerability-scanning evidence. Indexing, web research, site generation, and release editing effects are broadly identifiable, and an assets-only test demonstrates preservation of some user files; there is no general preview, backup, or undo facility. Source attribution earns full credit because cited answers are a core stated output and repository, package, license, and author attribution are explicit. Unknown enterprise publisher identity is treated only as unknown and is not used to infer other quality.
CI covers Linux, macOS, Windows, Python, Rust, site builds, packaging validation, and stable manifest hashing. Self-consistency is nevertheless reduced by substantial version-range differences between README-adjacent manifests, pyproject.toml, and requirements.txt for packages such as tree-sitter, mcp, pydantic, rich, psutil, voyageai, and language parsers; tests/__init__.py also declares 1.1.0 alongside dynamic package versioning and Rust 0.1.0. Dependency acquisition paths, locked CI installation, and DuckDB/Watchman artifact validation adequately support ordinary availability, but the large remote dependency set and Linux/Windows-only packaged Watchman matrix prevent full credit. Workflows emit clear failures for missing wheels and persistent test failures, and the deprecation workflow candidly identifies a false-success PyPI yank design; however, no implementation evidence shows user-facing CLI errors for provider, indexing, or network failures, so failure-message support remains thin.
The README thoroughly identifies audiences and scenarios including pre-edit research, PR and release review, conflict resolution, incident tracing, and product explanation; autodoc tests also substantiate technical, balanced, and end-user audiences. Capability boundaries distinguish regex, semantic, deep, and web research and state their provider requirements, while diff, db, and both scopes are described; deductions apply because indexing exclusions, scale limits, exact parser coverage, and web-research constraints are not comprehensively presented. Trigger precision earns full credit because index, search, research, websearch, and autodoc are explicit commands with explicit range and scope flags, with no evidence of ambiguous automatic triggering. Environment fit is good across Python 3.10–3.14, many languages, Linux and Windows, with macOS exercised in CI; it is not complete because packaged Watchman support lists only Linux x86_64 and Windows x86_64, Rust 1.82 is required for native builds, and advanced functions depend on particular provider capabilities.
The README has clear sections for requirements, scenarios, capabilities, installation, trial use, history search, fit, and community, earning full information-architecture credit. Installation notes specify Python, uv, optional credentials, commands, and a configuration example, also earning full credit. Project and CLI names are consistent, but naming/version stability is reduced by concurrent test-package 1.1.0, Rust 0.1.0, and VCS-derived Python versions, plus manifest drift. Examples cover all major workflows and important flags; although no dedicated FAQ is supplied, ordinary usage is well illustrated. Limitations are evidenced through the Alpha classifier, provider requirements, packaged-platform restrictions, PyArrow cap, zendriver coupling, and the incomplete deprecation workflow, but they are scattered through metadata and comments rather than consolidated for users. MIT metadata matches the complete LICENSE, justifying full credit. VCS versioning, the PyPI version badge, a GitHub Releases changelog link, and an approval-gated deprecation workflow provide a strong update path and justify full credit. The named author, issue tracker, contributing docs, Discord, and maintainer approval path identify responsibility, but there is no maintenance roster, support commitment, or security contact, and publisher identity remains unverified, so responsibility is adequate rather than complete.
The product targets cited research answers, engineering briefs, changelog drafts, and shareable autodoc output, and the command examples make those outputs plausibly actionable for review, debugging, and explanation. Output usability is capped because no representative generated answer, citation schema, or acceptance criteria are supplied. Combining present code, Git history, and external technical research offers clear marginal value over plain text search for large and cross-file investigations, but the evidence is primarily descriptive and contains no comparative measurements or comprehensive implementation sample. Regex search can operate without providers and local providers offer a lower-egress option, showing useful cost choices; deductions apply because the default dependency set is very large, semantic and deep workflows require embedding, reranking, and LLM resources, and installation, compute, API, and governance costs are not quantified.
Several claims trace to concrete commands, package entry points, dependency declarations, workflows, and tests, including audience parsing, preservation behavior, and deterministic site-tree hashing. Full traceability is withheld because the supplied files do not substantiate core semantic-search quality, citation correctness, Git research behavior, or web-research behavior with corresponding implementation or focused tests. README, pyproject.toml, CI, and tests corroborate platforms, entry points, requirements, builds, and selected autodoc behavior, but requirements.txt drift weakens cross-source corroboration. The material appropriately separates provider-free regex search from provider-dependent advanced features and labels the package Alpha; however, promotional claims such as deep understanding and grounded answers are not clearly separated from measured facts, so fact/inference separation is adequate rather than thorough.
- The configuration example stores an API key directly in a project-root .chunkhound.json. Prefer environment variables or managed secret storage until ignore rules, file permissions, and log redaction are confirmed.
- Remote embedding, LLM, and web-research providers may receive code, queries, or fetched content; the supplied source does not enumerate provider-specific payloads, retention, or telemetry.
- Version ranges differ materially between pyproject.toml and requirements.txt, so different installation paths may resolve different dependency graphs. Use the lock and primary package manifest and remove the drift.
- The package is classified Alpha, has a large dependency surface, and declares packaged Watchman runtimes only for Linux x86_64 and Windows x86_64. Validate other platforms and architectures separately.
- The deprecation workflow currently cannot yank an affected PyPI release and only edits the GitHub Release, leaving rollback during a security incident incomplete.
- Persistent CI test failures are evaluated through flaky annotations. Maintainers should keep that annotation policy narrow so genuine regressions are not accepted as flakiness.
What does this agent do, and when should you use it?
ChunkHound is an open-source, local-first codebase intelligence tool for coding agents and teams working with complex engineering context. Its CLI indexes project files and uses Tree-sitter to cover Python, JavaScript, TypeScript, Java, Go, Rust, C/C++, and other languages and file types. Searches can target the current codebase, recent commits, one commit, or a custom Git range. `chunkhound research` produces cited, cross-file explanations, `chunkhound search` performs semantic or regex retrieval, and `chunkhound websearch` brings external technical evidence into the workflow. Indexing and code search remain under the user's control, while network access, credentials, and external models depend on the selected providers and features.
The basic flow starts with chunkhound index ., followed by chunkhound search "query" to retrieve relevant code or chunkhound research "question" to produce a cited engineering analysis. Git research accepts --last-n, --commit-hash, and --commit-range to investigate recent commits, a specific commit, tags, branches, or arbitrary ranges; --vector-source selects changed code, the indexed database, or both. It can assemble evidence about architecture, behavior paths, large pull requests, releases, merge conflicts, and reported failures, and Autodoc can turn code-backed research into shareable documentation. chunkhound websearch finds technical documentation, APIs, issues, and articles and connects that material to local code research. Regex retrieval works without providers, semantic search needs an embedding provider, and deep research additionally needs an LLM plus an embedding provider with reranking support.
- A coding agent entering a large or unfamiliar repository can gather architecture, relevant files, recent changes, and external constraints before editing.
- A reviewer handling a large pull request, branch diff, or release can create a cited engineering brief and implementation-backed changelog draft for a chosen commit range.
- A maintainer investigating a stack trace, customer report, or incident symptom can trace likely code paths and inspect related recent changes.
- A developer resolving a merge conflict can research why the same behavior changed on each branch instead of examining only the conflicting lines.
- A support or product team can explain product behavior, such as subscription cancellation, using implementation evidence and version history.
- A security-sensitive team can keep indexing local and choose local providers for a zero-code-egress setup.
What are this agent's strengths and limitations?
- It combines current code, Git history, and technical web evidence in one cited research workflow, which is useful when a task requires explaining why behavior changed rather than merely locating text.
- Local-first indexing keeps code-search boundaries under the user's control, and local providers such as Ollama support zero-code-egress configurations.
- Regex search, semantic retrieval, deep research, and Autodoc offer an incremental adoption path based on the complexity of the task.
- Git queries can be scoped precisely to the last N commits, one commit, or an arbitrary range, supporting pull-request, release, and conflict analysis.
- Tree-sitter support spans multiple mainstream languages and file types, making the tool relevant to polyglot repositories and monorepos.
- The complete feature set is not zero-configuration: semantic search needs embeddings, while deep research also needs an LLM and reranking-capable embeddings.
- Installation requires Python 3.10+ and
uv, and teams must add a new CLI and indexing step to their local workflow. - Hosted embedding, LLM, and web-research services require network access and may require API keys; avoiding code egress depends on choosing local providers.
- Feature levels differ substantially: without a provider, users have regex search but not semantic retrieval or deep research.
- The supplied material does not quantify indexing limits, latency, resource consumption, or the depth of support for each language, so very large repositories need their own evaluation.
How do you install or deploy this agent?
Install Python 3.10+ and uv. If uv is not available, run curl -LsSf https://astral.sh/uv/install.sh | sh, then install ChunkHound with uv tool install chunkhound. Regex search requires no API key. Semantic search requires VoyageAI, OpenAI, or local Ollama embeddings; deep research also requires an LLM provider such as Claude Code CLI, Codex CLI, Anthropic, OpenAI, or Grok, together with an embedding provider that supports reranking.
How do you use this agent?
From a project root, run chunkhound index ., then try chunkhound research "How does authentication work?". For an explicit setup, create .chunkhound.json containing {"embedding":{"provider":"voyageai","api_key":"your-key"},"llm":{"provider":"claude-code-cli"}}. Use chunkhound search "JWT refresh token validation" for code retrieval, chunkhound research "What changed in auth recently?" --last-n 20 for recent history, or chunkhound research "Summarize the behavior changes on this branch for reviewers" --commit-range main..HEAD for a branch comparison. External technical research is available through commands such as chunkhound websearch "Stripe webhook retry schedule".
How does this agent compare with similar options?
For embeddings, VoyageAI is identified as the recommended hosted option, OpenAI is another hosted choice, and Ollama provides a local path. LLM execution can use Claude Code CLI or Codex CLI without a separate LLM API key, or use the Anthropic, OpenAI, or Grok APIs. At the feature level, regex search has no provider dependency, semantic search adds an embedding dependency, and deep research further requires an LLM and reranking-capable embeddings.
FAQ
Can it run without API keys?
Must source code be sent to an external service?
Why might deep research be unavailable?
Can research be limited to one pull request or release?
--commit-range main..HEAD or v2.4..HEAD, a specific --commit-hash, or --last-n for recent commits.