[chore] Update readmes (#255)

Co-authored-by: James Grugett <jahooma@gmail.com>

Author: brandonkachen

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.
+<div align="center">
+  <img src="./assets/multi-agents.png" alt="Codebuff Multi-Agents" width="600">
+</div>
 
-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 <repository-url>
-   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)

assets/demo.gif

@@ -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! 🤖
+    // 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).