Hunk Herdr Review

hunk review inside herdr

The hunk TUI belongs to the user. Never launch it — no hunk diff, hunk show, hunk patch, no herdr plugin action invoke review. Opening or re-pointing a review is the user's decision, made from their own keybindings and command palette. Your job is to leave notes on the review they are already looking at, and to move their view only when they ask you to.

Everything below is hunk's own session CLI, addressed with --repo "$PWD". There is no herdr action to go through: herdr plugin action invoke accepts no arguments and no stdin, so a plugin action cannot be handed a note batch or a navigation target at all.

Resolve the binary once, at the start of the task

hunk is not on your PATH. It ships as a dependency of the jhochenbaum.hunkdiff plugin, inside that plugin's install directory. Assume any bare hunk ... command you write will fail with "command not found". Ask herdr where the plugin lives, and use that copy:

plugin_root="$(herdr plugin list --json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const p=(JSON.parse(s).result.plugins||[]).find(p=>p.plugin_id==="jhochenbaum.hunkdiff");process.stdout.write(p&&p.plugin_root||"")})')"
hunk="$plugin_root/node_modules/.bin/hunkdiff"
test -x "$hunk" || echo "jhochenbaum.hunkdiff is not installed; report your notes in your reply instead"

herdr plugin list --json answers {"result":{"plugins":[{...,"plugin_id":...,"plugin_root":...}]}}. Match on plugin_id, never on list position or on name — the list holds every installed plugin. Resolve $hunk once and reuse it; do not hardcode the path, which differs per install.

Address the right session, every time

"$hunk" session list --json
"$hunk" session get --repo "$PWD" --json

Pass --repo "$PWD" to every session command. Never rely on hunk auto-resolving a single session: the user may be reviewing several worktrees at once, and a note applied to the wrong session lands on somebody else's diff.

session list is the one command that succeeds with nothing open ({"sessions": []}). Every other session command exits non-zero when no session matches, which is the signal that the user has not opened this review yet.

Read the review before commenting on it

"$hunk" session review --repo "$PWD" --json
"$hunk" session review --repo "$PWD" --include-notes --json
"$hunk" session context --repo "$PWD" --json

review --json gives the file and hunk structure without inflating your context; add --include-patch only for files you truly need in raw diff form. --include-notes adds the notes already on the review. context reports what the user is currently looking at.

Leave notes

One batch, from stdin, is the normal case:

printf '%s' '{"comments":[
  {"filePath":"src/a.ts","newLine":42,"summary":"Guard the null case","rationale":"userId is optional here"},
  {"filePath":"src/b.ts","hunk":2,"summary":"This rename is the point of the change"}
]}' | "$hunk" session comment apply --repo "$PWD" --stdin --json

Each item needs filePath, summary, and exactly one of hunk (1-based hunk number), oldLine, or newLine. rationale and author are optional. hunk validates the whole batch before it mutates anything, so a bad item costs you nothing but a retry.

For a single note, comment add takes flags instead of stdin:

"$hunk" session comment add --repo "$PWD" --file src/a.ts --new-line 42 \
  --summary "Guard the null case" --rationale "userId is optional here" --json

comment add requires --file, --summary, and exactly one of --old-line / --new-line; omitting the target answers Specify exactly one comment target: --old-line <n> or --new-line <n>.

Add --focus only when the note itself should steer the user's view — it moves them, so the same restraint applies as to navigate below.

A note needs a live session. There is no offline queue: if comment apply reports no active session, the user has not opened the review yet. Say so and put your findings in your own reply — do not open a review yourself, and do not retry in a loop.