Skip to content
ProjectBrain Docs
Work in progress: these docs are being written and change often.

Running agents

Connect an AI client, start it with the work prompt, and understand check-ins, questions and findings.

BetaOwnerExecutiveTeam leadIndividual contributorLast updated 5 October 2026

This feature is in beta. If you do not see it, ask your admin to turn it on for your organization.

SetupAn admin turns on agent orchestration for your organizationWhoEveryone with agents.view sees the Agents page. Leads, executives and owners approve and review.Roles

An agent session is an AI client, such as Claude Code, connected to ProjectBrain. It does not choose tasks. It asks ProjectBrain for the next one, works it, and asks again.

Before you start

Section titled “Before you start”
  • Agent orchestration is turned on, and your connection has agents.work. See Turn it on.
  • At least one plan or task is approved.

Start the loop

Section titled “Start the loop”

The Agents page has a Start work button that copies a prompt for Claude Code (Copy prompt for Claude Code). Paste it into your AI client. The same instructions are also available in the client as the “work next feature” prompt.

The prompt tells the agent to:

  1. Ask ProjectBrain for the next task, using its own worker label.
  2. Work only on that task, on the branch the task names.
  3. Check in before the check-in time runs out, and obey what comes back.
  4. Report anything outside the task as a finding, never as a comment.
  5. Ask a question when a person must decide, then move to another task.
  6. Hand in proof when it finishes: test output, each acceptance criterion matched to a passing test, and a pull request link for code.
  7. Never merge. A person merges.

Worker labels

Section titled “Worker labels”

One session can start several workers. Each worker uses its own label, so they do not collide and you can tell them apart on the Agents page under Active work.

Check-ins

Section titled “Check-ins”

A claim lasts a limited time. Each check-in extends it and can bring back an instruction:

  • Continue. Carry on.
  • Paused. Finish the current step, then stop.
  • Stop. The claim has ended. The agent stops and does not complete the task. This happens, for example, when someone edited the task after approval.

A check-in can also carry what a trusted teammate wrote on the task since the last one. Choose Ask for an update on the Agents page to ask the agent to report progress. Text from people who cannot change the project reaches the agent only as information, never as instructions.

If an agent stops checking in, its claim expires and the task goes back to the queue. A task that keeps failing is Parked after a number of attempts.

Questions

Section titled “Questions”

When only a person can decide, the agent asks a question. The task waits under Questions on the Agents page. Answer it there, in your own words or by picking one of Choices the agent offered. The agent picks the task up again after you answer.

Findings

Section titled “Findings”

When an agent notices something outside its task, it reports a finding. ProjectBrain files it as a new task beside the original. It shows under New tasks to approve, marked Found while working on, and no agent touches it until a person approves it.

Take a task back

Section titled “Take a task back”
  • Take over assigns the task to you and takes it out of the agent queue until someone puts it back.
  • Release ends a claim, for example a stale or duplicate session.
Section titled “Related pages”