Hunk Review

hunk diff

hunk show

hunk session *

Workflow

1. hunk session list                    # find live sessions
2. hunk session context --repo .        # check current focus
3. hunk session navigate ...            # move to the right place
4. hunk session reload -- <command>     # swap contents if needed
5. hunk session comment add ...         # leave review notes

Session selection

list

• --repo <path>

  -- match by repo root (most common)

• <session-id>

  -- match by exact ID (use when multiple sessions share a repo)
• If only one session exists, it auto-resolves

Commands

Inspect

hunk session list [--json]
hunk session get (--repo . | <id>) [--json]
hunk session context (--repo . | <id>) [--json]

Navigate

--file

--hunk

--new-line

--old-line

hunk session navigate --repo . --file src/App.tsx --hunk 2
hunk session navigate --repo . --file src/App.tsx --new-line 372
hunk session navigate --repo . --file src/App.tsx --old-line 355

• --hunk <n>

  is 1-based

• --new-line

  /

  --old-line

  are 1-based line numbers on that diff side

Reload

--

hunk session reload --repo . -- diff
hunk session reload --repo . -- show HEAD~1
hunk session reload --repo . -- show HEAD~1 -- README.md

Comments

hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording" [--rationale "..."] [--author "agent"]
hunk session comment list --repo . [--file README.md]
hunk session comment rm --repo . <comment-id>
hunk session comment clear --repo . --yes [--file README.md]

• comment add

  requires

  --file

  ,

  --summary

  , and exactly one of

  --old-line

  or

  --new-line

• Quote

  --summary

  and

  --rationale

  defensively in the shell

New files in working-tree reviews

hunk diff

git add -N src/new-file.ts
hunk session reload --repo . -- diff

Guiding a review

1. Load the right content (

   reload

   if needed)
2. Navigate to the first interesting file/hunk
3. Add a comment explaining what's happening and why
4. Move to the next point of interest -- repeat
5. Summarize when done

• Work in the order that tells the clearest story, not necessarily file order
• Navigate before commenting so the user sees the code you're discussing
• Keep comments focused: intent, structure, risks, or follow-ups
• Don't comment on every hunk -- highlight what the user wouldn't spot themselves

Common errors

• "No visible diff file matches ..." -- file isn't in the loaded review. Check

  context

  , then

  reload

  if needed.
• "No active Hunk sessions" -- ask the user to open Hunk in their terminal.
• "Multiple active sessions match" -- pass

  <session-id>

  explicitly.
• "Specify exactly one navigation target" -- pick one of

  --hunk

  ,

  --old-line

  ,

  --new-line

  .