Swarm

Parallel AI worker orchestration for Claude Code.

Swarm transforms how AI agents handle complex development tasks. Instead of one agent working through tasks sequentially, Swarm spawns multiple Claude workers that execute in parallel—completing in minutes what would otherwise take hours.

Note: swarm was built when Claude Code had no native parallel-agent orchestration. Since then, first-party features (subagents with worktree isolation, agent teams, /batch, dynamic workflows) have largely superseded it. It's shared here as a clean, tested reference implementation of file-dependency-aware agent orchestration — a portfolio piece, not a tool seeking adoption.

The Problem

When you ask an AI to implement a feature with 10 tasks, it works through them one by one. If each task takes 3 minutes, that's 30 minutes of waiting. But many of those tasks are independent—they touch different files and could run simultaneously.

The Solution

Swarm analyzes task dependencies, identifies which tasks can run in parallel, and spawns multiple Claude workers to execute them simultaneously.

Sequential (traditional):
  Task 1 → Task 2 → Task 3 → Task 4 → Task 5
  [================30 minutes================]

Parallel (Swarm):
  Task 1 ──┐
  Task 2 ──┼──→ Task 5
  Task 3 ──┤
  Task 4 ──┘
  [===10 minutes===]

Key Insight

Tasks are safe to parallelize when they touch non-overlapping files.

• Task A modifies src/auth/login.ts
• Task B modifies src/api/users.ts
• These can run in parallel (different files)

But:

• Task C modifies src/auth/login.ts
• Task D modifies src/auth/login.ts
• These must run sequentially (same file = conflict)

Swarm automatically detects file conflicts and serializes only when necessary.

Features

| Feature | Description | |---------|-------------| | Parallel Execution | Multiple Claude workers run simultaneously | | File Conflict Detection | Automatically serializes tasks that touch same files | | Real Claude Workers | Spawns actual claude CLI processes, not mocks | | Layer-Based Orchestration | Executes in dependency order with checkpoints | | Human-in-the-Loop | Strategic pauses for review and approval | | Trust Tiers | Interactive, supervised, or autonomous modes | | Risk-Based Gating | Sensitive files always require explicit approval | | Retry & Escalation | Failed tasks retry, then escalate to human |

Quick Start

# Install globally
npm install -g @chrolicious/swarm

# In your project directory
swarm init

# Create tasks in openspec/changes/my-feature/tasks.md, then:
swarm plan my-feature
swarm execute --workers 4

Or use npx without installing:

npx @chrolicious/swarm init

Inside Claude Code

If you're already in a Claude Code session, use slash commands:

/swarm:init
/swarm:plan my-feature
/swarm:execute
/swarm:status

How It Works

1. Parse Tasks

Swarm reads tasks from OpenSpec tasks.md files:

## 1. Authentication Module
- [ ] 1.1 Create `src/auth/login.ts` with login function
- [ ] 1.2 Create `src/auth/logout.ts` with logout function

## 2. API Module
- [ ] 2.1 Create `src/api/users.ts` with user endpoints
- [ ] 2.2 Create `src/api/posts.ts` with post endpoints

2. Analyze File Dependencies

For each task, Swarm predicts which files it will touch:

• Explicit paths mentioned in the task description
• Files found via codebase search
• Directory expansion for folder references

3. Build Execution Graph

Tasks are organized into layers based on file conflicts:

Layer 1 (4 tasks in parallel):
  [1.1] src/auth/login.ts    ← Worker 1
  [1.2] src/auth/logout.ts   ← Worker 2
  [2.1] src/api/users.ts     ← Worker 3
  [2.2] src/api/posts.ts     ← Worker 4

Layer 2 (1 task):
  [3.1] Integration tests    ← Depends on Layer 1

4. Spawn Parallel Workers

Each worker is a real Claude CLI process:

const worker = new ClaudeTaskWorker({
  model: "sonnet",
  workingDirectory: projectPath,
});

// Spawns: claude -p "Task prompt..." --model sonnet --max-turns 50

5. Coordinate & Checkpoint

• Workers execute in parallel within each layer
• Layer checkpoints pause for human review
• Failed tasks retry automatically
• High-risk file changes require approval

Commands

| CLI | Claude Code | Description | |-----|-------------|-------------| | swarm init | /swarm:init | Initialize swarm for a project | | swarm plan <name> | /swarm:plan <name> | Parse proposal and show execution plan | | swarm execute | /swarm:execute | Run workers on approved plan | | swarm analyze <name> | /swarm:analyze <name> | Show detailed file dependencies | | swarm status | /swarm:status | Check execution progress |

CLI Options

swarm plan my-feature --approve    # Approve plan for execution
swarm execute --workers 4          # Specify parallel workers
swarm execute --dry-run            # Preview without executing

Real Example

We tested Swarm with 3 independent tasks:

## Tasks
- [ ] 1.1 Create `src/logger/index.ts` - colored console output
- [ ] 2.1 Create `src/config/index.ts` - config validation
- [ ] 3.1 Create `src/stats/index.ts` - execution statistics

Execution plan:

Layer 1 (3 tasks in parallel)
  [1.1] src/logger/index.ts  ← Worker 1
  [2.1] src/config/index.ts  ← Worker 2
  [3.1] src/stats/index.ts   ← Worker 3

Conflicts: 0

Result:

Execution Complete
──────────────────
  Tasks completed: 3
  Tasks failed: 0
  Duration: 366.5s

All 3 files created in parallel by 3 simultaneous workers.

Configuration

Swarm stores config in .swarm.json:

{
  "initialized": true,
  "trustLevel": "interactive",
  "highRiskPatterns": ["*.sql", ".env*", "*/migrations/*"],
  "neverBypassHighRisk": true
}

Trust Levels

| Level | Layer Checkpoints | High-Risk Gates | |-------|-------------------|-----------------| | interactive | Every layer | Always prompt | | supervised | Start + end only | Always prompt | | autonomous | None | Always prompt |

High-risk gates are never bypassable, even in autonomous mode.

Architecture

src/
├── cli/           # CLI commands (commander)
├── parser/        # OpenSpec tasks.md parsing
├── analyzer/      # File dependency prediction
├── graph/         # Dependency graph & execution layers
├── orchestrator/  # Worker spawning & coordination
│   ├── TaskWorker      # Interface for workers
│   ├── MockWorker      # Testing implementation
│   └── ClaudeTaskWorker # Real Claude CLI worker
├── controls/      # Human-in-the-loop checkpoints
├── validation/    # Config and plugin validation
└── memory/        # SQLite session memory

Optional: Cross-Session Memory

Swarm's cross-session memory and context is an optional integration with a local claude-mem service (http://localhost:3456). Without it, Swarm runs normally and only skips historical context from previous sessions—the SQLite audit trail still works. Users can pass --no-memory to skip the integration check entirely.

Key Components

ClaudeTaskWorker - Spawns real Claude CLI processes:

// Builds task prompt with context
const prompt = buildTaskPrompt(task, attempt, maxAttempts);

// Spawns claude CLI
spawn("claude", ["-p", prompt, "--model", "sonnet", ...]);

Analyzer - Predicts file dependencies:

// Finds files mentioned in task description
const files = predictFilesFromDescription(task);

// Detects conflicts between tasks
const conflicts = findOverlaps(analyses);

Graph Builder - Creates execution layers:

// Tasks with conflicts go in different layers
// Tasks without conflicts can parallelize
const plan = toExecutionPlan(graph);

When to Use Swarm

Good fit:

• Multiple independent features to implement
• Tasks that touch different parts of codebase
• Large refactoring across many files
• Parallel test suites or builds

Not ideal:

• Single feature touching one file
• Highly interdependent tasks
• Tasks that must be reviewed individually

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in watch mode
npm run dev

# Run tests (306 tests)
npm test

# Lint
npm run lint

# Type check
npm run typecheck

Project Structure

swarm/
├── src/                    # Source code
├── dist/                   # Compiled output
├── openspec/               # OpenSpec proposals
│   └── changes/
│       ├── add-task-caching/
│       ├── add-github-integration/
│       └── add-features-parallel/
├── commands/               # Skill markdown files
├── skills/                 # Auto-detection skills
└── scripts/                # Build scripts

Roadmap

• [ ] Task Caching - Skip unchanged tasks on re-run
• [ ] GitHub Integration - Auto-create PRs, link issues
• [ ] Remote Workers - Distribute across machines
• [ ] Web Dashboard - Visual execution monitoring

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: npm test
5. Submit a pull request

License

MIT

Credits

Built with Claude Code and OpenSpec.