Claude Swarm

Orchestrate teams of AI agents in Claude Code. Enable multiple specialized agents to work together as a coordinated swarm with task delegation, shared memory, and isolated work environments.

Inspired by Claude Swarm (Ruby version).

Features

• Multi-Agent Teams - Define specialized agents with unique roles, tools, and capabilities
• Task Delegation - Agents delegate tasks to teammates based on expertise
• Shared Memory - Persistent semantic memory with vector search across sessions
• Git Worktree Isolation - Isolated branches per session prevent code conflicts
• Session Management - Track, restore, and monitor swarm executions
• MCP Integration - Connect agents to Model Context Protocol servers
• Flexible Configuration - YAML-based configs with environment variable interpolation

Installation

npm install claude-swarm

Or install globally:

npm install -g claude-swarm

Requirements: Node.js 18+

Quick Start

1. Initialize a swarm configuration

claude-swarm init

This creates a claude-swarm.yml file with a template configuration.

2. Configure your agents

Edit claude-swarm.yml to define your swarm:

swarm:
  name: my-project
  main: architect

agents:
  architect:
    description: "System architect who designs solutions and coordinates the team"
    model: opus
    connections:
      - frontend
      - backend
    prompt: |
      You are the lead architect. Analyze requirements, design solutions,
      and delegate implementation tasks to specialized team members.

  frontend:
    description: "Frontend developer specializing in React and TypeScript"
    model: sonnet
    directory: ./packages/frontend
    allowed_tools:
      - Read
      - Edit
      - Write
      - Glob
      - Grep
      - Bash

  backend:
    description: "Backend developer specializing in Node.js APIs"
    model: sonnet
    directory: ./packages/backend
    allowed_tools:
      - Read
      - Edit
      - Write
      - Glob
      - Grep
      - Bash

3. Start the swarm

# Interactive mode
claude-swarm start

# With an initial prompt
claude-swarm start --prompt "Build a user authentication system"

# Non-interactive execution
claude-swarm start --prompt "Fix the login bug" --no-interactive

Configuration Reference

Swarm Configuration

| Field | Type | Description | |-------|------|-------------| | name | string | Name of the swarm | | main | string | Entry-point agent name |

Agent Configuration

| Field | Type | Description | |-------|------|-------------| | description | string | Agent's role description (shown to other agents) | | model | string | Model to use: opus, sonnet, or haiku | | prompt | string | Custom system prompt instructions | | directory | string | string[] | Working directory/directories | | connections | string[] | Agents this agent can delegate to | | allowed_tools | string[] | Whitelist of allowed tools | | disallowed_tools | string[] | Blacklist of disallowed tools | | mcp_servers | object | MCP server connections | | before_hooks | string[] | Commands to run before agent starts | | after_hooks | string[] | Commands to run after agent completes |

Memory Configuration

memory:
  enabled: true
  categories:
    - concept
    - fact
    - skill
    - experience

MCP Server Configuration

agents:
  researcher:
    mcp_servers:
      browser:
        command: npx
        args: ["@anthropic/mcp-server-puppeteer"]
      filesystem:
        command: npx
        args: ["@anthropic/mcp-server-filesystem", "/path/to/data"]

Environment Variable Interpolation

Use ${VAR_NAME} syntax in configuration:

agents:
  api-agent:
    directory: ${PROJECT_ROOT}/api
    prompt: |
      API key is available at ${API_KEY_PATH}

CLI Commands

claude-swarm init

Create a new swarm configuration file.

claude-swarm init                    # Creates claude-swarm.yml
claude-swarm init --output my.yml    # Custom filename

claude-swarm start

Start a swarm execution.

claude-swarm start                           # Interactive mode
claude-swarm start config.yml                # Use specific config
claude-swarm start -p "Build feature X"      # With initial prompt
claude-swarm start --no-interactive          # Non-interactive
claude-swarm start --worktree                # Use git worktree isolation
claude-swarm start --vibe                    # Enable vibe coding mode

Options:

| Flag | Description | |------|-------------| | -p, --prompt <text> | Initial prompt to send | | -i, --interactive | Run in interactive mode (default: true) | | --no-interactive | Run non-interactively | | -w, --worktree | Create isolated git worktree | | --vibe | Enable vibe coding mode |

claude-swarm ps

List active swarm sessions.

claude-swarm ps

claude-swarm list-sessions

List all past sessions.

claude-swarm list-sessions              # List all
claude-swarm list-sessions -n 10        # Last 10 sessions
claude-swarm list-sessions --active     # Only active sessions

claude-swarm show <session-id>

Display details about a specific session.

claude-swarm show abc123

claude-swarm watch

Watch session logs in real-time.

claude-swarm watch              # Watch current session
claude-swarm watch abc123       # Watch specific session

claude-swarm restore <session-id>

Restore and continue a previous session.

claude-swarm restore abc123

claude-swarm clean

Clean up old sessions and worktrees.

claude-swarm clean              # Interactive cleanup
claude-swarm clean --force      # Force cleanup without prompts
claude-swarm clean --days 7     # Clean sessions older than 7 days

Memory Commands

claude-swarm memory list                    # List all memories
claude-swarm memory list --category fact    # Filter by category
claude-swarm memory list --agent architect  # Filter by agent

claude-swarm memory search "authentication" # Semantic search
claude-swarm memory search "auth" -n 5      # Limit results

claude-swarm memory clear                   # Clear all memories
claude-swarm memory clear --agent frontend  # Clear specific agent

Programmatic API

Use Claude Swarm programmatically in your Node.js applications:

import {
  parseConfig,
  validateConfig,
  Orchestrator,
  SwarmMemory,
  AgentRegistry
} from 'claude-swarm';

// Parse and validate configuration
const rawConfig = await parseConfig('./claude-swarm.yml');
const config = validateConfig(rawConfig);

// Create orchestrator and start swarm
const orchestrator = new Orchestrator(config);
const session = await orchestrator.start({
  prompt: 'Build a REST API',
  interactive: false
});

// Work with shared memory
const memory = new SwarmMemory('.swarm/memory.db');
await memory.add({
  content: 'The API uses JWT for authentication',
  category: 'fact',
  agent: 'architect'
});

const results = await memory.search('authentication');
console.log(results);

Exports

| Export | Description | |--------|-------------| | parseConfig | Parse YAML configuration file | | validateConfig | Validate config against schema | | interpolateEnv | Interpolate environment variables | | Orchestrator | Main swarm orchestration class | | AgentRegistry | Agent registration and lookup | | buildAgentPrompt | Generate agent system prompts | | SwarmMemory | Shared memory API | | WorktreeManager | Git worktree management | | SessionLog | Session event logging | | MCPServer | Model Context Protocol server |

Architecture

┌─────────────────────────────────────────────────────────────┐
│                       Claude Swarm                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │  Architect  │───▶│  Frontend   │    │   Backend   │     │
│  │   (opus)    │───▶│  (sonnet)   │    │  (sonnet)   │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│         │                  │                  │             │
│         └──────────────────┼──────────────────┘             │
│                            ▼                                │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                   Shared Memory                       │  │
│  │    (SQLite + Vector Embeddings for Semantic Search)   │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                  Session Manager                      │  │
│  │         (Logs, Metadata, Worktree Isolation)          │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Key Components

• Orchestrator - Coordinates swarm execution and agent lifecycle
• Agent Registry - Manages agent definitions and relationships
• Task Spawner - Generates Claude CLI commands for agent execution
• Memory Store - SQLite database with vector embeddings for semantic search
• Worktree Manager - Creates isolated git worktrees per session
• Session Manager - Tracks sessions with metadata and logs
• MCP Server - JSON-RPC 2.0 server for Model Context Protocol

Memory System

The shared memory system allows agents to store and retrieve information across sessions using semantic search.

Memory Categories

| Category | Purpose | |----------|---------| | concept | Abstract ideas and patterns | | fact | Concrete information and data | | skill | Learned capabilities and techniques | | experience | Past events and outcomes |

How It Works

1. Storage: Memories are stored in SQLite with full-text content
2. Embeddings: Vector embeddings generated using all-MiniLM-L6-v2 model
3. Search: Cosine similarity for semantic matching
4. Metadata: Each memory tracks agent, timestamp, tags, and relations

Agent Memory Instructions

When memory is enabled, agents receive instructions to:

• Store important discoveries and decisions
• Query existing knowledge before starting new work
• Tag memories with relevant categories
• Build on previous learnings

Git Worktree Isolation

Worktree mode creates isolated git branches for each swarm session:

claude-swarm start --worktree

Benefits

• No Conflicts - Each session works on its own branch
• Safe Experimentation - Changes are isolated until merged
• Concurrent Swarms - Run multiple swarms on the same repo
• Easy Cleanup - Remove worktree and branch together

How It Works

1. Creates a new branch: swarm/{session-id}
2. Sets up worktree in ~/.claude-swarm/worktrees/{session-id}
3. Agents work in the isolated worktree
4. On cleanup, worktree and branch are removed

Model Selection

| Model | ID | Best For | |-------|------|----------| | opus | claude-opus-4-5-20251101 | Complex reasoning, architecture, code review | | sonnet | claude-sonnet-4-20250514 | Balanced performance, implementation | | haiku | claude-haiku-3-5-20241022 | Fast, simple tasks |

Example Configurations

Full-Stack Development Team

swarm:
  name: fullstack-team
  main: architect

memory:
  enabled: true
  categories: [concept, fact, skill, experience]

agents:
  architect:
    description: "Lead architect who designs systems and coordinates development"
    model: opus
    connections: [frontend, backend, devops]
    prompt: |
      You are the lead architect. Design scalable solutions and delegate
      implementation to specialists. Ensure consistency across the stack.

  frontend:
    description: "Frontend developer - React, TypeScript, CSS"
    model: sonnet
    directory: ./frontend
    connections: [architect]

  backend:
    description: "Backend developer - Node.js, PostgreSQL, REST APIs"
    model: sonnet
    directory: ./backend
    connections: [architect]

  devops:
    description: "DevOps engineer - Docker, CI/CD, infrastructure"
    model: sonnet
    directory: ./infra
    connections: [architect]

Code Review Team

swarm:
  name: review-team
  main: reviewer

agents:
  reviewer:
    description: "Senior code reviewer who ensures quality and security"
    model: opus
    connections: [security, performance]
    prompt: |
      Review code changes for quality, maintainability, and correctness.
      Delegate security concerns to security specialist and
      performance issues to performance specialist.

  security:
    description: "Security specialist - OWASP, vulnerabilities, auth"
    model: sonnet
    allowed_tools: [Read, Grep, Glob]

  performance:
    description: "Performance specialist - optimization, profiling"
    model: sonnet
    allowed_tools: [Read, Grep, Glob, Bash]

Development

# Install dependencies
npm install

# Build
npm run build

# Development with watch
npm run dev

# Run tests
npm test

# Lint
npm run lint

# Type check
npm run typecheck

License

MIT