Multi-Agent Swarms

Multi-agent swarms let you decompose large tasks into a dependency graph of subtasks, each handled by an independent agent. CodeCLI orchestrates execution using wave-based DAG scheduling, worktree isolation, and automated merge strategies.

Architecture

A swarm is composed of three layers:

  1. Orchestrator — Decomposes the top-level task into subtasks, builds the DAG, and schedules waves
  2. Agent Pool — A set of worker agents that execute subtasks in parallel within each wave
  3. Merger — Collects results from all agents and merges changes back into the main working tree

Starting a Swarm

Terminal
bash
# Basic swarm with auto-decomposition
codecli swarm "Refactor the auth module to use OAuth 2.0"


# Swarm with specific agent count
codecli swarm --agents 6 "Add integration tests for all API endpoints"


# Swarm with custom model
codecli swarm --model claude-opus-4-20250514 "Rewrite the database layer in Rust"

Wave Execution

The orchestrator analyzes dependencies between subtasks and groups them into waves. All tasks within a wave run in parallel. A new wave begins only when all tasks in the previous wave have completed.

DAG example
text
Input: "Add tests and documentation for the auth module"


  Wave 0 (parallel):
    [Agent A] Analyze src/auth/*.ts and identify testable units
    [Agent B] Analyze src/auth/*.ts and identify public APIs


  Wave 1 (parallel, depends on Wave 0):
    [Agent C] Write unit tests for auth functions (uses Agent A output)
    [Agent D] Write integration tests for auth endpoints (uses Agent A output)
    [Agent E] Generate API documentation (uses Agent B output)


  Wave 2 (depends on Wave 1):
    [Agent F] Run all tests and generate coverage report (uses Agent C, D output)
    [Agent G] Review documentation for completeness (uses Agent E output)

Configuration

SettingDefaultDescription
maxConcurrentAgents4Maximum parallel agents per wave
timeoutPerAgent300sPer-agent timeout
mergeStrategysequential-rebaseMerge approach: sequential-rebase, patch-merge, fail
worktreeIsolationtrueIsolate each agent in its own git worktree
onConflictfail-and-reportConflict resolution: fail-and-report, prefer-newest, prefer-oldest
retryFailedWavestrueRetry failed tasks before aborting the swarm
maxWaveRetries2Maximum retries per failed task

Merge Process

1
  • Each agent commits changes to a branch named swarm/agent-{id}
    • 2
  • The merger collects all agent branches
    • 3
  • Branches are merged according to the merge strategy
    • 4
  • If conflicts occur, the onConflict policy is applied
    • 5
  • The final merged result is placed in the main working tree
    • !Warning
    Swarm mode with worktree isolation creates multiple git worktrees. Ensure your disk has enough space for the additional checkouts. Each worktree is approximately the size of the full repository.
    PreviousComputer UseNextMainframe Mode