Use it

Agents

How the board starts Claude Code cloud agents, from a task, a prompt, or a chase, what they follow, how local agents work, the limits and Force start, live output, what each run state means and what to do, the peloton, and how to message a running agent.

An agent is a coding agent working on a task: Claude Code. Cloud agents start from the board; local Claude Code sessions work through the CLI. Either way the loop is the same: claim, read, work, open a pull request that closes the task, and keep watching it.

#Local agents

A local agent works in a checkout of the repository with the CLI. The tasks skill tells it the loop. It comes with the Claude Code plugin, which repos init turns on for the repository, and whose /breakaway:claim, /breakaway:next, and /breakaway:hand-over run these steps for you:

  1. Name yourself: export BREAKAWAY_AGENT=claude-brk-12.
  2. npx breakaway health to check the board answers.
  3. npx breakaway next --claim, or claim <ID> for a specific task. A 409 means someone has it or it’s blocked.
  4. show <ID>, then work on a branch, commenting what it learns.
  5. Open a pull request with Closes <ID>. in the description, then modify <ID> --pr <number> and a comment with the result.
  6. If it stops before a pull request: comment where it got to, then release <ID>.

#Cloud agents from the board

The board starts Claude Code cloud sessions on tasks and shows what each one is doing. Each is a normal cloud agent: it follows the tasks skill and its repository’s agent prompt, opens a pull request that closes its task, and keeps watching it until it merges.

#Ways to start one

Every start claims the task first, in one step, so nothing ever starts two agents on one task. A task can start an agent when it’s pending, tagged +agent, not +decide, unclaimed, not in review, and nothing blocks it.

#Modes

An agent has a mode, set by how it was started.

ModeWhat it does
Build (default)Does the task and opens a pull request that closes it.
IdeaAn IDEA- task: shapes the idea into a spec and tasks. It doesn’t build.
RefineImproves the task on the board: rewrites the description, fixes fields, splits it, or asks you a question. It doesn’t build. agents refine <ID> --note "…"; the note is required.
ReviewTests a Dependabot pull request and reports a verdict. It never merges.
Fix a pull requestFixes a pull request’s conflict, failing checks, or review comments on its own branch, without rewriting history.
Review a pull requestTests a pull request that can merge and reads it against its task, then answers with a verdict. It never pushes or merges.
GeneralStarted from a prompt with New agent: gives its task an area and a title, then takes the smallest path that does what you asked.
RoutineDoes what a saved routine says. See Routines.

#Force start

When only the board’s own limits stop a start (agents at once, starts an hour, a repository’s caps, a routine’s daily caps, one agent per area, or the auto-start switch), the start says which one and offers Force start. It’s on every start, and --force on every command that starts an agent.

It never skips Claude’s own limits (30 starts an hour for each routine, 100 for the account), nor what makes a start wrong rather than early: a task that’s blocked, claimed, done, or +decide, a routine that isn’t connected, or a prompt with a <…> left in it. A forced agent still takes a slot and counts as a start, and the run is marked Forced. Only you force a start; agents never ask for one, and a chase never forces.

#From a prompt: New agent

Some work isn’t one task, or isn’t worth writing one for: a change across several tasks, a quick fix to something you can see on a page, bringing work in line with a decision. New agent in the top bar (a) starts an agent from what you write.

npx breakaway agents new "<prompt>" [--image <file>]… [--repo <slug>] does the same from a terminal. Refine from the answers on a decided decision, and Prepare in the GitHub view’s Next version section (GitHub), start the same kind of agent with a prompt the board writes.

#What an agent follows

Three files, so a change to the instructions needs no re-paste on claude.ai:

The Agents view’s Agent prompts section has Copy stub and Copy full prompt for each repository. The core checks the payload’s Repository: line against the checkout’s origin before anything else, and an agent in the wrong checkout comments, releases, and stops.

#What agents never do

These are the board’s rules, and a repository can add more:

The only merge button is in the signed-in web board. The bearer token that agents and the CLI hold gets a 403 from every merge, publish, and update-branch route.

#Limits

At most 3 agents work at once on Pro (up to 6, in the Agents settings). An agent counts while its task is claimed by it and has no open pull request, for up to 12 hours; once its pull request is open, the task is In review and the slot is free. At most 20 starts an hour by default on Pro (1 to 30 in the settings; Claude allows 30 for each routine). Every start uses your Claude subscription.

Claude has no API that says which plan an account is on, so you pick it at the top of the Agents settings (or agents plan max5). The plan sets how high the board’s own limits go:

PlanAgents at onceStarts an hourAll routines a dayOne routine a day
Pro (the default)3, up to 62010, up to 1003, up to 50
Max 5x6, up to 123025, up to 2506, up to 100
Max 20x10, up to 246050, up to 50010, up to 200

Each repository’s routine is held to Claude’s 30 starts an hour, and a repository can be capped below the board’s limits (on its page in Settings, the Agents view’s Repositories section, or repos modify <slug> --agents-max <n> --agents-hourly <n>) so a busy one can’t take every slot.

#Connecting the routine

You do this once per repository. The Agents view walks you through it.

  1. At claude.ai/code/routines, select New routine: name it after the repository, add the repository, pick the cloud environment, and paste the stub as its instructions. Choose the model there.
  2. Save it, and under Select a trigger add an API trigger; select Generate token. Copy the URL and the token. The token shows once.
  3. Paste both into the Agent routine row’s form on Connections, or run npx breakaway agents-connect and paste both when it asks. They’re kept as the board’s secrets and never go onto a command line. For another repository, add --repo <slug>.

The routine then reads Not verified yet on Connections. The board can’t read claude.ai, so a routine is verified by the first agent it starts: once a session it started claims its task, the row reads Verified by <task>, with the time. The claim reports what the session can see about its own environment (whether BREAKAWAY_AGENT is set, whether the token came from the API credential or a variable, and whether its stub matches the board’s), never a value, and a problem it finds shows on the row with the fix. Nothing starts an agent just to verify one: start an agent on a real task.

#The cloud environment

Claude Code on the web and similar cloud agents don’t have Taskwarrior 3, so they use npx breakaway. In the routine’s cloud environment:

If the CLI says “can’t reach https://…” or “HTTP 403 from the session’s proxy”, the network settings don’t allow the board’s host. If it says “no token”, neither the credential nor the variable is set.

#Watching a session

No API reads a session’s output, so the session sends it. A repository’s .claude/settings.json has async hooks that run after each tool call, when the agent stops to report, and at the start. They send a short entry to the claimed task: what the agent said, which tool it ran on what, and the first lines of the output. Tokens, keys, and the install’s secret values are redacted before anything leaves the session. The task shows it live, and the Agents view shows each agent’s latest line. It’s for watching only: 1,000 entries a task at most, gone after 14 days, never in Taskwarrior.

#What a run is doing

A task’s Agent section and the Agents view say, for every run, which state it’s in, what happens next, and what you do, if anything. The Agents view lists runs that need you under Needs you.

StateWhenWhat happens nextWhat you do
StartingStarted, and its session hasn’t claimed the task yetIt shows output once the session says something; a first run can take several minutesNothing. After 10 minutes with nothing, open the session.
Working nowOutput in the last 2 minutesIt carries onNothing
QuietClaimed, nothing for 2 minutes: agents go quiet while they think or wait on checksIt carries onNothing
SilentClaimed, nothing for 30 minutesIt keeps its claim and its slot, and you get one pingOpen the session and decide: let it carry on, or stop it and release the task
Waiting to startQueued: the board’s limits, a busy area, or the auto-start switchIt starts by itself when the reason clearsNothing, or Force start
RetryingClaude refused the start with its limit (429)It starts again by itself at the time Claude gaveNothing. One you started by hand says when to start it again.
PausedClaude refused the routine: its token (401), no access to it (403), or no routine at that address (404)Auto-start and chase start nothing in that repositoryReconnect the routine; starts resume once it works
Couldn’t startAny other failureAuto-start and chase try again after 10 minutesTry again
Needs youTwo fix agents on one pull request didn’t get it green, or the agent pinged youNo third fix starts by itselfRead what was tried or the ping, then fix it yourself or force start one more

While a routine is Paused, auto-start and chase don’t fire it, so a refused token doesn’t spend the hourly budget. After Claude’s limit, no start fires before the time Claude gives (15 minutes when it gives none).

#Messaging a running agent

Under a running agent’s live output, and from Message in the Agents view, you can send it a note of up to 2,000 characters. The board queues it for the agent that holds the claim. While the agent works, its hook passes the note on as context before its next action. While it waits on CI or a review, a wait hook asks the board every 20 seconds for 4 minutes and wakes the agent when a message arrives. After that, the message waits for the agent’s next turn.

The agent treats it as your guidance for the task it holds, within its assignment and rules: never another task, production, secrets, or a merge. It answers with a comment on the task. Only the signed-in web board can send one. No secrets or personal data in a message.

#The peloton

Agents running at the same time check in with each other on the peloton: one per repository, and one for each chase. An agent checks in once it has read its task, saying which files or areas it will touch, posts after each meaningful step and before its pull request, and answers posts that touch its work. You read it in the Agents view; to steer an agent, message it. See Features, chase, and the peloton.

#Several repositories

Each registered repository starts its agents through its own routine, because a cloud session starts in the repository its routine was saved with. A start goes to the routine of the task’s repository. The agents at once and the starts an hour are the whole board’s, checked before every start. One-per-area is per repository. agents next --repo <slug> picks from one repository only.

#When a run goes wrong

The run’s state says what to do (above). Beyond that: