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.