# What Are the Main Components of Freebuff?

> Explore the 8 core components of Freebuff including CLI SDK Agent Runtime LLM Providers and more Discover how this composable TypeScript monorepo powers AI coding agents

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

---

**Freebuff organizes its architecture into eight distinct components—CLI, SDK, Common utilities, Agent Runtime, LLM Providers, Code Map, agent definitions, and infrastructure scripts—that together form a composable TypeScript monorepo for executing AI-powered coding agents.**

Freebuff, developed by CodebuffAI, is an open-source agent framework structured as a TypeScript monorepo. Understanding the main components of Freebuff requires examining how it separates concerns across discrete packages, enabling developers to run agents via terminal UI, embed them via SDK, or extend the runtime with new capabilities. Each component resides in a specific directory and exposes well-defined APIs for interacting with the agent execution stack.

## CLI and SDK: The Interface Layer

Freebuff provides two primary entry points for users: an interactive command-line interface and a programmable software development kit.

### CLI Package (`cli/`)

The **CLI** package, located in `cli/`, implements the interactive terminal UI that parses user commands and drives the TUI (Terminal User Interface). The bootstrap logic in [`cli/src/entry.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/entry.ts) initializes the system by importing `runCLI` from [`common/src/utils/ask-user-bridge.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/utils/ask-user-bridge.ts) and `loadAgent` from [`packages/agent-runtime/src/loader.ts`](https://github.com/CodebuffAI/freebuff/blob/main/packages/agent-runtime/src/loader.ts). This sequence establishes the connection between user input and the agent runtime, launching the specified agent into an interactive session.

### SDK Package (`sdk/`)

The **SDK**, housed in `sdk/`, exposes the Freebuff runtime as a reusable JavaScript/TypeScript library. The public API defined in [`sdk/src/index.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/src/index.ts) includes the `createAgentRunner()` function, which allows external applications to instantiate and execute agents programmatically without invoking the interactive CLI. This enables embedding Freebuff capabilities into IDE extensions, build tools, or automated workflows.

## Runtime Infrastructure

Three packages within `packages/` handle the core execution mechanics, AI provider abstraction, and code comprehension.

### Agent Runtime (`packages/agent-runtime/`)

The **Agent Runtime** serves as the execution engine responsible for loading agent definitions and orchestrating LLM calls. The [`packages/agent-runtime/src/loader.ts`](https://github.com/CodebuffAI/freebuff/blob/main/packages/agent-runtime/src/loader.ts) file implements the `loadAgent()` function, which dynamically pulls agent configurations from the `agents/` directory, resolves their tool dependencies, and prepares the execution context for the runtime.

### LLM Providers (`packages/llm-providers/`)

To maintain provider independence, the **LLM Providers** package abstracts various AI services behind a unified interface. Located in `packages/llm-providers/`, this component contains adapter implementations for OpenAI, Gemini, Claude, and other services. The file [`packages/llm-providers/src/openai.ts`](https://github.com/CodebuffAI/freebuff/blob/main/packages/llm-providers/src/openai.ts) specifically handles OpenAI API communication, allowing the Agent Runtime to switch between providers without modifying agent-specific logic.

### Code Map (`packages/code-map/`)

The **Code Map** component enables agents to understand repository structures by parsing and analyzing source code. Utilities in `packages/code-map/` provide structural context about codebases, allowing agents to navigate files and comprehend architectural patterns during their execution cycle.

## Agent Definitions and Shared Resources

### Agents Directory (`agents/`)

The `agents/` directory contains public agent specifications, each defining system prompts, available tools, and execution logic. For example, [`agents/tmux-cli.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/tmux-cli.ts) defines the **tmux-cli** agent with its specialized toolset for terminal session management, while other files define agents like **thinker**. These definitions are loaded dynamically by the Agent Runtime at execution time.

### Common Utilities (`common/`)

The **Common** package in `common/` houses shared types, utilities, and helper functions used across the CLI, SDK, and runtime. The [`ask-user-bridge.ts`](https://github.com/CodebuffAI/freebuff/blob/main/ask-user-bridge.ts) utility in `common/src/utils/` facilitates bidirectional communication between the runtime and user interfaces. Additional helpers like `utcDays` provide standardized date manipulation capabilities used throughout the system.

### Root CLI Entry (`freebuff/`)

The top-level `freebuff/` directory serves as the root entry point that exposes the global `freebuff` command. This component ties together the CLI, SDK, and runtime into a cohesive executable that users install and invoke from their terminal.

## Infrastructure and Testing Support

### Tmux Helpers (`scripts/tmux/`)

The `scripts/tmux/` directory contains infrastructure scripts for managing terminal sessions during end-to-end tests and demonstrations. The [`scripts/tmux/tmux-start.sh`](https://github.com/CodebuffAI/freebuff/blob/main/scripts/tmux/tmux-start.sh) script automates Tmux session spawning, allowing agents to interact with controlled terminal environments for testing terminal-specific behaviors.

## Component Integration Examples

The following examples demonstrate how the main components of Freebuff interact in practice.

### Initializing the CLI with the Agent Runtime

This pattern from [`cli/src/entry.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/entry.ts) shows how the CLI bootstraps the runtime:

```typescript
// entry.ts – CLI entry point
import { runCLI } from '../common/src/utils/ask-user-bridge';
import { loadAgent } from '../../packages/agent-runtime/src/loader';

async function main() {
  const agent = await loadAgent('tmux-cli');   // pulls agent definition from agents/
  await runCLI(agent);                         // starts the TUI and invokes the runtime
}
main();

```

### Programmatic Agent Execution via SDK

To invoke an agent without the interactive CLI, use the SDK's `createAgentRunner()`:

```typescript
import { createAgentRunner } from '@freebuff/sdk';

async function demo() {
  const runner = await createAgentRunner('thinker');
  const result = await runner.run({ prompt: 'Explain the Unix pipe command.' });
  console.log(result);
}
demo();

```

### Importing Shared Utilities

Access cross-cutting utilities from the Common package:

```typescript
import { utcDays } from '@freebuff/common/util/utc-days';

console.log(utcDays(new Date()));

```

## Summary

- **Freebuff** is structured as a TypeScript monorepo with eight core components that separate interface, runtime, and infrastructure concerns.
- The **CLI** (`cli/`) provides the interactive terminal experience, while the **SDK** (`sdk/`) enables programmatic integration via `createAgentRunner()`.
- The **Agent Runtime** (`packages/agent-runtime/`) handles dynamic agent loading through `loadAgent()` in [`packages/agent-runtime/src/loader.ts`](https://github.com/CodebuffAI/freebuff/blob/main/packages/agent-runtime/src/loader.ts).
- **LLM Providers** (`packages/llm-providers/`) abstract multiple AI services, with specific implementations like [`packages/llm-providers/src/openai.ts`](https://github.com/CodebuffAI/freebuff/blob/main/packages/llm-providers/src/openai.ts).
- **Code Map** (`packages/code-map/`) supplies repository parsing for agent context awareness.
- **Agent definitions** (`agents/`) store specifications for agents like `tmux-cli` and `thinker`.
- **Common** (`common/`) utilities like [`ask-user-bridge.ts`](https://github.com/CodebuffAI/freebuff/blob/main/ask-user-bridge.ts) and the **Root CLI** (`freebuff/`) integrate the system.
- **Infrastructure scripts** (`scripts/tmux/`) support testing environments with tools like [`tmux-start.sh`](https://github.com/CodebuffAI/freebuff/blob/main/tmux-start.sh).

## Frequently Asked Questions

### What is the difference between the Freebuff CLI and SDK?

The **CLI** provides an interactive terminal interface that handles user input parsing and TUI rendering for end-users. The **SDK** exposes the same underlying runtime capabilities as a JavaScript/TypeScript library, allowing developers to embed Freebuff agents into external applications or automation scripts without launching the terminal interface.

### How does Freebuff support multiple LLM providers?

Freebuff implements a provider abstraction layer in `packages/llm-providers/`, which contains adapter implementations for services including OpenAI, Gemini, and Claude. The Agent Runtime communicates through this unified interface, enabling agents to execute against different LLM backends by simply switching the configured provider adapter without changing agent logic.

### Where are agent behaviors defined in Freebuff?

Agent behaviors are defined as TypeScript files in the `agents/` directory, with each file specifying system prompts, available tools, and execution parameters. For example, [`agents/tmux-cli.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/tmux-cli.ts) defines the tmux-cli agent's capabilities. The Agent Runtime loads these definitions dynamically using the `loadAgent()` function exported from [`packages/agent-runtime/src/loader.ts`](https://github.com/CodebuffAI/freebuff/blob/main/packages/agent-runtime/src/loader.ts).

### What role does the Common package play in the architecture?

The **Common** package (`common/`) provides shared utilities, TypeScript type definitions, and helper functions used across all other components. It includes critical bridges like [`common/src/utils/ask-user-bridge.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/utils/ask-user-bridge.ts) that facilitate communication between the runtime and user interfaces, ensuring consistent interaction patterns whether using the CLI or consuming the SDK programmatically.