Hunk: A Terminal Diff Viewer Built for Reviewing Agent-Written Code

The Problem Hunk Targets: Reviewing AI-Generated Changesets

Agentic coding tools produce changes that span many files, often with little human oversight during generation. Reviewing those changes in a plain terminal diff means scrolling through a linear stream of hunks with no sense of the overall structure. Hunk is built for that specific workflow. It is a review-first terminal diff viewer, meaning the interface is designed around the act of examining a changeset before accepting it, not just printing a diff. The intended user is someone who runs an AI agent, gets a multi-file patch back, and needs to verify it quickly. The README positions it as a tool for agent-authored changesets, and the agent workflow section shows how to connect it to a live session. This is not a general-purpose diff tool for everyday Git users; it is a specialized review surface for a particular, growing use case.

How Hunk Works: OpenTUI, Pierre Diffs, and a Review Stream

Hunk is built on OpenTUI, a terminal UI framework, and the Pierre diffs library for diff computation. The core mechanism is a multi-file review stream with a sidebar for navigation. You open a changeset, and Hunk presents the files in a list on the left, with the diff content in the main pane. The viewer supports split, stack, and responsive auto layouts, which change how files and hunks are arranged on screen. The split view shows two files side by side; the stacked view shows them one after another; the responsive auto layout switches based on terminal width. Inline AI and agent annotations appear beside the code, which is the feature that distinguishes Hunk from older tools. The documentation mentions experimental rich STML note bodies, activated with --experimental, while plain agent notes are the default. The data flow is straightforward: Hunk reads a Git diff, a patch from stdin, or two files, computes the diff with Pierre, and renders it in the OpenTUI interface. Watch mode uses filesystem observation for Git and direct-file reviews, with periodic polling as a fallback, while Jujutsu and Sapling reviews use polling only.

Getting Hunk Running: Install Methods and First Commands

Hunk installs several ways. The npm route is `npm i -g hunkdiff`, which requires Node.js 18 or newer. On macOS and Linux, an install script downloads a prebuilt binary, verifies its checksum, and installs into `~/.hunk`: `curl -fsSL https://hunk.dev/install.sh | sh`. Homebrew users run `brew install hunk`, and mise users run `mise use -g hunk`, with Windows requiring mise 2026.8.6 or newer. Nix users can use the default package in flake.nix. The install script, Homebrew, mise, and Nix all ship a standalone binary, so Node.js is only needed for the npm install. Once installed, `hunk` shows help and `hunk --version` prints the version. The Git-facing commands mirror Git's diff-style commands: `hunk diff` reviews current repo changes including untracked files, `hunk show` reviews the latest commit, and `hunk show HEAD~1` reviews an earlier commit. You can also compare two files directly with `hunk diff before.ts after.ts`, or pipe a patch in with `git diff --no-color | hunk patch -`. The `--fast` flag experimentally offloads syntax highlighting, and `--watch` enables auto-reload. Updating is done with `hunk update`, and `hunk update --check` reports versions without updating.

The Agent Workflow: Skills, Live Sessions, and STML Notes

The agent integration is the most distinctive part of Hunk. The workflow is: 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 Hunk session. The README gives a generic prompt: "Load the Hunk skill and use it for this review. Run `hunk skill path` to get the skill path." This suggests a live-session protocol where the agent can send annotations or notes into the running viewer. The full guide lives in docs/agent-workflows.md, which is not included in the material, so the exact wire format is unknown. What is clear is that the annotations are inline, placed beside the code, and that plain notes are the default. The experimental STML note bodies are a richer format, but they require starting the review with --experimental. This design has a trade-off: it ties the review experience to a specific agent protocol, which may not work with every agent framework out of the box. The skill file is a bridge, but it is an extra step that a plain diff viewer does not need.

VCS Support Beyond Git: Jujutsu and Sapling with a Caveat

Hunk auto-detects Jujutsu and Sapling checkouts, so `hunk diff [revset]` and `hunk show [revset]` use native revsets inside those workspaces. You can override detection with the `vcs` config key, setting it to `"git"`, `"jj"`, or `"sl"`. This is a meaningful advantage for users of those version control systems, since few diff tools understand their revsets natively. The caveat is in watch mode: Jujutsu and Sapling reviews use polling rather than filesystem observation, which the README says is a fallback for missed events or unavailable watchers. That means watch mode on jj or sl may be slower to reflect changes than on Git, and it may miss rapid edits. For direct-file and Git-backed reviews, filesystem observation refreshes promptly, with polling retained as a fallback. This is a concrete limitation for anyone who relies on watch mode in a jj or sl workspace. The polling approach is not inherently broken, but it is a different performance profile, and the README does not specify the polling interval.

Hardware and Platform Constraints: SSE4.2 and Node.js

Hunk has specific hardware requirements that are easy to overlook. On x86-64, the CPU must support SSE4.2, which means Intel Nehalem (2008+) or AMD Bulldozer (2011+). arm64 has no CPU feature floor. This is a real constraint for older machines or virtualized environments that disable SSE4.2. For the npm install, Node.js 18 or newer is required, but the install script, Homebrew, mise, and Nix ship a standalone binary, so Node is not needed at runtime for those methods. Git is recommended for most workflows, but not strictly required, since you can compare raw files or pipe a patch. The README does not state whether the standalone binary includes its own runtime or depends on system libraries; the install script verifies a checksum, which is good for supply chain hygiene. The SSE4.2 floor is a genuine limitation for legacy hardware, and it is worth checking before adopting Hunk in a constrained environment.

Alternatives and Where Hunk Fits in the Diff Tool Landscape

The README includes a feature comparison table that names lumen, difftastic, delta, diff-so-fancy, and GNU diff. Lumen is the closest alternative: it also offers a review-first interactive UI and multi-file stream with sidebar, plus mouse support and runtime toggles, but it lacks inline agent or AI annotations and responsive auto split/stack layout. Difftastic and delta are not interactive; they are formatters that output colored diffs to stdout, which makes them scriptable and pipe-friendly. Diff-so-fancy is a text filter that prettifies Git diffs. GNU diff is the baseline. The practical difference is approach: Hunk and lumen are interactive viewers you sit in front of, while difftastic and delta are tools you run in a pipeline or a pager. If your review process is non-interactive, such as generating a diff in CI or grepping through changes, Hunk is the wrong tool because it opens a UI instead of producing plain text. If you want an interactive review surface, Hunk's agent annotations and VCS support give it an edge over lumen, but lumen may be sufficient if you do not need AI integration.

Maintenance, Licensing, and Upgrade Path

Hunk is MIT licensed, which means you can use, modify, and redistribute it with few restrictions, though this is not legal advice. The repository is actively maintained, with recent releases including v0.20.0 in August 2026, and the default branch is main. The README documents an update mechanism: `hunk update` installs the newest release using the same package manager you originally used, and `hunk update --check` reports versions. For mise, Nix, and source installs, the command that updates them is printed instead, so you are not left guessing. The install script verifies a checksum, which is a good sign for upgrade safety. The maintenance cost is low for users: updates are a single command, and the tool is self-contained. For contributors, the project is TypeScript-based, built on OpenTUI and Pierre diffs, so the learning curve depends on familiarity with those libraries. The experimental flag for STML notes indicates that some features are not yet stable, so you should expect API or behavior changes in that area across releases. The release cadence (three releases in about nine days in August 2026) suggests active development, but it also means you may want to pin your version if you rely on stable behavior.

Editorial conclusion

Adopt Hunk if you are an agentic coder who regularly reviews large, multi-file changesets produced by AI assistants and you want an interactive terminal UI with inline annotations, watch mode, and native Jujutsu or Sapling support. Skip it if you only need a fast, scriptable diff formatter for pipelines or CI output, where tools like delta or difftastic are lighter and more familiar. Before adopting, verify that your CPU meets the SSE4.2 requirement on x86-64, confirm your Node.js version if installing via npm, and check whether the experimental STML note bodies are stable enough for your workflow, since they require the --experimental flag.

Official sources

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