API Documentation

Complete reference for the Claude Fleet REST API, WebSocket events, and MCP integration.

Base URL

All endpoints are relative to http://localhost:3847 by default. Configure with the PORT environment variable.

Installation

Install Claude Fleet globally via npm:

$ npm install -g claude-fleet $ claude-fleet Claude Fleet Server v2.0 HTTP API: http://localhost:3847 WebSocket: ws://localhost:3847/ws

Authentication

Claude Fleet uses JWT tokens for authentication. Obtain a token by authenticating with your handle and team name.

POST /auth
Authenticate and receive a JWT token.
{ "handle": "team-lead-1", "teamName": "my-team", "agentType": "team-lead" // or "worker" }

Include the token in subsequent requests:

Authorization: Bearer <your-token>
Role Description
team-lead Can spawn workers, dismiss workers, manage swarms
worker Can read tasks, post to blackboard, send mail

Spawning Workers

Spawn a new Claude Code worker instance. Workers run in isolated git worktrees.

POST /orchestrate/spawn team-lead
Spawn a new worker with a specific task.
{ "handle": "worker-alpha", "prompt": "Analyze the auth module and document the flow", "teamName": "my-team", "swarmId": "feature-auth", "workDir": "/path/to/repo" }

List Workers

GET /orchestrate/workers
Get all active workers and their status.
// Response [ { "handle": "worker-alpha", "state": "running", "health": "healthy", "teamName": "my-team", "worktreePath": "/path/to/worktree" } ]

Dismissing Workers

POST /orchestrate/dismiss/:handle team-lead
Gracefully dismiss a worker and clean up its worktree.

Blackboard

The blackboard is a shared message board for worker coordination. Workers post discoveries, and others can subscribe to updates.

POST /blackboard team-lead
Post a message to the blackboard.
{ "swarmId": "feature-auth", "category": "discovery", "message": "Found security issue in auth.ts:142", "author": "worker-alpha", "priority": "high" }
GET /blackboard/:swarmId
Read messages from the blackboard for a swarm.

Mail System

Direct messaging between workers for targeted communication.

POST /mail
Send mail to another worker.
{ "from": "worker-alpha", "to": "worker-beta", "subject": "API analysis complete", "body": "The endpoints are documented in /docs/api.md" }
GET /mail/:handle
Get all mail for a worker.

Checkpoints

Workers can create checkpoints to persist their state for crash recovery or handoff.

POST /checkpoints
Create a checkpoint with worker state.
{ "handle": "worker-alpha", "state": { /* arbitrary JSON */ }, "status": "in_progress" }
GET /checkpoints/latest/:handle
Get the most recent checkpoint for a worker.

Workflow Engine

DAG-based workflow execution for complex multi-step operations.

POST /workflows team-lead
Create a workflow definition.
{ "name": "feature-development", "steps": [ { "id": "analyze", "type": "spawn", "config": {...} }, { "id": "implement", "dependsOn": ["analyze"], ... } ] }
POST /workflows/:id/start team-lead
Start executing a workflow.

Swarm Templates

Pre-defined swarm configurations for common development patterns.

GET /templates
List all available swarm templates.
POST /templates/:id/run team-lead
Run a swarm template with custom parameters.
{ "teamName": "my-team", "workDir": "/path/to/repo", "variables": { "feature": "authentication" } }

WebSocket Events

Connect to ws://localhost:3847/ws for real-time updates.

// Authenticate after connection { "type": "auth", "token": "your-jwt-token" } // Subscribe to updates { "type": "subscribe", "chatId": "team-channel" }
Event Description
worker_spawned A new worker has been spawned
worker_output Output from a worker
worker_dismissed A worker has been dismissed

MCP Server

Claude Fleet includes an MCP server for integration with MCP-compatible clients.

# Add to your MCP config { "mcpServers": { "claude-fleet": { "command": "npx", "args": ["claude-fleet", "--mcp"] } } }
Tool Description
fleet_spawn Spawn a new worker
fleet_list_workers List active workers
fleet_dismiss Dismiss a worker
fleet_blackboard_post Post to the blackboard
fleet_blackboard_read Read from the blackboard