Fleet Commander

One-click dashboard for orchestrating multiple Claude Code agent teams across repositories.

Launch, monitor, message, and shut down 15+ parallel AI agents from a single control plane.

Note: The npm package name is fleet-commander-ai (the npm package name differs from the repo name). CLI binary commands remain fleet-commander and fleet-commander-mcp.

Why Fleet Commander?

Running 15+ parallel Claude Code agents across multiple repos is chaos without a control plane. You lose track of which teams are working on what, miss CI failures, and have no way to intervene when an agent gets stuck.

| Capability | What it does | |------------|--------------| | Launch | One-click team launch per GitHub issue. FIFO queue with per-project concurrency limits. | | Monitor | Real-time SSE dashboard with status, phase, PR state, CI checks, and Gantt timeline. | | Message | Send instructions to running agents via stdin pipe. Editable PM message templates. | | Track | GitHub polling every 30s for PRs, CI status, and merges. Auto-merge support. | | Detect | Idle detection at 5 minutes, stuck detection at 10 minutes. Automatic status transitions. | | Scale | Multiple projects (repos), each with independent team slots, queues, and prompt files. |

Quick Start

Prerequisites

• Node.js 20+
• GitHub CLI -- authenticated (gh auth login)

Option A: Install from npm (recommended)

npm install -g fleet-commander-ai

Once installed, run fleet-commander to start the server on port 4680 and open the dashboard.

Or run without installing:

npx fleet-commander-ai

Option B: Clone from source

git clone https://github.com/hubertciebiada/fleet-commander.git
cd fleet-commander
npm run launch

This installs dependencies, builds the project, starts the server on port 4680, and opens your browser.

Windows shortcut

Double-click fleet-commander.bat

First steps

1. Add a project -- Open the Projects view (/projects), click Add Project, and enter your repo path and GitHub slug (e.g., org/repo). Click Install to deploy hooks.
2. Launch a team -- Open the Issue Tree (/issues), find an issue, and click the Play button. Fleet Commander creates a worktree, spawns a Claude Code agent, and starts working.

Screenshots

Architecture

graph TB
  Browser["React 19 SPA<br/>Dark Theme"] -->|"SSE + REST"| Server["Fastify :4680"]
  Server --> TeamMgr["Team Manager<br/>spawn / stdin / stdout"]
  Server --> EventCol["Event Collector<br/>hook events"]
  Server --> GitPoller["GitHub Poller<br/>PR / CI / merge"]
  Server --> IssueFetch["Issue Fetcher<br/>GraphQL, 60s cache"]
  Server --> StuckDet["Stuck Detector<br/>idle 5min / stuck 10min"]
  Server --> SSE["SSE Broker<br/>14 event types"]
  Server --> DB[("SQLite<br/>fleet.db, WAL")]
  TeamMgr -->|"spawn + stdin pipe"| CC["Claude Code<br/>stream-json"]
  CC -->|"hooks POST"| EventCol
  GitPoller -->|"gh CLI"| GitHub["GitHub API"]

Hook Events

Claude Code agent sessions fire lifecycle hooks (session start, tool use, notifications, errors, session end). Fleet Commander installs shell scripts into each project repo that POST these events back to the server. All hooks are fire-and-forget -- they exit 0 regardless of whether the POST succeeds, so they never block the agent.

Stdin/Stdout Pipes

Each agent team is a child_process.spawn() of claude with --input-format stream-json --output-format stream-json. Fleet Commander holds the stdin pipe open to send messages (PM instructions, CI results, merge notifications) and reads stdout for real-time output streaming. The stdout stream is parsed and broadcast to the dashboard via SSE.

SSE Push

The SSE Broker manages long-lived connections from the React dashboard. It emits 14 event types (team status changes, output chunks, PR updates, usage snapshots, heartbeats, etc.) so the UI updates in real time without polling. A 30-second heartbeat keeps connections alive through proxies.

GitHub Polling

The GitHub Poller runs every 30 seconds and uses the gh CLI (not Octokit) to check for PR state changes, CI check results, and merge status. When it detects a change, it updates the database and broadcasts an SSE event. This is how the dashboard knows when CI passes or a PR is merged.

Team Lifecycle

stateDiagram-v2
  [*] --> queued
  queued --> launching
  launching --> running
  running --> idle : 5 min no events
  running --> done : session ends normally
  running --> failed : process crashes
  idle --> running : new event received
  idle --> stuck : 10 min no events
  stuck --> running : new event received
  done --> [*]
  failed --> [*]

Walkthrough

1. Queued -- A team is created for an issue and placed in the FIFO queue. It waits here until a slot opens (per-project concurrency limit).
2. Launching -- A slot is available. Fleet Commander creates a git worktree, spawns a Claude Code process, and waits for the first event. If no event arrives within the launch timeout (default 5 min), the team is marked failed.
3. Running -- The agent is actively working. Hook events stream in, output is captured, and the dashboard shows real-time progress.
4. Idle -- No hook events for 5 minutes. The team is flagged but continues running. Any new event transitions it back to running.
5. Stuck -- No hook events for 5 minutes (from idle). The team is flagged for PM attention. A message can be sent via stdin to nudge the agent. Any new event transitions it back to running.
6. Done / Failed -- The session ends normally (done) or the process crashes / exits non-zero (failed). The worktree and branch can be cleaned up from the Projects view.

CI flow: PR detected -> CI green/red -> message to team via stdin -> PR merged -> team marked done

Configuration

All settings have sensible defaults. Override via environment variables:

| Variable | Default | Description | |----------|---------|-------------| | PORT | 4680 | Server port | | FLEET_HOST | 0.0.0.0 | Network interface to bind to | | FLEET_IDLE_THRESHOLD_MIN | 5 | Minutes before a team is marked idle | | FLEET_STUCK_THRESHOLD_MIN | 10 | Minutes before a team is marked stuck | | FLEET_LAUNCH_TIMEOUT_MIN | 5 | Minutes before a launching team is marked failed | | FLEET_MAX_CI_FAILURES | 3 | Unique CI failure types before blocking | | FLEET_EARLY_CRASH_THRESHOLD_SEC | 120 | Seconds before a SubagentStop is considered an early crash | | FLEET_EARLY_CRASH_MIN_TOOLS | 5 | Minimum tool-use events for a subagent to be considered healthy | | FLEET_GITHUB_POLL_MS | 30000 | GitHub polling interval (ms) | | FLEET_DB_PATH | Platform data dir | SQLite database file path (e.g. %APPDATA%/fleet-commander/fleet.db on Windows) | | FLEET_TERMINAL | auto | Windows terminal preference: auto, wt, or cmd | | FLEET_CLAUDE_CMD | claude | Claude Code CLI command | | FLEET_SKIP_PERMISSIONS | true | Skip CC permission prompts (--dangerously-skip-permissions) | | LOG_LEVEL | info | Server log level |

Built With

| Layer | Technology | |-------|------------| | Server | Fastify 5 on Node.js 20+ | | Client | React 19 with Vite 6 | | Language | TypeScript 5.7 | | Database | SQLite via better-sqlite3, WAL mode | | Styling | Tailwind CSS (GitHub-dark theme) | | Real-time | Server-Sent Events (SSE) | | Agent interface | Claude Code CLI (--input-format stream-json, --output-format stream-json) | | GitHub | gh CLI for all GitHub operations | | Testing | Vitest, Testing Library |

MCP Integration

Fleet Commander exposes tools via the Model Context Protocol over stdio transport. This allows Claude Code (or any MCP-compatible client) to query fleet state, launch teams, send messages, and inspect timelines programmatically.

# Add as an MCP server in Claude Code
claude mcp add fleet-commander -- node bin/fleet-commander-mcp.js

Or add a .mcp.json to your project root:

{
  "mcpServers": {
    "fleet-commander": {
      "command": "node",
      "args": ["bin/fleet-commander-mcp.js"],
      "cwd": "/path/to/fleet-commander"
    }
  }
}

All MCP tools use the fleet_ prefix (e.g., fleet_system_health, fleet_list_teams, fleet_send_message). See docs/mcp.md for the full tool reference and developer guide.

Views

| View | Path | What it shows | |------|------|---------------| | Fleet Grid | / | Team table with status, phase, PR, CI, duration. Toggle to Gantt timeline. | | Issue Tree | /issues | GitHub issue hierarchy with search. Play button launches a team per issue. | | Usage | /usage | Four progress bars: daily, weekly, Sonnet, and extra usage percentages. | | Projects | /projects | CRUD for projects. Install status, cleanup, prompt editor. | | Lifecycle | /lifecycle | Team state machine diagram + editable PM message templates. | | Settings | /settings | Read-only viewer for current server configuration. |

Development

| Command | Description | |---------|-------------| | npm run dev | Start dev server + Vite HMR | | npm run build | Production build (tsc + vite) | | npm start | Production server (node dist/server/index.js) | | npm test | Run all tests (vitest) | | npm run test:client | Client-only tests | | npm run test:e2e | End-to-end smoke test | | npm run launch | Auto-install, build, open browser | | npm run capture-screenshots | Generate screenshots with Playwright |

Contributing

Contributions are welcome. To get started:

1. Fork the repository
2. Create a branch from main (git checkout -b feat/your-feature)
3. Make your changes and add tests
4. Run the test suite (npm test)
5. Commit with a clear message (git commit -m "Add your feature")
6. Push to your fork (git push origin feat/your-feature)
7. Open a Pull Request against main

Please follow the existing code style and conventions. See CLAUDE.md for project-specific guidelines.

License

Apache-2.0