|
| 1 | +# Contributing to Codebuff |
| 2 | + |
| 3 | +Hey there! 👋 Thanks for wanting to contribute to Codebuff. Whether you're squashing bugs, building cool features, or making our docs better, we're excited to have you aboard! |
| 4 | + |
| 5 | +## Getting Started |
| 6 | + |
| 7 | +### Prerequisites |
| 8 | + |
| 9 | +Before you begin, you'll need to install a few tools: |
| 10 | + |
| 11 | +1. **Bun** (our primary package manager): Follow the [Bun installation guide](https://bun.sh/docs/installation) |
| 12 | +2. **direnv**: This manages environment variables automatically |
| 13 | + - macOS: `brew install direnv` |
| 14 | + - Ubuntu/Debian: `sudo apt install direnv` |
| 15 | + - Other systems: See [direnv installation guide](https://direnv.net/docs/installation.html) |
| 16 | +3. **Docker**: Required for the web server database |
| 17 | +4. **Infisical CLI**: For secrets management |
| 18 | + ```bash |
| 19 | + npm install -g @infisical/cli |
| 20 | + ``` |
| 21 | + |
| 22 | +### Setting Up Your Development Environment |
| 23 | + |
| 24 | +1. **Hook direnv into your shell** (one-time setup): |
| 25 | + - For zsh: `echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && source ~/.zshrc` |
| 26 | + - For bash: `echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && source ~/.bashrc` |
| 27 | + - For fish: `echo 'direnv hook fish | source' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish` |
| 28 | + |
| 29 | +2. **Restart your shell**: Run `exec $SHELL` or restart your terminal |
| 30 | + |
| 31 | +3. **Clone the repository**: |
| 32 | + ```bash |
| 33 | + git clone https://github.com/CodebuffAI/codebuff.git |
| 34 | + cd codebuff |
| 35 | + ``` |
| 36 | + |
| 37 | +4. **Set up secrets management**: |
| 38 | + ```bash |
| 39 | + infisical login |
| 40 | + # Select "US" region when prompted |
| 41 | + infisical secrets # Verify setup works |
| 42 | + ``` |
| 43 | + |
| 44 | +5. **Configure environment**: |
| 45 | + ```bash |
| 46 | + direnv allow |
| 47 | + ``` |
| 48 | + |
| 49 | +6. **Install dependencies**: |
| 50 | + ```bash |
| 51 | + bun install |
| 52 | + ``` |
| 53 | + |
| 54 | +7. **Start development services** (requires 3 terminals): |
| 55 | + ```bash |
| 56 | + # Terminal 1 - Backend server |
| 57 | + bun run start-server |
| 58 | + |
| 59 | + # Terminal 2 - Web server |
| 60 | + bun run start-web |
| 61 | + |
| 62 | + # Terminal 3 - CLI client |
| 63 | + bun run start-bin |
| 64 | + ``` |
| 65 | + |
| 66 | +## Understanding the Codebase |
| 67 | + |
| 68 | +Codebuff is organized as a monorepo with these main packages: |
| 69 | + |
| 70 | +- **backend/**: WebSocket server, LLM integration, agent orchestration |
| 71 | +- **npm-app/**: CLI application that users interact with |
| 72 | +- **web/**: Next.js web application and dashboard |
| 73 | +- **python-app/**: Python version of the CLI (experimental) |
| 74 | +- **common/**: Shared code, database schemas, utilities |
| 75 | +- **sdk/**: TypeScript SDK for programmatic usage |
| 76 | +- **.agents/**: Agent definition files and templates |
| 77 | +- **packages/**: Internal packages (billing, bigquery, etc.) |
| 78 | +- **evals/**: Evaluation framework and benchmarks |
| 79 | + |
| 80 | +## Making Contributions |
| 81 | + |
| 82 | +### Finding Something to Work On |
| 83 | + |
| 84 | +Not sure where to start? Here are some great ways to jump in: |
| 85 | + |
| 86 | +- **New here?** Look for issues labeled `good first issue` - they're perfect for getting familiar with the codebase |
| 87 | +- **Ready for more?** Check out `help wanted` issues where we could really use your expertise |
| 88 | +- **Have an idea?** Browse open issues or create a new one to discuss it |
| 89 | +- **Want to chat?** Join our [Discord](https://codebuff.com/discord) - the team loves discussing new ideas! |
| 90 | + |
| 91 | +### Development Workflow |
| 92 | + |
| 93 | +Here's how we like to work together: |
| 94 | + |
| 95 | +1. **Fork and branch** - Create your own fork and a new branch for your changes |
| 96 | +2. **Code away** - Follow our style guidelines (more on that below) |
| 97 | +3. **Test it** - Write tests for new features and run `bun test` to make sure everything works |
| 98 | +4. **Type check** - Run `bun run typecheck` to catch any TypeScript issues |
| 99 | +5. **Submit a PR** - Open a pull request with a clear description of what you built and why |
| 100 | + |
| 101 | +*Pro tip: Small, focused PRs are easier to review and merge quickly!* |
| 102 | + |
| 103 | +### Code Style Guidelines |
| 104 | + |
| 105 | +We keep things consistent and readable: |
| 106 | + |
| 107 | +- **TypeScript everywhere** - It helps catch bugs and makes the code self-documenting |
| 108 | +- **Specific imports** - Use `import { thing }` instead of `import *` (keeps bundles smaller!) |
| 109 | +- **Follow the patterns** - Look at existing code to match the style |
| 110 | +- **Reuse utilities** - Check if there's already a helper for what you need |
| 111 | +- **Test with `spyOn()`** - Our preferred way to mock functions in tests |
| 112 | +- **Clear function names** - Code should read like a story |
| 113 | + |
| 114 | +### Testing |
| 115 | + |
| 116 | +Testing is important! Here's how to run them: |
| 117 | + |
| 118 | +```bash |
| 119 | +bun test # Run all tests |
| 120 | +bun test --watch # Watch mode for active development |
| 121 | +bun test specific.test.ts # Run just one test file |
| 122 | +``` |
| 123 | + |
| 124 | +**Writing tests:** Use `spyOn()` for mocking functions (it's cleaner than `mock.module()`), and always clean up with `mock.restore()` in your `afterEach()` blocks. |
| 125 | + |
| 126 | +### Commit Messages |
| 127 | + |
| 128 | +We use conventional commit format: |
| 129 | + |
| 130 | +``` |
| 131 | +feat: add new agent for React component generation |
| 132 | +fix: resolve WebSocket connection timeout |
| 133 | +docs: update API documentation |
| 134 | +test: add unit tests for file operations |
| 135 | +``` |
| 136 | + |
| 137 | +## Areas Where We Need Help |
| 138 | + |
| 139 | +There are tons of ways to make Codebuff better! Here are some areas where your skills could really shine: |
| 140 | + |
| 141 | +### 🤖 **Agent Development** |
| 142 | +Build specialized agents in `.agents/` for different languages, frameworks, or workflows. Think React experts, Python debuggers, or Git wizards! |
| 143 | + |
| 144 | +### 🔧 **Tool System** |
| 145 | +Add new capabilities in `backend/src/tools.ts` - file operations, API integrations, development environment helpers. The sky's the limit! |
| 146 | + |
| 147 | +### 📦 **SDK Improvements** |
| 148 | +Make the SDK in `sdk/` even more powerful with new methods, better TypeScript support, or killer integration examples. |
| 149 | + |
| 150 | +### 💻 **CLI Magic** |
| 151 | +Enhance the user experience in `npm-app/` with smoother commands, better error messages, or interactive features that make developers smile. |
| 152 | + |
| 153 | +### 🌐 **Web Dashboard** |
| 154 | +Level up the web interface in `web/` with better agent management, project templates, analytics, or any UX improvements you can dream up. |
| 155 | + |
| 156 | +## Getting Help |
| 157 | + |
| 158 | +**Setup issues?** |
| 159 | +- **direnv problems?** Make sure it's hooked into your shell, run `direnv allow`, and restart your terminal |
| 160 | +- **Script errors?** Double-check you're using bun for all commands |
| 161 | +- **Can't find files?** See our [local development guide](./local-development.md) for more detailed setup |
| 162 | + |
| 163 | +**Questions?** Jump into our [Discord community](https://codebuff.com/discord) - we're friendly and always happy to help! |
| 164 | + |
| 165 | +## Resources |
| 166 | + |
| 167 | +- **Detailed setup guide**: [local-development.md](./local-development.md) |
| 168 | +- **Documentation**: [codebuff.com/docs](https://codebuff.com/docs) |
| 169 | +- **Community Discord**: [codebuff.com/discord](https://codebuff.com/discord) |
| 170 | +- **Report issues**: [GitHub Issues](https://github.com/CodebuffAI/codebuff/issues) |
0 commit comments