fleet-commander: Instructions file for Claude Code

AGENTS.md

Guidance for AI coding agents working in the Fleet Commander repository.

For Claude-specific conventions, see CLAUDE.md. This file is intended to be self-contained for any agent.

---

Build & Run

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

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

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

# Run all Go tests
go test ./...

# Run a specific package's tests
go test ./internal/squadron/...

# Build the React SPA only
make build-web

# Build SPA + embed into Go binary + install to PATH
make build-all

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).

---

Data Model

A Fleet represents a managed repository. It stores:

• RepoPath — absolute path to the repo root
• ShortName — human-readable alias (defaults to directory basename)
• Agents — list of Agent structs
• Fleet metadata is persisted in .fleet/config.json inside the managed repo

An Agent represents one coding agent session:

• Name — unique identifier (used for tmux session name: fleet-<Name>)
• Branch — git branch the agent works on
• WorktreePath — path to the git worktree
• Driver — which agent CLI drives this session (claude-code, codex, aider, kimi-code, antigravity, generic)
• StateFile — path to .fleet/states/<Name>.json (used by hooks)
• Persona — optional built-in personality key
• FightMode — whether the agent roasts squadron mates

Global index: ~/.fleet/repos.json tracks all registered repos for multi-repo commands like fleet queue --all.

---

Package Layout

Package	Responsibility
cmd/fleet/	Cobra CLI commands, go:embed for the web SPA, main.go entrypoint
internal/fleet/	Fleet/Agent structs, JSON config persistence, Load() / Init()
internal/tmux/	tmux session creation, attachment, killing; session names are fleet-<agent>
internal/monitor/	Agent state detection: hook-based primary, tmux pane-scrape fallback
internal/tui/	Bubble Tea TUI for fleet queue and the hangar terminal overlay
internal/worktree/	Git worktree CRUD: Create, CreateFromExisting, Remove, Move, List, Exists
internal/context/	Shared JSON store (.fleet/context.json) with file locking; channels, logs, agent sections
internal/state/	Atomic read/write of .fleet/states/<agent>.json; IsStale(ttl) helper
internal/hooks/	Inject/remove fleet signal hooks in .claude/settings.json per worktree
internal/driver/	Driver interface + implementations for each supported agent CLI
internal/squadron/	Squadron launch logic, prompt suffix assembly (consensus, merger, fight mode, personas)
internal/hangar/	Web server, REST API, WebSocket hub, terminal proxy, embedded SPA serving
web/	React SPA source. Built to web/dist, copied to cmd/fleet/webdist for embedding