# What Technologies Power the Freebuff Project: A Deep Dive into the CodebuffAI Stack

> Explore the CodebuffAI stack powering the Freebuff project. Discover the TypeScript monorepo, Bun runtime, and composable agent-runtime orchestrating LLM agents.

- Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff)
- Tags: deep-dive
- Published: 2026-09-01

---

**Freebuff is built as a modern TypeScript monorepo running on Bun, featuring a composable agent-runtime that orchestrates multiple specialized agents across LLM providers.**

The Freebuff project from CodebuffAI represents a sophisticated approach to AI-driven coding assistance. Its technology stack combines a fast JavaScript runtime, strongly-typed workspaces, and a modular architecture for multi-agent orchestration. This article examines each technological pillar based on the actual source code implementation.

## Core Runtime and Package Management

### Bun as the Foundation

Freebuff targets **Bun** as its exclusive runtime and package manager. The [`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/package.json) at the repository root specifies:

```json
{
  "engines": {
    "node": ">=20",
    "bun": ">=1.0.0"
  }
}

```

This requirement enables fast package installation, native TypeScript execution, and streamlined build processes throughout the monorepo.

## Monorepo Architecture

### Workspace Structure

Freebuff organizes code into distinct TypeScript workspaces defined in [`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/package.json):

- `agents/` – Specialized agent implementations
- `cli/` – Command-line interface with interactive terminal UI
- `common/` – Shared utilities across packages
- `sdk/` – Public JavaScript/TypeScript SDK (`@codebuff/sdk`)
- `packages/*/` – Core runtime modules
- `scripts/tmux/` – Tmux-based testing utilities
- `freebuff/` – Main application entry point

This structure enforces strong typing boundaries while allowing cross-package imports through workspace references.

## Interactive Interfaces

### OpenTUI and React CLI

The `cli/` directory implements two interface layers:

- **OpenTUI** – Terminal-based interactive UI for command-line usage
- **React** – Desktop and web front-end components

These share underlying logic but adapt presentation for their respective environments. Both interfaces consume the same agent runtime and LLM provider abstractions.

## The Composable Agent Runtime

### Core Orchestration Engine

Located in `packages/agent-runtime/`, this module handles the heart of Freebuff's multi-agent capabilities:

- **Tool execution** – Agents invoke file operations, shell commands, and browser tools
- **Parallel work coordination** – Multiple agents operate simultaneously in isolated contexts
- **Result review** – Self-correction loops verify and refine outputs

The runtime abstracts agent lifecycle management, allowing developers to instantiate agents programmatically via the SDK or through the interactive CLI.

### Code-Map Helpers

The `packages/code-map/` workspace provides static analysis utilities that enable agents to:

1. Discover relevant source files within a codebase
2. Parse file structures without full execution
3. Build context windows for LLM prompts

This capability allows agents to "understand" project structure before making edits.

### LLM Provider Shims

`packages/llm-providers/` contains adapter implementations for various model providers:

| Provider | Adapter Location |
|----------|------------------|
| GLM | `packages/llm-providers/glm/` |
| GPT | `packages/llm-providers/openai/` |
| DeepSeek | `packages/llm-providers/deepseek/` |

Each adapter implements a unified interface, letting the runtime switch providers without changing orchestration logic.

## Developer Integration

### JavaScript/TypeScript SDK

The `@codebuff/sdk` package in `sdk/` exposes programmatic access to Freebuff's capabilities. A minimal implementation appears in [`sdk/examples/readme-example-1.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/examples/readme-example-1.ts):

```typescript
import { CodebuffClient } from '@codebuff/sdk'

async function demo() {
  const client = new CodebuffClient({
    apiKey: process.env.CODEBUFF_API_KEY,
    cwd: process.cwd(),
  })

  const run1 = await client.run({
    agent: 'codebuff/base@0.0.16',
    prompt: 'Create a simple calculator class in TypeScript',
    handleEvent: e => console.log('Event:', JSON.stringify(e)),
  })

  await client.run({
    agent: 'codebuff/base@0.0.16',
    prompt: 'Add unit tests for the calculator',
    previousRun: run1,
    handleEvent: e => console.log('Event:', JSON.stringify(e)),
  })
}

demo()

```

The `run()` method accepts:
- `agent` – Versioned agent identifier
- `prompt` – Natural language instruction
- `previousRun` – Session continuity reference
- `handleEvent` – Callback for runtime events

## Specialized Utilities

### Tmux Testing Infrastructure

The `scripts/tmux/` directory contains helpers for automated testing of interactive CLI sessions. These scripts drive terminal interactions programmatically, enabling reliable regression testing for features that require user input simulation.

### Canvas and GIF Encoding

Dependencies in [`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/package.json) include canvas and GIF encoder libraries (lines 32-35) that power:

- Terminal graphics rendering in OpenTUI
- GIF export functionality for sharing agent sessions

## Execution Modes

Freebuff adapts its parallelization strategy to deployment context:

- **Desktop mode** – Isolates agents in separate local workspaces
- **Web/cloud mode** – Provides sandboxed cloud environments for each agent

Both modes leverage the same `packages/agent-runtime/` core, differing only in process isolation implementation.

## Summary

- **Bun runtime** provides fast, modern JavaScript/TypeScript execution
- **TypeScript monorepo** with strict workspace boundaries enables scalable development
- **Composable agent-runtime** in `packages/agent-runtime/` handles multi-agent orchestration
- **LLM provider shims** abstract model differences behind unified interfaces
- **@codebuff/sdk** exposes full functionality to programmatic consumers
- **OpenTUI + React** deliver interactive experiences across terminal and desktop/web

## Frequently Asked Questions

### Does Freebuff require Node.js or only Bun?

Freebuff requires **Bun specifically**. While the [`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/package.json) specifies `node >= 20` as a fallback compatibility marker, the project depends on Bun's native TypeScript support and package management for proper operation.

### Can I use Freebuff with my own LLM API keys?

Yes. The SDK's `CodebuffClient` accepts configuration including API keys, and the `packages/llm-providers/` architecture supports multiple providers. You can instantiate the client with your own credentials as shown in [`sdk/examples/readme-example-1.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/examples/readme-example-1.ts).

### What is the difference between agents in the `agents/` workspace and the agent-runtime?

The `agents/` workspace contains **specialized agent implementations** (behavior definitions, prompts, tool selections), while `packages/agent-runtime/` provides the **execution engine** that instantiates and orchestrates these agents. Think of agents as configurations and the runtime as the kernel that runs them.

### How does Freebuff handle testing of interactive CLI features?

Through **Tmux-based automation** in `scripts/tmux/`. These scripts create controlled terminal sessions, send simulated keystrokes, and capture output for assertion—enabling reliable testing of features like progress indicators, prompts, and real-time event streams.