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

CI status Latest release MIT License

• 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

npm i -g hunkdiff

Or with Homebrew:

brew install modem-dev/tap/hunk

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. See nix/README.md for details.

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

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 diff --watch # auto-reload as the working tree changes
hunk show # review the latest commit
hunk show HEAD~1 # review an earlier commit

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.

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

1. Open Hunk in another terminal with hunk diff or hunk show.
2. Tell your agent to add the skill file returned by hunk skill path.
3. 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.

Hunk is optimized for reviewing a full changeset interactively.

You can persist preferences to a config file:

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

Example:

theme = "graphite" # graphite, midnight, paper, ember, catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, catppuccin-mocha, zenburn, custom
mode = "auto" # auto, split, stack
vcs = "git" # git, jj, sl
watch = false
exclude_untracked = false
line_numbers = true
wrap_lines = false
agent_notes = false
transparent_background = false

exclude_untracked affects Git/Sapling working-tree hunk diff sessions only. transparent_background can also be written as transparentBackground.

Custom themes can inherit from any built-in base theme and override only the colors you care about:

theme = "custom"
[custom_theme]
base = "graphite" # graphite, midnight, paper, ember, catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, catppuccin-mocha, zenburn
label = "My Theme"
accent = "#7fd1ff"
panel = "#10161d"
noteBorder = "#c49bff"
[custom_theme.syntax]
keyword = "#8ed4ff"
string = "#c7b4ff"
comment = "#6e85a7"

All custom theme colors must use #rrggbb hex values.

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

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"

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

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

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

[pager]
pager = hunk pager

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.

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

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

💬 Chat with users/contributors on the Modem Discord server

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

Sponsored by Modem.

MIT