https://github.com/sethdford/claude-fleet
Multi-agent orchestration server for Claude Code with fleet coordination, swarm intelligence, and real-time collaboration
https://github.com/sethdford/claude-fleet
ai-agents claude claude-code fleet mcp multi-agent orchestration swarm typescript
Last synced: 4 months ago
JSON representation
Multi-agent orchestration server for Claude Code with fleet coordination, swarm intelligence, and real-time collaboration
- Host: GitHub
- URL: https://github.com/sethdford/claude-fleet
- Owner: sethdford
- License: mit
- Created: 2026-01-24T21:43:31.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-02T02:11:54.000Z (5 months ago)
- Last Synced: 2026-02-02T11:52:39.849Z (5 months ago)
- Topics: ai-agents, claude, claude-code, fleet, mcp, multi-agent, orchestration, swarm, typescript
- Language: TypeScript
- Homepage: https://sethdford.github.io/claude-fleet
- Size: 5.48 MB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
```bash
# 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):
```bash
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
```bash
npm install -g claude-fleet
```
### Start the Server
```bash
# 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
```bash
# Register as team lead
fleet auth my-lead my-team team-lead
export FLEET_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
```bash
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](docs/ARCHITECTURE.md) for the complete API reference.
---
## CLI Reference
```bash
# Server
fleet health # Check server health
fleet metrics # Get Prometheus metrics
# Authentication
fleet auth [type] # Register (team-lead|worker)
# Workers
fleet workers # List workers
fleet workers --table # Table output
fleet spawn # Spawn worker
fleet dismiss # Dismiss worker
fleet output # Get worker output
# Waves
fleet wave --objective # 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 # Cancel wave
# Repositories
fleet repos # List repos
fleet repos add # Add repo
fleet repos remove # Remove repo
fleet repos sync # Sync all
# Swarm
fleet swarms # List swarms
fleet blackboard # Read blackboard
fleet blackboard-post
# Templates
fleet templates # List templates
fleet templates use # Apply template
# Agent Memory
fleet memory-store [--type ] [--tags ]
fleet memory-recall # Recall a memory
fleet memory-search [--type ] [--limit ]
fleet memory-list [--limit ]
# Task Routing
fleet route [description] # Classify task complexity
# DAG Operations
fleet dag-sort # Topological sort of tasks
fleet dag-cycles # Check for dependency cycles
fleet dag-critical-path # Find critical path
fleet dag-ready # Find unblocked tasks
# Natural Language Shell
fleet lmsh # Translate to shell command
# Search
fleet search [--limit ] # 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:
```json
{
"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
```bash
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
```bash
npm test # Run unit tests (Vitest)
npm run test:watch # Watch mode
npm run test:coverage # Coverage report (60% threshold)
```
### E2E Tests
```bash
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
```bash
npm run verify # typecheck + lint + test + e2e:all
```
### Audit Loop
Continuous improvement loop that runs until the codebase passes all quality gates:
```bash
npm run audit # Run until all checks pass
npm run audit:dry # Dry run (no changes)
```
---
## CI/CD (Headless Mode)
```yaml
# .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](docs/ARCHITECTURE.md) — System architecture, API reference, and data flow
- [DEPLOYMENT.md](docs/DEPLOYMENT.md) — Production deployment guide
- [NATIVE-INTEGRATION.md](docs/NATIVE-INTEGRATION.md) — Claude Code native features integration
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
```bash
npm run dev # Start with hot reload
npm test # Unit tests
npm run e2e # E2E tests
npm run lint # Lint
```
## License
MIT — see [LICENSE](LICENSE).