fleet

fleet is a set of tools and skills for running a fleet of long-lived Claude Code sessions: each session owns one repository, compute campaign or shared resource, and a coordinator session routes between them.

A session in a pane looks like typing claude in a terminal. Keeping a dozen of them useful for weeks is not: each needs a role it can re-read after a restart, a place in a recovery snapshot, a name nothing else answers to, and watchers that survive — or are known not to survive — an upgrade. fleet supplies the mechanical parts of that and records the judgement parts as skills.

What it gives you:

• Recovery. fleetsnap records which pane resumes which transcript while the fleet is healthy; fleetrestore rebuilds tmux, labels and sessions after a power cycle.

• Safe upgrades. fleetupgrade finds sessions on a stale binary and who would lose runtime state on restart.

• Watched cluster work. fleetwatch derives which scheduler jobs have a live watcher, from the scheduler and /proc rather than from notes.

• Onboarding and spin-down. fleetspawn brings one new session in — pane, labels, launch, verification — and never answers the folder-trust prompt; fleetretire parks or retires one, recording how to resume it first.

• Context trimming. fleetcontext measures what each session carries and recommends; it compacts one session at a time, on the human’s word, and confirms the compaction in the transcript.

• Visibility. fleetlog, fleetcost and fleetwaiting reconstruct who talks to whom, what it costs, and who is blocked on the human.

Design rules that run through all of it:

• Derive, don’t record. Anything observable at runtime is computed from the live system. Hand-kept copies of observed state rot, and nothing announces that they have.

• Stdlib only. The tools are the recovery path after a disk loss; a recovery tool that needs a package installed first fails exactly when it is needed.

• Read-only by default. Anything that changes tmux or launches a session prints a plan unless given --go.

• Authority stays with the human. No session, the coordinator included, holds it.

New here? Read Concepts, then Installation, then Your first fleet — which takes you from an empty configuration to a fleet you can leave running, and on to mail with someone else’s.

Contents

• Concepts
  • Sessions, kinds and the coordinator
  • Two channels, and one of them is not what it looks like
  • Three layers, kept apart on purpose
  • What a restart keeps, and what it does not
  • Identity
• Installation
  • Requirements
  • Configure
  • Link
  • Next steps
• Your first fleet
  • 1. Decide the roles before creating anything
  • 2. Write the configuration
  • 3. Bring the first session up
  • 4. The four habits that keep it alive
  • 5. Mail with another person’s fleet
  • Where new fleets go wrong
• Configuration
  • Sections
• Tools
• Skills
• Templates
  • Brief
  • Conventions
  • Configuration
• Checks that fail toward the reassuring answer
  • A. The check cannot distinguish itself from its target
  • B. The proxy diverges from the thing it stands for
  • C. The check had only one possible outcome
  • The rule that covers them all
  • The part that is about people, not shells
• Testing and contributing
  • Rules for changes
  • Continuous integration
  • Releasing
  • Building these docs
• API
  • fleet package