What Are the Main Components of Freebuff?

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 initializes the system by importing runCLI from common/src/utils/ask-user-bridge.ts and loadAgent from 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 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 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 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 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 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 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 shows how the CLI bootstraps the runtime:

// 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():

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:

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.
• LLM Providers (packages/llm-providers/) abstract multiple AI services, with specific implementations like 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 and the Root CLI (freebuff/) integrate the system.
• Infrastructure scripts (scripts/tmux/) support testing environments with tools like 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 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.

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 that facilitate communication between the runtime and user interfaces, ensuring consistent interaction patterns whether using the CLI or consuming the SDK programmatically.

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