All pages

Many agents at once · Lesson 2.3 · 14 min

Run a fleet

Let workers take cards from the board on their own, within a budget.

After this lesson you can judge when a board is ready for a fleet, size a run by workers and budget, choose a land policy you can defend, and read what the run leaves behind.

Time: 14 minutes · Works on: macOS app. Any MCP client connected to TRMNLY on a Mac can start, watch and stop a fleet with the fleet_* tools.

A fleet is the board, plus workers

Everything in this course so far adds up to a fleet. Each worker claims a ready card, works it in its own worktree, has a reviewer check its branch, and lands it under a policy you chose. The board is the only queue. A fleet runs exactly the work you wrote down, in the order your dependencies allow.

The Fleet lesson walks through the strip and a first one-worker run. Do that first. This lesson is about running one well: how many workers, how much money, how much trust, and what the board has to look like before you press Start.

Fleet is experimental. Workers approve their own edits, and the run spends money for as long as it lasts. Start small and watch the first run.

Make the board fleet-ready

A fleet can't ask you anything. Each worker's brief is built from the card's title, notes, checklist and labels, plus its branch and a standing instruction to do that task and nothing else. Its closing summary is written on the card, and it's the first thing you'll read. A board is ready for a fleet when every ready card could be handed to a stranger.

Before a run, go through the ready cards and check each one:

  • It says when it's done. A test to pass or a command to run. A worker told to "improve" something stops wherever it likes.
  • It needs no decision from you. Anything that does becomes a card for you, not the fleet.
  • It's one branch. Small enough that you'll read its pull request the day it opens.
  • It doesn't share files with another ready card. Two workers editing the same module at once will both pass review and then conflict. Add a dependency so one goes first.
  • Its dependencies are on the board. A card whose prerequisite only exists in your head will be taken too early.

Then write the rules that apply to every card. Put them in docs/doctrine/*.md in your repository. TRMNLY adds those files to the context of every agent on the project, workers included. "Run npm test before committing, because CI runs it and a red PR wastes a review" is a doctrine entry. A rule with its reason lets an agent apply it to a case you didn't foresee. Create the folder yourself; TRMNLY won't write into your repository unasked.

Size the run

Workers. More workers only help when there's that much parallel work. If your dependency graph lets two cards run at once, a third worker sits idle. Count the ready cards that don't share files and set workers to that number or fewer. The most is 8.

A sensible ramp:

Run Workers Budget Policy
First 1 A few dollars Open a PR
Once a run has gone cleanly 2–3 Enough for the batch Open a PR
Mature tests, routine cards Up to the parallel width Per batch Consider Merge when green

Budget. The budget is in US dollars and bounds the run. When spending reaches it, workers stop taking cards and the ones in progress finish. That's what you want overnight: no edit is cut off halfway. Estimate from a first run. Divide what one worker spent by the cards it finished, and multiply by the batch.

The fleet also pauses itself when three workers fail in a row. That's usually a missing key or a broken build, not three bad cards, and it stops the run from spending its budget finding that out once per card.

Tokens. The default, CLI harness (subscription), runs workers on an installed Claude Code, Codex or Gemini CLI, billed to your subscription rather than per token. If none is installed, workers fall back to the project's model and API key, and the strip says so before you start.

Choose how much to trust it

The land policy decides who merges.

  • Open a PR (default). Workers push branches and open pull requests. Nothing merges without you. Use this until you've read enough fleet PRs to know what they get wrong.
  • Merge when green. A branch merges once its checks pass. Only as safe as your checks. If your tests don't cover the area the card changes, "green" says little.
  • Merge immediately. Every finished branch merges at once, and breakage becomes a repair card. Fast, and only sane with tests you trust completely.

Leave Review first on. Under the two merging policies, the reviewer is the only thing between a worker's first draft and your base branch. If you turn it off under one of them, the strip warns: "Nothing will look at this code before it merges." The reviewer can't edit, and it fails closed. Output it can't read counts as a rejection. A rejected card goes back on the board with the findings added, so the next attempt starts from them.

The land policy is set only in the strip, per project. An agent can't change it over MCP. That's on purpose: whether an agent may merge to your base branch without a person is your call, not the call of whatever is on the other end of a socket.

Do it in TRMNLY

  1. Audit the board. Open Tasks from More ▾ and click the bolt button in the filter bar. Every card it shows is one a worker may take. Go through them with the checklist above. Archive or rewrite any that fail.
  2. Ask the board to explain itself. In the Agent tab, ask "What's ready, and what's blocked by what?" kanban_ready answers with both. Fix any dependency that's missing.
  3. Add doctrine. Create docs/doctrine/ in the repository and add one short file of standing rules. Commit it, so every worker's checkout has it.
  4. Set up the strip. Click the Fleet strip under the Tasks header. Its settings show only while the fleet is stopped. Set the worker count with the stepper, pick the token source, enter a Budget, leave When done on Open a PR (default), and keep Review first ticked.
  5. Start. Click Start. The board the Tasks tab is showing is the one the run works, and switching boards later doesn't move it. Over MCP, fleet_start does the same and asks for approval, because it spends money continuously.
  6. Watch the right things. The strip shows how many workers are busy, how many cards are done, and what the run has spent. The board shows each claimed card's holder. Worker branches are named fleet/<card-number>-<slug>, so you can tell them apart in git branch and in pull requests. From Claude Code or a script, fleet_status reports the roster, spend, any pause reason, and how much work is ready.
  7. Read pull requests as they open. Don't wait for the run to end. An early PR that misread its card tells you to fix the other cards like it before more workers take them.
  8. Stop when something looks wrong. Click Stop. Every unfinished card goes back to the board, and any review or merge in progress is cancelled. Nothing merges after you stop. fleet_stop never asks for approval, so a Claude Code session can always reach it.
  9. Read what came back. Each finished card carries its history: the branch, the commits, the conversation that produced it, the reviewer's verdict, and what landing did. A card that failed three times in the run has a note saying it was left alone. Rewrite it before the next run.
  10. Feed the next run. Cards can come from anywhere that writes the board: you, the sidebar agent, trmnly task add in a pane, Claude Code over MCP, or wish_submit, which turns a plain request into ordered cards. While a fleet runs, a build or test failure it detects becomes an urgent repair card with no dependencies. Repair attempts are limited; past the limit, the fleet files one card for you and stops retrying that failure.

Check yourself

  • Every card under the bolt filter says when it's done and needs no decision from you.
  • Your worker count is no larger than the number of ready cards that don't share files.
  • You can say what happens when the budget runs out mid-card.
  • You can say which land policy this project uses and what would have to be true to move to Merge when green.
  • After a run, you read one finished card's history and its pull request.

Go further