Desktop-inspired terminal diff viewer for understanding agent-authored changesets.
Hunk is an interactive terminal diff viewer for reviewing code changes, built on OpenTUI and Pierre diffs.
Split view with sidebar and inline AI notes |
Unified view and mouse-selectable menus |
On macOS and Linux, install the standalone binary:
curl -fsSL https://hunk.dev/install.sh | sh
Windows users can install with npm or mise. Other installation methods are also available:
npm i -g hunkdiff # macOS, Linux, or Windows; requires Node.js 22+
brew install hunk # macOS or Linux
mise use -g hunk # macOS, Linux, or Windows
[!NOTE] If you previously installed hunk via
modem-dev/tap, be sure to uninstall it first withbrew uninstall modem-dev/tap/hunk.
Windows requires mise 2026.8.6 or newer. Nix users can use the default package exported in flake.nix; see the Nix guide for details. Hunk also ships as a default tool in Omarchy, installed through mise.
Requirements:
For npm, Homebrew, and default install-script installs (Hunk 0.20+):
hunk update # install the newest release
hunk update --check # check without installing
hunk update 0.20.0 # select an exact npm or default install-script release
On an older release, update once with the installer or package manager that installed Hunk, then use hunk update going forward. Custom HUNK_INSTALL_DIR installs must re-run the installer with the same directory; mise, Nix, and source installs use their owning tools instead.
hunk # show help
hunk --version # print the installed version
Use familiar Git commands to open changes in Hunk:
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 log # browse history on a terminal; print when redirected
hunk log --static # force static output, paging when needed
hunk status # view workspace status and sibling worktrees (Git)
hunk status --static # print one read-only workspace snapshot
hunk status --json # emit one versioned workspace snapshot
hunk status is read-only: it does not fetch or change the repository. See workspace status for details.
hunk log opens an interactive history browser in a terminal and prints text when piped or redirected. Use --oneline for compact output. In the browser, enable Graph view from the View menu to see commit branches, or press v to select a commit range. Quit a commit review to return to history.
Hunk bundles hunk gh, so pull requests, commits, and comparisons open directly without the
GitHub CLI or a separate extension:
hunk gh pr # infer the open PR for the current branch
hunk gh pr 123 # infer the repository from origin
hunk gh pr 'modem-dev/hunk#123' # quote this form for shells that treat # as a comment
hunk gh commit a1b2c3d --repo modem-dev/hunk
hunk gh compare main...feature --repo modem-dev/hunk
Public repositories work anonymously. Set GH_TOKEN, or GITHUB_TOKEN when it is absent, for
private repositories and higher API limits. GitHub Enterprise is not currently supported.
Hunk auto-detects Jujutsu and Sapling checkouts, so hunk diff [revset] and hunk show [revset] use native revsets inside jj or Sapling workspaces. hunk log --vcs jj also reads JJ history directly, including in a non-colocated workspace. To override VCS detection, set vcs = "git" or vcs = "jj" or vcs = "sl" in config.
hunk open # browse the current directory
hunk open README.md # view a complete, syntax-highlighted document
hunk open path/to/project # browse another directory without requiring a repository
Use arrows and Enter to navigate, Tab to switch focus, i to show hidden/Git-ignored entries, and e to edit the displayed file in $EDITOR. See the open workflow for details and file limits.
hunk diff --files before.ts after.ts # compare two files directly
hunk diff --files before.ts after.ts --watch # auto-reload when either file changes
git diff --no-color | hunk patch - # review a patch from stdin
npx skills add modem-dev/hunk -g --skill hunk-review.hunk diff or hunk show.a in Hunk to show agent notes; they start hidden.If your agent has no skill system, ask it to run hunk skill show and follow the output.
See Review with an agent for live sessions, --agent-context, and experimental rich notes.
| 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/unified layout | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Mouse support inside the viewer | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Runtime view toggles | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Syntax highlighting | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| Structural diffing | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
| Pager-compatible mode | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ |
You can persist preferences to a config file:
$XDG_CONFIG_HOME/hunk/config.toml (default ~/.config/hunk/config.toml).hunk/config.toml in a repositoryPersistent state uses $XDG_STATE_HOME/hunk/state.json when the variable is
absolute, or ~/.local/state/hunk/state.json otherwise. Hunk preserves existing
state by copying the old config-directory file on first use, keeping the original
and falling back to it if migration fails. Global extension paths are unchanged.
For example:
theme = "github-dark-default"
mode = "auto" # auto, split, unified
auto_split_min_width = 160 # minimum available diff columns for split in auto mode
line_numbers = true
wrap_lines = false
See the configuration guide for command overrides and examples, the full reference for every option, or the theme guide to customize colors.
Remap shortcuts with a [keybindings] table in your user config. See the keybinding guide for available commands, default keys, and examples.
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 diffworking-tree loader. If you opengit diffthroughhunk 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"
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
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.
Extensions can add commands, themes, VCS backends, custom sidebars, and more. For example, filter lockfiles out of a review:
// ~/.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 the extension guide for the API, configuration, and publishing instructions. Installable examples include review triage, review snapshot export, an optional rendered Markdown file view, and a Vim navigation mode built from public semantic commands.
Hunk also publishes HunkDiffView and lower-level primitives from hunkdiff/opentui for embedding the same diff renderer in your own OpenTUI app.
See the OpenTUI component guide for install, API, and runnable examples.
Ready-to-run demo diffs live in the examples directory.
Each example includes the exact command to run from the repository root.
💬 Chat with users/contributors on the Modem Discord server
See CONTRIBUTING.md for development setup and contribution guidelines.
Sponsored by Modem.
FAQs
Desktop-inspired terminal diff viewer for understanding agent-authored changesets.
The npm package hunkdiff receives a total of 6,388 weekly downloads. As such, hunkdiff popularity was classified as popular.
We found that hunkdiff demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.