/hunk-extensions

name: hunk-extensions
description: Maps the `hunkdiff/extension` authoring surface for Hunk, the terminal diff viewer — hiding or reordering reviewed files, docked panes, alternate file views, commands and key bindings, dialogs, workspace writes, themes, syntax languages, VCS backends, lifecycle events. Use when writing, debugging, or installing a Hunk extension, or when a request asks Hunk itself to behave differently. Not for reviewing a diff in a live session — that is hunk-review.

Building Hunk extensions

A Hunk extension is **one TypeScript (or JSX/JS) file that default-exports a factory**. Hunk imports it at startup and hands it an API object. No build step, no manifest required.

// ~/.config/hunk/extensions/hello.ts
import type { HunkExtensionAPI } from "hunkdiff/extension";

export default function (hunk: HunkExtensionAPI) {
  hunk.on("startup", (_event, ctx) => ctx.notify("Hello"));
}

This skill is a map of the touchpoints, not a recipe. Decide what to build from the user's request; use the table below to find the call, then read the linked material before writing code.

Sources of truth — read before writing

| Source | What it answers | | ------------------------------------------ | ------------------------------------------------------------ | | `docs/extensions.md` | The authoring guide. Every call, every rule. Start here. | | `packages/hunk/src/extension-api/types.ts` | The contract — exact field names, optionality, doc comments. | | `examples/extensions/*` | Working extensions. Copy these patterns rather than invent. | | `docs/extension-architecture.md` | Hunk's internals. Needed only when changing the host. | | `docs/keybindings.md`, `docs/themes.md` | Chord grammar and theme token rules that extensions inherit. |

Outside a Hunk checkout the guide is split across <https://hunk.dev/docs/extend/extensions/> (discovery, trust, config) and its companion pages — extension-api, file-previews, vcs-adapters, custom-panes — and the contract ships as `node_modules/hunkdiff/dist/npm/extension/index.d.ts`.

The examples, by what they demonstrate:

• `review-triage/` — pane + commands + all three dialog shapes + lifecycle

events + the extension event bus + a `useSyncExternalStore` bridge.

• `inline-edit/` — an interactive file-view `mode` driving `ctx.workspace` writes;

its README explains the async lifetime rules better than anything else in tree.

• `rendered-markdown/` — a file view producing host-rendered rows from parsed

Markdown, and a folder extension with an npm dependency.

• `code-document-file-view/` — API-v28 host-owned syntax paint over complete old/new

code documents, including semantic gutters and partial UTF-16 ranges.

• `jsx-file-view/`, `jsx-file-view-gallery/` — the experimental fixed-height JSX

row component contract.

Where extensions live

| Source | Trust | | ------------------------------------------ | ---------------- | | `--extension <path>` (repeatable) | runs immediately | | `[extensions] paths` in user config | runs immediately | | `~/.config/hunk/extensions/` (XDG-aware) | runs immediately | | `.hunk/extensions/` or repo-config `paths` | **trust prompt** |

Only the repo-local group is gated. Everything else — including `--extension`, even when its path points inside the repository under review — is read as explicit user intent and executes with full user permissions, no prompt. Never pass or suggest a path you have not read, including one copied from a repository's own README.

A directory matches `*.ts`/`*.tsx`/`*.js`/`*.jsx`/`*.mjs` at its top level, plus one level of folder extensions. A folder is an extension if it has a `package.json` with `{"hunk": {"extensions": ["./index.ts"]}}`, or an `index.{ts,tsx,js,jsx,mjs}`. Reach for a folder only when you need npm dependencies, helper modules, or a README; a single file keeps the install to one `cp`. A `.hunk/extensions/` folder extension's `node_modules` has to exist on every machine that loads it — keep a repo-shared extension dependency-free.

Shared extensions install from git with `hunk extension install <source>` (`owner/repo[@ref]`, `git:host/path[@ref]`, a git URL, or a local path) into `~/.config/hunk/extensions/installed/<repo-name>/`, where they load with global origin; `list`, `update`, and `remove` manage them. Declared `dependencies` are `bun install`ed at install time. The manifest may state `{"hunk": {"apiVersion": N}}` — the minimum extension API version — and an older Hunk refuses the extension with a startup notice instead of failing mid-factory. To publish, push the folder-extension layout to a git repository's root with real `name`/`version`/`description`, tag releases for `@ref` pins, and add the `hunk-extension` GitHub topic so it appears at <https://github.com/topics/hunk-extension>.

The **id** is the file stem, or the folder name for a folder extension — unless its manifest declares several entries, in which case each entry is its own extension named by its own stem (numeric suffix on collision). The id is the namespace it owns: commands are `<id>.<commandId>`, panes and keyboard modes are `<id>:<localId>`, config `[extension.<id>]`. Ids match `/^[A-Za-z0-9][A-Za-z0-9_-]*$/`; `hunk`, `git`, `jj`, and `sl` are reserved. A bad or duplicate id is skipped with a startup notice. `[extensions] disabled = ["<id>"]` filters a user extension before import or trust prompting. `--disable-extension <id>` and `--enable-extension <id>` are ordered one-run overrides; `--no-extensions` remains the hard switch for all user extensions. Bundled capabilities use separate host-owned selection ids such as `hunk.gh`, even when their public registrations remain under the `hunk` namespace.

Pick the touchpoint

| To do this