The most latest version of the Codebuff client can be found on the npm page.

Run codebuff --version to make sure you're on the latest version.

Note: Codebuff should automatically install the latest version. If you're still having issues, see below.

If you see the npm install run but Codebuff still isn't at the latest version, this is most likely an issue with npm's cache. Try running npm cache clean --force and then npm install -g codebuff.

If npm install -g codebuff gave you an error regarding permissions, try using setting the owner of that directory to your user.

Mac/Linux: sudo chown -R $(whoami) <directory>

Windows: cmd takeown /F <directory> /R /D Y

Otherwise, try reinstalling node with nvm or fnm. Then run the codebuff install command again.

Your conversation history with Codebuff is stored locally (and nowhere else) at ~/.config/manicode/projects/<your-project-name>/chats.

If you need help, we'd love if you include a copy of your recent chats for us to help you troubleshoot!

If you see a message like this:

/Users/<youruser>/Library/pnpm/global/5/.pnpm/codebuff@someversion/node_modules/codebuff/dist/common/websockets/websocket-client.js:158
                    reject(new Error(`Websocket message with txid ${txid} timed out.`));                           ^

Error: Websocket message with txid 32 timed out.
    at Timeout._onTimeout (/Users/<youruser>/Library/pnpm/global/5/.pnpm/codebuff@someversion/node_modules/codebuff/dist/common/websockets/websocket-client.js:158:28)
    at listOnTimeout (node:internal/timers:594:17)
    at process.processTimers (node:internal/timers:529:7)

Node.js v22.12.0

it means you're having connection issues. In that case, try:

1. Check your internet connection.
2. Try logging out and back in with logout followed by login.

If Codebuff keeps trying to update itself in an endless loop, there could be several potential causes. Below are known issues and their solutions:

One common cause is having conflicting Node/npm installations on your system, particularly between Homebrew and nvm. Here's how to diagnose and fix this:

1. Check your Node and npm paths:

   bash

   which node
   which npm

   If these point to Homebrew paths (e.g., /opt/homebrew/bin/) instead of nvm paths (e.g., ~/.nvm/versions/), that's the issue.

2. Check what packages depend on Node through Homebrew:

   bash

   brew uninstall node

   This will show you any packages that depend on Node.

3. If you don't need those packages anymore, you can uninstall them. This will automatically remove Node as a dependency.

4. After this cleanup, your which node and which npm commands should point to your nvm installation, and Codebuff should work as expected.

If you see "command not found" when trying to run Codebuff:

1. Ensure Codebuff is installed globally: npm install -g codebuff
2. Check that your PATH includes npm's global bin directory
3. Try running which codebuff to verify the installation location

If you see an error like this:

npm ERR! code ENOTEMPTY
npm ERR! syscall rename
npm ERR! path /some/path/to/node_modules/codebuff
npm ERR! dest /some/path/to/node_modules/.codebuff-SOMEHASH
npm ERR! errno -66
npm ERR! ENOTEMPTY: directory not empty, rename '/some/path/to/node_modules/codebuff' -> '/some/path/to/node_modules/.codebuff-SOMEHASH'

It means you have a directory named .codebuff-SOMEHASH in your node_modules directory. This is a temporary directory created by npm when installing packages. You can safely delete this directory and try again:

rm -rf /some/path/to/node_modules/.codebuff-SOMEHASH

If you're still experiencing issues:

1. Join our Discord community for real-time help from other users!
2. Contact us at support@codebuff.com – please note we prioritize paying users, but we'll likely reply within a week.

Codebuff starts by running through the source files in all subdirectories and parsing them with tree-sitter. We use this information to help find relevant files to you requests.

We have a stateless server that passes messages along to Anthropic, OpenAI, or Gemini and websockets to ferry data back and forth to clients. It effectively acts as a proxy between the client and our LLM providers.

We use a fast model to pick the relevant files, and we load them into context Claude Sonnet responds with the right edit. This main agent can also delegate to other agents, as when it does its planning step, or when searching for files.

We use multiple models to get better results: Gemini 2.5 Pro for deep thinking, Claude Sonnet for most implementation work, Gemini Flash for quick tasks. We also use a speculative decoding model from Relace AI for fast file rewrites. We use o3-mini as a file editing fallback, and gpt-4o-mini for some trivial tasks. In other words, we carefully pick the best models for each job.

We have several modes which change the model setup to achieve different goals:

• --lite: Uses Gemini 2.5 Flash Thinking instead of Sonnet (~1/5 the cost). It also pulls fewer files, meaning that the context cost will be smaller.
• --max: Uses a hybrid approach with Gemini 2.5 Pro + Sonnet to better handle complex problems and pulls more files on your codebase.
• --experimental: Uses cutting-edge experimental features and the most advanced models available (like Gemini 2.5 Pro Experimental). This mode is for users who want to try the latest AI capabilities, though it may be less stable.

In general, Codebuff works quite well in larger projects. For example, we've pulled Codebuff into the VSCode repo (millions of lines of code) and have had no issues in our testing. That said, if you're noticing Codebuff getting stuck/forgetting context too soon or using a ton of credits, here are some tips to help you mitigate those issues.

When working with large codebases, you can start Codebuff from specific directories to maintain focus:

cd backend
codebuff

Or equivalently without changing directories:

codebuff --cwd backend

This helps Codebuff concentrate on relevant files and provide more targeted assistance.

For large projects:

• Create separate knowledge.md files in key directories, like so:

  text

  services/
  auth-service/
      knowledge.md
      src/
  user-service/
      knowledge.md
      src/
  api-gateway/
      knowledge.md
      src/

• Focus each knowledge file on its directory's specific concerns

• Link related concepts across knowledge files

• Keep root knowledge.md for project-wide concepts

When working with large codebases:

• Be specific about file locations
• Reference related files explicitly
• Break large changes into smaller, focused requests
• Use the --max mode for better context understanding by loading more files

• Leverage your .codebuffignore and .gitignore files to exclude irrelevant directories
• Start in subdirectories when possible
• Break large refactoring tasks into smaller chunks
• Let Codebuff handle file discovery instead of listing all files

Anthropic recently released Claude Code, their own AI coding assistant.

Both Codebuff and Claude Code:

• Run in your terminal for a seamless coding experience
• Understand your entire codebase context
• Can edit files and execute terminal commands
• Use Claude Sonnet as their primary model

Codebuff might be a better choice if you value:

• Speed: Codebuff is nearly 4 times faster
• Cost: Codebuff is one third the cost of Claude Code for equivalent tasks and even less for back-and-forth conversation
• Codebase Analysis: Codebuff pulls more context from scanning your entire codebase, rather than file-by-file. Codebuff also blends different models based on their strengths to provide more accurate results.
• Staying in Flow: Codebuff requires fewer confirmation prompts for file edits and command execution.
• Focused changes: Codebuff does just what you asked for, while Claude Code will often get carried away editing more and more files.
• SDK and Programmatic Access: Codebuff provides a full TypeScript SDK for programmatic integration, allowing you to create custom workflows and embed AI coding capabilities into your own tools.
• Advanced Agent System: Create custom agents with TypeScript generator functions, spawn subagents, and orchestrate complex multi-step workflows that go far beyond simple chat interactions.

Claude Code might be a better choice if you:

• You require first-party Anthropic integration (no intermediary/proxy) for procurement, data handling, or legal reasons
• You need enterprise security/compliance controls directly from Anthropic (e.g., SOC 2/ISO programs, data-retention controls, private/VPC networking options)
• Your org needs centralized admin controls within Anthropic's ecosystem (SSO, RBAC, governance, auditability)
• You prioritize early access to Anthropic model capabilities and first-party tooling

Both Codebuff and Claude Code are powerful AI coding assistants that can significantly boost your productivity. Codebuff offers more flexible pricing and performance options, while Claude Code provides direct integration with Anthropic's ecosystem.

Codebuff can be configured using a codebuff.json file in your project root. This file allows you to customize various aspects of how codebuff operates in your project.

Configuring codebuff helps you create a seamless development environment where codebuff becomes your central development hub. Instead of juggling multiple terminal windows and manually starting various services, you can let codebuff manage your entire development workflow.

You can configure startup processes, which will run in the background every time codebuff starts! When you use this feature, codebuff will automatically:

1. Start your development processes:
   • Servers (frontend, backend, etc.)
   • Launch your database
   • Run any other necessary background services
2. Manage all these processes for you
3. Read the logs and outputs and automatically handle any errors that arise

This means you can start your day with a single codebuff command, write code with codebuff's assistance, and when you're done, closing codebuff will cleanly shut down all your development processes. No more scattered terminal windows or forgotten running processes!

The configuration file follows this structure:

{
  "description": "Defines the overall Codebuff configuration file (e.g., codebuff.json). This schema defines the top-level structure of the configuration. This schema can be found at https://www.codebuff.com/config",
  "type": "object",
  "properties": {
    "description": {
      "description": "Does nothing. Put any thing you want here!"
    },
    "startupProcesses": {
      "description": "An array of startup processes.",
      "type": "array",
      "items": {
        "description": "Defines a single startup process.",
        "type": "object",
        "properties": {
          "name": {
            "description": "A user-friendly name for the process. Should be one word and unique.",
            "type": "string",
            "minLength": 1
          },
          "command": {
            "description": "The actual shell command to execute.",
            "type": "string",
            "minLength": 1
          },
          "cwd": {
            "description": "The working directory from which to run the command.",
            "type": "string"
          },
          "enabled": {
            "description": "Whether this process should be run",
            "default": true,
            "type": "boolean"
          },
          "stdoutFile": {
            "description": "Path to write the process's stdout. If not specified, stderr is not stored.",
            "type": "string"
          },
          "stderrFile": {
            "description": "Path to write the process's stderr. If not specified, stderr will be put into the stdoutFile.",
            "type": "string"
          }
        },
        "required": [
          "name",
          "command"
        ]
      }
    },
    "fileChangeHooks": {
      "description": "An array of commands to run on file changes.",
      "type": "array",
      "items": {
        "description": "Defines a single file change hook.",
        "type": "object",
        "properties": {
          "name": {
            "description": "A user-friendly name for the hook. Should be one word and unique.",
            "type": "string",
            "minLength": 1
          },
          "command": {
            "description": "The actual shell command to execute.",
            "type": "string",
            "minLength": 1
          },
          "cwd": {
            "description": "The working directory from which to run the command.",
            "type": "string"
          },
          "filePattern": {
            "description": "Glob pattern to match files.",
            "type": "string"
          },
          "enabled": {
            "description": "Whether this command should be run",
            "default": true,
            "type": "boolean"
          }
        },
        "required": [
          "name",
          "command"
        ]
      }
    },
    "maxAgentSteps": {
      "description": "Maximum number of turns agent will take before being forced to end",
      "default": 25,
      "type": "number"
    },
    "baseAgent": {
      "description": "Specify default base agent",
      "type": "string"
    },
    "spawnableAgents": {
      "description": "Specify complete list of spawnable agents for the base agent",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Here's an example configuration file that starts a development server and database:

{
"description": "Development environment configuration",
"startupProcesses": [
{
"name": "nextjs-server",
"command": "npm run dev",
"cwd": "./web",
"enabled": true
},
{
"name": "database",
"command": "docker-compose up",
"cwd": "./backend/db",
"stdoutFile": "logs/db-stdout.log",
"stderrFile": "logs/db-stderr.log"
}
]
}

1. Process Names: Use descriptive names that clearly indicate what each process does.
2. Working Directories: Use relative paths for cwd to maintain portability.
3. Logging: Consider using stdoutFile and stderrFile for important processes to help with debugging.
4. Process Management: Use the enabled flag to temporarily disable processes without removing them from the configuration.

If your startup processes aren't working as expected:

1. Check that the commands work when run manually from the specified working directory
2. Verify that any referenced paths (for logs or cwd) exist and are writable
3. Check the process output in the specified log files if you've configured them
4. Make sure the JSON syntax in your configuration file is valid

Need more help? Check out our Troubleshooting guide or join our Discord community.