hunk: a review-first terminal diff viewer for agent-authored changes

The problem hunk targets: changesets nobody wants to read

A plain git diff is fine for one file and one hunk. It stops being fine when an agent returns twelve touched files, a rename, and a rewritten test, and the reviewer has to reconstruct the intent from a scrolling wall of minus and plus lines. hunk is built for that second case. The README describes it as a review-first terminal diff viewer for agent-authored changesets, which is a narrow claim: the tool assumes a human is going to read the change carefully, and that the change was probably produced by a model rather than typed line by line.

The audience follows from that. If you run an agent in one terminal and want to inspect what it produced in another, hunk fits. If you review other people's pull requests in a browser, hunk does nothing for you. The feature list is explicit about the shape of the product: a multi-file review stream with sidebar navigation, split, stack and responsive auto layouts, and inline AI and agent annotations placed beside the code. Those are review affordances, not diff-rendering tricks.

How the review stream and the agent annotations actually fit together

hunk is a TypeScript project built on OpenTUI for the terminal interface and on the @pierre/diffs package for diff parsing and rendering. The repository is a workspace: the root package.json is named @hunk/workspace and declares workspaces under packages/*, with the runnable entry at packages/hunk/src/main.tsx. The root scripts show how the pieces are assembled, including build:npm, build:bin and a stage-prebuilt-npm step that packages a standalone binary alongside the npm artifact. That split explains a detail in the requirements: the npm install needs Node.js 18+, while the install script, Homebrew, mise and Nix ship a prebuilt binary.

The review model is a stream rather than one diff at a time. hunk diff opens the current repository changes, untracked files included, and the sidebar moves between files in that set. Layout can be split, stacked, or chosen automatically as the terminal resizes. Agent annotations are the distinguishing part: notes from an agent are rendered inline next to the lines they refer to, and the README says plain agent notes are the default while rich STML note bodies require starting the review with --experimental. That flag is worth noticing. It means the richer note format is not the stable path yet.

Watch mode is the other half of the loop. hunk diff --watch reloads as the working tree changes, and hunk diff before.ts after.ts --watch does the same for two loose files. The README is specific about how that refresh happens: direct-file and Git-backed reviews normally use filesystem observation, with periodic polling retained as a fallback for missed events or unavailable watchers, while Jujutsu and Sapling reviews currently use polling instead. If you review a large jj workspace, expect polling latency rather than instant refresh.

Installing hunk and running a first review

The npm route is the shortest if you already have Node.js 18 or newer. The package name on npm is hunkdiff, not hunk, so the global install command is:

npm i -g hunkdiff

After that, hunk --version prints the installed version and hunk with no arguments shows help. On macOS and Linux there is also an install script that downloads the prebuilt binary, verifies its checksum, and installs into ~/.hunk:

curl -fsSL https://hunk.dev/install.sh | sh

Homebrew and mise are the other documented routes. Homebrew users run brew install hunk. One migration note matters here: if you previously installed hunk through modem-dev/tap, the README says to uninstall it first with brew uninstall modem-dev/tap/hunk. mise users run mise use -g hunk, and the README notes that Windows requires mise 2026.8.6 or newer. Nix users are pointed at the default package exported in flake.nix rather than at the npm artifact.

The first real review is a Git one. From inside a repository with uncommitted work:

hunk diff

That opens the changeset in the review UI instead of printing text, including untracked files. To watch the tree while you edit or while an agent keeps writing:

hunk diff --watch

For an already committed change, hunk show reviews the latest commit and hunk show HEAD~1 reviews an earlier one. If the change arrives as a patch rather than a working tree, pipe it in:

git diff --no-color | hunk patch -

Upgrades go through hunk update, which installs the newest release with whichever package manager you used, and hunk update --check just reports the versions. The README states that mise, Nix and source installs print the command that updates them instead, so those users do not get the automatic path.

The agent loop is the part with the most caveats

The documented agent workflow has three steps. Open hunk in another terminal with hunk diff or hunk show. Tell your agent to add the skill file returned by hunk skill path. Then ask the agent to use that skill against the live session. The README offers a generic prompt for the second step, and points at docs/agent-workflows.md for the full live-session and --agent-context guide.

This is the least self-contained part of the product. The skill file is generated by a repository script (generate:skill) and lives in the skills directory, so the integration depends on your agent being able to load a skill and then talk to a running hunk session. Nothing in the README describes what happens when the agent writes a note for a file that has since been reloaded by watch mode, or how two agents writing to one session are ordered. Those are the questions to answer before you build a team process on top of annotations.

The --experimental flag is the second caveat. Rich STML note bodies are gated behind it, and the README frames plain agent notes as the default. If you want formatted notes, you are opting into the unstable surface, and the flag has to be present when the review starts rather than toggled later.

Where hunk is the wrong tool

hunk is a local terminal viewer, and several workflows fall outside that. Continuous integration is the clearest one: the README describes no headless mode, no exit code that fails a build on a diff, and no report artifact. If your requirement is that a machine reads the diff, hunk is not in that category.

Large single-file diffs are another mismatch. The review stream and sidebar exist to move between files; a three-thousand-line change to one generated file is the case where a pager plus a search is often faster, and the feature comparison in the README places hunk next to tools that do not attempt a review UI at all. Non-interactive environments are a third: the UI expects a terminal that can handle mouse input and resizing, and the requirements list a CPU feature floor on x86-64, SSE4.2, which rules out pre-2008 Intel and pre-2011 AMD hardware for the prebuilt binary. arm64 has no such floor. Finally, Jujutsu and Sapling reviews poll rather than observe the filesystem, so a jj workspace under heavy rewriting will feel less immediate than a Git one.

hunk against difftastic and delta

The README's own comparison table is the honest place to start, because it separates hunk from tools that solve a different problem. difftastic and delta are both diff renderers. They take a diff and make it more readable, and they are designed to be dropped into a pager or a Git configuration as a filter. Neither is interactive in the sense hunk is: the table marks review-first interactive UI, multi-file review stream with sidebar, inline agent annotations and responsive auto split/stack layout as absent for both.

That difference is architectural, not cosmetic. A renderer is stateless per invocation, which is why delta composes with git config and difftastic composes with a pager. hunk holds a session: it tracks which files are in the stream, which one is selected, and what annotations belong to which lines, and it keeps that state alive across reloads in watch mode. You cannot get the annotation workflow by piping a diff into a renderer, because there is nowhere for the annotation to live.

The trade is that hunk is heavier to adopt. It wants a terminal UI, an install outside your Git config, and for the agent path, a skill file and a running session. lumen is the closest name in the table, since it also carries a review-first interactive UI with sidebar and mouse support, but the table marks inline agent and AI annotations as absent there. So the decision is narrow: if you want agent notes pinned to lines, hunk is the one in this comparison that claims it.

Licence, maintenance and what an upgrade costs you

hunk is MIT licensed, which is permissive and imposes no source-disclosure requirement on your own code. The practical implication is that you can vendor the binary or wrap it in internal tooling without a licensing conversation, though the MIT text still has to travel with redistributed copies. Nothing here is legal advice; read LICENSE in the repository for the actual terms.

The maintenance signal is concrete. The repository is not archived, and the last push was on 2026-08-25, the same day v0.20.0 was released. Releases are frequent and versioned in the 0.x range: v0.19.0 on 2026-08-16, v0.19.1 and then v0.20.0 on 2026-08-25. A 0.x line moving that quickly means minor versions can carry interface changes, and the --experimental gate on STML notes is a reminder that some surfaces are still settling.

Upgrade cost depends on your install route. hunk update handles npm, Homebrew and the install-script installs by delegating to the package manager you used, and hunk update --check reports versions without changing anything. mise, Nix and source installs print the update command instead of running it, so those users carry the manual step. The repository also keeps a CHANGELOG.md and a .changeset directory, and the root package.json has check:changelog and check:docs scripts that fail when generated documentation drifts, which suggests changelog and docs are treated as build outputs rather than afterthoughts.

Editorial conclusion

Adopt hunk if an agent or a teammate produces multi-file changesets that you currently read as plain text, and you want the review to happen in the terminal with annotations attached to the code. Skip it if your workflow is a single-file diff, a CI-only check, or a GUI review board, since hunk is an interactive local viewer and the README documents no server component. Before relying on it, run hunk --version after install, confirm hunk update reports the newest release through your package manager, and read docs/agent-workflows.md to check that the live-session and --agent-context flow matches how your agent is wired.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes