Review with Crit

Review and revise code changes or a plan using

crit

for inline comment review.

Step 1: Determine review mode

Choose what to review based on context:

1. User argument — if the user specified a file, review it with

   crit <file>

2. Recent plan — if you just wrote a plan, review that file with

   crit <plan-file>

3. Branch review — otherwise, run

   crit

   with no arguments. It auto-detects what to review: uncommitted changes, or all changes on the current branch vs the default branch. Works on clean branches too.

Don't ask for confirmation — just proceed with whichever mode applies.

Step 2: Launch crit and block until review completes

Run

crit

to open the review UI in the browser:

# For a specific file:
crit <plan-file>

# For git mode (no args):
crit

This starts the daemon if needed (or connects to an existing one), opens the browser, and blocks until the user clicks "Finish Review". Feedback is printed to stdout when it exits.

Tell the user: "Crit is open in your browser. Leave inline comments, then click Finish Review."

Do NOT proceed until

crit

completes. Do NOT ask the user to type anything. Do NOT read the review file early. Wait for crit to exit — that is how you know the human is done reviewing.

Step 3: Read the review output

When

crit

completes, its stdout output includes the path to the review file. Read that file.

The file contains structured JSON with comments per file and review-level comments:

{
  "review_comments": [
    { "id": "r_f1e2d3", "body": "Overall feedback", "resolved": false }
  ],
  "files": {
    "plan.md": {
      "comments": [
        { "id": "c_a1b2c3", "start_line": 5, "end_line": 10, "body": "Clarify this step", "quote": "specific words", "anchor": "The sessions table needs a complete rewrite...", "resolved": false },
        { "id": "c_d4e5f6", "body": "File needs restructuring", "resolved": false }
      ]
    }
  }
}

There are three types of comments:

review_comments

(general feedback,

r_

-prefixed IDs), file comments (in per-file

comments

array with no

start_line

/

end_line

), and line comments (with

start_line

/

end_line

). If a comment has lines, it's about those lines. If not, it's about the file as a whole.

Identify all comments where

"resolved": false

or where the

resolved

field is missing (missing means unresolved). If a comment has a

"quote"

field, it contains the specific text the reviewer selected — focus your changes on the quoted text rather than the entire line range. If a comment has an

"anchor"

field, use it to locate the current position of the content rather than trusting

start_line

/

end_line

which may be stale after edits. If

"drifted": true

, the original content was removed or heavily rewritten — the line numbers are approximate at best.

Step 4: Address each review comment

For each unresolved comment:

1. Understand what the comment asks for (clarification, change, addition, removal)
2. If a comment contains a suggestion block, apply that specific change
3. Revise the referenced file to address the feedback — this could be the plan file or any code file from the git diff
4. Reply to the comment with what you did:

   crit comment --reply-to <id> --author 'Codex' '<what you did>'

When addressing multiple comments, use

--json

to reply to them all in one call:

echo '[
  {"reply_to": "c_a1b2c3", "body": "Fixed"},
  {"reply_to": "c_d4e5f6", "body": "Refactored as suggested"}
]' | crit comment --json --author 'Codex'

Editing the plan file triggers Crit's live reload — the user sees changes in the browser immediately.

If there are zero review comments: inform the user no changes were requested and stop.

Step 5: Signal completion and start next round

Run the exact same

crit

command from Step 2 again. This is critical — if you launched

crit plan.md

in Step 2, you must run

crit plan.md

again here (not bare

crit

). The daemon is keyed by the arguments, so mismatched args will start a new daemon instead of reconnecting.

# Must match Step 2 exactly:
crit <same-args-as-step-2>

On subsequent calls,

crit

automatically signals round-complete first, then blocks again until the next "Finish Review" click.

Tell the user: "Changes applied. Review the diff in your browser and click Finish Review when ready."

Do NOT proceed until

crit

completes. When it does, go back to Step 3. If the user finishes with zero comments, the review is approved — stop the loop and proceed.

Sharing

If the user asks for a URL, a link, or to share the review, run:

crit share <file>

Always relay the full output to the user — copy the URL from the command output and include it directly in your response.

To remove a shared review:

crit unpublish