How to Use Codebuff: The Beginner's Guide (Install, Login, the Instruction-File Habit, and the Undo Habit)

CodexFuse Team · 2026-11-03T13:17:18.002Z · 14 min read min read

Codebuff is the npm-installed terminal coding agent that writes code for you: install it with one command, log in, teach it your project with an instruction file, and lean on undo/redo while it works. This beginner's guide covers the full first run.

What Is Codebuff, Exactly?

Codebuff is a terminal coding agent that writes code for you: you describe the task in plain language, and it reads, edits, and runs files in your project to produce the code. It installs with one npm command, runs as a chat interface inside your terminal, and ships with undo and redo for the file changes it makes. If you are learning how to use Codebuff, the mental model is simple: it is a coding assistant that lives in your shell, not in an IDE. This Claude Code beginner guide shows the archetype Codebuff follows — the difference is that Codebuff is its own product, from Codebuff AI, with its own subscription and its own free tier. For the exact-match crowd: this is the codebuff tutorial the field was missing — a single unified walkthrough from install to first task to instruction files to undo, with every fact checked against the vendor's own docs.

One frame-setting note, once: Codebuff is the CLI product, and the company also runs Freebuff, the free tier that text ads support. The GitHub repo has been renamed — github.com/CodebuffAI/codebuff now redirects to CodebuffAI/freebuff — and the vendor's own docs say the project is Apache 2.0 licensed. The repo holds about 13,941 stars as of this writing, which makes it one of the most-starred open-source coding-agent projects on GitHub.

How Do You Use Codebuff, Step by Step?

1. Install it with one command: npm install -g codebuff — the package the vendor documents for the full client.
2. Start it in your project: cd into your project directory and run codebuff (or codebuff [project-directory]); the app walks you through sign-in on first run.
3. Give it its first task in plain words: "add a logout button to the header" — it reads your codebase, picks the files, edits them, and runs commands as it deems necessary.
4. Teach it your project with an instruction file: drop an AGENTS.md in the project root so it follows your patterns on every task.
5. Lean on undo/redo while it works: type undo to revert the file changes from the conversation, redo to reapply them; hit Esc or Ctrl+C to stop it mid-generation.

How Do You Install Codebuff?

The documented install is a single npm command, straight from the vendor's troubleshooting docs — the codebuff install path is npm-based on every platform, including Windows. The installer puts its files — including the codebuff binary — in ~/.config/manicode, and the client auto-updates itself.

npm install -g codebuff
codebuff --version

Two install pitfalls show up in the docs, both worth knowing before you start. If npm throws a permission error, the docs give three escalating fixes: on Mac/Linux run sudo chown -R $(whoami) <directory>, on Windows run cmd takeown /F <directory> /R /D Y, and if that fails, reinstall Node with nvm or fnm and rerun the install. If the client ever gets stuck in an update loop, the most common cause is conflicting Node/npm installations (Homebrew vs nvm) — diagnose with which node and which npm. Deleting the binary in ~/.config/manicode and restarting Codebuff fixes several classes of breakage.

The free route is the Freebuff CLI: the official repo's quick start now uses npm install -g freebuff, and it needs no subscription, no credits, and no API key — text ads support access to the included models. The free limited-access allowance is 5 hours a day (4 on a VPN or proxy), and balances have read in hours since October 15, 2026, at 1 hour = 5 Freebucks.

How Do You Sign In to Codebuff?

Here is the honest answer the docs give: the package README does not document a codebuff login command — you run codebuff from your project directory, and sign-in happens in the app's first-run flow. If you are looking for the cluster term "codebuff login", this is the whole story: there is no login command to memorize. For programmatic use, API keys live at codebuff.com/api-keys and are passed as CODEBUFF_API_KEY to the SDK — those keys are the documented auth surface, covered in the SDK section below.

One deprecation to know before you connect anything: connecting a Claude Pro or Max subscription inside Codebuff is deprecated and will be removed on March 1st — the docs do not give a year. The vendor's recommended replacement is the Codebuff Strong subscription, which it says includes generous usage limits across all models without connecting external subscriptions. The docs also warn that at least one user had their Anthropic account disabled after heavy usage through Codebuff, which is why the vendor tells you to switch.

How Do Instruction Files Work in Codebuff?

Codebuff reads an AGENTS.md file in your project root to learn your patterns, constraints, and commands; if there is none, CLAUDE.md is read instead. You can also set a home-directory file (~/.AGENTS.md or ~/.CLAUDE.md) for preferences that apply across all projects. This is the current, documented behavior — and it is the most important correction in this guide, because the package README and older docs still talk about knowledge.md.

The vendor's own FAQ contradicts itself on this point, and the top answer wins: it states plainly that knowledge.md is no longer read, while a stale lower section still recommends adding knowledge.md files. New projects should write AGENTS.md; if you inherited a knowledge.md, migrate its contents. Per directory, the agent picks one instruction file, so keep a single source of truth. A minimal starter looks like this:

Project instructions for Codebuff

Stack: TypeScript, React 19, Tailwind CSS 4. Build with `npm run build`.

Rules:
- Every new endpoint gets a unit test in the same PR.
- Never commit secrets; read them from env vars.
- Prefer existing components in /components before building new ones.

Two more file behaviors are worth one mention each. Codebuff will not read files listed in your .gitignore by default, and you can add a .codebuffignore file with gitignore-style rules for anything extra you want hidden. And because Codebuff reads and writes files fluently, the vendor notes it will add knowledge as it goes — but instruction files are only ever updated, never created, unless you ask.

Which Commands Should You Learn First?

The whole command surface fits in one small table. These are the vendor's own tips, from the package README as mirrored on the npm page — no IDE, no menus, just these.

How Do Undo and Redo Keep You Safe?

Undo and redo revert or reapply the file changes Codebuff made during the conversation — they are your safety net, not the agent's. The package README is explicit about the scope: file changes, not terminal commands. So the habit to build is: watch the agent's first few edits on any task, and the moment it touches something it should not have, type undo before it builds on top of the mistake. This matters more in Codebuff than in a read-only assistant because the vendor's own README warns that Codebuff "will run commands in your terminal as it deems necessary to fulfill your request" — the agent has full terminal access, which is how it installs packages, runs your tests, and checks type errors, but it is also why Esc and Ctrl+C belong in muscle memory.

A concrete workflow that uses this well: ask Codebuff to "add the feature but stop before running the test suite", review the diff it produced, and only then say "run the tests now". Each checkpoint is cheap because the codebuff undo habit exists.

What Does Codebuff Cost?

Codebuff's pricing has two lanes, and both are vendor-claimed figures you should verify on the pricing page before you buy. Here is what the docs and repo say today.

Two money traps from the docs, once each. First, the free tier's balances read in hours, not dollars: 1 hour equals 5 Freebucks, and the model catalog moves — DeepSeek V4 Pro was recently retired and replaced by GLM 5.3 Flash, so re-check which models are free before a big task. Second, the deprecated Claude Pro/Max connection route can get your Anthropic account disabled under heavy use, per the vendor's own warning — do not wire your main Anthropic account into it.

Codebuff vs Claude Code: Which Should You Pick?

The honest comparison is short, because both are terminal coding agents and the real differences are the ecosystem and the billing. Codebuff is Codebuff AI's product with its own Strong subscription and its own free tier; Claude Code is Anthropic's agent and bills against your Anthropic plan. Both install from npm, both read instruction files, both edit files and run commands. Codebuff's differentiators from the vendor's own docs: it is Apache 2.0 open source with ~13,941 GitHub stars, it reads AGENTS.md (with CLAUDE.md fallback), and it has built-in undo/redo for file changes.

Where to learn the alternatives on this site: this OpenCode beginner guide covers the open-source terminal agent with its own plugin story, and this Google Antigravity beginner guide covers the agent that runs inside Google's IDE. Pick Codebuff when you want a standalone npm CLI with a free tier and no IDE attached; pick the others when you are already bought into their ecosystems.

How Do You Run Codebuff Agents from Your Own Code?

The @codebuff/sdk npm package lets you run Codebuff agents programmatically: install it, hand it an API key from codebuff.com/api-keys, and call run() with an agent and a prompt. The vendor's minimal example is worth quoting because every line is load-bearing — apiKey, cwd, the versioned agent id, and the event handler for streaming progress:

import { CodebuffClient } from '@codebuff/sdk'

const client = new CodebuffClient({
  apiKey: process.env.CODEBUFF_API_KEY,
  cwd: process.cwd(),
})

const result = await client.run({
  agent: 'codebuff/[email protected]',
  prompt: 'Create a simple calculator class',
  handleEvent: (event) => {
    console.log('Event:', event.type)
  },
})

The SDK's Agent Store supplies the agents: codebuff/base@latest for general work and codebuff/reviewer@latest for automated code review. You can continue a conversation by passing the previous run's state, define custom agents with an AgentDefinition (id, model, display name, tool names, instruction prompt), and cap work with maxAgentSteps (about 20 by default). The docs even include a GitHub Actions CI/CD example that stores CODEBUFF_API_KEY as a repository secret — the same pattern you would use for any paid API in automation.

Where Does Your Code Go? The Privacy Lesson

Prompts and relevant project context are sent to Freebuff and the model providers — that is the one sentence of the privacy docs that matters most. Your chats are also stored locally at ~/.config/manicode/projects/<your-project-name>/chats. The full picture from the FAQ: Freebuff uses your messages, agent traces, and files to run the service and respond to your requests, and it may analyze that data to personalize ads and train ad models — but it does not hand your uploaded files, project files, or connected repositories to advertising providers. It does not read files outside your project except in narrow cases: files an agent reads during the conversation, files you explicitly share, and settings like your agent instructions and skills. AI training of models happens only when a model or feature explicitly says data may be used for training — with the separate carve-out that Freebuff may use your data to train the models that choose and measure ads.

The practical reading: keep secrets out of prompts (use env vars and the instruction file to enforce that), and remember the free tier's trade — no card, but your usage feeds the ad models. This is the vendor's own disclosure, not fine-print paranoia.

What Are the Five Beginner Mistakes?

Every one of these is documented somewhere in the vendor's docs — which is what makes them mistakes rather than mysteries.

Sources

Codebuff FAQ (codebuff.com/docs/help/faq) — Apache 2.0 license statement; the current AGENTS.md/CLAUDE.md instruction-file behavior and the "knowledge.md is no longer read" note; ~/.AGENTS.md home file; .gitignore and .codebuffignore behavior; Codebuff Strong recommendation; Claude Pro/Max deprecation with the March 1st removal and the Anthropic-account warning; Freebuff free-tier terms; the Freebuff privacy and ad-model-training disclosures. Codebuff troubleshooting docs (codebuff.com/docs/advanced/troubleshooting) — the npm install command and permission fixes; the ~/.config/manicode storage layout; auto-update and codebuff --version; the local chat storage path; the Homebrew-vs-nvm update-loop diagnosis. Codebuff SDK docs (codebuff.com/docs/advanced/sdk) — the CodebuffClient example, the codebuff.com/api-keys page, the Agent Store agents, previousRun, custom AgentDefinition, and the CI/CD example. The CodebuffAI/freebuff GitHub repo (github.com/CodebuffAI/codebuff, redirecting to CodebuffAI/freebuff) — the 13,941-star snapshot, the free-tier hours/5-Freebucks figures, the paid-plan model list, and the DeepSeek V4 Pro retirement note, all as of November 3, 2026. The npm package page as mirrored by Socket.dev (socket.dev/npm/package/codebuff/overview/1.0.499, crawled November 1, 2026) — the "CLI tool that writes code for you" definition, the install and run commands, the /help, undo/redo, and Esc/Ctrl+C tips, and the package's own knowledge.md wording. Hiretop's 2024 Codebuff feature piece (hiretop.com/articles-archive/codebuff-ai-code-editor/) — historical confirmation that the npm install path and project-directory run flow have been stable since 2024.

Frequently Asked Questions

How much does Codebuff cost?

The free tier (Freebuff) costs nothing — no subscription, credits, or API key — and gives 5 hours of limited access a day, with text ads supporting the included models. The paid lane is the Codebuff Strong subscription, which the vendor says includes generous usage limits across all models; its price is not published on the docs pages, so check the pricing page before buying.

Is Codebuff open source?

Yes. The vendor's FAQ states it is Apache 2.0 licensed, and the GitHub repo (now at CodebuffAI/freebuff after a rename) holds roughly 13,941 stars as of November 2026.

What is the difference between knowledge.md and AGENTS.md in Codebuff?

AGENTS.md (with CLAUDE.md as fallback) is the current instruction file Codebuff reads in your project root; knowledge.md is no longer read, per the top answer on the vendor's own FAQ. Older docs and the package README still mention knowledge.md — treat those as stale.

Can I use my Claude Pro or Max subscription with Codebuff?

Not for long: connecting a Claude subscription is deprecated and will be removed on March 1st, and the vendor warns that heavy use through Codebuff got at least one user's Anthropic account disabled. The vendor recommends the Codebuff Strong subscription instead.

Does Codebuff work on Windows?

The install path is npm-based, which works on Windows, and the troubleshooting docs give a Windows-specific permission fix (takeown) alongside the Mac/Linux one. The core flow — install, run codebuff in your project directory, chat — is platform-agnostic.