All pages
Docs · Right-sidebar surfaces
Kanban (the Tasks tab)
Availability: macOS · Linux and Windows (a smaller Tasks page, below) · cloud workspace (its own smaller implementation of the board tools, boards included).
The Tasks tab (right sidebar → More ▾) is a per-project Kanban board. Each project gets its own board — and can hold several named boards; the tab header shows how many cards are open and how many are overdue, and the More menu badges the count ("Tasks — N late") so lateness is visible even when the tab is closed.
The board
New boards start with three columns — To Do, In Progress, Done — and you can reshape them from the column header menu: Add Column…, Rename…, and WIP Limit… (a column over its work-in-progress limit shows it). Drag cards between columns, or use the card menu.
Cards carry more than a title:
- Due dates — overdue cards drive the "N late" badges and can fire reminders.
- Subtasks — check-off items inside a card. The row shows the
count (
2/7); click it, the eye button, or press Space on the selected card to unfold the notes, steps and links in place — steps can be ticked right there. Double-click, Return, or the Edit… menu item opens the full editor. - Labels and priorities — for filtering and triage.
- Archive — done-and-dusted cards leave the board without deleting history.
Every mutation goes through undo/redo (the arrows in the board header), so a mis-drag or accidental delete is one click back.
Several boards per project
One board per project is the default, and most projects never need another. When a project has genuinely separate streams of work — a bug queue beside feature work, one board per release — create a second board instead of splitting the project in two.
The board name sits next to the project name in the Tasks header once there is
more than one; click it to switch. Everything else lives in the board menu
() under Boards:
- New Board… — names a board and switches to it. It starts empty with To Do / In Progress / Done.
- Rename Board… — renames the board you are on, including the project's original one (unnamed, it is labelled by the project).
- Delete Board — deletes the board you are on and every card on it. It asks first, and it is the one board action undo can't reach — the undo history belongs to the board being deleted. The project's main board can't be deleted; Reset Board empties it instead.
Each board is genuinely separate: its own columns, cards, #N numbering,
archive, WIP limits and undo history. A #7 is only unambiguous alongside a
board name. A project holds at most 10 boards.
Fleet works whichever board you started it on: press Start while "Bugs" is on screen and the workers claim from Bugs. A run binds one board and holds it, so switching boards afterwards doesn't move the run — and while one is live on another board, the Tasks tab says so above the fleet section, so a roster showing work you can't see is explained. One fleet per project still, so one run at a time.
One thing deliberately stays on the project's main board: issue tracker imports, which are set up once and re-run later, so they have to land in the same place every time. Closing an issue when its card is done works from any board — the card finishing is what triggers it.
Which board is selected is shared: every window on that project shows it, and
an agent that doesn't name a board works it too (see below). The roll-up
(All Projects…) covers every board of every project and labels each row
project · board.
The cloud workspace has boards too. It runs its own implementation of the
board tools, so the shape differs a little: a box is one workspace rather than
many projects, its main board is called Main, and that name is fixed —
rename a board you made instead. Card ids there are minted from the clock, so
unlike the desktop's per-board #N they don't repeat across boards. Everything
else matches: board on every tool, kanban_boards to list, create, rename,
delete and select, and a board-less call acting on the selected one.
Cards in agent chat
Cards are addressable as #N — "move #12 to Done", "what's left on
#7?" works in the Agent tab. The agent manages the board with these
tools:
| Tool | Use |
|---|---|
kanban_list |
Cards for the bound project, with columns and metadata. include_body: false is the compact overview for a big board: no card bodies, and subtasks and links shrink to counts (notes to has_notes on a cloud box) |
kanban_add |
Create a card (column, due date, labels, subtasks…) |
kanban_update |
Edit a card's fields |
kanban_move |
Move a card between columns |
kanban_remove |
Delete a card |
kanban_columns |
List / reshape columns |
kanban_archive |
Archive a card |
kanban_undo |
Undo the last board mutation |
kanban_boards |
List / create / rename / delete / select the project's boards |
Every one of these takes an optional board — a board name (exact or unique
prefix, case-insensitive) or default for the project's main board. Without
it, a tool acts on the board the user has selected, so "add a task" from
chat lands where the person is looking rather than on a board they can't see.
Each reply names the board it read or wrote, and kanban_list names the
project's other boards, so a transcript is never ambiguous about which board a
#N belongs to.
kanban_boards action:delete needs confirm:true, refuses the main board, and
cannot be undone.
A project_name or project_id that matches no project is refused with the
list of projects, rather than quietly using the bound one. An id passed as the
name (trmnly task --project <id>) works as the id, and so does the project's
own folder (--project "$PWD" from the project's root; a subfolder is still
refused, so a card never lands on a board nobody named). When an MCP client works
in a folder that has no project of its own, it is bound to the home folder's
"Terminal" project, and every reply carries a project_hint saying so, with
the project_create call that gives the folder its own board.
kanban_list all_projects:true returns at most 40 cards across every project;
call it per project for the rest.
The same tools are exported over the MCP bridge, so an
external Claude Code session can file cards into your board — useful
for "log everything you fixed as tasks" workflows. kanban_update also
ticks checklist steps: tick_subtasks / untick_subtasks take step
numbers (1-based) or exact step titles.
From a terminal pane
The trmnly CLI works the live board from any pane,
with no MCP client:
trmnly task add "Fix the login redirect" --column "To Do" --priority high
trmnly task list # cards on the selected board
trmnly task move 12 Done
trmnly task tick 4 2 # tick step 2 of card #4
trmnly task tick 4 1 3 # several steps
trmnly task tick 4 "write the tests" # by the step's exact text
trmnly task untick 4 2
trmnly task boards # the project's boards
Each takes --project P (a name, an id, or the project's folder) and
--board B; without them the pane's project
and the board selected in the Tasks tab are used. Pass a card as its bare
number or quote it ("#4") — the shell reads an unquoted # as the start
of a comment. If a step doesn't match, tick says which one and exits 1
even when the other steps landed, so a script can tell.
Claims
An agent working a card claims it with kanban_claim (take, renew
or release), and kanban_ready lists the cards nothing is holding — the
mechanism Fleet runs on, and usable by hand. What a claim
means in practice:
- A claimed card shows who holds it. A second agent's
kanban_claimon it is refused and told who has it and when the lease ends (Claude Code (lease until 14:05Z));kanban_readyleaves claimed cards out and marks the ones you hold as yours. An agent cannot release a claim someone else holds. - A claim lasts the whole conversation. For a Claude Code or Codex
harness on a Mac, and the cloud Agent tab, every message starts a new
CLI process; the holder is pinned to the conversation (the same key
--resumeuses), so a card claimed in one message is still yours in the next and the agent can renew or release its own claim. Clients that open a connection per call — the panetrmnlyCLI, for one — pass a stable handle asas(up to 64 characters). It is coordination, not authentication: anyone can pass someone else's handle. - A finished card stops counting as claimed. Moving a claimed card into a done column, or archiving it, ends the agent's claim at once (the card's history says so), marking a column as done ends the claims on the cards in it, and an already-finished card cannot be claimed. Undo never undoes a claim an agent took after the edit being undone, and undoing the add of a card an agent is holding keeps the card. Deleting a held card names whose claim it ended. A person's own assignment has no lease and stays.
- A lease lapses when the holder dies, and a person can always free the card: Free on the Linux/Windows Tasks page and the cloud Tasks tab, or from the card on a Mac.
Issue tracker (GitHub, Linear, Kavanah)
A project can pull its issues onto the board from GitHub, Linear or Kavanah. Right-click the project in the rail → Project Settings… → Issue tracker:
- Tracker — GitHub, Linear or Kavanah.
- API key — a name from the Keys vault holding a GitHub or
Linear token, or a Kavanah workspace API key. For GitHub, Use the gh
CLI reuses the login
ghalready has. The token itself is never stored in the project; it is resolved from the vault at request time. - Repository or project (GitHub) —
owner/repofor a repository's issues,owner/repo#3for a repository Projects board,@org#3for an organisation one. Team key (Linear) — the short key as it appears on an issue: theENGinENG-123. Project (Kavanah, optional) — a Kavanah project ref (the3in?project=3); empty imports from every project. - Server (Kavanah only) — empty means
https://kavanah.ai. For a local Kavanah,http://localhost:3000; plainhttpis refused for any host other than this Mac, so the key never crosses the network unencrypted. - Close the issue when its card is done — off by default. With it on, moving an imported card into a done column closes the issue (for Kavanah: sets the task to completed); the Finish done cards button does it for cards already there. This is the only write the tracker connection makes.
- Test connection, Import issues, Disconnect.
Import issues puts the open issues on the board as cards. Each card
keeps a link back to its issue, so importing again updates the cards it
made (renames included) rather than duplicating them, and every imported
card carries a github, linear or kavanah label a board filter can
find. A failed import — no token, revoked token, rate limit, no network —
says which and leaves the board untouched.
Kavanah
- In Kavanah, open Settings → API keys and mint a key. It starts
with
kvn_live_and acts with your own permissions in that workspace. - Add it to the Keys vault and pick it as the connection's API key.
- Test connection answers with your Kavanah name.
What syncs: the tasks assigned to you that aren't completed — status
open, progress or review — up to 500, from every project or the
one named. A card's title is the task id and title (812 Ship the importer). A states filter on the connection narrows by those status
names. tracker_issue_context { identifier: "812" } returns Kavanah's
own markdown rendering of the task under a header naming its URL. A
done card marks its task completed in Kavanah only when Close the
issue when its card is done is on.
If the server answers that it "doesn't support TRMNLY sync yet", it is a Kavanah build from before these endpoints; the key and the network are fine.
An agent working a card can read the whole issue behind it — body,
comments, attachments — with tracker_issue_context { identifier },
which is read-only and needs no approval. With no tracker connected it
says so and points at Project Settings.
On Linux and Windows
The sidebar's Tasks page shows the board that agents on that machine work
through the kanban_* tools — the project's selected board. Creating and
switching boards is macOS-only in the UI; on Linux and Windows it goes through
kanban_boards. It lists each column with its cards, and a card
an agent has claimed says who holds it and when the lease ends
(Claimed by fleet-worker-1, lease until 17:05, in your local time). From the page you can:
- add a card with the New task… field. It goes into the first column.
- move a card on with Move to
. - Free a claimed card so another agent can take it, including one held by an agent that has died. The card's history records who held it.
The page re-reads the board when you open it, and every 5 seconds while it's
showing. It needs trmnly-core-mcp on your PATH, and the Agent page says
whether that's running. Things that behave differently from what you might
expect:
- One change at a time. While a move, free or add is waiting on the core, Move and Free are greyed out, so a double-click sends one request.
- A title you typed stays in the field until the card has been added. If the core refuses it (a board is capped at 500 cards) the text is still there to keep. Titles are capped at 200 characters, the board's own limit.
- A very large board lists its first 100 cards, and the status line says how many more there are.
- If the core stops answering, the page stops asking and says so. If the core exits, the board stays on screen, greyed out, until you restart TRMNLY. Editing a card's details, due dates, subtasks and columns is macOS only for now. Agents can do all of it on any platform through the tools.
Storage
Boards persist to:
~/Library/Application Support/TRMNLY/kanban/kanban.json # macOS
~/.local/state/trmnly/kanban/kanban.json # Linux ($XDG_STATE_HOME)
%LOCALAPPDATA%\TRMNLY\kanban\kanban.json # Windows
One entry per board. A project's main board is keyed by its project id, exactly
as it always has been, and each extra board adds a <project-id>#<board-id>
entry beside it — so an older build reading the same file still finds the board
it knows about. Which board each project has selected is a separate file in the
same directory (selected-boards.json); losing it only means every project
opens on its main board.