How Freebuff's Multi-Agent Orchestration Architecture Works

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

Code Examples

Creating the Orchestrator Programmatically

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 lines 89-91.

Spawning a Sub-Agent During Execution

// 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	Core orchestrator definition via createBase2()
agents/types/agent-definition.ts	Type definitions for SecretAgentDefinition
agents/types/util-types.ts	buildArray() and other construction utilities
agents/thinker/thinker.ts	Deep reasoning sub-agent implementation
agents/browser-use/browser-use.ts	Headless browser research sub-agent
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.

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.

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