/hunk-review

name: hunk-review
description: Interacts with live Hunk diff review sessions via CLI. Inspects review focus, navigates files and hunks, reloads session contents, and adds inline review comments. Use when the user has a Hunk session running or wants to review diffs interactively.

Hunk Review

Hunk 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.

If no session exists, ask the user to launch Hunk in their terminal first.

Workflow

1. hunk session list                                    # find live sessions
2. hunk session get --repo .                            # inspect path / repo / source
3. hunk session review --repo . --json                  # inspect file/hunk structure first
4. hunk session review --repo . --include-patch --json  # opt into raw diff text only when needed
5. hunk session context --repo .                        # check current focus when needed
6. hunk session navigate ...                            # move to the right place
7. hunk session reload -- <command>                     # swap contents if needed
8. hunk session comment add ...                         # leave one review note
9. hunk session comment apply ...                       # apply many agent notes in one stdin batch

Session selection

Most session commands accept:

• `--repo <path>` -- match the live session by its current loaded 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

`reload` also supports:

• `--session-path <path>` -- match the live Hunk window by its current working directory
• `--source <path>` -- load the replacement `diff` / `show` command from a different directory

Use `--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`.

Commands

Inspect

hunk session list [--json]
hunk session get (<session-id> | --repo <path>) [--json]
hunk session context (<session-id> | --repo <path>) [--json]
hunk session review (<session-id> | --repo <path>) [--include-patch] [--include-notes] [--json]

• `get` shows the session `Path`, `Repo`, and `Source`, which helps when choosing between `--repo` and `--session-path`
• `Repo` is what `--repo` matches; `Path` is what `--session-path` matches
• `review --json` returns file and hunk structure by default; add `--include-patch` only when a caller truly needs raw unified diff text
• `review --include-notes` also returns the live review notes alongside the file and hunk structure

Navigate

hunk session navigate (<session-id> | --repo <path>) --file <path> (--hunk <n> | --old-line <n> | --new-line <n>) [--json]
hunk session navigate (<session-id> | --repo <path>) (--next-comment | --prev-comment) [--json]

Absolute navigation requires `--file` and exactly one of `--hunk`, `--new-line`, or `--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

Relative comment navigation jumps between annotated hunks and does not require `--file`:

hunk session navigate --repo . --next-comment
hunk session navigate --repo . --prev-comment

• `--hunk <n>` is 1-based
• `--new-line` / `--old-line` are 1-based line numbers on that diff side
• Use either `--next-comment` or `--prev-comment`, not both

Reload

Swaps the live session's contents. Pass a Hunk review command after `--`:

hunk session reload (<session-id> | --repo <path> | --session-path <path>) [--source <path>] [--json] -- diff [ref] [-- <pathspec...>]
hunk session reload (<session-id> | --repo <path> | --session-path <path>) [--source <path>] [--json] -- show [ref] [-- <pathspec...>]

Examples:

hunk session reload --repo . -- diff
hunk session reload --repo . -- diff main...feature -- src/ui
hunk session reload --repo . -- show HEAD~1
hunk session reload --repo . -- show HEAD~1 -- README.md
hunk session reload --repo /path/to/worktree -- diff
hunk session reload --session-path /path/to/live-window --source /path/to/other-checkout -- diff

• Always include `--` before the nested Hunk command
• `--repo` or `<session-id>` usually selects the session you want
• `--source` is advanced: it does not select the session; it only changes where the replacement review command runs
• If the live session is already showing the target worktree, prefer `hunk session reload --repo /path/to/worktree -- diff`
• `--session-path` targets the live window when you need to keep session selection separate from reload source

Comments

hunk session comment add (<session-id> | --repo <path>) --file <path> (--old-line <n> | --new-line <n>) --summary <text> [--rationale <text>] [--author <name>] [--markup <stml>] [--focus] [--json]
hunk session comment apply (<session-id> | --repo <path>) --stdin [--focus] [--json]
hunk session comment list (<session-id> | --repo <path>) [--file <path>] [--type <live|all|ai|agent|user>] [--json]
hunk session comment rm (<session-id> | --repo <path>) <comment-id> [--json]
hunk session comment clear (<session-id> | --repo <path>) [--file <path>] [--include-user|--all] --yes [--json]

Examples:

hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording"
printf '%s\n' '{"comments":[{"filePath":"README.md","newLine":103,"summary":"Tighten this wording"}]}' | hunk session comment apply --repo . --stdin

• `comment list --type user` shows human-authored inline notes; without `--type`, `comment list` preserves the legacy