@g3nomaly/g3n-mods 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,76 @@
+# @g3nomaly/g3n-mods
+
+The g3n mods for Claude Code. A mod adds a pane, a status line, a slash command or a hook to Claude Code.
+
+This package holds the mods themselves. You don't install it directly. The installer, [`@g3nomaly/mods`](https://www.npmjs.com/package/@g3nomaly/mods), knows it as the built-in `g3n-mods` source and copies mods out of it into your project.
+
+## How to install
+
+Run these from the root of your project:
+
+```sh
+bunx @g3nomaly/mods init                # creates .claude/mods.json and sets up VS Code
+bunx @g3nomaly/mods add context-bar     # installs one mod
+bunx @g3nomaly/mods add g3n-mods        # installs every mod in this package
+```
+
+Then open the project in VS Code and trust the workspace. New sessions load the mods, and `/reload-plugins` loads them into a session that is already open. Updating, removing and installing for every project with `--user` are covered in the [`@g3nomaly/mods` README](https://www.npmjs.com/package/@g3nomaly/mods).
+
+## The mods
+
+| Mod | What it does | Command |
+|---|---|---|
+| `agents-panel` | The agents in `.claude/agents` with their model and a run button. A running agent shows a spinner, and a toast says when it starts and finishes | `/agents-panel` |
+| `context-bar` | One bar of context-window use split by source, with the total and where compaction starts | `/context-bar` |
+| `custom-crab-agents` | Each subagent as a crab with a hat: effort tier, model, steps, context, tokens, cost and time | `/crabs` |
+| `delete-guard` | Denies `rm -rf` and other permanent deletes and tells Claude which trash command to use instead | `/delete-guard on \| off` |
+| `focus-mode` | A timed focus block with a countdown, a progress bar and an end button. 25 minutes unless you pass a number | `/focus-mode [minutes] \| end` |
+| `handoff` | Writes a handoff with the `handoff` skill, clears the session, and attaches the handoff to your next prompt | `/handoff-new [what the next session is for]` |
+| `hide-personal-data` | Masks names, emails, phone numbers, IBANs and card numbers in replies. Hover a mask to read it | `/hide-personal-data on \| off` |
+| `mini-game` | Minesweeper, to play while Claude works | `/mini-game` |
+| `tool-timeline` | Each tool call with its duration. A denied call is struck through, next to the call that replaced it | `/tool-timeline` |
+| `you-should-know` | A card under long replies with their key point, a headline and one supporting line. It costs one small Haiku call per reply of 1500 characters or more | none |
+
+For `agents-panel`, `context-bar`, `custom-crab-agents` and `tool-timeline`, the command opens the pane and running it again closes it.
+
+Three mods take settings, declared under `userConfig` in their `.claude-plugin/plugin.json`:
+
+- `focus-mode`: `minutes`, the default block length (25).
+- `hide-personal-data`: `names`, extra names to always mask, separated by commas.
+- `you-should-know`: `minChars`, the shortest reply that gets a card (1500), and `model`, the model that picks the key point (`haiku`).
+
+## Requirements
+
+- [Bun](https://bun.sh), to run the installer
+- Claude Code for VS Code (`anthropic.claude-code`) 2.1.296 or newer. The mods are typed against that release.
+
+The mods also load in the terminal, but they are built for the VS Code extension.
+
+## Making your own mod
+
+Each mod here is a plugin folder under `mods/`, and `.claude-plugin/marketplace.json` lists them:
+
+```
+mods/<name>/
+├── .claude-plugin/plugin.json   # name, version, description
+├── hooks/hooks.json             # { "modules": ["./register.tsx"] }
+├── hooks/register.tsx           # exports `register`
+└── types/index.d.ts
+```
+
+The folder name must match `name` in `plugin.json`. Mods are TypeScript only, and the installer refuses a mod that contains any `.js`, `.mjs`, `.cjs` or `.jsx` file. To share your own mods, put them in a git repository, npm package or local folder with the same layout and register it with `bunx @g3nomaly/mods source add`.
+
+## Development
+
+Run `bun install` at the repository root first, then these from `packages/g3n-mods`:
+
+```sh
+bun run build       # rewrites .claude-plugin/marketplace.json from each mod's plugin.json
+bun run typecheck
+bun run validate    # runs `claude plugin validate` on every mod
+bun run types       # copies the mod API types into types/claude-code.d.ts
+```
+
+## License
+
+[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license). See `LICENSE`.

package/mods/agents-panel/hooks/register.tsx

@@ -20,7 +20,12 @@ const NAMED_COLORS: Readonly<Record<string, string>> = {
 const SPINNER = ['◐', '◓', '◑', '◒']
 const DONE_STATUSES = new Set(['completed', 'failed', 'killed', 'idle'])
 
-/** Frontmatter of a Markdown file as flat `key: value` pairs, quotes stripped. */
+/**
+ * Parses the frontmatter of a Markdown file into flat `key: value` pairs.
+ *
+ * @param text - Full Markdown text, which starts with a `---` block when it has frontmatter.
+ * @returns Fields by key with surrounding quotes stripped, or `{}` when there is no frontmatter.
+ */
 export function frontmatter(text: string): Record<string, string> {
   const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)
   if (match === null) return {}
@@ -33,12 +38,26 @@ export function frontmatter(text: string): Record<string, string> {
   return fields
 }
 
+/**
+ * Picks the dot color of an agent: its own color when it names one, else a palette color by position.
+ *
+ * @param agent - Definition whose `color` is tried first.
+ * @param index - Position of the agent in its list, used to pick a palette color.
+ * @returns CSS hex color.
+ */
 function dotColor(agent: AgentDef, index: number): string {
   const named = agent.color === undefined ? undefined : NAMED_COLORS[agent.color] ?? agent.color
   return named ?? DOT_COLORS[index % DOT_COLORS.length] ?? '#8a8f98'
 }
 
-/** Reads every agent definition in one agents folder; a missing folder reads as none. */
+/**
+ * Reads every agent definition in one agents folder.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param dir - Folder to read, e.g. `<root>/.claude/agents`.
+ * @param scope - Where the folder lives, as `project` or `user`.
+ * @returns Definitions sorted by name, or `[]` when the folder does not exist.
+ */
 async function readAgentsDir($: EngineInterface, dir: string, scope: AgentDef['scope']): Promise<AgentDef[]> {
   if (!(await $.fs.exists(dir))) return []
   const found: AgentDef[] = []
@@ -56,7 +75,13 @@ async function readAgentsDir($: EngineInterface, dir: string, scope: AgentDef['s
   return found.sort((a, b) => a.name.localeCompare(b.name))
 }
 
-/** Reloads the project's and the user's agent definitions into state. */
+/**
+ * Reloads the project's and the user's agent definitions into state.
+ *
+ * A user agent is dropped when the project has one with the same name.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
 async function loadAgents($: EngineInterface): Promise<void> {
   const root = await $.session.root()
   const home = await $.env.get('HOME')
@@ -66,7 +91,12 @@ async function loadAgents($: EngineInterface): Promise<void> {
   await update($, agents, () => [...project, ...user.filter(agent => !names.has(agent.name))])
 }
 
-/** Starts one agent with the task typed in the panel, or its standing job when none was typed. */
+/**
+ * Starts one agent with the task typed in the panel, or its standing job when none was typed.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param agent - Definition of the agent to start.
+ */
 async function runAgent($: EngineInterface, agent: AgentDef): Promise<void> {
   const typed = (await read($, task)).trim()
   const started = await $.agent.spawn({
@@ -83,7 +113,11 @@ async function runAgent($: EngineInterface, agent: AgentDef): Promise<void> {
   $.ui.toast(`Started ${agent.name}`)
 }
 
-/** Drops the agents that finished from the running list and says which ones did. */
+/**
+ * Drops the agents that finished from the running list and says which ones did.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
 async function pollRunning($: EngineInterface): Promise<void> {
   const list = await read($, running)
   if (list.length === 0) return
@@ -100,12 +134,25 @@ async function pollRunning($: EngineInterface): Promise<void> {
   }
 }
 
-/** Puts a finished agent's answer in the transcript as a notice the model does not read. */
+/**
+ * Puts a finished agent's answer in the transcript as a notice the model does not read.
+ *
+ * Answers longer than 4000 characters are cut to 4000.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param run - Agent that finished, from the running list.
+ * @param answer - Final text of the agent's reply.
+ */
 async function reportAnswer($: EngineInterface, run: RunningAgent, answer: string): Promise<void> {
   const text = answer.length > 4000 ? `${answer.slice(0, 4000)}…` : answer
   await $.session.append({ message: { type: 'system', content: [{ type: 'text', text: `${run.name} finished:\n\n${text}` }] } })
 }
 
+/**
+ * Registers this mod's `agents-panel` command, its session and turn hooks, and its pane.
+ *
+ * @param on - Hook registration function the engine passes in.
+ */
 export const register: Register = on => {
   on('session.start', async ($, e, next) => {
     await $.command.register({ name: 'agents-panel', description: 'Show or hide the agents panel' })
@@ -163,6 +210,12 @@ export const register: Register = on => {
       )
     }
 
+    /**
+     * Renders the agents of one scope under a heading, or nothing when the scope has none.
+     *
+     * @param scope - Scope to render, as `project` or `user`.
+     * @returns The section element, or `''` when no agent has that scope.
+     */
     const section = (scope: AgentDef['scope']) => {
       const members = list.filter(agent => agent.scope === scope)
       if (members.length === 0) return ''

package/mods/context-bar/hooks/register.tsx

@@ -28,7 +28,12 @@ const SOURCES: ReadonlyArray<{ match: RegExp; label: string; color: string }> =
   { match: /message/i, label: 'messages', color: '#e0775a' },
 ]
 
-/** Tokens as the screenshots spell them: `892`, `4.2k`, `52k`, `1M`. */
+/**
+ * Formats a token count the way the bar labels it, with `k` and `M` suffixes.
+ *
+ * @param tokens - Token count, e.g. `52000`.
+ * @returns Short label, e.g. `892`, `4.2k`, `52k` or `1M`.
+ */
 export function formatTokens(tokens: number): string {
   if (tokens >= 1_000_000) return `${+(tokens / 1_000_000).toFixed(1)}M`
   if (tokens >= 10_000) return `${Math.round(tokens / 1000)}k`
@@ -36,15 +41,23 @@ export function formatTokens(tokens: number): string {
   return String(Math.round(tokens))
 }
 
+/**
+ * Rounds `part` as a percent of `whole`.
+ *
+ * @returns The rounded percent, or `0` when `whole` is not positive.
+ */
 function percentOf(part: number, whole: number): number {
   return whole > 0 ? Math.round((part / whole) * 100) : 0
 }
 
 /**
- * Measures the context window by source. Categories of the same source add
- * up into one row; deferred tools and the compaction buffer are left out.
+ * @brief Measures the context window by source.
  *
- * @returns the snapshot, or `null` before the session has measured anything
+ * Categories of the same source add up into one row; deferred tools and the
+ * compaction buffer are left out.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @returns The snapshot, or `null` before the session has measured anything.
  */
 async function measure($: EngineInterface): Promise<ContextSnapshot | null> {
   const usage = await $.session.usage({ breakdown: 'summary' })
@@ -70,7 +83,13 @@ async function measure($: EngineInterface): Promise<ContextSnapshot | null> {
   }
 }
 
-/** The bar as one SVG: a rect per source, the free remainder, and a mark at the compaction point. */
+/**
+ * The bar as one SVG: a rect per source, the free remainder, and a mark at the compaction point.
+ *
+ * @param snap - Snapshot to draw, see `ContextSnapshot`.
+ * @param width - Width of the SVG in pixels.
+ * @returns The SVG markup as a string.
+ */
 function barSvg(snap: ContextSnapshot, width: number): string {
   const height = 14
   let x = 0
@@ -89,7 +108,11 @@ function barSvg(snap: ContextSnapshot, width: number): string {
 let lastMeasured = 0
 let isScheduled = false
 
-/** Measures now, or once the gap since the last measurement has passed; calls in between fold into one. */
+/**
+ * Measures now, or once the gap since the last measurement has passed; calls in between fold into one.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
 async function refresh($: EngineInterface): Promise<void> {
   const now = await $.clock.now()
   const wait = lastMeasured + MEASURE_GAP_MS - now
@@ -107,6 +130,11 @@ async function refresh($: EngineInterface): Promise<void> {
   if (snap !== null) await update($, snapshot, () => snap)
 }
 
+/**
+ * Registers this mod's `context-bar` command, its session, measure and turn hooks, and its pane.
+ *
+ * @param on - Hook registration function the engine passes in.
+ */
 export const register: Register = on => {
   on('session.start', async ($, e, next) => {
     await $.command.register({ name: 'context-bar', description: 'Show or hide the context window bar' })

package/mods/custom-crab-agents/hooks/register.tsx

@@ -56,11 +56,22 @@ const PRICES: ReadonlyArray<[RegExp, [number, number, number, number]]> = [
   [/haiku/, [1, 5, 0.1, 1.25]],
 ]
 
+/**
+ * Looks up the tier of an effort level, falling back to the default tier.
+ *
+ * @param effort - Effort level of an Agent call, e.g. `high`, or `undefined` when none was given.
+ * @returns The tier with its name, color and hat.
+ */
 function tierOf(effort: string | undefined) {
   return (effort === undefined ? undefined : TIERS[effort]) ?? DEFAULT_TIER
 }
 
-/** A model id or alias as people say it: `claude-opus-5-5` → `Opus 5.5`, `haiku` → `Haiku`. */
+/**
+ * Formats a model id or alias as a short display name.
+ *
+ * @param model - Model id or alias, e.g. `claude-opus-5-5` or `haiku`.
+ * @returns The family and version, e.g. `Opus 5.5` or `Haiku`, or `model` unchanged when no family matches.
+ */
 export function modelName(model: string): string {
   const match = /(opus|sonnet|haiku|fable|mythos)(?:-(\d+))?(?:-(\d+))?/i.exec(model)
   if (match === null) return model
@@ -69,25 +80,56 @@ export function modelName(model: string): string {
   return version.length > 0 ? `${family} ${version}` : family
 }
 
-/** Estimated dollars for a usage record, or `undefined` when the model is not priced. */
+/**
+ * Estimates the dollar cost of a usage record from the price table.
+ *
+ * @param model - Model id or alias, matched against the price table.
+ * @param usage - Usage record with token counts under `input_tokens`, `output_tokens`,
+ *   `cache_read_input_tokens` and `cache_creation_input_tokens`, e.g. `{ input_tokens: 1200 }`.
+ * @returns Estimated cost in US dollars, or `undefined` when no price matches the model.
+ */
 export function costOf(model: string, usage: Record<string, unknown>): number | undefined {
   const price = PRICES.find(([match]) => match.test(model))?.[1]
   if (price === undefined) return undefined
+  /**
+   * Reads one token count from the usage record.
+   *
+   * @param key - Token field to read, e.g. `input_tokens`.
+   * @returns The count, or `0` when the field is missing or not a number.
+   */
   const n = (key: string) => (typeof usage[key] === 'number' ? (usage[key] as number) : 0)
   return (n('input_tokens') * price[0] + n('output_tokens') * price[1]
     + n('cache_read_input_tokens') * price[2] + n('cache_creation_input_tokens') * price[3]) / 1_000_000
 }
 
+/**
+ * Formats a token count as `892`, `1.2k` or `52k`.
+ *
+ * @param tokens - Token count, e.g. `52000`.
+ * @returns Short label.
+ */
 function formatTokens(tokens: number): string {
   return tokens >= 10_000 ? `${Math.round(tokens / 1000)}k` : tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens)
 }
 
+/**
+ * Formats a duration as `m:ss`.
+ *
+ * @param ms - Duration in milliseconds.
+ * @returns Minutes and zero-padded seconds, e.g. `1:05`.
+ */
 function minutes(ms: number): string {
   const s = Math.max(0, Math.round(ms / 1000))
   return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`
 }
 
-/** The crab as one SVG: hat rows for the tier on top of the body; a planned crab is drawn grey. */
+/**
+ * Draws the crab as one SVG: hat rows for the tier on top of the body; a planned crab is drawn grey.
+ *
+ * @param hat - Hat to draw, a key of `HATS`.
+ * @param isPlanned - Whether the crab is planned work, not a running or finished subagent.
+ * @returns The SVG markup as a string.
+ */
 function crabSvg(hat: keyof typeof HATS, isPlanned: boolean): string {
   const rows = [...HATS[hat], ...BODY]
   const rects: string[] = []
@@ -103,31 +145,69 @@ function crabSvg(hat: keyof typeof HATS, isPlanned: boolean): string {
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}"${filter}>${rects.join('')}</svg>`
 }
 
+/**
+ * Draws a progress bar as one SVG, filled to `share` of its width.
+ *
+ * @param width - Width of the bar in pixels.
+ * @param share - Filled part of the bar, from `0` to `1`.
+ * @param color - Fill color as a CSS hex string.
+ * @returns The SVG markup as a string.
+ */
 function progressSvg(width: number, share: number, color: string): string {
   const w = Math.max(0, Math.min(1, share)) * width
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="5" viewBox="0 0 ${width} 5"><rect width="${width}" height="5" rx="2" fill="#2b3240"/><rect width="${w.toFixed(1)}" height="5" rx="2" fill="${color}"/></svg>`
 }
 
+/**
+ * Reads one property of an unknown value when the property passes `guard`.
+ *
+ * @param value - Any value, e.g. a parsed tool result.
+ * @param key - Name of the property to read.
+ * @param guard - Type guard the property value must pass.
+ * @returns The property value, or `undefined` when `value` is not an object or the guard fails.
+ */
 function field<T>(value: unknown, key: string, guard: (v: unknown) => v is T): T | undefined {
   if (typeof value !== 'object' || value === null) return undefined
   const found = (value as Record<string, unknown>)[key]
   return guard(found) ? found : undefined
 }
+/** Tells whether `v` is a string. */
 const isString = (v: unknown): v is string => typeof v === 'string'
+/** Tells whether `v` is a number. */
 const isNumber = (v: unknown): v is number => typeof v === 'number'
+/** Tells whether `v` is a non-null object. */
 const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null
 
+/**
+ * Applies `patch` to every crab that `match` selects.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param match - Selects the crabs to change.
+ * @param patch - Returns the changed crab for a selected one.
+ */
 async function patchCrab($: EngineInterface, match: (crab: Crab) => boolean, patch: (crab: Crab) => Crab): Promise<void> {
   await update($, crabs, list => list.map(crab => (match(crab) ? patch(crab) : crab)))
 }
 
-/** Records a subagent the main thread just started and shows the pane. */
+/**
+ * Records a subagent the main thread just started and shows the pane.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param crab - New running crab to add, see `Crab`.
+ */
 async function startCrab($: EngineInterface, crab: Crab): Promise<void> {
   await update($, crabs, list => [...list.filter(one => one.id !== crab.id), crab].slice(-KEEP))
   void $.ui.open({ id: PANE, title: TITLE })
 }
 
-/** Settles a crab from the Agent tool's result: its usage, model and time, or that it went to the background. */
+/**
+ * Settles a crab from the Agent tool's result: its usage, model and time, or that it went to the background.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param id - `tool_use_id` of the Agent call that started the crab.
+ * @param result - Raw result of the Agent call, of unknown shape.
+ * @param isError - Whether the Agent call reported an error.
+ */
 async function finishCrab($: EngineInterface, id: string, result: unknown, isError: boolean): Promise<void> {
   const status = field(result, 'status', isString)
   const agentId = field(result, 'agentId', isString)
@@ -152,7 +232,13 @@ async function finishCrab($: EngineInterface, id: string, result: unknown, isErr
   })
 }
 
-/** Settles a background crab when its own loop completes. */
+/**
+ * Settles a background crab when its own loop completes.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param agentId - Id of the subagent whose loop completed.
+ * @param usage - Usage record of that loop, or `undefined` when none was reported.
+ */
 async function finishBackground($: EngineInterface, agentId: string, usage: Record<string, unknown> | undefined): Promise<void> {
   const now = await $.clock.now()
   await patchCrab($, crab => crab.agentId === agentId && crab.status === 'running', crab => ({
@@ -165,7 +251,13 @@ async function finishBackground($: EngineInterface, agentId: string, usage: Reco
   }))
 }
 
-/** Ties a subagent's id to the newest running crab of its type that has none yet. */
+/**
+ * Ties a subagent's id to the newest running crab of its type that has none yet.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param agentId - Id the engine gave the subagent.
+ * @param agentType - Subagent type the crab was started with, e.g. `Explore`.
+ */
 async function bindAgent($: EngineInterface, agentId: string, agentType: string): Promise<void> {
   await update($, crabs, list => {
     if (list.some(crab => crab.agentId === agentId)) return list
@@ -174,7 +266,13 @@ async function bindAgent($: EngineInterface, agentId: string, agentType: string)
   })
 }
 
-/** Turns a todo list into steps (a subagent's own list) or planned items (the main thread's). */
+/**
+ * Turns a todo list into steps (a subagent's own list) or planned items (the main thread's).
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param todos - Raw `todos` field of a TodoWrite call, of unknown shape.
+ * @param agentId - Id of the subagent that wrote the list, or `undefined` for the main thread.
+ */
 async function readTodos($: EngineInterface, todos: unknown, agentId: string | undefined): Promise<void> {
   if (!Array.isArray(todos)) return
   const items = todos.filter(isRecord).map(todo => ({
@@ -202,21 +300,42 @@ async function readTodos($: EngineInterface, todos: unknown, agentId: string | u
   await update($, planned, () => open)
 }
 
-/** Counts a subagent's model requests and keeps its model and effort current. */
+/**
+ * Counts a subagent's model requests and keeps its model and effort current.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param agentId - Id of the subagent that made the request.
+ * @param model - Model the request ran on.
+ * @param effort - Effort level of the request, or `undefined` when none applies.
+ */
 async function countStep($: EngineInterface, agentId: string, model: string, effort: string | undefined): Promise<void> {
   await patchCrab($, crab => crab.agentId === agentId, crab => ({ ...crab, requests: crab.requests + 1, model, effort: effort ?? crab.effort }))
 }
 
-/** Redraws once a second while a crab runs, so its time moves. */
+/**
+ * Redraws once a second while a crab runs, so its time moves.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
 async function tick($: EngineInterface): Promise<void> {
   if ((await read($, crabs)).some(crab => crab.status === 'running')) $.ui.invalidate('ui.render')
 }
 
+/**
+ * Reads the session's context window size into state, keeping the old size when the read fails.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
 async function readWindow($: EngineInterface): Promise<void> {
   const usage = await $.session.usage().catch(() => undefined)
   if (usage !== undefined && usage.context.window > 0) await update($, contextWindow, () => usage.context.window)
 }
 
+/**
+ * Registers this mod's `crabs` command, its session, tool, subagent and turn hooks, and its pane.
+ *
+ * @param on - Hook registration function the engine passes in.
+ */
 export const register: Register = on => {
   on('session.start', async ($, e, next) => {
     await $.command.register({ name: 'crabs', description: 'Show or hide the subagent crabs' })
@@ -288,11 +407,25 @@ export const register: Register = on => {
     if (list.length === 0 && plan.length === 0) return <Text dimColor>No subagents yet. Each one shows up here as a crab.</Text>
 
     const barWidth = Math.max(120, (e.props.bodyColumns - 10) * 7)
+    /**
+     * Draws a crab sprite: an emoji in the terminal, an SVG elsewhere.
+     *
+     * @param hat - Hat to draw, a key of `HATS`.
+     * @param isPlanned - Whether the crab is planned work.
+     * @returns The sprite element.
+     */
     const sprite = (hat: keyof typeof HATS, isPlanned: boolean) => {
       if (e.surface === 'terminal') return <Text color={isPlanned ? '#6b7280' : PALETTE.b}>🦀</Text>
       const { Svg } = $.ui.resolve(e)
       return <Svg source={crabSvg(hat, isPlanned)} alt="crab" width={12 * PIXEL} height={11 * PIXEL} />
     }
+    /**
+     * Draws a progress bar for a crab.
+     *
+     * @param share - Filled part of the bar, from `0` to `1`.
+     * @param color - Fill color as a CSS hex string.
+     * @returns The bar element.
+     */
     const progress = (share: number, color: string) => {
       if (e.surface === 'terminal') {
         const cells = Math.max(10, e.props.bodyColumns - 10)
@@ -303,6 +436,12 @@ export const register: Register = on => {
       return <Svg source={progressSvg(barWidth, share, color)} alt={`${Math.round(share * 100)}%`} width={barWidth} height={5} />
     }
 
+    /**
+     * Draws one crab card: sprite, title, tier, model, step line, stats and progress.
+     *
+     * @param crab - Crab to draw, see `Crab`.
+     * @returns The card element.
+     */
     const card = (crab: Crab) => {
       const tier = tierOf(crab.effort)
       const elapsed = crab.durationMs ?? now - crab.startedAt

package/mods/delete-guard/hooks/register.ts

@@ -21,18 +21,33 @@ const TRASH_COMMANDS = [
   { probe: 'gio', spell: 'gio trash' },
 ] as const
 
-/** Splits a shell command line into its commands, each trimmed. */
+/**
+ * Splits a shell command line into its commands, each trimmed.
+ *
+ * @param command - Shell command line, e.g. `cd build && rm -rf dist`.
+ * @returns The non-empty commands in order.
+ */
 function segments(command: string): string[] {
   return command.split(SEGMENT_BREAK).map(part => part.trim()).filter(part => part.length > 0)
 }
 
-/** Words of a command after its prefixes, the program name without its directory. */
+/**
+ * Splits one command into words, dropping its prefixes and the program's directory.
+ *
+ * @param segment - One command, as `segments` returns it.
+ * @returns The program name first, then its arguments.
+ */
 function words(segment: string): string[] {
   const [program = '', ...rest] = segment.replace(PREFIX, '').split(/\s+/)
   return [program.split('/').pop() ?? program, ...rest]
 }
 
-/** The operands of a command: every word that is not a flag, and every word after `--`. */
+/**
+ * Picks the operands of a command: every word that is not a flag, and every word after `--`.
+ *
+ * @param args - Words after the program name.
+ * @returns The operands in order.
+ */
 function operands(args: readonly string[]): string[] {
   const end = args.indexOf('--')
   const flagged = end === -1 ? args : args.slice(0, end)
@@ -41,10 +56,13 @@ function operands(args: readonly string[]): string[] {
 }
 
 /**
- * Finds the first permanent delete in a shell command line: `rm`, `shred`,
- * `unlink`, `rimraf`, `find -delete`, `find -exec rm` or a forced `git clean`.
+ * @brief Finds the first permanent delete in a shell command line.
+ *
+ * Recognises `rm`, `shred`, `unlink`, `rimraf`, `find -delete`, `find -exec rm`
+ * and a forced `git clean`.
  *
- * @returns the delete and what it removes, or `undefined` when nothing is deleted for good
+ * @param command - Full shell command line, as the Bash tool received it.
+ * @returns The delete and what it removes, or `undefined` when nothing is deleted for good.
  */
 export function findDeletion(command: string): Deletion | undefined {
   for (const segment of segments(command)) {
@@ -62,7 +80,13 @@ export function findDeletion(command: string): Deletion | undefined {
   return undefined
 }
 
-/** What Claude should run instead, spelled with the trash command this machine has. */
+/**
+ * Builds the command Claude should run instead of a permanent delete.
+ *
+ * @param deletion - Delete to replace, see `Deletion`.
+ * @param trash - Trash command spelled as this machine has it, e.g. `gio trash`.
+ * @returns The suggested command, with `<paths>` where no path was named.
+ */
 function insteadOf(deletion: Deletion, trash: string): string {
   switch (deletion.kind) {
     case 'files':
@@ -74,7 +98,12 @@ function insteadOf(deletion: Deletion, trash: string): string {
   }
 }
 
-/** First trash command found on this machine's PATH, or `undefined` when there is none. */
+/**
+ * Finds the first trash command on this machine's PATH.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @returns The command as it should be spelled, or `undefined` when none is installed.
+ */
 async function detectTrash($: EngineInterface): Promise<string | undefined> {
   for (const candidate of TRASH_COMMANDS) {
     const found = await $.process.run(['sh', '-c', `command -v ${candidate.probe}`]).catch(() => undefined)
@@ -83,6 +112,11 @@ async function detectTrash($: EngineInterface): Promise<string | undefined> {
   return undefined
 }
 
+/**
+ * Registers this mod's `delete-guard` command, its session hook, and its Bash tool hook.
+ *
+ * @param on - Hook registration function the engine passes in.
+ */
 export const register: Register = on => {
   let trash: string | undefined
 

package/mods/focus-mode/hooks/register.tsx

@@ -14,7 +14,12 @@ const MAX_SQUARES = 30
 const FILLED = '#e6b450'
 const EMPTY = '#3a3f4b'
 
-/** Remaining time as `mm:ss`, or `h:mm:ss` from an hour up. */
+/**
+ * Formats remaining time as `mm:ss`, or `h:mm:ss` from an hour up.
+ *
+ * @param ms - Milliseconds left. Rounded up to whole seconds; negative values count as `0`.
+ * @returns Clock text, e.g. `24:59`.
+ */
 export function clock(ms: number): string {
   const total = Math.max(0, Math.ceil(ms / 1000))
   const h = Math.floor(total / 3600)
@@ -25,7 +30,12 @@ export function clock(ms: number): string {
   return h > 0 ? `${h}:${mm}:${ss}` : `${mm}:${ss}`
 }
 
-/** A wall-clock time as `3:10 pm`. */
+/**
+ * Formats a wall-clock time as `3:10 pm`.
+ *
+ * @param epochMs - Time in milliseconds since the epoch, shown in local time.
+ * @returns 12-hour clock text.
+ */
 function wallTime(epochMs: number): string {
   const date = new Date(epochMs)
   const hours = date.getHours()
@@ -33,6 +43,13 @@ function wallTime(epochMs: number): string {
   return `${hours % 12 === 0 ? 12 : hours % 12}:${minutes} ${hours < 12 ? 'am' : 'pm'}`
 }
 
+/**
+ * Draws a row of squares as one SVG, lighting the first `filled` of them.
+ *
+ * @param count - Number of squares.
+ * @param filled - Number of lit squares, counted from the left.
+ * @returns The SVG markup as a string.
+ */
 function squaresSvg(count: number, filled: number): string {
   const size = 10
   const gap = 3
@@ -42,14 +59,24 @@ function squaresSvg(count: number, filled: number): string {
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${size}" viewBox="0 0 ${width} ${size}">${rects.join('')}</svg>`
 }
 
-/** Starts a block of `minutes`, replacing one already running, and shows the pane. */
+/**
+ * Starts a block of `minutes`, replacing one already running, and shows the pane.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param minutes - Length of the block in minutes.
+ */
 async function startFocus($: EngineInterface, minutes: number): Promise<void> {
   const startedAt = await $.clock.now()
   await update($, block, () => ({ startedAt, endsAt: startedAt + minutes * 60_000, minutes }))
   await $.ui.open({ id: PANE, title: TITLE })
 }
 
-/** Ends the running block early, or on time when `isDone`. */
+/**
+ * Ends the running block, and counts it as done when it ran its full time.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param isDone - `true` when the block ran out, `false` when the user ended it early.
+ */
 async function endFocus($: EngineInterface, isDone: boolean): Promise<void> {
   const current = await read($, block)
   if (current === null) return
@@ -62,7 +89,11 @@ async function endFocus($: EngineInterface, isDone: boolean): Promise<void> {
   }
 }
 
-/** Once a second: ends a block whose time is up, else moves the countdown on. */
+/**
+ * Moves the running block on by one second: ends it when its time is up, else updates the countdown.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
 async function tick($: EngineInterface): Promise<void> {
   const current = await read($, block)
   if (current === null) return
@@ -75,6 +106,12 @@ async function tick($: EngineInterface): Promise<void> {
   $.ui.invalidate('ui.render')
 }
 
+/**
+ * Registers this mod's `focus-mode` command, its session hook, its tick, and its pane.
+ *
+ * @param on - Hook registration function the engine passes in.
+ * @param options - Plugin options; `minutes` sets the default block length.
+ */
 export const register: Register = (on, options) => {
   const configured = Number(options.minutes ?? DEFAULT_MINUTES)
   const defaultMinutes = Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_MINUTES

package/mods/handoff/hooks/register.tsx

@@ -20,10 +20,22 @@ const FALLBACK_SKILL = [
   'If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.',
 ].join('\n\n')
 
+/**
+ * Removes the frontmatter block from a Markdown skill file.
+ *
+ * @param text - Full text of a `SKILL.md` file.
+ * @returns The body, trimmed.
+ */
 function withoutFrontmatter(text: string): string {
   return text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim()
 }
 
+/**
+ * Tells whether a stored value has the shape of a `PendingHandoff`.
+ *
+ * @param value - Value read from the store, of unknown shape.
+ * @returns `true` when `text` and `path` are strings and `createdAt` is a number.
+ */
 function isPendingHandoff(value: unknown): value is PendingHandoff {
   return typeof value === 'object' && value !== null
     && 'text' in value && typeof value.text === 'string'
@@ -31,7 +43,12 @@ function isPendingHandoff(value: unknown): value is PendingHandoff {
     && 'createdAt' in value && typeof value.createdAt === 'number'
 }
 
-/** The `handoff` skill's body from the project, else the user's skills, else the built-in copy. */
+/**
+ * Loads the `handoff` skill's instructions: the project's copy, else the user's, else the built-in copy.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @returns The instructions without their frontmatter.
+ */
 async function loadSkill($: EngineInterface): Promise<string> {
   const root = await $.session.root()
   const home = await $.env.get('HOME')
@@ -41,19 +58,34 @@ async function loadSkill($: EngineInterface): Promise<string> {
   return FALLBACK_SKILL
 }
 
-/** Absolute path in the OS temporary folder for a handoff written at `now`. */
+/**
+ * Builds the path of a handoff document in the OS temporary folder, named by the time it was written.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param now - Time the handoff was written, in milliseconds since the epoch.
+ * @returns Absolute path, e.g. `/tmp/claude-handoff-2026-10-11T09-30-00.md`.
+ */
 async function documentPath($: EngineInterface, now: number): Promise<string> {
   const tmp = ((await $.env.get('TMPDIR')) ?? '/tmp').replace(/\/$/, '')
   const stamp = new Date(now).toISOString().replace(/[:.]/g, '-').slice(0, 19)
   return `${tmp}/claude-handoff-${stamp}.md`
 }
 
-/** Runs /clear once the session is idle, after the command that asked for it has answered. */
+/**
+ * Runs /clear, after the command that asked for it has answered. Shows a toast when /clear cannot run.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
 async function clearSession($: EngineInterface): Promise<void> {
   await $.command.run({ command: 'clear' }).catch(() => $.ui.toast('Run /clear to start the fresh session; the handoff waits for your next prompt.'))
 }
 
-/** The handoff waiting for the next prompt, dropping one that has gone stale. */
+/**
+ * Takes the handoff waiting for the next prompt, and removes it from the store either way.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @returns The handoff, or `undefined` when none waits or it is older than 24 hours.
+ */
 async function takePending($: EngineInterface): Promise<PendingHandoff | undefined> {
   const stored = await $.store.get(STORE_KEY)
   if (!isPendingHandoff(stored)) return undefined
@@ -64,6 +96,11 @@ async function takePending($: EngineInterface): Promise<PendingHandoff | undefin
   return now - stored.createdAt > MAX_AGE_MS ? undefined : stored
 }
 
+/**
+ * Registers this mod's `handoff-new` command, its session hook, and its prompt hook.
+ *
+ * @param on - Hook registration function the engine passes in.
+ */
 export const register: Register = on => {
   on('session.start', async ($, e, next) => {
     await $.command.register({

package/mods/hide-personal-data/hooks/register.tsx

@@ -34,21 +34,35 @@ const FIRST_NAMES = new Set(`
 const FULL_NAME = /\b([A-Z][a-z]+) ((?:van |de |von |da )?[A-Z][a-z]+(?:[-'][A-Z][a-z]+)?)\b/g
 const TITLED_NAME = /\b(?:Mr|Mrs|Ms|Dr|Prof)\.? [A-Z][a-z]+(?:[-'][A-Z][a-z]+)?\b/g
 
+/**
+ * Counts the digits in a text.
+ *
+ * @param text - Text to count in, e.g. a phone number.
+ * @returns Number of digit characters.
+ */
 function digitCount(text: string): number {
   return text.replace(/\D/g, '').length
 }
 
+/**
+ * Escapes the characters that have a meaning in a regular expression.
+ *
+ * @param text - Literal text to match exactly.
+ * @returns The text with each special character escaped.
+ */
 function escapeRegExp(text: string): string {
   return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
 /**
- * Finds personal data in a text: emails, phone numbers, IBANs, card numbers
- * and names, the latter from `names` and from common first names followed by
- * a surname. Overlapping matches keep the earlier, longer one.
+ * @brief Finds personal data in a text: emails, phone numbers, IBANs, card numbers and names.
  *
- * @param names - Exact names to mask wherever they occur, e.g. the git user's
- * @returns the matches in text order
+ * Names come from `names` and from common first names followed by a surname.
+ * Overlapping matches keep the earlier, longer one.
+ *
+ * @param text - Text to search, a line or a whole message.
+ * @param names - Exact names to mask wherever they occur, e.g. `["Ada Lovelace"]`.
+ * @returns The matches in text order.
  */
 export function findPersonalData(text: string, names: readonly string[]): PersonalSpan[] {
   const spans: PersonalSpan[] = []
@@ -80,12 +94,22 @@ export function findPersonalData(text: string, names: readonly string[]): Person
   return kept
 }
 
-/** Inline Markdown a line drawn as plain text would show raw: emphasis marks and heading hashes. */
+/**
+ * Strips the Markdown a plain-text line would show raw: heading hashes, bold, underscore and code marks.
+ *
+ * @param line - One line of a message.
+ * @returns The line without those marks.
+ */
 function plain(line: string): string {
   return line.replace(/^#{1,6}\s+/, '').replace(/(\*\*|__|`)/g, '')
 }
 
-/** Reads the git user's name and email, the names most likely to show up in replies. */
+/**
+ * Reads the git user's name and email from the repository config, the names most likely to show up in replies.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @returns The values that are set, `user.name` first, or `[]` when neither is set.
+ */
 async function gitIdentity($: EngineInterface): Promise<string[]> {
   const found: string[] = []
   for (const key of ['user.name', 'user.email']) {
@@ -96,6 +120,12 @@ async function gitIdentity($: EngineInterface): Promise<string[]> {
   return found
 }
 
+/**
+ * Registers this mod's `hide-personal-data` command, its session hook, and its assistant message hook.
+ *
+ * @param on - Hook registration function the engine passes in.
+ * @param options - Plugin options; `names` is a comma-separated list of names to always mask.
+ */
 export const register: Register = (on, options) => {
   const configured = typeof options.names === 'string'
     ? options.names.split(',').map(name => name.trim()).filter(name => name.length > 0)
@@ -128,6 +158,9 @@ export const register: Register = (on, options) => {
     const { Box, Text, Markdown } = $.ui.resolve(e)
     const blocks: RenderChildren[] = []
     let prose: string[] = []
+    /**
+     * Emits the prose lines collected so far as one Markdown block, then clears them.
+     */
     const flush = () => {
       if (prose.length > 0) blocks.push(<Markdown text={prose.join('\n')} />)
       prose = []

package/mods/mini-game/hooks/register.tsx

@@ -16,7 +16,13 @@ const BEST_KEY = 'best-seconds'
 const HINT_AFTER_MS = 60_000
 const NUMBER_COLORS = [undefined, '#6b8fd6', '#7cc47f', '#e06c6c', '#9b87f5', '#e0775a', '#5fb3c4', '#d0d0d0', '#8a8f98']
 
-/** Cells around `cell` on a `size` × `size` board. */
+/**
+ * Lists the cells around `cell` on a `size` × `size` board.
+ *
+ * @param cell - Cell number, counted row by row from `0`.
+ * @param size - Board width and height in cells.
+ * @returns The neighboring cell numbers, from one to eight of them.
+ */
 export function neighbors(cell: number, size: number): number[] {
   const row = Math.floor(cell / size)
   const col = cell % size
@@ -31,11 +37,24 @@ export function neighbors(cell: number, size: number): number[] {
   return found
 }
 
+/**
+ * Counts the mines in the cells around `cell`.
+ *
+ * @param board - Board to read, see `Game`.
+ * @param cell - Cell number to count around.
+ * @returns Number of neighboring mines, from `0` to `8`.
+ */
 function adjacentMines(board: Game, cell: number): number {
   return neighbors(cell, board.size).filter(n => board.mines.includes(n)).length
 }
 
-/** Places mines anywhere but `safe` and the cells around it. */
+/**
+ * Picks random cells for the mines, leaving `safe` and the cells around it free.
+ *
+ * @param board - Board to place mines on, see `Game`.
+ * @param safe - Cell the first reveal hit, which must not be a mine.
+ * @returns Mine cell numbers, `board.mineCount` of them.
+ */
 function placeMines(board: Game, safe: number): number[] {
   const banned = new Set([safe, ...neighbors(safe, board.size)])
   const free = Array.from({ length: board.size * board.size }, (_, i) => i).filter(i => !banned.has(i))
@@ -47,10 +66,13 @@ function placeMines(board: Game, safe: number): number[] {
 }
 
 /**
- * Reveals one cell: the first reveal places the mines, a zero opens its
+ * @brief Reveals one cell: the first reveal places the mines, a zero opens its
  * neighbours, a mine ends the game, and the last safe cell wins it.
  *
- * @param now - Milliseconds since the epoch, stamped as the start or end time
+ * @param board - Board to reveal on, see `Game`.
+ * @param cell - Cell number to reveal.
+ * @param now - Milliseconds since the epoch, stamped as the start or end time.
+ * @returns The board after the reveal, or the same board when the cell cannot be revealed.
  */
 export function reveal(board: Game, cell: number, now: number): Game {
   if (board.status === 'won' || board.status === 'lost') return board
@@ -74,18 +96,33 @@ export function reveal(board: Game, cell: number, now: number): Game {
   return isWon ? { ...started, revealed, status: 'won', endedAt: now } : { ...started, revealed }
 }
 
+/**
+ * Creates a board in the `ready` state, with no mines placed yet.
+ *
+ * @param now - Milliseconds since the epoch, stamped as the start time.
+ * @returns The new board, see `Game`.
+ */
 function newGame(now: number): Game {
   return { size: SIZE, mineCount: MINES, mines: [], revealed: [], flagged: [], status: 'ready', isFlagMode: false, startedAt: now }
 }
 
-/** Starts a new board and shows the pane. */
+/**
+ * Starts a new board and shows the pane.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
 async function startGame($: EngineInterface): Promise<void> {
   const now = await $.clock.now()
   await update($, game, () => newGame(now))
   await $.ui.open({ id: PANE, title: TITLE })
 }
 
-/** Reveals or flags a cell, as the flag mode says, and records a best time on a win. */
+/**
+ * Reveals or flags a cell, as the flag mode says, and records a best time on a win.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param cell - Cell number the player pressed.
+ */
 async function pressCell($: EngineInterface, cell: number): Promise<void> {
   const now = await $.clock.now()
   const after = await update($, game, board => {
@@ -106,11 +143,20 @@ async function pressCell($: EngineInterface, cell: number): Promise<void> {
   }
 }
 
+/**
+ * Switches the board between revealing and flagging cells.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
 async function toggleFlagMode($: EngineInterface): Promise<void> {
   await update($, game, board => (board === null ? board : { ...board, isFlagMode: !board.isFlagMode }))
 }
 
-/** Redraws the timer once a second while a game is on. */
+/**
+ * Redraws the timer once a second while a game is on.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ */
 async function tick($: EngineInterface): Promise<void> {
   if ((await read($, game))?.status === 'playing') $.ui.invalidate('ui.render')
 }
@@ -118,7 +164,12 @@ async function tick($: EngineInterface): Promise<void> {
 let hintTurn: string | undefined
 let isHinted = false
 
-/** Suggests a game once per session, when a turn is still running after a minute. */
+/**
+ * Suggests a game once per session, when a turn is still running after a minute.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param turnId - Turn the hint was scheduled for; the hint is skipped when another turn is running.
+ */
 async function hint($: EngineInterface, turnId: string): Promise<void> {
   if (isHinted || hintTurn !== turnId) return
   if ((await $.ui.panes()).some(pane => pane.id === PANE)) return
@@ -126,6 +177,11 @@ async function hint($: EngineInterface, turnId: string): Promise<void> {
   $.ui.toast('Waiting on Claude? /mini-game opens Minesweeper.')
 }
 
+/**
+ * Registers this mod's `mini-game` command, its session, turn and pane hooks.
+ *
+ * @param on - Hook registration function the engine passes in.
+ */
 export const register: Register = on => {
   on('session.start', async ($, e, next) => {
     await $.command.register({ name: 'mini-game', description: 'Play Minesweeper while Claude works' })
@@ -166,6 +222,12 @@ export const register: Register = on => {
     const record = await read($, best)
     const isOver = board.status === 'won' || board.status === 'lost'
 
+    /**
+     * Draws one cell: a number, a flag, a mine, or a button that reveals or flags it.
+     *
+     * @param cell - Cell number to draw.
+     * @returns The cell element.
+     */
     const cellView = (cell: number) => {
       const isRevealed = board.revealed.includes(cell)
       const isMine = board.mines.includes(cell)

package/mods/tool-timeline/hooks/register.tsx

@@ -31,16 +31,23 @@ const TOOL_COLORS: ReadonlyArray<[RegExp, string]> = [
 /** Input fields that say most about a call, tried in order. */
 const LABEL_FIELDS = ['command', 'file_path', 'notebook_path', 'pattern', 'url', 'query', 'description', 'skill', 'prompt'] as const
 
+/** Finds the badge color of a tool, or the dim color for a tool outside every family. */
 function colorOf(tool: string): string {
   return TOOL_COLORS.find(([match]) => match.test(tool))?.[1] ?? DIM
 }
 
+/** Picks the one-character badge a tool shows: `$` for shell tools, else its first letter. */
 function badgeOf(tool: string): string {
   if (tool === 'Bash' || tool === 'PowerShell') return '$'
   return tool.replace(/^mcp__[^_]+__/, '').charAt(0).toUpperCase()
 }
 
-/** Short form of a call's input: a command, a file's name, a pattern, or the first text field. */
+/**
+ * @brief Shortens a call's input to the text the pane shows: a command, a file's name, a pattern, or the first text field.
+ *
+ * @param input - Arguments of the tool call.
+ * @returns The label, with whitespace collapsed to single spaces.
+ */
 export function labelOf(input: Record<string, unknown>): string {
   for (const field of LABEL_FIELDS) {
     const value = input[field]
@@ -52,7 +59,12 @@ export function labelOf(input: Record<string, unknown>): string {
   return first?.replace(/\s+/g, ' ').trim() ?? ''
 }
 
-/** Text of a tool result's content, which is a string or a list of text blocks. */
+/**
+ * @brief Joins the text of a tool result's content, which is a string or a list of text blocks.
+ *
+ * @param content - Result content: a string, or a list of blocks with a `text` field.
+ * @returns The text, one block per line.
+ */
 function resultText(content: unknown): string {
   if (typeof content === 'string') return content
   if (!Array.isArray(content)) return ''
@@ -61,16 +73,17 @@ function resultText(content: unknown): string {
     .join('\n')
 }
 
-/** Whether an error text reads as a refusal: a hook's deny, the permission dialog's no, a blocked call. */
+/** Checks whether an error text reads as a refusal: a hook's deny, the permission dialog's no, a blocked call. */
 function isRefusal(text: string): boolean {
   return /\bdenied\b|\bblocked\b|doesn't want to proceed|was rejected|permission/i.test(text)
 }
 
+/** Formats a duration in milliseconds as seconds, with one decimal below ten seconds. */
 function seconds(ms: number): string {
   return ms >= 10_000 ? `${Math.round(ms / 1000)}s` : `${(ms / 1000).toFixed(1)}s`
 }
 
-/** Short note for the callout, e.g. `use the trash` for delete-guard's deny. */
+/** Shortens a call's note for the callout, e.g. `use the trash` for delete-guard's deny. */
 function shortNote(note: string | undefined): string {
   if (note === undefined) return ''
   if (/trash/i.test(note)) return 'use the trash'
@@ -78,7 +91,13 @@ function shortNote(note: string | undefined): string {
   return text.length > 40 ? `${text.slice(0, 39)}…` : text
 }
 
-/** Adds a call or changes the one with its id; the list stays in start order and capped. */
+/**
+ * @brief Adds a call or changes the one with its id; the list stays in start order and capped.
+ *
+ * @param $ - Engine handle the calls state is updated through.
+ * @param id - Tool use id of the call.
+ * @param patch - Builds the call's next value from its stored value, or from `undefined` when the call is new.
+ */
 async function patchCall($: EngineInterface, id: string, patch: (call: TimelineCall | undefined) => TimelineCall): Promise<void> {
   await update($, calls, list => {
     const index = list.findIndex(call => call.id === id)
@@ -87,7 +106,14 @@ async function patchCall($: EngineInterface, id: string, patch: (call: TimelineC
   })
 }
 
-/** Ends a call with its status, keeping the first ending it got. */
+/**
+ * @brief Ends a call with its status, keeping the first ending it got.
+ *
+ * @param $ - Engine handle the calls state is updated through.
+ * @param id - Tool use id of the call.
+ * @param status - Status the call ends with.
+ * @param note - Text shown with the status, such as a refusal reason.
+ */
 async function settleCall($: EngineInterface, id: string, status: CallStatus, note?: string): Promise<void> {
   const endedAt = await $.clock.now()
   await patchCall($, id, call =>
@@ -97,23 +123,46 @@ async function settleCall($: EngineInterface, id: string, status: CallStatus, no
   )
 }
 
-/** Redraws the pane while a call runs, so its bar and time move. */
+/**
+ * @brief Redraws the pane while a call runs, so its bar and time move.
+ *
+ * @param $ - Engine handle the pane is redrawn through.
+ */
 async function tick($: EngineInterface): Promise<void> {
   const list = await read($, calls)
   if (list.some(call => call.status === 'running')) $.ui.invalidate('ui.render')
 }
 
-/** The call a denied call was replaced by: the next call of the same tool. */
+/**
+ * @brief Finds the call that replaced a denied call: the next call of the same tool.
+ *
+ * @param list - Calls in start order.
+ * @param index - Position of the denied call in `list`.
+ * @returns The replacing call, or `undefined` when none follows.
+ */
 function replacementOf(list: readonly TimelineCall[], index: number): TimelineCall | undefined {
   const denied = list[index]
   return denied === undefined ? undefined : list.slice(index + 1).find(call => call.tool === denied.tool)
 }
 
+/**
+ * @brief Builds the SVG of a track with a bar filled to `fill` pixels.
+ *
+ * @param width - Width of the track in pixels.
+ * @param fill - Filled length in pixels, clamped to the width.
+ * @param color - Fill color.
+ * @returns The SVG markup.
+ */
 function barSvg(width: number, fill: number, color: string): string {
   const w = Math.max(0, Math.min(width, fill))
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="8" viewBox="0 0 ${width} 8"><rect width="${width}" height="8" rx="2" fill="${TRACK}"/><rect width="${w.toFixed(1)}" height="8" rx="2" fill="${color}"/></svg>`
 }
 
+/**
+ * @brief Subscribes the timeline's handlers to the engine's events, its command and its pane.
+ *
+ * @param on - Subscribes a handler to one engine event, optionally filtered.
+ */
 export const register: Register = on => {
   on('session.start', async ($, e, next) => {
     await $.command.register({ name: 'tool-timeline', description: 'Show or hide the tool call timeline' })
@@ -185,12 +234,14 @@ export const register: Register = on => {
     const now = await $.clock.now()
     const room = Math.max(4, (e.viewport?.rows ?? 30) - 6)
     const shown = list.slice(-room)
+    /** Length of a call so far, or up to its end when it has one. */
     const durationOf = (call: TimelineCall): number => (call.endedAt ?? now) - call.startedAt
     const longest = Math.max(1, ...shown.map(durationOf))
     const total = list.reduce((sum, call) => sum + (call.status === 'denied' ? 0 : durationOf(call)), 0)
     const barCells = Math.max(8, Math.floor(e.props.bodyColumns * 0.3))
     const labelCells = Math.max(12, e.props.bodyColumns - barCells - 12)
 
+    /** Draws the bar showing a call's share of the longest call's time. */
     const bar = (call: TimelineCall) => {
       const color = call.status === 'error' ? ERROR : call.status === 'ok' && /^Bash$/.test(call.tool) ? '#5fae6e' : colorOf(call.tool)
       const share = call.status === 'denied' ? 0.04 : Math.max(0.03, durationOf(call) / longest)
@@ -208,6 +259,7 @@ export const register: Register = on => {
       return <Svg source={barSvg(width, share * width, color)} alt={`${call.tool} ${seconds(durationOf(call))}`} width={width} height={8} />
     }
 
+    /** Renders a call's status at the end of its row: its time, `denied`, `queued` or a mark for an error. */
     const outcome = (call: TimelineCall) => {
       switch (call.status) {
         case 'denied': return <Text color={ERROR}>denied</Text>

package/mods/you-should-know/hooks/register.tsx

@@ -23,11 +23,17 @@ const SYSTEM = [
 
 const BULB_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" fill="#3d3424"/><path d="M20 11a6 6 0 0 0-3.6 10.8c.8.6 1.1 1.3 1.1 2.2v1h5v-1c0-.9.3-1.6 1.1-2.2A6 6 0 0 0 20 11z" fill="none" stroke="#e5b567" stroke-width="1.6"/><path d="M17.5 28h5M18.3 30.5h3.4" stroke="#e5b567" stroke-width="1.6" stroke-linecap="round"/></svg>'
 
+/** Collapses every run of whitespace to one space and trims both ends. */
 function normalize(text: string): string {
   return text.replace(/\s+/g, ' ').trim()
 }
 
-/** Reads the model's answer: a card's headline and detail, or `undefined` for a skip or anything malformed. */
+/**
+ * @brief Reads the model's answer into a card's headline and detail.
+ *
+ * @param text - Raw answer from the model.
+ * @returns The headline and detail, or `undefined` for a skip or anything malformed.
+ */
 export function parseCard(text: string): Omit<Card, 'tail'> | undefined {
   const json = /\{[\s\S]*\}/.exec(text)?.[0]
   if (json === undefined) return undefined
@@ -43,7 +49,13 @@ export function parseCard(text: string): Omit<Card, 'tail'> | undefined {
   return { headline: headline.trim().slice(0, 90), detail: detail.trim().slice(0, 160) }
 }
 
-/** Asks the model for the reply's key point and keeps the card when there is one. */
+/**
+ * @brief Asks the model for the reply's key point and keeps the card when there is one.
+ *
+ * @param $ - Engine handle the model call and the cards state go through.
+ * @param answer - Full text of the assistant's reply.
+ * @param model - Model that reads the reply.
+ */
 async function extract($: EngineInterface, answer: string, model: string): Promise<void> {
   const result = await $.model.complete({ model, system: SYSTEM, prompt: answer.slice(-MAX_PROMPT_CHARS), maxTokens: 300 })
   if (!result.isAnswered) return
@@ -53,6 +65,12 @@ async function extract($: EngineInterface, answer: string, model: string): Promi
   await update($, cards, list => [...list.filter(one => one.tail !== tail), { tail, ...card }].slice(-KEEP))
 }
 
+/**
+ * @brief Subscribes the card handlers to the engine's events and renders the card.
+ *
+ * @param on - Subscribes a handler to one engine event.
+ * @param options - Plugin options: `minChars` sets the shortest reply read, `model` the model that reads it.
+ */
 export const register: Register = (on, options) => {
   const minChars = Number(options.minChars ?? DEFAULT_MIN_CHARS)
   const model = typeof options.model === 'string' && options.model.length > 0 ? options.model : DEFAULT_MODEL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3nomaly/g3n-mods",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The g3n Claude Code mods: panes, status lines, commands and hooks, installed with @g3nomaly/mods.",
   "type": "module",
   "files": [