Skip to content

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.

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
  1. 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).
  2. 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.
  3. 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.
  4. 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).
  5. One verdict. Submit review… sends the agent your decision, your message and every open comment at once.
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.

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:

  1. Tells you it takes a few minutes, and prepares the guide without showing it, as an explanation: no findings, no verdict.
  2. 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.
  3. 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.
  4. 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).
  5. 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.

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.

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.

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:

  1. Prepares the review with open_review({ diff, title, open: false }). Co-Review runs the git diff itself (so no output filtering or pager can garble it) and includes new, untracked files for uncommitted work.
  2. 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.
  3. 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.

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:

  1. Reads the pull request (gh pr view), fetches its branch, and writes a review directory outside the repository with a PR.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.
  2. 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.
  3. Reads the changed code in context and adds at most five proposed findings where it matters.
  4. 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.

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:

  1. Investigates the code and writes design/<name>/index.markdown in the design-document format.
  2. Checks it with open_review({ dir, open: false }) and fixes every format warning Co-Review reports, so you never see a malformed document.
  3. Shows it and shares the link.
  4. Revises the document from your comments, keeping commented steps’ wording stable so your threads stay anchored.
  5. 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-reviewer subagent.
  • 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).