Development
Plugin
hunk
Hunk is a review-first terminal diff viewer for agent-authored changesets, built on OpenTUI and Pierre diffs.
Plugin Signal74/100Solid
maintained100
capable23
documented100
adopted83
Install
$ npx -y skills add modem-dev/hunk --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Stats
8,199
Stars
242
Forks
Active
Maintenance
TypeScript
Language
MIT
License
3m ago
Last commit
4mo ago
Created
Repo: modem-dev/hunk
What's inside
Skills
2/hunk-reviewInteracts with live Hunk diff review sessions via CLI. Inspects review focus, navigates files and hunks, reloads session contents, and adds inline review comments. Use when the user has a Hunk session running or wants to review diffs interactively./launch-videoProduces Hunk videos by driving the real TUI headlessly in a PTY, compositing captioned 1080p frames in Chromium, and encoding with ffmpeg. Use for feature demos, workflow explainers, announcements, launch videos, and full-release roundups.
README
1hunk
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
Or with Homebrew:
brew install hunk
[!NOTE] If you previously installed hunk via
modem-dev/tap, be sure to uninstall it first withbrew uninstall modem-dev/tap/hunk.
Requirements:
- Node.js 18+
- macOS, Linux, or Windows
- Git recommended for most workflows
Nix users can use the
defaultpackage exported inflake.nixinstead. See nix/README.md for details.
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 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 difforhunk 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
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 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"
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 };
});
}
See docs/extensions.md for the full API, the trust model,
and the [extensions] / [extension.<id>] config reference. Installable examples
include review triage and an optional
rendered Markdown file view.
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
File tree
759modem-dev/hunkView on GitHub
.changeset/
config.json
cuddly-papers-burn.md
hip-moments-end.md
inline-edit-example.md
lazy-spiders-draw.md
lucky-moons-smash.md
ninety-mirrors-sleep.md
README.md
tall-emus-bathe.md
wild-owls-wash.md
.env.test
.envrc
.github/
dependabot.yml
ISSUE_TEMPLATE/
bug.yml
config.yml
contribution.yml
scripts/
detect-code-changes.sh
workflows/
benchmarks.yml
ci.yml
nix.yml
pinact.yml
pr-ci.yml
release-prebuilt-npm.yml
website.yml
.gitignore
.lintstagedrc.json
.oxfmtrc.json
.oxlintrc.json
AGENTS.md
assets/
hunk-logo.webp
benchmarks/
bootstrap-load.ts
changeset-parse.ts
competitors.ts
geometry-memory.ts
highlight-prefetch.ts
huge-stream.ts
interaction-latency.ts
large-stream-fixture.ts
large-stream-profile.ts
large-stream.ts
lib/
benchmark-result.ts
fixtures.ts
interaction.ts
memory.ts
navigation-memory.ts
non-ascii-stream.ts
README.md
release/
.gitkeep
bench-0.15.0.json
bench-0.15.1.json
bench-0.15.2.json
bench-0.15.3.json
bench-0.16.0.json
bench-0.17.0.json
bench-0.17.1.json
bench-0.17.2.json
bench-0.17.3.json
bench-0.17.4.json
bench-0.17.5.json
bench-0.17.6.json
bench-0.17.7.json
bench-0.18.0-beta.0.json
bench-0.18.0.json
README.md
render-layout.ts
resize-memory.ts
results/
.gitignore
.gitkeep
run.ts
terminal-width.ts
working-tree-load.ts
wrapped-cjk.ts
bin/
hunk.cjs
bun.lock
bunfig.toml
CHANGELOG.md
CLAUDE.md
CONTRIBUTING.md
docs/
agent-workflows.md
extension-api-evaluation.md
extension-architecture.md
extension-system-exploration.md
extensions.md
file-view-jsx-poc.md
keybindings.md
opentui-component.md
source-architecture.md
themes.md
watch-benchmark-final.md
watch-benchmark.md
examples/
1-hello-diff/
after.ts
before.ts
README.md
2-mini-app-refactor/
after/
src/
format.ts
groupTasks.ts
main.ts
tasks.ts
test/
main.demo.ts
before/
src/
format.ts
main.ts
tasks.ts
test/
main.demo.ts
change.patch
README.md
3-agent-review-demo/
after/
src/
commands.ts
index.ts
normalize.ts
search.ts
test/
search.demo.ts
agent-context.json
before/
src/
commands.ts
index.ts
search.ts
test/
search.demo.ts
change.patch
README.md
4-ui-polish/
after.tsx
before.tsx
README.md
5-pager-tour/
after.ts
before.ts
README.md
6-readme-screenshot/
after/
src/
components/
ReviewSummaryCard.tsx
lib/
reviewCopy.ts
test/
reviewSummaryCard.demo.ts
agent-context.json
before/
src/
components/
ReviewSummaryCard.tsx
test/
reviewSummaryCard.demo.ts
change.patch
README.md
7-opentui-component/
after.ts
before.ts
change.patch
from-files.tsx
from-patch.tsx
README.md
support.tsx
8-opentui-primitives/
primitives-demo.tsx
README.md
9-agent-markup-notes/
after/
retry.ts
agent-context.json
before/
retry.ts
change.patch
README.md
extensions/
inline-edit/
index.ts
package.json
README.md
jsx-file-view/
jsx-file-view-gallery/
fixtures/
change-atlas/
after.ts
before.ts
css-palette/
after.css
before.css
package-dependencies/
after/
package.json
before/
package.json
index.tsx
mixed-review/
fixtures/
after/
README.md
scripts/
deploy.py
before/
README.md
scripts/
deploy.py
README.md
run.ts
package.json
README.md
index.tsx
package.json
README.md
rendered-markdown/
index.ts
package.json
README.md
review-triage/
index.tsx
package.json
README.md
README.md
flake.lock
flake.nix
knip.json
LICENSE
nix/
bun.lock.nix
devShell.nix
home-manager.nix
package.nix
README.md
package.json
packages/
session-broker/
session-broker-bun/
package.json
README.md
src/
index.ts
serve.test.ts
serve.ts
session-broker-core/
package.json
README.md
src/
brokerState.test.ts
brokerState.ts
brokerWire.test.ts
brokerWire.ts
index.ts
limits.test.ts
limits.ts
selectors.ts
sessionTerminalMetadata.test.ts
sessionTerminalMetadata.ts
types.ts
session-broker-node/
package.json
README.md
src/
index.ts
serve.test.ts
serve.ts
package.json
README.md
src/
broker.test.ts
broker.ts
connection.test.ts
connection.ts
daemon.test.ts
daemon.ts
index.ts
types.ts
term-video/
package.json
README.md
src/
capture.ts
compose.mjs
plan.d.mts
plan.mjs
plan.test.ts
stage.html
README.md
scripts/
build-bin.ts
build-npm.ts
build-prebuilt-artifact.test.ts
build-prebuilt-artifact.ts
check-pack.ts
check-prebuilt-pack.ts
check-release-version.ts
check-website-links.test.ts
check-website-links.ts
compare-release-benchmarks.test.ts
compare-release-benchmarks.ts
daemon-memory-check.ts
extension-consumer-check.ts
extension-doc-examples.test.ts
extension-doc-examples.ts
generate-docs.test.ts
generate-docs.ts
generate-skill.ts
inline-edit-extension.test.ts
install-bin.ts
jsx-file-view-gallery.test.ts
launch-video/
capture.ts
compose.mjs
README.md
prebuilt-package-helpers.test.ts
prebuilt-package-helpers.ts
probe-terminal-theme.ts
publish-prebuilt-npm.ts
rendered-markdown-extension.test.ts
run-release-benchmark.ts
script-helpers.ts
smoke-prebuilt-install.ts
source-boundaries.test.ts
stage-prebuilt-npm.ts
test-large-untracked-render.tsx
verify-pr-release-notes.test.ts
verify-pr-release-notes.ts
skills/
hunk-review/
SKILL.md
launch-video/
SKILL.md
src/
app/
sessionBootstrap.test.ts
sessionBootstrap.ts
startup.test.ts
startup.ts
core/
agent.test.ts
agent.ts
binary.test.ts
binary.ts
cli.test.ts
cli.ts
config.test.ts
config.ts
customThemes.test.ts
customThemes.ts
diffFile.test.ts
diffFile.ts
diffPaths.ts
errors.test.ts
errors.ts
experimental.test.ts
experimental.ts
fileLanguage.test.ts
fileLanguage.ts
fileSource.test.ts
fileSource.ts
hunkHeader.ts
hunkState.test.ts
hunkState.ts
hunkSummary.test.ts
hunkSummary.ts
inputReload.ts
jobControl.test.ts
jobControl.ts
legacySyntaxScopes.test.ts
legacySyntaxScopes.ts
liveComments.test.ts
liveComments.ts
loaders.ordering.test.ts
loaders.test.ts
loaders.ts
pager.test.ts
pager.ts
patch/
chunks.test.ts
chunks.ts
gitFormat.test.ts
gitFormat.ts
gitLog.test.ts
gitLog.ts
normalize.test.ts
normalize.ts
singleFile.ts
paths.test.ts
paths.ts
... 502 moreFAQ
hunk is a Claude Code plugin with 2 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes hunk-review, launch-video. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is hunk?
- Hunk is a review-first terminal diff viewer for agent-authored changesets, built on OpenTUI and Pierre diffs.
- How do I install hunk?
- Run these in Claude Code: npx -y skills add modem-dev/hunk --agent claude-code. Then prompt normally.
- Does hunk auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is hunk free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.