How to Install CodebuffAI/freebuff Locally: Global CLI vs. Development Setup

Install the Freebuff CLI globally with npm install -g freebuff for immediate use, or clone the repository and run bun install followed by bun up to build the full TypeScript monorepo locally for development.

Freebuff is a TypeScript monorepo built with the Bun runtime that provides an agent-powered coding assistant through a terminal-based UI. Whether you want to install the published CLI or contribute to the open-source project, this guide covers the exact steps documented in the README.md and CONTRIBUTING.md files.

Global CLI Installation for End Users

The simplest way to install CodebuffAI/freebuff locally is through the npm registry. This method installs the pre-built CLI globally on your system without requiring the full source code.

Run the following command to install the CLI:

npm install -g freebuff

Once installed, navigate to any project directory and launch the agent-powered assistant:

cd <your-project>
freebuff

This approach installs the TUI (terminal user interface) built with OpenTUI and React, which is housed in the cli/ directory of the repository. According to the README.md Quick Start section, this is the recommended path for users who want to use Freebuff without modifying its source code.

Local Development Installation for Contributors

Developers who want to modify agents, add tools, or extend the SDK must set up the full monorepo locally. The repository architecture splits functionality across several modules including cli/, sdk/, common/, agents/, packages/agent-runtime/, and packages/code-map/.

Clone the Repository

Start by cloning the GitHub repository and entering the project directory:

git clone https://github.com/CodebuffAI/freebuff.git
cd freebuff

Install Dependencies with Bun

Because Freebuff is built specifically for the Bun runtime, you must use bun rather than npm or yarn to install dependencies:

bun install

This command pulls in all workspace packages defined across the monorepo structure, as documented in the CONTRIBUTING.md file under the Install dependencies section.

Build and Link Workspace Packages

After installation, build all packages and link them within the workspace using:

bun up

The bun up command compiles the TypeScript sources and establishes internal dependencies between the sdk/, common/, and packages/* directories. This step is essential before running the CLI from source.

Launch the Local CLI

To run the TUI without publishing to npm, use the start-cli script:

bun start-cli

As noted in the README.md section "Start the CLI separately," this command boots the React-based terminal interface using your local source changes rather than a globally installed package.

Optional Development Tasks

Once you have installed CodebuffAI/freebuff locally, several utility commands help validate your setup or prepare changes for submission.

• Run the test suite: Execute bun test to run all unit and integration tests (see cli/README.md → Testing).
• Build the SDK: Run bun run build:sdk to compile the @codebuff/sdk package distributed to npm.
• Build the binary: Run bun run build:freebuff to create a standalone binary of the CLI.

Some internal services, such as Docker-based development environments, require a .env.local file. However, according to the contributing guide, Docker and .env.local are only needed for the full suite of backend services; the CLI itself functions after completing the core installation steps above.

Summary

• End users should run npm install -g freebuff to install the CLI globally and invoke it with the freebuff command.
• Contributors must clone the repository, run bun install to fetch dependencies, then bun up to build the monorepo workspace.
• The bun start-cli command runs the local TUI without requiring global installation.
• Testing (bun test) and building (bun run build:sdk) require the full local development setup.

Frequently Asked Questions

What is the difference between global and local installation of Freebuff?

Global installation via npm install -g freebuff provides a ready-to-use CLI for end users who only want to run the agent assistant. Local installation requires cloning the repository and using Bun to install dependencies, which is necessary for developers who need to modify the sdk/, agents/, or packages/agent-runtime/ source code.

Do I need Docker to run Freebuff locally?

No. While some internal services documented in CONTRIBUTING.md require Docker and a .env.local file for the full backend suite, the CLI and core agent runtime work after running bun install and bun up. Docker is only necessary if you plan to run specific containerized development services.

How do I run tests after installing Freebuff locally?

After completing the local development installation, execute bun test from the repository root. This command runs the test suite defined across the monorepo workspaces and is documented in the cli/README.md file under the Testing section.

Can I use npm or yarn instead of Bun to install Freebuff locally?

No. Freebuff is built specifically for the Bun runtime, and the monorepo workspace configuration relies on Bun's package manager. You must use bun install rather than npm install or yarn when setting up the development environment locally, though end users can install the published CLI via npm install -g freebuff.

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