Swarm Mode

Swarm mode is Cosine’s most powerful and complex agent mode. It enables multiple agents to work in parallel on different parts of a large task, dramatically reducing completion time for work that can be partitioned.

Overview

When you activate Swarm mode, Cosine’s orchestrator:

1. Analyzes the task to identify parallelizable workstreams
2. Spawns multiple subagents, each with a focused scope
3. Coordinates execution to prevent conflicts and ensure progress
4. Aggregates results from all workers into a coherent outcome

Swarm mode is ideal for:

• Large refactoring projects affecting many files
• Tasks requiring exploration across multiple code areas
• Work that can be cleanly separated into independent subtasks
• Time-sensitive projects where parallel execution provides significant speedup

How Swarm mode works

Advisory file locking

Before making any edits, each agent “claims” the files it intends to modify. If another agent already holds a write lock on an overlapping path, the new agent is blocked from proceeding until the lock is released.

This ensures that:

• Two agents never simultaneously edit the same file
• File-level conflicts are prevented at the planning stage
• Agents can still read files locked by others

Scope partitioning

The orchestrator assigns each parallel worker a distinct subset of files. The system explicitly enforces: two parallel workers must not edit the same file. If subtasks require editing the same file, the orchestrator either:

• Sequences those subagents to run one after another
• Merges the related work into a single subagent’s scope
• Rejects the parallelization plan and falls back to sequential execution

Peer awareness

Agents can see what other active agents are working on and what they have recently edited. This enables:

• Stale file detection: Agents can identify when a file they’re reading has been modified by another agent and re-read the updated version
• Coordination awareness: Agents understand the broader context of parallel work happening alongside them
• Conflict avoidance: Agents can adjust their approach based on changes made by peers

Worktree isolation

Each agent runs in its own git worktree, providing filesystem-level isolation:

• Each worktree has an independent working directory
• Changes in one worktree do not affect others until explicitly merged
• Failed or problematic agent executions can be discarded without affecting other agents
• Clean separation enables safe rollback of individual subagent work

Conflict prevention (not resolution)

Swarm mode is designed with a clear philosophy: prevent conflicts rather than resolve them. The system achieves this through several design choices:

Small parallel batches

The orchestrator intentionally keeps parallel batches small—typically 3-4 workers maximum. This constraint:

• Reduces the complexity of coordination
• Makes scope partitioning more tractable
• Limits the blast radius if coordination fails
• Keeps the orchestration overhead manageable

Explicit work partitioning

Rather than letting agents discover conflicts at edit time, the orchestrator partitions work explicitly before any agents begin. Each agent receives a clearly defined scope with guaranteed non-overlapping write access.

Lock-before-edit semantics

Agents must acquire locks on all files they intend to modify before making any changes. This prevents the classic “read-modify-write” race condition where two agents read the same file, modify it independently, and the second write overwrites the first.

When to use Swarm mode

Swarm mode works best when:

• The task can be decomposed into independent subtasks
• Subtasks naturally map to different files or file regions
• Speed of completion is important
• You can tolerate some orchestration overhead for the parallelization benefit

Avoid Swarm mode when:

• The task is inherently sequential (each step depends on the previous)
• All work must happen in a single file
• The coordination overhead would exceed the parallelization benefit
• You need fine-grained control over the exact execution order

Best practices

1. Start with clear prompts: The orchestrator’s ability to partition work depends on understanding the task structure
2. Be specific about scope: If you know how work should be divided, say so in your prompt
3. Review subagent results: Check each subagent’s output before approving the final merge
4. Use for exploration: Swarm mode excels at parallel exploration of large codebases

Related topics

• CLI Modes for switching between agent modes
• Models and Pricing for cost considerations when using Swarm mode

Swarm mode limitations

• Maximum parallel workers per swarm batch is intentionally limited
• Tasks requiring heavy coordination between subagents may not parallelize well
• Each subagent consumes credits independently based on its token usage
• Some operations (like running tests or builds) may still need to happen sequentially after parallel editing completes

---

Swarm mode is available on all Cosine plans. The orchestrator automatically determines when parallelization is appropriate based on the task structure.