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

> Update Freebuff to the latest version easily. Follow our NPM or source guide to install the newest release and get the latest features.

- Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff)
- Tags: how-to-guide
- Published: 2026-08-22

---

**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`](https://github.com/CodebuffAI/freebuff/blob/main/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**:

   ```bash
   freebuff --version
   ```

2. **Install the newest version**:

   ```bash
   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**:

   ```bash
   freebuff --version
   ```

### Option 2: Update from Source

For contributors working with the CodebuffAI/freebuff repository:

1. **Pull the latest commits**:

   ```bash
   git pull origin main
   ```

2. **Install dependencies with Bun**:

   ```bash
   bun install
   ```

3. **Rebuild the workspace**:

   ```bash
   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**:

   ```bash
   bun start-cli
   ```

## Verifying the Agent Runtime

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

```bash
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`](https://github.com/CodebuffAI/freebuff/blob/main/package.json).
- **Source contributors**: Execute `git pull origin main`, `bun install`, and `bun up` to rebuild the monorepo.
- **Key files**: [`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/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.