{"id":46393228,"url":"https://github.com/sethdford/claude-fleet","last_synced_at":"2026-03-05T09:11:50.835Z","repository":{"id":334537724,"uuid":"1141453016","full_name":"sethdford/claude-fleet","owner":"sethdford","description":"Multi-agent orchestration server for Claude Code with fleet coordination, swarm intelligence, and real-time collaboration","archived":false,"fork":false,"pushed_at":"2026-02-02T02:11:54.000Z","size":5747,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-02T11:52:39.849Z","etag":null,"topics":["ai-agents","claude","claude-code","fleet","mcp","multi-agent","orchestration","swarm","typescript"],"latest_commit_sha":null,"homepage":"https://sethdford.github.io/claude-fleet","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sethdford.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-24T21:43:31.000Z","updated_at":"2026-02-02T02:11:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sethdford/claude-fleet","commit_stats":null,"previous_names":["sethdford/claude-fleet"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/sethdford/claude-fleet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethdford%2Fclaude-fleet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethdford%2Fclaude-fleet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethdford%2Fclaude-fleet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethdford%2Fclaude-fleet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sethdford","download_url":"https://codeload.github.com/sethdford/claude-fleet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethdford%2Fclaude-fleet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30117552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T08:19:04.902Z","status":"ssl_error","status_checked_at":"2026-03-05T08:17:37.148Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude","claude-code","fleet","mcp","multi-agent","orchestration","swarm","typescript"],"created_at":"2026-03-05T09:11:50.115Z","updated_at":"2026-03-05T09:11:50.815Z","avatar_url":"https://github.com/sethdford.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Fleet\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/logo.svg\" alt=\"Claude Fleet Logo\" width=\"120\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eWaves of agents until the job is done\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/sethdford/claude-fleet/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/sethdford/claude-fleet/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/claude-fleet\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/claude-fleet\" alt=\"NPM Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-5.3-blue\" alt=\"TypeScript\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nMulti-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.\n\n```bash\n# Launch a wave across multiple repos\n$ fleet wave --repos api,frontend,shared --objective \"Add rate limiting\"\n\nWave 1: Spawning scouts...\n  Scout[api]      Mapped 47 endpoints\n  Scout[frontend] Found 12 API calls\n  Scout[shared]   Identified rate-limit types\n\nWave 2: Architect designing...\n  Architect       Proposed middleware approach\n\nWave 3: Implementation...\n  Worker[api]     Added middleware + config\n  Kraken[api]     22 tests passing\n\nWave 4: Review...\n  Critic          Approved. Creating PRs...\n\n3 PRs created. Objective achieved in 4 waves.\n```\n\n---\n\n## Architecture\n\n```\nsrc/\n├── index.ts           # Entry point — starts CollabServer\n├── server.ts          # Express HTTP + WebSocket server\n├── types.ts           # All type definitions (centralized)\n├── cli.ts             # CLI commands (fleet binary)\n├── storage/           # Data layer (SQLite default, DynamoDB/Firestore/PostgreSQL optional)\n├── workers/           # Worker process management \u0026 agent roles\n├── routes/            # HTTP route handlers (core, waves, swarm, tasks, etc.)\n├── validation/        # Zod schemas for all API inputs\n├── metrics/           # Prometheus metrics collection\n├── scheduler/         # Cron-based autonomous task scheduling\n├── mcp/               # Model Context Protocol bridge (98 tools)\n├── middleware/         # JWT auth, RBAC, validation middleware\n└── integrations/      # Third-party integrations (Linear)\n```\n\n**Layer dependency rules:**\n\n| Layer | Can Import From |\n|-------|-----------------|\n| `types.ts` | Nothing |\n| `storage/` | `types.ts` |\n| `workers/` | `storage/`, `types.ts` |\n| `routes/` | `workers/`, `storage/`, `validation/`, `types.ts` |\n| `server.ts` | All layers |\n\nAdditional directories:\n\n```\ncrates/                # Rust crates (compound accumulator, search engine, lmsh)\npackages/              # Monorepo packages (common, fleet, mcp, tmux, session, storage)\napps/cli/              # CLI app package\npublic/                # Dashboard UI \u0026 compound machine frontend\nscripts/               # Build, E2E test, and deployment scripts\n```\n\n### Key Technologies\n\n- **Express + WebSocket (ws)** — HTTP API and real-time events\n- **better-sqlite3** — Default embedded database (with umzug migrations)\n- **jsonwebtoken** — JWT authentication\n- **Zod** — Input validation for all endpoints\n- **prom-client** — Prometheus metrics\n- **@modelcontextprotocol/sdk** — MCP server integration\n- **Rust (NAPI-RS)** — 8 optional native crates for acceleration (compound, search, lmsh, logstream, dag, swarm, metrics, ringbus)\n\n---\n\n## Rust Native Acceleration\n\nClaude Fleet includes an optional Rust acceleration layer. All crates have JS fallback implementations — native binaries are never required.\n\n```\ncrates/\n├── compound/    # Ring-buffer accumulator for time-series metrics\n├── search/      # Tantivy-based full-text search engine\n├── lmsh/        # Natural language → shell translator\n├── logstream/   # High-performance log streaming\n├── dag/         # DAG operations (topo sort, critical path, cycle detection)\n├── swarm/       # Swarm coordination primitives\n├── metrics/     # Native Prometheus metrics engine\n└── ringbus/     # Lock-free ring buffer message bus\n```\n\nBuild native modules (optional):\n\n```bash\ncargo build --workspace --release\ncargo test --workspace    # 36 Rust tests\n```\n\n---\n\n## Agent Roles\n\n7 specialized agent roles with role-based access control:\n\n| Role | Purpose | Key Capability |\n|------|---------|----------------|\n| **Lead** | Orchestrates the fleet, delegates tasks | Can spawn other agents |\n| **Worker** | General-purpose implementation | Code changes, commits |\n| **Scout** | Explores codebases, maps dependencies | Read-only exploration |\n| **Kraken** | TDD specialist — red-green-refactor | Test-first development |\n| **Oracle** | Research and analysis | Deep code analysis |\n| **Critic** | Code review, quality gates | Review and approve |\n| **Architect** | System design, API contracts | Can spawn workers |\n\nEach role has a custom system prompt, allowed tool list, maximum spawn depth, and default task priority.\n\n### Wave Flow\n\n```\nWave 1 (parallel):  Scout ─────── Oracle\n                         \\       /\n                          \\     /\nWave 2 (sequential):       Architect\n                              |\nWave 3 (parallel):    Worker ───── Kraken\n                         \\       /\n                          \\     /\nWave 4 (quality gate):     Critic\n                              |\n                    [ Loop if needed ]\n```\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js \u003e= 18.0.0\n- An `ANTHROPIC_API_KEY` for Claude API access\n\n### Installation\n\n```bash\nnpm install -g claude-fleet\n```\n\n### Start the Server\n\n```bash\n# Set your API key (required for spawning agents)\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# Start the fleet server (default port 3847)\nclaude-fleet\n\n# Or in development mode with hot reload\nnpm run dev\n```\n\n### Authenticate and Use\n\n```bash\n# Register as team lead\nfleet auth my-lead my-team team-lead\nexport FLEET_TOKEN=\"\u003ctoken\u003e\"\n\n# Launch a wave\nfleet wave --objective \"Add input validation to all API endpoints\"\n\n# Monitor workers\nfleet workers --table\n\n# View the dashboard\nopen http://localhost:3847/dashboard/\n```\n\n### Multi-Repository Setup\n\n```bash\nfleet repos add api ./repos/api-service\nfleet repos add frontend ./repos/web-client\nfleet repos add shared ./repos/shared-types\n\nfleet wave --repos api,frontend,shared \\\n  --objective \"Implement rate limiting across all services\"\n```\n\n---\n\n## API Overview\n\n### Public Endpoints (no auth)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/health` | Server health check |\n| `GET` | `/metrics` | Prometheus metrics |\n| `POST` | `/auth` | Get JWT token |\n\n### Core Endpoints (JWT required)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/tasks` | Create task |\n| `GET` | `/tasks/:id` | Get task details |\n| `PUT` | `/tasks/:id` | Update task status |\n| `POST` | `/orchestrate/spawn` | Spawn a worker |\n| `POST` | `/orchestrate/dismiss/:handle` | Dismiss a worker |\n| `GET` | `/orchestrate/workers` | List all workers |\n| `POST` | `/waves/execute` | Launch a wave |\n| `GET` | `/waves/:id` | Wave status |\n| `POST` | `/waves/:id/cancel` | Cancel a wave |\n| `POST` | `/multi-repo/execute` | Multi-repo wave |\n| `POST` | `/swarms` | Create swarm |\n| `POST` | `/swarms/:id/blackboard` | Post to blackboard |\n| `GET` | `/swarms/:id/blackboard` | Read blackboard |\n| `POST` | `/teams/:name/broadcast` | Broadcast to team (lead only) |\n| `POST` | `/memory/store` | Store agent memory |\n| `GET` | `/memory/recall/:agentId/:key` | Recall a memory |\n| `POST` | `/memory/search` | Search memories (FTS5) |\n| `GET` | `/memory/:agentId` | List agent memories |\n| `POST` | `/routing/classify` | Classify task complexity |\n| `POST` | `/dag/sort` | Topological sort of tasks |\n| `POST` | `/dag/ready` | Find unblocked tasks |\n| `POST` | `/lmsh/translate` | Natural language to shell |\n| `POST` | `/search` | Full-text code search |\n\nSee [ARCHITECTURE.md](docs/ARCHITECTURE.md) for the complete API reference.\n\n---\n\n## CLI Reference\n\n```bash\n# Server\nfleet health                        # Check server health\nfleet metrics                       # Get Prometheus metrics\n\n# Authentication\nfleet auth \u003chandle\u003e \u003cteam\u003e [type]   # Register (team-lead|worker)\n\n# Workers\nfleet workers                       # List workers\nfleet workers --table               # Table output\nfleet spawn \u003chandle\u003e \u003cprompt\u003e       # Spawn worker\nfleet dismiss \u003chandle\u003e              # Dismiss worker\nfleet output \u003chandle\u003e               # Get worker output\n\n# Waves\nfleet wave --objective \u003ctext\u003e       # Launch wave\nfleet wave --repos a,b,c            # Target repos\nfleet wave --roles scout,critic     # Specific roles\nfleet wave-status [id]              # Check progress\nfleet wave-cancel \u003cid\u003e              # Cancel wave\n\n# Repositories\nfleet repos                         # List repos\nfleet repos add \u003cname\u003e \u003cpath\u003e       # Add repo\nfleet repos remove \u003cname\u003e           # Remove repo\nfleet repos sync                    # Sync all\n\n# Swarm\nfleet swarms                        # List swarms\nfleet blackboard \u003cswarmId\u003e          # Read blackboard\nfleet blackboard-post \u003cswarm\u003e \u003csender\u003e \u003ctype\u003e \u003cpayload\u003e\n\n# Templates\nfleet templates                     # List templates\nfleet templates use \u003cname\u003e          # Apply template\n\n# Agent Memory\nfleet memory-store \u003cagent\u003e \u003ckey\u003e \u003cvalue\u003e [--type \u003ctype\u003e] [--tags \u003ct1,t2\u003e]\nfleet memory-recall \u003cagent\u003e \u003ckey\u003e   # Recall a memory\nfleet memory-search \u003cagent\u003e \u003cquery\u003e [--type \u003ctype\u003e] [--limit \u003cn\u003e]\nfleet memory-list \u003cagent\u003e [--limit \u003cn\u003e]\n\n# Task Routing\nfleet route \u003csubject\u003e [description] # Classify task complexity\n\n# DAG Operations\nfleet dag-sort \u003cteam\u003e               # Topological sort of tasks\nfleet dag-cycles \u003cteam\u003e             # Check for dependency cycles\nfleet dag-critical-path \u003cteam\u003e      # Find critical path\nfleet dag-ready \u003cteam\u003e              # Find unblocked tasks\n\n# Natural Language Shell\nfleet lmsh \u003cnatural-language\u003e       # Translate to shell command\n\n# Search\nfleet search \u003cquery\u003e [--limit \u003cn\u003e]  # Full-text code search\n\n# Audit\nfleet audit                         # Run all quality checks\nfleet audit --verbose               # Verbose output\n```\n\n---\n\n## MCP Integration\n\nClaude Fleet exposes 98 tools via Model Context Protocol for direct Claude Code integration:\n\n```json\n{\n  \"mcpServers\": {\n    \"claude-fleet\": {\n      \"command\": \"npx\",\n      \"args\": [\"claude-fleet\", \"--mcp\"],\n      \"env\": {\n        \"CLAUDE_FLEET_URL\": \"http://localhost:3847\",\n        \"FLEET_TOKEN\": \"your-jwt-token\"\n      }\n    }\n  }\n}\n```\n\nKey MCP tools: `wave_launch`, `wave_status`, `team_spawn`, `repo_add`, `blackboard_post`.\n\n---\n\n## Swarm Intelligence\n\nAgents coordinate through a blackboard pattern:\n\n- **Blackboard** — Shared message board with typed entries (directive, report, query, discovery)\n- **Pheromone trails** — Path optimization markers left by agents\n- **Beliefs** — Agent knowledge base entries\n- **Credits** — Agent reward and resource system\n- **Priority routing** — Critical, high, normal, low message priorities\n- **Read tracking** — Know which agents have seen which messages\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | `3847` | Server port |\n| `HOST` | `0.0.0.0` | Bind address |\n| `NODE_ENV` | `development` | Environment |\n| `JWT_SECRET` | auto-generated | **Required in production** |\n| `MAX_WORKERS` | `5` | Max concurrent workers |\n| `ANTHROPIC_API_KEY` | — | Claude API key |\n| `FLEET_MODE` | `tmux` | `tmux` or `headless` |\n| `STORAGE_BACKEND` | `sqlite` | `sqlite`, `dynamodb`, `firestore`, `postgresql` |\n| `DB_PATH` | — | SQLite database location |\n\n### Storage Backends\n\nThe storage factory (`src/storage/factory.ts`) supports pluggable backends:\n\n- **SQLite** (default) — Embedded, zero-config\n- **DynamoDB** — AWS serverless (optional dependency)\n- **Firestore** — Google Cloud (optional dependency)\n- **PostgreSQL** — Traditional SQL (optional dependency)\n- **S3** — Blob storage for large artifacts (optional dependency)\n\n---\n\n## Building \u0026 Testing\n\n### Build\n\n```bash\nnpm run build         # Compile TypeScript to dist/\nnpm run typecheck     # Type check only (no emit)\nnpm run lint          # ESLint\nnpm run lint:fix      # Auto-fix lint issues\n```\n\n### Test\n\n```bash\nnpm test              # Run unit tests (Vitest)\nnpm run test:watch    # Watch mode\nnpm run test:coverage # Coverage report (60% threshold)\n```\n\n### E2E Tests\n\n```bash\nnpm run e2e           # Core (auth, tasks, chat)\nnpm run e2e:phase2-3  # Work items, mail\nnpm run e2e:cli       # CLI commands\nnpm run e2e:dashboard # Dashboard UI\nnpm run e2e:compound  # Compound machine\nnpm run e2e:all       # All suites\n```\n\n### Full Verification\n\n```bash\nnpm run verify        # typecheck + lint + test + e2e:all\n```\n\n### Audit Loop\n\nContinuous improvement loop that runs until the codebase passes all quality gates:\n\n```bash\nnpm run audit         # Run until all checks pass\nnpm run audit:dry     # Dry run (no changes)\n```\n\n---\n\n## CI/CD (Headless Mode)\n\n```yaml\n# .github/workflows/fleet-audit.yml\nname: Fleet Audit\non: [push]\n\njobs:\n  audit:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - name: Install Claude Fleet\n        run: npm install -g claude-fleet\n      - name: Run Audit Wave\n        env:\n          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n        run: |\n          claude-fleet --headless wave \\\n            --objective \"Audit codebase for security vulnerabilities\" \\\n            --roles scout,oracle,critic \\\n            --max-iterations 2\n```\n\n---\n\n## Documentation\n\n- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — System architecture, API reference, and data flow\n- [DEPLOYMENT.md](docs/DEPLOYMENT.md) — Production deployment guide\n- [NATIVE-INTEGRATION.md](docs/NATIVE-INTEGRATION.md) — Claude Code native features integration\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n```bash\nnpm run dev       # Start with hot reload\nnpm test          # Unit tests\nnpm run e2e       # E2E tests\nnpm run lint      # Lint\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethdford%2Fclaude-fleet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsethdford%2Fclaude-fleet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethdford%2Fclaude-fleet/lists"}