Codebuff

What It Does

Codebuff is an open-source (Apache-2.0) AI coding assistant that runs as a CLI and decomposes coding tasks across a pipeline of specialist agents: a File Picker agent that scans the codebase to identify relevant files, a Planner agent that sequences changes, an Editor agent that makes precise edits, and a Reviewer agent that validates the output. This multi-agent architecture is the core architectural differentiator vs. single-model tools like Claude Code.

The project ships three products from a single TypeScript monorepo: Codebuff (paid subscription, full-featured), Freebuff (free, ad-supported, uses MiniMax M2.5), and @codebuff/sdk (npm package for embedding coding agents into applications). All variants support custom agent definitions written in TypeScript, with a handleSteps generator API that mixes programmatic control with LLM-driven steps and supports subagent spawning.

Key Features

• Multi-agent pipeline: Specialist agents for file discovery, planning, editing, and review run in sequence; each agent has a scoped tool set and context window
• Custom agent framework: TypeScript agent definitions with handleSteps async generators, toolNames access control, and instructionsPrompt — write agents that mix deterministic logic with LLM steps
• OpenRouter model flexibility: Any model available on OpenRouter can be assigned per-agent via the model field; also supports native Anthropic and OpenAI provider credentials
• Agent Store: Publish and reuse agents at codebuff.com/store; agents are composable via @AgentName mentions in the CLI
• @codebuff/sdk: Programmatic Node.js SDK (CodebuffClient) supporting multi-turn sessions (previousRun), custom tool definitions, and per-run agent overrides
• Freebuff free tier: npm install -g freebuff, ad-supported, no API key required, uses MiniMax M2.5 + Gemini Flash Lite for file scanning
• Built-in eval framework: Git Commit Reimplementation Evaluation — reconstructs real open-source commits via multi-turn prompting, judged by 3 parallel Gemini 2.5 Pro instances (median scoring)
• knowledge.md project context: Project-level context file (analogous to CLAUDE.md) loaded at session start for codebase conventions
• TUI built on OpenTUI + React: Terminal UI with React rendering via OpenTUI; supports slash commands (/init, /history, /usage), agent mentions, bash mode

Use Cases

• Codebase-wide refactoring: Multi-agent file discovery + planning ensures edits are consistent across large codebases without missing dependent files
• Custom CI/CD coding workflows: SDK integration enables embedding coding agents in pipelines — automated issue-to-PR generation, code review bots, or migration scripts
• Model-flexible teams: Organizations that want to use DeepSeek for cost, Claude for complex reasoning, and GPT for code generation, switching per-task without changing tools
• Agent development and sharing: Engineering teams building reusable agents (e.g., git-committer, migration runner, test generator) and publishing to the Agent Store
• Free-tier experimentation: Developers evaluating AI coding assistants without subscription commitment via Freebuff

Adoption Level Analysis

Small teams (<20 engineers): Good fit. npm install -g codebuff and start coding. The agent definition framework rewards engineers who want to encode team conventions into reusable agents. Freebuff removes the subscription barrier for individual developers. Main friction: Codebuff’s subscription is required for full model access beyond the free tier.

Medium orgs (20-200 engineers): Fit with investment. The SDK enables building coding automation into internal tooling, CI/CD pipelines, and review workflows. Custom agents can encode org-specific patterns and be shared via the Agent Store. OpenRouter model flexibility allows cost optimization per task type. Governance concern: agent execution has full terminal access, requiring trust and policy definition.

Enterprise (200+ engineers): Evaluate carefully. Codebuff lacks the enterprise access controls, audit logging, and centralized policy management that large orgs require. The @codebuff/sdk is a viable path for building controlled internal tools, but the CLI as-is is not enterprise-governed. The open-source license allows forking and self-hosting, which may address some concerns.

Alternatives

Evidence & Sources

• Codebuff GitHub Repository
• Codebuff Eval Framework — evals/README.md
• Codebuff Architecture Docs
• @codebuff/sdk on npm
• Freebuff on npm

Notes & Caveats

• Eval claims are self-reported: The 61% vs 53% Claude Code win rate is from Codebuff’s own eval suite. The methodology (Git Commit Reimplementation + AI judge) is transparent and published, but no independent replication exists. Treat as directional, not definitive.
• Model name accuracy in Freebuff: The Freebuff README references model names (Gemini 3.1 Flash Lite, GPT-5.4) that are not clearly in public release as of April 2026. This raises questions about documentation currency.
• Staging releases only: GitHub releases show “Codecane” staging builds (internal beta product rebranding?), not stable Codebuff releases. Versioning and release cadence are opaque from the outside.
• Ad-supported CLI risk: The Freebuff ad-supported model is novel in developer tooling. Developer backlash to ads in CLIs has historically been significant. Commercial sustainability of the free tier is uncertain.
• Apache-2.0 is genuinely open: Unlike many “open-source” AI tools that use BSL or source-available licenses, Codebuff’s Apache-2.0 license allows modification, redistribution, and commercial use without restriction. This is a meaningful positive for self-hosting and forking.
• Bun runtime dependency: The monorepo uses Bun for package management and testing. Teams on standard npm/pnpm pipelines need to account for this in contribution and CI workflows.