Review workflows
Co-Review does five jobs: one explains, four review. Pick the one that matches what you want to read, start it with one command, and the agent does the setup and a first pass before you see anything.
| You want to | Claude Code | Pi / Oh My Pi | What opens |
|---|---|---|---|
| Understand the whole repository | /co-review:understand [focus] |
/co-review-understand [focus] |
A guide to the repository on its overview page, no findings, no verdict |
| Review the whole repository | /co-review:audit [focus] |
/co-review-audit [focus] |
A short overview with findings by area |
| Your change | /co-review:review [base] |
/co-review-change [base] |
The diff, as a pull-request page |
| Someone else’s pull request | /co-review:pr <number> |
/co-review-pr <number> |
The pull request, with its description |
| A design, before the code | /co-review:design <task> |
/co-review-design <task> |
The design document, rendered |
In any other agent (Codex, Cursor, VS Code, …), ask in plain words, e.g. “Review this pull request with me in
Co-Review: #42”; the co-review skill (or the Co-Review MCP server’s instructions) has the same steps. Setup for
each agent: Connect your agent.
The shape of every review
Section titled “The shape of every review”sequenceDiagram participant You participant Agent participant CR as Co-Review You->>Agent: /co-review:… (or "review … with me") Agent->>CR: open_review({ …, open: false }) Note over CR: prepared, not shown Agent->>CR: first pass: add_findings (a design: fix format warnings) Agent->>CR: open_review({ reviewId }) CR-->>You: opens on the overview page (a design on its document) loop until you submit You->>CR: comment, ask, accept or dismiss a finding CR-->>Agent: your question (await_reviewer, or live in Claude Code) Agent->>CR: reply in the thread end You->>CR: Submit review: Approve / Request changes / Comment CR-->>Agent: the verdict, every open comment, accepted suggestions Agent->>You: acts on it- Prepared, not shown. The agent creates the review with
open: false. You don’t see a half-built review, and in the desktop app no window appears yet (an agent that connects starts Co-Review in the background). - First pass. The agent adds findings: the risks and non-obvious decisions it wants you to look at. They arrive proposed: you accept or dismiss each one.
- Shown.
open_review({ reviewId })opens the review with the Review panel: a browser tab, or the repository’s window in the desktop app (focused if it’s already open). A repository, diff or pull-request review opens on its overview page; a design on its document, with the findings inline. The agent tells you what it found. - Questions and answers. Comment anywhere, or reply to a finding: the agent answers in the same thread. In Claude
Code with the live channel, questions reach the session the moment
you ask; otherwise the agent picks them up from
await_reviewer(each thread shows whether it has; the agent next to the review’s scope in the panel shows whether it is listening; hover it). - One verdict. Submit review… sends the agent your decision, your message and every open comment at once.
In Co-Review, whatever you review
Section titled “In Co-Review, whatever you review”| To | Do |
|---|---|
| Keep or drop a proposed finding | ✓ Accept finding / ⊘ Dismiss finding on the thread (the panel’s Proposed tab lists them) |
| Ask about a finding | Reply in its thread; the agent answers there |
| Ask the agent about code | + in the gutter (drag for several lines), or select it and press Cmd+Alt+A (Ask Agent): asking is the default with an agent |
| Comment on code (feedback for your verdict) | Select it and press Cmd+Alt+M (Comment), or Comment instead in a question’s draft |
| Suggest an edit | In a comment on a patch line or document text, Suggest a change |
| Move between threads | Cmd+Alt+↓ / Cmd+Alt+↑, or click a thread in the panel |
| Finish | Submit review… in the panel: Approve, Request changes or Comment, with a message |
After you submit, the agent:
| Decision | The agent |
|---|---|
| Approve | Goes ahead (commits, merges, continues the plan) and mentions anything still open |
| Request changes | Addresses every open comment and applies your accepted suggestions (as new commits for a change; into the document for a design), replies in each thread with what changed, and waits for the next round |
| Comment | Answers your comments; changes nothing unless you asked |
The agent doesn’t edit files while you review unless you ask for it in a thread.
Understanding the whole repository
Section titled “Understanding the whole repository”For learning a codebase: one you’re new to, or one an agent built until it no longer felt like yours. It explains, it doesn’t review: understanding comes first, and the review comes much later. The goal is that afterwards you can, without the agent, say what it does and where things live, use the repository’s vocabulary, trace its main flows, recognise its patterns and naming, follow its house rules, and place a change and predict what it affects. Why it works this way: the proposal and ADR 0003.
Start: /co-review:understand (optionally a focus: /co-review:understand internal/billing). It takes the agent
a few minutes, and it says so first.
The agent:
- Tells you it takes a few minutes, and prepares the guide without showing it, as an explanation: no findings, no verdict.
- Reads the docs, CI, entry points and core types, and the repository’s facts: what Co-Review works out without a model (entry points, folder roles, load-bearing files, naming rules, repeated shapes, what changes together, recipes). With Graphify installed, it can also ask the code graph how parts connect.
- Covers everything the facts list: every entry point gets a flow (or is named as not traced), every mapped folder a row in the map, every naming rule and repeated shape an explanation.
- Writes the overview page as a guide in four chapters:
- Lay of the land: what it does and doesn’t, a C4 context diagram and, when there is more than one running part, a C4 container diagram, how to build, run, test and deploy it, and the map: every folder’s job and role, and what you can ignore.
- How it works: a glossary and a “cast of characters” for names that are easy to confuse; each core entity’s lifecycle and what it looks like on disk; one flow per entry point, as a sequence diagram with numbered stops in the code and what happens when it fails.
- Patterns, naming, and why: the shapes the code repeats, in its own terms (not textbook labels); how things are named and what the names signal; the design decisions.
- Making a change: where to look for common tasks; recipes for “add a new X”; the house rules and how each is enforced; what a change ripples into (the code most depends on, what changes together, the trust boundaries).
- Shows it and tells you the chapters.
Every claim links to the code it is about; what the agent couldn’t verify is marked inferred or unknown, and an unknown “why” is asked, not invented. The guide’s first line names the commit it was written for.
You: the guide opens on the overview page. Read it top to bottom, or start at any chapter.
Each chapter ends with a Check, a prediction such as “where would you add a new command?”: select it and comment
your answer, and the agent tells you how it matches the code. Ask anything in a comment on the page or on any line,
symbol, file or folder; when something in the guide is wrong, say so and the agent checks the code and fixes the
guide. Viewed (Cmd+Alt+V) marks a file as read, and Coverage shows how much of each area you’ve read.
There is nothing to submit: press Done when you’ve read enough.
Reviewing the whole repository
Section titled “Reviewing the whole repository”Once you know your way around, or before a release: the agent’s first pass at what is wrong, area by area. If you don’t know the repository yet, start with the guide.
Start: /co-review:audit (optionally a focus: /co-review:audit internal/billing).
The agent reads the same docs and facts, splits the repository into its areas, and writes a short overview (what it does, a C4 context diagram, the areas, and where it hurts: the load-bearing code, hotspots, what changes together, what’s untested, the trust boundaries). Then it adds its findings, at most three per area, labelled with the area, each proposed for you to keep or dismiss.
You: the review opens on the overview page, with the panel on Proposed. Accept or dismiss each finding (By area groups them); reply in a finding’s thread to ask the agent why. Then submit your verdict, and the agent acts on it.
The overview page
Section titled “The overview page”A repository, diff or pull-request review opens on one page that holds all of it, top to bottom: the pull request (its link, branches and description), the agent’s overview (what the change or repository does and why, how it works as a flow chart, what else it affects, where to start), the files the change touches with the lines added and removed, then every finding and comment grouped by area, each with its severity, whether it’s proposed, open or resolved, a link to the code, the code it’s about and the conversation so far. A repository review ends with the repository’s areas and how they connect. It’s a rendered document, so you read it like a report and comment on it like any page: select text and Comment (or Ask Agent). A comment there reaches the agent with the text you selected, so it knows which part you mean. The page keeps itself up to date as findings arrive or change; Overview in the Review panel (or Review: Open Review Overview) opens it again. A design opens on its document instead: that is its front page.
Your change
Section titled “Your change”For a change the agent made (or you made together), before it’s committed or merged. You read it as a pull request: only the diff, with line comments, suggested edits and one verdict.
Start: /co-review:review reviews the uncommitted work. With a base, /co-review:review main reviews the branch
against it (main...HEAD).
The agent:
- Prepares the review with
open_review({ diff, title, open: false }). Co-Review runs thegit diffitself (so no output filtering or pager can garble it) and includes new, untracked files for uncommitted work. - Adds at most five findings on the changed lines: real risks and decisions you’d want to know about, not a list of everything it changed.
- Shows the review and says, in a sentence, what to look at first.
You: the pull-request page lists each file’s changes; findings sit on their lines. Comment on a line (or drag for several), suggest an edit, and submit. With Request changes, the agent fixes every comment and applies the accepted suggestions as new commits (it doesn’t rewrite the diff you reviewed), then replies in each thread.
Someone else’s pull request
Section titled “Someone else’s pull request”For a pull request you didn’t write: a teammate’s, or an outside contribution. The agent takes the first pass; you decide what goes back to the author.
Start: /co-review:pr 42 (a number or a URL). The agent uses the GitHub CLI (gh); without it, it asks you for
the diff.
The agent:
- Reads the pull request (
gh pr view), fetches its branch, and writes a review directory outside the repository with aPR.md(title, number, URL, branch, base, commits and the description). The URL is what lets Co-Review post your review back to the pull request. - Prepares the review with
open_review({ dir, diff: "<base>...<branch>", patchName, title, open: false }): the diff becomes the pull-request page, with the description above it. - Reads the changed code in context and adds at most five proposed findings where it matters.
- Shows the review with a two-sentence summary: what the pull request does and its riskiest part.
You: triage the findings, add your own comments, ask the agent about anything (“does this break the old API?”), and submit. The agent doesn’t touch the pull request.
The code around the diff. The window opens on the pull request’s code, not just its diff: a git worktree of its
head under ~/.co-review/worktrees/ (it shares your clone’s objects and leaves your clone alone), removed when you
archive or delete the review. The change’s neighbourhood is checked out first, the rest follows in the background.
Nothing heavy runs until you reach for it:
- The explorer shows the change: the files it adds or changes are coloured, with their lines added and removed, and so are the folders holding them. A changed file opens as base and head side by side, with the review’s comments on the head side; a new file opens as the file, its added lines marked. For a pull request the explorer starts with Changed files only (a label in its title bar; click it to show all files, or the pull-request icon to narrow it again); your choice is remembered per review. Deleted files are on the pull-request page.
- A comment on a line of the diff is listed in the Review panel under its file (
path:line), and opens that file’s diff at the line, with the comment there. One on an old-side line or on a whole file opens on the pull-request page, which shows it; so do drafts, where they were written. - The agent’s proposed findings stay folded in the editor (a gutter icon; the panel’s Proposed list) until you open one; Go to Comment lists them too.
- On the diff page, a new-side line number opens the file there, and an old-side one the base version (read-only). Cmd/Ctrl-click a name to go to its definition; rest the pointer on it for its type and docs. Compare on a file shows base and head side by side.
- The overview page adds a Blast radius: the definitions the change touches, what depends on them, and a chart.
- A comment you write in the editor on a line of the diff is a comment on the diff (it’s on the pull-request page and posted to GitHub); anywhere else it’s a comment on the file. Threads on the diff show in the editor too.
A review of your own change works the same way, on your repository itself: what you review is the diff taken when the review opened, so editing files while you review doesn’t change it.
Post it to GitHub. When you submit, tick Also post to GitHub: owner/repo#42. Co-Review posts your review to
the pull request as one GitHub review, through the GitHub CLI (so gh auth login is the only setup):
| In Co-Review | On GitHub |
|---|---|
| Your decision (Approve / Request changes / Comment) | The review’s decision (on your own pull request GitHub only allows a comment; Co-Review posts it as one and says so) |
| Your message | The review’s summary |
| Open threads on diff lines (your comments, findings you accepted) | Line comments: your point only, not the discussion; a finding you kept and replied to is the finding followed by your reply (the agent can reword each in your voice when it posts, and you can edit each in the preview) |
| Suggested edits you accepted | GitHub suggestions the author can commit with one click |
| Comments on the pull request or its description | Listed in the summary |
| Agents’ replies, questions you asked an agent (Ask Agent), proposed findings you didn’t accept, resolved threads, the agent’s own questions | Not posted |
If a line has left the diff since (the author pushed), its comment goes into the summary instead of failing the post.
Before anything goes out, Co-Review shows you exactly what will be posted: the decision, the summary and each line
comment where it lands, word for word, and each part is editable: what you change there is what’s posted, and a line
comment you empty is left out. It posts only when you click Post to GitHub; cancel and the submit form stays open. The panel then links to the posted review. You can also post later with ⋯ → Post review to GitHub…
(it asks for the decision first), or ask the agent to (post_review_to_github): the same preview appears in a thread.
A design, before the code
Section titled “A design, before the code”For a change worth agreeing on first: a new component, data model, API, async flow or migration. You review the plan (an L1 · L2 · L3 tree of what → how → what can go wrong, with Mermaid diagrams), not the source.
Start: /co-review:design <what to build>.
The agent:
- Investigates the code and writes
design/<name>/index.markdownin the design-document format. - Checks it with
open_review({ dir, open: false })and fixes every format warning Co-Review reports, so you never see a malformed document. - Shows it and shares the link.
- Revises the document from your comments, keeping commented steps’ wording stable so your threads stay anchored.
- Implements only after you approve. If the code has to depart from the design, it updates the design and asks again.
You: switch levels with L1 · L2 · L3, comment on a step (the icon at its end), a diagram, a node or an edge,
or select text. Open questions are marked ?, risks ⚠. Approve lets the agent implement; Request changes
sends it back to revise.
- Desktop app or browser. Both work the same. In the desktop app, the window appears when the agent shows the review, and closes once you submit it (after posting to GitHub, if you chose to) or the agent’s session ends (when an agent started the app). In the browser, the agent gives you a link.
- Keep working while you review. In Claude Code, “keep answering my review while you fix the tests” hands the
review to the background
co-reviewersubagent. - Several reviews. The switcher at the top of the Review panel lists them; archive the ones you’re done with.
- Away from your desk. ⋯ → Open mobile view reads, replies and submits from a phone (over Tailscale).
- Without an agent. Every review can be started by hand from the Review panel (+), and ⋯ → Connect agent… brings in an agent for quick questions (Agents).