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

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 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 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 settings.

Step-by-Step Installation

Execute these commands sequentially to bootstrap your local environment:

# 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.

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:

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:

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:

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:

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:

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.

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.
• 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 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. The runtime loads these definitions from packages/agent-runtime/, which manages tool registration and task orchestration for each agent.

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