hunk_review_changes

Review a diff hunk-by-hunk in your browser, then hand the comments back to your AI coding agent.

Your agent groups a diff into pieces — each a hunk with a plain-language what/why — and launches a local web app. You read the highlighted hunks and comment on each at your own pace. No model tokens are spent while you review. Click Done and the agent picks up your comments and implements them.

Works with Claude Code, Codex, Cursor, and OpenCode.

CI

Installation

Install the gem:

gem install hunk_review_changes

Then install the companion skill into your agents:

hunk-review-changes install

It asks which agents to set up and installs the skill for each.

How it works

  1. You ask your agent to review a change — a branch, PR, commit, or your working tree.
  2. The skill resolves the target, groups it into hunks, and writes a bundle.json.
  3. It runs hunk-review-changes bundle.json, which opens the review UI in your browser.
  4. For each hunk you leave a comment, mark it Looks good, or Flag for discussion.
  5. You click Done. The app writes export.md and exits.
  6. Your agent reads the export and implements every requested change.

Usage

Serve a bundle:

hunk-review-changes bundle.json

Options:

hunk-review-changes bundle.json --port 4321   # bind a specific port
hunk-review-changes bundle.json --no-open      # do not open the browser

Install the skill for specific agents without the prompt:

hunk-review-changes install --agent claude,codex,cursor,opencode

The review UI

  • 120-column diffs with syntax highlighting, in Atkinson Hyperlegible fonts.
  • Word-level highlighting shows exactly what changed within a modified line.
  • Dark mode follows your operating system setting.
  • Keyboard navigation — j/k to move between hunks, c to comment, g to mark Looks good, ? for help.
  • Reviewed state — every hunk tracks whether you have seen it, so you know what is left.

Your review persists as you go, so closing the tab loses nothing. Re-running the same bundle resumes it.

Battle review

Every explanation on a hunk is written by the agent that wrote the change, so it argues its own case. Ask for a battle review and a second agent argues the other side.

Say "battle review this branch" (or "challenge these changes") instead of "review this branch". The skill runs one pass of Codex over the whole diff, asking it to make the strongest case for why each hunk should not be changed at all — or not this way. Each piece then shows two voices: the author's what/why, and the adversary's pushback marked nitpick, concern, or blocking. Where the adversary has nothing to say, it concedes, and the hunk says so in one line — so you always know it looked.

The pushback travels into export.md for the pieces you comment on, so the agent implementing your comment sees the argument against it too.

Battle review is opt-in and needs the Codex CLI installed. If Codex is missing or fails, you get the plain review and an explanation — it never blocks. Since the adversary has to be independent of the author, the mode is unavailable when Codex is the agent running the review.

The gem itself never calls Codex: your agent does the adversarial pass before launching, so no model tokens are spent while you read.

Skills marketplace

The skill lives in its own repo, hunk-review-changes-skills, a marketplace that serves every supported agent. hunk-review-changes install uses it: it calls the Claude Code plugin CLI, and copies the skill into the directory Codex, Cursor, and OpenCode scan.

Development

Get the dependencies:

bundle install

Run the tests and linter:

bundle exec rake

Rebuild the stylesheet after changing assets/tailwind.css or the fonts:

bundle exec rake css

Release a new version with:

bundle exec rake release

Contributing

Bug reports and pull requests are welcome on GitHub.

License

The gem is available as open source under the MIT License. The bundled Atkinson Hyperlegible fonts are licensed under the SIL Open Font License.