How Base2 Orchestration Coordinates Multiple Subagents in Codebuff

Base2 orchestration coordinates multiple subagents by breaking high-level user requests into discrete steps, delegating each step to specialized agents via the spawn_agents tool, and aggregating their outputs into a final result.

The base2 orchestration system serves as the default strategic agent in the Codebuff repository, designed to handle complex coding tasks by distributing work across a fleet of specialized subagents. Unlike monolithic approaches, base2 orchestration dynamically selects and coordinates agents such as commanders, editors, thinkers, and reviewers based on the operational mode, ensuring optimal resource utilization while maintaining code quality.

Core Architecture of Base2 Orchestration

The createBase2 Factory

At the heart of base2 orchestration lies the createBase2 factory function defined in .agents/base2/base2.ts. This function constructs the orchestrator definition based on the selected mode (default, lite, max, or fast), configuring the base model, system prompt, and available capabilities.

// .agents/base2/base2.ts
export function createBase2(
  mode: 'default' | 'lite' | 'max' | 'fast',
  options?: { hasNoValidation?: boolean; planOnly?: boolean },
) {
  const isDefault = mode === 'default';
  const isLite    = mode === 'lite';
  const isMax     = mode === 'max';
  const isFast    = mode === 'fast';

  return {
    publisher,
    model: isLite ? 'x-ai/grok-4.1-fast' : 'anthropic/claude-opus-4.5',
    toolNames: buildArray(/* ... */),
    spawnableAgents: buildArray(/* ... */),
    // systemPrompt generated dynamically...
  };
}

Tool Registry and Spawnable Agents

Base2 orchestration maintains two critical registries that define its coordination capabilities:

• Tool List (toolNames): Declares low-level primitives available during execution, including read_files, write_file, str_replace, set_output, and the pivotal spawn_agents tool.
• Spawnable Agents (spawnableAgents): Catalogs the specialized subagents the orchestrator can instantiate, built dynamically using the buildArray helper based on mode flags.

The spawn_agents tool, implemented in packages/agent-runtime/src/tools/spawnAgents.ts, accepts a list of sub-agent specifications, executes them in parallel or sequence, and returns their aggregated messages for the orchestrator to process.

Mode-Specific Configuration

Base2 orchestration adapts its subagent fleet through mode flags (isDefault, isLite, isMax, isFast):

Mode	Model	Key Subagents	Use Case
default	anthropic/claude-opus-4.5	commander, editor-best-of-n, thinker-best-of-n, code-reviewer-opus	Balanced quality and speed
lite	x-ai/grok-4.1-fast	commander-lite, editor-gpt-5	Rapid feedback, lower cost
max	anthropic/claude-opus-4.5	editor-best-of-n-max, thinker-best-of-n-opus, code-reviewer-best-of-n-gpt-5	Maximum quality via best-of-N sampling
plan	Varies	commander only	Generates plans without execution

The Coordination Workflow

Base2 orchestration follows a structured pipeline to transform user requests into code changes, with each phase potentially spawning specialized subagents.

Planning Phase with Commander

Upon receiving a user prompt, the orchestrator first creates a high-level plan. It may invoke read_files to gather context, then calls spawn_agents with the commander subagent (or commander-lite in lite mode) to decompose the task into concrete, actionable steps.

The commander returns a structured task list that guides subsequent implementation phases.

Implementation Phase with Editor Agents

Based on the selected mode, base2 orchestration spawns the appropriate editor subagent to execute code changes:

• editor-best-of-n (default): Generates multiple implementations and selects the optimal solution through internal evaluation.
• editor-best-of-n-max (max): Uses higher-capacity models for the best-of-N sampling process.
• editor-gpt-5 (lite): A lightweight, fast editor for rapid modifications.

These editors return write_file or str_replace messages containing the actual code changes.

Validation and Review Phase

In default and max modes, base2 orchestration enhances quality through additional validation layers:

1. Thinking Phase: Spawns thinker-best-of-n or thinker-best-of-n-opus to perform static analysis, type-checking, or test execution against the proposed changes.
2. Review Phase: Spawns code-reviewer-opus (or code-reviewer-best-of-n-gpt-5 in max mode) to critique the implementation. The reviewer’s feedback is returned to the orchestrator, which can trigger additional implementation rounds if issues are detected.

Lite mode (base2-lite) skips the review phase to minimize latency and cost.

Final Output Aggregation

Once the plan is satisfied and all validation phases complete, base2 orchestration aggregates the subagent outputs into a final result. The orchestrator emits set_output or write_file calls containing the definitive code changes, then terminates the run.

Running Base2 Orchestration

Default Orchestrator Example

Use the base2 agent for balanced quality and thorough validation:

import { CodebuffClient } from '@codebuff/sdk';

async function main() {
  const client = new CodebuffClient();

  const result = await client.run({
    agent: 'base2',
    prompt: `
      Implement a new utility function \`deepMerge\` that merges two
      nested objects recursively. Add unit tests under \`test/deepMerge.test.ts\`.
    `,
  });

  console.log('Files written:', result.outputFiles);
}

main();

This executes the full pipeline: planning → implementation → thinking → review.

Lite Mode for Rapid Feedback

For quick tasks where speed matters more than comprehensive review:

await client.run({
  agent: 'base2-lite',
  prompt: 'Add JSDoc comments to all exported functions in src/utils.ts',
});

This configuration uses x-ai/grok-4.1-fast and spawns only commander-lite and editor-gpt-5, omitting the reviewer subagent.

Max Mode for Critical Code

When generating complex, production-critical code:

await client.run({
  agent: 'base2-max',
  prompt: `
    Refactor the authentication middleware to use JWT-based session management.
    Include comprehensive error handling and integration tests.
  `,
});

This spawns editor-best-of-n-max and thinker-best-of-n-opus for maximum quality through ensemble methods.

Summary

• Base2 orchestration acts as a strategic coordinator in Codebuff, breaking complex requests into discrete steps executed by specialized subagents.
• The createBase2 factory in .agents/base2/base2.ts configures the orchestrator's capabilities, model selection, and available subagents based on mode flags (default, lite, max, fast).
• Coordination relies on the spawn_agents tool, which launches subagents like commander, editor-best-of-n, thinker-best-of-n, and code-reviewer-opus in structured phases.
• Mode-specific variants trade off between speed and quality: base2-lite skips reviews for fast feedback, while base2-max uses best-of-N sampling for maximum code quality.

Frequently Asked Questions

What is the difference between base2 and base2-lite orchestration?

Base2 (default) runs the full coordination pipeline including planning, implementation, thinking, and code review using models like anthropic/claude-opus-4.5 and subagents like code-reviewer-opus. Base2-lite switches to x-ai/grok-4.1-fast, replaces the standard commander with commander-lite, uses editor-gpt-5 for implementation, and skips the review phase entirely to minimize latency and cost.

How does the spawn_agents tool coordinate multiple subagents?

The spawn_agents tool, implemented in packages/agent-runtime/src/tools/spawnAgents.ts, accepts a list of sub-agent specifications from the orchestrator. It handles the actual instantiation and execution of these agents, running them in parallel or sequence as required, and aggregates their return messages back to the base2 orchestrator. This allows the orchestrator to treat subagent execution as a discrete tool call within its broader reasoning process.

Can I use base2 orchestration without the review phase?

Yes, by using the base2-lite mode, you can run base2 orchestration without the review phase. In .agents/base2/base2-lite.ts, the spawnableAgents array excludes code-reviewer-opus and the isLite flag disables review-related logic. Alternatively, you could create a custom mode or use the planOnly option available in base2-plan mode, though the latter stops after planning rather than skipping just the review.

Which subagents are available in base2-max mode?

Base2-max mode includes the most comprehensive set of subagents for maximum quality. According to .agents/base2/base2-max.ts, these include commander for planning, editor-best-of-n-max for high-capacity implementation with best-of-N sampling, thinker-best-of-n-opus for advanced validation, and code-reviewer-best-of-n-gpt-5 for comprehensive code review. This mode uses anthropic/claude-opus-4.5 as the base model but leverages ensemble methods through the best-of-N agents.

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