Fleet Canvas

A spatial dashboard for staying oriented and cost-aware while running many Claude Code agents at once.

Screenshots

Canvas with multiple agents — blocked state shows a loud "Needs Input" banner:

Cost badges and token counts per agent — all done:

The Problem

Running multiple Claude Code agents in parallel unlocks real velocity — but the moment you have 3–6 agents going, two things break down:

1. Orientation. You lose track of which session is doing what, which is stuck, and which needs a decision.
2. Cost blindness. N agents burn ~N× the tokens. Easy to wake up to a spent budget with no per-agent breakdown.

The Solution

Fleet Canvas is a canvas of agent cards. Each card answers three questions at a glance:

• What is this agent doing right now? (rolling one-line summary)
• Does it need me? (idle / working / blocked-on-input / done — with a loud blocked signal)
• What is it costing? (running token + $ estimate, per agent and total)

Architecture

React + TypeScript (Vite)  <——WebSocket——>  Node.js backend
  - Canvas of agent cards                   - Agent manager
  - Per-agent output drawer                 - node-pty per agent  
  - Cost + status badges                    - git worktree lifecycle
                                            - Stream parser → status
                                            - Cost estimator
                                            - Per-agent log files

Stack

• Frontend: React 18 + TypeScript + Vite
• Backend: Node.js with Express + WebSockets
• Process spawning: node-pty (with child_process fallback)
• Isolation: git worktrees — one per agent, separate branches
• Testing: Vitest (unit) + Playwright (e2e) + smoke test

Quick Start

# Prerequisites: Node.js 18+, git
npm install

# Development (both servers)
npm run dev

# Or run backend and frontend separately:
npm run dev:backend   # http://localhost:3001
npm run dev:frontend  # http://localhost:5173

# Use a custom agent command (e.g. the fake CLI for testing):
CANVAS_AGENT_CMD="node scripts/fake-claude.mjs --mode=done" npm run dev:backend

Verify (CI)

npm run verify
# Runs: tsc --noEmit, eslint, vitest, vite build, playwright test, smoke test

fake-claude.mjs

A fake claude CLI for testing — no real tokens spent. Selectable via CANVAS_AGENT_CMD:

# Modes: done | blocked | idle | crash
CANVAS_AGENT_CMD="node scripts/fake-claude.mjs --mode=blocked" npm run dev:backend

Features

• Agent cards — each shows status, rolling summary, cost estimate
• Live output — expand any card to see full streamed output
• Status detection — working / idle / blocked / done / error from PTY stream heuristics
• Cost tracking — per-agent token + $ estimate with ~ flag for estimates; total across all agents
• Overnight guard — blocked agents show a loud banner; idle detection after silence timeout
• Log durability — each agent's output written to logs/<agentId>.log; survives browser refresh
• Worktree lifecycle — creates git worktree on add, cleans up on remove
• Reconnect — frontend auto-reconnects to backend after disconnect

What's cut from v1 (roadmap)

• Inter-agent coordination — human orientation first, autonomous orchestration later
• Auto-merging — merging parallel outputs is where danger lives; needs its own design pass
• Dependency graphs — speculative until users ask for it
• Multi-machine / hosted — v1 is local-only
• Non-Claude-Code agents — architecture supports it (just a process + parser), v1 targets claude

Screenshots

See the Screenshots section near the top of this README.

License

MIT