Hunk: the review diff as a two-way human↔︎agent annotation channel
TL;DR
The video demos Hunk, a review-first terminal diff
viewer, and its actual payload is not the viewer's ergonomics (view
modes, search, theming) but that it turns the diff into a
bidirectional, line-anchored annotation channel between a human
and a coding agent. Hunk ships a hunk-review
skill wrapping its CLI; once the agent loads it, the
loop runs both ways on the same surface: the agent writes
review notes pinned to lines the human reads in place (it flags "KV
increments can lose concurrent updates" on
worker/index.ts:25), and the human writes notes pinned to
lines that the agent reads back and implements ("add a button for the
reset API" on src/App.tsx becomes a working reset button).
The presenter's own framing — the first two-thirds is "not that
impressive," the annotation round-trip is "the good part" — is the whole
point: legible diff review already exists (Agent Supervision); making the review
artifact writable by both parties is the new move. He prefers
manual refresh (R) over --watch so updates
land when he asks for them.
Concepts introduced
- Shared Review Surface — the load-bearing idea: a line-anchored diff both a human and an agent can annotate is a two-way channel, not a one-way report. Location is part of the message, so a note pinned to a line needs no re-description of where.
- Agent Supervision (updated) — Hunk is an operator review workbench; this source pushes its "render legible diffs to accept/reject/annotate" lever from one-way review to a bidirectional loop.
- CLI Tools over MCP Servers
(updated) — the agent integration is a vendor-shipped
skill wrapping the
hunkCLI:hunk skill pathto load,hunk session commentto read/write notes.
Held, not dropped (touched, no concept page yet):
- TUI review ergonomics — responsive auto split/stack layout, chunk/file navigation, runtime view toggles, mouse support in the terminal. Real UX detail, but tool-specific; not a durable concept yet.
- Vendor-shipped agent skill as a product-integration strategy — a tool author (not the operator) writing the skill that makes their app agent-drivable. Adjacent to Public Skill Adoption but from the producer side; spin out if a second source appears.
- Refresh-vs-watch as reviewer pacing — folded into Shared Review Surface as a pacing claim for now; could become its own note if the pacing angle recurs.
Key claims
- A diff both a human and an agent can annotate becomes a two-way communication channel, not a one-way report. principle → Shared Review Surface
- A note pinned to a line carries its own location, making line-anchored annotation lower-ambiguity than prose chat about "that function." principle → Shared Review Surface
- Bidirectional review requires the agent to have read and write access to the annotation store, here via a loaded skill wrapping the tool's CLI. (best_practice, context: a review tool that exposes an agent-drivable comment interface) → Shared Review Surface, CLI Tools over MCP Servers
- A vendor can make its interactive tool agent-drivable by shipping its own skill that wraps its CLI. (best_practice, context: third-party tool integration) → CLI Tools over MCP Servers
- Preferring manual refresh (
R) over--watchlets the reviewer control when new changes appear. (best_practice, context: reviewer pacing) → Shared Review Surface - The video states Hunk was praised by Mitchell Hashimoto (Ghostty, Terraform) and DHH (Rails, 37signals). (observation — check-worthy, external endorsement)
- The video shows the coding agent as "gpt-5.5" (via Herder) at ~$0.96 for the session. (observation — check-worthy, named model + price shown on screen)
- The video's feature table claims Hunk is unique among lumen/difftastic/delta/diff-so-fancy/diff in offering inline agent/AI annotations. (observation — check-worthy, vendor comparison table)
- The agent's own review note asserts Cloudflare KV lacks atomic increments/CAS, so a read-modify-write counter can lose concurrent updates; it recommends a Durable Object. (observation — the agent's claim inside the demo, not adjudicated here)
Why this builds on Agent Supervision
Agent Supervision already holds the operator-workbench thesis: when review bandwidth is the bottleneck, the tool's job is to render agent output as legible diffs the human can accept, reject, edit, or annotate. This source sits squarely inside that frame — Hunk is such a workbench — and corroborates the "legible diffs before approval" claim from an independent tool. What it builds on / refines is the annotation lever: supervision described annotation as one option among accept/reject/edit, implicitly one-way (the human marks up the agent's output). Hunk makes the annotation store symmetric — the agent writes notes the human reads, and the human writes notes the agent reads and acts on — so the review view becomes a closed loop rather than a terminal approval gate. That symmetry is the new node (Shared Review Surface); the enabling seam is a skill wrapping a CLI (CLI Tools over MCP Servers), which is why the same page also touches the tool-surface concept. No tension with existing concepts — this is additive.
Illustrated walkthrough
Video is 5:14.
- t=00:00 — Intro. Hunk is pitched as a diff viewer that "prioritizes reviewing code" and "works really well with agents." The presenter cites endorsements from Mitchell Hashimoto (Ghostty, Terraform) and DHH (Rails, 37signals) — attributed as the source's claim. He'll pair it with "Herder" but says that's not required.
- t=00:37 — Install & open.
npm i hunk; runninghunk diffopens the viewer on a trivial React counter app after an agent added a Hono.js API. - t=00:53–02:00 — Viewer basics (the "not impressive yet"
part). View modes:
1side-by-side,2stacked,0auto (side-by-side on big screens, stacked on small). Navigate chunks with[/], sidebar withS, fuzzy file search with/; toggle line numbersL, wrappingW, metadataM, themeT(he picks GitHub Dark Default). He asks the agent to make the counter persistent with Cloudflare KV, then must manually refresh withRfor the new diff to appear — or runhunk diff --watchfor live updates, which he declines by preference. - t=02:50 — "The good part": working with agents. He
opens the
modem-dev/hunkGitHub repo (framef0057, t≈2:51) — "Review-first terminal diff viewer for agentic coders." The "Working with agents" section gives a generic prompt: "Load the Hunk skill and use it for this review. Runhunk skill pathto get the skill path." A feature-comparison table claims Hunk is alone among peers (lumen, difftastic, delta, diff-so-fancy, plain diff) in offering "Inline agent / AI annotations." You can tailor the prompt ("focus on security," "focus on being idiomatic"); he keeps a/hunktemplate but uses the generic prompt for the demo. - t=03:30 — Agent → human (frame
f0067, t≈3:38). After the agent reviews,Rrefreshes and an inline agent note appears anchored toworker/index.ts:25: "KV increments can lose concurrent updates — this read-modify-write sequence is persistent, but Cloudflare KV doesn't provide atomic increments/compare-and-swap… for a reliable shared counter, use a Durable Object or another atomic store." The left terminal shows the mechanism: the agent loaded the skill from…/hunkdiff/skills/hunk-review/SKILL.mdand ranhunk session comment list --repo . --type liveto write the comment. The status bar shows the coding agent is gpt-5.5 (via Herder), ~$0.96 for the session — attributed as shown on screen. Agent notes toggle with the angle-bracket keys. - t=04:10 — Human → agent (frame
f0074, t≈4:24). He writes his own note in the viewer: a "Draft note" onsrc/App.tsxline 54 — "Add a button for the reset" — saved with^S. He tells the agent "implement the comments I left"; because the Hunk skill is loaded, the agent reads the human's notes off the same surface and edits the code (swapping the inlineonClickfor anincrementCounterhandler and adding the reset button). - t=04:57 — It works. The demo app's new reset button resets the counter live. "Freaking incredible." t=05:02 — Final thoughts: Hunk "greatly improved my workflow."