CLI tool
modem-dev/hunk avatar
modem-dev/hunk

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

Review-first terminal diff viewer for agentic coders. Requirements: Node.js 18+ macOS, Linux, or Windows Git recommended for most workflows Nix users can use the default package exported in flake.nix instead.

9,835 stars334 forksTypeScriptMIT

At a glance

What is it?
Hunk is a review-first terminal diff viewer for agent-authored changesets, built on OpenTUI and Pierre diffs. It offers a multi-file sidebar, inline AI annotations, and Git, Jujutsu, and Sapling support, but its focus on interactive review means it is not a drop-in replacement for plain-text diff tools.
Who is it for?
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.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • modem-dev/hunk9,835 ★ · +1,987
Star history
Repository2026-07-282026-11-15
modem-dev/hunk7.8k9.8k

1,987 Stars in the last 110 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

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, unified, and responsive auto layouts, which change how files and hunks are arranged on screen. The split view shows two files side by side; the unified view shows them in a single column; 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 README mentions experimental rich notes. Watch mode auto-reloads file and Git-backed reviews.

Getting Hunk Running: Install Methods and First Commands

Hunk installs several ways. The npm route is `npm i -g hunkdiff`, which requires Node.js 22+. On macOS and Linux, an install script installs the standalone binary: `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 --files before.ts after.ts`, or pipe a patch in with `git diff --no-color | hunk patch -`. The `--watch` flag 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: install the review skill once with `npx skills add modem-dev/hunk -g --skill hunk-review`, open Hunk in another terminal with `hunk diff` or `hunk show`, then ask your agent to use the hunk-review skill against the live Hunk session. Press `a` in Hunk to show agent notes, which start hidden. If your agent has no skill system, ask it to run `hunk skill show` and follow the output. This suggests a live-session protocol where the agent can send annotations or notes into the running viewer. The README points to https://hunk.dev/docs/agents/review-with-an-agent/ for live sessions, `--agent-context`, and experimental rich notes. 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 README describes watch mode as auto-reloading file and Git-backed reviews, so check the documentation before relying on watch mode in a jj or sl workspace.

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 22 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. Prebuilt binaries are published for macOS (arm64, x64), Linux (arm64, x64; glibc) and Windows (x64), not for Windows on arm64 or musl-based Linux such as Alpine. 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 first alternative in the table. 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 is an interactive viewer 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 is built for that.

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.24.1 on 2026-10-25, 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. Mise, Nix, and source installs use their owning tools instead. 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 rich notes indicate 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, one of them a beta, in about ten days in October 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 rich notes are stable enough for your workflow.

Frequently asked questions

What is the best terminal diff viewer?

For changesets written by coding agents, hunk is built around review: a multi-file stream with sidebar navigation, inline AI and agent annotations beside the code, split, unified, and responsive auto layouts, watch mode, and keyboard, mouse, pager, and Git difftool support.

How do I install hunk on Windows?

Windows users install with npm or mise, and the mise route requires mise 2026.8.6 or newer. Both commands are documented: `npm i -g hunkdiff` needs Node.js 22+, and `mise use -g hunk` needs the newer mise.

Do I need the GitHub CLI to review a pull request in hunk?

No. hunk bundles `hunk gh`, so pull requests, commits, and comparisons open without the GitHub CLI or a separate extension. Public repositories work anonymously; set `GH_TOKEN`, or `GITHUB_TOKEN` when it is absent, for private repositories and higher API limits.

Can hunk review a diff that did not come from a git repository?

Yes. `hunk diff --files before.ts after.ts` compares two files directly, and `git diff --no-color | hunk patch -` reviews a patch arriving on standard input. Git is recommended for most workflows rather than required.

Why does hunk update not work for my install?

From version 0.20 the canonical `hunk update` covers npm, Homebrew, and default install-script installs only. A custom `HUNK_INSTALL_DIR` install needs the installer re-run with the same directory, and mise, Nix, and source installs are updated with their owning tool.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
  4. Release notes
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/modem-dev-hunk.svg)](https://hysenlabs.com/projects/modem-dev-hunk)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/modem-dev-hunk.svg)](https://hysenlabs.com/projects/modem-dev-hunk)

Was this useful?