The infrastructure for AI agent fleets
Documentation • Quick Start • Features • Issues
Orchestrate multiple Claude Code instances with intelligent coordination, swarm intelligence, and real-time collaboration. Build production-grade multi-agent systems.
- Fleet Orchestration - Spawn and manage multiple Claude Code worker agents
- Swarm Coordination - Blackboard messaging pattern for agent communication
- Task Management - Create, assign, and track tasks across agents
- Git Worktrees - Isolated workspaces for each agent to prevent conflicts
- MCP Integration - 25+ tools accessible via Model Context Protocol
- Real-time Updates - WebSocket notifications for live collaboration
- JWT Authentication - Secure role-based access control
- Prometheus Metrics - Production-ready observability
# Install globally
npm install -g claude-fleet
# Start the server
claude-fleet
# Use the CLI in another terminal
fleet health
fleet workersgit clone https://github.com/sethdford/claude-fleet.git
cd claude-fleet
npm install
npm run build
./start.sh# Foreground (see logs)
./start.sh
# Background daemon
./start.sh --background
# Check status
./start.sh --status
# Stop daemon
./start.sh --stopfleet health # Server health check
fleet metrics # Prometheus metrics (JSON)
fleet workers # List active workers
fleet spawn <handle> <prompt> # Spawn a worker agent
fleet dismiss <handle> # Stop a worker
fleet send <handle> <message> # Send message to worker
fleet swarms # List all swarms
fleet swarm-create <name> <max> # Create a swarm
fleet teams <team> # List team agents
fleet tasks <team> # List team tasksAdd to ~/.claude/settings.json:
{
"mcpServers": {
"fleet": {
"command": "npx",
"args": ["claude-fleet-mcp"],
"env": {
"CLAUDE_FLEET_URL": "http://localhost:3847",
"CLAUDE_FLEET_TEAM": "my-team",
"CLAUDE_CODE_AGENT_NAME": "my-agent",
"CLAUDE_CODE_AGENT_TYPE": "team-lead"
}
}
}
}Then use MCP tools in Claude Code:
team_status- See team membersteam_spawn- Spawn worker agentsteam_assign- Assign tasksteam_broadcast- Send team-wide messagesblackboard_post- Post to swarm blackboardcheckpoint_create- Save agent state
┌─────────────────────────────────────────────────────────────┐
│ Claude Fleet Server │
│ (localhost:3847) │
├─────────────────────────────────────────────────────────────┤
│ HTTP API WebSocket Worker Manager │
│ ───────── ───────── ────────────── │
│ • Auth • Real-time • Spawn/dismiss │
│ • Tasks • Subscriptions • Health monitoring │
│ • Teams • Broadcasts • Auto-restart │
│ • Swarms • Git worktrees │
├─────────────────────────────────────────────────────────────┤
│ Storage (SQLite) │
│ ───────────────── │
│ • Agents, Tasks, Messages, Checkpoints, Blackboard │
└───────────────────────────┬─────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ Claude │ │ Claude │ │ Claude │
│ Code │ │ Code │ │ Code │
│ (lead) │ │ (worker)│ │ (worker)│
└─────────┘ └─────────┘ └─────────┘
| Role | Permissions |
|---|---|
| team-lead | Spawn workers, assign tasks, broadcast, merge code |
| worker | Claim tasks, complete work, send messages |
| coordinator | Full orchestration control |
| monitor | Read-only access, alerts |
| merger | Merge branches, push code |
| Method | Endpoint | Description |
|---|---|---|
| GET | /health |
Server health |
| GET | /metrics |
Prometheus metrics |
| POST | /auth |
Authenticate agent |
| Method | Endpoint | Description |
|---|---|---|
| GET | /teams/:team/agents |
List team agents |
| GET | /teams/:team/tasks |
List team tasks |
| POST | /tasks |
Create task |
| PATCH | /tasks/:id |
Update task |
| Method | Endpoint | Description |
|---|---|---|
| POST | /orchestrate/spawn |
Spawn worker |
| POST | /orchestrate/dismiss/:handle |
Dismiss worker |
| GET | /orchestrate/workers |
List workers |
| Method | Endpoint | Description |
|---|---|---|
| POST | /swarms |
Create swarm |
| GET | /swarms |
List swarms |
| POST | /blackboard |
Post message |
| GET | /blackboard/:swarmId |
Read messages |
| POST | /checkpoints |
Create checkpoint |
See API Documentation for complete reference.
| Variable | Default | Description |
|---|---|---|
PORT |
3847 |
Server port |
STORAGE_BACKEND |
sqlite |
Storage backend (see below) |
DB_PATH |
./fleet.db |
SQLite database path |
JWT_SECRET |
(random) | JWT signing secret |
JWT_EXPIRES_IN |
24h |
Token expiration |
MAX_WORKERS |
5 |
Maximum concurrent workers |
Claude Fleet supports multiple storage backends for different deployment scenarios:
| Backend | Best For | Required Package |
|---|---|---|
sqlite |
Local development | Built-in |
dynamodb |
AWS serverless | @aws-sdk/client-dynamodb |
s3 |
Archival/infrequent access | @aws-sdk/client-s3 |
firestore |
Google Cloud | @google-cloud/firestore |
postgresql |
Production deployments | pg |
SQLite (Default)
STORAGE_BACKEND=sqlite
DB_PATH=./fleet.dbDynamoDB
STORAGE_BACKEND=dynamodb
AWS_REGION=us-east-1
DYNAMODB_TABLE_PREFIX=fleet_
# Optional: DYNAMODB_ENDPOINT for local developmentS3
STORAGE_BACKEND=s3
S3_BUCKET=my-fleet-bucket
AWS_REGION=us-east-1
S3_PREFIX=data/Firestore
STORAGE_BACKEND=firestore
GOOGLE_CLOUD_PROJECT=my-project
# Optional: GOOGLE_APPLICATION_CREDENTIALS for service accountPostgreSQL
STORAGE_BACKEND=postgresql
DATABASE_URL=postgres://user:pass@host:5432/fleet
POSTGRESQL_SCHEMA=public
POSTGRESQL_POOL_SIZE=10| Variable | Description |
|---|---|
CLAUDE_FLEET_URL |
Server URL |
CLAUDE_FLEET_TEAM |
Team name |
CLAUDE_CODE_AGENT_NAME |
Agent handle |
CLAUDE_CODE_AGENT_TYPE |
team-lead or worker |
# Install dependencies
npm install
# Development mode (hot reload)
npm run dev
# Run tests
npm test
# Run E2E tests
npm run e2e
# Type checking
npm run typecheck
# Linting
npm run lint- Architecture Guide - System design and components
- API Reference - Complete API documentation
- Deployment Guide - Production deployment
- Contributing - How to contribute
MIT - see LICENSE
Created by Seth Ford
Built for orchestrating Claude Code agents.