# How to Set Up a Development Environment for Freebuff: Complete 2024 Guide

> Set up your freebuff development environment easily. Clone the monorepo, install Bun, build the SDK and CLI, and launch the terminal UI with this 2024 guide.

- Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff)
- Tags: getting-started
- Published: 2026-08-21

---

**To set up a development environment for freebuff, clone the TypeScript monorepo, install Bun 1.3.14, run `bun install` to link workspaces, build the SDK with `bun run build:sdk`, compile the CLI binary via `bun run build:freebuff`, and launch the terminal UI using `bun start-cli`.**

Freebuff is a **TypeScript monorepo** hosted at `CodebuffAI/freebuff` that uses the **Bun** runtime and package manager to orchestrate multiple workspaces. Setting up a development environment for freebuff requires understanding its workspace architecture, which separates the CLI, SDK, agent runtime, and shared utilities into distinct but interdependent packages.

## Prerequisites and System Requirements

Before installing dependencies, verify your system meets the toolchain requirements defined in the repository configuration.

**Bun Runtime:** The project strictly requires **Bun 1.3.14** as specified in [`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/package.json) lines 69-71. Using older versions causes build failures due to monorepo workspace resolution differences. Install Bun via the official installer and verify the version matches the `engines` field.

**Docker:** While not required for basic code development, Docker is mandatory for running the full integration and end-to-end test suites. The repository spins up containers for certain `evals` tests, and these will fail without a running Docker daemon.

**Environment File:** For complete integration testing or running cloud agent features, create a `.env.local` file in the repository root. Copy the example configuration: `cp .env.example .env.local`.

## Understanding the Monorepo Structure

Freebuff organizes its codebase into Yarn-/Bun-workspaces declared in the root [`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/package.json) lines 7-18. Understanding this layout prevents import errors when modifying cross-package dependencies:

- **`cli/`** — The terminal UI for the Freebuff CLI
- **`sdk/`** — Re-usable JavaScript/TypeScript SDK consumed by the CLI and external users  
- **`common/`** — Shared types, utilities, and schemas
- **`agents/`** — Public agent definitions (the "brains" performing research and editing)
- **`packages/agent-runtime/`** — Core runtime that loads agents, manages tools, and handles orchestration
- **`packages/code-map/`** — Source code parsing and mapping utilities
- **`packages/llm-providers/`** — Shims for interacting with LLM back-ends
- **`freebuff/`** — Built binary and high-level orchestration for desktop, web, and cloud deployments

This modular structure allows parallel development across the CLI, SDK, and runtime components while maintaining type consistency through shared [`tsconfig.base.json`](https://github.com/CodebuffAI/freebuff/blob/main/tsconfig.base.json) settings.

## Step-by-Step Installation

Execute these commands sequentially to bootstrap your local environment:

```bash

# 1. Clone the monorepo

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

# 2. Install Bun 1.3.14 if not already present

curl -fsSL https://bun.sh/install | bash
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

# 3. Install and link all workspace dependencies

bun install

```

The `bun install` command automatically resolves inter-workspace dependencies and links local packages according to the workspace glob patterns in [`bunfig.toml`](https://github.com/CodebuffAI/freebuff/blob/main/bunfig.toml).

## Building Core Components

After installation, you must compile the TypeScript sources before running the application. The build process follows a strict dependency order: the SDK must build before the CLI.

### Compile the SDK

The CLI depends on the SDK's type definitions, making this step mandatory:

```bash
bun run build:sdk

```

This command traverses the `sdk/` workspace and emits compiled JavaScript to the distribution folder, enabling the CLI to import the latest API definitions.

### Build the Freebuff Binary

Generate the executable CLI using the build script defined in [`freebuff/cli/build.ts`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/cli/build.ts):

```bash
bun run build:freebuff

```

This produces the `freebuff` binary that serves as the entry point for the terminal application. The build script handles bundling of the `cli/` workspace with its runtime dependencies.

## Running the Development Server

Launch the CLI in hot-reload development mode to test changes instantly:

```bash
bun start-cli

```

This command starts the TUI (Terminal User Interface) with file-watching enabled, automatically restarting the process when you modify source files in the `cli/` or `sdk/` directories.

To run **desktop** or **cloud** agents locally, enable the special mode flag:

```bash
FREEBUFF_MODE=true bun start-cli

```

This environment variable activates additional orchestration features required for non-terminal deployments.

## Testing Your Setup

Validate your development environment by running the lightweight benchmark suite:

```bash
bun run buffbench

```

This executes the `evals/run-buffbench` harness, which tests agent definitions against curated benchmarks. Note that tests requiring Docker will skip if the daemon is unavailable, but the core unit tests will execute.

For full e2e validation including containerized integration tests, ensure Docker is running and your `.env.local` file contains the necessary configuration variables referenced in [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md).

## Summary

- **Clone** the `CodebuffAI/freebuff` repository and ensure Bun 1.3.14 is installed.
- **Install** dependencies using `bun install` to automatically link all monorepo workspaces.
- **Build** the SDK first (`bun run build:sdk`), then the CLI binary (`bun run build:freebuff`) as defined in [`freebuff/cli/build.ts`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/cli/build.ts).
- **Run** the development server with `bun start-cli` for hot-reload testing.
- **Test** your setup using `bun run buffbench`, and ensure Docker is available for integration tests.
- **Configure** `.env.local` for features requiring external API keys or cloud agent support.

## Frequently Asked Questions

### What version of Bun is required for freebuff?

The repository enforces **Bun 1.3.14** strictly, as defined in [`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/package.json) lines 69-71. Using an older version will cause workspace resolution failures during `bun install`. Always verify your installation with `bun --version` before proceeding.

### Do I need Docker to develop freebuff locally?

You only need Docker for **integration and e2e testing**. Basic development—including building the CLI, modifying agents, and running unit tests—works without Docker. However, the `evals` test harness and certain cloud agent features require containerized services that fail if Docker is not running.

### How do I run the desktop or cloud agents locally?

Prepend the `FREEBUFF_MODE=true` environment variable when starting the CLI: `FREEBUFF_MODE=true bun start-cli`. This flag activates the orchestration layer required for desktop and cloud deployments, as implemented in the `packages/agent-runtime/` workspace.

### Where are the agent definitions located in the codebase?

Public agent definitions reside in the **`agents/`** workspace, with core type definitions in [`agents/types/agent-definition.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/agent-definition.ts). The runtime loads these definitions from `packages/agent-runtime/`, which manages tool registration and task orchestration for each agent.