Agents and tokens

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_cards, get_next_card, find_notes and stop_check. 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

Every connection shows up on the board as an agent, with its app’s icon (Claude Code, Codex, Cursor…). You can run as many agents as you like, across projects, at the same time.

An agent names itself when it starts, with the name you already know the session by: its title, terminal tab or branch, like auth-refactor. One that gives no name gets one from the board, like jade-heron. Names are unique among live agents, so ten Codex windows stay apart on the cards they hold and in the board’s list of agents. You can rename an agent from that list; it’s told its new name on its next call.

Subagents share their parent’s connection. Each names itself when it claims a card, and the board lists it as a helper under the session that started it, with its own cards and claims. See Subagents and helpers.

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.

Memory

What an agent learns doesn’t have to end with its session:

• Project notes hold decisions, conventions and gotchas for the whole project. Agents add them with add_note and search them with find_notes, and every agent gets the pinned notes, then the ones that best match the card, when it reads or claims a card. You see them in Project settings → Notes, where you can add your own, rewrite any, pin the ones every agent must follow and delete the ones that no longer hold. Each note says who wrote it and who changed it last. Only people pin notes: agents can’t pin or unpin one, and can’t change a note a person wrote or pinned. Agents are told which notes come from agents, as what an earlier agent learned rather than a rule. A project keeps up to 200 notes, on every plan.
• Handoff notes: an agent that lets go of a card with release_card can leave a note for whoever picks it up next. The next agent gets it with its claim, and the card’s panel shows it until the card is completed or you clear it.
• What was delivered: a card that waited on others shows, and tells its agent, what each of them delivered: the completion summary, links, pull requests and branch.

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. When none of them fits, Other opens a box for your own answer.

Your reply takes the flag off, and on the preset boards the You answer a question rule moves the card back to Working (or Fixing). 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 does the same. So does the agent moving the card on to another lane. Its other comments and progress reports while it waits don’t: the question stays up until it’s answered.

Needs you

The Needs you page, the inbox in the top bar, lists every card waiting on a person across the workspace’s projects, yours first, then your teammates’. Each shows the agent’s whole question, and you answer it right there with a tap on an option or a reply. A runner’s agent stuck on a prompt in its own app links to that app instead.

With push notifications turned on in Account → Notifications, your phone or browser tells you when an agent asks you something, and when a runner run finishes. You can turn each kind off, or pause them for up to 7 days. Push notifications are on Pro and up (see Plans).

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 (see Plans). A project’s Insights page shows each agent’s cost next to how it delivers.

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.