How to Update Freebuff to the Latest Version: NPM and Source Guide

To update Freebuff to the latest version, run npm install -g freebuff for global installations, or pull the latest commits and execute bun up when working from the source repository.

Freebuff is a TypeScript monorepo built on the Codebuff multi-agent framework and distributed as the freebuff CLI package. Keeping your installation current ensures access to the latest agent definitions, runtime improvements, and model catalog updates. Whether you installed via npm globally or cloned the CodebuffAI/freebuff repository for development, this guide covers the exact steps to update freebuff using the method that matches your setup.

Two Paths to Update Freebuff

The repository structure dictates two distinct update workflows. The npm package provides a compiled binary that delegates to the monorepo code at runtime, while the source installation requires rebuilding the workspace after pulling changes.

Global NPM Installation (End Users)

When installed via npm install -g freebuff, the CLI binary lives in your global node_modules. The package.json at the repository root defines this published package, which bundles the entry point that pulls in internal packages like cli/, sdk/, and agents/.

Source Installation with Bun (Contributors)

Developers working with the source code use Bun as the package manager. The monorepo contains packages spanning cli/, sdk/, common/, agents/, and packages/agent-runtime/. The bun.lock file locks dependencies, and the bun up command recompiles the entire workspace after updates.

Step-by-Step Update Instructions

Follow the procedure that matches your installation type to update freebuff without conflicts.

Option 1: Update via NPM

For end users who installed the CLI globally:

1. Check your current version:

   freebuff --version

2. Install the newest version:

   npm install -g freebuff

   This overwrites the previous binary and pulls in any new agent definitions from agents/, runtime updates from packages/agent-runtime/, or model catalog changes.

3. Verify the update:

   freebuff --version

Option 2: Update from Source

For contributors working with the CodebuffAI/freebuff repository:

1. Pull the latest commits:

   git pull origin main

2. Install dependencies with Bun:

   bun install

3. Rebuild the workspace:

   bun up

   This recompiles all packages—including the TUI client in cli/ and shared utilities in common/src/util/—and updates the bun.lock file.

4. Run the updated CLI:

   bun start-cli

Verifying the Agent Runtime

After you update freebuff, confirm the Codebuff runtime orchestrates agents correctly by executing a test command:

freebuff "Create a new README file for a TypeScript project"

This validates that the agent pipeline in agents/thinker/ and the runtime in packages/agent-runtime/ are functioning with the latest code.

Summary

• NPM users: Run npm install -g freebuff to fetch the latest published package defined in package.json.
• Source contributors: Execute git pull origin main, bun install, and bun up to rebuild the monorepo.
• Key files: package.json controls the npm release, while bun.lock ensures reproducible builds for source installations.
• Architecture: The CLI delegates to the Codebuff runtime, which loads agents from agents/ and executes tasks using the SDK in sdk/.

Frequently Asked Questions

How do I check which version of Freebuff is currently installed?

Run the command freebuff --version in your terminal. This displays the version defined in the package metadata, allowing you to compare against the latest release on npm or the commit hash in the git log for source installations.

Can I update Freebuff using npm if I originally installed it from source?

No, mixing package managers creates conflicts. If you cloned the CodebuffAI/freebuff repository and use bun start-cli, continue using git pull and bun up to update. Switching to npm install -g freebuff would create a separate global binary that doesn't reflect your local code changes in cli/ or agents/.

What does the bun up command do in the Freebuff repository?

The bun up command recompiles all packages in the TypeScript monorepo, including the TUI client in cli/, the SDK in sdk/, and the agent runtime in packages/agent-runtime/. It also updates the bun.lock file to reflect any new dependency versions pulled during bun install.

Why should I update Freebuff regularly?

Updating ensures you receive the latest agent implementations in agents/, security patches in common/src/util/, and model provider updates. The Codebuff runtime depends on these components to orchestrate tasks, and outdated versions may lack support for newer LLM features or contain resolved bugs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}