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!
Before you begin, you'll need to install a few tools:
- Bun (our primary package manager): Follow the Bun installation guide
- direnv: This manages environment variables automatically
- macOS:
brew install direnv - Ubuntu/Debian:
sudo apt install direnv - Other systems: See direnv installation guide
- macOS:
- Docker: Required for the web server database
- Infisical CLI: For secrets management
npm install -g @infisical/cli
-
Hook direnv into your shell (one-time setup):
- For zsh:
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && source ~/.zshrc - For bash:
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && source ~/.bashrc - For fish:
echo 'direnv hook fish | source' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish
- For zsh:
-
Restart your shell: Run
exec $SHELLor restart your terminal -
Clone the repository:
git clone https://github.com/CodebuffAI/codebuff.git cd codebuff -
Set up secrets management:
npm install -g @infisical/cli infisical init infisical login # Select "US" region when promptedFollow the Infisical Setup Guide for detailed setup instructions.
Load all environment variables at once:
infisical secrets set --file .env.example infisical secrets set DATABASE_URL=postgresql://manicode_user_local:secretpassword_local@localhost:5432/manicode_db_local
-
Configure environment:
direnv allow
-
Install dependencies:
bun install
-
Start development services (requires 3 terminals):
# Terminal 1 - Backend server (start first) bun run start-server # Expected: 🚀 Server is running on port 4242 # Terminal 2 - Web server (start second) bun run start-web # Expected: Ready on http://localhost:3000 # Terminal 3 - CLI client (start last) bun run start-bin # Expected: Welcome to Codebuff! + agent list
Now, you should be able to run the CLI and send commands, but it will error out because you don't have any credits.
Note: CLI requires both backend and web server running for authentication.
-
Giving yourself credits:
There are two ways to give yourself credits:
-
If you have the Stripe environment variables set, you can add billing information (just put in a fake credit card) at http://localhost:3000/usage
-
However, if you don't have Stripe set up, you will need to manually add credits to your account in the database.
bun run start-studio
Then, navigate to https://local.drizzle.studio/
Create a new row in the
credit_ledgertable. The values should be:operation_id: [anything you want should be unique]user_id: [your user ID from theusertable]principal: [some very large number, one hundred million should last basically indefinitely]balance: [the same asprincipal]type: adminpriority: 80
Now, you should be able to run the CLI commands locally from within the
codebuffdirectory. -
-
Running in other directories:
In order to run the CLI from other directories, you need to first publish the agents to the database.
-
First, create a publisher profile at http://localhost:3000/publishers. Make sure the
publisher_idiscodebuff. -
Run:
bun run start-bin publish base
-
It will give you an error along the lines of
Invalid agent ID: [some agent ID], e.g.Invalid agent ID: context-pruner. You need to publish that agent at the same time, e.g.:bun run start-bin publish base context-pruner
-
Repeat this until there are no more errors.
- As of the time of writing, the command required is:
bun start-bin publish base context-pruner file-explorer file-picker researcher thinker reviewer
-
Now, you can start the CLI in any directory by running:
bun run start-bin --cwd [some/other/directory]
-
Codebuff is organized as a monorepo with these main packages:
- backend/: WebSocket server, LLM integration, agent orchestration
- npm-app/: CLI application that users interact with
- web/: Next.js web application and dashboard
- python-app/: Python version of the CLI (experimental)
- common/: Shared code, database schemas, utilities
- sdk/: TypeScript SDK for programmatic usage
- .agents/: Agent definition files and templates
- packages/: Internal packages (billing, bigquery, etc.)
- evals/: Evaluation framework and benchmarks
Not sure where to start? Here are some great ways to jump in:
- New here? Look for issues labeled
good first issue- they're perfect for getting familiar with the codebase - Ready for more? Check out
help wantedissues where we could really use your expertise - Have an idea? Browse open issues or create a new one to discuss it
- Want to chat? Join our Discord - the team loves discussing new ideas!
Here's how we like to work together:
- Fork and branch - Create your own fork and a new branch for your changes
- Code away - Follow our style guidelines (more on that below)
- Test it - Write tests for new features and run
bun testto make sure everything works - Type check - Run
bun run typecheckto catch any TypeScript issues - Submit a PR - Open a pull request with a clear description of what you built and why
Pro tip: Small, focused PRs are easier to review and merge quickly!
We keep things consistent and readable:
- TypeScript everywhere - It helps catch bugs and makes the code self-documenting
- Specific imports - Use
import { thing }instead ofimport *(keeps bundles smaller!) - Follow the patterns - Look at existing code to match the style
- Reuse utilities - Check if there's already a helper for what you need
- Test with
spyOn()- Our preferred way to mock functions in tests - Clear function names - Code should read like a story
Testing is important! Here's how to run them:
bun test # Run all tests
bun test --watch # Watch mode for active development
bun test specific.test.ts # Run just one test fileWriting tests: Use spyOn() for mocking functions (it's cleaner than mock.module()), and always clean up with mock.restore() in your afterEach() blocks.
We use conventional commit format:
feat: add new agent for React component generation
fix: resolve WebSocket connection timeout
docs: update API documentation
test: add unit tests for file operations
There are tons of ways to make Codebuff better! Here are some areas where your skills could really shine:
Build specialized agents in .agents/ for different languages, frameworks, or workflows. Think React experts, Python debuggers, or Git wizards!
Add new capabilities in backend/src/tools.ts - file operations, API integrations, development environment helpers. The sky's the limit!
Make the SDK in sdk/ even more powerful with new methods, better TypeScript support, or killer integration examples.
Enhance the user experience in npm-app/ with smoother commands, better error messages, or interactive features that make developers smile.
Level up the web interface in web/ with better agent management, project templates, analytics, or any UX improvements you can dream up.
Setup issues?
- direnv problems? Make sure it's hooked into your shell, run
direnv allow, and restart your terminal - Script errors? Double-check you're using bun for all commands
- Infisical issues? See our Infisical Setup Guide for step-by-step instructions
- Database connection errors? If you see
password authentication failed for user "postgres"errors:- Ensure DATABASE_URL uses the correct credentials:
postgresql://manicode_user_local:secretpassword_local@localhost:5432/manicode_db_local - Update both your local
.envfile and Infisical secret:infisical secrets set DATABASE_URL=postgresql://manicode_user_local:secretpassword_local@localhost:5432/manicode_db_local - Run the database migration:
infisical run -- bun run db:migrate - Restart your development services
- Ensure DATABASE_URL uses the correct credentials:
- Empty Agent Store in dev mode? This is expected behavior - agents from
.agents/directory need to be published to the database to appear in the marketplace
Questions? Jump into our Discord community - we're friendly and always happy to help!
- Documentation: codebuff.com/docs
- Community Discord: codebuff.com/discord
- Report issues: GitHub Issues