hunkdiff

hunk

Hunk is a review-first terminal diff viewer for agent-authored changesets, built on OpenTUI and Pierre diffs.

hunk.dev · Documentation

• multi-file review stream with sidebar navigation
• inline AI and agent annotations beside the code
• split, stack, and responsive auto layouts
• watch mode for auto-reloading file and Git-backed reviews
• keyboard, mouse, pager, and Git difftool support

Split view with sidebar and inline AI notes

Stacked view and mouse-selectable menus

Install

npm i -g hunkdiff

Or with Homebrew:

brew install hunk

[!NOTE] If you previously installed hunk via modem-dev/tap, be sure to uninstall it first with brew uninstall modem-dev/tap/hunk.

Or with mise (Windows requires mise 2026.8.6 or newer):

mise use -g hunk

Requirements:

• macOS, Linux, or Windows
• On x86-64, a CPU with SSE4.2 (Intel Nehalem 2008+, AMD Bulldozer 2011+); arm64 has no CPU feature floor
• Node.js 18+ for the npm install; Homebrew, mise, and Nix ship a standalone binary
• Git recommended for most workflows

Nix users can use the default package exported in flake.nix instead. See nix/README.md for details.

Hunk also ships as a default tool in Omarchy, installed through mise.

Quick start

hunk           # show help
hunk --version # print the installed version

Working with Git

Hunk mirrors Git's diff-style commands, but opens the changeset in a review UI instead of plain text.

hunk diff                      # review current repo changes, including untracked files
hunk --fast                    # experimentally offload eligible large-diff highlighting
hunk diff --watch              # auto-reload as the working tree changes
hunk show                      # review the latest commit
hunk show HEAD~1               # review an earlier commit

Working with Jujutsu and Sapling

Hunk auto-detects Jujutsu and Sapling checkouts, so hunk diff [revset] and hunk show [revset] use native revsets inside jj or Sapling workspaces. To override VCS detection, set vcs = "git" or vcs = "jj" or vcs = "sl" in config.

Working with raw files and patches

hunk diff before.ts after.ts                # compare two files directly
hunk diff before.ts after.ts --watch        # auto-reload when either file changes
git diff --no-color | hunk patch -          # review a patch from stdin

Watch mode remains continuous. Direct-file and Git-backed reviews normally use filesystem observation to refresh promptly, with periodic polling retained as a fallback for missed events or unavailable watchers. Jujutsu and Sapling reviews currently use polling rather than filesystem observation.

Working with agents

• Open Hunk in another terminal with hunk diff or hunk show.
• Tell your agent to add the skill file returned by hunk skill path.
• Ask your agent to use the skill against the live Hunk session.

A good generic prompt is:

Load the Hunk skill and use it for this review. Run `hunk skill path` to get the skill path.

For the full live-session and --agent-context workflow guide, see docs/agent-workflows.md. Experimental rich STML note bodies require starting the review with --experimental; plain agent notes remain the default.

Feature comparison

Capability	hunk	lumen	difftastic	delta	diff-so-fancy	diff
Review-first interactive UI	✅	✅	❌	❌	❌	❌
Multi-file review stream + sidebar	✅	✅	❌	❌	❌	❌
Inline agent / AI annotations	✅	❌	❌	❌	❌	❌
Responsive auto split/stack layout	✅	❌	❌	❌	❌	❌
Mouse support inside the viewer	✅	✅	❌	❌	❌	❌
Runtime view toggles	✅	✅	❌	❌	❌	❌
Syntax highlighting	✅	✅	✅	✅	❌	❌
Structural diffing	❌	❌	✅	❌	❌	❌
Pager-compatible mode	✅	❌	✅	✅	✅	✅

Hunk is optimized for reviewing a full changeset interactively.

Advanced

Config

You can persist preferences to a config file:

• ~/.config/hunk/config.toml
• .hunk/config.toml

Example:

theme = "github-dark-default" # any built-in theme id, auto, or custom
mode = "auto"        # auto, split, stack
vcs = "git"          # git, jj, sl
watch = false
exclude_untracked = false
line_numbers = true
tab_width = 4        # tab stops, 1-16
wrap_lines = false
menu_bar = true
sidebar = "auto"     # "auto", true, false
agent_notes = false
prompt_save_view_preferences = true
transparent_background = false

Choose a built-in theme, auto, or a custom theme with theme. See docs/themes.md for automatic selection, custom theme tables, syntax scopes, and legacy syntax-table migration.

exclude_untracked affects Git/Sapling working-tree hunk diff sessions only. tab_width controls source-code tab stops and can be overridden with -x4 or --tab-width 4. prompt_save_view_preferences = false disables the quit prompt for saving changed view preferences. transparent_background can also be written as transparentBackground.

Keybindings

Every keyboard shortcut is a named command, and a [keybindings] table in your user config remaps command ids to the keys you want them on — several keys per command, exclusive claims over defaults, and false to unbind. See docs/keybindings.md for the rules, the chord grammar, and the full table of built-in commands and their default keys.

Git integration

Set Hunk as your Git pager so git diff and git show open in Hunk automatically:

[!NOTE] Untracked files are auto-included only for Hunk's own hunk diff working-tree loader. If you open git diff through hunk pager, Git still decides the patch contents, so untracked files will not appear there.

git config --global core.pager "hunk pager"

Or in your Git config:

[core]
    pager = hunk pager

If you want to keep Git's default pager and add opt-in aliases instead:

git config --global alias.hdiff "-c core.pager=\"hunk pager\" diff"
git config --global alias.hshow "-c core.pager=\"hunk pager\" show"

Jujutsu pager integration

To use Hunk as jj's pager, run jj config edit --user and update:

[ui]
pager = ["hunk", "pager"]
diff-formatter = ":git"

Sapling pager integration

To use Hunk as Sapling's pager, run sl config -u and update:

[pager]
pager = hunk pager

Extensions (experimental)

The extension API is experimental and may change in breaking ways between minor releases while it stabilizes; breaking changes are called out in release notes.

Hunk loads plain TypeScript extensions from ~/.config/hunk/extensions/, from a repository's .hunk/extensions/ (after you explicitly trust that repository), and from --extension <path> for development. --no-extensions turns those off for one run; Hunk's own bundled backends (Git, Jujutsu, and Sapling) stay loaded.

A Phase 1 extension can contribute themes and file-extension → language mappings, add a VCS backend, rewrite the changeset before review (collapse lockfiles, reorder files by review priority), replace the file-navigation sidebar with its own React component, react to lifecycle events, and show transient messages:

// ~/.config/hunk/extensions/collapse-lockfiles.ts
import type { HunkExtensionAPI } from "hunkdiff/extension";

export default function (hunk: HunkExtensionAPI) {
  hunk.transformChangeset((changeset, ctx) => {
    const files = changeset.files.filter((file) => !file.path.endsWith(".lock"));
    ctx.notify(`Collapsed ${changeset.files.length - files.length} lockfiles`);
    return { ...changeset, files };
  });
}

Extensions shared as git repositories install straight from their host, and a hunk-extension GitHub topic marks community ones:

hunk extension install acme/hunk-word-diff@v1.2.0   # or git:host/path, a URL, a local path
hunk extension list                                 # then update [name] / remove <name>

Browse community extensions at github.com/topics/hunk-extension; publish yours by pushing the extension to a repository root and adding that topic.

See docs/extensions.md for the full API, the trust model, publishing guidance, and the [extensions] / [extension.<id>] config reference. Installable examples include review triage, an optional rendered Markdown file view, and a Vim navigation mode built from public semantic commands.

OpenTUI component

Hunk also publishes HunkDiffView and lower-level primitives from hunkdiff/opentui for embedding the same diff renderer in your own OpenTUI app.

See docs/opentui-component.md for install, API, and runnable examples.

Examples

Ready-to-run demo diffs live in examples/.

Each example includes the exact command to run from the repository root.

Contributing

💬 Chat with users/contributors on the Modem Discord server

For source setup, tests, packaging checks, and repo architecture, see CONTRIBUTING.md.

Sponsor

Sponsored by Modem.

License

MIT