You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AGENTS.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,10 +46,10 @@ CLI input
46
46
-`[` and `]` navigate hunks across the full review stream. Do not reintroduce `j`/`k` hunk navigation unless the user asks.
47
47
- Agent context belongs beside the code, not hidden in a separate mode or workflow.
48
48
- Agent notes are hunk-specific: show notes for the selected hunk, render them in the diff flow near the annotated row, and keep a clear spatial relationship to the code they explain.
49
-
- When making code changes in this repo, also refresh `.hunk/latest.json` so the next review can load agent rationale with `hunk git --agent-context .hunk/latest.json`.
49
+
- When making code changes in this repo, also refresh `.hunk/latest.json` so the next review can load agent rationale with `hunk diff --agent-context .hunk/latest.json`.
50
50
- Keep `.hunk/latest.json` concise and review-oriented: one changeset summary, file summaries in narrative order, and a few hunk-level annotations with real rationale.
51
51
- File order in `.hunk/latest.json` is intentional, but the visible note UI should stay hunk-note driven rather than showing generic file or changeset explainer cards.
52
-
- If newly created files should appear in `hunk git` before commit, use `git add -N <paths>` so they show up in the review stream without staging content.
52
+
- If newly created files should appear in `hunk diff` before commit, use `git add -N <paths>` so they show up in the review stream without staging content.
| Mouse support inside the diff viewer | ✅ | ❌ | ❌ | ❌ |
65
+
| Runtime toggles for wrapping / line numbers / hunk metadata | ✅ | ❌ | ❌ | ❌ |
66
+
| Pager-compatible mode | ✅ | ✅ | ✅ | ✅ |
67
+
68
+
## Benchmarks
69
+
70
+
Quick local timing snapshot from one Linux machine on the same 120-line TypeScript file pair. Metric: time until a changed marker first became visible.
71
+
72
+
| Tool | Avg first-visible changed output |
73
+
| --- | ---: |
74
+
|`diff`|~37 ms |
75
+
|`delta --paging=never`|~35 ms |
76
+
|`hunk diff`|~219 ms |
77
+
|`difft --display side-by-side`|~266 ms |
78
+
79
+
Takeaway:
40
80
41
-
## Workflows
81
+
-`diff` and `delta` are fastest here because they print plain diff text and exit.
82
+
-`hunk` spends more startup time on an interactive UI, syntax highlighting, navigation state, and optional agent context.
83
+
-`difftastic` spends more startup time on structural diffing.
42
84
43
-
-`hunk` — print standard CLI help with the most common commands
44
-
-`hunk diff` — review local working tree changes in the full Hunk UI
45
-
-`hunk diff --staged` / `hunk diff --cached` — review staged changes in the full Hunk UI
Hunk reads layered TOML config with this precedence:
76
150
77
151
1. built-in defaults
78
152
2. global config: `$XDG_CONFIG_HOME/hunk/config.toml` or `~/.config/hunk/config.toml`
79
153
3. repo-local config: `.hunk/config.toml`
80
-
4. command-specific sections like `[git]`, `[diff]`, `[show]`, `[stash-show]`, `[patch]`, `[difftool]`
154
+
4. command-specific sections like `[diff]`, `[show]`, `[stash-show]`, `[patch]`, `[difftool]`
81
155
5.`[pager]` when Hunk is running in pager mode
82
156
6. explicit CLI flags
83
157
84
-
When you change persistent view settings inside Hunk, it writes them back to `.hunk/config.toml` in the current repo when possible, or to the global config file outside a repo.
85
-
86
158
Example:
87
159
88
160
```toml
@@ -101,16 +173,7 @@ line_numbers = false
101
173
mode = "split"
102
174
```
103
175
104
-
CLI overrides are available when you want one-off or pager-specific behavior:
Use `--agent-context <file>` to load a JSON sidecar and show agent rationale next to the diff.
125
188
126
-
The order of `files` in the sidecar is significant. Hunk uses that order for the sidebar and main review stream so an agent can tell a story instead of relying on raw patch order.
189
+
The order of `files` in the sidecar is significant. Hunk uses that order for the sidebar and the main review stream so an agent can present a review narrative instead of raw patch order.
127
190
128
191
```json
129
192
{
@@ -142,130 +205,40 @@ The order of `files` in the sidecar is significant. Hunk uses that order for the
142
205
"confidence": "high"
143
206
}
144
207
]
145
-
},
146
-
{
147
-
"path": "src/ui/App.tsx",
148
-
"summary": "Presents the new workflow after the loader changes.",
149
-
"annotations": [
150
-
{
151
-
"newRange": [90, 136],
152
-
"summary": "Uses the normalized model in the review shell.",
153
-
"rationale": "The reader should inspect this after understanding the loader changes.",
154
-
"tags": ["ui"],
155
-
"confidence": "medium"
156
-
}
157
-
]
158
208
}
159
209
]
160
210
}
161
211
```
162
212
163
-
Files omitted from the sidecar keep their original diff order and appear after the explicitly ordered files.
164
-
165
-
## Codex workflow
166
-
167
-
For Codex-driven changes, keep a transient sidecar at `.hunk/latest.json` and load it during review:
213
+
For local agent-driven review, keep a transient sidecar at `.hunk/latest.json` and load it with:
168
214
169
215
```bash
170
216
hunk diff --agent-context .hunk/latest.json
171
217
```
172
218
173
-
Suggested pattern:
174
-
175
-
- Codex makes code changes.
176
-
- Codex refreshes `.hunk/latest.json` with a concise changeset summary, file summaries, and hunk-level rationale.
177
-
- You open `hunk diff`, `hunk diff --staged`, or `hunk show <ref>` with that sidecar.
178
-
179
-
Keep the sidecar concise. It should explain why a hunk exists, what risk to review, and how the files fit together. It should not narrate obvious syntax edits line by line.
| Mouse support inside the diff viewer | ✅ | ❌ | ❌ | ❌ |
197
-
| Runtime toggles for wrapping / line numbers / hunk metadata | ✅ | ❌ | ❌ | ❌ |
198
-
| Pager-compatible mode | ✅ | ✅ | ✅ | ✅ |
199
-
200
-
### Local timing snapshot
201
-
202
-
These numbers are **not a universal benchmark**. They are a quick local comparison from one Linux machine using tmux panes, measuring **time until a changed marker first became visible** on the same 120-line TypeScript file pair.
-`diff` and `delta` are fastest here because they emit plain diff text and exit.
221
-
-`hunk` pays extra startup cost for an interactive terminal UI, syntax highlighting, navigation state, and optional agent context.
222
-
-`difftastic` pays extra cost for syntax-aware / structural diffing.
223
-
- For larger review sessions, Hunk is optimized for **navigating and understanding** a changeset, not just dumping the quickest possible patch text.
224
-
225
-
## Git integration
226
-
227
-
For full-screen review, you can invoke Hunk directly with Git-shaped commands:
228
-
229
-
```bash
230
-
hunk diff
231
-
hunk diff --staged
232
-
hunk diff main...feature
233
-
hunk show
234
-
hunk show HEAD~1
235
-
hunk stash show
236
-
```
237
-
238
-
Use Hunk as the default Git pager when you want it to behave like a normal pager under `git diff` / `git show`:
221
+
Install dependencies:
239
222
240
223
```bash
241
-
git config --global core.pager 'hunk patch -'
224
+
bun install
242
225
```
243
226
244
-
Or scope it just to `git diff` and `git show`:
227
+
Validate a change:
245
228
246
229
```bash
247
-
git config --global pager.diff 'hunk patch -'
248
-
git config --global pager.show 'hunk patch -'
230
+
bun run typecheck
231
+
bun test
232
+
bun run test:tty-smoke
249
233
```
250
234
251
-
When Hunk reads a patch from stdin, it automatically switches to pager-style chrome, strips Git's color escape sequences before parsing, and binds keyboard input to the controlling terminal so it works correctly as a Git pager.
252
-
253
-
Then:
235
+
Build the npm runtime bundle used for publishing:
254
236
255
237
```bash
256
-
git diff
257
-
git show HEAD
238
+
bun run build:npm
239
+
bun run check:pack
258
240
```
259
241
260
-
If you want Git to launch Hunk as a difftool for file-to-file comparisons:
0 commit comments