# codebuff **Repository Path**: devai/codebuff ## Basic Information - **Project Name**: codebuff - **Description**: Codebuff 是一个开源的 AI 编码助手，它可以通过自然语言指令对代码库进行编辑。它不依赖单一模型，而是协调多个专业代理协同工作，以理解项目并进行精确修改 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-09-16 - **Last Updated**: 2026-03-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Codebuff & Freebuff **[Codebuff](https://codebuff.com)** is an open-source AI coding assistant that edits your codebase through natural language instructions. **[Freebuff](https://www.npmjs.com/package/freebuff)** is the free, ad-supported version — no subscription, no credits, no configuration. Instead of using one model for everything, Codebuff coordinates specialized agents that work together to understand your project and make precise changes.
Codebuff vs Claude Code
Codebuff beats Claude Code at 61% vs 53% on [our evals](evals/README.md) across 175+ coding tasks over multiple open-source repos that simulate real-world tasks. ## How it works When you ask Codebuff to "add authentication to my API," it might invoke: 1. A **File Picker Agent** to scan your codebase to understand the architecture and find relevant files 2. A **Planner Agent** to plan which files need changes and in what order 3. An **Editor Agent** to make precise edits 4. A **Reviewer Agent** to validate changes
Codebuff Multi-Agents
This multi-agent approach gives you better context understanding, more accurate edits, and fewer errors compared to single-model tools. ## CLI: Install and start coding Install: ```bash npm install -g codebuff ``` Run: ```bash cd your-project codebuff ``` Then just tell Codebuff what you want and it handles the rest: - "Fix the SQL injection vulnerability in user registration" - "Add rate limiting to all API endpoints" - "Refactor the database connection code for better performance" Codebuff will find the right files, makes changes across your codebase, and runs tests to make sure nothing breaks. ## Create custom agents To get started building your own agents, start Codebuff and run the `/init` command: ```bash codebuff ``` Then inside the CLI: ``` /init ``` This creates: ``` knowledge.md # Project context for Codebuff .agents/ └── types/ # TypeScript type definitions ├── agent-definition.ts ├── tools.ts └── util-types.ts ``` You can write agent definition files that give you maximum control over agent behavior. Implement your workflows by specifying tools, which agents can be spawned, and prompts. We even have TypeScript generators for more programmatic control. For example, here's a `git-committer` agent that creates git commits based on the current git state. Notice that it runs `git diff` and `git log` to analyze changes, but then hands control over to the LLM to craft a meaningful commit message and perform the actual commit. ```typescript export default { id: 'git-committer', displayName: 'Git Committer', model: 'openai/gpt-5-nano', toolNames: ['read_files', 'run_terminal_command', 'end_turn'], instructionsPrompt: 'You create meaningful git commits by analyzing changes, reading relevant files for context, and crafting clear commit messages that explain the "why" behind changes.', async *handleSteps() { // Analyze what changed yield { tool: 'run_terminal_command', command: 'git diff' } yield { tool: 'run_terminal_command', command: 'git log --oneline -5' } // Stage files and create commit with good message yield 'STEP_ALL' }, } ``` ## SDK: Run agents in production Install the [SDK package](https://www.npmjs.com/package/@codebuff/sdk) -- note this is different than the CLI codebuff package. ```bash npm install @codebuff/sdk ``` Import the client and run agents! ```typescript import { CodebuffClient } from '@codebuff/sdk' // 1. Initialize the client const client = new CodebuffClient({ apiKey: 'your-api-key', cwd: '/path/to/your/project', onError: (error) => console.error('Codebuff error:', error.message), }) // 2. Do a coding task... const result = await client.run({ agent: 'base', // Codebuff's base coding agent prompt: 'Add error handling to all API endpoints', handleEvent: (event) => { console.log('Progress', event) }, }) // 3. Or, run a custom agent! const myCustomAgent: AgentDefinition = { id: 'greeter', displayName: 'Greeter', model: 'openai/gpt-5.1', instructionsPrompt: 'Say hello!', } await client.run({ agent: 'greeter', agentDefinitions: [myCustomAgent], prompt: 'My name is Bob.', customToolDefinitions: [], // Add custom tools too! handleEvent: (event) => { console.log('Progress', event) }, }) ``` Learn more about the SDK [here](https://www.npmjs.com/package/@codebuff/sdk). ## Freebuff: The free coding agent Don't want a subscription? **[Freebuff](https://www.npmjs.com/package/freebuff)** is a free variant of Codebuff — no subscription, no credits, no configuration. Just install and start coding. ```bash npm install -g freebuff cd your-project freebuff ``` Freebuff is ad-supported and uses models optimized for fast, high-quality assistance. It includes built-in web research, browser use, and more. Learn more in the [Freebuff README](./freebuff/README.md). ## Why choose Codebuff **Custom workflows**: TypeScript generators let you mix AI generation with programmatic control. Agents can spawn subagents, branch on conditions, and run multi-step processes. **Any model on OpenRouter**: Unlike Claude Code which locks you into Anthropic's models, Codebuff supports any model available on [OpenRouter](https://openrouter.ai/models) - from Claude and GPT to specialized models like Qwen, DeepSeek, and others. Switch models for different tasks or use the latest releases without waiting for platform updates. **Reuse any published agent**: Compose existing [published agents](https://www.codebuff.com/store) to get a leg up. Codebuff agents are the new MCP! **SDK**: Build Codebuff into your applications. Create custom tools, integrate with CI/CD, or embed coding assistance into your products. ## Advanced Usage ### Custom Agent Workflows Create your own agents with specialized workflows using the `/init` command: ```bash codebuff /init ``` This creates a custom agent structure in `.agents/` that you can customize. ## Contributing to Codebuff We ❤️ contributions from the community - whether you're fixing bugs, tweaking our agents, or improving documentation. **Want to contribute?** Check out our [Contributing Guide](./CONTRIBUTING.md) to get started. ### Running Tests To run the test suite: ```bash cd cli bun test ``` **For interactive E2E testing**, install tmux: ```bash # macOS brew install tmux # Ubuntu/Debian sudo apt-get install tmux # Windows (via WSL) wsl --install sudo apt-get install tmux ``` See [cli/src/__tests__/README.md](cli/src/__tests__/README.md) for comprehensive testing documentation. Some ways you can help: - 🐛 **Fix bugs** or add features - 🤖 **Create specialized agents** and publish them to the Agent Store - 📚 **Improve documentation** or write tutorials - 💡 **Share ideas** in our [GitHub Issues](https://github.com/CodebuffAI/codebuff/issues) ## Get started ### Install **CLI**: `npm install -g codebuff` **SDK**: `npm install @codebuff/sdk` **Freebuff (free)**: `npm install -g freebuff` ### Resources **Documentation**: [codebuff.com/docs](https://codebuff.com/docs) **Community**: [Discord](https://codebuff.com/discord) **Issues & Ideas**: [GitHub Issues](https://github.com/CodebuffAI/codebuff/issues) **Contributing**: [CONTRIBUTING.md](./CONTRIBUTING.md) - Start here to contribute! **Support**: [support@codebuff.com](mailto:support@codebuff.com) ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=CodebuffAI/codebuff&type=Date)](https://www.star-history.com/#CodebuffAI/codebuff&Date)