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.