README

Operator tools for a Robot Council fleet: a fleet of AI coding agents (Claude Code seats) that coordinate through a shared service. fleet-kit is for two people in an organization that runs one:

• Operators, who keep the seats running on their own machines. seat-stage brings a machine's seats back, resumed and joined to the fleet, after a reboot or an update. seat-pace says whether the fleet's usage allowance is being spent faster or slower than a straight line to its reset.
• Coordinators, who decide what the seats do. They read seat-pace's verdicts and set the policy for what happens when the fleet is on course to run out. The kit never acts on a verdict.

You install fleet-kit and keep your own configuration in a private repository of your own. You do not fork it: a fork of a public repository stays public, and your seats file (machine names, checkout paths, conversation ids), your pacing policy and your on_change scripts must not be.

Start with Getting started if you operate machines, or the Coordinator guide if you decide what the seats do.

Documentation

The documentation is the wiki: Getting started, the Coordinator guide, Restarting a machine's seats and Pacing a usage allowance. It is not in the package: an installed copy has no offline docs. The pacing policy template you copy is in the repository, at examples/pacing-policy.example.md.

What's verified

Everything below was built and tested against recorded and faked output on macOS, Linux and Windows, and measured by hand on one Windows 11 machine (Claude Code 2.1.304, psmux 3.3.8). These have not been run live, and you should expect to be the first to:

What was measured, on Windows: where Claude Code keeps its OAuth credential, that psmux's capture-pane reads a window (so confirm_channels works there), how to tell which process holds a conversation, and the order of arguments the channel flag takes. Each is recorded in the doc it affects.

Install

PHP 8.4 or later and Composer. The usual way:

composer global require robot-council/fleet-kit        # seat-pace and seat-stage on your PATH

or, in a project of your own, composer require robot-council/fleet-kit, which puts vendor/bin/seat-pace and vendor/bin/seat-stage in place. composer create-project robot-council/fleet-kit gives a copy of the release to run from (no tests or CI). To work on fleet-kit itself and send a change upstream, clone it:

git clone https://github.com/robot-council/fleet-kit && cd fleet-kit && composer install

composer global require needs Composer's global vendor/bin on your PATH (composer global config bin-dir --absolute prints it). On Windows Composer writes .bat proxies, so seat-pace and seat-stage run from any terminal; the bin/*.ps1 wrappers are optional, for Task Scheduler and for running a checkout from PowerShell without a proxy.

Your seats file is yours, not the package's. Keep it in a private repository of your own and remember it once with seat-stage config set <path> (or point FLEET_KIT_CONFIG or --config at it); the default is seats.toml in the current directory. The examples ship with the package, in vendor/robot-council/fleet-kit/examples/ (or $(composer global config home)/vendor/robot-council/fleet-kit/examples/ for a global install). Getting started walks through it.

Scheduler examples (examples/schedulers/) name /path/to/fleet-kit/bin/seat-pace. For a Composer install use the proxy instead: vendor/bin/seat-pace in your project, or seat-pace in Composer's global bin-dir (a .bat on Windows). A checkout keeps working with bin/seat-pace.

Packagist reads release tags: install a tag, or dev-main for the branch. To take a new release, see Updating.

seat-pace

Reports whether a harness's usage allowance is being spent faster or slower than a straight line to its reset. An account can list several machines, so a second one reads when the fleet shows the first absent. See Pacing a usage allowance.

seat-pace pace --used 46 --now 2026-10-21T12:00:00-05:00   # arithmetic only
seat-pace read | pace | log | watch

seat-stage

Stages a machine's seats in a terminal multiplexer (tmux on macOS and Linux, psmux on Windows) and starts each one joined to the fleet. See Restarting a machine's seats.

seat-stage stage office --dry-run     # print each seat's command and first prompt
seat-stage check office               # every reason staging would fail
seat-stage collect office             # record live conversation ids in the seats file

(In a checkout, bin/seat-pace and bin/seat-stage, with --config examples/seats.toml to try the example.)

Contributing

Changing the tools themselves is a contribution upstream: open an issue or a pull request at robot-council/fleet-kit. Your configuration stays in your own repository.

Releasing

A release refreshes the wiki. Before tagging, read the wiki pages against what the release changes and update any that are now wrong; wiki pages publish on push with no pull request, so each push follows the approval practice used for the core and cli wikis. Release notes go on the GitHub Release.

Tests

The suite uses Pest and replays recorded fixtures, so it needs no credential, usage endpoint or multiplexer.

composer install
vendor/bin/pest --ci     # what CI runs; `composer test` runs the same suite without --ci

CI runs it on macOS, Linux and Windows for every pull request and every push to main (.github/workflows/ci.yml). Each platform reports its own check, and ci-passed passes only when all three do.