hunk-extensions

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.
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.
• jsx-file-view/, jsx-file-view-gallery/ — the experimental fixed-height JSX row component contract.