hunk-review

Source excerpt starting at line 1.

1---2name: hunk-review3description: Interacts with live Hunk diff review sessions via CLI. Inspects review focus, navigates files, hunks, and exact lines, reloads session contents, adds inline review comments, and paints attention marks on character ranges. Use when the user has a Hunk session running or wants to review diffs interactively.4---5 6# Hunk Review7 8Hunk is an interactive terminal diff viewer. The TUI is for the user -- do NOT run `hunk diff`, `hunk show`, or other interactive commands directly. Use `hunk session *` CLI commands to inspect and control live sessions through the local daemon.9 10If no session exists, ask the user to launch Hunk in their terminal first.11 12## Workflow13 14```text151. hunk session list                                    # find live sessions162. hunk session get --repo .                            # inspect path / repo / source173. hunk session review --repo . --json                  # inspect file/hunk structure first184. hunk session review --repo . --include-patch --json  # opt into raw diff text only when needed195. hunk session context --repo .                        # check current focus when needed206. hunk session navigate ...                            # move to the right place217. hunk session reload -- <command>                     # swap contents if needed228. hunk session comment add ...                         # leave one review note239. hunk session comment apply ...                       # apply many agent notes in one stdin batch2410. hunk session highlight add ...                      # light up the exact range you are explaining25```26 27## Session selection28 29Most session commands accept:30 31- `--repo <path>` -- match the live session by its current loaded repo root (most common)32- `<session-id>` -- match by exact ID (use when multiple sessions share a repo)33- If only one session exists, it auto-resolves34 35`reload` also supports:36 37- `--session-path <path>` -- match the live Hunk window by its current working directory38- `--source <path>` -- load the replacement `diff` / `show` command from a different directory39 40Use `--source` only for advanced reloads where the live session you want to control is not already associated with the checkout you want to load next. For a normal worktree session, prefer selecting it directly with `--repo /path/to/worktree`.41 42## Commands43 44### Inspect45 46```bash47hunk session list [--json]48hunk session get (<session-id> | --repo <path>) [--json]49hunk session context (<session-id> | --repo <path>) [--json]50hunk session review (<session-id> | --repo <path>) [--include-patch] [--include-notes] [--json]51```52 53- `get` shows the session `Path`, `Repo`, and `Source`, which helps when choosing between `--repo` and `--session-path`54- `Repo` is what `--repo` matches; `Path` is what `--session-path` matches55- `review --json` returns file and hunk structure by default; add `--include-patch` only when a caller truly needs raw unified diff text56- `review --include-notes` also returns the live review notes alongside the file and hunk structure57 58### Navigate59 60```bash61hunk session navigate (<session-id> | --repo <path>) --file <path> (--hunk <n> | --old-line <n> | --new-line <n>) [--json]62hunk session navigate (<session-id> | --repo <path>) --comment <id> [--json]63hunk session navigate (<session-id> | --repo <path>) (--next-comment | --prev-comment) [--json]64```65 66Absolute navigation requires `--file` and exactly one of `--hunk`, `--new-line`, or `--old-line`:67 68```bash69hunk session navigate --repo . --file src/App.tsx --hunk 270hunk session navigate --repo . --file src/App.tsx --new-line 37271hunk session navigate --repo . --file src/App.tsx --old-line 35572```73 74Exact comment navigation uses the `commentId` returned by `hunk session comment list --json` and does not require `--file`:75 76```bash77hunk session navigate --repo . --comment comment-178```79 80Relative comment navigation jumps between annotated hunks and does not require `--file`:81 82```bash83hunk session navigate --repo . --next-comment84hunk session navigate --repo . --prev-comment85```86 87- `--hunk <n>` is 1-based88- `--new-line` / `--old-line` are 1-based line numbers on that diff side89- A line target lands the user's viewport on that exact line (falling back to its hunk when the line is inside a collapsed region); `--hunk` lands on the hunk90- Use either `--next-comment` or `--prev-comment`, not both91 92### Reload93 94Swaps the live session's contents. Pass a Hunk review command after `--`:95 96```bash97hunk session reload (<session-id> | --repo <path> | --session-path <path>) [--source <path>] [--json] -- diff [ref] [-- <pathspec...>]98hunk session reload (<session-id> | --repo <path> | --session-path <path>) [--source <path>] [--json] -- show [ref] [-- <pathspec...>]99```100 101Examples:102 103```bash104hunk session reload --repo . -- diff105hunk session reload --repo . -- diff main...feature -- src/ui106hunk session reload --repo . -- show HEAD~1107hunk session reload --repo . -- show HEAD~1 -- README.md108hunk session reload --repo /path/to/worktree -- diff109hunk session reload --session-path /path/to/live-window --source /path/to/other-checkout -- diff110```111 112- Always include `--` before the nested Hunk command113- `--repo` or `<session-id>` usually selects the session you want114- `--source` is advanced: it does not select the session; it only changes where the replacement review command runs115- If the live session is already showing the target worktree, prefer `hunk session reload --repo /path/to/worktree -- diff`116- `--session-path` targets the live window when you need to keep session selection separate from reload source117 118### Comments119 120```bash121hunk session comment add (<session-id> | --repo <path>) (--reply-to <note-id> | --file <path> (--old-line <n> | --new-line <n>)) --summary <text> [--rationale <text>] [--author <name>] [--markup <stml>] [--focus] [--json]122hunk session comment apply (<session-id> | --repo <path>) --stdin [--focus] [--json]123hunk session comment list (<session-id> | --repo <path>) [--file <path>] [--type <live|all|ai|agent|user>] [--json]124hunk session comment rm (<session-id> | --repo <path>) <comment-id> [--json]125hunk session comment clear (<session-id> | --repo <path>) [--file <path>] [--include-user|--all] --yes [--json]126```127 128Examples:129 130```bash131hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording"132hunk session comment add --repo . --reply-to user:123 --summary "Addressed in the latest revision"133printf '%s\n' '{"comments":[{"filePath":"README.md","newLine":103,"summary":"Tighten this wording"}]}' | hunk session comment apply --repo . --stdin134```135 136- `comment list --type user` shows human-authored inline notes; without `--type`, `comment list` preserves the legacy live-agent-comment view137- `comment add` is best for one note; `comment apply` is best when an agent already has several notes ready138- Root `comment add` notes require `--file`, `--summary`, and exactly one of `--old-line` or `--new-line`; replies use `--reply-to <note-id>` with `--summary` and inherit the parent's anchor139- `comment apply` items require `summary` plus either `replyTo` by itself or `filePath` with exactly one target such as `hunk`, `hunkNumber`, `oldLine`, or `newLine`140- `comment apply` reads a JSON batch from stdin and validates the full batch before mutating the live session141- Pass `--focus` when you want to jump to the new note or the first note in a batch142- `comment list` and `comment clear` accept optional `--file`143- Quote `--summary` and `--rationale` defensively in the shell144 145### Attention marks146 147Highlights paint character ranges inside the diff lines the user is looking at — use them to light up the exact expression you are explaining while you narrate.148 149```bash150hunk session highlight add (<session-id> | --repo <path>) --file <path> (--old-line <n> | --new-line <n>) --start <n> --end <n> [--tone <tone>] [--focus] [--json]151hunk session highlight clear (<session-id> | --repo <path>) [--file <path>] [--json]152```153 154Examples:155 156```bash157hunk session highlight add --repo . --file src/App.tsx --new-line 42 --start 6 --end 19158hunk session highlight add --repo . --file src/App.tsx --new-line 42 --start 6 --end 19 --tone warning --focus159hunk session highlight clear --repo .160```161 162- `highlight add` requires `--file`, exactly one of `--old-line` or `--new-line`, and the `--start` / `--end` offsets163- `--start` is a 0-based inclusive offset into the line's text and `--end` is exclusive, counted in UTF-16 code units — the same `[start, end)` range extensions use164- Tones: `match` (default), `info`, `warning`, `error`, `dim`; `current` renders as reverse video and is best reserved for the one range under discussion165- Pass `--focus` to also land the viewport on the marked line166- Marks survive scrolling, navigation, and reloads that leave the marked file's content unchanged; a reload that changes that file drops its marks, and `highlight clear` removes them explicitly (optionally per `--file`)167- Marks are visual only — pair them with a `comment add` when the explanation should persist as a note168 169### Experimental rich markup notes (STML)170 171Only use STML when `hunk session context --json` lists `stml` in `experimentalFeatures`. The user opts into that experience by launching the review with `--experimental`; do not ask a normal session to render markup.172 173For an opted-in session, `--markup` (or a `markup` field on apply items) renders the note body as STML — a small HTML-like markup for terminal UI (boxes, rows, gauges, badges, lists, code). Keep `--summary` a real sentence: it is the fallback and the `comment list` text.174 175Before writing markup, run `hunk markup guide` once — it has copy-paste patterns and the width rules. The session context also reports `noteMarkupWidth` (the live render width); preview with `hunk markup render - --width <that>`. Comment responses echo `markupWidth` and return `markupNotes` when markup degraded — fix what they flag.176 177## New files in working-tree reviews178 179`hunk diff` includes untracked files by default. If the user wants tracked changes only, reload with `--exclude-untracked`:180 181```bash182hunk session reload --repo . -- diff --exclude-untracked183```184 185## Guiding a review186 187The user may ask you to walk them through a changeset or review code using Hunk. Start with `hunk session review --json` to understand the file/hunk structure without inflating agent context, then use `--include-patch` only for the files you truly need to read in raw diff form. Use `context` and `navigate` to line up the user's current view before adding comments.188 189Your role is to narrate: steer the user's view to what matters and leave comments that explain what they're looking at.190 191Typical flow:192 1931. Load the right content (`reload` if needed)1942. Navigate to the first interesting file / hunk1953. Add a comment explaining what's happening and why1964. If you already have several notes ready, prefer one `comment apply` batch over many separate shell invocations1975. Summarize when done198 199Guidelines:200 201- Work in the order that tells the clearest story, not necessarily file order202- Navigate before commenting so the user sees the code you're discussing203- Use `highlight add --focus` to steer the user's eyes to the exact expression while you explain it, and `highlight clear` before moving to the next topic204- Use `comment apply` for agent-generated batches and `comment add` for one-off notes205- Use `--focus` sparingly when the note itself should actively steer the review206- Keep comments focused: intent, structure, risks, or follow-ups207- Don't comment on every hunk -- highlight what the user wouldn't spot themselves208 209## Common errors210 211- **"No diff file matches ..."** -- the file is not in the loaded review. Check `context`, then `reload` if needed.212- **"No active Hunk sessions"** -- if Hunk is visibly running, localhost may be blocked by the agent sandbox; retry with network/sandbox escalation. Otherwise ask the user to open Hunk.213- **"Multiple active sessions match"** -- pass `<session-id>` explicitly.214- **"No active session matches session path ..."** -- for advanced split-path reloads, verify the live window `Path` via `hunk session get` or `list`, then use `--session-path`.215- **"Pass the replacement Hunk command after `--`"** -- include `--` before the nested `diff` / `show` command.216- **"Pass --stdin to read batch comments from stdin JSON."** -- `comment apply` only reads its batch payload from stdin.217- **"Specify exactly one navigation target"** -- pick one of `--hunk`, `--old-line`, or `--new-line`.218- **"Specify exactly one comment target"** -- pass `comment add` one of `--old-line` or `--new-line`.219- **"Specify exactly one highlight target"** -- pass `highlight add` one of `--old-line` or `--new-line`.220- **"Highlight --end must be greater than --start"** -- offsets are `[start, end)` UTF-16 code units into the line text; end is exclusive.221- **"Specify either --next-comment or --prev-comment, not both."** -- choose one comment-navigation direction.222- **"The session daemon is ..."** -- a `daemon-build-mismatch` (the `--json` error carries `daemon`, `cli`, `attachedSessions`, and `recommendedAction`). Tell the user which build is newer and how many windows are attached, then **ask** before running `hunk daemon restart --yes`; never restart unprompted. After the restart, windows that failed to register attach on their own, so re-run `hunk session list` instead of relaunching anything. When `recommendedAction` is `use-newer-hunk`, the daemon is the newer build: use that Hunk instead.223- **"Could not read the raw diff for ..."** -- the session reloaded or closed while `--include-patch` was reading it. Re-run `review`; drop `--include-patch` if you only need file and hunk structure.224