# Codebuff: a multi-agent coding framework you run from the terminal

> Codebuff is the open TypeScript framework behind Freebuff, an Apache-2.0 monorepo for building agents that read a codebase, edit it and run commands. Here is what the repository actually documents, and where it stops.

**CodebuffAI/codebuff** — Generate code from the terminal. **Loaded**, Built-in web research, browser use, and more.

- Repository: https://github.com/CodebuffAI/codebuff
- Website: https://codebuff.com
- Stars: 12,778 · Forks: 1,365
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/codebuffai-codebuff

## What Codebuff is for, and who it is not for

Codebuff is the orchestration layer underneath Freebuff. The README states that Freebuff is built on Codebuff, described there as "the open multi-agent framework that powers its orchestration, tools, and SDK", and it points readers who want custom agents or embedded agents to the Codebuff documentation and to the @codebuff/sdk package on npm. That is the clearest statement of audience in the repository: Codebuff is aimed at people assembling agent behaviour, not at people who just want a chat window that writes code.

The distinction matters because the repository is a monorepo, not a product page. The workspaces list in package.json covers agents, cli, common, evals, freebuff, packages/agent-runtime, packages/code-map, packages/llm-providers, scripts/tmux and sdk. Each of those is a separate concern. The agent-runtime package is the execution core, code-map is the piece that finds relevant files, llm-providers abstracts model access, and sdk is the embedding surface. If you only want to describe a change and watch it happen, the README sends you to Freebuff Desktop, CLI, Web, Cloud or Chat instead.

So the honest framing is this: Codebuff solves the problem of composing specialized agents that gather context, plan, edit, run tools and review results, and of exposing that composition to other programs. It is for engineers who have an opinion about how an agent should be structured and want the pieces rather than the finished article.

## Specialized agents instead of one prompt through one model

The README's description of the mechanism is short but specific: Freebuff "uses specialized agents instead of sending every task through one model and one prompt". Depending on the task, agents gather context, plan, edit or research, run tools, and review the result. The README lists five consequences of that design: file-finding agents map the relevant parts of a project before editing; implementation and review agents can divide work, make changes, run commands and inspect the result; research agents can investigate documentation and test applications in a real browser; Desktop isolates concurrent agents in separate workspaces; and Web and Cloud provide sandboxes, previews, terminals and deployment workflows.

That is a routing architecture, not a single loop. The repository layout supports the reading. packages/code-map exists as its own workspace, which fits the file-finding role being separable from editing. packages/agent-runtime exists separately from agents, which fits the runtime being generic and the agent definitions being data. The evals workspace and the buffbench script in package.json suggest the project measures agent behaviour rather than only model output, though the README does not describe what buffbench evaluates.

What the README does not give is the message format between agents, the tool-call protocol, or how the runtime decides which agent handles a task. Those answers live in the docs directory and in the source, not in the README. Treat the README as a map of intent and the packages as the actual contract.

## Installing the Codebuff CLI and running it in a project

The README's quick start is written for Freebuff, and it is the only install path it gives for terminal use. It requires npm and a project directory. After the global install, running the bare command in a project starts the interactive session, where you describe what you want and the agents find files, make changes and run the project's checks.

```bash
npm install -g freebuff
cd ~/my-project
freebuff
```

The README does not document an equivalent npm install line for a codebuff binary. The related searches include "Codebuff npm", and the repository does publish @codebuff/sdk on npm, but the README only names that package in the context of embedding agents in another application. If you want the framework itself rather than the Freebuff product, the documented route is the source checkout.

Local development is documented and has hard prerequisites: Docker and a configured .env.local, with CONTRIBUTING.md to be read before starting the services. The monorepo uses Bun, and the repository pins a Bun version in .bun-version.

```bash
git clone https://github.com/CodebuffAI/freebuff.git
cd freebuff
bun install
bun up
```

The CLI runs separately from the services, which is worth noting because it means a working CLI session depends on the local stack being up.

```bash
bun start-cli
```

package.json also defines dev:freebuff, which sets FREEBUFF_MODE=true when starting the CLI, and release:cli, release:sdk and release:freebuff scripts for publishing each workspace independently. Those release scripts are the clearest signal that the CLI and the SDK are versioned as separate artifacts from the monorepo root.

## The staging release channel is the real upgrade constraint

The most recent releases are tagged v1.0.420-beta.185, v1.0.420-beta.184 and v1.0.420-beta.180, and the release titles read "Codecane v1.0.420-beta.185 (Staging)". The last push to the repository was on 2025-10-21. Every visible release is a beta on a staging channel, and the names alternate between Codecane and Freebuff depending on which workspace was published.

That combination tells you something practical about upgrade cost. There is no visible stable release line to pin to. If you build on the SDK, you are tracking beta artifacts whose version numbers advance quickly (185 to 184 to 180 across three days, in non-monotonic order because they are separate publishes). You will need to decide whether to pin an exact beta version and accept missing fixes, or follow the channel and re-test on each bump. The repository does not document a deprecation policy, a support window, or a changelog beyond the release list.

Maintenance is another thing to read carefully. The repository is not archived, but the last push was on 2025-10-21, which is well over six months before today. Nothing in the repository states a support commitment. If your adoption depends on upstream responsiveness, the release cadence visible here is the only evidence you have, and it stops at that date.

## Licence, attribution and what Apache-2.0 does not settle

The root package.json declares "license": "Apache-2.0", and the repository carries both a LICENSE and a NOTICE file. Apache-2.0 permits commercial use, modification and redistribution, and it includes an explicit patent grant. It also requires that you preserve the licence and notice files and state significant changes when you redistribute. The presence of NOTICE is not decorative: Apache-2.0 expects its contents to be carried through in derivative distributions, so if you fork the runtime into your own product, that file travels with it.

What the licence does not settle is the service side. Freebuff's own data-use section, generated into the README, describes prompts, messages, code, files and repository data being used to provide the service, and analysis of prompts and messages, including pasted content, for ad personalization through Freebuff systems and service providers. It notes that separate uploads and connected repositories are not provided to advertising providers, and that model or feature notices govern whether submissions may be used for AI training. None of that is a licence question, and none of it is answered by Apache-2.0.

If you self-host the framework and point it at your own model provider through packages/llm-providers, the hosted-service terms are not the ones you are operating under. If you use the hosted Freebuff products, they are. This is a distinction worth making explicit before anyone signs off, and it is not legal advice: read the Privacy Policy and NOTICE yourself.

## Where Codebuff is the wrong tool, and what to compare it against

The clearest failure mode is scope. If you want an editor-integrated assistant, Codebuff is not that. The related searches include "codebuff vscode", and the README does not describe a VS Code extension at all. The surfaces it names are terminal, desktop, browser, GitHub repositories and chat. A team standardized on an IDE extension will find nothing to install here.

The other mismatch is operational. Local development requires Docker and a configured .env.local, and the CLI is started separately from the services with bun start-cli. That is a heavier footprint than a single binary you point at a repository. For a laptop with a locked-down container policy, that alone can be disqualifying.

As an alternative, Claude Code takes a different approach: it is a single agent driven by one provider's models, installed as a tool and used directly, rather than a framework you compose agents inside. The trade-off is explicit. Claude Code gives you a finished product with one vendor's model line; Codebuff gives you an agent runtime, a code-map package, an LLM-provider abstraction and an SDK, and leaves the composition to you. If your requirement is "one capable agent today", the first fits. If your requirement is "our own agents, our own routing, embeddable in our product", the second is the shape you want, and the cost is that you own the integration.

The related searches also pair Codebuff against opencode and Cursor. Both comparisons turn on the same axis: editor-first tooling versus a runtime you assemble. The README gives no benchmark that would let you rank them on output quality, and no such claim should be inferred from the repository.

## What to check before committing to Codebuff

Start with the two guides the README names rather than the README itself. CONTRIBUTING.md is the stated prerequisite for local development, and docs/development.md and docs/testing.md cover environment setup and the checks to run before a pull request. Those three files are where the actual working contract lives, and the README is explicit that they should be read before starting the services.

Then confirm the SDK surface. The README points to @codebuff/sdk on npm and to the Codebuff documentation for creating custom agents or embedding them in another application. Read the published package and the docs together, because the version you install from npm and the version in this monorepo may not be the same commit. The release:sdk script exists precisely because the SDK ships on its own cadence.

Finally, decide your stance on the beta channel. Every release visible in the repository is a staging beta, and the last push was on 2025-10-21. Pin an exact version, record which one, and re-run your own evaluation whenever you move. The evals workspace and the buffbench script show the project has its own harness, but the README does not describe what it measures, so it is not a substitute for testing your own workloads.

## Conclusion

Adopt Codebuff if you want to build or embed multi-agent coding workflows on top of an Apache-2.0 TypeScript framework and are willing to read CONTRIBUTING.md, docs/development.md and docs/testing.md before touching the runtime. Do not adopt it if you want a finished, supported coding assistant with a published install path: the README routes end users to Freebuff, and the framework's own CLI install steps are not spelled out there. Verify first that the CLI package name and the @codebuff/sdk API surface match what you need, that Docker and a configured .env.local are acceptable in your environment, and that the staging-only release tags in the repository fit your upgrade policy.

## FAQ

### Is Codebuff free to use?

The README describes Freebuff, the product built on Codebuff, as five free AI products with no subscription, credits or API key required, supported by text ads. It does not state pricing for the Codebuff framework itself, and the repository is licensed Apache-2.0.

### What is Codebuff?

The README calls Codebuff "the open multi-agent framework that powers its orchestration, tools, and SDK" for Freebuff. The repository is a TypeScript monorepo built with Bun, with separate workspaces for agents, the CLI, the agent runtime, the code map and LLM providers.

### What are the differences between Codebuff and Freebuff?

Freebuff is the set of end-user products (Desktop, CLI, Web, Cloud and Chat) that the README tells you to download or install. Codebuff is the framework underneath, and the README directs readers to it only when they want to create custom agents or embed agents in another application.

### How do I install Codebuff?

The README gives no npm install line for a codebuff binary. It gives npm install -g freebuff for the terminal product, and for the framework it documents a source checkout with git clone, bun install and bun up, requiring Docker and a configured .env.local.

### Does Codebuff have a VS Code extension?

The README does not mention a VS Code extension. It lists terminal, desktop, browser, GitHub repository and chat surfaces for Freebuff, and describes Codebuff itself as a framework and SDK.

## Sources

- [Official documentation](https://codebuff.com)
- [Official README](https://github.com/CodebuffAI/codebuff#readme)
- [Project repository](https://github.com/CodebuffAI/codebuff)
- [Release notes](https://github.com/CodebuffAI/codebuff/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/codebuffai-codebuff