Review Mirror

A VSCode extension for the human-reviews / agents-edit workflow: review changes an AI coding agent made to your branch in a GitHub-PR-style split diff, leave line comments the agent picks up from a file in the repo, and see inline git blame — all without leaving your editor.

Features

• Changed Files panel (activity bar → Review Mirror): every file changed between merge-base(HEAD, baseBranch) and the working tree — committed, staged, unstaged, and untracked.
• Split diff: click a file to open old vs new side by side. The view is read-only — changes are made by agents, not by hand.
• Full LSP on the new side: the right side is the real file, so cmd+click / go-to-definition / hover work with whatever language extensions you have installed.
• Line feedback: click the + gutter on any line in the diff, then choose Comment for a read-only answer or Request Changes when the agent may edit the code. Feedback is stored in .review/comments.json for agents to read; agent replies appear in-thread automatically. Threads can be resolved, and they re-anchor when the code moves (or get marked stale when the commented code disappears).
• Inline blame at the end of each line on the new side (author, age, commit summary). Hover for details and a link to the full commit. (A hook exists for "open the PR that made this change" — see CommitLinkProvider in src/blame/blameController.ts.)
• Cmd+R / Ctrl+R refreshes the review (scoped to the review diff and Changed Files view only).

Settings

The agent contract: .review/comments.json

Reviewer comments are written to this file. Point your agent (e.g. Claude Code) at it — a good standing instruction is:

Read .review/comments.json. For each open thread whose latest comment is from a human, follow its intent: answer comment threads without modifying code; for requestChanges, edit when the request is clear, or reply with a clarification question without editing. Append agent replies and resolve only answered or completed threads.

Shape:

{
  "version": 1,
  "baseBranch": "main",
  "mergeBase": "<sha of merge-base at last write>",
  "threads": [
    {
      "id": "uuid",
      "intent": "requestChanges",          // "comment" | "requestChanges"
      "file": "src/server/auth.ts",        // repo-relative posix path
      "side": "new",                        // "new" = working tree, "old" = base version
      "range": { "startLine": 42, "endLine": 42 },   // 1-based, inclusive
      "status": "open",                     // "open" | "resolved" | "stale"
      "anchor": { /* managed by the extension — do not edit */ },
      "createdAt": "2026-07-07T18:22:31Z",
      "updatedAt": "2026-07-07T18:25:02Z",
      "comments": [
        {
          "id": "uuid",
          "author": { "name": "andrew", "kind": "human" },
          "body": "This swallows the original error — rethrow with cause.",
          "createdAt": "2026-07-07T18:22:31Z"
        },
        {
          "id": "uuid",
          "author": { "name": "claude-code", "kind": "agent" },
          "body": "Fixed: now wraps with `{ cause }`.",
          "createdAt": "2026-07-07T18:24:55Z"
        }
      ]
    }
  ]
}

Rules for agents:

• For intent: "comment", answer without modifying code. For intent: "requestChanges", code changes are allowed but not required when clarification is needed. A missing intent on an older thread means "requestChanges".
• Append to comments[] (fresh id, kind: "agent", ISO createdAt) and optionally set status to "resolved"; bump the thread's updatedAt.
• Never change existing ids, delete human comments, or edit anchor.
• Concurrent writes are safe: the extension merges by id on every save, so worst case nobody's comment is lost.

Development

npm install
npm run build        # bundle to dist/extension.js
npm run typecheck
npm test             # unit tests for parsers / anchoring / merge (node --test)

Press F5 in VSCode ("Run Extension") to launch an Extension Development Host, then open a git repo with a feature branch in the new window.