Claude Fleet

Waves of agents until the job is done

---

Multi-agent orchestration server for Claude Code. Deploy specialized agent fleets, run iterative waves across repositories, and coordinate swarms via a REST API, CLI, and MCP integration. Supports TMUX visual mode or headless mode for CI/CD.

# Launch a wave across multiple repos
$ fleet wave --repos api,frontend,shared --objective "Add rate limiting"

Wave 1: Spawning scouts...
  Scout[api]      Mapped 47 endpoints
  Scout[frontend] Found 12 API calls
  Scout[shared]   Identified rate-limit types

Wave 2: Architect designing...
  Architect       Proposed middleware approach

Wave 3: Implementation...
  Worker[api]     Added middleware + config
  Kraken[api]     22 tests passing

Wave 4: Review...
  Critic          Approved. Creating PRs...

3 PRs created. Objective achieved in 4 waves.

---

Architecture

src/
├── index.ts           # Entry point — starts CollabServer
├── server.ts          # Express HTTP + WebSocket server
├── types.ts           # All type definitions (centralized)
├── cli.ts             # CLI commands (fleet binary)
├── storage/           # Data layer (SQLite default, DynamoDB/Firestore/PostgreSQL optional)
├── workers/           # Worker process management & agent roles
├── routes/            # HTTP route handlers (core, waves, swarm, tasks, etc.)
├── validation/        # Zod schemas for all API inputs
├── metrics/           # Prometheus metrics collection
├── scheduler/         # Cron-based autonomous task scheduling
├── mcp/               # Model Context Protocol bridge (98 tools)
├── middleware/         # JWT auth, RBAC, validation middleware
└── integrations/      # Third-party integrations (Linear)

Layer dependency rules:

Layer	Can Import From
types.ts	Nothing
storage/	types.ts
workers/	storage/, types.ts
routes/	workers/, storage/, validation/, types.ts
server.ts	All layers

Additional directories:

crates/                # Rust crates (compound accumulator, search engine, lmsh)
packages/              # Monorepo packages (common, fleet, mcp, tmux, session, storage)
apps/cli/              # CLI app package
public/                # Dashboard UI & compound machine frontend
scripts/               # Build, E2E test, and deployment scripts

Key Technologies

• Express + WebSocket (ws) — HTTP API and real-time events
• better-sqlite3 — Default embedded database (with umzug migrations)
• jsonwebtoken — JWT authentication
• Zod — Input validation for all endpoints
• prom-client — Prometheus metrics
• @modelcontextprotocol/sdk — MCP server integration
• Rust (NAPI-RS) — 8 optional native crates for acceleration (compound, search, lmsh, logstream, dag, swarm, metrics, ringbus)

---

Rust Native Acceleration

Claude Fleet includes an optional Rust acceleration layer. All crates have JS fallback implementations — native binaries are never required.

crates/
├── compound/    # Ring-buffer accumulator for time-series metrics
├── search/      # Tantivy-based full-text search engine
├── lmsh/        # Natural language → shell translator
├── logstream/   # High-performance log streaming
├── dag/         # DAG operations (topo sort, critical path, cycle detection)
├── swarm/       # Swarm coordination primitives
├── metrics/     # Native Prometheus metrics engine
└── ringbus/     # Lock-free ring buffer message bus

Build native modules (optional):

cargo build --workspace --release
cargo test --workspace    # 36 Rust tests

---

Agent Roles

7 specialized agent roles with role-based access control:

Role	Purpose	Key Capability
Lead	Orchestrates the fleet, delegates tasks	Can spawn other agents
Worker	General-purpose implementation	Code changes, commits
Scout	Explores codebases, maps dependencies	Read-only exploration
Kraken	TDD specialist — red-green-refactor	Test-first development
Oracle	Research and analysis	Deep code analysis
Critic	Code review, quality gates	Review and approve
Architect	System design, API contracts	Can spawn workers

Each role has a custom system prompt, allowed tool list, maximum spawn depth, and default task priority.

Wave Flow

Wave 1 (parallel):  Scout ─────── Oracle
                         \       /
                          \     /
Wave 2 (sequential):       Architect
                              |
Wave 3 (parallel):    Worker ───── Kraken
                         \       /
                          \     /
Wave 4 (quality gate):     Critic
                              |
                    [ Loop if needed ]

---

Quick Start

Prerequisites

• Node.js >= 18.0.0
• An ANTHROPIC_API_KEY for Claude API access

Installation

npm install -g claude-fleet

Start the Server

# Set your API key (required for spawning agents)
export ANTHROPIC_API_KEY="sk-ant-..."

# Start the fleet server (default port 3847)
claude-fleet

# Or in development mode with hot reload
npm run dev

Authenticate and Use

# Register as team lead
fleet auth my-lead my-team team-lead
export FLEET_TOKEN="<token>"

# Launch a wave
fleet wave --objective "Add input validation to all API endpoints"

# Monitor workers
fleet workers --table

# View the dashboard
open http://localhost:3847/dashboard/

Multi-Repository Setup

fleet repos add api ./repos/api-service
fleet repos add frontend ./repos/web-client
fleet repos add shared ./repos/shared-types

fleet wave --repos api,frontend,shared \
  --objective "Implement rate limiting across all services"

---

API Overview

Public Endpoints (no auth)

Method	Path	Description
GET	/health	Server health check
GET	/metrics	Prometheus metrics
POST	/auth	Get JWT token

Core Endpoints (JWT required)

Method	Path	Description
POST	/tasks	Create task
GET	/tasks/:id	Get task details
PUT	/tasks/:id	Update task status
POST	/orchestrate/spawn	Spawn a worker
POST	/orchestrate/dismiss/:handle	Dismiss a worker
GET	/orchestrate/workers	List all workers
POST	/waves/execute	Launch a wave
GET	/waves/:id	Wave status
POST	/waves/:id/cancel	Cancel a wave
POST	/multi-repo/execute	Multi-repo wave
POST	/swarms	Create swarm
POST	/swarms/:id/blackboard	Post to blackboard
GET	/swarms/:id/blackboard	Read blackboard
POST	/teams/:name/broadcast	Broadcast to team (lead only)
POST	/memory/store	Store agent memory
GET	/memory/recall/:agentId/:key	Recall a memory
POST	/memory/search	Search memories (FTS5)
GET	/memory/:agentId	List agent memories
POST	/routing/classify	Classify task complexity
POST	/dag/sort	Topological sort of tasks
POST	/dag/ready	Find unblocked tasks
POST	/lmsh/translate	Natural language to shell
POST	/search	Full-text code search

See ARCHITECTURE.md for the complete API reference.

---

CLI Reference

# Server
fleet health                        # Check server health
fleet metrics                       # Get Prometheus metrics

# Authentication
fleet auth <handle> <team> [type]   # Register (team-lead|worker)

# Workers
fleet workers                       # List workers
fleet workers --table               # Table output
fleet spawn <handle> <prompt>       # Spawn worker
fleet dismiss <handle>              # Dismiss worker
fleet output <handle>               # Get worker output

# Waves
fleet wave --objective <text>       # Launch wave
fleet wave --repos a,b,c            # Target repos
fleet wave --roles scout,critic     # Specific roles
fleet wave-status [id]              # Check progress
fleet wave-cancel <id>              # Cancel wave

# Repositories
fleet repos                         # List repos
fleet repos add <name> <path>       # Add repo
fleet repos remove <name>           # Remove repo
fleet repos sync                    # Sync all

# Swarm
fleet swarms                        # List swarms
fleet blackboard <swarmId>          # Read blackboard
fleet blackboard-post <swarm> <sender> <type> <payload>

# Templates
fleet templates                     # List templates
fleet templates use <name>          # Apply template

# Agent Memory
fleet memory-store <agent> <key> <value> [--type <type>] [--tags <t1,t2>]
fleet memory-recall <agent> <key>   # Recall a memory
fleet memory-search <agent> <query> [--type <type>] [--limit <n>]
fleet memory-list <agent> [--limit <n>]

# Task Routing
fleet route <subject> [description] # Classify task complexity

# DAG Operations
fleet dag-sort <team>               # Topological sort of tasks
fleet dag-cycles <team>             # Check for dependency cycles
fleet dag-critical-path <team>      # Find critical path
fleet dag-ready <team>              # Find unblocked tasks

# Natural Language Shell
fleet lmsh <natural-language>       # Translate to shell command

# Search
fleet search <query> [--limit <n>]  # Full-text code search

# Audit
fleet audit                         # Run all quality checks
fleet audit --verbose               # Verbose output

---

MCP Integration

Claude Fleet exposes 98 tools via Model Context Protocol for direct Claude Code integration:

{
  "mcpServers": {
    "claude-fleet": {
      "command": "npx",
      "args": ["claude-fleet", "--mcp"],
      "env": {
        "CLAUDE_FLEET_URL": "http://localhost:3847",
        "FLEET_TOKEN": "your-jwt-token"
      }
    }
  }
}

Key MCP tools: wave_launch, wave_status, team_spawn, repo_add, blackboard_post.

---

Swarm Intelligence

Agents coordinate through a blackboard pattern:

• Blackboard — Shared message board with typed entries (directive, report, query, discovery)
• Pheromone trails — Path optimization markers left by agents
• Beliefs — Agent knowledge base entries
• Credits — Agent reward and resource system
• Priority routing — Critical, high, normal, low message priorities
• Read tracking — Know which agents have seen which messages

---

Configuration

Environment Variables

Variable	Default	Description
PORT	3847	Server port
HOST	0.0.0.0	Bind address
NODE_ENV	development	Environment
JWT_SECRET	auto-generated	Required in production
MAX_WORKERS	5	Max concurrent workers
ANTHROPIC_API_KEY	—	Claude API key
FLEET_MODE	tmux	tmux or headless
STORAGE_BACKEND	sqlite	sqlite, dynamodb, firestore, postgresql
DB_PATH	—	SQLite database location

Storage Backends

The storage factory (src/storage/factory.ts) supports pluggable backends:

• SQLite (default) — Embedded, zero-config
• DynamoDB — AWS serverless (optional dependency)
• Firestore — Google Cloud (optional dependency)
• PostgreSQL — Traditional SQL (optional dependency)
• S3 — Blob storage for large artifacts (optional dependency)

---

Building & Testing

Build

npm run build         # Compile TypeScript to dist/
npm run typecheck     # Type check only (no emit)
npm run lint          # ESLint
npm run lint:fix      # Auto-fix lint issues

Test

npm test              # Run unit tests (Vitest)
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report (60% threshold)

E2E Tests

npm run e2e           # Core (auth, tasks, chat)
npm run e2e:phase2-3  # Work items, mail
npm run e2e:cli       # CLI commands
npm run e2e:dashboard # Dashboard UI
npm run e2e:compound  # Compound machine
npm run e2e:all       # All suites

Full Verification

npm run verify        # typecheck + lint + test + e2e:all

Audit Loop

Continuous improvement loop that runs until the codebase passes all quality gates:

npm run audit         # Run until all checks pass
npm run audit:dry     # Dry run (no changes)

---

CI/CD (Headless Mode)

# .github/workflows/fleet-audit.yml
name: Fleet Audit
on: [push]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Fleet
        run: npm install -g claude-fleet
      - name: Run Audit Wave
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude-fleet --headless wave \
            --objective "Audit codebase for security vulnerabilities" \
            --roles scout,oracle,critic \
            --max-iterations 2

---

Documentation

• ARCHITECTURE.md — System architecture, API reference, and data flow
• DEPLOYMENT.md — Production deployment guide
• NATIVE-INTEGRATION.md — Claude Code native features integration

---

Contributing

See CONTRIBUTING.md for guidelines.

npm run dev       # Start with hot reload
npm test          # Unit tests
npm run e2e       # E2E tests
npm run lint      # Lint

License

MIT — see LICENSE.