Contributing to ChunkHound

Welcome to ChunkHound’s 100% AI-generated codebase! We’re building the future of AI-assisted development by maintaining production-quality software that’s entirely generated by AI agents with human guidance. Every line of code, documentation, and feature comes from AI - proving that AI-generated code can be robust, maintainable, and continuously evolving.

Read our origin story to see how ChunkHound bootstrapped itself from empty repository to functional codebase in a single day.

Getting Started

Prerequisites

Before contributing, you need ChunkHound set up and running:

Install & Configure ChunkHound

Follow the Tutorial to install ChunkHound, configure your embedding provider, index your first codebase, and set up MCP integration

Set Up Code Expert Agent

Install the Code Expert Agent - essential for understanding the codebase before coding

Set Up Research Tools

You’ll need additional MCP tools for web searches and documentation access. For a custom research agent designed for coding workflows, ping @ofri in our Discord

Development Workflow

Before Writing Any Code

Always use the Code Expert Agent first. This is crucial for maintaining code quality in an AI-generated codebase:

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

The Code Expert Agent ensures your AI agent:

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

Quality Standards

AI-generated only - All code must be generated by AI agents
Match existing patterns - Study how similar features are implemented
Minimize changes - Prefer editing existing files over creating new ones
Reuse mechanisms - Don’t reinvent existing functionality
Optimize for simplicity - Follow KISS principle while balancing developer experience and scalability needs for ChunkHound’s enterprise use cases
Test thoroughly - Always run smoke tests before commits:
Terminal window
```
uv run pytest tests/test_smoke.py -v
```

Testing Philosophy

ChunkHound’s testing approach is designed for AI-generated development:

Smoke tests are mandatory - Run before every commit to catch AI-introduced breaking changes
Real components over mocks - Exercise actual functionality whenever possible
Tests as AI guardrails - Define expected behavior to guide AI agents
Fast feedback over coverage - Better fewer reliable tests than many flaky ones

Claude Code Commands

These optimized slash commands help maintain ChunkHound’s code quality. Create these files in your project’s .claude/commands/ directory:

Code Review Command

Create .claude/commands/review.md:

---
description: Critical code review before committing changes
argument-hint: [description of changes]
---

You are an expert code reviewer. Analyze the current changeset and provide a critical review.

The changes in the working tree were meant to: $ARGUMENTS

Think step-by-step through each aspect below, focusing solely on the changes in the working tree.

1. **Architecture & Design**
   - Verify conformance to project architecture
   - Check module responsibilities are respected
   - Ensure changes align with the original intent

2. **Code Quality**
   - Code must be self-explanatory and readable
   - Style must match surrounding code patterns
   - Changes must be minimal - nothing unneeded
   - Follow KISS principle

3. **Maintainability**
   - Optimize for future LLM agents working on the codebase
   - Ensure intent is clear and unambiguous
   - Verify comments and docs remain in sync with code

4. **User Experience**
   - Identify areas where extra effort would significantly improve UX
   - Balance simplicity with meaningful enhancements

Review the changes critically. Focus on issues that matter.
DO NOT EDIT ANYTHING - only review.

Commit Command

Create .claude/commands/commit.md:

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*)
argument-hint: [description of changes]
description: Review changes and create clean git commits
---
$ARGUMENTS
---
Review the changes and create atomic commits based on the intended behavior above.

PROCESS:
1. Review all diffs since last commit
2. Identify logical units - split unrelated changes into separate commits
3. Use partial/hunk staging when files contain multiple logical changes
4. Write single-line commit messages describing WHAT changed

CONSTRAINTS:
- Exclude temporary/non-essential files
- Update .gitignore only if necessary
- Commit locally only (no push)
- Keep commit messages clear and concise - one line each

Execute the commits now.

Using the Commands

Recommended Workflow:

Make your changes
Review: /project:review "add new language parser support"
Think critically about the suggestions - don’t blindly accept them
Apply only the improvements that make sense
Commit: /project:commit "fix embedding batch size calculation"

The review command provides suggestions, not requirements. Use your judgment to determine which suggestions improve the code and which don’t fit the context.

Community

Join our community to collaborate on AI-assisted development:

License

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

Ready to contribute? Index ChunkHound with itself, set up the Code Expert Agent, and join our Discord to connect with the community of AI-assisted developers.