hunkdiff 0.5.1 → 0.6.0-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +87 -79
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,18 +1,15 @@
|
|
|
1
|
-
|
|
1
|
+
# hunk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
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).
|
|
4
4
|
|
|
5
5
|
[](https://github.com/modem-dev/hunk/actions/workflows/ci.yml?branch=main)
|
|
6
6
|
[](https://github.com/modem-dev/hunk/releases)
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
- keyboard & mouse support
|
|
14
|
-
- split, stacked, and responsive auto layouts
|
|
15
|
-
- Git pager and difftool integration
|
|
9
|
+
- multi-file review stream with sidebar navigation
|
|
10
|
+
- inline AI and agent annotations beside the code
|
|
11
|
+
- split, stack, and responsive auto layouts
|
|
12
|
+
- keyboard, mouse, pager, and Git difftool support
|
|
16
13
|
|
|
17
14
|
<table>
|
|
18
15
|
<tr>
|
|
@@ -24,7 +21,7 @@ Hunk is a desktop-inspired terminal diff viewer for reviewing agent-authored cha
|
|
|
24
21
|
<td width="40%" align="center">
|
|
25
22
|
<img width="508" height="920" alt="image" src="https://github.com/user-attachments/assets/44c542a2-0a09-41cd-b264-fbd942e92f06" />
|
|
26
23
|
<br />
|
|
27
|
-
<sub>Stacked view and mouse-selectable menus
|
|
24
|
+
<sub>Stacked view and mouse-selectable menus</sub>
|
|
28
25
|
</td>
|
|
29
26
|
</tr>
|
|
30
27
|
</table>
|
|
@@ -38,20 +35,20 @@ npm i -g hunkdiff
|
|
|
38
35
|
Requirements:
|
|
39
36
|
|
|
40
37
|
- Node.js 18+
|
|
41
|
-
-
|
|
42
|
-
- Git
|
|
43
|
-
|
|
44
|
-
## Usage
|
|
38
|
+
- macOS or Linux
|
|
39
|
+
- Git recommended for most workflows
|
|
45
40
|
|
|
46
|
-
|
|
41
|
+
## Quick start
|
|
47
42
|
|
|
48
43
|
```bash
|
|
49
44
|
hunk # show help
|
|
50
|
-
hunk --version #
|
|
45
|
+
hunk --version # print the installed version
|
|
51
46
|
```
|
|
52
47
|
|
|
53
48
|
### Working with Git
|
|
54
49
|
|
|
50
|
+
Hunk mirrors Git's diff-style commands, but opens the changeset in a review UI instead of plain text.
|
|
51
|
+
|
|
55
52
|
```bash
|
|
56
53
|
hunk diff # review current repo changes
|
|
57
54
|
hunk diff --staged
|
|
@@ -59,35 +56,57 @@ hunk show # review the latest commit
|
|
|
59
56
|
hunk show HEAD~1 # review an earlier commit
|
|
60
57
|
```
|
|
61
58
|
|
|
62
|
-
### Working with raw files
|
|
59
|
+
### Working with raw files and patches
|
|
63
60
|
|
|
64
61
|
```bash
|
|
65
62
|
hunk diff before.ts after.ts # compare two files directly
|
|
66
63
|
git diff --no-color | hunk patch - # review a patch from stdin
|
|
67
64
|
```
|
|
68
65
|
|
|
66
|
+
### Working with agents
|
|
67
|
+
|
|
68
|
+
Load the [`skills/hunk-review/SKILL.md`](skills/hunk-review/SKILL.md) skill in your coding agent (e.g. Claude, Codex, Opencode, Pi).
|
|
69
|
+
|
|
70
|
+
Open Hunk in another window, then ask your agent to leave comments.
|
|
71
|
+
|
|
69
72
|
## Feature comparison
|
|
70
73
|
|
|
71
|
-
| Capability
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
| Multi-file review stream
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
| Pager-compatible mode | ✅ | ✅ | ✅ | ✅ |
|
|
74
|
+
| 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/) |
|
|
75
|
+
| ---------------------------------- | ----------------------------------------- | ----------------------------------------- | --------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------- |
|
|
76
|
+
| Review-first interactive UI | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
77
|
+
| Multi-file review stream + sidebar | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
78
|
+
| Inline agent / AI annotations | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
|
79
|
+
| Responsive auto split/stack layout | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
|
80
|
+
| Mouse support inside the viewer | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
81
|
+
| Runtime view toggles | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
82
|
+
| Syntax highlighting | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
|
|
83
|
+
| Structural diffing | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
|
|
84
|
+
| Pager-compatible mode | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ |
|
|
85
|
+
|
|
86
|
+
Hunk is optimized for reviewing a full changeset interactively.
|
|
85
87
|
|
|
86
|
-
##
|
|
88
|
+
## Advanced
|
|
87
89
|
|
|
88
|
-
|
|
90
|
+
### Config
|
|
89
91
|
|
|
90
|
-
|
|
92
|
+
You can persist preferences to a config file:
|
|
93
|
+
|
|
94
|
+
- `~/.config/hunk/config.toml`
|
|
95
|
+
- `.hunk/config.toml`
|
|
96
|
+
|
|
97
|
+
Example:
|
|
98
|
+
|
|
99
|
+
```toml
|
|
100
|
+
theme = "graphite" # graphite, midnight, paper, ember
|
|
101
|
+
mode = "auto" # auto, split, stack
|
|
102
|
+
line_numbers = true
|
|
103
|
+
wrap_lines = false
|
|
104
|
+
agent_notes = false
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Git integration
|
|
108
|
+
|
|
109
|
+
Set Hunk as your Git pager so `git diff` and `git show` open in Hunk automatically:
|
|
91
110
|
|
|
92
111
|
```bash
|
|
93
112
|
git config --global core.pager "hunk pager"
|
|
@@ -100,64 +119,44 @@ Or in your Git config:
|
|
|
100
119
|
pager = hunk pager
|
|
101
120
|
```
|
|
102
121
|
|
|
103
|
-
If you
|
|
122
|
+
If you want to keep Git's default pager and add opt-in aliases instead:
|
|
104
123
|
|
|
105
124
|
```bash
|
|
106
125
|
git config --global alias.hdiff "-c core.pager=\"hunk pager\" diff"
|
|
107
126
|
git config --global alias.hshow "-c core.pager=\"hunk pager\" show"
|
|
108
127
|
```
|
|
109
128
|
|
|
110
|
-
|
|
129
|
+
### Agent workflows
|
|
111
130
|
|
|
112
|
-
|
|
131
|
+
Hunk supports two agent workflows:
|
|
113
132
|
|
|
114
|
-
|
|
133
|
+
- steer a live Hunk window from another terminal with `hunk session ...` (recommended)
|
|
134
|
+
- load agent comments from a file with `--agent-context`
|
|
115
135
|
|
|
116
|
-
|
|
136
|
+
#### Steer a live Hunk window
|
|
117
137
|
|
|
118
|
-
|
|
138
|
+
Use the Hunk review skill: [`skills/hunk-review/SKILL.md`](skills/hunk-review/SKILL.md).
|
|
119
139
|
|
|
120
|
-
|
|
140
|
+
A good generic prompt is:
|
|
121
141
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
- inspect current review focus before navigating blindly
|
|
125
|
-
- use `hunk session reload` to swap what an existing live session is showing
|
|
126
|
-
- leave concise inline review comments tied to real diff lines
|
|
127
|
-
|
|
128
|
-
If your coding agent supports packaged or repo-local skills, point it at this repository or copy the `skills/hunk-review/` directory into that agent's skill search path.
|
|
129
|
-
|
|
130
|
-
## Config
|
|
131
|
-
|
|
132
|
-
Hunk reads config from:
|
|
133
|
-
|
|
134
|
-
- `~/.config/hunk/config.toml`
|
|
135
|
-
- `.hunk/config.toml`
|
|
136
|
-
|
|
137
|
-
Example:
|
|
138
|
-
|
|
139
|
-
```toml
|
|
140
|
-
theme = "graphite" # graphite, midnight, paper, ember
|
|
141
|
-
mode = "auto" # auto, split, stack
|
|
142
|
-
line_numbers = true
|
|
143
|
-
wrap_lines = false
|
|
144
|
-
agent_notes = false
|
|
142
|
+
```text
|
|
143
|
+
> Load the Hunk skill and use it for this review
|
|
145
144
|
```
|
|
146
145
|
|
|
147
|
-
|
|
146
|
+
That skill teaches the agent how to inspect a live Hunk session, navigate it, reload it, and leave inline comments.
|
|
148
147
|
|
|
149
|
-
|
|
150
|
-
- `hunk mcp serve` runs the local Hunk session daemon and websocket broker for manual startup or debugging
|
|
151
|
-
- normal Hunk sessions auto-start/register with it by default
|
|
152
|
-
- coding agents should usually interact through `hunk session ...`, not by managing the daemon directly
|
|
153
|
-
- Hunk keeps the daemon loopback-only by default
|
|
154
|
-
- if you intentionally need remote access, set `HUNK_MCP_UNSAFE_ALLOW_REMOTE=1` and choose a non-loopback `HUNK_MCP_HOST`
|
|
148
|
+
#### How remote control works
|
|
155
149
|
|
|
156
|
-
|
|
150
|
+
When a Hunk TUI starts, it registers with a local loopback daemon. `hunk session ...` talks to that daemon to find the right live window and control it.
|
|
157
151
|
|
|
158
|
-
|
|
152
|
+
Use it to:
|
|
159
153
|
|
|
160
|
-
|
|
154
|
+
- inspect the current review context
|
|
155
|
+
- jump to a file, hunk, or line
|
|
156
|
+
- reload the current window with a different `diff` or `show` command
|
|
157
|
+
- add, list, and remove inline comments
|
|
158
|
+
|
|
159
|
+
Most users only need `hunk session ...`. Use `hunk mcp serve` only for manual startup or debugging of the local daemon.
|
|
161
160
|
|
|
162
161
|
```bash
|
|
163
162
|
hunk session list
|
|
@@ -165,19 +164,28 @@ hunk session context --repo .
|
|
|
165
164
|
hunk session navigate --repo . --file README.md --hunk 2
|
|
166
165
|
hunk session reload --repo . -- diff
|
|
167
166
|
hunk session reload --repo . -- show HEAD~1 -- README.md
|
|
168
|
-
hunk session comment add --repo . --file README.md --new-line 103 --summary "
|
|
167
|
+
hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording"
|
|
169
168
|
hunk session comment list --repo .
|
|
170
169
|
hunk session comment rm --repo . <comment-id>
|
|
171
170
|
hunk session comment clear --repo . --file README.md --yes
|
|
172
171
|
```
|
|
173
172
|
|
|
174
|
-
`hunk session reload ... -- <hunk command>` swaps
|
|
173
|
+
`hunk session reload ... -- <hunk command>` swaps what a live session is showing without opening a new TUI window.
|
|
174
|
+
|
|
175
|
+
#### Load agent comments from a file
|
|
176
|
+
|
|
177
|
+
Use `--agent-context` to attach agent-written comments or rationale from a JSON sidecar file. For a compact real example, see [`examples/3-agent-review-demo/agent-context.json`](examples/3-agent-review-demo/agent-context.json).
|
|
175
178
|
|
|
176
|
-
|
|
179
|
+
```bash
|
|
180
|
+
hunk diff --agent-context notes.json
|
|
181
|
+
hunk patch change.patch --agent-context notes.json
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## Examples
|
|
177
185
|
|
|
178
|
-
|
|
186
|
+
Ready-to-run demo diffs live in [`examples/`](examples/README.md).
|
|
179
187
|
|
|
180
|
-
|
|
188
|
+
Each example includes the exact command to run from the repository root.
|
|
181
189
|
|
|
182
190
|
## Contributing
|
|
183
191
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hunkdiff",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0-beta.2",
|
|
4
4
|
"description": "Desktop-inspired terminal diff viewer for understanding agent-authored changesets.",
|
|
5
5
|
"bin": {
|
|
6
6
|
"hunk": "./bin/hunk.cjs"
|
|
@@ -30,9 +30,9 @@
|
|
|
30
30
|
"node": ">=18"
|
|
31
31
|
},
|
|
32
32
|
"optionalDependencies": {
|
|
33
|
-
"hunkdiff-darwin-arm64": "0.
|
|
34
|
-
"hunkdiff-darwin-x64": "0.
|
|
35
|
-
"hunkdiff-linux-x64": "0.
|
|
33
|
+
"hunkdiff-darwin-arm64": "0.6.0-beta.2",
|
|
34
|
+
"hunkdiff-darwin-x64": "0.6.0-beta.2",
|
|
35
|
+
"hunkdiff-linux-x64": "0.6.0-beta.2"
|
|
36
36
|
},
|
|
37
37
|
"license": "MIT",
|
|
38
38
|
"publishConfig": {
|