diff --git a/README.md b/README.md index 0034aece0a..17e963f821 100644 --- a/README.md +++ b/README.md @@ -1,175 +1,115 @@ # Codebuff -Codebuff is an AI-powered coding assistant that helps developers build apps faster and easier. It provides an interactive command-line interface for natural language interactions with your codebase. +Codebuff is an AI coding assistant that edits your codebase through natural language instructions. Instead of using one model for everything, it coordinates specialized agents that work together to understand your project and make precise changes. -## Features +Codebuff beats Claude Code at 61% vs 53% on [our internal evals](evals/README.md) across 200+ coding tasks over multiple open-source repos that simulate real-world tasks. -- AI-powered code generation and modification -- Real-time, interactive command-line interface -- Support for multiple programming languages -- File management and version control integration -- Web scraping capabilities for gathering external information -- Terminal command execution for various development tasks -- Knowledge management system for project-specific information +![Codebuff Demo](./assets/demo.gif) -## How It Works +## How it works -Codebuff uses advanced AI models to understand and generate code based on natural language instructions. Here's a brief overview of its operation: +When you ask Codebuff to "add authentication to my API," it might invoke: -1. **Project Analysis**: Codebuff analyzes your project structure and files to gain context. +1. A **File Explorer Agent** scans your codebase to understand the architecture and find relevant files +2. An **Planner Agent** plans which files need changes and in what order +3. An **Implementation Agents** make precise edits +4. A **Review Agents** validate changes -2. **User Interaction**: You interact with Codebuff through a command-line interface, providing instructions or queries in natural language. +
+ Codebuff Multi-Agents +
-3. **AI Processing**: Codebuff processes your input, considering the project context and your instructions. +This multi-agent approach gives you better context understanding, more accurate edits, and fewer errors compared to single-model tools. -4. **Code Generation/Modification**: Based on its understanding, Codebuff generates new code or suggests modifications to existing files. +## CLI: Install and start coding -5. **Real-time Feedback**: Changes are presented to you in real-time, allowing for immediate review and further refinement. - -6. **Knowledge Accumulation**: Codebuff learns from interactions and stores project-specific knowledge for future use. - -## How to Use Codebuff - -To get started with Codebuff, follow these steps: - -1. Install Codebuff globally using npm: - - ``` - npm install -g codebuff - ``` - -2. Navigate to your project directory in the terminal. - -3. Run Codebuff: - - ``` - codebuff - ``` - -4. Interact with Codebuff using natural language commands. For example: - - - "Add a new function to handle user authentication" - - "Refactor the database connection code for better performance" - - "Explain how the routing system works in this project" - -5. Review the suggested changes and approve or modify them as needed. - -6. Use the built-in commands for navigation and control: - - Type "help" or "h" for a list of available commands - - Use arrow keys to navigate through command history - - Press Ctrl+U to undo changes and Ctrl+R to redo - - Press Esc to toggle the menu or stop the current AI response - -## Setting Up Locally - -If you want to set up Codebuff for local development: - -### Prerequisites - -1. **Install Bun**: Follow the [Bun installation guide](https://bun.sh/docs/installation) - -2. **Install direnv**: This manages environment variables automatically - - - macOS: `brew install direnv` - - Ubuntu/Debian: `sudo apt install direnv` - - Other systems: See [direnv installation guide](https://direnv.net/docs/installation.html) - -3. **Hook direnv into your shell**: - - For zsh: - ```bash - echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && source ~/.zshrc - ``` - - For bash: - ```bash - echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && source ~/.bashrc - ``` - - For fish: - ```bash - echo 'direnv hook fish | source' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish - ``` -4. **Restart your shell**: Run `exec $SHELL` (or manually kill and re-open your terminal). - -5. **Install Docker**: Required for the web server database - -### Setup Steps - -1. **Clone and navigate to the project**: - - ```bash - git clone - cd codebuff - ``` - -2. **Set up Infisical for secrets management**: +```bash +npm install -g codebuff +cd your-project +codebuff +``` - ```bash - npm install -g @infisical/cli - infisical login - ``` +Then just tell Codebuff what you want and it handles the rest: - When prompted, select the "US" region, then verify setup: +- "Fix the SQL injection vulnerability in user registration" +- "Add rate limiting to all API endpoints" +- "Refactor the database connection code for better performance" - ```bash - infisical secrets - ``` +Codebuff will find the right files, makes changes across your codebase, and runs tests to make sure nothing breaks. -3. **Configure direnv**: +### Create custom agents - ```bash - direnv allow - ``` +You can create specialized agents for your workflows using TypeScript generators for more programmatic control. - This automatically manages your PATH and environment variables. The `.envrc` file is already committed to the repository and sets up the correct PATH to use the project's bundled version of Bun. +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 messagea and perform the actual commit. -4. **Install dependencies**: +```typescript +export default { + id: 'git-committer', + displayName: 'Git Committer', + model: 'openai/gpt-5-nano', + toolNames: ['read_files', 'run_terminal_command', 'end_turn'], - ```bash - bun install - ``` + 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.', -5. **Start the development services**: + async *handleSteps() { + // Analyze what changed + yield { tool: 'run_terminal_command', command: 'git diff' } + yield { tool: 'run_terminal_command', command: 'git log --oneline -5' } - **Terminal 1 - Backend server**: + // Stage files and create commit with good message + yield 'STEP_ALL' + }, +} +``` - ```bash - bun run start-server - ``` +## SDK: Build custom AI coding tools + +```typescript +import { CodebuffClient } from 'codebuff' + +// Initialize the client +const client = new CodebuffClient({ + apiKey: 'your-api-key', + cwd: '/path/to/your/project', + onError: (error) => console.error('Codebuff error:', error.message), +}) + +// Run a task, like adding error handling to all API endpoints +const result = await client.run({ + prompt: 'Add comprehensive error handling to all API endpoints', + agent: 'base', + handleEvent: (event) => { + console.log('Progress:', event) + }, +}) +``` - **Terminal 2 - Web server** (requires Docker): +Learn more about the SDK [here](https://www.npmjs.com/package/@codebuff/sdk). - ```bash - bun run start-web - ``` +## Why choose Codebuff - **Terminal 3 - Client**: +**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. - ```bash - bun run start-client - ``` +**Deep customizability**: Create sophisticated agent workflows with TypeScript generators that mix AI generation with programmatic control. Define custom agents that spawn subagents, implement conditional logic, and orchestrate complex multi-step processes that adapt to your specific use cases. -### Running Tests +**Fully customizable SDK**: Build Codebuff's capabilities directly into your applications with a complete TypeScript SDK. Create custom tools, integrate with your CI/CD pipeline, build AI-powered development environments, or embed intelligent coding assistance into your products. -After direnv setup, you can run tests from any directory: +## Get started -```bash -bun test # Runs with secrets automatically -bun test --watch # Watch mode -bun test specific.test.ts # Run specific test file -``` +### Install -## Troubleshooting +**CLI**: `npm install -g codebuff` -### direnv Issues +**SDK**: `npm install @codebuff/sdk` -If direnv isn't working: +### Resources -1. Ensure it's properly hooked into your shell (see Prerequisites step 3) -2. Run `direnv allow` in the project root -3. Check that `.envrc` exists and has the correct content -4. Restart your terminal if needed +**Running Codebuff locally**: [local-development.md](./local-development.md) -## Licensing +**Documentation**: [codebuff.com/docs](https://codebuff.com/docs) -1. NPM Package: The npm package contained in this project is licensed under the MIT License. See the LICENSE file in the npm package directory for details. +**Community**: [Discord](https://codebuff.com/discord) -2. Other Project Components: All other parts of this project, including but not limited to server-side code and non-public client-side code, are proprietary and confidential. No license is granted for their use, modification, or distribution without explicit permission from the project owner. +**Support**: [support@codebuff.com](mailto:support@codebuff.com) diff --git a/assets/demo.gif b/assets/demo.gif new file mode 100644 index 0000000000..e8c2767b89 Binary files /dev/null and b/assets/demo.gif differ diff --git a/assets/multi-agents.png b/assets/multi-agents.png new file mode 100644 index 0000000000..620d7acc4a Binary files /dev/null and b/assets/multi-agents.png differ diff --git a/common/src/templates/initial-agents-dir/README.md b/common/src/templates/initial-agents-dir/README.md index 13824e94d3..6616eb7173 100644 --- a/common/src/templates/initial-agents-dir/README.md +++ b/common/src/templates/initial-agents-dir/README.md @@ -1,49 +1,52 @@ -# Codebuff Agents +# Custom Agents -This directory contains your custom Codebuff agents. Each agent is a TypeScript file that defines an AI agent with specific capabilities and behavior. +Create specialized agent workflows that coordinate multiple AI agents to tackle complex engineering tasks. Instead of a single agent trying to handle everything, you can orchestrate teams of focused specialists that work together. -## Getting Started +## Context Window Management -1. **Edit an existing agent**: Start with `my-custom-agent.ts` and modify it for your needs -2. **Check out the examples and types**: See the examples and types directories to draw inspiration and learn what's possible. -3. **Test your agent**: Run `codebuff --agent your-agent-name` -4. **Publish your agent**: Run `codebuff publish your-agent-name` +### Why Agent Workflows? -## File Structure +Modern software projects are complex ecosystems with thousands of files, multiple frameworks, intricate dependencies, and domain-specific requirements. A single AI agent trying to understand and modify such systems faces fundamental limitations—not just in knowledge, but in the sheer volume of information it can process at once. -- `types/` - TypeScript type definitions -- `examples/` - Example agents for reference -- `my-custom-agent.ts` - Your first custom agent (edit this!) -- Add any new agents you wish to the .agents directory +### The Solution: Focused Context Windows -## Agent Basics +Agent workflows elegantly solve this by breaking large tasks into focused sub-problems. When working with large codebases (100k+ lines), each specialist agent receives only the narrow context it needs—a security agent sees only auth code, not UI components—keeping the context for each agent manageable while ensuring comprehensive coverage. -Each agent file exports an `AgentDefinition` object with: +### Why Not Just Mimic Human Roles? -- `id`: Unique identifier (lowercase, hyphens only) -- `displayName`: Human-readable name -- `model`: AI model to use (see OpenRouter for options) -- `toolNames`: Tools the agent can use -- `instructionsPrompt`: Instructions for the agent's behavior -- `spawnerPrompt`: When other agents should spawn this one -- `spawnableAgents`: Which agents *this* agent can spawn +This is about efficient AI context management, not recreating a human department. Simply creating a "frontend-developer" agent misses the point. AI agents don't have human constraints like context-switching or meetings. Their power comes from hyper-specialization, allowing them to process a narrow domain more deeply than a human could, then coordinating seamlessly with other specialists. -## Common Tools +## Agent workflows in action -- `read_files` - Read file contents -- `write_file` - Create or modify files -- `str_replace` - Make targeted edits -- `run_terminal_command` - Execute shell commands -- `code_search` - Search for code patterns -- `spawn_agents` - Delegate to other agents -- `end_turn` - Finish the response +Here's an example of a `git-committer` agent that creates good commit messages: -See `types/tools.ts` for more information on each tool! +```typescript +export default { + id: 'git-committer', + displayName: 'Git Committer', + model: 'openai/gpt-5-nano', + toolNames: ['read_files', 'run_terminal_command', 'end_turn'], -## Need Help? + 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.', -- Check the type definitions in `types/agent-definition.ts` -- Look at examples in the `examples/` directory -- Join the Codebuff Discord community (https://discord.com/invite/mcWTGjgTj3) + async *handleSteps() { + // Analyze what changed + yield { tool: 'run_terminal_command', command: 'git diff' } + yield { tool: 'run_terminal_command', command: 'git log --oneline -5' } -Happy agent building! 🤖 \ No newline at end of file + // Stage files and create commit with good message + yield 'STEP_ALL' + }, +} +``` + +This agent systematically analyzes changes, reads relevant files for context, then creates commits with clear, meaningful messages that explain the "why" behind changes. + +## Getting started + +Edit `my-custom-agent.ts` with your team's patterns, then run `codebuff --agent my-custom-agent` to test it. + +For detailed documentation, see [agent-guide.md](./agent-guide.md). +For examples, check the `examples/` directory. +For help, join our [Discord community](https://codebuff.com/discord). diff --git a/common/src/templates/initial-agents-dir/agent-guide.md b/common/src/templates/initial-agents-dir/agent-guide.md new file mode 100644 index 0000000000..fd79e5a281 --- /dev/null +++ b/common/src/templates/initial-agents-dir/agent-guide.md @@ -0,0 +1,211 @@ +# Agent Development Guide + +This guide covers everything you need to know about building custom Codebuff agents. + +## Agent Structure + +Each agent is a TypeScript file that exports an `AgentDefinition` object: + +```typescript +export default { + id: 'my-agent', // Unique identifier (lowercase, hyphens only) + displayName: 'My Agent', // Human-readable name + model: 'claude-3-5-sonnet', // AI model to use + toolNames: ['read_files', 'write_file'], // Available tools + instructionsPrompt: 'You are...', // Agent behavior instructions + spawnerPrompt: 'Use this agent when...', // When others should spawn this + spawnableAgents: ['helper-agent'], // Agents this can spawn + + // Optional: Programmatic control + async *handleSteps() { + yield { tool: 'read_files', paths: ['src/config.ts'] } + yield 'STEP' // Let AI process and respond + } +} +``` + +## Core Properties + +### Required Fields + +- **`id`**: Unique identifier using lowercase letters and hyphens only +- **`displayName`**: Human-readable name shown in UI +- **`model`**: AI model from OpenRouter (see [available models](https://openrouter.ai/models)) +- **`instructionsPrompt`**: Detailed instructions defining the agent's role and behavior + +### Optional Fields + +- **`toolNames`**: Array of tools the agent can use (defaults to common tools) +- **`spawnerPrompt`**: Instructions for when other agents should spawn this one +- **`spawnableAgents`**: Array of agent names this agent can spawn +- **`handleSteps`**: Generator function for programmatic control + +## Available Tools + +### File Operations +- **`read_files`**: Read file contents +- **`write_file`**: Create or modify entire files +- **`str_replace`**: Make targeted string replacements +- **`code_search`**: Search for patterns across the codebase + +### Execution +- **`run_terminal_command`**: Execute shell commands +- **`spawn_agents`**: Delegate tasks to other agents +- **`end_turn`**: Finish the agent's response + +### Web & Research +- **`web_search`**: Search the internet for information +- **`read_docs`**: Read technical documentation +- **`browser_logs`**: Navigate and inspect web pages + +See `types/tools.ts` for detailed parameter information. + +## Programmatic Control + +Use the `handleSteps` generator function to mix AI reasoning with programmatic logic: + +```typescript +async *handleSteps() { + // Execute a tool + yield { tool: 'read_files', paths: ['package.json'] } + + // Let AI process results and respond + yield 'STEP' + + // Conditional logic + if (needsMoreAnalysis) { + yield { tool: 'spawn_agents', agents: ['deep-analyzer'] } + yield 'STEP_ALL' // Wait for spawned agents to complete + } + + // Final AI response + yield 'STEP' +} +``` + +### Control Commands + +- **`'STEP'`**: Let AI process and respond once +- **`'STEP_ALL'`**: Let AI continue until completion +- **Tool calls**: `{ tool: 'tool_name', ...params }` + +## Model Selection + +Choose models based on your agent's needs: + +- **`claude-3-5-sonnet`**: Best for complex reasoning and code generation +- **`gpt-4`**: Strong general-purpose capabilities +- **`claude-3-haiku`**: Fast and cost-effective for simple tasks +- **`gemini-pro`**: Good for analysis and research tasks + +See [OpenRouter](https://openrouter.ai/models) for all available models and pricing. + +## Agent Coordination + +Agents can spawn other agents to create sophisticated workflows: + +```typescript +// Parent agent spawns specialists +async *handleSteps() { + yield { tool: 'spawn_agents', agents: [ + 'security-scanner', + 'performance-analyzer', + 'code-reviewer' + ]} + yield 'STEP_ALL' // Wait for all to complete + + // Synthesize results + yield 'STEP' +} +``` + +## Best Practices + +### Instructions +- Be specific about the agent's role and expertise +- Include examples of good outputs +- Specify when the agent should ask for clarification +- Define the agent's limitations + +### Tool Usage +- Start with file exploration tools (`read_files`, `code_search`) +- Use `str_replace` for targeted edits, `write_file` for major changes +- Always use `end_turn` to finish responses cleanly + +### Error Handling +- Include error checking in programmatic flows +- Provide fallback strategies for failed operations +- Log important decisions for debugging + +### Performance +- Choose appropriate models for the task complexity +- Minimize unnecessary tool calls +- Use spawnable agents for parallel processing + +## Testing Your Agent + +1. **Local Testing**: `codebuff --agent your-agent-name` +2. **Debug Mode**: Add logging to your `handleSteps` function +3. **Unit Testing**: Test individual functions in isolation +4. **Integration Testing**: Test agent coordination workflows + +## Publishing & Sharing + +1. **Validate**: Ensure your agent works across different codebases +2. **Document**: Include clear usage instructions +3. **Publish**: `codebuff publish your-agent-name` +4. **Maintain**: Update as models and tools evolve + +## Advanced Patterns + +### Conditional Workflows +```typescript +async *handleSteps() { + const config = yield { tool: 'read_files', paths: ['config.json'] } + yield 'STEP' + + if (config.includes('typescript')) { + yield { tool: 'spawn_agents', agents: ['typescript-expert'] } + } else { + yield { tool: 'spawn_agents', agents: ['javascript-expert'] } + } + yield 'STEP_ALL' +} +``` + +### Iterative Refinement +```typescript +async *handleSteps() { + for (let attempt = 0; attempt < 3; attempt++) { + yield { tool: 'run_terminal_command', command: 'npm test' } + yield 'STEP' + + if (allTestsPass) break + + yield { tool: 'spawn_agents', agents: ['test-fixer'] } + yield 'STEP_ALL' + } +} +``` + +## Troubleshooting + +### Common Issues +- **Agent not spawning**: Check the `id` format (lowercase, hyphens only) +- **Tool errors**: Verify tool parameters match the expected schema +- **Infinite loops**: Always include exit conditions in loops +- **Memory issues**: Avoid storing large objects in generator state + +### Debugging Tips +- Use `console.log` in `handleSteps` for debugging +- Test individual tool calls before adding to workflows +- Start simple and add complexity gradually + +## Community & Support + +- **Discord**: Join our community for help and inspiration +- **Examples**: Study the `examples/` directory for patterns +- **Documentation**: Check `types/` for detailed type information +- **Issues**: Report bugs and request features on GitHub + +Happy agent building! 🤖 \ No newline at end of file diff --git a/local-development.md b/local-development.md new file mode 100644 index 0000000000..8e9c31772e --- /dev/null +++ b/local-development.md @@ -0,0 +1,109 @@ +# Local Development Setup + +This guide helps you set up Codebuff for local development if you want to contribute to the project or run it locally. + +### Prerequisites + +1. **Install Bun**: Follow the [Bun installation guide](https://bun.sh/docs/installation) + +2. **Install direnv**: This manages environment variables automatically + + - macOS: `brew install direnv` + - Ubuntu/Debian: `sudo apt install direnv` + - Other systems: See [direnv installation guide](https://direnv.net/docs/installation.html) + +3. **Hook direnv into your shell**: + - For zsh: + ```bash + echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && source ~/.zshrc + ``` + - For bash: + ```bash + echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && source ~/.bashrc + ``` + - For fish: + ```bash + echo 'direnv hook fish | source' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish + ``` +4. **Restart your shell**: Run `exec $SHELL` (or manually kill and re-open your terminal). + +5. **Install Docker**: Required for the web server database + +### Setup Steps + +1. **Clone and navigate to the project**: + + ```bash + git clone + cd codebuff + ``` + +2. **Set up Infisical for secrets management**: + + ```bash + npm install -g @infisical/cli + infisical login + ``` + + When prompted, select the "US" region, then verify setup: + + ```bash + infisical secrets + ``` + +3. **Configure direnv**: + + ```bash + direnv allow + ``` + + This automatically manages your PATH and environment variables. The `.envrc` file is already committed to the repository and sets up the correct PATH to use the project's bundled version of Bun. + +4. **Install dependencies**: + + ```bash + bun install + ``` + +5. **Start the development services**: + + **Terminal 1 - Backend server**: + + ```bash + bun run start-server + ``` + + **Terminal 2 - Web server** (requires Docker): + + ```bash + bun run start-web + ``` + + **Terminal 3 - Client**: + + ```bash + bun run start-client + ``` + +### Running Tests + +After direnv setup, you can run tests from any directory: + +```bash +bun test # Runs with secrets automatically +bun test --watch # Watch mode +bun test specific.test.ts # Run specific test file +``` + +## Troubleshooting + +### direnv Issues + +If direnv isn't working: + +1. Ensure it's properly hooked into your shell (see Prerequisites step 3) +2. Run `direnv allow` in the project root +3. Check that `.envrc` exists and has the correct content +4. Restart your terminal if needed + +For more troubleshooting help, see [our documentation](https://www.codebuff.com/docs) or join our [Discord community](https://codebuff.com/discord). \ No newline at end of file diff --git a/npm-app/src/cli.ts b/npm-app/src/cli.ts index d0d9d9a00d..1ae27d24fa 100644 --- a/npm-app/src/cli.ts +++ b/npm-app/src/cli.ts @@ -863,14 +863,11 @@ export class CLI { if (mode === 'lite') { console.log(yellow('✨ Switched to lite mode (faster, cheaper)')) } else if (mode === 'normal') { - console.log(green('⚖️ Switched to normal mode (balanced)')) + console.log(green('⚖️ Switched to normal mode (balanced)')) } else if (mode === 'max') { console.log( blueBright('⚡ Switched to max mode (slower, more thorough)'), ) - console.log( - blueBright('New Jul 2: Even more powerful (though more expensive)'), - ) } else if (mode === 'experimental') { console.log(magenta('🧪 Switched to experimental mode (cutting-edge)')) } else if (mode === 'ask') {