hunk README

The project's README from github.com/modem-dev/hunk. As one markdown file: README.md.

hunk

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

hunk.dev · Documentation

CI status Latest release MIT License Join the Discord community

image
Split view with sidebar and inline AI notes 		image
Unified view and mouse-selectable menus

Install

The default installation method on macOS and Linux downloads a standalone binary and installs it into ~/.hunk. It checks the archive against the release checksum when both SHA256SUMS and a supported checksum tool are available, and warns otherwise. Release discovery uses Hunk's anonymous aggregate endpoint with direct GitHub fallback:

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 with brew 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:

Update Hunk

Starting with Hunk 0.20, npm, Homebrew, and default install-script installs use Hunk’s canonical update command:

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.

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 syntax 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
hunk log                       # browse history on a terminal; print when redirected
hunk log --static              # force static output, paging when needed

hunk log is one auto-responsive, read-only history surface, not a repository manager. On a terminal it opens the desktop history browser; pipes and redirects receive shell-native static records automatically, and --static forces static output that pages only when needed. The selected VCS adapter owns traversal, filtering, refs, and how a history item opens for review; the bundled Git and Jujutsu adapters both implement that public capability. Static output keeps full commit, author, date, message, branch/bookmark, remote, and tag details; --oneline provides compact records, and --theme uses the same palette as Hunk review. Interactive history groups commits by local-calendar day with account-like author handles and relative times, while keeping commit ids right-aligned and clickable. Enable Graph view from the View menu to replace day groups with commit-topology lanes. Press v and move with Up/Down or k/j to select a contiguous range. Shift+Up/Shift+Down, uppercase K/J, and Shift-click extend directly. Escape collapses the selection; opening the range reviews the inclusive cumulative change from the oldest commit's parent through the newest commit. History also shares review's b/f full-page and u/d half-page movement keys. Range selection is disabled with --all or author, message, date, and path filters because traversal can interleave or hide commits. After opening a commit or range, quit its normal Hunk review to return to the same selection. History controls are configurable through canonical hunk.history.* keybindings.

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

Working with raw files and patches

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

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

  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 the agent workflow guide. 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/unified 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:

Example:

theme = "github-dark-default" # any built-in theme id, auto, or custom
mode = "auto"        # auto, split, unified
vcs = "git"          # git, jj, sl
watch = false
exclude_untracked = false
line_numbers = true
tab_width = 4        # tab stops, 1-16
file_gap = 1         # rows between files, including the ─ rule; 0 hides it
hunk_gap = 0         # blank rows before later hunks
wrap_lines = false
menu_bar = true
animations = 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 the theme guide 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. file_gap is separator height between files, including the ─ rule; hunk_gap is blank rows before later hunks. Set animations = false to make panes open and close immediately. 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 the keybinding guide 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.

An extension can add generic top-level CLI workflows, 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/[email protected]   # 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 full API, the trust model, publishing guidance, and the [extensions] / [extension.<id>] config reference. Installable examples include a dependency-free hunk gh 123 GitHub PR workflow, review triage, authoritative review snapshot export, 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 the OpenTUI component guide for install, API, and runnable examples.

Examples

Ready-to-run demo diffs live in the examples directory.

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 the contribution guide.

Sponsor

Sponsored by Modem.

Modem

License

MIT

hunk (modem-dev/hunk)

Searching Database…

9.6K ·GitHub
Hunk
这是什么?Hunk 是一个以代码审查为先的终端 diff 查看器,专门用来查看 AI 编程助手生成的改动——它是一个终端界面,基于 OpenTUI 构建,方便你审查编程助手改了什么。
所以它是在本地运行的终端应用,而不是网站或在线服务?对——它是一个 TUI(终端界面):hunk diff 和 hunk show 会把一组改动打开成多文件的审查流,带侧边栏、分屏/合并布局,并支持键盘、鼠标、分页器和 Git difftool。
我需要先装 Node.js 之类的吗?通常什么都不用:安装脚本、Homebrew、mise 和 Nix 都自带独立的二进制文件。只有通过 npm install 安装才需要 Node.js 22+。大多数使用场景建议装 Git。
有什么硬件或升级方面的坑需要知道?x86-64 版本需要 CPU 支持 SSE4.2(Intel Nehalem 2008 年起、AMD Bulldozer 2011 年起);arm64 没有这个要求。如果你是通过旧的 modem-dev/tap Homebrew tap 安装的,请先卸载那个版本。
它只对 AI 助手做的改动有用吗?这是它的主要定位,但它也是一个通用的 diff 查看器——可以处理原始文件和补丁、工作区改动,还能浏览完整的提交历史。
它在 Windows 上也能用吗,还是只有类 Unix 系统?三大桌面系统都支持:macOS、Linux 和 Windows。唯一要注意的是 Windows 上 mise 必须是 2026.8.6 或更新版本。
怎么把它和我的编程助手连起来?在另一个终端窗口打开 hunk diff 或 hunk show,运行 hunk skill path,然后让助手把它返回的技能文件加进去;接着让助手对着正在运行的 Hunk 会话使用这个技能,就能在代码旁边留下行内批注。监视模式(watch mode)会让审查内容随助手的修改实时更新。
它和 delta 或 difftastic 有什么不同?那两个只是在分页器里把 diff 渲染成带样式的文本;而 Hunk 会把整组改动打开成一个可交互的审查界面——多文件流加侧边栏、分屏/合并/自动布局、鼠标支持,还有行内的助手或 AI 批注,它的对比表显示这些其他工具都没有。代价是不支持结构化的 diff 比较。
它能配合 Git 以外的版本控制用吗?可以——Jujutsu 和 Sapling 的工作区会被自动识别,hunk diff 和 hunk show 能接受原生的 revset,hunk log 甚至能直接读取 jj 的历史记录,包括非共置(non-colocated)工作区。你还可以在配置文件里用 vcs = 'git'、'jj' 或 'sl' 固定后端。
我可以扩展它或者复用它的 diff 界面吗?每个快捷键都是一条命名命令,可以重新映射;主题既有内置的也支持自定义;还有一个实验性的 TypeScript 扩展 API,可以添加工作流、主题、VCS 后端,甚至用 React 组件替换侧边栏——不过它在小版本之间可能会变动。渲染器也以 HunkDiffView 的形式发布,可以嵌入你自己的 OpenTUI 应用。
What are similar projects?plannotator, pi-shadow-mind, oh-my-pi, MiMo-Code, diffle, DSH-better-sidebar, difftastic, diff-so-fancy
Which topics is it in?diff, bun, code-review, plugin-system, tui, git, agents, coding-agent, free, terminal, tool, typescript
Creator
modem-dev
Size
36.7 MB
Stars
9.6K
Updated
CommitOct 16Releasev0.23.0Sep 30
Age
7mo
Commits · 90 Days