Use it

Agents

How the board starts Claude Code cloud agents, what they follow, how local agents work, the limits, live output, 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, which repos init copies into the repository, tells it the loop:

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.

#Five ways to start one

• On a task. Start an agent, with an optional note, in the task’s Agent section.
• The next few. In the Agents view, Start the next N. It shows which tasks it would pick, and why not the others, before anything starts. At most one task per area, none in an area where an agent already works, horizon now first, then by priority.
• By itself when ready. Tick Start by itself when ready on a task (modify <ID> --autostart yes). It starts its own agent the moment nothing blocks it, for example right after the pull request it waits for merges.
• For a Dependabot pull request. Safe to merge? on a Dependabot pull request makes a task from it and starts an agent in review mode. The agent tests the update with the repository’s own checks, reads the release notes, and answers with a verdict as a comment on the task and on the pull request. You still press Merge.
• For a security alert. Fix with an agent on a Dependabot alert makes a task from it and starts an agent. In the Agents settings, you can choose a severity at or above which new alerts do this by themselves. It’s off unless you choose 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.

#What an agent follows

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

• The stub, pasted as the routine’s instructions on claude.ai. It only says to read the repository’s prompt in the checkout.
• The repository’s prompt, at the path its registry entry gives. It sends the agent to the core, then says under fixed headings what each step means in that repository (see the playbook).
• The core, the board’s rules every repository shares: the assignment, the repository check, claim, show, hand-over, the modes, messages, decisions, and pings. It never says how to build.

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:

• Deploy, or touch production: databases, secrets stores, DNS, dashboards.
• Merge, or push to the default branch. Changes reach it through pull requests you merge.
• Start other agents, or set --autostart.
• Share a secret, another repository’s work, or a person’s details.

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:

Each repository’s routine is held to Claude’s 30 starts an hour, and a repository can be capped below the board’s limits (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. Run npx breakaway agents-connect and paste both. They’re stored as the board’s secrets and never go onto a command line. For another repository, add --repo <slug>.

#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:

• Best: an API credential (Pro and Max plans). Add a Bearer credential for the board’s host, with the token as the Authorization header’s value. The proxy adds it to every request after it leaves the session, so the token never enters the session. Leave BREAKAWAY_TOKEN unset.
• Network access. Set it to Custom, add the board’s host under Allowed domains (and api.githubcopilot.com, for the GitHub MCP server), and tick Also include default list of common package managers so installs keep working. With the credential alone, every call from the agents comes back 403.
• Otherwise: an environment variable. BREAKAWAY_TOKEN=<token> plus the same network access. Values there are visible to anyone using the environment.
• Either way, set BREAKAWAY_AGENT=claude-cloud, or pass --as each time.

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.

A task shows Quiet when its session hasn’t sent anything for 2 minutes: it may be waiting on something, or done.

#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.

#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 something’s off

• An agent that stays “Starting” never claimed its task: open its session.
• One that comments “Started in …, but … is …’s” was started by a routine saved with the wrong repository: fix the routine’s repository on claude.ai.
• A task that never shows live output while its agent works means the hook can’t reach the board: look for claim’s warning in the session, and check the environment’s allowed hosts.
• “The routine’s token was refused” means the token was regenerated on claude.ai: run npx breakaway agents-connect again.
• No agent starts in a repository whose prompt still has a <…> placeholder. Fill it in and merge it.