hunk

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

• 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

Install

npm i -g hunkdiff

Requirements:

• Node.js 18+
• macOS or Linux
• Git recommended for most workflows

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 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 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

Working with agents

1. Open Hunk in another terminal with hunk diff or hunk show.
2. Load the Hunk review skill: skills/hunk-review/SKILL.md.
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.

[!NOTE] hunk skill path lands in Hunk 0.10.0. Until that release is out, load the skill from the repo path above.

For the full live-session and --agent-context workflow guide, see docs/agent-workflows.md.

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 = "graphite"   # graphite, midnight, paper, ember
mode = "auto"        # auto, split, stack
exclude_untracked = false
line_numbers = true
wrap_lines = false
agent_notes = false

exclude_untracked affects working-tree hunk diff sessions only.

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"

OpenTUI component

Hunk also publishes HunkDiffView 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

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

Sponsor

Sponsored by Modem.

License

MIT