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_claim on it is refused and told who has it and when the lease ends (Claude Code (lease until 14:05Z)); kanban_ready leaves 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 --resume uses), 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 pane trmnly CLI, for one — pass a stable handle as as (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 gh already has. The token itself is never stored in the project; it is resolved from the vault at request time.
  • Repository or project (GitHub) — owner/repo for a repository's issues, owner/repo#3 for a repository Projects board, @org#3 for an organisation one. Team key (Linear) — the short key as it appears on an issue: the ENG in ENG-123. Project (Kavanah, optional) — a Kavanah project ref (the 3 in ?project=3); empty imports from every project.
  • Server (Kavanah only) — empty means https://kavanah.ai. For a local Kavanah, http://localhost:3000; plain http is 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

  1. In Kavanah, open Settings → API keys and mint a key. It starts with kvn_live_ and acts with your own permissions in that workspace.
  2. Add it to the Keys vault and pick it as the connection's API key.
  3. 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.