fleet-commander: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

For agent-neutral guidance (self-contained), see AGENTS.md. Keep both files in sync when architecture changes.

Build & Run

# Build the binary
go build -o fleet ./cmd/fleet/

# Run directly without building
go run ./cmd/fleet/ <command>

# Install to PATH
go install ./cmd/fleet/

# Run tests
go test ./...

# Run a single package's tests
go test ./internal/monitor/...

# Build web UI + Go binary with embedded SPA (installs to PATH)
make build-all

# Build web UI only
make build-web

# Run web tests
cd web && npm run test

The binary must be placed alongside fleet.tmux.conf for the tmux config to be auto-sourced (it looks for the conf file relative to the executable path).

Tech stack: Go 1.21+ (backend), React 18 + TypeScript + Vite (frontend), tmux (session management), git worktrees (isolation).

Architecture

Fleet Commander is a CLI + TUI tool for managing parallel AI coding agent sessions, each in its own git worktree. The user stays in control — there is no AI coordinator.

Data model:

• Fleet — owns RepoPath, ShortName, and a list of Agents. Persisted at .fleet/config.json inside the managed repo.
• Agent — Name (unique, used as tmux session: fleet-<Name>), Branch, WorktreePath, Driver (one of claude-code, codex, aider, kimi-code, antigravity, generic), StateFile, optional Persona, FightMode bool.
• Global index: ~/.fleet/repos.json tracks all registered repos for cross-repo commands (fleet queue --all).

Package layout:

• cmd/fleet/ — Cobra CLI wiring split across main.go, cmd_agents.go, cmd_context.go, cmd_launch.go, cmd_repos.go, cmd_utils.go. Commands: init, add, list, start, attach, stop, queue, remove, hint, hangar, context, repos, launch, signal, unlock, rename, clear.
• cmd/fleet/embed.go — go:embed all:webdist directive for the compiled React SPA (cmd/fleet/webdist/).
• internal/fleet/ — Core data model. Fleet and Agent structs, JSON config persistence at .fleet/config.json. Load() walks up the directory tree to find a fleet.
• internal/global/ — Global cross-repo state at ~/.fleet/ (repos index, global context/log).
• internal/tmux/ — Thin wrapper around tmux CLI commands. Sessions are named fleet-<agentName>. Sources fleet.tmux.conf after creating a session (best-effort).
• internal/monitor/ — Reads tmux pane content via capture-pane and classifies agent state as working, waiting, stopped, or starting. State detection inspects only the bottom 15 lines and checks for Claude Code-specific patterns: "esc to interrupt", spinner characters, "Esc to cancel", ❯ prompt, etc.
• internal/tui/ — Bubble Tea TUI for fleet queue. Lists all agents with live state indicators, refreshes every 2 seconds. Selecting an agent starts its session if stopped, then attaches. After detaching (Ctrl+B, Q), the TUI loop restarts automatically.
• internal/worktree/ — Git worktree CRUD: Create, CreateFromExisting, Remove, List, Move, Exists. Manager.Create(path, branch) runs git worktree add -b <branch> <path>.
• internal/context/ — Shared context store (.fleet/context.json). Agents can publish and read context from each other. Uses POSIX advisory file locks (flock) on .fleet/context.lock with a 5-second timeout. Supports named private channels with fixed membership (names are used as-is; an empty name defaults to channel-default).
• internal/state/ — State file read/write for agent state signaling between Claude Code hooks and the monitor. Atomic writes via temp-file + rename. States live in .fleet/states/<name>.json. IsStale(ttl) helper for fallback-detection.
• internal/hooks/ — Claude Code hook injection/removal. Injects fleet signal working (PreToolUse) and fleet signal waiting (Stop) into .claude/settings.json in each worktree. Entries are tagged with "_fleet": true for safe removal. Hooks read FLEET_STATE_FILE and FLEET_AGENT_NAME env vars.
• internal/hangar/ — Web-based squadron mission control (fleet hangar). Go HTTP server + embedded React SPA.
  • internal/hangar/server.go — HTTP server, route registration, SPA serving (embedded or Vite dev proxy).
  • internal/hangar/tui.go — Bubble Tea TUI shown in the terminal while the server runs (zen/log views).
  • internal/hangar/api/ — REST handlers for fleet info, personas, drivers, squadron launch, agent generation, and stop.
  • internal/hangar/ws/ — WebSocket hub that polls .fleet/context.json every 2s and broadcasts new channel messages and agent state changes.
  • internal/hangar/terminal/ — WebSocket-to-PTY proxy for tmux attach-session, powers the browser terminal.
• internal/driver/ — Driver interface and implementations (claude-code, codex, aider, kimi-code, antigravity, generic). Each driver implements state detection, hook injection (where supported), and command building.
• internal/squadron/ — Squadron launch logic. RunHeadless() creates worktrees, tmux sessions, context channels, and prompt files. BuildMergerSuffix(), BuildConsensusSuffix(), ApplyPersona(), and fight-mode suffix assembly live here.
• web/ — React 18 + TypeScript + Vite SPA for the hangar UI. Built with make build-web, embedded into the Go binary via make build-all.
  • web/src/components/wizard/ — Squadron setup wizard (SetupStep → AgentsStep → ReviewStep, with PersonaStep as a per-agent modal from AgentsStep).
  • web/src/components/mission/ — Mission control view (MissionControl, ContextLog, AgentPill, AgentTooltip, MultiView).
  • web/src/components/terminal/ — xterm.js terminal page for "Assume Control".
  • web/src/hooks/ — useWebSocket (auto-reconnect JSON event stream), useFleet (fleet data fetching).
  • web/src/api.ts — Typed API client for all REST endpoints.