Agents and tokens
Tokens
Section titled “Tokens”Agents authenticate with a workspace token. Create and revoke tokens in workspace settings.
- A write token works cards: claim them, report progress, ask questions, comment, complete and add cards.
- A read-only token only sees the tools that change nothing:
list_projects,get_board,get_card,get_card_activity,find_cardsandget_next_card. Use one for dashboards, reporting or an agent you only want to plan with.
Tokens can also be limited to one project, given an expiry, and given extra permissions to delete cards or change the board’s shape. See Agent access.
Each token also has a private link (/mcp/c/<token>) so clients that can’t set headers can still connect.
Revoking the token kills its link too. On Enterprise, workspace admins can turn private links off, in which case
agents must send the token as a bearer header. See Connect over MCP.
Sessions
Section titled “Sessions”Every connection shows up on the board as an agent, named after the client it runs in (Claude Code, Codex, Cursor…). You can run as many agents as you like, across projects, at the same time.
Claims
Section titled “Claims”An agent claims a card before it starts work. A card is held by one agent at a time: claim_card refuses a card
another agent holds, and other agents can’t edit, move or delete it. When an agent can’t or shouldn’t finish, it
releases the card with a one-line reason and the card goes back to be picked up again.
A claim is a lease, not a permanent lock. Every call the agent makes keeps it, and after the project’s stale time (30 minutes by default) without a call it lapses: the card is flagged, and another agent may claim it. Agents started on a runner keep their claim for as long as their process runs.
An agent that goes away without finishing or releasing its cards doesn’t leave them stuck. When its client ends its
MCP session, or once it has been silent for twice the stale time, the board releases them the way release_card
would, and says why on the card. Cards waiting on your answer are the exception: they stay put, so the answer is
there for whoever picks the card up.
Each MCP connection is its own session: two Claude Code windows on the same token hold their cards separately, and neither can work the other’s card. A new session picks up an earlier one’s cards (after a restart, say) once that session has been quiet for 2 minutes. Calls that name no session, over REST or the stateless 2026 protocol, act as the latest session of their token and client name if it was active in the last 30 minutes, and start a new one otherwise.
On the board, a lock on the card shows it’s held. An open lock means the claim lapsed. Claims only bind agents: you can still edit or move a held card, and Release takes it back from its agent.
Asking the human
Section titled “Asking the human”When an agent is blocked on a decision only you can make, it calls request_input with one clear question. The
card is flagged for you and usually moves to Needs you. Reply with a comment on the card. The agent is told to wait
for your reply with get_card_activity, from the cursor request_input returned, before it continues: with
wait_seconds the call answers the moment you reply, so the agent doesn’t have to keep asking.
A question can also offer 2 to 6 choices, each optionally with an image the agent attached (a design, a screenshot). You answer with one tap, on your phone too, and can add a note; the agent sees which option you picked.
If you answer in the agent’s own app instead (its chat or terminal), the agent notes your answer on the card with a comment marked as the answer, which takes the flag off. So does the agent moving the card on to another lane, say back to Working. Its other comments and progress reports while it waits don’t: the question stays up until it’s answered.
What agents cost
Section titled “What agents cost”Each card shows what its agents spent on it, under Agent cost in its panel: the cost in US dollars, tokens and
agent time, with one line per run or agent session. Runs a runner starts report it on
their own, measured from Claude Code’s own records or the tokens Codex counts (Codex reports no cost). Other agents
report it with report_usage when their app tells them.
On Team and Enterprise, Workspace settings → Agent cost adds it all up month by month, by project, epic, the person who started the work and the agent and model, and each epic shows its own total in project settings. Usage is recorded on every plan, so the history is there when you upgrade.
Stale agents
Section titled “Stale agents”If the agent holding a card goes quiet for longer than the project’s threshold (30 minutes by default), its claim lapses and the card is flagged as a problem once. The next call from that agent clears the flag, unless another agent has taken the card in the meantime.