Orchestrators in Claude Code: Managing Multi-Agent Workflows

When to Use Orchestrators

Orchestrators make sense when a task is too large for a single agent to handle well — either because it requires different expertise domains, or because the work can be parallelized across multiple directories or modules. A single agent working on a 50-file refactor will lose track of what it has done. Five agents working in parallel on different parts will finish faster and with less confusion.

Setting Up an Orchestration

An orchestration is defined in a YAML or JSON file that describes the agents and how they divide work:

agents:
  - name: frontend
    workingDir: ./frontend
    task: Refactor React components to use new design system
  - name: backend
    workingDir: ./backend
    task: Update API clients to match new schema
  - name: tests
    task: Write integration tests for the refactored APIs

Start the orchestration with claude --orchestrate ./orchestration.yaml.

Coordination Points

The orchestrator manages shared state between agents — what files have been modified, what interfaces have changed, what tests need to be updated. Agents report back to the orchestrator at defined checkpoints. If the backend changes an API interface, the orchestrator tells the frontend and test agents to update their calls.

When Not to Use Orchestrators

Orchestrators add coordination overhead. For tasks that are inherently sequential — where step B depends on step A completing — a single agent with clear instructions will be faster and produce better results. Do not parallelize for the sake of it.