Skip to main content

​
Overview

Capy analyzes pull request diffs in two complementary ways: a PR summary and review findings. The summary explains what changed at a functional level, grouped by capability rather than by file. Findings identify specific issues, categorize them, assign severity, and attach them to code locations. You can trigger reviews from Captain or directly from the PR page. When Captain is managing the task, it handles the full triage-and-fix loop after the review completes.

​
Triggering a review

You can start a review in three ways:
  1. From Captain After Captain creates a PR for a completed task, it automatically triggers a review when permissions allow. Captain passes context about what the task was meant to accomplish, so the Review agent evaluates the diff against intended behavior, not just raw code changes. You can also ask Captain to review any PR at any time, for example review PR #42 or run the review agent on SCO-005.
  2. From the PR page Open any pull request in the Capy dashboard and click Review to run a manual review.
  3. Automatic on PR events Enable Auto-review PRs in your project settings to automatically review every PR when it’s opened or updated. This applies to PRs not managed by Captain - draft PRs are skipped, and PRs associated with Capy tasks are skipped because Captain handles those reviews separately. No user-level permission is needed; the setting is project-wide.

​
Review permissions

By default, Capy asks for permission before running a review. When Captain wants to review a PR, you get a permission card with four options:
  • Deny - skip the review
  • Allow this time - one-time approval (expires after about 5 minutes)
  • Allow for this run - approve for the current Captain session
  • Always allow - enable auto-review permanently
Always allow is the same setting as the PR reviews toggle in Settings → Preferences. When you enable it, Capy reviews PRs automatically without prompting, and any PR where you are the author gets reviewed. You only need to grant permanent permission once. After auto-review is enabled, future reviews run without interruption.

​
What a review produces

PR summaries and reviews are separate processes run by different agents. PR summary A separate Summary agent reads the full diff and groups changes by functional capability, not by file. This gives you a fast, high-level view of what the PR accomplishes. The summary updates automatically whenever the PR changes (for example, when new commits are pushed), and it runs independently of reviews. Findings When you run a review, the Review agent analyzes the diff for issues and emits structured findings. Each finding includes a title and rationale, category, severity, and code location (file path plus line number).

​
Finding categories

CategoryWhat it covers
BugLogic errors, incorrect behavior, crashes
RiskSecurity issues, race conditions, data loss potential
MaintainabilityCode clarity, naming, documentation gaps
RefactorStructural improvements, duplication, pattern violations

​
Severity levels

SeverityMeaning
CriticalMust fix before merging - security holes, data corruption
HighLikely to cause problems in production
MediumShould address - maintainability or correctness concerns
LowStyle, minor improvements, nice-to-haves

​
GitHub comments

Findings with medium severity or higher are posted as inline review comments on GitHub, attached to the relevant lines in the PR. Low severity findings stay in Capy’s dashboard only, so GitHub threads stay focused on higher-impact issues. Re-reviews do not flag the same issue twice. If a finding was already reported, Capy skips it. When a finding is marked resolved or irrelevant, Capy automatically resolves the corresponding GitHub review thread.

​
Triage and resolution

Each finding has a triage status.
StatusMeaning
OpenActive issue that needs attention
ResolvedThe issue has been fixed
IrrelevantFalse positive or not applicable
When Captain is managing the task, it triages automatically after review, marking false positives as irrelevant, confirming already-fixed issues as resolved, and sending real issues to the Build agent for fixing. You can override any triage decision. If Captain marks a finding as irrelevant but you disagree, you can reopen it. You can also triage findings manually from the Capy dashboard without Captain.

​
Re-reviews

Re-reviews are incremental. Previously irrelevant findings are skipped. Resolved findings are re-checked and only re-flagged if the issue persists. Open findings are re-flagged only when the referenced code changed, and new issues in new or modified code are flagged normally.

​
Custom review instructions

Create a .capy/REVIEW.md file in your repository to customize how reviews work. This is the Review agent’s equivalent of BUILD.md - it only reads this file. 
# Review Instructions

## Do not flag

- Snapshot ID changes are normal workflow
- Intentional fallback patterns are backward compat
- Defensive defaults are project convention

## Severity

- Only flag medium+ for user-facing bugs
- Style/preference issues should be low priority

## Focus areas

- Always check for SQL injection in new queries
- Flag any direct database access outside the repository layer
Changes to REVIEW.md take effect on the next review. If .capy/REVIEW.md is not found, the Review agent falls back to AGENTS.md (or CLAUDE.md) at the repository root.