Code review

Optionalplugin: code-review

The code review plugin puts a reviewing agent’s comments in front of you before they reach a pull or merge request. You see the diff, with each proposed comment on the line it is about, and decide which ones are worth posting. Your notes improve the ones you keep and explain the ones you reject, so the agent’s next review is better than its last.

Click to enlarge

A finding accepted with a revision note, another rejected with its reason.

When to use it

• An AI reviewer on your pull requests, whose comments you want to filter before your team sees them.
• Replies to review threads, where the agent drafts answers to your colleagues’ comments.
• Suggested changes the agent wants to commit, reviewed as a diff first.

It works with any forge. The agent maps its pull or merge request into the payload, and the decision back out; the plugin itself knows nothing about GitHub or GitLab.

Install

The plugin comes with the app. Install it in Settings › Plugins, or from the command line:

pinrail plugins install code-review

What you see

• A file tree with a count of proposals per file, in the order the agent suggests reading them or by path.
• The diff, inline or side by side, with folding and a short summary of what changed in each file.
• Proposals on their lines, each with severity, markdown body, and suggestion blocks shown as the change they would make. Accept, reject, or add a note.
• Reply threads, with the whole conversation so far.
• Your own comments, from any line of the diff.
• A confirmation before hand-over when proposals are left undecided. They are not posted, and the agent is told they were left undecided.

The layout choices are saved as plugin settings, so they hold for your next review. Press ? for the keys.

To see it before any agent asks with it, send its sample: pinrail submit code-review --sample, or Send a sample in its details in Settings › Plugins.

Asking from your agent

AGENTS.md

## Before posting review comments

Never post review comments directly. Submit them to Pinrail with the
`code-review` plugin and wait for my decision:

1. Write the payload: the change, each file's unified diff (as `git diff`
   prints it), and one proposal per comment, anchored on `file` and `line`.
   Give each proposal a stable integer `id`.
2. Run: `pinrail submit code-review --title "<PR title>" --data review.json --wait`
3. Post only accepted proposals. Apply an accept note as a revision before
   posting. Never post undecided proposals.
4. Consider my line `comments` and address them in your next round.
5. Learn from rejection notes: don't make the same kind of comment again.
6. If the command exits 5, stop and post nothing.

What the agent sends

review.json

{
  "change": {
    "ref": "!42", "title": "Dedup tickets on save", "url": "https://gitlab.example/acme/api/-/merge_requests/42",
    "description": "markdown", "source": "fix/tickets", "target": "main"
  },
  "overview": { "summary": "What changed and why.", "concerns": "What this review focused on." },
  "files": [
    { "path": "lib/acme/tickets.ex", "status": "modified", "summary": "Dedups before insert",
      "rank": 1, "diff": "@@ -140,7 +140,9 @@\n …" }
  ],
  "proposals": [
    { "id": 18, "kind": "comment", "severity": "major", "title": "Reversing twice is a no-op with a cost",
      "body": "The second `Enum.reverse/1` undoes the first.\n\n```suggestion\n|> Enum.uniq_by(& &1.id)\n```",
      "file": "lib/acme/tickets.ex", "line": 149, "side": "new" }
  ]
}

• diff is one unified diff per file. rank sets the reading order.
• line counts on side, new by default. A proposal whose line is not in the diff shows under its file; one whose file is not in the diff shows in a section of its own.
• ```suggestion blocks in a body render as a proposed change.
• A kind: "reply" proposal carries its thread, so the conversation renders without the forge.

What comes back

{
  "decisions": [
    { "id": 18, "action": "accept" },
    { "id": 19, "action": "reject", "note": "out of scope for this change" }
  ],
  "comments": [ { "file": "lib/acme/tickets.ex", "line": 152, "side": "new", "body": "Add a test for this." } ],
  "undecided": [20]
}

Field	What the agent does with it
decisions	Posts accepted proposals, revised by their note. Drops rejected ones, and learns from the reason.
comments	Your own line comments, for the agent to assess and address.
undecided	Never posted.

Reference

The plugin’s manifest, and the schemas a payload and a decision are checked against, read from the plugin’s own files.

Manifestmanifest.jsonPayloadwhat the agent sendsDecisionwhat comes backSettingsSettings › Plugins

FieldsJSON

name	code-review
version	1.0.0
title	Code review
description	A change's diff with the comments a reviewer agent proposes to post, each accepted or rejected before anything is posted.
use_when	You reviewed a merge or pull request and want a person to approve each comment before it is posted to the forge.
shortcuts	JNext undecided proposal KPrevious undecided proposal JNext proposal KPrevious proposal AAccept the focused proposal XReject the focused proposal, with a reason CWrite a note to the agent on the focused finding VInline or side-by-side diff WWrap long lines or scroll sideways OSemantic or alphabetical file order EscClose dialogs and composers

A change under review: its diff, the reviewer agent's overview, and the comments it proposes to post. Forge-agnostic: the requester maps its merge/pull request in, and maps the decision back out.

• changeobjectrequired

  • refstringrequired

    the change's identifier as people write it: 42, !42, #42

  • titlestringrequired
  • urlstring
  • descriptionstring

    markdown

  • sourcestring

    source branch

  • targetstring

    target branch

• overviewobject

  • summarystring

    what the change does and why, markdown

  • concernsstring

    what the review focused on, markdown

• filesobject[]required

  • pathstringrequired
  • old_pathstring | null
  • statusenum

    "added" "deleted" "modified" "renamed" · default "modified"

  • summarystring

    a short summary of what changed in this file, in markdown; one line is best

  • rankinteger

    semantic reading order; omit for path order

  • diffstringrequired

    unified diff hunks for this file, as git diff prints them

• proposalsobject[]required

  • idintegerrequired

    the workflow's own id; never renumbered

  • kindenum

    "comment" "reply" · default "comment"

  • severityenum

    "blocker" "major" "minor" "nit" · default "minor"

  • titlestringrequired
  • bodystringrequired

    markdown; ```suggestion blocks render as a proposed change

  • filestring | null
  • lineinteger | null
  • sideenum

    which side of the diff line counts on

    "new" "old" · default "new"

  • resolvesboolean

    a reply that would resolve its thread

    default false

  • threadobject

    for replies: the conversation so far, so it renders without the forge

    • roundinteger
    • commentsobject[]required

      • authorstring
      • bodystringrequired
      • oursboolean

        default false

• decisionsobject[]required

  • idintegerrequired
  • actionenumrequired

    "accept" "reject"

  • notestring

    accept: revise the comment per this before posting; reject: the reason, a lesson for the agent

• commentsobject[]required

  the reviewer's own line comments; handed to the agent to assess, not posted verbatim

  • filestringrequired
  • lineintegerrequired
  • sideenumrequired

    "new" "old"

  • bodystringrequired

    at least 1 chars

• undecidedinteger[]required

  proposal ids left without a verdict; the requester must not post them

• diffstringDiff

  How a file's changes are laid out

  "inline" Inline · "split" Side by side · default "inline"

• wrapbooleanWrap long lines

  Long lines carry on underneath; off, a file scrolls sideways (inline diff only)

  default true

• orderstringFile order

  The order the agent suggests, or by path; a change without an order is by path

  "semantic" Semantic · "path" By path · default "semantic"

• findings_onlybooleanOnly files with findings

  Hide files the agent had nothing to say about

  default false

• tree_openbooleanFile tree open

  Start with the file tree beside the diff

  default true