# How Base2 Orchestration Coordinates Multiple Subagents in Codebuff

> Learn how Base2 orchestration coordinates multiple subagents in Codebuff by breaking down requests, delegating steps to specialized agents, and aggregating results for efficient task completion.

- Repository: [Codebuff/codebuff](https://github.com/CodebuffAI/codebuff)
- Tags: internals
- Published: 2026-03-09

---

**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`](https://github.com/CodebuffAI/codebuff/blob/main/.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.

```typescript
// .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`](https://github.com/CodebuffAI/codebuff/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/CodebuffAI/codebuff/blob/main/.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`](https://github.com/CodebuffAI/codebuff/blob/main/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`](https://github.com/CodebuffAI/codebuff/blob/main/.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`](https://github.com/CodebuffAI/codebuff/blob/main/.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.