All pages

Docs · Right-sidebar surfaces

Fleet

Availability: macOS.

A fleet is a pool of agents that work a project's Kanban board on their own. You file the work, say how many workers and how much they may spend, and press Start. Each worker claims a card, does it in its own git worktree, gets its branch reviewed, and lands it under a policy you chose.

A run works one board. A project can hold several; pressing Start binds the board the Tasks tab is showing, fleet_start { board: "Bugs" } binds a named one, and fleet_status reports the bound board with that board's ready count. The binding is held for the whole run — a live fleet does not follow you when you switch boards, because its workers hold claims and worktrees against cards on the board they took them from. One coordinator per project means one run at a time, and its settings (workers, budget, land policy, column names) are per project.

The board is the queue. That is the whole design: work survives closing the window and relaunching the app, anything that can write the board can feed the fleet (including Claude Code over the MCP bridge), and you can see and cancel everything from the Tasks tab.

Making work schedulable

A fleet only picks up cards that are ready — not finished, not claimed, and with every dependency done.

  • Dependencies. Open a card and use Blocked By to say what has to happen first. Agents use kanban_depend. A cycle is refused when you create it, and the error names the cards involved.
  • Ready filter. The ⚡ button in the Tasks filter bar shows only startable cards — the same rule the fleet schedules by, so what you see and what a worker takes can't drift apart.
  • Claims. A claimed card shows who has it, and a claim carries a lease: if a worker crashes or the app quits, the lease lapses and the card returns to the queue by itself. Nothing stays stuck as permanently in-progress. See Kanban → Claims for what a claim means outside a fleet run — who may renew or release one, what ends it, and how to free a card by hand.
  • Awaiting merge. A card whose branch has an open pull request is neither ready nor finished. It isn't offered again — the work exists — and it doesn't release its dependents either, because the code isn't in the base branch yet. Merging the PR and moving the card to a done column releases them; so does deleting the PR link if you closed it without merging.

A card the fleet tries three times in one run without landing is left alone for the rest of that run, with a note saying so on the card.

kanban_ready is the agent-facing version of the same question, and it explains an empty result — "everything is claimed" and "everything is blocked" are different situations.

Running one

The Fleet strip sits under the Tasks header. Expand it to set:

Setting What it does
Workers How many run at once (max 8). Each gets its own worktree.
Tokens Where tokens come from — see below.
Budget USD for this run. Reaching it pauses claiming; in-flight work finishes.
When done Land policy — see below.
Review first Run an agent reviewer over each branch before landing it.

While running, the strip shows each worker, the card it has, and what the run has spent. Stop hands every in-flight card back unfinished rather than leaving the board looking busy.

Where the tokens come from

Workers default to an installed CLI harness (Claude Code, Codex, Gemini CLI), so a long run bills against a subscription rather than per token. The harness still calls back through TRMNLY's MCP bridge, so approvals, the audit log, and the agent lock all still apply.

If no harness is installed, workers fall back to the project's model and the strip says so before you start.

Set more than one API key per provider and TRMNLY will rotate off an account that hits its rate limit instead of stalling. The extra keys go in the Providers sheet's Accounts section — see Agent → Allowance. This applies to fleet work only — your own sidebar conversations never silently change which account they bill.

Land policy

Policy What happens when a card is done
Open a PR (default) Push the branch, open a PR, park the card. You merge.
Merge when green Merge once checks pass, re-checking while the fleet runs.
Merge immediately Merge straight away; breakage becomes a repair card.

The last two let an agent change your base branch with no human in the loop. They are opt-in per project, and a config written before this feature existed reads as Open a PR — upgrading TRMNLY never starts merging your work unasked.

The reviewer sees the branch's diff against its base, computed for it and capped, plus read-only file tools for surrounding code. It cannot edit anything — a reviewer that "just fixed it first" makes its own verdict meaningless.

It fails closed. Unparseable output, a missing verdict, an approval with no reasoning, or a diff that couldn't be read are all rejections. A rejected card goes back on the board with the findings appended to its body, so the next worker starts from them.

Pressing Stop cancels work in flight, including a review or land already underway — nothing merges after you stop.

Repair

With repair on, a build or test failure detected while the fleet is running becomes an urgent card with no dependencies — so it is simply what the next free worker takes. Repair is not a second scheduler: it gets the same claim, lease, review and land path as everything else, and shows up on the board where you can cancel it.

Attempts are bounded. TRMNLY fingerprints the failure with line numbers stripped so a recompile of the same fault isn't counted as a new one, retries up to the configured limit, then files one card for you and stops.

Races — one prompt, several agents

A race hands the same prompt to several agents at once, each in its own git worktree on its own branch, so you can read the attempts side by side. It is for a task with more than one defensible approach, where reading three answers costs less than arguing about which to try first.

Tool What it does
race_start Start a race from a prompt, plus optional workers, base, budget_usd
race_status Each entrant's state, branch, change size, summary, and spend against the ceiling
race_pick Keep one entrant's branch and remove the other worktrees

workers is 2–5 and defaults to 3; a value outside that range is clamped. base defaults to the repository's default branch. budget_usd defaults to the project's fleet budget and is clamped to whatever today's spend cap has left. The reply to race_start states the ceiling and each entrant's share of it, and the race stops itself when spend reaches the ceiling.

race_start asks for approval for the same reason fleet_start does: it is several agent turns running at once, each auto-approving its own writes. So does race_pick, which removes worktrees. race_status is free to call. Omitting race_id means the running race, or the most recent one if none is running.

The prompt has to be self-contained — an entrant starts with no conversation history and nobody to ask.

Picking a winner. race_pick takes the entrant's label as race_status lists it (a, b, …). It keeps that branch, removes the other worktrees, and ends the race. Nothing is merged and no card is touched — what to do with the kept branch stays your decision. A worktree with uncommitted changes is never removed, and the reply names any left in place.

Wishes

wish_submit turns a request in someone's own words into ordered cards. Triage reads the code and the existing board first, and returns nothing — with a reason — if the request is already covered or is really a question.

It only creates cards. Nothing is claimed, edited, or merged as a result, so a misread wish costs one model call and some cards you delete. Useful over Telegram, the iOS remote, or MCP, where the alternative is a sentence that disappears with the conversation.

Doctrine

Standing rules for a project live in docs/doctrine/*.md in the repo itself and are injected into every agent's context on the project.

This is different from Notes: notes are your scratch, stored in TRMNLY's data directory. Doctrine is versioned with the code, reviewed in a diff, and travels to a machine that has never run TRMNLY — which is what a rule needs to be once several agents work the project and none of them shares a conversation with the others.

Create the directory yourself — TRMNLY won't write into your repo unasked — and the next turn picks it up. Keep it short and keep it true: a rule nobody follows teaches agents to skim the file. Entries work best as a decision with its reason attached, because the reason is what lets an agent apply the rule to a case you didn't anticipate.

Driving it from outside

Every part of this is reachable over TRMNLY's MCP server, so Claude Code — or any MCP client — can queue work, take work, and run the pool:

Tool What it does
kanban_ready What can be started now, and why nothing can if nothing can
kanban_depend Record that one card blocks another
kanban_claim Take, renew, or release a card
wish_submit Turn a free-text request into ordered cards
fleet_status Roster, spend, pause reason, and how much work is ready
fleet_start Start the pool (worker count and budget optional)
fleet_stop Stop it; cancels reviews and merges in flight

fleet_start asks for approval — it spends money continuously and runs agents that auto-approve their own writes. fleet_stop never does: stopping is the thing you most want reachable when something is going wrong.

Land policy is deliberately not settable over MCP. Whether an agent may merge to your base branch without a human is a decision for the Settings UI, not for whatever is on the other end of a socket.

What the fleet writes back

Each finished card carries its own history: the branch, the commits, the conversation that produced it, the reviewer's verdict, and what landing did. The board stops being a to-do list and becomes the record of how the work happened.