Architecture

Fleet is a pure Go application. Single binary, no JavaScript runtime, no Docker, no Node.js. This page covers the system design, package layout, and key decisions.

High-Level Architecture

cmd/fleet/main.go          CLI subcommand router
          ┌────┐
          └──┬──→ fleet mcp serve → internal/mcp/       MCP server (JSON-RPC over stdio)
             │                     26 tools for Claude Code / any MCP client
             │
             └──→ internal/actions/service.go   Business logic orchestration
                 (wraps store + tmux + prompts)

          ─────────────────────────────────────────────────────────────────────────────
          │     │    │    │    │    │    │    │    │    │    │    │    │    │    │
          └──┬──┴──┬──┴──┬──┴──┬──┴──┬──┴──┬──┴──┬──┴──┬──┴──┬──┴──┬──┘
              │    │    │    │    │    │    │    │    │    │
          ┌───┴──┐ ┌───┴──┐ ┌───┴──┐ ┌───┴──┐
          │      │ │      │ │      │ │      │
      store/  tmux/client.go  prompt/manager   pipeline/engine
      (SQLite) (session mgmt) (file prompts)  (stage orchestration)
              │    │    │    │
              └───────────────────────────────────────────────────────────────────────
              │     │    │    │
          ┌───┴──┐ ┌───┴──┐ ┌───┴──┐ ┌───┴──┐
          │      │ │      │ │      │ │      │
      brain/  fabric/   fleetlog/  issuewatcher/
      (daemon) (event bus) (history) (label polling)

Layer Diagram

Each layer has strict dependency rules. Higher layers depend on lower layers, never the reverse.

CLI

cmd/fleet, ui/

MCP Server

mcp/

Actions (Business Logic)

actions/, pipeline/, brain/

Infrastructure

store/, tmux/, fabric/, prompt/, fleetlog/, issuewatcher/

Domain Model

model/

Package Overview

Fleet is organized into ~25 focused packages, each with a single responsibility:

Package	Purpose
cmd/fleet	CLI subcommand router
model/	Pure data structs (types.go), no logic
store/	SQLite CRUD, one file per domain
actions/	Business logic orchestration (wraps store + tmux + prompts)
actions/handbook.go	Fleet Agent Handbook compiled into every agent prompt
ui/	CLI text dashboards and output formatters
mcp/	JSON-RPC 2.0 MCP server, 26 tools
pipeline/	Pipeline orchestration engine (Sweep, AdvanceRun)
brain/	Event-driven daemon (eval, risk, alerts, quarantine, evolve)
fabric/	Agent coordination: events, claims, inbox, tasks, subscriptions
budget/	Agent cost tracking and budget enforcement
resolve/	Fuzzy name matching (exact, prefix, substring)
fleetlog/	Unified decision/conversation history
issuewatcher/	GitHub label watcher with expiring dedup
prompt/	File-based prompt management with frontmatter
project/	Config discovery (.fleet/config.yaml, org.yaml)
eval/	Stateless 6-dimension scoring
risk/	Logistic regression risk model (8 features)
tmux/	tmux session lifecycle management
catalog/agents/	136 ready-to-use prompt templates

Key Design Decisions

tmux for agent isolation

Each agent runs in its own tmux session. This provides process isolation, session persistence across disconnects, and observable output via tmux capture-pane. Agent status is determined at runtime via tmux.HasSession(), not stored in the database.

SQLite for persistence

Single-file database with no external dependencies. In-memory SQLite (NewMemory()) for tests. Variadic project parameters enable project-scoped queries. UNIQUE(name, project) constraint allows the same agent name across repos.

Compiled handbook

The Fleet Agent Handbook is compiled into the binary (actions/handbook.go), not stored externally. Every agent gets it prepended to their prompt at launch. Role-based skill directives use deterministic selection, not conditional logic.

Fabric as shared event bus

Cross-repo coordination via publish/subscribe. Both org and project agents use the same event bus. Events include structured types (pr_created, ticket_ready, pr_approved) with JSON payloads for machine-readable data exchange.

Stdio MCP transport

No HTTP server, no WebSocket. The MCP server communicates via stdin/stdout using JSON-RPC 2.0. Claude Code spawns fleet mcp serve as a child process. Zero network configuration, zero ports, zero TLS certificates.

File-based prompt overlays

Org-level prompts at ~/.team-dashboard/prompts/ with per-repo overlays at .fleet/prompts/. YAML-like frontmatter for metadata. This allows prompt customization without touching agent config.

Org-Centric Architecture

Fleet is org-centric with two tiers of agents:

~/.team-dashboard/org.yaml          Org agents (CEO, CPO, CTO, CMO, PMs, POs)
                                   Org watcher: fleet watcher start --org
                                   Project sentinel: __org__
                                   See events from ALL repos

<repo>/.fleet/config.yaml          Repo agents (devs, QA, release managers)
                                   Repo watcher: fleet watcher start
                                   Scoped to one repo
                                   See events from their repo only

Fabric is the shared event bus. Both tiers publish and subscribe to the same events. Org agents use OrgConfig.AsProjectConfig() adapter to present a unified interface to the actions layer.

Reactive Event Chain

The watcher daemon, fabric bus, and agent subscriptions create a fully autonomous reactive chain:

Label added (ready) → label watcher publishes ticket_ready
          → subscription processor matches frontend-dev → agent starts
          → agent creates PR, publishes pr_created, adds needs-review label
          → label watcher publishes pr_needs_review
          → tech-lead + qa-lead start, review, publish pr_approved
          → release-manager starts, merges, adds shipped label
          → label watcher publishes ticket_shipped
          → CEO, CPO, CTO see it in their next run

Brain Daemon

The brain is an event-driven daemon started with fleet brain start. It listens on ~/.team-dashboard/brain.sock for JSON signals and dispatches handlers asynchronously.

Eval

6-dimension agent scoring (task, reliability, quality, efficiency, collaboration, cost)

Risk

Logistic regression model on 8 features for risk assessment

Alerts

Threshold-based alerting on eval and risk scores

Quarantine

Automatically disable agents that exceed risk thresholds

Evolve

Suggest prompt improvements based on performance history

The brain runs a 5-minute heartbeat for idle detection and health monitoring.