The Problem

Developers working with AI‑generated code often need to inspect a diff before the changes are applied. Traditional line‑oriented tools make it hard to see inline agent annotations, switch between split/stacked layouts, or watch a repository evolve in real time. This forces a back‑and‑forth between the terminal diff and the editor, slowing review cycles.

What This Does

hunk replaces the plain‑text diff with an interactive terminal UI built on OpenTUI and Pierre diffs. The core UI lives in src/ui/ – e.g. src/ui/App.tsx creates the top‑level layout, while src/ui/diff/renderRows.tsx handles line wrapping and inline span rendering. The diff data model is defined in src/core/types.ts (a hub module imported by 67 other files) and src/hunk-session/types.ts (used by the session broker).

Examples illustrate the workflow: the mini‑app refactor (examples/2-mini-app-refactor/after/src/main.ts) shows a full session with a before/after diff, and the agent‑review demo (examples/3-agent-review-demo/after/src/index.ts) demonstrates how an external agent can query the live session via the CLI in src/hunk-session/cli.ts.

How It Is Wired

Execution begins at the CLI entry point src/hunk-session/cli.ts (function request is exported and invoked by the hunk binary defined in bin/hunk.cjs). From there:

  1. request → resolveSessionBrokerConfig (13 callers) → packages/session-broker/src/connection.ts (start) which opens a socket to the broker.
  2. The UI is launched by src/ui/App.tsx (function main at line 28) which creates the root component and calls createTestDiffFile (used in 23 places) to build the initial diff model.
  3. Rendering traverses src/ui/diff/pierre.ts (theme handling) and src/ui/diff/renderRows.tsx (functions fitText, sliceSpansWindow, renderInlineSpans). These modules are called from many UI panes (DiffPane, FileListItem) and therefore carry the widest blast radius (up to 18 outgoing edges).
  4. File I/O occurs only in src/core/git.ts and the test harness test/pty/harness.ts; the shortest external call is main → runSessionCommand → reloadSession → resolveConfiguredCliInput → readTomlRecord which reads a TOML config via fs.readFileSync. No database or network services are used beyond the optional session‑broker socket.

Circular imports involve src/hunk-session/types.ts, src/session/protocol.ts, and src/session/capabilities.ts. Breaking these cycles would reduce build‑time coupling and simplify type‑only imports.

Large, high‑connectivity files (src/core/types.ts, src/ui/themes.ts) act as stability anchors; any change propagates to dozens of modules, so keep them focused on pure type definitions and constants.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/hunk
cd hunk

# Install globally (requires Node ≥ 18)
npm i -g hunkdiff

# Run the built‑in demo
hunk diff --watch          # watches the current Git repo
hunk show HEAD             # view the latest commit
hunk skill path            # prints the skill file path for an LLM

Configuration lives in hunk.config.ts (searched automatically) where you can set vcs = "git" or "jj" and theme overrides. The CLI (src/hunk-session/cli.ts) also supports --agent-context to pipe a JSON context file (see examples/3-agent-review-demo/agent-context.json).

Real‑World Use

A CI pipeline can invoke hunk diff --watch in a detached terminal while an LLM‑based code‑review bot reads the session via the generated skill (hunk skill path). The bot can post annotations back into the UI, letting a human reviewer approve or edit before the changes are merged.

Code Health & Issues

  • High – Workflow pushes directly to the default branch (.github/workflows/release-prebuilt-npm.yml).
  • Medium – No least‑privilege GITHUB_TOKEN permissions (.github/workflows/benchmarks.yml).
  • Medium – No dependency‑vulnerability scan in CI.
  • Medium – Checkout step retains credentials (.github/workflows/ci.yml).
  • Low – No job time‑outs (.github/workflows/benchmarks.yml).
  • Low – Missing conventional repo files (.editorconfig, formatter config).

Static analysis also flagged:

  • Hub modules with high churn (src/core/types.ts, src/ui/themes.ts).
  • Circular import cycle (src/hunk-session/types.ts etc.).
  • Several oversized files (> 600 LOC) and duplicated test helpers.

No lockfile is present, so builds are not reproducible out of the box.

The Bottom Line

hunk delivers a focused, terminal‑based diff UI that integrates AI annotations and live watch mode, making it a practical tool for agent‑assisted code review. The codebase is functional but carries technical debt: large hub files, import cycles, and missing CI hardening. Teams that need an interactive review surface and are comfortable managing TypeScript monorepos will find it useful; they should address the identified health issues before using it in production.