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.

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
| Setting | What it does | Default |
|---|---|---|
| Enable PR reviews | Turns reviews on for the repository. Turning it off cancels reviews in progress | On for GitHub; on for other providers when linked and checks pass |
| Review trigger | When reviews start: Manual, Once when ready or Every update. See Review Triggers | Manual |
| Maximum review rounds | Rounds each PR starts with, 1 to 20 | 5 |
| Skip drafts for automatic review | Automatic triggers ignore draft PRs; requests still review drafts | On |
| Allow coding agents to fix blockers | Lets 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 Fixes | On |
| Delete source branch after merge | Deletes 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 deleted | Off |
| How Vera gates merges | Advisory, Status gate, Open threads or Vote (Vote acts only on GitHub for now). See Merge Gate | Status gate |
| Label pull requests with Vera's verdict | Keeps one verdict label on the PR. Not offered on Bitbucket | On |
| Let Vera run builds and tests | Lets Vera build and run targeted tests. It executes the PR's code on the runner | On |
| Use this project's VibeFlow data in reviews and answers | Lets Vera read the project's tickets and context. See VibeFlow Project Data | Off |
| Questions per pull request | How many @vibeflow ask questions each PR allows, 0 to 200; 0 turns questions off. Not offered on Bitbucket | 20 |
| Runner preference | Automatic or one Preferred runner, where reviews belong to the repository (GitHub, Azure Repos, and Bitbucket with the VibeFlow Vera app). See Runner Selection | Automatic |
Saving settings applies them at once to every existing review of the repository.

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 alwayssubscriptions survive.
Review Triggers
| Trigger | When a review starts |
|---|---|
| Manual | Only 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 ready | One 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 update | When 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 alwaysis 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:
| Condition | Detail |
|---|---|
| The setting is on | Let Vera run builds and tests in the repository's review settings |
| The PR is not from a fork | The source repository is the target repository |
| On GitHub, the author is trusted | The 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.jsonhooks or.mcp.jsonservers) 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:
- Open the project and go to Pull Requests
- Click Review a PR
- Choose the Repository and enter the PR number, then click Continue
- 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.

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.
| Command | Effect |
|---|---|
@vibeflow review | Review the current revision |
@vibeflow review always | Review the current revision, then every new push within the round budget |
@vibeflow re-review | Run 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 summary | Repost the latest review summary |
@vibeflow configuration | Show the repository's review settings and this PR's round usage |
@vibeflow help | List the commands. Any unrecognized @vibeflow line gets the same reply |
- Who can use them (GitHub):
review,review always,re-review,askanddismissneed write access to the repository, read back from GitHub for each command.summary,configurationandhelpwork 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.

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
| Severity | Meaning |
|---|---|
| Blocker | Should be fixed before merge, and blocks it at the Status gate level and above. Becomes a repair ticket |
| Advisory | Worth 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.

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 filesand 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
| State | Meaning |
|---|---|
| Not reviewed | No review has been requested for the current revision |
| Disabled | Reviews are off for this repository |
| Draft: waiting for ready for review | Automatic reviews skip drafts; a project member can still request a draft review. The PR check titles this Waiting for ready |
| Review required | The current base and head have no complete, blocker-free review |
| Waiting for the Vera agent | Queued until an eligible runner claims it. The PR check titles this Waiting for runner |
| Reviewing | Vera is checking the exact base and head shown on the panel |
| Findings to address | Unresolved findings remain; a fresh review must verify any fixes |
| Fixes queued | Repair tickets are waiting for a coding session on the PR branch |
| Fixing | A coding agent is repairing the linked issues |
| Verifying fixes | A fresh Vera session is checking the repair push |
| Reviewed | The current revision is clean |
| Partial review | Vera 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 reached | A review is needed but the PR has used all its rounds. Use Continue to add rounds |
| Paused | Reviews and automatic repairs are paused for this PR |
| Needs attention | The review has stopped; check the remaining rounds and findings before continuing |
| Closed | The pull request is closed; review and repair work has stopped |
| Review could not complete | The 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 required | Upgrade the VibeFlow CLI and restart Vera |
Controls
| Control | Effect |
|---|---|
| Review current revision / Re-run review | Starts a review. Re-running an already reviewed revision spends a round |
| Pause | Stops 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 |
| Continue | Resumes 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 update | Republishes 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.
| Review | Round |
|---|---|
| The first review, and each review after new commits | Spent |
A re-run of an unchanged revision, or @vibeflow re-review | Spent |
| The verification of a coding agent's fix | Spent |
| The restart after Pause and Continue, or the retry after a failed review | Spent |
| A runner retry within the same review | Free |
| An automatic recheck after only the target branch moved | Free |
A repeated @vibeflow review on an already reviewed revision | Free where reviews belong to the repository (GitHub, Azure Repos, Bitbucket with the VibeFlow Vera app) |
summary, configuration, help, dismiss and ask | Free (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 getsDismissed: <reason>, a withdrawn oneWithdrawn: <why>, and a finding that returnsReopened: <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:
successwhen nothing is open, andneutral(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.
- It passes only when the current head and base have a completed review with no unresolved blockers:
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.


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:
| Level | Gate |
|---|---|
| Advisory | Never 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 gate | Fails while an unresolved blocker exists |
| Open threads | The 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) |
| Vote | The 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
| Feature | Permission |
|---|---|
| Status gate (check run) | Checks: write |
| Vote, verdict labels and inline comments | Pull requests: write (labels also work with Issues: write) |
| Resolving finding threads | Contents: write. Without it Vera still replies in the thread and leaves it open |
| Gate name detection | Rulesets 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.

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




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
- In the CLI, press
nto start a new session - Choose the repository checkout, VibeFlow as the session type, and your project
- In the team picker, select Vera · Code Reviewer under Review & Support. Add a coding persona, such as Developer, to handle repairs
- Choose providers, routing, branch and worktree, then confirm. If Vera is the only persona, the wizard asks only for a provider, then Confirm

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.

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.

Runner settings in the CLI config:
| Setting | Effect | Default |
|---|---|---|
review_concurrency | Reviews and questions running at once across all Vera sessions in one CLI root | 2 |
review_review_slots / review_answer_slots | Slots that run reviews, and slots that only answer @vibeflow ask questions (0 to 8 each) | 1 each |
review_isolated | Runs 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 reminder | Off (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.

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 (
--intervalsets 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 sharedso 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 off | Setting on | |
|---|---|---|
| Review brief | PR, repository, findings and CI only | Also the project record, linked work and context documents |
| Answer to a project member | Repository only | Also the project's data |
| Answer to anyone else | Repository only | Repository 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 Cloud | Azure Repos | GitLab | |
|---|---|---|---|
| Vera acts as | The connected user's Bitbucket account; with the VibeFlow Vera Forge app, PR events arrive through the app | The organization's saved connection | The organization's GitLab review bot (a group access token under Integrations → GitLab) |
| Review owner | The repository with the Forge app; otherwise one VibeFlow user | The repository | One VibeFlow user |
| Comment commands | The GitHub commands from a commenter whose connected account has write access | The 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 dismiss | The GitHub commands from Developer access or more, with the commenter's own GitLab account connected to VibeFlow |
| Gate | Commit build status; with the Forge app, also a merge check | Iteration-bound PR status | Commit status VibeFlow review / <target branch> (gitlab.com only) |
| Comments | No HTML or Mermaid. Inline comments plus a PR task per blocker | No collapsible sections or Mermaid. Threads on changed files | Same as GitHub; findings published as one review on GitLab 17.2 and later |
| Labels and vote | No labels; vote pending verification | Tags; vote pending verification | Labels; 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 reviewcomment, 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 reviewworks 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 reviewon 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-reviewto 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 reviewas your connected account, so it starts a round only for a head that has not been reviewed; post@vibeflow re-reviewto 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
| Symptom | Fix |
|---|---|
| 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 required | Upgrade the VibeFlow CLI and restart Vera |
| Review could not complete | Use Continue to retry. A new commit also retries when the attempts ran out |
| Fixes queued never moves to Fixing | Start 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 reply | Any 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 disabled | Turn on Enable PR reviews for the repository, then request a review again |
| Review limit reached | Use Continue with additional rounds and a reason |