Claude Swarm Plugin

A distributed agent orchestration system for Claude Code that enables multiple AI agents to work collaboratively on complex projects.

Overview

The Swarm plugin provides:

Multi-agent coordination - Multiple Claude instances working in parallel
Task management - Automatic task distribution and execution
Sandbox isolation - Each agent runs in its own Daytona sandbox
Real-time chat - Communication channel between agents and master
Project sync - Shared codebase across all agents

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           SWARM ARCHITECTURE                                 │
└─────────────────────────────────────────────────────────────────────────────┘

┌──────────────┐     ┌──────────────────┐     ┌─────────────────────────────┐
│   YOU        │     │   FLY.IO API     │     │   DAYTONA (reliablesite)    │
│  (Claude     │────▶│  (Orchestrator)  │────▶│   Sandboxes with Claude     │
│   Code)      │     │                  │     │                             │
└──────────────┘     └──────────────────┘     └─────────────────────────────┘
      │                      │                           │
      │                      │                           │
      ▼                      ▼                           ▼
┌──────────────┐     ┌──────────────────┐     ┌─────────────────────────────┐
│ Local Plugin │     │ swarm-layer.js   │     │ daytona-sandbox.js          │
│ - Commands   │     │ - Task mgmt      │     │ - Sandbox lifecycle         │
│ - Agents     │     │ - Auto-claim     │     │ - Claude execution          │
│ - Skills     │     │ - Auto-execute   │     │ - File/Git/Browser ops      │
└──────────────┘     └──────────────────┘     └─────────────────────────────┘

Components

1. Backend API (Fly.io)

Location: https://claude-remote-little-wave-2609.fly.dev

Files:

server.js - Main Express server with all API routes
swarm-layer.js - Swarm orchestration logic
daytona-sandbox.js - Daytona SDK integration

2. Local Plugin

Location: /data/.claude/

Commands:

/swarm-status - View swarm and agent status
/swarm-task - Create new tasks
/swarm-chat - Send messages to swarm chat
/swarm-project - Manage project (create, init, sync)

Agents:

swarm-master - Main orchestrator agent

3. Infrastructure

Daytona Server: 104.194.10.186 (reliablesite)

32GB RAM
913GB disk
Docker + Daytona + Supabase

Task Execution Flow

1. TASK CREATION
   ┌─────────────────┐
   │ /swarm-task     │
   │ "Create Button" │
   └────────┬────────┘
            │
            ▼
2. API RECEIVES TASK
   ┌─────────────────┐
   │ POST /tasks     │
   │ status: pending │
   └────────┬────────┘
            │
            ▼
3. AUTO-CLAIM (every 5s)
   ┌─────────────────────────────┐
   │ Backend checks:             │
   │ - Which tasks are pending?  │
   │ - Which agents are idle?    │
   │ - Match by skills/tags      │
   │                             │
   │ → status: claimed           │
   │ → agent: assigned           │
   └────────────┬────────────────┘
                │
                ▼
4. AUTO-EXECUTE (NEW!)
   ┌─────────────────────────────┐
   │ Immediately after claim:    │
   │ 1. status → running         │
   │ 2. agent → working          │
   │ 3. Restore Claude creds     │
   │ 4. Execute: claude --print  │
   │ 5. Capture output           │
   └────────────┬────────────────┘
                │
                ▼
5. COMPLETION
   ┌─────────────────────────────┐
   │ When Claude finishes:       │
   │ - status → completed/failed │
   │ - Result saved to task      │
   │ - Agent → idle              │
   │ - Triggers processed        │
   │ - Dependencies unblocked    │
   └─────────────────────────────┘

API Reference

Swarm Endpoints

Method	Endpoint	Description
GET	`/swarms`	List all swarms
POST	`/swarms`	Create new swarm
GET	`/swarms/:id`	Get swarm details
GET	`/swarms/:id/status`	Get full status with agents/tasks
DELETE	`/swarms/:id`	Delete swarm

Task Endpoints

Method	Endpoint	Description
GET	`/swarms/:id/tasks`	List tasks
POST	`/swarms/:id/tasks`	Create task
PUT	`/swarms/:id/tasks/:taskId`	Update task
DELETE	`/swarms/:id/tasks/:taskId`	Delete task

Agent Endpoints

Method	Endpoint	Description
GET	`/swarms/:id/agents`	List agents
POST	`/swarms/:id/agents`	Register agent
PUT	`/agents/:sandboxId`	Update agent

Chat Endpoints

Method	Endpoint	Description
GET	`/swarms/:id/chat`	Get chat messages
POST	`/swarms/:id/chat`	Send message

Project Endpoints

Method	Endpoint	Description
GET	`/projects`	List projects
POST	`/projects`	Create project
GET	`/swarms/:id/project`	Get swarm's project
POST	`/projects/:id/init`	Initialize in sandboxes
POST	`/projects/:id/sync`	Sync (git pull)

Configuration

Environment Variables

File: /data/.claude-swarm.env

# API
export SWARM_API_URL="https://claude-remote-little-wave-2609.fly.dev"
export SWARM_DEFAULT_ID="swarm-1769380552744"

# Daytona
export DAYTONA_API_URL="http://104.194.10.186:3986"
export DAYTONA_API_KEY="your-key"

File: /data/.swarm/credentials.env

# Fly.io
export FLY_API_TOKEN="FlyV1..."
export FLYCTL_INSTALL="/data/.fly"
export PATH="$FLYCTL_INSTALL/bin:$PATH"

# SSH
export SWARM_SSH_KEY="/data/.ssh/id_ed25519"
export SWARM_SERVER_HOST="104.194.10.186"
export SWARM_SERVER_USER="root"

Local Commands Reference

/swarm-status

View current swarm status including agents, tasks, and recent chat.

/swarm-status

Output:

=== SWARM ===
Name: dev-swarm
Status: active
Sandboxes: 5

=== AGENTS ===
[🟢 IDLE] Frontend Agent (frontend)
[🔵 WORKING] Backend Agent (backend)
  └─ Task: task-123

=== TASKS ===
Pending: 3
Running: 1
Completed: 5

/swarm-task

Create a new task for the swarm.

/swarm-task "Task title" [tags] [priority] [depends]

Examples:

/swarm-task "Create Button component"
/swarm-task "Create Button" frontend,ui
/swarm-task "Create Button" frontend,ui high
/swarm-task "Test Button" qa,test medium task-123

/swarm-chat

Send a message to the swarm chat.

/swarm-chat "message" [@mention]

Examples:

/swarm-chat "Hello team!"
/swarm-chat "Deploy at 6pm" @all
/swarm-chat "What's the status?" @frontend

/swarm-project

Manage the shared project.

/swarm-project <action> [name] [gitUrl]

Actions:

create - Create new project
init - Initialize (git clone in all sandboxes)
sync - Synchronize (git pull in all sandboxes)
status - View project status

Files Structure

/data/
├── .claude/
│   ├── agents/
│   │   └── swarm-master.md        # Orchestrator agent
│   └── commands/
│       ├── swarm-status.md        # Status command
│       ├── swarm-task.md          # Task creation
│       ├── swarm-chat.md          # Chat command
│       └── swarm-project.md       # Project management
│
├── .swarm/
│   ├── backend/                   # Backend source (local copy)
│   │   ├── server.js
│   │   ├── swarm-layer.js
│   │   ├── daytona-sandbox.js
│   │   └── package.json
│   ├── docs/                      # Documentation
│   ├── agents/                    # Agent configs (JSON)
│   ├── tasks/                     # Task data (JSON)
│   ├── chats/                     # Chat history (JSON)
│   ├── projects/                  # Project configs (JSON)
│   ├── swarms/                    # Swarm configs (JSON)
│   └── credentials.env            # Credentials (DO NOT COMMIT)
│
├── .claude-swarm.env              # Main config
└── .ssh/
    ├── id_ed25519                 # SSH private key
    └── id_ed25519.pub             # SSH public key

Recent Changes (2026-01-26)

Added Auto-Execution

Previously, tasks were created and claimed but never executed. Now:

swarm-layer.js - Added executeTaskInAgent() method
- Automatically triggers after task is claimed
- Restores Claude credentials in sandbox
- Executes Claude with task prompt
- Captures output and updates task status
daytona-sandbox.js - Added runClaudeCodeAsync() method
- Synchronous Claude execution (waits for completion)
- 10-minute timeout
- Returns full output

Removed jq Dependency

All local commands rewritten to use Node.js for JSON parsing instead of jq (which wasn't installed).

Added Credentials Management

SSH key generated for sandbox access
Fly.io token configured
All credentials stored in /data/.swarm/credentials.env

Troubleshooting

API Not Responding

source /data/.swarm/credentials.env
curl -s "$SWARM_API_URL/health"

Check Fly.io Status

source /data/.swarm/credentials.env
flyctl status -a claude-remote-little-wave-2609

View Fly.io Logs

source /data/.swarm/credentials.env
flyctl logs -a claude-remote-little-wave-2609

SSH to Main Server

ssh -i /data/.ssh/id_ed25519 root@104.194.10.186

Restart Backend

source /data/.swarm/credentials.env
flyctl apps restart claude-remote-little-wave-2609

Deployment

Deploy Backend Changes

source /data/.swarm/credentials.env

# Copy files to fly.io
flyctl ssh console -a claude-remote-little-wave-2609 -C "cat > /app/swarm-layer.js" < /data/.swarm/backend/swarm-layer.js
flyctl ssh console -a claude-remote-little-wave-2609 -C "cat > /app/daytona-sandbox.js" < /data/.swarm/backend/daytona-sandbox.js

# Restart
flyctl apps restart claude-remote-little-wave-2609

License

Internal use only.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
agents		agents
docs		docs
skills		skills
swarm-backend		swarm-backend

Ianfr13/claude-code-plugins

Folders and files

Latest commit

History

Repository files navigation