This is the full developer documentation for Hunk # Hunk documentation > Find the Hunk guide, workflow, configuration, or reference you need. Hunk is a terminal diff viewer for reviewing complete changesets and keeping agent rationale beside the code it explains. Use this page to jump directly to the guide or reference you need. ## New to Hunk? 1. [Install Hunk](/docs/start/install/). 2. Open your working tree with `hunk diff`. 3. Follow the [quick start](/docs/start/quick-start/) to learn the review stream and navigation model. ## Browse the docs [Start here](/docs/start/install/)Install Hunk, open your first review, and learn the keyboard and mouse controls. [Review workflows](/docs/workflows/working-trees-and-commits/)Review working trees, commits, files, patches, pager input, difftool pairs, and other VCS backends. [Working with agents](/docs/agents/review-with-an-agent/)Let an agent inspect a live review, navigate hunks, and leave inline comments and annotations. [Configure](/docs/configure/configuration/)Set layered preferences, choose themes, and control layout and display behavior. [Extend](/docs/extend/extensions/)Write TypeScript extensions that add file previews, themes, VCS backends, transforms, commands, and sidebars. [Reference](/docs/reference/cli/)Look up generated CLI and config references or embed Hunk's OpenTUI components. [Help](/docs/help/troubleshooting/)Troubleshoot startup and rendering, check platform support, or plan a docs deployment. ## Common tasks * [Review current work or a commit](/docs/workflows/working-trees-and-commits/) * [Configure Hunk as a Git pager or difftool](/docs/workflows/git-pager-and-difftool/) * [Review a live session with a coding agent](/docs/agents/review-with-an-agent/) * [Choose a theme and layout](/docs/configure/themes/) * [Remap a keyboard shortcut](/docs/configure/keybindings/) * [Build a custom file preview](/docs/extend/file-previews/) * [Look up a command](/docs/reference/cli/) * [Troubleshoot terminal behavior](/docs/help/troubleshooting/) # Install > Install Hunk with the install script, npm, Homebrew, mise, or Nix and verify the CLI. Hunk runs on macOS, Linux, and Windows. npm installs require Node.js 18 or newer; the install script, Homebrew, mise, and Nix installs are self-contained binaries. Git is recommended for the most common review workflows. ## Install script On macOS and Linux, the install script downloads the prebuilt binary for your machine: ```bash curl -fsSL https://hunk.dev/install.sh | sh hunk --version ``` It verifies the downloaded archive against the release's published `SHA256SUMS`, installs into `~/.hunk` (binary at `~/.hunk/bin/hunk`, bundled agent skills beside it), and adds `~/.hunk/bin` to `PATH` in your shell's startup file. Restart your shell afterwards. The script reads three settings: | Setting | Effect | | ----------------------------------------------- | ------------------------------------------------------------------------------------------- | | `HUNK_VERSION` | Install an exact release instead of the newest one. Also accepted as a positional argument. | | `HUNK_INSTALL_DIR` | Install the binary into this directory instead of `~/.hunk/bin`. | | `--no-modify-path` (or `HUNK_NO_MODIFY_PATH=1`) | Leave shell startup files alone. | ```bash curl -fsSL https://hunk.dev/install.sh | sh -s -- 0.19.0 curl -fsSL https://hunk.dev/install.sh | sh -s -- --no-modify-path curl -fsSL https://hunk.dev/install.sh | HUNK_VERSION=0.19.0 sh ``` `hunk update` refreshes a default install in place. An install redirected with `HUNK_INSTALL_DIR` cannot be auto-detected later (the variable is gone once your shell exits), so update one of those by re-running the script with the same `HUNK_INSTALL_DIR`; the installer prints a reminder at the end of a custom-directory install. Windows is not covered by the script; use npm there. ## npm Install the published `hunkdiff` package globally: ```bash npm install --global hunkdiff hunk --version ``` The package exposes both `hunk` and `hunkdiff`; the docs use `hunk`. ## Homebrew ```bash brew install hunk hunk --version ``` If you previously used the old `modem-dev/tap` formula, remove it before installing from Homebrew core: ```bash brew uninstall modem-dev/tap/hunk brew install hunk ``` ## mise [mise](https://mise.jdx.dev) knows Hunk by the short name `hunk` (alias `hunkdiff`) and installs the prebuilt binary on macOS, Linux, and Windows: ```bash mise use -g hunk hunk --version ``` On Windows, use mise 2026.8.6 or newer; earlier releases fail with `unsupported env: windows/amd64`. Hunk also ships as a default tool in [Omarchy](https://omarchy.org), which installs it through mise. ## Nix The repository exports a `default` package from `flake.nix`. From a clone of Hunk: ```bash nix build ./result/bin/hunk --version ``` See the repository's `nix/README.md` for Home Manager and development-shell details. ## Verify the install ```bash hunk --help ``` You should see `Usage: hunk [options]`. If the shell cannot find Hunk, ensure your global npm, Homebrew, mise, or `~/.hunk/bin` directory is on `PATH`, then open a new shell. ## Update Hunk `hunk update` replaces Hunk with the newest release, using the package manager that installed it: ```bash hunk update # install the newest release hunk update --check # report the installed and available versions hunk update 0.19.0 # install a specific npm release ``` npm installs (including `bun` and `pnpm` global installs), Homebrew installs, and install-script installs update in place; a curl install re-runs the install script with the target version. mise, Nix, and local source builds are owned by their own tooling, so Hunk prints the command that updates them — `mise up hunk`, your Nix configuration, or `bun run install:bin` — instead of updating itself. Pass `--method npm`, `--method brew`, or `--method curl` if Hunk detects the wrong one. Next, [review your first working tree](/docs/start/quick-start/). # Keyboard and mouse > Navigate, scroll, filter, and change Hunk's view without leaving the review. Press `?` at any time for Hunk's in-app shortcut reference. Menus and primary review actions are also mouse-selectable. ## Navigate the review | Keys | Action | | ------------------------- | ----------------------------------------------------- | | `↑` / `↓`, `k` / `j` | Scroll one row | | `Space` / `f`, `b` | Page down / up | | `Shift+Space` | Page up | | `d` / `u` | Half page down / up | | `[` / `]` | Previous / next hunk | | `,` / `.` | Previous / next file | | `{` / `}` | Previous / next annotated hunk | | `Home` / `End`, `g` / `G` | Start / end of review | | `←` / `→` | Scroll unwrapped code; hold Shift for faster movement | Hunk navigation stays review-wide: hunk and file shortcuts move through the same multi-file stream shown in the main pane. `↑` / `↓` and `k` / `j` move a highlighted current line, and the view scrolls only far enough to keep it visible. Paging or scrolling past it moves it to the nearest line still on screen, and `c` anchors a note on it. Pick the marker from the View menu, or set [`cursor_line`](/docs/configure/layout-and-display/): `number` marks only the line number, and `off` turns the marker off and lets `↑` / `↓` and `k` / `j` scroll the view one row at a time instead. ## Change the view | Key | Action | | --------------- | ------------------------------------------------ | | `0` / `1` / `2` | Auto / split / stack layout | | `s` | Toggle files pane | | `t` | Choose a theme | | `l` | Toggle line numbers | | `w` | Toggle line wrapping | | `m` | Toggle hunk metadata | | `M` | Toggle menu bar | | `z` | Toggle unchanged context for the selected hunk | | `a` | Toggle agent notes | | `e` | Open the selected file in `$EDITOR` | | `/` | Focus file filter | | `Tab` | Move focus between the file list and file filter | | `r` | Reload a reloadable input | | `F10` | Open menus | | `q` | Quit | Hunk may offer to save view changes on quit. Saving writes personal preferences globally unless the repository already has a `.hunk/config.toml`. ## Add a human note Press `c` on the selected hunk or use a visible add-note affordance with the mouse. While editing, app shortcuts are suspended so normal text entry works. Save with the note editor's displayed action or cancel with Escape. ## Mouse behavior * Click a sidebar file to jump to it in the review stream. * Click menus and dialog actions instead of their key equivalents. * Use the wheel or scrollbar to move through the review; hold Shift while scrolling to move horizontally through unwrapped code. * Select diff text for copy where the terminal supports it. ## Remap the defaults Every shortcut above is a named command you can move to different keys with a `[keybindings]` table in your user config. See [Keybindings](/docs/configure/keybindings/). Terminal mouse protocols vary; see [terminal compatibility](/docs/help/compatibility/) if clicks or selection do not behave as expected. # Quick start > Open a working tree or commit and learn Hunk's review-first mental model. Hunk presents every visible file in one review stream. The sidebar is an index into that stream, not a single-file mode. ## Review current work From a repository: ```bash hunk diff ``` This includes tracked changes and untracked files. Use `--exclude-untracked` when you intentionally want tracked changes only. Inside Hunk: 1. Press `]` to jump to the next hunk. 2. Press `.` to jump to the next file. 3. Press `1`, `2`, or `0` for split, stack, or responsive auto layout. 4. Press `q` to quit.  The sidebar indexes the same continuous stream shown in the main pane. Selecting a file jumps to it without hiding the rest of the changeset. ## Review a commit ```bash hunk show # latest commit hunk show HEAD~1 # an earlier commit ``` A target is a Git ref or, in Jujutsu and Sapling workspaces, a native revset. Add path filtering after `--`: ```bash hunk show HEAD~1 -- src/ui README.md ``` ## Keep the review fresh ```bash hunk diff --watch ``` Hunk reloads file- and Git-backed input while preserving the review experience. Watch mode is continuous; press `q` when finished. ## Bring in an agent Keep Hunk open, then in another terminal ask your coding agent to run `hunk skill path` and use the returned review skill. Continue with [Review with an agent](/docs/agents/review-with-an-agent/). # Changelog > Every Hunk release, newest first — features, fixes, and performance work in the terminal diff viewer. [RSS](https://hunk.dev/changelog/rss.xml) · [CHANGELOG.md](https://github.com/modem-dev/hunk/blob/main/CHANGELOG.md) ## [Hunk 0.20](/changelog/0.20/) Latest · August 25, 2026 · 1 release · 11 changes Hunk 0.20 adds a checksum-verified one-line installer and self-updates, launches a directory of 12 community extensions, and makes line-level reviewing faster and more precise. ## [Hunk 0.19](/changelog/0.19/) August 16, 2026 – August 24, 2026 · 2 releases · 39 changes Hunk 0.19.0 expands the extension platform, makes live agent guidance more precise, and keeps large reviews responsive. ## [Hunk 0.18](/changelog/0.18/) August 8, 2026 – August 14, 2026 · 3 releases · 52 changes Hunk 0.18.0 makes reviews more precise, customizable, and extensible—while improving performance and reliability across large repositories and diverse terminals. ## [Hunk 0.17](/changelog/0.17/) July 7, 2026 – July 28, 2026 · 8 releases · 26 changes Hunk 0.17 makes the review chrome configurable, adds an Agent menu for setting up the review skill, and smooths out scrolling, theming, and session reliability across platforms. ## [Hunk 0.16](/changelog/0.16/) June 19, 2026 · 1 release · 8 changes Hunk 0.16 rebuilds the built-in theme system around a single theme setting with a live selector, and lets custom themes inherit from any built-in theme. ## [Hunk 0.15](/changelog/0.15/) June 8, 2026 – June 13, 2026 · 4 releases · 23 changes Hunk 0.15 adds release benchmark gating, Sapling support, and a run of rendering performance work that keeps large reviews responsive on Windows and Unix alike. ## [Hunk 0.14](/changelog/0.14/) May 26, 2026 – June 1, 2026 · 2 releases · 20 changes Hunk 0.14 adds mouse-drag selection with clipboard copy, inline expansion of collapsed unchanged context, and the Catppuccin Latte and Mocha themes. ## [Hunk 0.13](/changelog/0.13/) May 18, 2026 – May 19, 2026 · 2 releases · 12 changes Hunk 0.13 adds human-authored inline notes saved with c, an e shortcut to open the selected file in $EDITOR, and g/G jump navigation. ## [Hunk 0.12](/changelog/0.12/) May 12, 2026 – May 14, 2026 · 2 releases · 15 changes Hunk 0.12 brings native Windows support, Homebrew release automation, terminal-aware light and dark theme detection, and row windowing for very large single-file reviews. ## [Hunk 0.11](/changelog/0.11/) May 9, 2026 – May 10, 2026 · 2 releases · 13 changes Hunk 0.11 adds Jujutsu support through vcs = "jj", a pager-mode sidebar file tree, and steadier cross-file hunk navigation. ## [Hunk 0.10](/changelog/0.10/) April 21, 2026 · 1 release · 7 changes Hunk 0.10 introduces hunk daemon serve as the standard session entrypoint, publishes reusable session-broker packages, and surfaces agent comment counts in the sidebar. ## [Hunk 0.9](/changelog/0.9/) April 8, 2026 – April 21, 2026 · 6 releases · 28 changes ## [Hunk 0.8](/changelog/0.8/) March 29, 2026 – March 30, 2026 · 2 releases · 11 changes ## [Hunk 0.7](/changelog/0.7/) March 25, 2026 · 1 release · 8 changes ## [Hunk 0.6](/changelog/0.6/) March 23, 2026 – March 24, 2026 · 2 releases · 11 changes ## [Hunk 0.5](/changelog/0.5/) March 22, 2026 – March 23, 2026 · 2 releases · 10 changes ## [Hunk 0.4](/changelog/0.4/) March 22, 2026 · 1 release · 2 changes ## [Hunk 0.3](/changelog/0.3/) March 22, 2026 · 1 release · 8 changes ## [Hunk 0.2](/changelog/0.2/) March 20, 2026 · 1 release · 1 change ## [Hunk 0.1](/changelog/0.1/) March 20, 2026 · 1 release · 7 changes # Hunk 0.1 > Release notes for Hunk 0.1: 1 release, March 20, 2026. March 20, 2026 · 1 release ```sh npm i -g hunkdiff@0.1.0 ``` Hunk 0.1 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Releases in this series []() ### 0.1.0 March 20, 2026 #### Added * Initial Hunk release with split and stack terminal diff views built around a single multi-file review stream. * Added git-style `diff` and `show` commands plus a general Git pager wrapper for drop-in review workflows. * Added persistent Hunk view preferences across sessions ([#7](https://github.com/modem-dev/hunk/pull/7)). * Added agent-note anchored review flows, responsive layouts, and display toggles for line numbers, wrapping, and hunk metadata. #### Changed * Simplified the review chrome around a menu bar, lighter borders, and diff-focused headers. * Improved startup and large-review performance with windowed diff sections and deferred syntax highlighting. #### Fixed * Stabilized diff repainting, active-hunk scrolling, syntax highlighting, pager stdin patch handling, and terminal cleanup on exit. *** [Newer: Hunk 0.2](/changelog/0.2/) · [All releases](/changelog/) # Hunk 0.10 > Hunk 0.10 introduces hunk daemon serve as the standard session entrypoint, publishes reusable session-broker packages, and surfaces agent comment counts… April 21, 2026 · 1 release Hunk 0.10 introduces `hunk daemon serve` as the standard session entrypoint, publishes reusable session-broker packages, and surfaces agent comment counts in the sidebar. ```sh npm i -g hunkdiff@0.10.0 ``` Hunk 0.10 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Related documentation * [Live session control](/docs/agents/live-session-control/) * [Working trees and commits](/docs/workflows/working-trees-and-commits/) ## Releases in this series []() ### 0.10.0 April 21, 2026 #### Added * Added agent comment counts in the sidebar so review-heavy files stand out at a glance. * Added `hunk daemon serve` as the standard daemon entrypoint and published reusable session-broker packages plus an OpenTUI diff component for integrators. #### Changed * Included untracked files when `hunk diff ` still compares against the live working tree, while keeping explicit revset diffs commit-to-commit only. #### Fixed * Enabled mouse scrolling in pager mode. * Balanced Pierre word-level highlights so split-view inline changes stay visible without overpowering the surrounding diff row. * Smoothed mouse-wheel review scrolling so small diffs stay precise while sustained wheel gestures still speed up. * Fixed Shift+mouse-wheel horizontal scrolling so it no longer leaks a one-line vertical scroll in some terminals. *** [Newer: Hunk 0.11](/changelog/0.11/) · [Older: Hunk 0.9](/changelog/0.9/) · [All releases](/changelog/) # Hunk 0.11 > Hunk 0.11 adds Jujutsu support through vcs = "jj", a pager-mode sidebar file tree, and steadier cross-file hunk navigation. May 9, 2026 – May 10, 2026 · 2 releases Hunk 0.11 adds Jujutsu support through `vcs = "jj"`, a pager-mode sidebar file tree, and steadier cross-file hunk navigation. ```sh npm i -g hunkdiff@0.11.1 ``` Hunk 0.11 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Related documentation * [Jujutsu and Sapling](/docs/workflows/jujutsu-and-sapling/) * [Git pager and difftool](/docs/workflows/git-pager-and-difftool/) ## Releases in this series []() ### 0.11.1 May 10, 2026 #### Changed * Auto-detect Jujutsu checkouts for `hunk diff` and `hunk show`, while keeping explicit `vcs` config overrides. #### Fixed * Fixed large tracked and untracked file handling so very large diffs render as skipped placeholders instead of slowing startup or overflowing the JavaScript call stack. * Fixed Git patch parsing for `diff.noprefix=true` input so Hunk restores parser-safe `a/` and `b/` prefixes without mangling real paths. * Fixed `hunk pager` parsing for Git diffs emitted with `diff.mnemonicPrefix=true` so file paths do not keep `i/`, `w/`, `c/`, `1/`, or `2/` side prefixes. * Fixed review scrolling so viewport updates are coalesced and no longer risk a render loop. * Fixed agent comment hunk ranges so context lines from hunk headers remain part of the target range. * Fixed untracked-file reviews in repositories with external diff tools configured by passing `--no-ext-diff`. * Fixed diff geometry for hunks with multiple agent notes so offscreen notes no longer skew scrolling measurements. []() ### 0.11.0 May 9, 2026 #### Added * Added `vcs = "jj"` support, enabling `hunk diff [revset]` and `hunk show [revset]`. * Added a pager-mode sidebar file tree that can be revealed with the existing `s` shortcut while keeping pager chrome hidden by default. #### Fixed * Fixed `git log -p` and multi-commit `git show -p` inputs so patch parsing ignores commit metadata instead of emitting Pierre parser warnings. * Fixed cross-file hunk navigation so near-boundary jumps keep the selected file pinned and backward jumps reveal the target hunk instead of the file top. * Fixed the View menu sidebar checkmark so it follows whether the responsive layout is actually rendering the sidebar. *** [Newer: Hunk 0.12](/changelog/0.12/) · [Older: Hunk 0.10](/changelog/0.10/) · [All releases](/changelog/) # Hunk 0.12 > Hunk 0.12 brings native Windows support, Homebrew release automation, terminal-aware light and dark theme detection, and row windowing for very large… May 12, 2026 – May 14, 2026 · 2 releases Hunk 0.12 brings native Windows support, Homebrew release automation, terminal-aware light and dark theme detection, and row windowing for very large single-file reviews. ```sh npm i -g hunkdiff@0.12.1 ``` Hunk 0.12 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Related documentation * [Install](/docs/start/install/) * [OpenTUI components](/docs/reference/opentui-components/) ## Releases in this series []() ### 0.12.1 May 14, 2026 #### Fixed * Included the bundled Hunk review skill in standalone prebuilt release archives so `hunk skill path` works after extracting a tarball or installing via Homebrew. []() ### 0.12.0 May 12, 2026 #### Added * Added Homebrew tap release automation and Homebrew-aware startup update notices. * Added lower-level `hunkdiff/opentui` primitives for embedding Hunk diff bodies, file headers, file navigation, and multi-file review streams in custom OpenTUI apps. * Added row windowing for large single-file reviews to keep huge diffs responsive. * Added Windows x64 prebuilt artifact publishing to the release workflow. * Added native Windows support in the README, contributor guide, and local build/install scripts. * Added Nix flake app outputs for `nix run`, a named `hunk` package output, and package validation. * Added automatic light/dark theme detection from the terminal background when `theme = "auto"` is enabled. #### Changed * Ported `build:npm`, `build:bin`, and `install:bin` from bash scripts to cross-platform Bun-runnable TypeScript so native Windows contributors no longer need Git Bash to build or install Hunk locally. #### Fixed * Fixed the prebuilt npm package so the `hunkdiff/opentui` export and bundled type declarations are included. * Fixed the npm package so `npx hunkdiff` and other package-name executable lookups resolve to the Hunk CLI. * Made `hunk pager` emit static highlighted diff output for captured pager contexts like LazyGit, and pass diff input through unchanged when stdout is non-interactive. * Fixed Ctrl-Z job-control suspend support so Hunk can suspend and resume cleanly from a terminal. * Fixed Windows compatibility issues across paths, packaging, and tests. * Fixed Ctrl-C in the live TUI so it exits through Hunk's full shutdown path instead of only destroying the renderer. *** [Newer: Hunk 0.13](/changelog/0.13/) · [Older: Hunk 0.11](/changelog/0.11/) · [All releases](/changelog/) # Hunk 0.13 > Hunk 0.13 adds human-authored inline notes saved with c, an e shortcut to open the selected file in $EDITOR, and g/G jump navigation. May 18, 2026 – May 19, 2026 · 2 releases Hunk 0.13 adds human-authored inline notes saved with `c`, an `e` shortcut to open the selected file in `$EDITOR`, and `g`/`G` jump navigation. ```sh npm i -g hunkdiff@0.13.1 ``` Hunk 0.13 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Related documentation * [Comments and annotations](/docs/agents/comments-and-annotations/) * [Keyboard and mouse](/docs/start/keyboard-and-mouse/) ## Releases in this series []() ### 0.13.1 May 19, 2026 #### Fixed * Hid the inline add-note affordance while scrolling and only show it after deliberate pointer movement, so it no longer flickers during review navigation. * Hardened the local session daemon against browser-originated requests by validating Host and Origin headers and requiring JSON content types for API posts. * Disabled the generic broker HTTP API by default so Hunk's supported session API is the only app-daemon command surface. * Bounded session daemon memory by capping HTTP request body and websocket message sizes and rejecting session registrations with oversized file, hunk, patch, comment, or note payloads. []() ### 0.13.0 May 18, 2026 #### Added * Added an `e` shortcut to open the selected diff file in `$EDITOR`. * Added `g` and `G` keyboard aliases for jump-to-top and jump-to-bottom review navigation. * Added session-persistent user-authored inline notes with `c` to draft/save notes. * Added `hunk session comment list --type ` so agents can read human-authored notes through the comment workflow. #### Changed * Clarified inline note draft actions by labeling buttons as `Save (^S)` and `Cancel (Esc)`. #### Fixed * Fixed draft note focus handling so app shortcuts resume after the note textarea blurs without discarding the draft. * Preserved the resolved auto theme across `--watch` refreshes instead of falling back to the default dark theme. * Fixed standalone release archive generation so staged npm package directories are not accidentally packaged as GitHub release assets. *** [Newer: Hunk 0.14](/changelog/0.14/) · [Older: Hunk 0.12](/changelog/0.12/) · [All releases](/changelog/) # Hunk 0.14 > Hunk 0.14 adds mouse-drag selection with clipboard copy, inline expansion of collapsed unchanged context, and the Catppuccin Latte and Mocha themes. May 26, 2026 – June 1, 2026 · 2 releases Hunk 0.14 adds mouse-drag selection with clipboard copy, inline expansion of collapsed unchanged context, and the Catppuccin Latte and Mocha themes. ```sh npm i -g hunkdiff@0.14.1 ``` Hunk 0.14 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Related documentation * [Keyboard and mouse](/docs/start/keyboard-and-mouse/) * [Themes](/docs/configure/themes/) ## Releases in this series []() ### 0.14.1 June 1, 2026 #### Added * Added local performance benchmarks for Hunk startup, loading, rendering, highlighting, navigation, memory, and optional competitor comparisons. #### Fixed * Fixed npm installs by pinning `@pierre/diffs` to the version Hunk is tested with instead of allowing the broken `1.2.6` release. []() ### 0.14.0 May 26, 2026 #### Added * Added Catppuccin Latte and Mocha as built-in themes. * Added mouse-drag text selection in diff views that copies selected rows to the system clipboard via OSC 52. A `View > Copy decorations` toggle (or `copy_decorations` config) controls whether the clipboard includes diff rails, gutters, and file headers or only the changed code. * Added inline expansion for collapsed unchanged file content. Click an unchanged-context row (`▾ N unchanged lines` when expandable, otherwise the static `··· N unchanged lines ···` form) or press `e` while a hunk is selected to reveal surrounding and trailing file lines without leaving the review. The affordance is shown only for input modes that have reachable source content (`hunk diff`, `show`, `stash show`, file-pair `diff` and `difftool`, untracked files); raw `hunk patch` input still renders as before. Failed and in-flight loads surface a one-line status ("Loading…", "Could not load N unchanged lines") on the gap row. Expanded context rows use the same syntax highlighting as the surrounding diff. * Surfaced the agent author name in inline notes and the matching agent popover so multi-agent reviews are readable at a glance, with a fallback title when an annotation has no author. #### Fixed * Preserved Git log ANSI colors when `hunk pager` falls back to a plain-text terminal pager for non-diff output. * Capped inline context expansion source reads so huge files cannot freeze or exhaust memory when expanding unchanged lines. * Hardened plain-text pager startup so `PAGER` and `HUNK_TEXT_PAGER` shell metacharacters are passed as arguments instead of being evaluated implicitly. * Hardened terminal rendering against control-sequence injection from diffs, file paths, notes, expanded context, copied selections, and pager fallback output. * Fixed custom theme configuration so Catppuccin Latte and Mocha can be used as base themes. * Fixed inline note draft shortcuts so copy chords such as Ctrl-C and Ctrl-Shift-C no longer trigger note actions. * Fixed split diff alignment for wide CJK and emoji characters by measuring rendered text in terminal cells. * Fixed Ctrl-S saving for inline notes when tmux sends CSI-u keyboard input. * Stabilized hover backgrounds on wrapped diff rows so add-note affordances do not shift row layout. * Restricted session reloads so daemon commands cannot read files outside the initial Hunk session root. * Fixed static pager output so captured pager hosts honor configured custom themes. * Made `hunk pager` pass non-diff text through in captured pager and dumb-terminal contexts instead of spawning `less`. * Fixed the `e` editor shortcut when Hunk is launched from a repo subdirectory. * Fixed VCS auto-detection so a Git repository nested under a parent Jujutsu workspace still uses Git mode by default. *** [Newer: Hunk 0.15](/changelog/0.15/) · [Older: Hunk 0.13](/changelog/0.13/) · [All releases](/changelog/) # Hunk 0.15 > Hunk 0.15 adds release benchmark gating, Sapling support, and a run of rendering performance work that keeps large reviews responsive on Windows and Unix… June 8, 2026 – June 13, 2026 · 4 releases Hunk 0.15 adds release benchmark gating, Sapling support, and a run of rendering performance work that keeps large reviews responsive on Windows and Unix alike. ```sh npm i -g hunkdiff@0.15.3 ``` Hunk 0.15 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Related documentation * [Jujutsu and Sapling](/docs/workflows/jujutsu-and-sapling/) * [Git pager and difftool](/docs/workflows/git-pager-and-difftool/) ## Releases in this series []() ### 0.15.3 June 13, 2026 #### Added * Added release benchmark snapshots and a release workflow gate that blocks publishing when committed benchmark results show material performance regressions, with auditable accepted-regression records for intentional release tradeoffs. #### Fixed * Fixed Windows launches from Cygwin, Git Bash, and WSL-style VCS paths by normalizing Unix-style repo roots before reusing them as subprocess working directories or filesystem roots. * Fixed release staging so benchmark comparison artifacts are not mistaken for platform binary artifacts. * Reduced hunk-navigation latency and memory growth on large reviews by keeping diff geometry memoized when the selected hunk changes. * Reduced scroll and hunk-navigation latency on large reviews by avoiding repeated separator measurement and preserving memoized offscreen/visible diff rows across viewport updates. * Reduced main diff pane rendering work on large reviews by virtualizing offscreen file sections behind exact-height spacers. * Reduced sidebar rendering work on many-file reviews by virtualizing offscreen file rows behind exact-height spacers. []() ### 0.15.2 June 13, 2026 #### Changed * Coalesced scroll-position React updates into a single per-frame read and shifted background syntax highlighting from microtasks to timers, so rapid wheel or held-arrow scrolling no longer produces visible jank from per-delta state updates or per-file highlight work starving input and render callbacks. #### Fixed * Honored `--transparent-bg` and `transparent_background` in static pager output, so captured pager hosts like LazyGit let translucent terminal backgrounds through on context lines, gutters, and hunk headers while added/removed rows keep their tinted backgrounds. * Kept menu dropdowns and the help dialog on the base theme in transparent-background mode so popups remain readable over translucent terminals. * Resolved `hunk session ... --repo ` selectors to the containing repo root before matching, so `--repo .` (and any path inside the tree) targets the live session from a subdirectory instead of reporting no match. []() ### 0.15.1 June 9, 2026 #### Fixed * Restored the `e` keyboard shortcut and menu hint for opening the selected file in `$EDITOR`. * Added timeouts to `hunk session *` daemon capability and API calls so unresponsive daemons fail instead of hanging indefinitely. * Updated OpenTUI so light and dark theme backgrounds render without the native renderer's color shift. * Prevented Git watch polling from taking optional index locks while discovering untracked files. []() ### 0.15.0 June 8, 2026 #### Added * Show the newly selected theme in the footer status bar when switching themes. * Added Catppuccin Frappé and Macchiato as built-in themes, completing the four official Catppuccin flavors. * Added a Zenburn built-in theme (`theme = "zenburn"`), a warm low-contrast dark palette inspired by Jani Nurminen's original Zenburn. It also works as a custom-theme `base`. * Added a `--transparent-bg` flag and `transparent_background` config option for translucent terminal setups. * Added Sapling VCS backend support for `hunk diff` and `hunk show`. #### Fixed * Preserved split diff alignment when horizontal scrolling starts inside a wide CJK or emoji character. * Made diff syntax highlighting follow the active theme: keyword, function, number, and variable token colors now resolve to the configured theme's palette (including custom themes) in both light and dark, instead of passing through Pierre's built-in syntax colors. * Expanded the diff window during rapid scrolling bursts so large reviews keep real rows mounted instead of falling back to blank placeholder regions. *** [Newer: Hunk 0.16](/changelog/0.16/) · [Older: Hunk 0.14](/changelog/0.14/) · [All releases](/changelog/) # Hunk 0.16 > Hunk 0.16 rebuilds the built-in theme system around a single theme setting with a live selector, and lets custom themes inherit from any built-in theme. June 19, 2026 · 1 release Hunk 0.16 rebuilds the built-in theme system around a single `theme` setting with a live selector, and lets custom themes inherit from any built-in theme. ```sh npm i -g hunkdiff@0.16.0 ``` Hunk 0.16 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Related documentation * [Themes](/docs/configure/themes/) ## Releases in this series []() ### 0.16.0 June 19, 2026 #### Minor Changes * Refresh Hunk's built-in theme system, default to `github-dark-default`, and simplify theme selection around one `theme` setting with `View -> Themes…` / `t` opening the selector. Custom themes can inherit from any built-in theme with `custom_theme.base` while keeping explicit syntax color overrides, and removed theme ids such as `graphite` and `paper` remain accepted as compatibility aliases. #### Patch Changes * Allow session comment cleanup commands to remove human `c` notes: `comment rm` accepts `user:*` note ids, and `comment clear --include-user`/`--all` clears user notes alongside live agent comments. * Adopt Changesets for release-note fragments so pull requests can avoid conflicting `CHANGELOG.md` edits. * Prevent standalone Hunk binaries from loading `bunfig.toml` files from the caller's working directory. * Improve React review-stream responsiveness by reducing offscreen file mounting work while preserving adjacent highlight prefetching. * Honor explicit split layout mode in static pager output for captured hosts like LazyGit. * Improve generated theme contrast checks for built-in themes, including diff rows, metadata, chrome, and fallback token colors. * Require an explicit click or keyboard action before previewing a theme from the theme selector, while keeping mouse-wheel navigation available inside the selector. *** [Newer: Hunk 0.17](/changelog/0.17/) · [Older: Hunk 0.15](/changelog/0.15/) · [All releases](/changelog/) # Hunk 0.17 > Hunk 0.17 makes the review chrome configurable, adds an Agent menu for setting up the review skill, and smooths out scrolling, theming, and session… July 7, 2026 – July 28, 2026 · 8 releases Hunk 0.17 makes the review chrome configurable, adds an Agent menu for setting up the review skill, and smooths out scrolling, theming, and session reliability across platforms. ```sh npm i -g hunkdiff@0.17.7 ``` Hunk 0.17 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Related documentation * [Layout and display](/docs/configure/layout-and-display/) * [Review with an agent](/docs/agents/review-with-an-agent/) * [Themes](/docs/configure/themes/) ## Releases in this series []() ### 0.17.7 July 28, 2026 #### Patch Changes * Fix session commands when the local daemon uses the IPv6 loopback address. * Fix Nix flake evaluation on Nixpkgs 26.11, which dropped `x86_64-darwin`. Hunk's flake no longer declares that system, and it now pins bun2nix's `systems` input to the same list so building the `aarch64-darwin` package never forces an Intel macOS Nixpkgs. The system list is exposed as a `systems` flake input for consumers that need to override it. []() ### 0.17.6 July 24, 2026 #### Patch Changes * Republish the 0.17.5 application changes as 0.17.6 so the GitHub release includes downloadable binaries for every supported platform. Application behavior is unchanged from 0.17.5. []() ### 0.17.5 July 24, 2026 #### Patch Changes * Avoid loading OpenTUI's embedded native library for headless commands. Help, version, session polling, daemon serving, markup rendering, and non-interactive pager paths now stay behind a lightweight CLI entrypoint, preventing Bun from leaking a native temp file for commands that never open the review UI. * Optimize terminal cell width measurement so diffs with CJK, emoji, and chrome-glyph runs render faster: single-scalar clusters now measure through a fast zero-width check plus the East Asian Width table instead of string-width's expensive emoji regexes, while multi-scalar clusters still defer to string-width for identical results. []() ### 0.17.4 July 23, 2026 #### Patch Changes * Restore OpenTUI's platform-default renderer threading to improve interactive startup on macOS. * Rapidly pressing Ctrl+S (or double-clicking Save) while saving a draft note no longer saves the same note twice, and saved note ids stay unique even within one millisecond. []() ### 0.17.3 July 19, 2026 #### Patch Changes * Extend static pager diff-row backgrounds to the edge of host panels such as Lazygit. * Wrap plain-text agent notes by terminal cells instead of UTF-16 code units, so CJK and emoji text wraps correctly instead of being truncated with silent content loss. Long unbroken words split on grapheme boundaries, so wide characters and surrogate pairs are never cut apart. []() ### 0.17.2 July 18, 2026 #### Patch Changes * Reject malformed and unsafe line and hunk numbers instead of accepting their numeric prefix. * Fix mouse-selection copy misalignment on lines with wide (CJK, emoji) characters: drag, double-click, and triple-click selections now convert terminal cell columns into string indices before slicing, so the copied text matches the selected cells exactly. File-header rows with wide-character filenames now copy with the same cell alignment, and invisible zero-width characters at a selection boundary round-trip through the clipboard. []() ### 0.17.1 July 15, 2026 #### Patch Changes * Prevent Windows crashes when scrolling to the end of a diff and suppress Yoga NaN warning spam in Apple Silicon npm installs by upgrading OpenTUI to 0.4.3. * Reduced retained memory for large reviews by lazily materializing cached geometry row plans only when copy selection needs them. * Fix global config discovery on Windows when `HOME` is unavailable. []() ### 0.17.0 July 7, 2026 #### Minor Changes * Add a configurable menu bar toggle so keyboard-driven reviews can reclaim one row of terminal space. * Add an `enableClaudeIntegration` home-manager option that links the packaged `hunk-review` skill into `~/.claude/skills`, so Nix users get the Claude Code review skill without manual setup. * Add an `enableJujutsuIntegration` home-manager option that sets hunk as the jujutsu pager and switches `ui.diff-formatter` to `:git` so jj emits diffs hunk can render. #### Patch Changes * Add an Agent menu dialog that shows and copies the Hunk review skill setup prompt. * Upgrade OpenTUI to 0.4.2 and Bun to 1.3.14 for renderer, input, and platform fixes. * Fix a transient bottom-edge scroll clamp: mounted diff sections now always render their agent-note rows, so the review stream's painted height matches its measured layout height and over-scrolling at the bottom can no longer snap short by the height of an offscreen note. * Highlight `.mts` and `.cts` files as TypeScript instead of plain text. * Stop treating Escape as a global quit shortcut; use `q` to quit while preserving Escape for dialogs and focused controls. * Keep live review sessions from being pruned after the machine wakes from sleep. * Avoid transient mixed-color frames when previewing or accepting themes from the theme selector. * Preserve added and removed diff row tints when transparent background mode is enabled in the interactive TUI. * Fix session daemon auto-launch on Windows: the compiled binary's virtual `B:\~BUN\...` entrypoint was mistaken for a script path and passed to the relaunched daemon as a bogus argument, so `hunk session` commands never found a live session. *** [Newer: Hunk 0.18](/changelog/0.18/) · [Older: Hunk 0.16](/changelog/0.16/) · [All releases](/changelog/) # Hunk 0.18 > Hunk 0.18.0 makes reviews more precise, customizable, and extensible—while improving performance and reliability across large repositories and diverse… August 8, 2026 – August 14, 2026 · 3 releases Hunk 0.18.0 makes reviews more precise, customizable, and extensible—while improving performance and reliability across large repositories and diverse terminals. ```sh npm i -g hunkdiff@0.18.2 ``` Hunk 0.18 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Highlights * **A full extension platform.** Install TypeScript extensions that add VCS backends, commands, sidebars, dialogs, interactive file views, themes, and workspace actions. * **Line-level review and commenting.** A visible cursor moves with `j`/`k`, and `c` adds a comment exactly where you are looking—even across large reviews and wrapped lines. * **Richer agent context.** Experimental STML notes can present structured, terminal-native explanations with preview tools and layout-aware feedback. * **Full reviews from pipelines.** Piped diffs now retain Hunk’s navigation, filtering, layouts, sidebars, and other review controls. * **A UI that follows your preferences.** Remappable shortcuts appear correctly in menus and help, view settings can be saved on quit, and tabs and syntax colors are configurable. * **Faster and more dependable reviews.** Watch mode uses less CPU, navigation retains less memory, Unicode filenames render correctly, narrow terminals stay readable, and saved state and session behavior are more resilient. ## Related documentation * [Extensions](/docs/extend/extensions/) * [Keyboard and mouse](/docs/start/keyboard-and-mouse/) * [Git pager and difftool](/docs/workflows/git-pager-and-difftool/) ## Releases in this series []() ### 0.18.2 August 14, 2026 #### Patch Changes * Fix `hunk diff` taking tens of seconds in repos with many untracked files by synthesizing untracked diffs in-process instead of spawning one `git diff --no-index` subprocess per file. ([#742](https://github.com/modem-dev/hunk/pull/742)) []() ### 0.18.1 August 11, 2026 #### Patch Changes * Fix malformed `@@` hunk headers so each side's line range and count are emitted correctly. * Keep the top menu bar inside the same one-column margin as the rest of the app instead of painting its background into the outer gutter. * Keep Git's colors in non-diff `hunk pager` output for captured pager hosts, so LazyGit's branch log renders in its normal per-branch palette instead of a single color. []() ### 0.18.0 August 8, 2026 #### Minor Changes * Let custom themes override exact Shiki/TextMate syntax scopes while keeping deprecated syntax-role colors compatible. ([#570](https://github.com/modem-dev/hunk/pull/570)) * Let extension commands navigate directly to visible files and hunks. ([#629](https://github.com/modem-dev/hunk/pull/629)) * Give extension commands a snapshot of the file and hunk the user is reviewing. ([#616](https://github.com/modem-dev/hunk/pull/616)) * Render tabs at four-column stops by default, with CLI and config overrides. ([#588](https://github.com/modem-dev/hunk/pull/588)) * Add experimental React/OpenTUI component rows to extension file views without giving up Hunk's review navigation and notes. ([#632](https://github.com/modem-dev/hunk/pull/632)) * Add a visible current-line cursor so `j`/`k` move line by line and `c` comments exactly where the cursor sits. ([#662](https://github.com/modem-dev/hunk/pull/662)) * Let extension commands open Hunk-native confirmation, selection, and text-input dialogs. ([#617](https://github.com/modem-dev/hunk/pull/617)) * Add extension UI lifecycle events, sidebar controls, and inter-extension events. ([#619](https://github.com/modem-dev/hunk/pull/619)) * Add experimental TypeScript extensions for custom themes, VCS backends, changeset transforms, lifecycle hooks, config, and notifications. ([#599](https://github.com/modem-dev/hunk/pull/599)) * Let interactive extension file views handle keys until Escape returns control to Hunk. ([#675](https://github.com/modem-dev/hunk/pull/675)) * Let stateful extension file views refresh their rendered layouts in place. ([#673](https://github.com/modem-dev/hunk/pull/673)) * Expose resolved user keybindings to extension sidebars so their controls honor remapping and unbinding. ([#615](https://github.com/modem-dev/hunk/pull/615)) * Add experimental rich STML agent notes with preview commands and live width feedback. ([#512](https://github.com/modem-dev/hunk/pull/512)) * Make menus and help reflect actual keybindings, and add an Extensions menu for contributed commands. ([#614](https://github.com/modem-dev/hunk/pull/614)) * Let extensions add commands and multiple sidebars, with configurable keybindings and safe conflict handling. ([#611](https://github.com/modem-dev/hunk/pull/611)) * Give piped pager reviews the same navigation, filtering, layout, and sidebar controls as regular reviews. ([#647](https://github.com/modem-dev/hunk/pull/647)) * Expose stable hunk summaries to extension events, sidebars, commands, and file views. ([#626](https://github.com/modem-dev/hunk/pull/626)) * Add an experimental extension file-view API and an optional rendered Markdown example. ([#632](https://github.com/modem-dev/hunk/pull/632)) * Offer to save changed themes and view preferences when quitting. ([#468](https://github.com/modem-dev/hunk/pull/468)) * Let extensions replace file navigation with custom React sidebars while safely falling back to Hunk's sidebar on errors. ([#609](https://github.com/modem-dev/hunk/pull/609)) * Let extension commands read reviewed files and write them back with user confirmation. ([#674](https://github.com/modem-dev/hunk/pull/674)) #### Patch Changes * Reduce Git polling and CPU use in watch mode while preserving reliable refreshes. ([#531](https://github.com/modem-dev/hunk/pull/531)) * Make repo-extension trust persist across symlinked and alternate path spellings. ([#599](https://github.com/modem-dev/hunk/pull/599)) * Show the changed-file count beside addition and deletion totals. ([#684](https://github.com/modem-dev/hunk/pull/684)) * Preserve syntax highlighting when visible hunks begin inside folded multiline constructs. ([#669](https://github.com/modem-dev/hunk/pull/669)) * Make remapped `ctrl+letter` shortcuts work when terminals send bare control characters. ([#675](https://github.com/modem-dev/hunk/pull/675)) * Discover `.tsx` and `.jsx` extension entries and clarify extension authoring guidance. ([#625](https://github.com/modem-dev/hunk/pull/625)) * Let folder extensions declare multiple entry points and dependencies in `package.json`. ([#606](https://github.com/modem-dev/hunk/pull/606)) * Keep current-line navigation responsive and memory-efficient in large reviews and long wrapped rows. ([#685](https://github.com/modem-dev/hunk/pull/685)) * Make extensions safer and more reliable across loading, reloads, themes, lifecycle handlers, and custom VCS detection. ([#599](https://github.com/modem-dev/hunk/pull/599)) * Load a directory passed as an extension from its `index` entry instead of treating every file as a separate extension. ([#606](https://github.com/modem-dev/hunk/pull/606)) * Keep file statistics visible and paths readable on narrow terminals. ([#668](https://github.com/modem-dev/hunk/pull/668)) * Prevent one keypress from triggering both a modal action and the focused review control. ([#649](https://github.com/modem-dev/hunk/pull/649)) * Require `--experimental` before rendering rich STML agent notes. ([#589](https://github.com/modem-dev/hunk/pull/589)) * Label repository-root files with `./` in the sidebar. ([#519](https://github.com/modem-dev/hunk/pull/519)) * Reduce watch-mode startup time on macOS and Windows with native recursive observation. ([#531](https://github.com/modem-dev/hunk/pull/531)) * Display tracked CJK and emoji filenames correctly throughout reviews and session APIs. ([#670](https://github.com/modem-dev/hunk/pull/670)) * Warn when deprecated custom syntax colors are translated to approximate Shiki scopes. ([#574](https://github.com/modem-dev/hunk/pull/574)) * Restart stale session daemons after upgrades so live comments keep working. ([#572](https://github.com/modem-dev/hunk/pull/572)) * Resolve a shell-quote denial-of-service vulnerability and keep direct-file watch refreshes responsive. ([#627](https://github.com/modem-dev/hunk/pull/627)) * Document the supported scrolling and selection-following contract for custom extension sidebars. ([#630](https://github.com/modem-dev/hunk/pull/630)) * Generate the bundled review skill from the CLI surface so commands, errors, and flags stay accurate. ([#596](https://github.com/modem-dev/hunk/pull/596)) * Avoid preparing inactive custom file views, reducing work and retained memory in normal diff reviews. ([#652](https://github.com/modem-dev/hunk/pull/652)) * Keep file navigation focused on the file it just selected, even on loaded machines. ([#655](https://github.com/modem-dev/hunk/pull/655)) * Keep one-line scrolling consistent after clicking inside the review stream. ([#645](https://github.com/modem-dev/hunk/pull/645)) * Write saved state atomically and preserve corrupt state files for recovery. ([#599](https://github.com/modem-dev/hunk/pull/599)) * Improve STML guidance for composing rich content inside Hunk's native note frame. ([#573](https://github.com/modem-dev/hunk/pull/573)) * Show Nix-specific update instructions for Nix installations. ([#598](https://github.com/modem-dev/hunk/pull/598)) *** [Newer: Hunk 0.19](/changelog/0.19/) · [Older: Hunk 0.17](/changelog/0.17/) · [All releases](/changelog/) # Hunk 0.19 > Hunk 0.19.0 expands the extension platform, makes live agent guidance more precise, and keeps large reviews responsive. August 16, 2026 – August 24, 2026 · 2 releases Hunk 0.19.0 expands the extension platform, makes live agent guidance more precise, and keeps large reviews responsive. ```sh npm i -g hunkdiff@0.19.1 ``` Hunk 0.19 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Highlights * **Install and build richer extensions.** Install shared extensions from Git, dock panes on every edge, add session-scoped keyboard modes and guided workflows, and use the bundled authoring skill to discover the public API. * **Point agents and reviewers at exact code.** Live sessions and extensions can highlight character ranges and navigate directly to a source line, while `$EDITOR` opens at the line currently under review. * **Stay responsive in large repositories.** Untracked-file diffs avoid per-file subprocesses, syntax caches follow the active review, generated files skip expensive highlighting, and experimental `--fast` highlighting can offload eligible large diffs to a worker. * **Control the workspace more precisely.** Configure sidebar visibility, keep files and extension panes independent, and use review keybindings consistently in selectors and extension modes. * **Verify and install releases confidently.** Release archives carry build provenance attestations, and mise installation is documented across macOS, Linux, and Windows. ## Related documentation * [Extensions](/docs/extend/extensions/) * [Live session control](/docs/agents/live-session-control/) * [Layout and display](/docs/configure/layout-and-display/) ## Releases in this series []() ### 0.19.1 August 24, 2026 #### Patch Changes * Stop installing Pierre dependencies for CLI-only npm users. * Restore executable permissions for platform binaries installed through npm. * Accelerate complex Unicode text width measurement in reviews. * Git's `color.moved` highlights are no longer lost when `wrap_lines` is on. * Build the x64 binaries for CPUs without AVX2, so Hunk no longer dies with an illegal instruction on pre-Haswell machines and conservative VM CPU models. []() ### 0.19.0 August 16, 2026 #### Minor Changes * Agents can now light up exact character ranges in a live review with `hunk session highlight add` / `clear` (five contrast-guaranteed tones, painted through the same pipeline as extension line highlights), and `hunk session navigate` line targets now land the viewport on the exact line instead of just its hunk. ([#728](https://github.com/modem-dev/hunk/pull/728)) * Ship an extension-authoring skill for coding agents and let `hunk skill path [name]` print any bundled skill. ([#697](https://github.com/modem-dev/hunk/pull/697)) * Open `$EDITOR` at the current line instead of the start of the selected hunk. ([#713](https://github.com/modem-dev/hunk/pull/713)) * Generalize extension sidebars into dockable panes on all four review edges. ([#710](https://github.com/modem-dev/hunk/pull/710)) * Add extension APIs for transient sessions and observing or navigating guided review workflows. ([#717](https://github.com/modem-dev/hunk/pull/717)) * Install shared extensions straight from git with `hunk extension install /[@ref]` (plus `list`, `update`, and `remove`), let extension manifests declare a minimum API version via `"hunk": {"apiVersion": N}`, and find community extensions under the `hunk-extension` GitHub topic. ([#712](https://github.com/modem-dev/hunk/pull/712)) * Extensions can mark character ranges inside diff lines with `hunk.registerLineHighlighter` (API v5): source-addressed, tone-based marks painted inside Hunk's own rendering with guaranteed contrast on every line kind, invalidated through `ctx.highlights.refresh`. ([#726](https://github.com/modem-dev/hunk/pull/726)) * Hunk now runs on OpenTUI 0.5, picking up its faster FFI layout reads and a fix for duplicate live frame timers. Embedders of `hunkdiff/opentui` need to move their `@opentui/core` and `@opentui/react` peer installs to `^0.5.1`. ([#749](https://github.com/modem-dev/hunk/pull/749)) * Let extensions invoke public Hunk review commands with atomic movement counts. ([#706](https://github.com/modem-dev/hunk/pull/706)) * Let every configured vertical review key move open selection dialogs, including the theme selector. * Extensions can jump the review to one exact source line with `ctx.navigation.revealLine(fileId, side, line)` (API v5), so a target deep inside a tall hunk lands near the top of the viewport instead of pages below its anchor. ([#727](https://github.com/modem-dev/hunk/pull/727)) * Let extensions activate visible session-scoped keyboard modes that route keys through Hunk's public semantic commands. ([#708](https://github.com/modem-dev/hunk/pull/708)) * Add configuration and CLI flags to control the sidebar in non-pager mode. ([#648](https://github.com/modem-dev/hunk/pull/648)) * Decouple bundled VCS providers from core, add provider-neutral repository bootstrapping, and let extension source readers report files that exceed their safe read limit. ([#711](https://github.com/modem-dev/hunk/pull/711)) #### Patch Changes * Publish GitHub build provenance attestations for the release archives so installs can be cryptographically verified. ([#714](https://github.com/modem-dev/hunk/pull/714)) * Make the theme picker scroll independently, preview themes after a brief hover, and apply them on click. ([#743](https://github.com/modem-dev/hunk/pull/743)) * Fix malformed `@@` hunk headers so each side's line range and count are emitted correctly. ([#695](https://github.com/modem-dev/hunk/pull/695)) * Start up faster for commands that never build a changeset. `hunk --version`, `--help`, `daemon serve`, the markup commands, and `hunk session *` no longer load the VCS, extension, and diff-engine graph before answering. ([#750](https://github.com/modem-dev/hunk/pull/750)) * Document installing Hunk with mise, and note that Hunk ships as a default Omarchy tool. ([#714](https://github.com/modem-dev/hunk/pull/714)) * Wrap draft review notes by terminal cells instead of scrolling horizontally, so long CJK notes stay fully visible while typing; previously the composer stayed one row high and hid everything before the cursor. ([#682](https://github.com/modem-dev/hunk/pull/682)) * Agent notes anchored to collapsed or expanded-away lines now render beside their owning hunk instead of the top of the file. ([#740](https://github.com/modem-dev/hunk/pull/740)) * Budget the syntax highlighting cache by lines instead of file count, so reviews of many small files stop re-highlighting as you scroll and reviews of very large files stay within a bounded memory footprint. ([#754](https://github.com/modem-dev/hunk/pull/754)) * Toggle the files pane without hiding independently controlled extension panes. ([#757](https://github.com/modem-dev/hunk/pull/757)) * Fix extension line highlights: marks now paint per file as they resolve instead of waiting for every file, never paint a previous review's offsets onto a reloaded file, stay visible on transparent line backgrounds, keep every active file's result retained however large the review is, and paint a row carrying thousands of ranges in milliseconds instead of seconds. Marks still resolve their tint against an assumed background on transparent cells, and a range covering only zero-width characters paints nothing. ([#733](https://github.com/modem-dev/hunk/pull/733)) * Keep syntax highlighting cached for the files you are actually reviewing, so scrolling back to a recent file no longer re-highlights it. ([#754](https://github.com/modem-dev/hunk/pull/754)) * Keep the top menu bar inside the same one-column margin as the rest of the app instead of painting its background into the outer gutter. ([#693](https://github.com/modem-dev/hunk/pull/693)) * Add an experimental `hunk --fast` mode that keeps eligible large syntax-highlighted diffs responsive with a Bun worker. ([#759](https://github.com/modem-dev/hunk/pull/759)) * Recognize mise-managed installs and skip the startup update notice for them, since mise already keeps Hunk up to date. ([#714](https://github.com/modem-dev/hunk/pull/714)) * Document that `mise use -g hunk` now installs Hunk on Windows with mise 2026.8.6 or newer. ([#777](https://github.com/modem-dev/hunk/pull/777)) * Improved diff alignment when a change block adds and removes different numbers of lines: the changed line now pairs with the line it actually resembles instead of whichever line happened to sit in the same position, so split view lines up correctly and the word-level highlight marks just the edited part instead of most of an unrelated line. ([#753](https://github.com/modem-dev/hunk/pull/753)) * Keep Git's colors in non-diff `hunk pager` output for captured pager hosts, so LazyGit's branch log renders in its normal per-branch palette instead of a single color. ([#703](https://github.com/modem-dev/hunk/pull/703)) * Render diffs larger than 10,000 lines as plain rows instead of syntax highlighting them, so a regenerated lockfile appears immediately and stops delaying color on the files around it. ([#754](https://github.com/modem-dev/hunk/pull/754)) * Fix `hunk diff` taking tens of seconds in repos with many untracked files by synthesizing untracked diffs in-process instead of spawning one `git diff --no-index` subprocess per file. ([#738](https://github.com/modem-dev/hunk/pull/738)) * Name the public files-pane command `hunk.view.toggleFilesPane`, preserve `hunk.view.toggleSidebar` as a compatibility alias, and require `hunk:files` when directly controlling the built-in pane. ([#760](https://github.com/modem-dev/hunk/pull/760)) *** [Newer: Hunk 0.20](/changelog/0.20/) · [Older: Hunk 0.18](/changelog/0.18/) · [All releases](/changelog/) # Hunk 0.2 > Release notes for Hunk 0.2: 1 release, March 20, 2026. March 20, 2026 · 1 release ```sh npm i -g hunkdiff@0.2.0 ``` Hunk 0.2 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Releases in this series []() ### 0.2.0 March 20, 2026 #### Fixed * Fixed npm installs by bundling Bun in published packages ([#11](https://github.com/modem-dev/hunk/pull/11)). *** [Newer: Hunk 0.3](/changelog/0.3/) · [Older: Hunk 0.1](/changelog/0.1/) · [All releases](/changelog/) # Hunk 0.20 > Hunk 0.20 adds a checksum-verified one-line installer and self-updates, launches a directory of 12 community extensions, and makes line-level reviewing… August 25, 2026 · 1 release Hunk 0.20 adds a checksum-verified one-line installer and self-updates, launches a directory of 12 community extensions, and makes line-level reviewing faster and more precise. ```sh npm i -g hunkdiff@0.20.0 brew update && brew upgrade hunk ``` This is the current release. See [all install options](/docs/start/install/). ## Related documentation * [Install](/docs/start/install/) * [Extensions](/docs/extend/extensions/) * [Extension API](/docs/extend/extension-api/) ## Releases in this series []() ### 0.20.0 August 25, 2026 #### Minor Changes * Add a curl installer (`curl -fsSL https://hunk.dev/install.sh | sh`) with checksum verification, and teach `hunk update` to update curl installs. ([#799](https://github.com/modem-dev/hunk/pull/799)) * Let extension commands inspect `ctx.selection.currentLine`; TypeScript authors constructing `ExtensionReviewSelection` must add its required field. ([#779](https://github.com/modem-dev/hunk/pull/779)) * Let extension commands capture immutable snapshots of stable review files and every saved review note. ([#833](https://github.com/modem-dev/hunk/pull/833)) * Add `hunk update` to self-update Hunk with the package manager that installed it (npm or Homebrew), with guidance for Nix, mise, and source installs. ([#788](https://github.com/modem-dev/hunk/pull/788)) #### Patch Changes * Keep the active code line fixed in place while an inline comment form pushes following content down. ([#809](https://github.com/modem-dev/hunk/pull/809)) * Keep `hunk --version`, `--help`, `daemon serve`, and `hunk session *` off the diff-engine startup path again, and release the syntax worker when the review app exits instead of at startup. ([#784](https://github.com/modem-dev/hunk/pull/784)) * Make `--fast` offload eligible syntax highlighting for files with 40 or more lines. ([#810](https://github.com/modem-dev/hunk/pull/810)) * Let mouse clicks reliably select exact code lines, including blank lines, for keyboard review actions. ([#840](https://github.com/modem-dev/hunk/pull/840)) * Fail clearly when an OpenTUI upgrade removes the shifted-wheel scroll reset Hunk requires. ([#786](https://github.com/modem-dev/hunk/pull/786)) * Reduce hunk navigation latency by avoiding unnecessary diff, sidebar, and syntax-highlighting work. ([#803](https://github.com/modem-dev/hunk/pull/803)) * Reuse worker-highlighted diffs after the terminal cache evicts them. ([#791](https://github.com/modem-dev/hunk/pull/791)) *** [Older: Hunk 0.19](/changelog/0.19/) · [All releases](/changelog/) # Hunk 0.3 > Release notes for Hunk 0.3: 1 release, March 22, 2026. March 22, 2026 · 1 release ```sh npm i -g hunkdiff@0.3.0 ``` Hunk 0.3 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Releases in this series []() ### 0.3.0 March 22, 2026 #### Added * Added prebuilt npm binary packaging and automated npm releases, including beta tag support ([#12](https://github.com/modem-dev/hunk/pull/12), [#14](https://github.com/modem-dev/hunk/pull/14), [#15](https://github.com/modem-dev/hunk/pull/15)). * Added a top-level `hunk --version` command ([#19](https://github.com/modem-dev/hunk/pull/19)). * Added the experimental MCP daemon for live Hunk sessions ([#22](https://github.com/modem-dev/hunk/pull/22)). #### Changed * Always showed the diff rail while dimming inactive hunks ([#16](https://github.com/modem-dev/hunk/pull/16)). * Decoupled sidebar visibility from layout toggles ([#18](https://github.com/modem-dev/hunk/pull/18)). * Stopped auto-saving view preferences to config files ([#13](https://github.com/modem-dev/hunk/pull/13)). #### Fixed * Used a supported Intel macOS runner for prebuilt release builds ([#17](https://github.com/modem-dev/hunk/pull/17)). * Preserved executable permissions for prebuilt binaries after installation. *** [Newer: Hunk 0.4](/changelog/0.4/) · [Older: Hunk 0.2](/changelog/0.2/) · [All releases](/changelog/) # Hunk 0.4 > Release notes for Hunk 0.4: 1 release, March 22, 2026. March 22, 2026 · 1 release ```sh npm i -g hunkdiff@0.4.0 ``` Hunk 0.4 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Releases in this series []() ### 0.4.0 March 22, 2026 #### Added * Auto-started the MCP daemon when needed for live sessions ([#29](https://github.com/modem-dev/hunk/pull/29)). * Added arrow-key line-by-line scrolling ([#30](https://github.com/modem-dev/hunk/pull/30)). *** [Newer: Hunk 0.5](/changelog/0.5/) · [Older: Hunk 0.3](/changelog/0.3/) · [All releases](/changelog/) # Hunk 0.5 > Release notes for Hunk 0.5: 2 releases, March 22, 2026 – March 23, 2026. March 22, 2026 – March 23, 2026 · 2 releases ```sh npm i -g hunkdiff@0.5.1 ``` Hunk 0.5 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Releases in this series []() ### 0.5.1 March 23, 2026 #### Fixed * Improved friendly Git command errors during CLI failures ([#75](https://github.com/modem-dev/hunk/pull/75)). []() ### 0.5.0 March 22, 2026 #### Added * Added inline agent notes across the review stream, including side-aware range guides ([#69](https://github.com/modem-dev/hunk/pull/69), [#62](https://github.com/modem-dev/hunk/pull/62)). * Added a session control CLI and a session reload command for live review workflows ([#50](https://github.com/modem-dev/hunk/pull/50), [#63](https://github.com/modem-dev/hunk/pull/63)). * Added live session comment lifecycle support and expanded the MCP tool surface ([#53](https://github.com/modem-dev/hunk/pull/53), [#39](https://github.com/modem-dev/hunk/pull/39)). * Added curated Hunk demo examples ([#34](https://github.com/modem-dev/hunk/pull/34)). #### Changed * Made Graphite the default theme ([#57](https://github.com/modem-dev/hunk/pull/57)). * Switched review rendering and scroll math to an explicit review row plan for more consistent navigation ([#64](https://github.com/modem-dev/hunk/pull/64), [#67](https://github.com/modem-dev/hunk/pull/67)). #### Fixed * Hardened MCP daemon lifecycle handling and kept the daemon loopback-only by default ([#36](https://github.com/modem-dev/hunk/pull/36), [#46](https://github.com/modem-dev/hunk/pull/46)). * Refreshed stale MCP daemons when using the session CLI ([#55](https://github.com/modem-dev/hunk/pull/55)). * Let the sidebar shortcut force the files pane open ([#56](https://github.com/modem-dev/hunk/pull/56)). *** [Newer: Hunk 0.6](/changelog/0.6/) · [Older: Hunk 0.4](/changelog/0.4/) · [All releases](/changelog/) # Hunk 0.6 > Release notes for Hunk 0.6: 2 releases, March 23, 2026 – March 24, 2026. March 23, 2026 – March 24, 2026 · 2 releases ```sh npm i -g hunkdiff@0.6.1 ``` Hunk 0.6 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Releases in this series []() ### 0.6.1 March 24, 2026 #### Added * Added watch mode for reloadable reviews ([#91](https://github.com/modem-dev/hunk/pull/91)). #### Changed * Fit menu dropdowns to their contents ([#92](https://github.com/modem-dev/hunk/pull/92)). #### Fixed * Shut down idle session daemons more reliably ([#96](https://github.com/modem-dev/hunk/pull/96)). * Coordinated singleton daemon launches to avoid duplicate background processes ([#97](https://github.com/modem-dev/hunk/pull/97)). * Exited the daemon process cleanly after shutdown ([#98](https://github.com/modem-dev/hunk/pull/98)). []() ### 0.6.0 March 23, 2026 #### Added * Added a reload shortcut for the current diff ([#83](https://github.com/modem-dev/hunk/pull/83)). #### Changed * Optimized large split review streams for faster rendering on big changesets ([#76](https://github.com/modem-dev/hunk/pull/76)). * Replaced footer hints with a keyboard help modal ([#88](https://github.com/modem-dev/hunk/pull/88)). #### Fixed * Restored daemon autostart for prebuilt npm binaries ([#84](https://github.com/modem-dev/hunk/pull/84)). * Detected `$bunfs` virtual paths correctly when autostarting daemons from Bun binaries ([#86](https://github.com/modem-dev/hunk/pull/86)). * Published prerelease tags to npm under the `beta` dist-tag ([#87](https://github.com/modem-dev/hunk/pull/87)). *** [Newer: Hunk 0.7](/changelog/0.7/) · [Older: Hunk 0.5](/changelog/0.5/) · [All releases](/changelog/) # Hunk 0.7 > Release notes for Hunk 0.7: 1 release, March 25, 2026. March 25, 2026 · 1 release ```sh npm i -g hunkdiff@0.7.0 ``` Hunk 0.7 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Releases in this series []() ### 0.7.0 March 25, 2026 #### Added * Grouped sidebar files by folder for easier navigation in large reviews ([#99](https://github.com/modem-dev/hunk/pull/99)). * Added `Ctrl+D`, `Ctrl+U`, and `Shift+Space` navigation shortcuts ([#102](https://github.com/modem-dev/hunk/pull/102)). * Added an auto-hiding vertical scrollbar to the diff pane ([#93](https://github.com/modem-dev/hunk/pull/93)). * Added Linux arm64 prebuilt package release support ([#107](https://github.com/modem-dev/hunk/pull/107)). #### Fixed * Prevented scroll snapback when using `Space`, `PageUp`, and `PageDown` ([#105](https://github.com/modem-dev/hunk/pull/105)). * Normalized Git patch prefixes for parser compatibility ([#106](https://github.com/modem-dev/hunk/pull/106)). * Kept selected hunks fully visible when they fit in the viewport ([#108](https://github.com/modem-dev/hunk/pull/108)). * Fixed wrap-toggle redraws while preserving the viewport anchor ([#110](https://github.com/modem-dev/hunk/pull/110)). *** [Newer: Hunk 0.8](/changelog/0.8/) · [Older: Hunk 0.6](/changelog/0.6/) · [All releases](/changelog/) # Hunk 0.8 > Release notes for Hunk 0.8: 2 releases, March 29, 2026 – March 30, 2026. March 29, 2026 – March 30, 2026 · 2 releases ```sh npm i -g hunkdiff@0.8.1 ``` Hunk 0.8 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Releases in this series []() ### 0.8.1 March 30, 2026 #### Fixed * Enabled `j` and `k` step scrolling in normal mode ([#131](https://github.com/modem-dev/hunk/pull/131)). * Aligned inline note rendering more cleanly beside diffs ([#137](https://github.com/modem-dev/hunk/pull/137)). []() ### 0.8.0 March 29, 2026 #### Added * Added file state indicators to the sidebar ([#128](https://github.com/modem-dev/hunk/pull/128)). * Added comment-to-comment navigation in review mode ([#126](https://github.com/modem-dev/hunk/pull/126)). * Included TTY and tmux pane metadata in session lists ([#90](https://github.com/modem-dev/hunk/pull/90)). * Added worktree-based session path targeting for session workflows ([#118](https://github.com/modem-dev/hunk/pull/118)). #### Changed * Included untracked files in working-tree diff reviews by default ([#123](https://github.com/modem-dev/hunk/pull/123)). * Surfaced a transient startup update notice ([#127](https://github.com/modem-dev/hunk/pull/127)). * Refined top-level CLI help text and files/filter focus copy ([#129](https://github.com/modem-dev/hunk/pull/129), [#121](https://github.com/modem-dev/hunk/pull/121)). #### Fixed * Fixed keyboard help dialog row overlap ([#122](https://github.com/modem-dev/hunk/pull/122)). * Fixed scrollbar click-drag behavior on large diffs ([#120](https://github.com/modem-dev/hunk/pull/120)). *** [Newer: Hunk 0.9](/changelog/0.9/) · [Older: Hunk 0.7](/changelog/0.7/) · [All releases](/changelog/) # Hunk 0.9 > Release notes for Hunk 0.9: 6 releases, April 8, 2026 – April 21, 2026. April 8, 2026 – April 21, 2026 · 6 releases ```sh npm i -g hunkdiff@0.9.5 ``` Hunk 0.9 is no longer the current release. See [the latest release](/changelog/) or [all install options](/docs/start/install/). ## Releases in this series []() ### 0.9.5 April 21, 2026 #### Added * Added a Modem sponsor block to the README. []() ### 0.9.4 April 14, 2026 #### Added * Added `hunk skill path` to print the bundled Hunk review skill path for direct loading or symlinking in coding agents. #### Changed * Show a one-time startup notice after version changes that points users with copied agent skills to `hunk skill path`. #### Fixed * Restored execute permissions for packaged prebuilt binaries so `npm install -g hunkdiff` works on root-owned installs without `spawnSync … EACCES` failures. []() ### 0.9.3 April 13, 2026 #### Fixed * Normalized rename-only diff paths so pure renames keep one clean `old/path -> new/path` header in the review UI ([#194](https://github.com/modem-dev/hunk/pull/194)). * Stripped Pierre's empty-line newline placeholder spans so blank additions and deletions keep stable line numbers and diff row backgrounds ([#201](https://github.com/modem-dev/hunk/pull/201)). []() ### 0.9.2 April 11, 2026 #### Fixed * Fixed a bottom-edge scrolling regression where short last files could snap back and make upward navigation feel stuck near the end of the review stream ([#196](https://github.com/modem-dev/hunk/pull/196)). []() ### 0.9.1 April 10, 2026 #### Fixed * Preserved viewport position when switching layouts ([#185](https://github.com/modem-dev/hunk/pull/185)). * Skipped binary file contents in reviews while keeping binary files visible in the review stream with a `Binary file skipped` placeholder ([#187](https://github.com/modem-dev/hunk/pull/187)). []() ### 0.9.0 April 8, 2026 #### Added * Added `hunk session review --json` for full live-session exports ([#160](https://github.com/modem-dev/hunk/pull/160)). * Added horizontal code-column scrolling in review mode ([#171](https://github.com/modem-dev/hunk/pull/171)). * Added batch apply support for live session comments in agent review flows ([#179](https://github.com/modem-dev/hunk/pull/179)). #### Changed * Pinned the current file header while scrolling the review pane ([#141](https://github.com/modem-dev/hunk/pull/141)). * Made session comment focus opt-in instead of forcing comment focus by default ([#163](https://github.com/modem-dev/hunk/pull/163)). * Synced active hunks to mouse scrolling and prefetched diff highlighting for smoother navigation ([#172](https://github.com/modem-dev/hunk/pull/172)). * Hid zero-value sidebar file stats to reduce visual noise ([#174](https://github.com/modem-dev/hunk/pull/174)). * Updated in-app controls help ([#175](https://github.com/modem-dev/hunk/pull/175)). * Sped up syntax-highlight row building in large diffs ([#177](https://github.com/modem-dev/hunk/pull/177)). #### Fixed * Reported the packaged version correctly in installed builds ([#153](https://github.com/modem-dev/hunk/pull/153)). * Fixed stale syntax highlights after reloads ([#146](https://github.com/modem-dev/hunk/pull/146)). * Fixed diff pane header popping while scrolling ([#159](https://github.com/modem-dev/hunk/pull/159)). * Avoided failures on untracked directory symlinks ([#169](https://github.com/modem-dev/hunk/pull/169)). * Aligned top-menu dropdowns correctly ([#176](https://github.com/modem-dev/hunk/pull/176)). * Restored live escape handling in PTY flows ([#173](https://github.com/modem-dev/hunk/pull/173)). * Kept viewport-follow selection from jumping unexpectedly ([#181](https://github.com/modem-dev/hunk/pull/181)). * Refreshed stale daemons after upgrades ([#178](https://github.com/modem-dev/hunk/pull/178)). * Rejected incompatible live session registrations more clearly ([#180](https://github.com/modem-dev/hunk/pull/180)). * Versioned daemon compatibility separately from other MCP behavior ([#183](https://github.com/modem-dev/hunk/pull/183)). *** [Newer: Hunk 0.10](/changelog/0.10/) · [Older: Hunk 0.8](/changelog/0.8/) · [All releases](/changelog/) # Agent context and experimental STML notes > Load review rationale from a sidecar and opt into rich terminal-native note markup. Live session comments are the recommended workflow. A sidecar is useful when the annotations already exist before Hunk starts or need to travel with a patch. ## Load a JSON sidecar ```bash hunk diff --agent-context notes.json hunk patch change.patch --agent-context notes.json ``` The sidecar can set narrative file order and attach hunk-level annotations. Keep it concise: one changeset summary, short file summaries, and only rationale that improves the review. The visible UI prioritizes hunk notes rather than generic explainer cards. A compact example lives at `examples/3-agent-review-demo/agent-context.json` in the repository. ## Opt into STML STML is experimental rich markup for terminal note bodies. It is off by default: ```bash hunk --experimental diff --agent-context notes.json ``` The launch flag is the authority for that session; a reload cannot turn the capability on later. Plain `summary` text remains required as the fallback. Before sending markup, an agent should inspect support and width: ```bash hunk session context --repo . --json hunk markup guide hunk markup render - --width ``` Only send `--markup` when `experimentalFeatures` includes `stml`. Keep colors symbolic and markup compact so notes retain a clear spatial relationship to their code. # Comments and annotations > Attach human or agent review notes to the code and navigate them in context. Notes are hunk-specific and render beside the rows they explain. Hunk intentionally keeps them in the review flow rather than in a separate comments screen. ## Add one agent comment ```bash hunk session comment add \ --repo . \ --file README.md \ --new-line 103 \ --summary "Tighten this wording" ``` Choose exactly one `--old-line` or `--new-line` target. Add `--focus` only when the new note should move the user's viewport. ## Apply a batch ```bash printf '%s\n' '{"comments":[{"filePath":"README.md","newLine":103,"summary":"Tighten this wording"}]}' \ | hunk session comment apply --repo . --stdin ``` Every item needs `filePath`, `summary`, and exactly one target: `hunk`, `hunkNumber`, `oldLine`, or `newLine`. Hunk validates the complete batch before changing the live session. ## Inspect and clean up ```bash hunk session comment list --repo . hunk session comment list --repo . --type all hunk session comment rm --repo . hunk session comment clear --repo . --file README.md --yes ``` Use `--all --yes` to clear both live agent comments and human notes. Destructive clears require confirmation. ## Add a human note In the TUI, select a hunk and press `c` or click an add-note affordance. Human and agent notes are labeled by source. Use `{` and `}` to move through annotated hunks across the review stream. # Live session control > Inspect, target, navigate, and reload Hunk windows through the local session broker. Each normal Hunk TUI registers with one loopback daemon. `hunk session ...` finds a registered window and sends it review actions. ## Find the session ```bash hunk session list hunk session get --repo . hunk session context --repo . ``` Use `--repo ` for normal worktrees. Use an explicit session ID when multiple windows share a repository. ## Inspect without overloading context ```bash hunk session review --repo . --json ``` This returns files and hunks. Add flags only when required: ```bash hunk session review --repo . --include-notes --json hunk session review --repo . --include-patch --json ``` ## Navigate the visible window ```bash 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 . --next-comment ``` Hunk numbers are 1-based. Absolute navigation needs a file and exactly one hunk, old-line, or new-line target. ## Reload the review Always place `--` before the nested Hunk command: ```bash hunk session reload --repo . -- diff hunk session reload --repo . -- show HEAD~1 -- README.md ``` Advanced reloads can target the live window by `--session-path` and load from a separate `--source` directory. Prefer `--repo` until those roles genuinely need to differ. ## Diagnose local access If a visible Hunk window does not appear in `session list`, an agent sandbox may block loopback access. Hunk's daemon is intentionally local-only; retry with the agent's network/sandbox permission rather than exposing it remotely. `hunk daemon serve` is available for manual startup or daemon debugging. # Hunk review skill > Load the versioned machine guidance that teaches coding agents Hunk's live review protocol. Hunk ships a generated `hunk-review` skill with every installation. It is the authoritative machine-facing workflow for session selection, efficient review inspection, navigation, reloads, and comments. ## Locate the installed skill ```bash hunk skill path ``` Load or symlink the returned file according to your coding agent's skill mechanism. Resolve the path again after upgrades so the guidance stays aligned with the installed CLI. For agents that need a stable web-readable URL, use the [generated Hunk review skill](/docs/hunk-review-skill.md). The published artifact and installed skill are rendered by the same function; neither is a handwritten copy. ## Why it is generated The checked-in `skills/hunk-review/SKILL.md` is rendered from typed command metadata and agent error definitions in Hunk's source. Parser help, examples, constraints, and common remedies therefore share ownership instead of drifting as separate handwritten copies. Do not edit the generated skill directly. Contributors change `src/hunk-review/skillDocument.ts`, `src/session/agent/surface.ts`, or `src/session/agent/errors.ts`, then run: ```bash bun run generate:skill ``` ## Use it safely The skill instructs agents to avoid launching interactive commands such as `hunk diff` themselves. The user owns the TUI; the agent talks to an already-live review through `hunk session *`. For the human workflow around that surface, start with [Review with an agent](/docs/agents/review-with-an-agent/). # Review with an agent > Let a coding agent inspect and guide a live Hunk review without giving up the human review UI. The Hunk window stays with you. Your agent uses non-interactive `hunk session` commands from another terminal to inspect the same review, navigate it, and leave inline notes. ## Start the review ```bash hunk diff ``` Keep that window open. Normal Hunk sessions register with a local loopback daemon so the session CLI can find them. ## Give the agent the skill In the agent's shell, locate the skill bundled with the installed Hunk version: ```bash hunk skill path ``` Ask the agent to load that file and use it for the review. A portable prompt is: ```text Load the Hunk skill and use it for this review. Run `hunk skill path` to get the skill path. ``` The skill tells agents not to launch the interactive TUI themselves. It teaches them to use the session surface instead. ## What the agent does A typical agent flow is: ```bash hunk session list hunk session get --repo . hunk session review --repo . --json hunk session navigate --repo . --file src/App.tsx --hunk 2 hunk session comment add --repo . --file src/App.tsx --new-line 42 --summary "Check this boundary" ``` `review --json` exposes structure without forcing the full patch into agent context. The agent should request `--include-patch` only when it actually needs raw unified diff text.  Agent notes remain spatially attached to the code they explain. Use `{` and `}` to move between annotated hunks while keeping the full changeset visible. ## Give the agent the docs These docs are published as plain Markdown so an agent can read them without scraping HTML: * [/llms.txt](https://hunk.dev/llms.txt) — index of every page, for pulling only what is needed. * [/llms-small.txt](https://hunk.dev/llms-small.txt) — compact corpus for tight context budgets. * [/llms-full.txt](https://hunk.dev/llms-full.txt) — the complete docs in one file, around 130KB. Any docs page URL also returns its Markdown source with `.md` appended, so `https://hunk.dev/docs/reference/cli.md` is the CLI reference as the agent should read it. ## Keep control The agent can guide the visible selection and add agent-authored notes, but you remain in the review stream and can navigate normally. Ask it to summarize when finished, then use `{` and `}` to walk annotated hunks. # Configuration > Layer user and repository TOML settings, then override them per command or from the CLI. Hunk reads TOML preferences from a user file and an optional repository file: * `~/.config/hunk/config.toml` (or the platform/XDG config location) * `.hunk/config.toml` at the repository root Repository settings override user settings. Command sections then override their layer's top-level values, pager sections apply to pager-style sessions, and explicit CLI flags win last. ## Start with useful defaults ```toml theme = "github-dark-default" mode = "auto" vcs = "git" watch = false exclude_untracked = false line_numbers = true tab_width = 4 wrap_lines = false hunk_headers = true menu_bar = true sidebar = "auto" agent_notes = false transparent_background = false ``` Use only the keys you want to change; built-in defaults fill the rest. ## Scope a command ```toml mode = "auto" [vcs] watch = true [pager] menu_bar = false wrap_lines = true ``` Command sections are named after the input Hunk parses, which is not always the command you type. In particular, `hunk diff` on a repository reads `[vcs]`, not `[diff]`: | Section | Applies to | | -------------- | ------------------------------------------------- | | `[vcs]` | `hunk diff` working-tree and target reviews | | `[show]` | `hunk show` commit reviews | | `[stash-show]` | `hunk stash show` reviews | | `[diff]` | two-file comparisons (`hunk diff `) | | `[patch]` | `hunk patch` reviews | | `[difftool]` | `hunk difftool` pair reviews | `[pager]` is an overlay applied after the matching command section whenever the invocation uses pager-style behavior. ## Save interactive changes When you change view preferences and quit, Hunk can offer to persist them. It writes to an existing repository config when one exists; otherwise it keeps personal view choices in the user config. Set `prompt_save_view_preferences = false` to disable that prompt. The [config reference](/docs/reference/config/) lists every key, default, and alias. The root-only `[extensions]` table has its own guide: [Extensions](/docs/extend/extensions/). # Keybindings > Remap Hunk's named commands to your own keys with the user-config keybindings table. Every keyboard shortcut is a named command. A `[keybindings]` table in your user config maps command ids to the chords you want them on: ```toml [keybindings] "hunk.app.quit" = "ctrl+x" # one chord "hunk.review.nextHunk" = ["]", "ctrl+n"] # several chords for one command "hunk.review.focusFilter" = "f" # takes "f" away from page-down "hunk.view.toggleMenuBar" = false # unbind it entirely "myext.toggle" = "ctrl+g" # extension commands too ``` Every id starts with the name of whoever owns the command: Hunk's own commands live under `hunk.`, and an extension's live under its extension id. `hunk` is a reserved extension id, so an extension can never shadow a built-in command. ## Rules * **User bindings replace defaults.** The chords you list are the complete set of keys that command answers to. * **A key you bind is yours.** Any command holding the same chord only as a default gives it up and keeps its other keys. * **`false` (or `[]`) unbinds a command**, leaving its keys doing nothing. * Two entries claiming one chord is a conflict: the first in the file wins and the session reports the other. Unknown ids and unusable chords are reported the same way, and the rest of the table still applies. ## Chord grammar Chords join `ctrl`, `alt`/`option`, `cmd`/`meta`, and `shift` with `+` around a base key: a character (`"y"`, `"["`), an uppercase letter for its shifted form (`"G"`), or a named key (`"tab"`, `"pageup"`, `"left"`, `"f2"`). For shifted symbols or digits, write the resulting character (`"!"`, not `"shift+1"`). `ctrl+` also matches an unnamed bare control byte; named Tab and Enter events stay distinct. ## Find command ids The menus and the in-app help (`?`) show the keys for the commands they present, so a remap changes what they advertise. The full table of built-in command ids and their default keys lives in [`docs/keybindings.md`](https://github.com/modem-dev/hunk/blob/main/docs/keybindings.md) in the repository. Commands listed without a default key remain callable by id and can be assigned a shortcut; some also appear in menus. Keys owned by a dialog, menu, or focused text input — `Esc`, `Enter`, `Ctrl-S` while writing a note — belong to those widgets and are not remappable. `[keybindings]` is read from your user config only, never from a repository's `.hunk/config.toml`: which keys do what is a property of your keyboard and habits, so a checkout you review cannot rearrange them. # Layout and display > Control responsive structure, line treatment, review chrome, and note visibility. Hunk uses the same normalized review model in every layout. ## Pick a layout policy ```bash hunk diff --mode auto hunk diff --mode split hunk diff --mode stack ``` * `auto` chooses split on wide terminals and stack on narrow ones. * `split` keeps before and after columns side by side. * `stack` shows changed rows in a single-width flow. Explicit split and stack choices override responsive behavior. Press `0`, `1`, or `2` to switch while reviewing. ## Tune code rows ```bash hunk diff --no-line-numbers --wrap --no-hunk-headers --tab-width 2 ``` Paired flags let scripts express either state: `--line-numbers` / `--no-line-numbers`, `--wrap` / `--no-wrap`, and `--hunk-headers` / `--no-hunk-headers`. Tab width accepts an integer from 1 through 16. ## Tune review chrome TOML settings cover persistent display details: ```toml mode = "auto" line_numbers = true wrap_lines = false hunk_headers = true menu_bar = true sidebar = "auto" agent_notes = false copy_decorations = false transparent_background = false cursor_line = "row" ``` `transparent_background` lets the terminal paint Hunk surfaces; turn it off when exact theme surfaces matter more than matching terminal transparency. `cursor_line` chooses how the line you are on is marked: `row` highlights the whole row, `number` marks only its line number, and `off` removes the marker and returns `k` / `j` to scrolling the view one row at a time. Switch it mid-review from the View menu, or set `--cursor-line