Lead tasks and workers
In the app, a workspace's lead is its Manager and the tasks it starts are its workers. This page uses the API's names.
The owner can mark a task as a lead when creating it with POST /api/sessions:
{"prompt":"Plan and delegate this work","lead":{"workersAuto":false,"maxWorkers":4,"budgetUsd":5}}
Set "agent":"codex" to run the lead or workspace Manager with Codex. Its ccr-lead tools create and follow workers just as a Claude lead's do. In a room, Codex also receives ccr-room and the same room instructions. A handoff to Codex carries the lead limits, workers and room handle to the new task, and moves the workspace's Manager pointer when the old lead was its Manager. The old lead stops when the new lead is ready.
The owner can later send PATCH /api/sessions/:id with {"lead":{...}}. Only the owner token may set a lead's limits (maxWorkers, budgetUsd) or change an existing task's lead. A paired device may create a lead with the default limits, optionally with workersAuto, so a phone can start a workspace's Manager; that gives the device nothing it couldn't already start as separate tasks. Runner tokens can't set lead at all. Settings on a lead are independent of room auto-pass. maxWorkers defaults to 8 live workers (maximum configurable value 32), budgetUsd defaults to $100 (maximum configurable value $10,000), and each worker accepts at most 10 lead messages per rolling hour. Promoting an idle task restarts its runner so the tools and lead note become available. A task currently working receives them when it next resumes. Changing an existing lead's limits doesn't restart it: they apply the next time it starts a worker.
#Monthly budget
budgetUsd is a monthly budget. It counts the reported cost of the lead and all the workers it started, live or finished, in the current calendar month of the server's local time zone (the service's TZ; Workspace settings shows which). It resets at midnight on the first of each month, with nothing to run: each task keeps its reported cost per month (costByMonth) and the month's spend is their sum. Codex reports no cost, so Codex workers count as $0. Records from before this version had their months rebuilt once from their event logs when the server started, reading each log in chunks without keeping it in memory; spend a log can't place is counted in the month of the task's last update.
Spend is reported at API prices whatever the billing. On a subscription login that is an estimate, not a bill, so reaching the budget is a warning: the Budget reached card appears in Needs you, says so, and the lead keeps starting workers. Setting Hard cap (hardCap: true in lead, owner token only) makes it stop at the budget anyway.
A login counts as a subscription only when the server confirms it. Claude Code reports no API key (apiKeySource: "none") for a claude.ai login, Bedrock, Vertex and a gateway alike, so the server also requires all of these: the task is on the account route (not the CCR gateway), it wasn't continued on Claude API, the environment it gets has no API key, gateway, Bedrock or Vertex setting (including saved model access), and claude auth status with that environment reports a claude.ai first-party login with a subscription type. For a Codex lead, codex login status must report a ChatGPT login. Every Claude worker with spend this month must pass the same test. Anything else, including unknown billing, stops new workers at the budget.
When this month's spend reaches the budget and it stops, task_create is refused with the spend and the reset date, and the lead gets a Budget reached card in Needs you (budgetHold on the task) with the spend so far and Raise to $X (double the budget, or enough to cover 1.5 times this month's spend, at most $10,000; it never lowers a budget raised since, and at $10,000 the card says the budget is at its maximum instead). Running workers carry on. Raising the budget is the owner token's alone: a paired device sees the card with Raise greyed out, and PATCH from it gets 403. The card goes when the owner raises the budget above this month's spend, or when the month ends.
Workspace settings has a Manager limits section for the workspace's Manager: this month's and lifetime spend, Workers running against the cap, Codex workers, the billing and whether the budget warns or stops, the reset date, and the budget, Workers at once, Workers may use Auto and Hard cap. Turning Hard cap off asks first, like raising a limit. Start your Manager shows the limits the Manager will start with. Raising a limit there asks first. A paired device sees the values only.
In a room, messages between a lead and a worker it created pass automatically in either direction, even when room auto-pass is off. This uses a room turn, wakes the recipient, and appears in the room log as passed by lead-pair. Workers messaging each other and unrelated tasks messaging the lead still wait for the owner unless room auto-pass is on. A lead's posts to the owner are updates, under Updates in Needs you, and don't notify; when it needs the owner to choose, it asks a decision with ask_owner. Room budgets, deadlines, pause and turn limits apply to these passes.
The lead gets ccr-lead MCP tools. task_create accepts a brief, optional title, agent, projectId, permissionMode, and files (see File overlaps). Without agent, a worker uses the lead's own agent if this computer has it, otherwise the one it has; the tool's description lists the agents on this computer. A worker inherits the lead's workspace and room, and by default its project or repository. It is recorded with createdBy set to the lead task id. Workers do not become leads. Worker permission mode cannot be wider than the lead's mode. The owner can allow worker Auto explicitly with workersAuto: true; that does not allow bypassPermissions.
| Tool | Result |
|---|---|
task_create | Start a worker and return its compact status, with a warning when its files overlap another open worker's. reviews (a PR URL) makes it that PR's reviewer: only then can it record a verdict. |
task_message | Queue a message to one of this lead's workers, marked as from the lead. |
task_status | State, counts and titles of open approvals and questions, last assistant text (up to 500 characters), branch, known PR URL, usage, changedFiles and overlaps for any task in the lead's workspace. |
task_wait | Wait on any workspace task's events for idle after its queued turn, waiting for the owner, failed, exited, or a new PR; timeoutMs is capped at 60,000. Returns the same compact status. |
task_list | List mine (default), room, or workspace tasks, each with its changedFiles (up to 20) and overlaps. |
task_stop | Stop one of this lead's workers, keeping its workspace. |
task_retire | Free the disk of one of this lead's workers that is stopped or exited. Its unpushed and uncommitted work is backed up first; its record, log and deliverables stay. See Retire and delete. |
review_pr | Start a fresh read-only reviewer for an open PR, on the agent opposite to the author's: repo (OWNER/NAME), number, optional focus. It ends in a PASS or FAIL verdict on the PR's head. See Local PR review. |
task_review_done | Record an independent review's outcome for a PR at its current head; releases a risky PR held for review once the reviewer said PASS. |
task_status and task_wait give a lead read access to every task in its workspace, including tasks it did not create. In the Default workspace, that means every task on the server. They can see the task's last assistant text, owner-request titles, PR and usage. Only workers that lead created can receive task_message, task_stop or task_retire, and task_retire refuses a worker that is still running or has a durable job running. The lead note asks leads to retire workers they stopped or replaced; the server also retires quiet workers whose work is pushed or whose PR is merged or closed.
Lead actions appear as plain events in the lead's task view and as notices in its room. The MCP server reaches the control plane through the runner's local socket and authenticated WebSocket. The task never receives the owner token. Non-lead tasks do not have the ccr-lead MCP server. The control plane also checks the owner's grant on every tool call.
The tools cannot answer approvals or questions, merge, manage credentials, delete tasks or data, or increase their own limits. Those actions remain with the owner. Retiring deletes nothing that can't be made again. A lead may inspect tasks in its room or workspace, but may message, stop and retire only workers it created.
#Running several workers
Parallel work is only faster when the pieces don't touch each other. Conflicting branches cost a merge and a full test run every time something else lands, so a one-hour change can take three. The lead follows these rules:
- Plan by features, schedule by files. Plan the work as features, as usual. Before running them in parallel, note which files each will change. Features that overlap run one after another, or go to one worker; features in separate parts of the code run in parallel. Keeping the code modular means more features land in separate files.
- One owner per area. Each part of the code base (for example the sidebar, the runner, the relay) has one worker at a time. Follow-ups in that area go to the same worker.
- At most two open PRs per area, and no stacks. Merge before starting the next change in the same place. Split large work into small PRs that each merge on their own, not into a chain of PRs on top of each other.
- Test capacity is shared. Workers run the tests for what they touched; the full suite runs once, when the PR is about to merge. Long commands run as jobs or in the foreground with a timeout, never as a background command the agent then waits on.
- Review before the final full run. Review the change first and send all findings in one message. Risky PRs get an independent review the server enforces: see Risky PRs.
- Remove conflict magnets early. Generated files committed to the repository, versions bumped by hand in every change, and single large files that every feature edits make every pair of branches conflict. Fix those first.
#File overlaps
The control plane keeps rule 1 checkable. For every open worker it tracks the files its branch changes:
- Worktree: at the end of each turn that changed something, the runner diffs the worktree (commits, staged and unstaged edits, new files) against the commit the task started from. This works for host and container tasks alike.
- PR: when PR watch sees a new head commit on a tracked PR, it reads the PR's file list through
gh api(renames count under both names). A failed read keeps the last list.
A task's changed files are both lists together, for its open PRs only. Open work is any task other than a lead, reviewer or chat that isn't retired and is either live or has an open PR; a task whose PRs all merged or closed no longer counts.
task_status and task_list return changedFiles (up to 50 and 20, changedFilesTotal when there are more), any declaredFiles, and overlaps: other open work in the same project (or, without a project, the same repository) whose changed or declared files include the same files, each as {taskId, title, files}.
task_create takes optional files, the repository-relative paths or globs the worker is expected to change (src/server/public/board.js, src/server/*.ts, docs/; * stays inside one directory, ** crosses directories, a trailing / means everything under it; at most 100). They are stored on the worker as declaredFiles. If they overlap an open worker's changed or declared files, the result carries a warning naming each worker and the files, and the lead's log records it. It is a warning, not a refusal: the worker starts either way, so the lead can run the work in order or hand it to one worker.
The board shows a small amber "Overlaps …" line on each affected worker's card.
#Reviewer verdict on every Worker PR
On a server that can run a reviewer (host mode, with Claude Code or Codex installed), every Worker's PR waits for an independent reviewer's PASS on its current head commit before the lead hears it is ready:
| Card | When | What releases it |
|---|---|---|
| Needs reviewer verdict | no review_pr verdict yet | a PASS on this head |
| Verdict stale · new commits | the verdict is for an older head | a PASS on the new head |
| Reviewer FAIL | the reviewer found a P0 or P1 on this head (or said FAIL) | a PASS on a new head, or the owner |
A FAIL can't be released by any agent: not by the lead's task_review_done, and not by asking the worker. The worker fixes the findings and pushes, and a new review runs. The owner can still let the current commits through with Skip review, and decides on merging, as always. Once the head has a PASS, a PR that touches no risky path is released; a risky one still needs the recorded review below. On servers that can't run reviewers (Docker mode), only risky paths are held, as before, so nothing waits on a review that can't run. A FAIL that did run still holds the PR there.
The verdict shows on the task's PR card ("Reviewer PASS · 1 P3 · abc1234 · Codex (other agent)"), on the ready-to-merge card in Needs you, on the board and in the review queue, and in the lead's ready and held messages. It's always tied to one head commit; after a push it reads "Reviewer verdict is for abc1234; new commits since".
#Risky PRs
Some changes cost much more when they're wrong than others. A PR is risky when its diff touches the repository's risky paths. When a worker reports such a PR ready, the control plane holds it as "needs independent review": the lead gets a held message naming the risky areas and files instead of a plain Ready, the board's card says Risky · review needed, and the review queue marks it. It stays held, after the reviewer verdict above, until both:
- an independent review has run on the PR's current head commit: a local
review_prthat posted its comment, or a reviewer task the lead started (passed asreviewer); and - the lead has recorded the outcome with
task_review_done.
| Argument | |
|---|---|
pr | The PR's URL, or #number when only one PR in the workspace has it. |
verdict | approve (no blocking findings left) or fix (fixes needed first; the PR stays held as Reviewed · fixes requested). |
rechecked | true once the lead has rechecked fixes pushed after the review. |
reviewer | The reviewer task's id, for a review that wasn't review_pr. It can't be the author or the lead. |
note | Optional, up to 500 characters. |
When new commits arrive after a review, the PR is held again as Reviewed · recheck needed, and recording the new head needs rechecked: true. Each record applies to the head commit it was made on. A PR that touches no risky path needs only the reviewer verdict, where one is required.
The owner or a paired device can waive a held review with Skip review and a reason of 10–500 characters. The server checks the live PR head, records the authenticated actor, reason, full head SHA and time in the task and activity audit, then marks uubright/review successful on that exact head with a Review waived description. A later push is pending again. Agents cannot waive a review. The waiver response follows the durable audit write; only that PR's card and commit status are reconciled asynchronously, and a failed status write is shown on the card and retried.
#Risky paths: .uubright/review.json
The patterns are read from the repository's .uubright/review.json on the PR's base branch, never from the PR itself, so a PR can't make itself safe. A PR that edits .uubright/review.json is always risky. The file is optional:
{
"defaults": false,
"risky": {
"Auth and permissions": ["src/server/devices.ts", "src/drivers/**"],
"Relay crypto": ["src/relay/**", "src/server/public/relay/e2ee.js"]
}
}
riskymaps an area name (shown to the lead and on the board) to paths and globs, as fortask_createfiles:*stays inside one directory,**crosses directories, a trailing/means everything under it.defaults(defaulttrue) keeps the built-in areas below; an area with the same name as a built-in one replaces it.falseuses only the file's areas.$commentis ignored.autoReviewis optional and off by default. See Automatic PR review.
Without the file, or with an invalid one (the lead's message says why), these built-in areas apply: auth and permissions (**/*auth*, **/*permission*, **/*login*, **/*token*, **/*credential*, **/*sandbox*), secrets (**/*secret*, **/.env*, **/*keychain*, **/*vault*), deletion and retire (**/*delete*, **/*retire*, **/*cleanup*, **/*purge*, **/migrations/**), crypto (**/*crypto*, **/*encrypt*, **/*e2ee*, **/*cipher*), and automatic model turns and retries (**/*retry*, **/*retries*, **/*cron*, **/*schedule*, **/*webhook*). The ccr-cloud repository has its own file listing its device and owner-token code, plugin secret stores, retire and cleanup, relay crypto, and the stall check, recovery, PR routing, rooms and messaging that start model turns by themselves.
The PR's files are read through gh api whenever PR watch sees a new head (see File overlaps), and its risk is worked out at the same time.
#Manager playbook
Practices that made a long run of parallel work go well, and the mistakes behind them. They apply to any Manager, whatever the project.
Briefing workers
- Start workers in Auto mode unless the owner says otherwise. A worker that stops to ask for every command is slower than one you review afterwards.
- Give each worker a complete brief: the goal, decisions already made (and by whom), files other workers are changing right now, the final check to run, and how to report. A clear task needs no plan round trip; a fuzzy one does.
- Codex workers open PRs and post comments with the
ghCLI, not the GitHub connector: connector calls wait for a manual approval even in Auto mode. - Reuse a worker that just finished in the same area for the next change there; it already knows the code.
Reviewing
- Changes that touch secrets, credentials, deletion of user data, auth, encryption, or anything that runs automatically and costs money (nudges, retries) are risky PRs: the server holds their Ready until a separate reviewer has run on the current head and you record the outcome with
task_review_done. Give the reviewer an attack list, not your conclusion: "can the agent read the secret", "can retire lose a stash", "can a nudge repeat forever". - Ask the reviewer to reproduce each finding, and when the worker says it is fixed, send the same reviewer back to rerun its reproductions against the fix. Fixes for a security finding often open a second path; one recheck round is cheap (the hold returns on every new head and needs
rechecked: true). - Check facts at the source, not from summaries: a review summary can be stale, a remote-tracking ref can point at a deleted branch, a worker's "Ready" may predate its last push.
- Check licenses before borrowing code or skills. A bundled library can carry a copyleft dependency (and code you can read is not always code you may ship).
Bugs the owner reports
- Reproduce first, with a failing test, then fix; post the root cause in one or two plain sentences. Several of the worst bugs looked like one thing and were another (a crash that showed as a page-load error, a test-browser quirk that looked like a Safari freeze).
- Give the owner a workaround right away if one exists, then the fix.
Merging and deploying
- One heavy test run at a time on a shared host. Under load, timing-sensitive tests fail and hide real results; rerun a failure alone before believing it, and record genuinely flaky tests.
- Don't rerun a full check just because the base moved; the merge itself reruns it. Do rerun after changing code.
- Run the owner journeys (or the project's end-to-end check) before deploying a batch, on a quiet host.
- Production deploys of services the owner runs, and merges in repositories the owner merges, stay with the owner: give the exact command and check the result afterwards.
Talking to the owner
- Lead with the result. Link every PR, issue and file you mention.
- Ask decisions with
ask_owner: one short question, each choice with a label and a one-line description, your recommendation marked. Don't ask what you can check yourself. - Say plainly when a merge went in with a caveat (a flaky test rerun, a skipped check) and why.
- Destructive actions stay with the owner; anything automatic that frees space must back up first and never touch work it can't restore.
#Worker states and stalls
A worker can end a turn saying it will check on something later with nothing set to wake it, and then sit idle unnoticed. To prevent that, every worker reports where it stands with the ccr-task tool report_state, and its note tells it to call the tool at the end of every turn:
| State | Arguments | Meaning |
|---|---|---|
done | Finished; nothing more to do. | |
ready | pr: a PR URL, or the number of a PR the task opened | Ready for review. |
waiting_on | on: lead, owner, job:<id>, review:<pr> or external:<what>; optional until, an ISO time | Waiting, and on what. |
blocked | reason | Can't go on without help. |
Every state takes an optional one-line note for the lead. Workers are tasks with createdBy (started by a lead's task_create) or parentTaskId (started through the API by another task, such as a Manager), and members of a room that has a lead, when they are created. Only workers get the tool; an API worker with parentTaskId has it even outside a room, so it can reach its lead.
The state is stored on the task (workerState), shown beside the task's status in its header, and logged in its feed. A state is current until the worker's next turn starts; a turn that ends without a new report leaves no current state.
Once a minute the control plane checks idle workers:
- No current state and no running job for over 5 minutes: the worker is marked stalled and gets an automatic message: "Say what you're waiting on with report_state, or start a job that wakes you". It is nudged once per reason (no state, a state from before its latest turn, a job that stopped, a wait past its until): a new report clears the flag, but a later stall for the same reason is only flagged, so a worker can't answer every nudge with the same non-answer. Tasks the owner started (a room member with no parent task) are flagged but never nudged or woken.
- **
waiting_onleadfor over 10 minutes:** the lead gets one message naming the worker and its note, and is listed on the Stalled row. - **
waiting_onjob:<id>:** fine while the job runs; its end wakes the worker. A report naming a job that isn't running is refused, with the reason, so the worker reports what it is actually waiting on. - **
waiting_onwithuntil:** the time must be at least 5 minutes ahead. Once it passes (other than for lead or owner), the worker is woken once per until value to recheck. - **
ready: for a risky PR still held, the lead gets one held message per head and hold instead. Otherwise the lead gets one message per PR, however often it is reported, and the PR shows in the board's Review queue until it merges or closes, the worker reports something else, or the owner or a lead stops or retires the worker. The server tracks a reported PR on GitHub, whatever its repository, so the queue follows its real state. Comments already on it aren't news, and a PR closed and reopened comes back. An idle worker retired automatically, or one whose sandbox stopped, keeps its open PR in the queue. If GitHub doesn't answer, the item stays and says PR state unknown**. - **
waiting_on owner: becomes a decision card in Needs you**, so it never sits only in chat. Put the question innoteand the choices inoptions. An openask_ownercard from the same worker is enough on its own. - **
blocked:** the lead gets one message per reason.
Each automatic nudge or wake is a model turn, so a worker gets at most 3 an hour and 10 in its lifetime. After that it is only flagged on the Stalled row ("no automatic nudges left") for the lead or the owner to look at.
A worker waiting on the owner (waiting_on owner, or an open decision, approval or form), with a running job, a recovery card, or a message about to start is covered and never flagged. The board's Stalled row lists each workspace's uncovered idle workers with the reason, the tasks whose running turn stalled (they keep their recovery card in Needs you), and leads a worker has waited on for too long.
#The review loop
The server keeps every open PR moving, so nobody has to watch GitHub. Once a minute it works out what each PR needs at its current head and sends only what hasn't gone yet. Its record, review-loop.json in the data folder, survives a restart.
| The PR | What happens |
|---|---|
| PASS on its head | The Manager is woken once. A non-risky PR under merge: manager stays on the Manager page; the Manager uses the gated merge script and posts the result in Updates. If merging is the owner's, a Ready to merge card goes to Needs you only when GitHub would merge it, with reminders after 4 and 8 hours. Until then the board says what blocks it and who acts next. |
| FAIL on its head | The Manager is woken once, and the blocked board card names the author as the next actor. A local reviewer or designated Worker reviewer queues one sanitized exact-head repair brief to the author, including under Ask routing. The Manager can inspect queued, delivered, and new-head handoff status without reviewer text. |
| New commits after a FAIL | Once the head has rested 3 minutes (20 if its author is still working), the Worker named to review the PR gets the new head and its findings if it's alive and hasn't pushed; otherwise review_pr runs for the Manager. The Manager is told. A fork PR, whoever opened it, or one no task tracks by an author without write access, is never rechecked by itself: the Manager is woken once per FAIL to decide. |
| No verdict on the head for 60 minutes | An idle reviewer is nudged once, then the Manager is woken 60 minutes later. With no reviewer alive, the Manager is woken at once. A running reviewer or author is left alone. |
| New PR no task tracks | It shows on the board, and the Manager is woken to assign a review. PRs already open at a repository's first scan show, but don't wake anyone. |
A verdict is a record on the server, never what a PR comment says, because every task posts to GitHub as one login and a comment can be edited. It is one of:
- a
review_prreviewer's verdict; ccr-task report_reviewfrom a Worker started withtask_create reviews: <PR URL>. Only that Worker can record on that PR, at the head GitHub says is current, with the full SHA, once per head. A task that pushed anything can't. It moves the loop, but doesn't release the verdict hold, which needsreview_pror the owner. A FAIL queues a server-written repair brief with severity counts and the validated review-comment link. The Manager can inspect its safe handoff state withtask_status; a capped brief retries after a restart, and a new head retires the old brief;- the Manager's
task_review_donenaming areviewer.
People with their own GitHub login count only if the owner lists them in the workspace's trustedReviewers (PATCH /api/workspaces/<id>, owner token). A listed login's comment counts if its first line has PASS or FAIL with the head's full 40-character SHA beside it. An edited PASS doesn't count, a login the agents use or the PR's author can't be listed into counting, and a comment's PASS never outranks a record on its head.
A FAIL on the head pulls a PASS, whichever came first: it only ever stops a merge. A held PR's card says why and has no Merge button. So does a PR whose files weren't all read at this head, or whose review.json couldn't be read.
Watched repositories are the workspace's projects, plus repositories where a tracked PR lives and this login can push. Open PRs are listed every 3 minutes with ETags.
Cost: each wake is a model turn, so a Manager gets at most one message a tick and 6 an hour, one PR at most 3 of those, and a PR gets at most 5 automatic rechecks, at most 4 an hour per workspace. An untrusted PR wakes the Manager once as new and once as stale until it gets a verdict, however often its author pushes, and new untrusted PRs are held to 3 an hour per workspace. Quiet hours hold wakes, rechecks and nudges until morning. Anything held goes out later, together; the board card says why it waits. PR titles, comment text and fork file names never reach the Manager; it gets risky areas, the owner's card gets the paths.
Who merges: the owner, by default. This repository sets "merge": "manager" in .uubright/review.json on the base branch. It leaves tracked PRs whose risk was read at this head and is empty to the Manager, so no owner card appears for them. The Manager uses scripts/merge-pr.sh after the exact head passes review. The policy changes who is told; it grants no permission. Risky paths, held PRs and PRs no task tracks remain the owner's. Only a ready owner decision appears in Needs you; drafts, failed or pending checks, unresolved threads and conflicts stay blocked on the board with the reason and next actor. A PR no task tracks gets the same Merge bar as a tracked one, read again at the tap.
Everything the loop does is on the PR's board card and in the activity log.
#PR review routing
The control plane polls every PR tracked by a task through gh api, using the task's workspace GitHub login or token. It needs no inbound webhook. A runner PR action is tracked automatically. When an agent opens one with gh pr create, the server also detects the URL in that command's output; an assistant's statement that it opened a PR can identify one too. Before adoption, the server checks that the open PR is in the task repository and uses its work branch or a branch the task pushed. For an assistant statement, it also checks the PR author against the workspace GitHub login and the PR creation time for other branches. Merely mentioning or reviewing a PR does not attach it. A lead's own PR routes to the lead. The owner can use Track PR… on any task to attach a PR, or stop tracking one. Several PRs can be tracked independently on one task. Review comments, reviews, issue comments, and failed checks become a Needs-you item on the author task by default. Open that task and select Send to queue a message containing the feedback links and shortened bodies. The message asks the author to address the feedback, reply on each comment, push, and leave merging to the owner.
Set prRouting to auto on a task or its lead to send new feedback directly to the author. The task's setting takes precedence. A room can also set prRouting; a lead setting takes precedence over the room. Automatic routing shares the lead's 10 messages per worker per hour cap. Feedback that hits the cap remains on the task for the owner to send. Same-login comments posted during the author task's turn are treated as its own replies; comments posted while it was idle still route, including owner and lead comments from the same GitHub account. After a reviewed PR receives an author push, its lead gets a re-review message.
The task card shows check results, merged or closed status, and when checks are green, the PR is mergeable, and review threads are resolved, Ready to merge. Merging from the app is always the owner's; no agent receives a merge request, and a repository's "merge": "manager" only changes who is told (see the review loop).
#Local PR review
The console writes the classic GitHub commit status uubright/review on each exact PR head. A newly discovered head and a review in progress are pending; an independent PASS is success and FAIL is failure. Pushing another commit starts a new pending status, so an old PASS cannot turn the new head green. The status description is short and its link opens the task. For an outside PR, it opens the Manager task when one is available. The PR comment and local review record remain the source of the verdict.
The workspace GitHub credential needs Commit statuses: Read and write on each repository (a classic personal access token needs the repo scope). A missing permission makes review_pr return a specific setup error before it starts a reviewer. The PR card also shows a status posting error until the credential is fixed and the next poll retries. Set CCR_CLOUD_PUBLIC_URL to the console's reachable address so GitHub's status link opens the task from other devices.
review_pr (or POST /api/reviews with the owner token, for the owner's own assistant) reviews a PR on this host instead of waiting for GitHub's Codex review. Leads are told to use it, and on repositories that rely on it, such as the ccr-cloud repos, not to wait for GitHub's Codex review. The PR is untrusted input throughout.
#Automatic PR review
An owner can opt a watched repository in by committing this setting to its default branch:
{
"autoReview": {
"enabled": true,
"maxConcurrent": 2,
"skipDrafts": true
}
}
The default is enabled: false, maxConcurrent: 2, skipDrafts: true. maxConcurrent accepts 1–16. The console reads this setting from the repository default branch, regardless of the PR's target branch or head, and caches successful reads for 30 seconds. A PR author cannot opt in by targeting an unprotected branch with their own setting. A failed refresh pauses automatic scheduling until the next successful read, including manual fallback wakes and rechecks, so the PR cannot opt itself in or weaken its own gate. No team repository is opted in by this release. The repository also needs a local checkout and the GitHub permissions described above.
When enabled, the review loop starts an independent review_pr on each new or updated head after it rests for 3 minutes (up to 20 while its author works). It includes drafts only when skipDrafts is false. The loop holds at most maxConcurrent active reviewers per repository across workspaces; an old-head review must finish before the new head of that PR starts. A durable reservation and reviewer record prevent another paid review of the same head after a restart. To bound a busy repository, each tick examines at most 16 eligible PRs, reads at most 16 base policies, and attempts at most four review launches, rotating through the rest on later ticks. A durable per-repository budget starts at most 12 paid automatic reviews per rolling hour; queued PRs resume as the window clears. Host reviewer capacity and quiet hours still apply. The first scan does not buy reviews of heads already open before the loop starts; later pushes are eligible. Owner stops and ignored PRs are never launched automatically. Manual recheck limits govern the Manager-driven path; automatic review uses the repository hourly budget so a new head after a FAIL is not stranded at a manual cap. A preexisting failed head is not bought again on the loop's first run. A temporary review-launch failure leaves the head waiting and retries with a bound; repeated failure or a reviewer that finishes without a verdict wakes the Manager once with the reason and the manual review_pr action. A base config read failure pauses automatic scheduling and rechecks until the next read succeeds; explicit manual review_pr remains available. The exact-head commit status remains pending until a PASS, FAIL or human waiver is recorded.
The board keeps a waiting or started review label across ticks. A repository concurrency cap or the hourly automatic budget also shows a waiting reason and wakes the Manager once; scheduling resumes when that limit clears. A review marker without a local reviewer or verdict record wakes the Manager to inspect the record, without starting another paid review. Slow automatic launches do not delay verdict wakes or an owner's waiver; a slow default-branch policy read also does not delay waiver status reconciliation. For draft reviews enabled by skipDrafts: false, verdicts reach the Manager while the PR is still a draft.
#Review flow
- The repository must belong to a project in the task's workspace, as a local checkout on this server whose configured
originis that repository. - The control plane reads the PR through
gh apiwith the workspace's GitHub login. If that login already posted a review comment for the head commit, it returns the comment's URL instead of starting another review. Marker comments from anyone else don't count. A review already running for that commit is not started twice. - The server fetches the PR head and its base into that checkout with its own Git login, so the reviewer needs no credentials. It then starts a fresh reviewer task in the project, on the agent opposite to the author's: a Codex reviewer for a Claude Code PR, a Claude Code reviewer for a Codex PR (for a PR no task tracks, Codex). When that agent can't run here (Codex not installed or its sandbox not confirmed; Claude Code not installed), the reviewer is a fresh read-only session of the author's own agent, and the PR comment, the
review_prresult (independence: "same-agent",note) and the verdict say so and why. The reviewer is never the task that wrote the PR, nor the lead that asked. Its checkout is its own clone of the local checkout (not a shared worktree, so the owner's.git/configstays out of reach), at the PR head merged with its base branch, with git hooks off. When the two conflict, it reviews the head alone and logs a warning. The project's setup script and setup variables never run for a reviewer, since they would run the PR's code outside the sandbox. A Codex reviewer runs Codex's built-in review (
review/start) in Codex's read-only sandbox. It can read the code and run commands that only read, such as the typecheck or tests whenfocusasks for them. Any request for more access, file change, MCP tool call or question is declined without asking anyone. The reviewer gets:- its own Codex home holding only a link to the Codex login and a permission profile that lets commands read only its checkout, the Node and npm it runs by exact path, and the system's minimum, so not the host's files or credentials. None of the owner's
config.toml, MCP servers, hooks or trusted projects apply, and git ignores the host's global and system Git settings; - no uuBright Console tools (artifacts, rooms, leads);
- no Git, GitHub or gateway credentials in its runner or agent environment, an empty
ghconfig soghcan't fall back to the host login, and apushurlthat goes nowhere.
The read boundary is that profile, and it fails closed. Before starting a reviewer, the server checks that this host's Codex reports the profile as in force; the reviewer checks again when it starts. Where Codex can't enforce it (for example, a host without
bwrap, or with unprivileged user namespaces restricted on Linux; a Codex that doesn't confirm its Seatbelt profile on a Mac), Codex doesn't review, and a Claude Code reviewer does instead. No reviewer runs unconfined.A Claude Code reviewer can read the checkout and nothing else, and can't change anything. The boundary is Claude Code's own, checked on Claude Code 2.1.312, and needs no OS sandbox, so it works the same on Linux and macOS. It is started as
claude --restricted --safe-mode --strict-mcp-config --tools Read,Grep,Glob:--tools Read,Grep,Glob: those are its only tools. Write, Edit, Bash and WebFetch don't exist in the session, so it can't change files, run commands, push or reach the network. It reviews by reading, so it can't run the typecheck or tests: ask for a Codex reviewer when that matters.--restricted: the file tools are confined to the checkout, with symlinks resolved (a link pointing out of the checkout is refused), and user, project and local settings files are ignored, so a PR's.claude/settings.jsonhooks never run.--safe-mode: no CLAUDE.md, skills, plugins or hooks.--strict-mcp-configwith no MCP config: no MCP servers and no uuBright Console tools.
The runner denies every permission request without asking anyone. It stops the reviewer if Claude Code's start-up message lists any other tool or an MCP server, and the server checks the same message again before posting. A Claude Code too old for these flags fails to start, so the review fails instead of running. Like a Codex reviewer, it has no Git, GitHub or gateway credentials, an empty
ghconfig, git without the host's settings or hooks, and apushurlthat goes nowhere. Its model access is the CCR client key, a Bedrock profile or this server's own Claude Code setup, never a raw saved key. A Claude reviewer must end its answer withVERDICT: PASSorVERDICT: FAIL. Without that line it posts nothing.When neither can run,
review_prrefuses (409) with what this host lacks. On Linux: "No reviewer can run on this server: Codex needs an enforced sandbox (bubblewrap installed and unprivileged user namespaces allowed), and Claude Code isn't installed. Install Claude Code for a read-only Claude reviewer that needs no sandbox." On a Mac it names macOS Seatbelt and Codex 0.163 instead of bubblewrap. A server in Docker mode always refuses: reviewers need host mode.The reviewer's own text never leaves the server before that check: chat channels and Web Push don't send a reviewer's turn results, and lead tools see only its status.
- its own Codex home holding only a link to the Codex login and a permission profile that lets commands read only its checkout, the Node and npm it runs by exact path, and the system's minimum, so not the host's files or credentials. None of the owner's
- The review instructions include the PR title, description and earlier review comments, marked as untrusted, so findings already answered aren't repeated.
- When the reviewer's turn completes, the control plane decides the verdict: PASS when there is no P0 or P1 finding, FAIL otherwise (or when a Claude reviewer's own verdict line says FAIL). It posts the verdict, the reviewer and its findings (P0–P3, file:line, scenario) as one PR comment headed "Independent review: PASS · round N" and starting with
<!-- ccr-review sha=<head> -->, with@mentions neutralised. It records the verdict on the author task's PR, for that head (see Reviewer verdict on every Worker PR). It counts rounds from its own earlier markers. A failed or interrupted turn posts nothing and leaves the commit unreviewed, so it can be asked again. As a backstop (not the boundary), the server looks for credential-shaped text before posting: GitHub, OpenAI and Slack tokens, OAuth refresh tokens (rt.…), AWS keys, private keys, JWTs, any unbroken token-like run of 100+ characters, the values in the Codex logins, the server's own tokens and keys, and the reviewer's runner token. It also checks the text with spaces removed, and decodes base64 runs of 40+ characters and checks those. If it finds any, it posts only a short "review withheld" notice (which doesn't mark the commit reviewed), sends the author nothing, marks the reviewer failed, and alerts the owner by push. The review text stays in the reviewer's log for the owner. - A FAIL queues one server-written repair brief for the author task at the reviewed head, regardless of Ask routing. The brief contains only validated file locations, server-written scenarios, counts and a comment link; raw reviewer text and prompts stay in the private reviewer task. It is sent after the live PR head is confirmed and before a potentially slow commit-status write, within the 10 messages per worker per hour cap. If capped, it stays queued and retries on later polls, even under Ask. Every actual repair send, including a designated Worker's recovered FAIL, uses one final GitHub head check after any earlier poll reads. If GitHub cannot confirm that head, the brief stays pending; manual Send cannot bypass the check. A newer PR head retires the old queued brief. A Manager can inspect the reviewer with
task_statusortask_wait:handoff.stateisqueued,awaiting_author, ornew_head, with safe timestamps for verdict, delivery and the next head. A PASS with findings keeps normal PR routing; a clean PASS sends nothing. The posted comment is not routed again as new feedback. - The reviewer stops, and its checkout (and, for a local repository, its merge branch) is removed. Its record and log stay; it can't be resumed.
At most two reviewers run at once on a host (CCR_CLOUD_MAX_REVIEWERS, 1–16). Beyond that, review_pr fails with a limit error; try again when one finishes. A reviewer still running after 20 minutes (CCR_CLOUD_REVIEW_TIMEOUT_MIN) is stopped and marked failed, freeing its slot. A lead can task_wait on the returned reviewerTaskId. For a reviewer, task_status and task_wait return only the review's status (running, posted, failed or stopped), the reviewer's agent and independence, the verdict (pass or fail) and comment link once posted, and the server's own error. They never return the reviewer's text, which may hold what it read.
The author is asked to fix every confirmed P0 and P1 finding and any security or data-loss finding. From round four on, it is asked to defer the remaining P2 and P3 findings to a follow-up issue. Reviewers need host mode, and Claude Code or Codex.
#Efficient review and coordination
Before starting a paid review, inspect the current PR commit, repository policy and any configured GitHub reviewer. A Codex GitHub connector may start when a draft becomes ready. Give one reviewer ownership of that commit and track its status. Accept an external review only through the repository’s trusted reviewer policy and an explicit outcome tied to that commit. A bot acknowledgment, no findings, or findings without a verdict cannot release a review hold. Use a fallback for a failed or stalled external review only under the repository policy, with the reason recorded.
Keep each repair with its existing author Worker. Deliver all findings together and review the repair scope when appropriate. A PASS advances authorized work to the merge gate. Stop after three failed rounds to reassess scope. Use background jobs for checks, and report review time, dispatch wait, author wait and merge wait separately. Record available usage and cost as estimates, preserving unknown values.
Assign separable features to Workers with acceptance criteria, file ownership and the next actor. Keep small decisions and edits inline when delegation would cost as much as the work. Serialize overlapping review-pipeline changes. Every waiting item needs a reason, responsible actor and a scheduled wake or running job.