hunkdiff 0.5.0 → 0.6.0-beta.1
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 +101 -78
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,18 +1,30 @@
|
|
|
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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
|
13
|
+
|
|
14
|
+
<table>
|
|
15
|
+
<tr>
|
|
16
|
+
<td width="60%" align="center">
|
|
17
|
+
<img width="794" alt="image" src="https://github.com/user-attachments/assets/f6ffd9c4-67f5-483c-88f1-cbe88c19f52f" />
|
|
18
|
+
<br />
|
|
19
|
+
<sub>Split view with sidebar and inline AI notes</sub>
|
|
20
|
+
</td>
|
|
21
|
+
<td width="40%" align="center">
|
|
22
|
+
<img width="508" height="920" alt="image" src="https://github.com/user-attachments/assets/44c542a2-0a09-41cd-b264-fbd942e92f06" />
|
|
23
|
+
<br />
|
|
24
|
+
<sub>Stacked view and mouse-selectable menus</sub>
|
|
25
|
+
</td>
|
|
26
|
+
</tr>
|
|
27
|
+
</table>
|
|
16
28
|
|
|
17
29
|
## Install
|
|
18
30
|
|
|
@@ -23,20 +35,20 @@ npm i -g hunkdiff
|
|
|
23
35
|
Requirements:
|
|
24
36
|
|
|
25
37
|
- Node.js 18+
|
|
26
|
-
-
|
|
27
|
-
- Git
|
|
28
|
-
|
|
29
|
-
## Usage
|
|
38
|
+
- macOS or Linux
|
|
39
|
+
- Git recommended for most workflows
|
|
30
40
|
|
|
31
|
-
|
|
41
|
+
## Quick start
|
|
32
42
|
|
|
33
43
|
```bash
|
|
34
44
|
hunk # show help
|
|
35
|
-
hunk --version #
|
|
45
|
+
hunk --version # print the installed version
|
|
36
46
|
```
|
|
37
47
|
|
|
38
48
|
### Working with Git
|
|
39
49
|
|
|
50
|
+
Hunk mirrors Git's diff-style commands, but opens the changeset in a review UI instead of plain text.
|
|
51
|
+
|
|
40
52
|
```bash
|
|
41
53
|
hunk diff # review current repo changes
|
|
42
54
|
hunk diff --staged
|
|
@@ -44,35 +56,57 @@ hunk show # review the latest commit
|
|
|
44
56
|
hunk show HEAD~1 # review an earlier commit
|
|
45
57
|
```
|
|
46
58
|
|
|
47
|
-
### Working with raw files
|
|
59
|
+
### Working with raw files and patches
|
|
48
60
|
|
|
49
61
|
```bash
|
|
50
62
|
hunk diff before.ts after.ts # compare two files directly
|
|
51
63
|
git diff --no-color | hunk patch - # review a patch from stdin
|
|
52
64
|
```
|
|
53
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
|
+
|
|
54
72
|
## Feature comparison
|
|
55
73
|
|
|
56
|
-
| Capability
|
|
57
|
-
|
|
|
58
|
-
|
|
|
59
|
-
| Multi-file review stream
|
|
60
|
-
|
|
|
61
|
-
|
|
|
62
|
-
|
|
|
63
|
-
|
|
|
64
|
-
|
|
|
65
|
-
|
|
|
66
|
-
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
| Pager-compatible mode | ✅ | ✅ | ✅ | ✅ |
|
|
74
|
+
| Capability | hunk | difftastic | delta | diff-so-fancy | diff |
|
|
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.
|
|
70
87
|
|
|
71
|
-
##
|
|
88
|
+
## Advanced
|
|
72
89
|
|
|
73
|
-
|
|
90
|
+
### Config
|
|
74
91
|
|
|
75
|
-
|
|
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:
|
|
76
110
|
|
|
77
111
|
```bash
|
|
78
112
|
git config --global core.pager "hunk pager"
|
|
@@ -85,64 +119,44 @@ Or in your Git config:
|
|
|
85
119
|
pager = hunk pager
|
|
86
120
|
```
|
|
87
121
|
|
|
88
|
-
If you
|
|
122
|
+
If you want to keep Git's default pager and add opt-in aliases instead:
|
|
89
123
|
|
|
90
124
|
```bash
|
|
91
125
|
git config --global alias.hdiff "-c core.pager=\"hunk pager\" diff"
|
|
92
126
|
git config --global alias.hshow "-c core.pager=\"hunk pager\" show"
|
|
93
127
|
```
|
|
94
128
|
|
|
95
|
-
|
|
129
|
+
### Agent workflows
|
|
96
130
|
|
|
97
|
-
|
|
131
|
+
Hunk supports two agent workflows:
|
|
98
132
|
|
|
99
|
-
|
|
133
|
+
- steer a live Hunk window from another terminal with `hunk session ...` (recommended)
|
|
134
|
+
- load agent comments from a file with `--agent-context`
|
|
100
135
|
|
|
101
|
-
|
|
136
|
+
#### Steer a live Hunk window
|
|
102
137
|
|
|
103
|
-
|
|
138
|
+
Use the Hunk review skill: [`skills/hunk-review/SKILL.md`](skills/hunk-review/SKILL.md).
|
|
104
139
|
|
|
105
|
-
|
|
140
|
+
A good generic prompt is:
|
|
106
141
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
- inspect current review focus before navigating blindly
|
|
110
|
-
- use `hunk session reload` to swap what an existing live session is showing
|
|
111
|
-
- leave concise inline review comments tied to real diff lines
|
|
112
|
-
|
|
113
|
-
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.
|
|
114
|
-
|
|
115
|
-
## Config
|
|
116
|
-
|
|
117
|
-
Hunk reads config from:
|
|
118
|
-
|
|
119
|
-
- `~/.config/hunk/config.toml`
|
|
120
|
-
- `.hunk/config.toml`
|
|
121
|
-
|
|
122
|
-
Example:
|
|
123
|
-
|
|
124
|
-
```toml
|
|
125
|
-
theme = "graphite" # graphite, midnight, paper, ember
|
|
126
|
-
mode = "auto" # auto, split, stack
|
|
127
|
-
line_numbers = true
|
|
128
|
-
wrap_lines = false
|
|
129
|
-
agent_notes = false
|
|
142
|
+
```text
|
|
143
|
+
> Load the Hunk skill and use it for this review
|
|
130
144
|
```
|
|
131
145
|
|
|
132
|
-
|
|
146
|
+
That skill teaches the agent how to inspect a live Hunk session, navigate it, reload it, and leave inline comments.
|
|
133
147
|
|
|
134
|
-
|
|
135
|
-
- `hunk mcp serve` runs the local Hunk session daemon and websocket broker for manual startup or debugging
|
|
136
|
-
- normal Hunk sessions auto-start/register with it by default
|
|
137
|
-
- coding agents should usually interact through `hunk session ...`, not by managing the daemon directly
|
|
138
|
-
- Hunk keeps the daemon loopback-only by default
|
|
139
|
-
- 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
|
|
140
149
|
|
|
141
|
-
|
|
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.
|
|
142
151
|
|
|
143
|
-
|
|
152
|
+
Use it to:
|
|
144
153
|
|
|
145
|
-
|
|
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.
|
|
146
160
|
|
|
147
161
|
```bash
|
|
148
162
|
hunk session list
|
|
@@ -150,19 +164,28 @@ hunk session context --repo .
|
|
|
150
164
|
hunk session navigate --repo . --file README.md --hunk 2
|
|
151
165
|
hunk session reload --repo . -- diff
|
|
152
166
|
hunk session reload --repo . -- show HEAD~1 -- README.md
|
|
153
|
-
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"
|
|
154
168
|
hunk session comment list --repo .
|
|
155
169
|
hunk session comment rm --repo . <comment-id>
|
|
156
170
|
hunk session comment clear --repo . --file README.md --yes
|
|
157
171
|
```
|
|
158
172
|
|
|
159
|
-
`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).
|
|
160
178
|
|
|
161
|
-
|
|
179
|
+
```bash
|
|
180
|
+
hunk diff --agent-context notes.json
|
|
181
|
+
hunk patch change.patch --agent-context notes.json
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## Examples
|
|
162
185
|
|
|
163
|
-
|
|
186
|
+
Ready-to-run demo diffs live in [`examples/`](examples/README.md).
|
|
164
187
|
|
|
165
|
-
|
|
188
|
+
Each example includes the exact command to run from the repository root.
|
|
166
189
|
|
|
167
190
|
## Contributing
|
|
168
191
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hunkdiff",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0-beta.1",
|
|
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.1",
|
|
34
|
+
"hunkdiff-darwin-x64": "0.6.0-beta.1",
|
|
35
|
+
"hunkdiff-linux-x64": "0.6.0-beta.1"
|
|
36
36
|
},
|
|
37
37
|
"license": "MIT",
|
|
38
38
|
"publishConfig": {
|