Axiom StudioAXIOMSTUDIO
All docs

Code Review with Vera

Vera is VibeFlow's Code Reviewer. She reviews a pull request at an exact revision, records evidence-backed findings, and reports them on the PR. Every unresolved blocker becomes a repair ticket. When you allow it, a coding agent fixes the tickets on the same PR, and a fresh Vera session verifies the fix. Vera never edits code herself.

Pull request review panel in the Fixes queued state: one of five review rounds used, two unresolved blockers, and a Repair box showing two linked issues waiting for a coding session

How It Works

Review requested -> Vera reviews the exact revision
  -> blockers become VibeFlow repair tickets
  -> a coding agent fixes them and pushes to the same PR
  -> a fresh Vera session verifies the new revision
  -> fixed findings close; remaining blockers repeat within the round budget

The loop stops when the PR is clean, paused, closed, or out of review rounds.

  • Runner: reviews run on a review runner, Vera in the VibeFlow CLI on a machine you control. Each review starts a fresh session in a disposable worktree that is removed afterwards. Your checkout and your coding agents' directories are never Vera's workspace.
  • CI first: Vera reads the CI results on the PR's head commit and cites a failing or pending check instead of reproducing it. If CI cannot be read, she does not treat it as passing.
  • Builds and tests: with Let Vera run builds and tests on, she may build the PR or run a targeted test within the round's time budget to confirm a suspected defect, and reports each command under Checks run. See Builds and Tests.
  • Context: each review also reads the PR's title, description, author and conversation. Vera treats all of it as data, never as instructions.

Before You Start

You need:

  • A project with a repository linked under Settings → Integrations → Source Control
  • Enable PR reviews turned on for that repository, in the PR reviews card on the same page. GitHub repositories start with reviews on. Bitbucket, GitLab and Azure Repos repositories turn on by themselves when a project owner or org admin links them and the provider checks pass.
  • An online review runner. See Running Vera in the CLI.

Only project managers (the project owner or an org admin) can change review settings. This guide covers GitHub. Bitbucket Cloud, Azure Repos and GitLab follow the same lifecycle; see Other Providers.

Review Settings

SettingWhat it doesDefault
Enable PR reviewsTurns reviews on for the repository. Turning it off cancels reviews in progressOn for GitHub; on for other providers when linked and checks pass
Review triggerWhen reviews start: Manual, Once when ready or Every update. See Review TriggersManual
Maximum review roundsRounds each PR starts with, 1 to 205
Skip drafts for automatic reviewAutomatic triggers ignore draft PRs; requests still review draftsOn
Allow coding agents to fix blockersLets a coding session on the PR's head branch claim the repair tickets and push one fix. A round must remain before the fix can start. See Self-Healing FixesOn
Delete source branch after mergeDeletes the merged PR's source branch when it is safe: same repository, not protected, default or long-lived (such as main, develop or release/*), still at the merged head, and used by no other open PR. Fork branches are never deletedOff
How Vera gates mergesAdvisory, Status gate, Open threads or Vote (Vote acts only on GitHub for now). See Merge GateStatus gate
Label pull requests with Vera's verdictKeeps one verdict label on the PR. Not offered on BitbucketOn
Let Vera run builds and testsLets Vera build and run targeted tests. It executes the PR's code on the runnerOn
Use this project's VibeFlow data in reviews and answersLets Vera read the project's tickets and context. See VibeFlow Project DataOff
Questions per pull requestHow many @vibeflow ask questions each PR allows, 0 to 200; 0 turns questions off. Not offered on Bitbucket20
Runner preferenceAutomatic or one Preferred runner, where reviews belong to the repository (GitHub, Azure Repos, and Bitbucket with the VibeFlow Vera app). See Runner SelectionAutomatic

Saving settings applies them at once to every existing review of the repository.

PR reviews settings card for a linked GitHub repository: Enable PR reviews checked, Review trigger Manual, Maximum review rounds 5, How Vera gates merges set to Status gate, Allow coding agents to fix blockers and Let Vera run builds and tests checked, and Runner preference Automatic

Turning Reviews Off and On

  • A review in progress is cancelled and its round stays spent.
  • Every review of the repository shows Disabled, except closed, paused or stopped ones.
  • PR events start nothing, and requests and comment commands are refused.
  • A PR that already has a VibeFlow check is updated to Review disabled, which fails a required check unless the gate level is Advisory.
  • Turning reviews back on does not review existing PRs. Each waits as Not reviewed until its next qualifying event or a request. @vibeflow review always subscriptions survive.

Review Triggers

TriggerWhen a review starts
ManualOnly when someone requests one: Review this PR (or Review current revision once a review exists) in VibeFlow, or @vibeflow review on the PR
Once when readyOne automatic review per PR, on the first ready event (opened, reopened or marked ready for review), and only if no review has started on it. Later commits are not reviewed automatically
Every updateWhen VibeFlow first sees the PR, and after each new commit or target-branch change, until its rounds run out

In every mode:

  • A PR subscribed with @vibeflow review always is reviewed after each push.
  • With automatic fixes on, a coding agent's fix is re-reviewed without a request.
  • Commits pushed while a review waits or runs replace it with a review of the new head.
  • With Skip drafts for automatic review on, a push to a draft, or turning a PR back into a draft, cancels its queued or running review.
  • A PR that VibeFlow opens is tracked at once. With Once when ready or Every update it also gets an automatic review, once it is marked ready, because VibeFlow opens PRs as drafts by default.

Builds and Tests

Vera may execute the PR's code only when all of these hold:

ConditionDetail
The setting is onLet Vera run builds and tests in the repository's review settings
The PR is not from a forkThe source repository is the target repository
On GitHub, the author is trustedThe author is the repository's owner, an organization member or a collaborator, or the account VibeFlow publishes as. If this cannot be read, the author is not trusted

When execution is allowed, Vera reads CI first and builds or runs a targeted test only to confirm or refute a specific suspicion. She stays inside the review's worktree, never installs global packages, and uses the network only for the dependency fetches the build needs. When it is not allowed, she does not build, install dependencies or run tests, and runs nothing from the PR. She still reads the code and uses read-only commands, and states defects with file and line evidence.

Requesting a Review

Security: reviews can run code from the pull request.

  • Each review runs the coding CLI with permission prompts and sandbox off, as the user who started Vera, on the runner machine.
  • With Let Vera run builds and tests on, Vera may build the PR and run its tests. That executes the PR's code with that user's files, Git credentials and VibeFlow CLI config.
  • Vera is told to do this only for PRs from the repository's own branches. On GitHub the author must also be trusted. A fork, or on GitHub any other author, gets a task that forbids building and running tests. Turning the setting off forbids it for every PR.
  • This rule is part of Vera's task, not a sandbox. Treat the runner account as exposed to every PR it reviews, including PRs from forks.
  • Claude Code reviews never load project settings (such as .claude/settings.json hooks or .mcp.json servers) from the PR checkout. The other harnesses refuse a PR that adds or changes their own workspace configuration.

With Once when ready or Every update, anyone who can open or update a PR, including one from a fork, starts a review automatically. On a public repository, or any repository that accepts outside contributors, either leave Enable PR reviews off, or run Vera only on an isolated, disposable runner with no personal credentials and no access to other repositories or secrets.

From VibeFlow

The Pull Requests page lists the project's PRs, highest PR number first. The Open, Merged, Closed and All tabs filter by state, and the search box takes a PR number or part of a title. The Vera column shows each review at a glance, for example Needs review, Queued, Reviewing, Clean, N blockers, Paused or Needs attention. A review that did not cover every file shows Needs attention while the PR is open, and Partial once it is closed.

To review a PR that is not in the list:

  1. Open the project and go to Pull Requests
  2. Click Review a PR
  3. Choose the Repository and enter the PR number, then click Continue
  4. On the PR's review panel, click Review this PR

On GitHub, anyone with access to the project can request a review. Requests are refused while reviews are off, and a paused or stopped PR needs Continue instead. The request stays queued (Queued in the list, Waiting for the Vera agent on the review panel, Waiting for runner on the PR's check) until a runner claims it. If none is online, the PR comment and reply name the vibeflow review-watch command that starts one.

Choose a pull request form on the Pull Requests tab, with the linked repository selected, a PR number entered and two runners online, above the list of reviewed pull requests

From a GitHub Comment

Post a top-level comment that starts with the command. For ask and dismiss, the rest of the first line and any later lines are the question or the reason; for the other commands, later lines are ignored. These commands also work on GitLab, Bitbucket and Azure Repos with different permission rules; see Other Providers.

CommandEffect
@vibeflow reviewReview the current revision
@vibeflow review alwaysReview the current revision, then every new push within the round budget
@vibeflow re-reviewRun a fresh round on the current revision, even if already reviewed. Spends a round
@vibeflow ask <question>Ask Vera about the PR, before or after a review. The answer cites file and line evidence
@vibeflow dismiss <reason>In a finding's thread: dismiss that advisory. See Disagreeing with a Finding
@vibeflow summaryRepost the latest review summary
@vibeflow configurationShow the repository's review settings and this PR's round usage
@vibeflow helpList the commands. Any unrecognized @vibeflow line gets the same reply
  • Who can use them (GitHub): review, review always, re-review, ask and dismiss need write access to the repository, read back from GitHub for each command. summary, configuration and help work for anyone who can comment. No VibeFlow account is needed.
  • Reply: VibeFlow reacts with 👀 and replies with a link to follow the review. If the revision is already reviewed, the reply says so and no round is spent. A paused or stopped review, or one with no rounds left, needs Continue first.
  • Forks: until a repository's review settings are saved, it refuses PRs from forks with "Vera can't review pull requests opened from a fork". Saved settings let GitHub fork PRs be reviewed. Azure Repos never reviews fork PRs.
  • Behavior: commands count as manual requests, so they work in Manual mode and on draft PRs. Only newly posted comments count; editing a comment into a command does nothing.
  • review always: works in any trigger mode and survives trigger changes. It stops while the review is paused, the PR is closed, or the round budget is used up.

Questions do not spend review rounds. Each PR has its own allowance (20 by default). Vera answers from the whole repository at the PR's revision and from the review's findings, and follow-up questions continue the conversation. Answers are written against the latest completed review's head, and the reply names it. A question that no runner picks up within 30 minutes is failed with a reply and does not count against the allowance. With questions turned off, Vera replies that they are off for the repository.

Repositories Without a Webhook

PR events and comment commands arrive through provider webhooks, and nothing scans for them on a schedule. Check for pull requests on the Pull Requests page appears only when a linked repository has no webhook configured. One click checks up to 4 such repositories, queues newly found PRs for automatic review, and re-checks tracked PRs; each repository is checked at most once every 5 minutes. If a configured webhook stops delivering, fix or recreate it, or request reviews from the review panel.

Reading a Review

The review panel shows the PR's state, rounds used, unresolved blockers and the next action.

Review panel while Vera is reviewing: status Reviewing, one of five rounds used, the selected runner, and a Vera Code Reviewer card showing the round, attempt, revision and start time

Findings

Each finding has a severity, a location and four parts:

  • Trigger: the input or path that causes the problem
  • Impact: what goes wrong
  • Evidence: the code that causes it
  • Verification: how Vera confirmed it, for example by executing the code
SeverityMeaning
BlockerShould be fixed before merge, and blocks it at the Status gate level and above. Becomes a repair ticket
AdvisoryWorth fixing, but does not block. No ticket is filed automatically; you can create issues from advisories on the review page

A finding is Present, Uncertain, Verified fixed or Dismissed. Project managers can Dismiss finding and later Reopen with evidence on the review page.

A blocker must carry proof: a failing CI check, a command Vera ran with its output, or a trace from trigger to impact through file and line references. Before submitting, Vera re-checks every blocker in a second pass. One that does not survive is published as an advisory whose Verification starts with Unverified:, so it never gates the merge.

Findings list on the review panel: two Blocker · Present findings, a missing first entry in the monthly report and an SQL injection in the account lookup, each with its Trigger, Impact and linked repair issue

Coverage

A review is Clean only when every changed file is accounted for. The CLI lists every changed file and marks those Vera may skip, by rule: deleted, binary, vendored, lockfile and generated files. Vera reports each file as reviewed or skipped, and VibeFlow checks that list against the provider's own changed-file list.

A clean result with any unreviewed file is a Partial review:

  • The gate shows Partial review: N of M files and never passes (an Advisory gate still reports it as passing).
  • Vera gives no approval, and withdraws an earlier one for the same head.
  • @vibeflow re-review, the check's Re-review button, or a request from VibeFlow reviews the rest. It spends a round.

Only runners that report coverage take reviews. An older CLI never claims one: the review stays queued and the PR shows Runner upgrade required.

Each review runs as one Vera session. Files she does not reach within the round's time budget are reported as unreviewed and make the review Partial.

Repository Rules

Put your own review rules, in plain English, in .vibeflow/review-rules.md. Vera reads the file from the PR's target branch, never from the PR, so a PR cannot weaken its own review. Only the first 8 KiB are used. A violation the PR introduces is a finding, and a blocker when file and line evidence shows it. The rules apply to reviews, not to @vibeflow ask answers. REVIEW.md on the target branch is still read as general review standards.

## SQL
Every database query uses bound parameters, never string concatenation.

## Money
Amounts are integer cents; no float arithmetic on prices.

Disagreeing with a Finding

Every inline finding comment names the ways out: apply the suggestion, reply @vibeflow ask <question>, or reply @vibeflow dismiss <reason>.

  • Advisories: @vibeflow dismiss <reason> in the advisory's thread dismisses it, as does Dismiss advisories on the GitHub check run. A reason is required, and the commenter needs write access.
  • Blockers: these are dismissed only from the review page, by a project manager, so a PR's author cannot clear the merge gate from the conversation.
  • Withdrawals: if a reply in an advisory's thread persuades a later round that the advisory is wrong, Vera withdraws it and says why. She never withdraws a blocker.

Dismissal memory: Vera remembers findings your team rejected, per repository. A person's dismissal, or a thumbs-down on one of her inline comments from someone who can push (GitHub and GitLab), counts as dismissed-as-wrong. A withdrawal by Vera does not. The next round's brief carries the newest dismissals for the PR's files. A new finding that matches a dismissal exactly (same title, severity, path, line and unchanged file) is dropped and counted on the PR comment. A dismissed advisory never drops a blocker. Reopening a finding with evidence removes its remembered dismissal.

Review States

StateMeaning
Not reviewedNo review has been requested for the current revision
DisabledReviews are off for this repository
Draft: waiting for ready for reviewAutomatic reviews skip drafts; a project member can still request a draft review. The PR check titles this Waiting for ready
Review requiredThe current base and head have no complete, blocker-free review
Waiting for the Vera agentQueued until an eligible runner claims it. The PR check titles this Waiting for runner
ReviewingVera is checking the exact base and head shown on the panel
Findings to addressUnresolved findings remain; a fresh review must verify any fixes
Fixes queuedRepair tickets are waiting for a coding session on the PR branch
FixingA coding agent is repairing the linked issues
Verifying fixesA fresh Vera session is checking the repair push
ReviewedThe current revision is clean
Partial reviewVera did not account for every changed file, so the review cannot pass. The review page shows Needs attention; the PR check and comment show Partial review
Review limit reachedA review is needed but the PR has used all its rounds. Use Continue to add rounds
PausedReviews and automatic repairs are paused for this PR
Needs attentionThe review has stopped; check the remaining rounds and findings before continuing
ClosedThe pull request is closed; review and repair work has stopped
Review could not completeThe runner used up its attempts or passed the round deadline. Continue retries it; a new commit also retries when the attempts ran out
Runner upgrade requiredUpgrade the VibeFlow CLI and restart Vera

Controls

ControlEffect
Review current revision / Re-run reviewStarts a review. Re-running an already reviewed revision spends a round
PauseStops reviews and repairs on this PR and cancels any running; a cancelled review's round stays spent. It also suspends @vibeflow review always until you Continue
ContinueResumes a paused PR, one that needs attention, or one out of rounds. Adds Additional review rounds to this PR only (0 to 20; at least 1 when none is left) and needs a Reason. If the revision already has a completed review, it restores that result instead of reviewing again
Retry PR updateRepublishes the GitHub summary and check without another review. It appears only when the PR update failed or is blocked

Re-run review is disabled once the PR has used all its rounds; use Continue first. Pause, Continue, dismissing and reopening findings, and Retry PR update need project manager access (the project owner or an org admin). Where a review belongs to one VibeFlow user (Bitbucket without the VibeFlow Vera app, and GitLab), only its owner can use them.

Review Rounds

A round is spent when a runner starts a review, not when someone asks for one. Requests and pushes that arrive while a review is waiting merge into it.

ReviewRound
The first review, and each review after new commitsSpent
A re-run of an unchanged revision, or @vibeflow re-reviewSpent
The verification of a coding agent's fixSpent
The restart after Pause and Continue, or the retry after a failed reviewSpent
A runner retry within the same reviewFree
An automatic recheck after only the target branch movedFree
A repeated @vibeflow review on an already reviewed revisionFree where reviews belong to the repository (GitHub, Azure Repos, Bitbucket with the VibeFlow Vera app)
summary, configuration, help, dismiss and askFree (ask counts against the question allowance)
  • Cut short: a review that started stays spent when a push, Pause, turning reviews off, closing the PR or converting it to a draft cuts it short. Spent rounds are never refunded.
  • Budget: VibeFlow copies Maximum review rounds into a PR when it first tracks it. Raising the maximum does not extend tracked PRs; use Continue. Lowering it cuts their limits, never below the rounds already spent.
  • Attempts: each round allows 3 runner attempts. If a runner fails, stops renewing its 2-minute lease or loses access, another attempt runs on the same round for free. When attempts run out or the deadline passes, the PR shows Review could not complete.
  • Deadline: a round starts with 30 minutes from the runner's first claim. Every 5,000 changed lines add 10 minutes, up to 60. The deadline never gets shorter.

What Vera Posts on GitHub

  • One summary comment per PR, posted when the first review is requested and edited in place, so there is never a stale one. It leads with the current round; earlier rounds fold at the bottom. It holds:
    • Verdict: for example Changes requested: 1 blocker, 1 advisory, with the round and the reviewed head
    • Gate rule: what the merge gate does at the configured level
    • Fix before merge: up to three unresolved blockers, linked to their inline comments
    • Also noticed: up to five unresolved advisories
    • Fixed since last round: findings verified fixed, dismissed or withdrawn
    • What the change does: Vera's summary, with a Mermaid diagram of the flow where it helps, then Verified, Checks run and Limits
    • Proof and history: a collapsed block with each blocker's trigger, impact, evidence and verification
  • A clean first round gets a short comment: ✅ Clean: nothing to fix., the coverage line, Checks run, What this change is and Verified. A review with partial coverage, a Limits section, or no What this change is keeps the full layout.
  • Inline comments on the diff. Unresolved blockers are placed on their lines (up to 50 findings). A blocker on a line outside the diff goes on its file as a file comment; one in a file outside the diff appears only in the summary. An advisory is placed only when it carries a suggested change you can apply. Other advisories are listed in the summary, five at a time, with the rest counted.
    • A cause found in several places gets one comment that names the others.
    • Each blocker comment includes a Prompt for an AI agent to paste into a coding agent, followed by a line naming how to ask or dismiss.
    • After three completed rounds in a row with no new blocker, later advisory-only rounds update the summary only. This is automatic, with no setting.
  • Thread replies. When a round verifies a finding fixed, Vera replies Fixed in <sha>: <reason> and resolves the thread. A dismissed finding gets Dismissed: <reason>, a withdrawn one Withdrawn: <why>, and a finding that returns Reopened: <reason>. Vera waits to resolve a thread as fixed while its newest message is someone else's reply that she has not answered. A dismissal replies and resolves at once.
  • A check run named VibeFlow review. With a personal access token instead of the GitHub App, it is a commit status with the same name.
    • It passes only when the current head and base have a completed review with no unresolved blockers: success when nothing is open, and neutral (grey, still passing) while advisories remain open.
    • It fails while blockers remain, and asks for action when the review is paused, disabled, closed or needs a person.
    • Its title carries the result, for example Findings to address · 2 blockers · 1 advisory · 522fd64.
    • It annotates Files changed with each unresolved finding, up to 150.
    • Re-review and, while advisories are open, Dismiss advisories buttons need write access. GitHub's own Re-run button also starts a re-review.

Edits to the summary comment send no notification, so progress updates stay quiet. Inline comments, thread replies and votes are new posts and do notify. Mentions, issue references and links in Vera's text are made inert, and other raw HTML is shown as code.

VibeFlow review comment on the GitHub pull request in the Clean state: round 2 of 5 and the reviewed head, the gate rule, the coverage line, the fixed and still-open counts, and the advisories listed under Also noticed

GitHub merge box after a clean review: the vera: approved label added, and All checks have passed with the VibeFlow review checks

Merge Gate

To make reviews a merge gate, add the check named in the repository's review settings (under Merge gate name) as a required status check in your branch protection rules or rulesets, and select the GitHub App as its source. A PR has no result until its first review, so a required check blocks PRs that have not been reviewed yet. Pair it with a required human approval, so no single automated result is the only control on a merge.

How Vera gates merges sets what the check reports:

LevelGate
AdvisoryNever fails. A clean review with nothing open is success. Every other result passes with a title that starts Advisory:; on check runs that is neutral (grey, not green)
Status gateFails while an unresolved blocker exists
Open threadsThe status gate, plus guidance to turn on the provider's rule that blocks merges while review threads are open (on GitHub, Require conversation resolution before merging)
VoteThe status gate, plus Vera's own approve or request-changes vote (GitHub only for now)

The level lives in VibeFlow, not in the repository, so a PR cannot weaken its own review. Saving a new level republishes the gates of every open review. The summary comment always keeps the real verdict.

Vote counts toward required approvals, and Vera reviews content the PR author controls, so treat her approval as additional to human review. Keep at least one required human approval (Code Owners review or 2 approvals) and turn on Dismiss stale pull request approvals when new commits are pushed. Only the GitHub App votes; with a personal access token Vera applies labels but does not vote. Vera dismisses her approval when a push moves the head, and removes the vera: approved label.

Verdict labels: with the label setting on, Vera keeps one label, vera: approved or vera: changes requested, and swaps it when her verdict changes. She creates the label only if the repository has none of that name, and never touches other labels.

Merge queues are supported. For a merge group, VibeFlow passes the gate on the group's commit, because every PR in it already passed to enter the queue. The GitHub App must subscribe to the Merge group webhook event; the VibeFlow GitHub App does not subscribe to it by default.

Gate name: the default branch's gate is VibeFlow review. A PR into any other branch publishes VibeFlow review / <base branch>, unless that branch's protection requires the plain name. A repository whose default-branch protection requires the older name VibeFlow review / <base branch> keeps it. If VibeFlow cannot read the protection, it keeps the base-suffixed name and also publishes VibeFlow review. The repository's review settings show the name in use under Merge gate name. When a PR opens or changes its base and the head commit already carries a result from another PR or base, VibeFlow posts a pending gate titled Waiting for a review against <base>, so an earlier result cannot satisfy this PR's required check.

GitHub App permissions

FeaturePermission
Status gate (check run)Checks: write
Vote, verdict labels and inline commentsPull requests: write (labels also work with Issues: write)
Resolving finding threadsContents: write. Without it Vera still replies in the thread and leaves it open
Gate name detectionRulesets are read with the App's repository read access (Metadata: read); classic branch protection needs Administration: read. Without it the gate keeps the base-suffixed name and is also published as VibeFlow review

The VibeFlow GitHub App holds Checks, Contents, Issues and Pull requests (write) and Metadata (read). It does not hold Administration: read, so it cannot read classic branch protection.

Self-Healing Fixes

Every unresolved blocker becomes a VibeFlow issue targeting the PR branch, whether or not automatic fixes are on. With Allow coding agents to fix blockers off, the tickets tell a human to fix them and the repair batch stays held.

Issues list showing the two repair tickets created from Vera's blockers, both Done after the fix was verified, each targeting the pull request's branch

With automatic fixes on:

  1. A Developer, Architect or Principal Engineer session on the PR's head branch claims the repair batch
  2. The agent fixes all blockers in the batch and pushes one update to the same PR. VibeFlow does not open a new PR
  3. A fresh Vera session reviews the updated PR. This spends a round
  4. Findings close only when that fresh review verifies them. Completing a ticket does not close a finding by itself
  5. Remaining blockers repeat the loop until the PR is clean or the round budget runs out

Review panel in the Fixing state while the coding agent repairs the linked issues, with the next action to wait for its push

Review panel in the Verifying fixes state: two of five rounds used and a fresh Vera session reviewing the pushed revision

Review panel in the Reviewed state: round 2 of 5 reviewed at the repair head, with the repair pushed for verification

Findings after verification, filtered to Resolved: both blockers are now Blocker · Verified fixed, each with its repair issue

Limits:

  • The PR must not be a draft, and its head repository must be linked to the project
  • A review round must remain before an agent can claim the batch; the verification review spends it
  • Each batch allows at most 3 claims and has one 30-minute deadline from its first claim. The claiming session renews a 2-minute lease while it works
  • More than 100 unresolved blockers stop the loop for human triage

Vera never claims a repair batch. Where reviews belong to the repository (GitHub, Azure Repos, and Bitbucket with the VibeFlow Vera app), any project member's coding session on the PR's head branch and repository can; otherwise only the member who owns the review can. A session that already holds a repair batch, or a todo or issue in planning or implementing, cannot. Turning on automatic fixes does not start coding sessions; start one on the PR branch yourself. A batch also waits if the PR's head repository is not added under Git Source → Repos for the project. Turning it off cancels a repair in progress and returns its tickets to In review. Turning it back on does not resume that batch; a new review creates a new one. Where the coding-agent plan gate is on, Starter organizations fix the tickets by hand and the PR's next step says so.

Running Vera in the CLI

Reviews run on your machine through the VibeFlow CLI. Run Vera on a dedicated machine or container account, not your personal workstation: each review runs with full permissions as that account (see the security note).

Requirements:

  • macOS or Linux
  • tmux 3.2 or later
  • A supported coding CLI (Claude Code, Codex, Copilot, Cursor, Gemini, Kiro or Qwen), installed and signed in
  1. In the CLI, press n to start a new session
  2. Choose the repository checkout, VibeFlow as the session type, and your project
  3. In the team picker, select Vera · Code Reviewer under Review & Support. Add a coding persona, such as Developer, to handle repairs
  4. Choose providers, routing, branch and worktree, then confirm. If Vera is the only persona, the wizard asks only for a provider, then Confirm

VibeFlow CLI team picker with Developer selected as the code agent and Vera · Code Reviewer checked under Review & Support

Vera runs in her own tmux session and listens for requests until you delete the session. No model runs while she is idle. Each review starts a fresh harness session in a disposable worktree.

Vera's session: the review runner on the left reporting each result and returning to listening, and the Reviews history on the right listing the reviewed pull requests as Clean

The right pane, Reviews, lists recent reviews with their outcome (for example Clean, Changes requested, Needs human review, Queued or Reviewing), round, finding count and revision. Use ↑/↓ to browse and Enter to open a review. Ctrl-C stops Vera while she is listening; during a review it goes to the harness.

Review detail popup in the CLI: the pull request, outcome Clean, two of five rounds used, the last reviewed head, and the recorded summary

Runner settings in the CLI config:

SettingEffectDefault
review_concurrencyReviews and questions running at once across all Vera sessions in one CLI root2
review_review_slots / review_answer_slotsSlots that run reviews, and slots that only answer @vibeflow ask questions (0 to 8 each)1 each
review_isolatedRuns Vera's Claude Code without your hooks, MCP servers, plugins and output style. Claude Code only. --isolated turns it on for one foreground run and is not accepted with --background; for a background runner set it in the config. When nothing is saved the runner prints a reminderOff (your own setup)

Vera in Team Chats

While a Vera runner is active, she also appears in the project's Team Chats as a read-only card with her status, repository, runner and owner, plus a Reviewed PRs list. She has no chat; manage reviews from Pull Requests.

Team Chats with the Vera · Code Reviewer card selected: status Listening, the repository, local runner and owner, and a Reviewed PRs list with each pull request's outcome and round

Runner Selection

Every project member can open the runner chip beside Review a PR on the Pull Requests page; it reads, for example, "1 runner" or "No runners online". Opening it shows each repository's review-watch command and a Refresh runners button. Status loads when you open it and when you refresh; it does not update on its own. Project managers see the same on each repository's PR reviews card.

  • Runners pull work: each checks in every 5 seconds by default (--interval sets 1 to 60 seconds), and the first eligible runner to claim a queued review runs it.
  • A runner counts as online while it is enabled and has checked in within the last 2 minutes. Each runs one review at a time.
  • A review or question runs on the requester's own runner whenever one is online for the repository, even while it is busy. Otherwise any eligible runner takes it. Where reviews belong to the repository, the finding tickets belong to the person who requested the round, and a verification round after an automatic fix keeps the original requester.
  • Preferred holds new reviews for one runner while it is online, and takes precedence over the requester's runner. When it is offline, any eligible runner can take them. Automatic lets any eligible runner take the next review.
  • A queued review waits until a runner claims it and spends no round until then.
  • A runner is identified by server, project, repository link, Git provider, kind and --name (the hostname by default). Restarting with the same values reuses it, so a saved Preferred choice still applies; changing the coding harness does not create a new runner.
  • Where reviews belong to one user (Bitbucket without the VibeFlow Vera app), start a runner with --runner-kind shared so that you and other members can select it as your Shared fallback. On GitHub and Azure Repos, use Preferred instead.

Headless Runners

On a machine without tmux, run a detached runner. The same security note applies. Copy the review-watch command shown for the repository, then add --repo with the path to your checkout and --background. A background runner needs --project, --repository-link and --repo, and reads its credentials from the CLI config:

vibeflow review-watch --project <project-id> --repository-link <link-id> --git-provider github --repo <path-to-checkout> --background

Use vibeflow review-watch --status to list background runners and --stop <ID> to stop one.

VibeFlow Project Data

Vera uses the project's VibeFlow data only when a project manager turns on Use this project's VibeFlow data in reviews and answers. It is off by default. Reviews and answers are posted on the PR, so everyone who can read it sees them; on a public repository that is anyone.

Setting offSetting on
Review briefPR, repository, findings and CI onlyAlso the project record, linked work and context documents
Answer to a project memberRepository onlyAlso the project's data
Answer to anyone elseRepository onlyRepository only

Each review or answer gets its own read-only VibeFlow credential for this project. It stops working when the review ends or the setting is turned off, and after at most one hour. The runner never gives the agent your own VibeFlow token. Claude Code, Codex, Qwen Code and Copilot CLI can use it; Gemini CLI, Cursor and Kiro run without VibeFlow tools.

Other Providers

Bitbucket Cloud, Azure Repos and GitLab use the same settings card, review panel and lifecycle, with these differences.

Bitbucket CloudAzure ReposGitLab
Vera acts asThe connected user's Bitbucket account; with the VibeFlow Vera Forge app, PR events arrive through the appThe organization's saved connectionThe organization's GitLab review bot (a group access token under Integrations → GitLab)
Review ownerThe repository with the Forge app; otherwise one VibeFlow userThe repositoryOne VibeFlow user
Comment commandsThe GitHub commands from a commenter whose connected account has write accessThe GitHub commands from a commenter whose sign-in email belongs to a VibeFlow user who can see the project. ask and dismiss also work as replies in Vera's threads; only a project manager can dismissThe GitHub commands from Developer access or more, with the commenter's own GitLab account connected to VibeFlow
GateCommit build status; with the Forge app, also a merge checkIteration-bound PR statusCommit status VibeFlow review / <target branch> (gitlab.com only)
CommentsNo HTML or Mermaid. Inline comments plus a PR task per blockerNo collapsible sections or Mermaid. Threads on changed filesSame as GitHub; findings published as one review on GitLab 17.2 and later
Labels and voteNo labels; vote pending verificationTags; vote pending verificationLabels; vote pending verification

Vote is GitHub only for now: on the other providers Vote works like Status gate. Self-managed GitLab is not supported; GitLab reviews run on gitlab.com. For Azure Repos (connection, comment commands, statuses and checkout) see Vera pull-request reviews.

Bitbucket Differences

  • Link: linking a repository needs your own connected Bitbucket account. VibeFlow reads the repository with it before saving the link.
  • Without the Forge app: each review belongs to one VibeFlow user: whoever first requests it, the author of the first @vibeflow review comment, or, for automatic reviews, the PR author when their Bitbucket account is connected to exactly one VibeFlow user. Only the owner can pause, continue, dismiss or retry, and only the owner's runner and coding sessions can work on it.
  • With the Forge app: any member with a connected Bitbucket account and write access can request a review, their runner is tried first, and the tickets are theirs. A workspace that installs the app links to your organization on the first PR event in a repository one of your projects links, if the user who verified that link administers the workspace. An org admin whose own connected Bitbucket account administers the workspace can also link it under Integrations → Bitbucket with Link to this organization.
  • Commands: @vibeflow review works only when the commenter's Bitbucket account is connected to VibeFlow, can see the project, and has write or admin permission. Vera acknowledges each command with a reply, since Bitbucket has no reactions. Without the Forge app, a repeated @vibeflow review on a reviewed revision runs again and spends a round. With the Forge app it is answered as already reviewed and spends no round; use @vibeflow re-review to force one.
  • Gate: Vera posts a build status named VibeFlow review on the head commit, plus a Code Insights report with one annotation per finding. Bitbucket's minimum-successful-builds check counts all builds on the last commit and does not single out Vera's status, so use the Forge app's merge check to gate on her review. Code Insights is informational and never gates a merge; it is skipped when the workspace refuses it, for example on plans that limit third-party integrations.
  • Inline comments: blockers, and advisories with a suggestion, are posted on the diff. The fix is a plain Suggested change block to copy, since Bitbucket cannot apply it. Each blocker also gets a PR task, resolved when the blocker is fixed, so the No unresolved pull request tasks merge check holds the merge.
  • Forge app on PRs: the VibeFlow review merge check, a side card, an overview panel and an Ask Vera about this PR action. Enable the merge check in the repository's Bitbucket merge-check settings. On plans other than Bitbucket Premium, merge checks only warn; blocking a merge needs Premium. It passes only when the current head has a completed review with no unresolved blockers, and never starts a review. Re-review posts @vibeflow review as your connected account, so it starts a round only for a head that has not been reviewed; post @vibeflow re-review to force one. Ask Vera posts @vibeflow ask <question>.

GitLab Differences

The gate is a commit status named after the target branch, VibeFlow review / main for a merge request into main. GitLab keys statuses by commit, so merge requests from one source branch share a pipeline. Naming the target keeps one merge request's success from passing "Pipelines must succeed" on another. Two open merge requests from one source branch each need the other's review to pass; review both, or close the one you do not need. After a round, the bot's reviewer state follows the verdict on GitLab 18.9 and later; older versions rely on the commit status alone. VibeFlow never overwrites an approval.

Troubleshooting

SymptomFix
Review stays queued (Waiting for the Vera agent in VibeFlow, Waiting for runner on the PR)Start Vera in the CLI and check the runner chip on the Pull Requests page. Check that the runner's CLI supports repository reviews and that no online Preferred runner is holding new reviews. Where reviews belong to one user, that user must start the runner or pick a shared one as Shared fallback
Runner upgrade requiredUpgrade the VibeFlow CLI and restart Vera
Review could not completeUse Continue to retry. A new commit also retries when the attempts ran out
Fixes queued never moves to FixingStart a Developer, Architect or Principal Engineer session on the PR's head branch, from a clone of the PR's head repository, with no other todo, issue or repair in progress. Check that automatic fixes are on, a round remains, and the head repository is added under Git Source → Repos for the project
@vibeflow review gets no replyAny top-level comment that starts with @vibeflow gets at least a help reply, so no reply means the comment did not start with @vibeflow, was not top-level, or the repository's webhook did not reach VibeFlow. On Azure Repos, a commenter whose email matches no organization member is ignored silently. Request the review from the PR's review panel
Reply says the repository review policy is disabledTurn on Enable PR reviews for the repository, then request a review again
Review limit reachedUse Continue with additional rounds and a reason