Contributing to ChunkHound

ChunkHound is built 100% by AI agents without compromising on production quality. Contribute the same way — use AI tools to write code, and AI agents will review it.

The methodology behind this workflow is published at agenticoding.ai: structured prompting, plan → execute → verify cycles, and CI-integrated automated review.

Getting started

Before writing any code, set up ChunkHound and index its own codebase:

1. Follow the Getting Started guide to install ChunkHound with uv and configure your embedding provider and LLM.
2. Clone the repo and index it:

   git clone https://github.com/chunkhound/chunkhound.git
   cd chunkhound
   chunkhound index .

3. Set up MCP integration so your agent has access to code_research and search. code_research lets your agent understand ChunkHound's architecture, patterns, and module boundaries before touching any code — one research call replaces 5–10 manual searches and produces better-targeted changes.

Development workflow

Before writing any code

Always start with Code Research:

Research the codebase. Consider the surrounding code style,
architecture, and module responsibilities.
Think of the minimal required changes that reuse as much as possible.

This ensures your agent:

• Understands existing patterns and conventions
• Reuses existing mechanisms instead of duplicating code
• Follows the established architecture
• Makes minimal, targeted changes

Testing ladder

Run the right checks at each stage:

# Before every commit — smoke tests (~10 seconds)
uv run pytest tests/test_smoke.py -v -n auto

# Before pushing to a PR — full suite + quality gate
uv run ruff check chunkhound       # lint
uv run ruff format chunkhound      # format
uv run mypy chunkhound             # type check
uv run pytest tests/ -v            # full tests

Commit messages

Use Conventional Commits:

fix(llm): Gemini timeout converted to milliseconds
feat: add native Grok (xAI) LLM provider support
fix(deps): pin tree-sitter-language-pack<1.0.0

The review process

This is where ChunkHound differs from most open-source projects. PRs go through an iterative AI-assisted review process with human oversight at every step.

How reviews work

Every review pass combines AI agents and a human reviewer. The reviewer runs one or more AI agents internally, verifies their outputs and claims, then posts the result — an AI-generated review that a human has validated. Depending on the size and risk of the PR, one or more reviewers may participate, and they can hand off across rounds. Different reviewers may use different tools; for example, some use CURe for structured Business and Technical assessments with explicit verdicts.

Reviews are marked with a note: "This review was generated by an AI agent. If you'd like to talk with other humans, drop by our Discord!"

Iterative rounds

Expect 2–6 review rounds on a typical PR. Complex changes can go through 10+. Each round identifies specific blocking issues that must be resolved before the next pass. This is normal — the iterative process produces cleaner code than a single-pass review.

Getting to merge

1. Keep CI green. All tests must pass before every review round, including the first. Reviewers will not look at a PR with failing tests.
2. Stay rebased. It is your responsibility to keep your branch merged with main and free of conflicts. PRs with merge conflicts will not be merged.
3. Request review. Once tests are green and conflicts are resolved, re-request review in the GitHub reviewers section or ask on Discord.
4. Final approval. A maintainer merges once all blocking issues are resolved, CI is green on all three platforms (Ubuntu, macOS, Windows), and the branch is up to date with main.

Testing philosophy

AI agents write the code here, and they refactor aggressively. Tests that break every time an agent restructures internals are worse than no tests — they punish good engineering. So we follow one rule: test what was promised, not how it was built.

• Verify the value proposition. Tests assert external behavior, user-facing contracts, and invariants. If the behavior stays the same after a refactor, every test should still pass.
• Sociable, not solitary. Test clusters of real components working together — real file systems, real parsers, real pipelines. Only mock at true system boundaries like external APIs and third-party services.
• Clean interfaces in, behavior out. Interact with the system through its public APIs and build dedicated test helpers — factories, builders, fixtures — when you need controlled setup. What matters is that assertions verify observable behavior, not implementation details.
• Platform-agnostic. Tests must pass on Windows, macOS, and Linux. No platform-specific assumptions.

What makes a good PR

ChunkHound PRs use a split format: a human-readable description in the PR body, plus an agent-optimized attachment that grounds the reviewer's AI agents.

The PR body (human-optimized)

The PR description is written for humans — direct, concise, and conversational. It should be 1–3 paragraphs covering what was done, the reasoning behind it, breaking changes (if any), and the value it adds.

Frame the body like this:

**Note**: This PR was generated by an AI agent. If you'd like to
talk with other humans, drop by our [Discord](https://discord.gg/BAepHEXXnX)!

---

[Your 1–3 paragraph description here]

---

Attached is an agent optimized description of the changes in this PR - [AGENT_REVIEW.md](...)

The agent attachment (agent-optimized)

Upload an AGENT_REVIEW.md file as a GitHub attachment on the PR. This file is optimized for the reviewer's AI agents to consume — it explains the changes efficiently with enough context for an agent to verify correctness, trace architecture decisions, and identify regressions without needing to re-derive everything from the diff.

General PR hygiene

• Explain why the change is needed, not just what it does
• Link the related issue if one exists (Closes #123)
• Add regression tests for bug fixes
• All code must be AI-generated

Community

License

By contributing, you agree that your contributions will be licensed under the same MIT License as ChunkHound.

Ready to contribute? Pick an issue and join our Discord.