claude-code-swarm

A Claude Code plugin that launches agent teams from openteams YAML topologies.

Overview

Define your multi-agent team structure as a YAML topology (roles, communication channels, spawn rules) using openteams, then let this plugin spin it up as a coordinated Claude Code agent team.

Built-in topologies

Template	Roles	Description
get-shit-done	12	Wave-based parallel execution with goal-backward verification and checkpoint management
bmad-method	10	Full agile development team across 4 phases: analysis, planning, solutioning, implementation

Installation

Install as a Claude Code plugin:

claude plugin add /path/to/claude-code-swarm

Usage

Option 1: Configure a default team

Create .claude-swarm.json in your project root:

{
  "template": "get-shit-done"
}

The team context loads automatically on session start.

Option 2: Launch on demand

/swarm get-shit-done

Option 3: Use a custom topology

Point to any openteams template directory:

{
  "template": "/path/to/my-team-template"
}

Or create your own using openteams editor:

npm install -g openteams
openteams editor

Configuration

Config resolution

Configuration is resolved with tiered fallthrough — each level overrides the one below:

SWARM_* env vars  >  project config  >  global config  >  defaults

Project config

Lives in your project directory at .swarm/claude-swarm/config.json (or .claude-swarm/config.json with --no-prefix):

{
  "template": "get-shit-done",
  "map": {
    "scope": "my-project",
    "systemId": "my-project-swarm"
  }
}

Project config is typically committed to the repo or gitignored per preference.

Global config

Lives at ~/.claude-swarm/config.json. Created by swarmkit init or manually. Sets user-wide defaults that apply to all projects unless overridden:

{
  "map": {
    "server": "ws://my-map-server:8080",
    "sidecar": "session",
    "auth": {
      "token": "my-token"
    }
  },
  "sessionlog": {
    "enabled": true,
    "sync": "metrics"
  }
}

This is useful for settings you don’t want to repeat in every project — MAP server address, auth tokens, sidecar mode, sessionlog preferences. Fields like template and map.scope are typically project-specific and belong in the project config.

Environment variable overrides

All config values can be overridden via SWARM_* environment variables:

Config field	Environment variable
template	SWARM_TEMPLATE
map.server	SWARM_MAP_SERVER
map.enabled	SWARM_MAP_ENABLED
map.scope	SWARM_MAP_SCOPE
map.systemId	SWARM_MAP_SYSTEM_ID
map.sidecar	SWARM_MAP_SIDECAR
map.auth.token	SWARM_MAP_AUTH_TOKEN
map.auth.param	SWARM_MAP_AUTH_PARAM
sessionlog.enabled	SWARM_SESSIONLOG_ENABLED
sessionlog.sync	SWARM_SESSIONLOG_SYNC

How it works

1. SessionStart hook ensures openteams is installed and reads your team configuration
2. openteams generators produce per-role SKILL.md files with prompts, communication config, and CLI references
3. Agent bridge converts those into Claude Code agent definitions
4. Claude Code agent teams spawns teammates according to the topology

Teams coordinate via openteams’ shared state (SQLite-backed tasks, messages, and signal channels) alongside Claude Code’s native team features.

Creating custom topologies

See the openteams documentation for the full template format. A minimal topology:

name: my-team
version: 1
roles:
  - lead
  - researcher
  - implementer

topology:
  root:
    role: lead
    prompt: prompts/lead.md
  spawn_rules:
    lead: [researcher, implementer]
    researcher: []
    implementer: []

communication:
  enforcement: permissive
  channels:
    workflow:
      signals: [RESEARCH_DONE, IMPLEMENTATION_DONE]
  subscriptions:
    lead:
      - channel: workflow
  emissions:
    researcher: [RESEARCH_DONE]
    implementer: [IMPLEMENTATION_DONE]

Requirements

• Claude Code with agent teams support (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)
• Node.js >= 18
• openteams (installed automatically)