https://github.com/modem-dev/hunk
Review-first terminal diff viewer for agentic coders
https://github.com/modem-dev/hunk
cli code-review diff git tui
Last synced: 20 days ago
JSON representation
Review-first terminal diff viewer for agentic coders
- Host: GitHub
- URL: https://github.com/modem-dev/hunk
- Owner: modem-dev
- License: mit
- Created: 2026-03-17T19:16:15.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-10T14:20:01.000Z (about 2 months ago)
- Last Synced: 2026-04-10T16:12:13.432Z (about 2 months ago)
- Topics: cli, code-review, diff, git, tui
- Language: TypeScript
- Homepage:
- Size: 2.64 MB
- Stars: 393
- Watchers: 1
- Forks: 10
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-cli-agents - modem-dev/hunk - Review-first terminal diff viewer for agentic coders [Terminal] (4k⭐) (🚀 AI Tools for Vim, Neovim, and Terminal)
README
# hunk
Hunk is a review-first terminal diff viewer for agent-authored changesets, built on [OpenTUI](https://github.com/anomalyco/opentui) and [Pierre diffs](https://www.npmjs.com/package/@pierre/diffs).
[](https://github.com/modem-dev/hunk/actions/workflows/ci.yml?branch=main)
[](https://github.com/modem-dev/hunk/releases)
[](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
Split view with sidebar and inline AI notes
Stacked view and mouse-selectable menus
## Install
```bash
npm i -g hunkdiff
```
Or with Homebrew:
```bash
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](./nix/README.md) for details.
## Quick start
```bash
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.
```bash
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
Hunk auto-detects Jujutsu checkouts, so `hunk diff [revset]` and `hunk show [revset]` use jj revsets inside a jj workspace. To override VCS detection, set `vcs = "git"` or `vcs = "jj"` in [config](#config).
### Working with raw files and patches
```bash
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. 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:
```text
Load the Hunk skill and use it for this review.
```
For the full live-session and `--agent-context` workflow guide, see [docs/agent-workflows.md](docs/agent-workflows.md).
## Feature comparison
| Capability | [hunk](https://github.com/modem-dev/hunk) | [lumen](https://github.com/jnsahaj/lumen) | [difftastic](https://github.com/Wilfred/difftastic) | [delta](https://github.com/dandavison/delta) | [diff-so-fancy](https://github.com/so-fancy/diff-so-fancy) | [diff](https://www.gnu.org/software/diffutils/) |
| ---------------------------------- | ----------------------------------------- | ----------------------------------------- | --------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------- |
| 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:
```toml
theme = "graphite" # graphite, midnight, paper, ember
mode = "auto" # auto, split, stack
vcs = "git" # git, jj
watch = false
exclude_untracked = false
line_numbers = true
wrap_lines = false
agent_notes = false
```
`exclude_untracked` affects Git 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.
```bash
git config --global core.pager "hunk pager"
```
Or in your Git config:
```ini
[core]
pager = hunk pager
```
If you want to keep Git's default pager and add opt-in aliases instead:
```bash
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:
```toml
[ui]
pager = ["hunk", "pager"]
diff-formatter = ":git"
```
### 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](docs/opentui-component.md) for install, API, and runnable examples.
## Examples
Ready-to-run demo diffs live in [`examples/`](examples/README.md).
Each example includes the exact command to run from the repository root.
## Contributing
💬 _Chat with users/contributors on the [Modem Discord server](https://discord.gg/WZFjaP6Gt8)_
For source setup, tests, packaging checks, and repo architecture, see [CONTRIBUTING.md](CONTRIBUTING.md).
## Sponsor
Sponsored by [Modem](https://modem.dev?utm_source=github&utm_medium=oss&utm_campaign=hunk).
## License
[MIT](LICENSE)