# How Freebuff's Multi-Agent Orchestration Architecture Works

> Discover how Freebuff's multi-agent orchestration architecture works. Buffy the orchestrator agent delegates tasks efficiently to specialized coding sub-agents for seamless file operations.

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

---

**Freebuff coordinates specialized coding sub-agents through a single orchestrator agent called "Buffy," which delegates tasks rather than performing file operations directly.**

Freebuff's multi-agent orchestration architecture is built around a **hierarchical controller pattern** that separates strategic planning from execution. According to the Freebuff source code, the orchestrator lives in [`agents/base2/base2.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/base2/base2.ts) and is constructed by the `createBase2()` factory function, which returns a `SecretAgentDefinition` describing Buffy's capabilities.

## The Orchestrator Definition

The `createBase2()` function builds the orchestrator's identity and behavior through three core properties:

- **Display name**: `"Buffy the Orchestrator"` — the user-facing identity that appears in the interface
- **Unique ID**: `base2` — the internal identifier exported at the bottom of the file
- **System prompt**: A detailed prompt that frames Buffy as "the strategic coding assistant" and defines how it coordinates sub-agents

The system prompt is assembled dynamically inside `createBase2()` and includes placeholders like `${PLACEHOLDER.CURRENT_DATE}` alongside coding conventions and user interaction guidelines. This prompt drives the orchestrator's step-by-step planning behavior.

## Tools Available to the Orchestrator

The orchestrator exposes a configurable **tool list** (`toolNames`) assembled via `buildArray()` from [`agents/types/util-types.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/util-types.ts). The exact tools vary by mode, but the core set includes:

| Tool | Purpose |
|------|---------|
| `spawn_agents` | Launch sub-agents for specific tasks |
| `read_files`, `read_subtree` | Inspect source code |
| `write_file`, `str_replace` | Apply file changes |
| `ask_user` | Request clarifying information |
| `suggest_followups` | Propose next steps to the user |
| `read_url`, `skill`, `gravity_index` | Web research and utilities |

Tool selection is **mode-conditional**: fast modes drop heavy tools like `propose_write_file`, while max modes include the full suite.

## Sub-Agents in the Ecosystem

The `spawnableAgents` array in `createBase2()` declares which sub-agents Buffy can instantiate. The Freebuff source code shows these specialized agents:

- **`file-picker`** / **`file-picker-max`** — Locate relevant files in the repository
- **`code-searcher`** — Textual search across the codebase
- **`researcher-web`** / **`researcher-docs`** — Fetch external documentation
- **`thinker`** / **`thinker-best-of-n-opus`** — Deep reasoning with models like Gemini or GPT-4
- **`editor`** / **`editor-multi-prompt`** — Apply code changes
- **`code-reviewer`** — Review diffs and suggest fixes

Agent selection is controlled by boolean flags: `isMax`, `isLean`, `hasGeminiThinker`, etc. For example, max mode adds `editor-multi-prompt` for complex multi-file edits, while free mode injects a cost-optimized reviewer.

## Execution Flow: How Buffy Processes Requests

The orchestrator follows a **guided step-by-step plan** encoded in its system prompt:

1. **Gather context** — Spawn `file-picker`, `code-searcher`, and `researcher-web` agents in parallel
2. **Clarify requirements** — Optionally invoke `ask_user` for missing information
3. **Plan implementation** — Write a TODO list tracking progress
4. **Deep reasoning** — Spawn a `thinker` agent for complex problems
5. **Apply changes** — Delegate to `editor` or use direct `str_replace`/`write_file` for simple edits
6. **Validate results** — Run type-checking, tests, and linting
7. **Review quality** — Spawn `code-reviewer` to examine the diff
8. **Suggest follow-ups** — Propose additional improvements to the user

Critically, **Buffy never performs file I/O directly** — every filesystem operation flows through sub-agents. This separation keeps the orchestrator model-agnostic and simplifies reasoning.

## Mode-Specific Behavior

Freebuff ships multiple runtime modes configured in `createBase2()`:

- **`default`** — Balanced capabilities using `OPUS_MODEL`
- **`lite`** — Faster, cheaper with `LITE_MODEL` and reduced tools
- **`max`** — Full agent suite including multi-prompt editors
- **`free`** — Cost-optimized with `FREEBUFF_MINIMAX_M3_MODEL_ID` and limited sub-agents
- **`fast`** — Minimal tool set for quick responses

Each mode adjusts the **model selection**, **tool availability**, and **spawnable agents** through conditional logic in lines 43-77 of [`base2.ts`](https://github.com/CodebuffAI/freebuff/blob/main/base2.ts).

## Code Examples

### Creating the Orchestrator Programmatically

```typescript
import { createBase2 } from './agents/base2/base2';

// Default orchestrator for production use
const orchestrator = {
  ...createBase2('default'),
  id: 'base2',
};

export default orchestrator;

```

This mirrors the actual export in [`agents/base2/base2.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/base2/base2.ts) lines 89-91.

### Spawning a Sub-Agent During Execution

```typescript
// Inside an orchestrator workflow step
yield {
  toolName: 'spawn_agent_inline',
  input: {
    agent_type: 'code-searcher',
    params: { query: 'readFile', maxResults: 5 },
  },
  includeToolCall: false,
} as any;

```

This pattern appears in `handleSteps*` generators throughout the codebase for launching context-pruner and other sub-agents.

## Key Source Files

| File | Purpose |
|------|---------|
| [`agents/base2/base2.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/base2/base2.ts) | Core orchestrator definition via `createBase2()` |
| [`agents/types/agent-definition.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/agent-definition.ts) | Type definitions for `SecretAgentDefinition` |
| [`agents/types/util-types.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/util-types.ts) | `buildArray()` and other construction utilities |
| [`agents/thinker/thinker.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/thinker/thinker.ts) | Deep reasoning sub-agent implementation |
| [`agents/browser-use/browser-use.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/browser-use/browser-use.ts) | Headless browser research sub-agent |
| [`common/src/constants/agents.ts`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/constants/agents.ts) | Built-in agent ID constants |

## Summary

- **Buffy is the single orchestrator** that coordinates all Freebuff operations without touching files directly
- **`createBase2()`** builds the orchestrator definition with mode-conditional tools and sub-agents
- **Sub-agents specialize** in search, editing, reasoning, review, and research — spawned on demand via `spawn_agents`
- **Execution follows an 8-step plan** from context gathering through validation to follow-up suggestions
- **Multiple runtime modes** trade capability for speed and cost through model and tool selection

## Frequently Asked Questions

### What makes Freebuff's orchestration different from single-agent coding assistants?

**Single-agent systems combine planning and execution in one model, which limits tool use and reasoning depth.** Freebuff's architecture separates strategic planning (Buffy) from specialized execution (sub-agents), allowing each component to use the optimal model and tool set. The orchestrator can spawn a cheap sub-agent for file search while reserving expensive reasoning models for complex problems.

### Can I customize which sub-agents are available?

**Yes, through the mode system in `createBase2()`.** The function accepts a mode parameter (`'default'`, `'max'`, `'lite'`, etc.) that conditionally includes agents via `buildArray()`. For example, `isMax` adds `thinker-best-of-n-opus` and `editor-multi-prompt` to the spawnable list. Custom modes require modifying the conditional logic in [`agents/base2/base2.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/base2/base2.ts).

### How does the orchestrator communicate between sub-agents?

**Through shared context and the `spawn_agent_inline` tool pattern.** When Buffy spawns a sub-agent, it passes parameters in the `input` field and receives results through the agent runtime. The orchestrator maintains state across steps using the TODO list and can parallelize independent sub-agents — such as spawning `file-picker` and `researcher-web` simultaneously during context gathering.