Skip to content
Jordan Hudgens
Illustration: a matte-white capsule robot at a dark navy workbench slides a mint-green cartridge into a rounded white housing topped by three glowing glass tubes, beside a row of colored glass tiles, an opened cartridge, a brass toggle switch and a copper desk lamp.AI-generated illustration
Guide 12IntermediateClaude Code and agentic codingEvaluation and testingSecurity and containment

Extend Claude Code from the Inside: Build a Forkable Visual Mod

Build Model Ledger, a Claude Code mod that draws per-model tokens and estimated cost in the session, test it offline, break it, and decide which mods may load.

Reading
88 min
Workshop
120 min
Stack
TS · Claude Code 2.1.325 · Node.js 22 · pnpm 12
Version
1.0.0
Last verified
Nov 15, 2026

What you will build and be able to do

Each outcome has an observable criterion. The lab and the assessment check exactly these, nothing more and nothing less.

  1. OBJ-001

    Explain what a mod is and how it loads, then inspect one

    Explain what a mod is and how it loads, then inspect one: read its register function, run "claude plugin validate --strict --json", list it in /plugin, load it with claude --plugin-dir, read the build's generated types, and use hot reload.

  2. OBJ-002

    Collect per-step usage and keep state

    Collect per-step usage and keep state: a turn.step async generator reading result.usage, e.agentId and result.serverToolUses, an agent.spawn hook building the subagent tree, $.session.usage() readings, and totals that survive a module reload, /clear and organization-managed sessions.

  3. OBJ-003

    Render across surfaces

    Render across surfaces: a Pane with a bounded terminal Raster bar and heat chart, a Box and Text fallback for Desktop and VS Code, an AbovePrompt band, and a /ledger command.

  4. OBJ-004

    Diagnose and repair four seeded failures

    Diagnose and repair four seeded failures (the 10-second hook limit, a self-opened pane below 144 columns, Raster on Desktop, an oversized Raster), each from the line Claude Code prints, with a regression test that fails before the fix.

  5. OBJ-005

    Apply safety and organization controls

    Apply safety and organization controls: an opt-in mutating guard with a .catch fallback, cost labeled as an estimate, no secret or network capability in a visual mod, a tier('prepend') policy mod, and managed settings (allowManagedModsOnly on the built-in guard, prependPlugins, disableSideloadFlags, disableAllHooks), written up in trust-boundaries.md.

Unpack the download and check your tools ($0.00)

  • Node.js 22.18.0 or later and pnpm 12. The labs pin Node.js 22.23.5 (.node-version) and pnpm 12.14.0 through Corepack (corepack enable reads the packageManager field). The lab kit is plain TypeScript that Node runs through its built-in type stripping, so pnpm install installs nothing.pnpm installation guide
  • Git, a POSIX shell, and working TypeScript. You write hooks in TypeScript and read type declarations.
  • Claude Code 2.1.325 from the native installer. "claude plugin validate" and "claude plugin test" run offline with no sign-in and cost $0.00. Claude Code 2.1.311 (npm stable on 2026-11-14) runs every mechanism here the same way, but its validate skips the TypeScript check, which several labs rely on; 2.1.323 added that check (Claude Code changelog, checked 2026-11-15).Claude Code setup
  • For the optional live route only: an Anthropic API key in a workspace with a spend limit you control. Each live task runs in a scratch HOME with --max-budget-usd and --max-turns and costs about $0.02 to $0.05. A terminal at least 144 columns wide shows the pane that opens itself; LAB-003 uses a narrower one on purpose.
  • Guide 05 and Guide 10, or equivalent experience with plugins, skills and settings hooks. The first lesson section restates what this guide uses from them. Guide 07 helps, because Model Ledger draws the routing it measures.Read the primer

Model Ledger: one wiring file, two seams

Model Ledger's shape: Claude Code's events reach one wiring file, which hands plain inputs to pure modules and returns the tree each surface draws.
Architecture diagram: Claude Code's events flow into hooks/register.ts, the only file that calls $, which passes inputs to pure modules in src/ (collector.ts is seam 1, render.ts is seam 2) and writes $.state and $.store; the tree it returns is drawn as Raster on the terminal and as Box and Text on Desktop and VS Code.
Extended description

hooks/register.ts registers 9 hooks on 8 events (classic.SessionStart, session.start, turn.start, turn.step, agent.spawn, turn.complete, command.run and ui.render, which has one hook for the pane and one for the band above the prompt). It is the only file that calls the mods API, and it writes each call out in full so "claude plugin validate" lists it. It passes plain inputs to the modules in src/, which never see $: collector.ts (seam 1) turns events into records, ledger-store.ts holds the reducers and store keys, pricing.ts the dated price table, spawn-guard.ts the reroute decision, and render.ts (seam 2) builds the tree from a ledger and a size.

With their results, register.ts writes the live ledger to $.state atoms, which /clear resets, and saves it with $.store.set to the store, which holds up to 4 MiB and is kept across sessions. Writing an atom makes Claude Code redraw the pane and the band: the terminal draws the tree's Raster bars, and Desktop and VS Code draw Box and Text. A fork edits the modules in src/ and registers its own hooks in the wiring file.

What this guide takes from Guides 05 and 10

Three Claude Code extensions get confused, and the differences decide which one a job needs:

Settings hooks, skills and mods compared.
AspectSettings hook (Guide 05)Skill (Guide 10)Mod (this guide)
What it isA command in settings.json that Claude Code runs on events such as PreToolUseInstructions and files Claude loads when a task matchesA plugin whose TypeScript or JavaScript code registers hooks inside Claude Code
Where it runsA separate process per eventIn Claude's contextIn Claude Code's hooks runtime, with the $ mods API
Can it draw in the interfaceNoNoYes: panes, a band above the prompt, transcript lines
Can it keep stateOnly in files its command writesOnly in files its scripts write$.state in memory and $.store on disk
Can it change what Claude Code doesAllow, deny or add feedback around tool callsShape Claude's workRewrite or answer events, such as a subagent's model

A plugin is a directory with .claude-plugin/plugin.json. Guide 10's skills and this guide's mod both ship that way, and claude plugin validate checks both. The neighbors keep their subjects: Guide 05 owns headless verification, settings hooks, deny rules and OS sandboxing; Guide 10 owns SKILL.md packaging and activation testing; Guide 07 owns measuring whether routing saves money; Guide 03 owns prompt injection and containment.

What a mod is and how it loads

"A mod is a plugin whose code registers event handlers, called hooks" (Mods overview, checked 2026-11-15). Model Ledger's hooks/hooks.json names one hooks module:

hooks/hooks.jsonjson
{  "modules": ["./register.ts"]}

hooks/register.ts exports register(on, options). Claude Code calls it once when the module loads; on registers hooks, and options holds "the values of the userConfig fields the manifest declares, with defaults filled in" (Mods reference, checked 2026-11-15). There is no build step: Claude Code runs .ts and .js directly.

How a mod reaches a session:

  • Installed through /plugin, or loaded for one session with claude --plugin-dir ./model-ledger. "Claude Code watches a directory loaded with --plugin-dir and hot-reloads the hooks module when a file in it changes" (Create a mod), and each reload runs register and session.start again. "Mods are on by default. In the terminal, use Claude Code v2.1.287 or later" (Mods overview). /plugin shows a count line such as 1 mod active · model-ledger.
  • Print mode and the Agent SDK run hooks too, the overview says, unless you pass --bare or --safe-mode; this guide ran print mode, not the SDK. In the spike, --bare printed hooks module spike-probe@inline not loaded: installed plugins that are not managed load no hooks module in this mode (--bare); built-in plugins load regardless.
  • Generated types. When Claude Code loads a mod from --plugin-dir in an interactive session, it writes declaration files into the mod's .claude-plugin/types/. "The events and methods can change between releases, so trust these files over any page, this one included, when they disagree" (Create a mod, checked 2026-11-15). The interactive session also writes a tsconfig.json at the top of the mod folder; the labs' .gitignore lists both.

The middleware chain

Every hook sits in a chain. It receives $ (the mods API), e (the event) and next (the rest of the chain, ending in Claude Code's own behavior), and it does one of three things: observe (return next(e), or await it and read the result), rewrite (return next({ ...e, model })), or answer without calling next. "The event itself is immutable: it's deeply frozen, and assigning to a field throws" (React to events, checked 2026-11-15), which is failure gallery card F-06.

The failure rule matters more than any other: "If the handler itself throws or times out, Claude Code skips the hook as if it had no handler" (React to events). A hook that guards something fails open unless you add a .catch handler, which answers in its place.

One more rule applies when a module registers two hooks on one event, as a gate and a recorder for Bash would. Claude Code runs a module's hooks for an event as one unit. In this guide's probes, when the second of two tool.call hooks threw, the first hook's .catch answered, with next.called false, and its next(e) ran the tool, so the second hook's own .catch, which would have refused, never ran. That held live on 2.1.325 and in the test kit on 2.1.325 and 2.1.311. Register a hook that guards something ahead of the other hooks on its event, so its .catch is the one that answers.

What validate reads

claude plugin validate --strict --json <dir> analyzes the manifest and hooks module without running them and lists what the module hooks and calls. For the finished mod it prints notes such as:

Offline output, recorded 2026-11-15 with Claude Code 2.1.325 ($0.00):

Offline, 2026-11-15text
"./register.ts hooks: session.start, classic.SessionStart{source=clear|resume|fork}, turn.start, turn.step, agent.spawn, turn.complete, command.run{command=ledger}, ui.render{component=Pane} (default matcher key: plugin), ui.render{component=AbovePrompt} (default matcher key: plugin)","./register.ts answers its own command: command.run{command=ledger}","./register.ts gating hook with .catch: classic.SessionStart{source=clear|resume|fork}","./register.ts gating hook with .catch: agent.spawn","./register.ts calls: $.clock.now, $.command.register, $.session.id, $.session.usage (via engineUsd, reconcile), $.state.get, $.state.set, $.store.delete (via startFresh), $.store.get (via addToHistory, loadToday, restoreAfterReset, restoreOrStart), $.store.keys (via startFresh), $.store.set (via addToHistory, save), $.ui.close, $.ui.log, $.ui.open (via openPane), $.ui.resolve","./register.ts state writes: model-ledger.guard, model-ledger.ledger, model-ledger.notice, model-ledger.today","./register.ts state reads: model-ledger.guard, model-ledger.ledger, model-ledger.notice, model-ledger.today"

Those lists are only exact if you write every call in full. "Don't assign $ or one of its namespaces to a variable, destructure it, or index it with a computed name" (Create a mod). On 2.1.325, --strict also type-checks the module and its tests against the build's own declarations, and fails on any finding.

The JSON has two more sections. directory holds the plugin directory's listing checks, such as a missing icon; they do not count toward success, and the section's own note says passing here does not mean the directory accepts the plugin when it has a hooks module. advice suggests an install line for the README. Both are about publishing a listing, which the local labs do not need.

Model Ledger's shape: one wiring file, two seams

Model Ledger's files: what each one does, and whether it sees $.
FileJobSees $
hooks/register.tsWires each event to the pure modules and writes every mods API call in fullYes
src/collector.ts (seam 1)Turns a turn.step result, an agent.spawn and a usage reading into plain recordsNo
src/ledger-store.tsPure reducers (applyStep, applySpawn, applyUsage) and the store keysNo
src/pricing.tsThe dated price table and its userConfig overrideNo
src/render.ts (seam 2)Draws the pane, band and /ledger text from a ledger and a sizeNo: it receives the element constructors
src/spawn-guard.tsDecides whether a spawn is reroutedNo
types/index.d.tsDeclares the state atoms and record typesNo: declarations only

Keeping $ out of src/ buys three things. The pure modules run under plain Node, so the offline replays draw from them and the unit tests need no stubs. Validate's lists stay complete, because every call is in one file. And a fork changes what is collected and drawn in the pure modules, touching the wiring only to register its own hooks.

The mod also calls nothing a visual mod does not need: no $.fs, $.process, $.http, $.env, $.mcp or $.model. The lab kit's contract checker reads validate's call list and fails a copy that adds one (rule MLC-08), so a fork that quietly uploads usage fails before anyone loads it.

Collecting usage: turn.step, agent.spawn and the engine's figure

One recorded session passing through Model Ledger's four stages: event, handler, store and render. The motion takes one agent.spawn and one turn.step through the stages, plays the run's other four steps, and ends on this frame. Silent loop, 18 seconds.
Extended description

The session is a print-mode run of the delegated lookup task with the guard on, recorded on 2026-11-15 and played back through Model Ledger's own modules, as pnpm mod:replay does. At 2.39 s, agent.spawn fires for an Explore subagent whose parent runs on claude-sonnet-5-5. The guard asks for claude-haiku-5-5 with next({ ...e, model }), $.state.set adds a subagent row, $.store.set saves the ledger, and the pane, with no step yet, reads No model steps yet. Send a prompt to fill the ledger.

At 2.41 s, the first turn.step result arrives from the main loop on claude-sonnet-5-5: 2 input, 189 output, 11,495 cache-read and 5,470 cache-write tokens. The handler's const result = yield* next(e) hands the result on, $.state.set records 1 step and $0.0167 estimated, and the pane draws a sonnet bar. The subagent's three steps on claude-haiku-5-5 follow at 4.63 s (2 input, 307 output, 0 cache-read and 8,955 cache-write tokens; $0.0180 in all), 5.81 s (2, 111, 8,955 and 690; $0.0182) and 6.83 s (2, 55, 9,645 and 237; $0.0184).

The main loop's last step at 7.89 s (2, 43, 16,965 and 446) brings the ledger to 5 steps and $0.0216 estimated, and the pane shows a full sonnet bar beside a short haiku bar.

Every step, from an async generator

"Write a turn.step hook as an async generator, because the event streams. yield* next(e) forwards the response as it streams and evaluates to the finished result" (React to events). Model Ledger's hook passes every chunk through unread and records the result:

hooks/register.tsts
// turn.step must be an async generator: yield* passes every chunk through, and the// result, with its usage, arrives when the step endson('turn.step', async function* ($, e, next) {  const result = yield* next(e)  const rec = stepRecord(e, result, await $.clock.now())  await ensureLedger($)  if (rec === null) {    const at = await $.clock.now()    await update($, ledger, (l) => (l === null ? l : applyNoUsage(l, at)))  } else {    await update($, ledger, (l) => (l === null ? l : applyStep(l, rec, prices)))    await addToHistory($, rec, stepUsd(rec, prices))  }  await save($)  return result})

result.usage carries input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens and model; e.agentId is set on a subagent's steps. The pricing module turns those four counts into dollars at the dated list rates, with cache writes at the 5-minute rate, and the ledger keeps per-model rows.

Advisor calls carry no tokens

result.serverToolUses lists tool calls the API ran inside the request, such as the advisor; "Claude Code doesn't run these calls, so no tool.call or tool.check hook fires for them" (React to events). Each entry has a name and timing and no tokens, and result.usage is the executor's alone: "Top-level usage fields reflect executor tokens only" (Advisor tool, checked 2026-11-15). In the spike's advisor run, the steps summed to 285 output tokens while Claude Code's modelUsage reported 919, and the session cost of $0.0747244 included the advisor's sub-inference. So the ledger counts advisor calls and their wall time, and never invents their tokens.

The subagent tree

agent.spawn fires when Claude starts a subagent. The hook records the type, description, requested and parent model, and the agentId it gets back from next, which links the subagent's later steps to its row. It never reads e.prompt, which can hold anything the parent pasted into the delegation (rule MLC-09).

Reconciling with Claude Code's own figure

After each main-loop turn.complete, the mod reads $.session.usage(), which "returns context window use and plan limits" (Use the mods API, checked 2026-11-15), plus Claude Code's cost for the session. The difference between that cost and the priced steps is the row "Not in any step". In print mode it was zero in every ledger run. In interactive sessions it was not, because Claude Code makes requests no step reports: a session title on Haiku 5.5 with the first prompt, and a prompt suggestion after each turn. In the recorded 150-column session, the pane read Not in any step: $0.0068 when the last turn ended. The last suggestion landed after that reading, so /ledger status reads usage again before it answers; its $0.0102 then equaled /cost's $0.0430 less the priced steps.

Both figures are estimates. "Claude Code computes the dollar figure locally from token counts at list price, unless a modelPricing table is in effect" (Manage costs effectively, checked 2026-11-15), and the ledger labels every dollar figure the same way, with the date of its table.

What the measured runs showed

On 2026-11-15, ten measured print-mode runs worked three small tasks (read and answer, a one-line edit checked by tests, and a delegated Explore lookup) with no mod, with a recorder mod alone, and with Model Ledger:

  • No overhead. The read-and-answer task cost $0.017813 in all four of its runs, with identical modelUsage, and the first request's prompt was 16,957 tokens with and without Model Ledger. The mod's hooks send nothing to the model; only /ledger answers enter the conversation, which is why they are one short line.
  • Exact per-model figures. In all nine print-mode task runs that loaded Model Ledger (six of the measured runs and three through the lab kit's kit/live/run.sh), its per-model tokens and dollars equaled Claude Code's modelUsage and total_cost_usd.
  • The guard moved the subagent. With the guard on, Explore ran on claude-haiku-5-5 both when the guard asked for the full id and when it asked for the alias haiku.
Bar chart: in nine print-mode runs, Model Ledger's per-model figures equaled Claude Code's own, with run costs from $0.017813 to $0.049309; a side panel splits an interactive session's /cost of $0.0430 into $0.0328 of priced steps and $0.0102 that was in no step.
Model Ledger against Claude Code's own cost, one run per row, recorded on 2026-11-15 with Claude Code 2.1.325 and claude-sonnet-5-5 at effort medium.
Extended description

T1 reads a file and answers, T2 makes a one-line edit that the tests check, and T3 delegates a lookup to an Explore subagent. Each bar is the run's total_cost_usd, split by its modelUsage, and in all nine print-mode runs the ledger's tokens and dollars per model equaled those figures. T1 cost $0.017813 in both measured runs and T2 $0.026386.

With the guard off, T3 ran entirely on claude-sonnet-5-5 for $0.038437. With the guard on, the subagent ran on claude-haiku-5-5: $0.021622 in all, $0.019964 of it on Sonnet and $0.001658 on Haiku, and $0.025403 when the guard asked for the alias haiku ($0.023883 and $0.001521). The kit rows are three runs through the lab kit's kit/live/run.sh, which leaves the guard off: T1 for $0.017835, T3 for $0.049309 with its subagent on Sonnet, and T1 again for $0.017866.

The panel is an interactive session at 150 columns that ran T1 and then T3 with the guard on: /cost read $0.0430, Model Ledger priced its steps at $0.0328 ($0.0313 on Sonnet, $0.0015 on Haiku), and $0.0102 was in no step. That remainder is requests Claude Code makes on its own, which no step reports; the debug log of an earlier capture of the same steps named a session-title request and prompt suggestions. These are single runs of small tasks: they show that the ledger matches Claude Code's figure, not what a routing choice saves.

These are single runs of small tasks. They show that the ledger reports what Claude Code reports; whether a routing choice saves money on your work is Guide 07's method.

State that outlives a reload and a /clear

Model Ledger keeps two kinds of state:

  • $.state atoms hold the live ledger. "It's reactive state: a ui.render hook that reads a value subscribes to it, so Claude Code redraws that site each time you write the value" (Draw in the interface, checked 2026-11-15). Atoms survive a module reload. /clear, /resume and /branch "reset every $.state value to its default, and session.start doesn't fire again" (Draw in the interface).
  • $.store is "a JSON key-value store of your plugin's own, kept between sessions" (Use the mods API), up to 4 MiB in total, and "every session on your machine that runs your mod shares one $.store. A get followed by a set isn't atomic" (Draw in the interface). So each session writes under its own key (ledger:v1:<session id>), the newest ten are kept, and the shared daily history is read again right before each write.

After /clear, a classic.SessionStart hook with source clear, resume or fork restores the saved ledger. That hook is not enough on its own. Where an organization manages Claude Code, the built-in guard passes over a user mod's classic.* hooks; the spike's /plugin Errors tab said Its hooks on classic.SessionStart do not run here: where an organization manages Claude Code, these events pass over the plugins you install. So every writer first calls ensureLedger, which restores the saved copy whenever the atom is empty:

hooks/register.tsts
// Runs after /clear, /resume and /branch (source 'fork'), which reset every $.state valueon('classic.SessionStart', { source: ['clear', 'resume', 'fork'] }, async ($, e, next) => {  await restoreAfterReset($)  // Before this process's first session.start, the session is not bound yet  if (!started) rebaseAtStart = true  return next(e)}).catch(async ($, e, next) => {  // A failed restore must not hold up the session: it goes on, and the next turn restores  $.ui.log('restoring the totals failed (' + next.error.kind + '); the next turn tries again')  return next(e)})

A module variable keeps the ledger's store key across /clear, where $.state resets, and the atom keeps it across a reload, where module variables reset, so either path finds the right copy.

Recorded behavior worth knowing before you teach it: after /clear, Claude Code's /cost starts again at $0.0000, while Model Ledger restores its totals and shows Context unknown of 1.00M tokens until the next turn reports context. The ledger outlives the conversation that /cost counts.

A resumed claude -p process orders the two start events the other way. classic.SessionStart with source resume runs first, while no session is bound, and $.session.usage() answers a cost of 0 there; by session.start it answers the resumed session's whole cost. The ledger counts every rise in that figure as new spend, so a ledger restored in the first hook counted the resumed cost a second time: in the clean-room walk, /ledger status after a $0.0178 run answered $0.0178 not in any step. Model Ledger now takes the baseline again at session.start for a ledger restored before it, and an Increment 2 test fires the two events in that order.

Drawing on three surfaces

Real terminal capture of Model Ledger's pane at 150 columns: a long blue bar for claude-sonnet-5-5 at $0.0313 and a short green bar for claude-haiku-5-5 at $0.0015, a strip of eight recent steps, totals of 133.7k tokens and $0.0328 estimated, an amber line of $0.0068 not in any step, the guard's state and the subagent tree.
Model Ledger's pane in a real interactive session on 2026-11-15, where a 150-column terminal docks it on the right with a 66-column body.
Extended description

The session ran T1 and then T3 with the guard on. Its screen was played back from the session's recorded terminal output with xterm.js and cropped to the pane without scaling. The blue bar is claude-sonnet-5-5: 5 steps, 107.8k tokens, $0.0313.

The short green bar is claude-haiku-5-5, where the guard sent the Explore subagent: 3 steps, 25.8k tokens, $0.0015. The strip of recent steps has one cell per step, colored by cost: the first, the costliest, is red and the other seven are blue. Below it: 133.7k tokens and $0.0328 estimated over 8 steps, context at 22.4k of 1.00M tokens (2 percent), today's total, the guard's state, and the subagent tree, whose row is cut to the pane's width.

The amber line reads $0.0068 because this capture was taken as the last turn ended, before Claude Code's last prompt suggestion landed. /ledger status reads usage again before it answers, and a moment later it answered $0.0102, which is /cost's $0.0430 less the priced $0.0328. Every dollar figure is an estimate at list prices.

The pane and its width

$.ui.open({ id, title }) asks for a pane. One the person asks for opens at any width. One a mod opens on its own, such as at session start, "appears only in a terminal at least 144 columns wide. After the user has opened that pane once themselves, 110 columns is enough" (Draw in the interface). $.ui.open resolves { isPlaced: false, reason } when it waits, and Model Ledger says so in the transcript and the band rather than failing silently. The recorded sessions showed three placements:

Where the pane appeared in the sessions recorded on 2026-11-15, by terminal width.
TerminalThe pane opened at startAfter /ledger open
150 columnsDocks on the right with a 66-column bodyAlready open
120 columnsWaits, and the mod prints the pane is not shown yet: unasked below 144 columns (120 now): ...Docks with a 49-column body
80 columnsWaitsPlaced inline under the conversation, with a 76-column body
Two real terminal screens shown small, the pane outlined in green: at 120 columns the pane waits, unasked below 144 columns, until /ledger open docks it with a 49-column body; at 80 columns it waits the same way, and /ledger open places it inline with a 76-column body.
Below 144 columns, a pane the mod opens on its own waits until the person asks for it; two real interactive sessions recorded on 2026-11-15.
Extended description

Each picture is a whole terminal screen after the first task, reduced so the pane's position reads at a glance; its text is too small to read by design, and the lines that matter are set beside it. In the 120-column session, Model Ledger asked for its pane at session start, Claude Code held it, and the mod printed model-ledger: the pane is not shown yet: unasked below 144 columns (120 now): placed when the person opens it, or when the terminal is widened to 144 columns. After /ledger open, the pane docked on the right with a 49-column body.

In the 80-column session the notice read (80 now), and /ledger open placed the pane inline under the conversation with a 76-column body. A pane the person opens appears at any width.

focus, closeOnEscape and holdToasts "accept only true. To leave one off, omit it. Passing false throws an error such as ui.open: focus is true or left out" (Draw in the interface), which is card F-08.

Raster on the terminal, text everywhere else

The ui.render hook branches on e.surface, because "apps other than the terminal have no Raster, so check e.surface and draw text there" (Draw in the interface):

hooks/register.tsts
on('ui.render', { component: 'Pane' }, async ($, e, next) => {  if (e.requestId !== PANE_ID) return next(e)  const live = await read($, ledger)  const side = await sideNow($, prices, config)  const view = { columns: e.props.bodyColumns, rows: e.props.scroll.bodyRows, theme }  // Raster is in the terminal's element table only; Desktop and VS Code get the text layout  if (e.surface === 'terminal') {    const { Box, Text, Raster } = $.ui.resolve(e)    return terminalPane({ Box, Text, Raster }, live, side, view)  }  const { Box, Text } = $.ui.resolve(e)  return textPane({ Box, Text }, live, side, view)})

A Raster takes "key, columns up to 512, rows up to 256, cells" (Mods reference), and one tree holds at most 262,144 Raster cells. "Each cell is three numbers: the character's code point, its color, and its background color", and "the value 0x01000000, one above that range, means the terminal's default" (Draw in the interface). The renderer fits each Raster to the pane's bodyColumns and to those limits, folds a long session's steps into the heat strip's buckets, and packs cells with its own base64 encoder, since the generated tsconfig.json targets a library without Uint8Array.prototype.toBase64. Where a bar would not fit, it draws the text table instead. Desktop and VS Code always get the table.

The same recorded session drawn by Model Ledger's renderer for the terminal at two widths and for Desktop and VS Code. The motion redraws all three after each event and ends on this frame. Silent loop, 13 seconds.
Extended description

The bars and tables are the renderer's own output for each surface and width, from the guard-on run of the delegated lookup task recorded on 2026-11-15. On the terminal, the pane's Raster bars are 24 cells wide in the 66-column body of a docked pane at 150 columns and 14 cells wide in the 49-column body at 120 columns, in the renderer's own colors. Desktop and VS Code have no Raster, so they get a Box and Text table of block characters.

At 2.39 s, agent.spawn starts the Explore subagent and every view reads No model steps yet. Send a prompt to fill the ledger. At 2.41 s, a main-loop step on sonnet-5-5 adds $0.0167; the table reads 1 step and 17.2k tokens, with the line Total 17.2k tokens, $0.0167 estimated, 1 step. The subagent's steps on haiku-5-5 add $0.0013 at 4.63 s (1 step, 9.3k tokens), $0.0002 at 5.81 s (2 steps, 19.0k, $0.0015) and $0.0002 at 6.83 s (3 steps, 29.0k, $0.0017).

The last step at 7.89 s adds $0.0032 on sonnet-5-5, for 2 steps, 34.6k tokens and $0.0200. Each step also adds a cell to the strip of recent steps: the first, the costliest, is red and the rest are blue.

The band above the prompt

The AbovePrompt hook draws one dim line and keeps what next(e) returns beneath it, so another mod's band still shows. From 2.1.323, each mod's rows stack; before that, mods shared one band drawing. At narrow widths the band drops its model counts and context first.

One thing only a real terminal shows: the test kit's find returns each Text's children, not laid-out lines, so text cut at a narrow width looks whole in a test. The 49-column dock cut sentences in an early capture, which is why the pane now wraps sentences and cuts only table cells.

Real terminal capture of a probe pane with three boxes: borderStyle 'round' draws rounded corners, 'rounded' draws no border and 'single' draws square corners; below it, Claude Code 2.1.325's message that 'rounded' is not a border style and the Box is drawn with no border.
Failure gallery card F-09 in a real terminal: borderStyle: 'rounded' draws no border, and Claude Code 2.1.325 says so in the conversation.
Extended description

A probe mod drew one pane with three Box elements, each with a different borderStyle, in an interactive session on 2026-11-15. No prompt was sent, so no model request ran, and /cost read $0.0000: everything shown is Claude Code drawing a mod's tree. The screen was played back from the session's recorded terminal output with xterm.js and cropped to the pane without scaling.

'round' draws rounded corners and 'single' square ones; 'rounded', which is not a style, draws the text with no border. Claude Code printed the message below the crop in the conversation and logged it as a warning, while claude plugin validate --strict and the test suite pass the mistake, because neither checks a drawn border.

The /ledger command and the opt-in spawn guard

$.command.register adds /ledger at session start, and an on('command.run', { command: 'ledger' }, ...) hook answers it: status, open, close, reset, export, guard on and guard off. Two details came from the runs. Registering a name that is taken throws, and a hook that throws is skipped, so the mod registers last, inside try, and says when /ledger is unavailable. And a command's text goes into Claude's next request, so status answers in one line. export writes its JSON through $.ui.log, which shows in the transcript and is not sent to the model.

The guard is the one part of Model Ledger that changes what Claude Code does, so it is off by default (guard_enabled: false in userConfig) and /ledger guard on turns it on for one session. "To send a request to a different model, pass next the event with model changed" (React to events):

hooks/register.tsts
// The one hook that can change what Claude Code does: off unless the person turns it onon('agent.spawn', async ($, e, next) => {  const decision = decideSpawn(guardIsOn(config, await read($, guard)), config, e)  const result = decision.action === 'reroute' ? await next({ ...e, model: decision.model }) : await next(e)  if (decision.action === 'reroute') $.ui.log(decision.why + ' (guard on; /ledger guard off stops it)')  const rec = spawnRecord(e, result, decision.action === 'reroute' ? decision.model : null, await $.clock.now())  if (rec !== null) {    await ensureLedger($)    await update($, ledger, (l) => (l === null ? l : applySpawn(l, rec)))    await save($)  }  return result}).catch(async ($, e, next) => {  // Fail safe for a cost guard: before next, the spawn goes on unchanged; after next,  // next(e) hands back what the first call answered without spawning again  $.ui.log('the spawn guard failed (' + next.error.kind + '), so the subagent runs as Claude asked')  return next(e)})

It reroutes only a listed subagent type whose Agent call names no model, never a fork, a resumed agent, a teammate or a workflow agent, and it logs every reroute. Its .catch handler shows what failing safe means for a cost guard: the subagent runs as Claude asked. Failing safe for a policy check means the opposite, refusing the mod, which is LAB-003's org-guard.

Two recorded details to expect. With the full id claude-haiku-5-5, the debug log on 2.1.325 gets an [ERROR] line, ZodError: ... expected one of "sonnet"|"opus"|"haiku"|"fable" (path model), yet the Agent call ends outcome=ok and the subagent runs on Haiku 5.5; with the alias haiku, nothing is logged. The ledger keeps the full id because its price table and rows key on full ids. And whether Explore ran in the background was the parent's choice per call: with the guard on, one run spawned it in the background and one did not, so the guard is not credited with any difference in steps.

Testing a mod offline

claude plugin test [directory] runs *.test.ts files against a stubbed Claude Code, with no network and no sign-in, and "exits with status 1 when a test fails, so it works in CI" (Test a mod, checked 2026-11-15). The rules that trip people, each with a gallery card:

  • "Register every stub before the test's first call on $" (Test a mod). The first call loads the plugins (F-11).
  • "session.start doesn't run by itself" (Test a mod): fire it with await $.session.start(...).
  • A stub for a mods API call answers { value: ... } or { deny: 'the reason' }; a stub for an event answers the event's own result (F-12).
  • "A stub for turn.step is an async generator, and the test reads the stream to its end to get the result" (Test a mod).
  • "For $.clock calls, use mock.clock(on), or your mod's $.clock.now() fails with no implementation for clock.now" (Test a mod).
  • $.ui.mount({ ...target, surface }) mounts a Pane or AbovePrompt on terminal, desktop or vscode, with find, press, input, select and unmount.
  • tier('prepend') at the top of a file loads your mod ahead of the others, for policy mods.

Model Ledger's suite has 63 tests in six files: the pure modules, one file per build increment, and one file of regression tests, one per seeded failure. It passes on 2.1.325 and 2.1.311. A surface matrix mounted the pane and the band on all three surfaces at three widths each, fed from four recorded sessions (72 mounts), with the same text and Raster sizes on both versions.

The lab kit adds a contract checker, pnpm mod:check (rules MLC-01 to MLC-12), each rule tagged with the increment from which it must hold, so a checkpoint passes what is done and lists what is still ahead. A checker that never fails proves nothing, so pnpm mod:faults plants one fault per rule and confirms each is caught (12 of 12).

On 2.1.325, validate --strict catches several mistakes before any test runs, because it type-checks the module and the tests. On 2.1.311 the same mistakes show only at runtime, which the gallery cards mark.

Organization controls and trust boundaries

"A mod is code that runs with your permissions, inside Claude Code" (Mods overview). The overview's list of what one can do starts with "Act on your machine as you: read and write files anywhere your user account can, start programs, and make network requests", and it adds: "Mods aren't sandboxed. If you turn on sandboxing, the sandbox isolates the Bash commands Claude runs, and a process that a mod starts runs outside it." Treat a mod like installed native code.

Permission rules do not cover a mod either. With a Read(.env) deny rule in place, a recorded session refused Claude's Read tool (File is in a directory that is denied by your permission settings.) while a small probe mod read the same file with $.fs.read (gallery-probe: gprobe env: $.fs.read(".env") returned 80 characters; first key NORTHSTAR_DEMO_FLAG), as the admin page warns: "With Read(.env) denied, a mod can still read that file with $.fs.read or start a program that does" (Manage mods for your organization, checked 2026-11-15).

The controls live in managed settings, which a person cannot override (/etc/claude-code/managed-settings.json on Linux and WSL, /Library/Application Support/ClaudeCode/managed-settings.json on macOS, per Managed settings, checked 2026-11-15). Each line below was recorded on 2.1.325 against a scratch managed-settings directory, never a real machine's:

Organization controls, each with the line Claude Code 2.1.325 printed against a scratch managed-settings directory.
ControlWhat it doesRecorded line
The built-in guard, sec-default@builtin (cc-plugin-sec-default in /plugin)Runs ahead of user mods once any managed setting exists; a file holding only {} does not seat itcc-plugin-sec-default@builtin seated outermost: this machine has managed settings
allowManagedModsOnly, an option on the guard under pluginConfigs["cc-plugin-sec-default@builtin"]Only the organization's mods loadrefused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly)
disableSideloadFlags"rejects --plugin-dir and --plugin-url at startup, and keeps mods Claude writes during a session from loading" (admin page)--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags), exit 1
disableAllHooksNo hook or mod from an installed plugin runs; built-in mods still donot loaded: disableAllHooks in managed settings
prependPlugins with a policy modThe policy mod's plugin.register hook reads each user mod's calls before it loads and can refuse it. "With prependPlugins, also list sec-default@builtin to keep the built-in guard" (admin page)refused by org-guard: Northstar policy: mods may not call http.fetch

LAB-003's org-guard is that policy mod. It reads e.uses.calls, "the mods API methods the mod calls, each written namespace.method such as process.run" (admin page), and refuses a user mod that starts processes, uses the network or writes files:

org-guard registerts
// Northstar Parcel's policy mod. An administrator lists it first in prependPlugins, so it// sees every user's mod before that mod loads. It reads the calls the mod's code makes,// the list `claude plugin validate` prints, and refuses a mod that reaches past what a// visual mod needs: starting processes, the network, or writing files.import type { On } from 'claude-code' /** The mods API methods no user's mod may call, spelled as e.uses.calls lists them. */const BLOCKED_CALLS = ['process.run', 'process.spawn', 'http.fetch', 'fs.write'] export function register(on: On) {  on('plugin.register', async ($, e, next) => {    const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))    // Every mod a person installs or loads with --plugin-dir is tier 'user'; the    // organization's own mods and the built-in ones pass    if (e.tier === 'user' && blocked.length > 0) return { refuse: 'Northstar policy: mods may not call ' + blocked.join(', ') }    return next(e)  }).catch(async ($, e, next) => {    // A check that throws or runs past its time limit would otherwise let the mod load    if (e.tier !== 'user') return next(e)    return { refuse: 'Northstar policy check failed, so this mod was not loaded' }  })}

The .catch handler is not decoration: "If your plugin.register hook throws or exceeds its time limit, Claude Code skips the hook, so the check fails open and the mod it was checking loads" (admin page). Card F-13 shows both outcomes.

Two consequences to tell your users. When policy keeps a mod from loading, its slash command is no longer a command, so Claude Code sends what was typed to the model as a prompt: under allowManagedModsOnly, /ledger status became a model turn costing $0.0188 whose answer said the command is not installed. And "none of these controls sandboxes a mod. A mod you allow runs as the user, with the user's access to files, processes, and the network" (admin page). Model Ledger's trust-boundaries.md states what it receives, the one thing it changes, where its data goes, what it does not promise and what an administrator controls.

Forking the template

The point of the two seams is that the next team does not start over. FORKING.md in the mod walks a fork step by step; the short version:

  1. Copy the folder and rename the plugin, its options and its store key prefix, so the two mods never read each other's data.
  2. In src/collector.ts, write a record for the new stream from the hook's input and result, free of $.
  3. In src/ledger-store.ts, replace per-model rows with rows for the new stream.
  4. In src/render.ts, keep the layout functions (fitRaster, packCells, the text table) and change what the bars measure.
  5. In hooks/register.ts, register the new hooks with every $ call written in full, and keep any hook that changes behavior opt-in with a .catch handler.
  6. Copy the test pattern, then run pnpm mod:check <fork> --fork. Nine rules hold for any visual mod: strict validate with its type check, turn.step as an async function* wherever you register it, a .catch on every gating hook, $ written in full with src/ kept pure, Raster only behind the terminal branch, the allowlist, no reads of a subagent's prompt, and tests that pass and mount all three surfaces. The three rules that run Model Ledger's own renderer, guard and price table are skipped, so your tests carry those properties for the new stream: limits at every width, any hook that changes behavior off by default, and an estimate label on any dollar figure. The check is a self-check, not a grade.

The assessment is exactly this: a fork that charts test runs from a data source you have not seen.

Troubleshooting

T-01: pnpm is not found or is the wrong major version

Run corepack enable with Node.js 22.18.0 or newer on your PATH, so Corepack reads "packageManager": "pnpm@12.14.0". Check with node --version and pnpm --version. Every script in package.json is also a plain node command you can run directly.

T-02: The kit says Claude Code is not found

The kit calls claude on your PATH. Set CLAUDE_BIN to the binary's full path if it lives elsewhere, and check claude --version.

T-03: MLC-01 passes on 2.1.311, which skips the TypeScript check

That version runs mods, but its validate does not type-check them, so F-03, F-06, F-08 and F-12 show no static error there. Install 2.1.325 for the labs. Its validate notes also leave out (default matcher key: plugin) after the two ui.render hooks, which register and draw the same way on both versions.

T-04: validate --strict fails on an import ending in .ts

On 2.1.325 the type check refuses .ts import specifiers (TS5097), although Claude Code runs them. Import ./name.js, as every module in the lab does; the kit resolves those to the .ts files under plain Node.

T-05: The pane does not open at session start

A pane the mod opens on its own waits for 144 columns. Widen the terminal or run /ledger open; the transcript line and the band say when it is waiting.

T-06: /ledger reached the model as a prompt

The mod did not load: policy refused it, --bare or --safe-mode skipped it, or the module failed validation. Run /plugin and read the Errors tab, or run claude plugin validate --strict on the folder.

T-07: Hot reload printed nothing, or reload failed

Reload works in interactive sessions started with --plugin-dir. Save inside the folder you passed and look for the reloaded (N hooks: ...) line. reload failed, the previous version stays loaded: <reason> means your last working version is still running and the reason names what to fix (Troubleshoot a mod, checked 2026-11-15); /reload-plugins reloads every plugin by hand.

T-08: A live run stops with error_max_budget_usd

--max-budget-usd is checked after each model turn, so the turn that crosses the cap finishes first. Raise the cap a little for the task, and keep a total cap across loops; kit/live/run.sh sets both.

Lines that look like failures and are not

What this guide leaves out

  • Headless verification, settings hooks, deny rules and OS sandboxing belong to Guide 05.
  • Packaging skills, progressive disclosure and activation testing belong to Guide 10.
  • Measuring whether a routing choice saves money belongs to Guide 07. Model Ledger draws routing; it does not prove a saving.
  • Prompt injection and containment belong to Guide 03.
  • Publishing a mod to a marketplace or the plugin directory, mods that call $.model, Svg drawings, and custom tools are outside one visual mod.
  • The Desktop app and VS Code windows were not run for this guide. Their behavior is taught from the documentation and checked through test-kit mounts with surface: 'desktop' and 'vscode'.

Quick reference

Commands

Quick referencebash
pnpm mod:check [folder] [--upto start|inc1|inc2|inc3|inc4]   # contract rules MLC-01 to MLC-12 ($0.00)pnpm mod:check <fork> --fork                                # the nine rules any visual mod keeps ($0.00)pnpm mod:test [folder] [--upto start|inc1|inc2|inc3|inc4]    # claude plugin test, by increment ($0.00)pnpm mod:replay trace replays/t3-explore-guard-on.jsonl      # draw a recorded session offline ($0.00)pnpm mod:seed <sf-1|sf-2|sf-3|sf-4|all>                     # seeded failures F-01 to F-04 ($0.00)pnpm mod:faults                                             # one planted fault per contract rule ($0.00)pnpm mod:gallery <f-05|...|f-13|all>                        # failure gallery cards ($0.00)claude plugin validate --strict --json model-ledger         # static scan and type check ($0.00)claude plugin test model-ledger                             # the mod's own tests ($0.00)bash kit/live/run.sh T1|T2|T3 [--guard on]                  # optional capped live task (cents)

Limits (Mods reference, checked 2026-11-15)

Mods limits, from the Mods reference (checked 2026-11-15).
LimitValue
A hook's own time for one event10 seconds (50 milliseconds for prompt.edit), not counting next or mods API calls other than $.clock.sleep
Rastercolumns up to 512, rows up to 256, 262,144 cells in one tree
Elements and text children in one tree20,000
Text in one treethe first 100,000 characters are drawn
$.store4 MiB of JSON in total, shared by every session on the machine
A pane the mod opens itself144 columns, or 110 after the person opened it once

Version watch list (recorded 2026-11-15)

Tested versions and what to watch on upgrade (recorded 2026-11-15).
ItemTestedWatch on upgrade
Claude Code2.1.325; 2.1.311 for runtime behaviorThe mods API changes across point releases: rerun pnpm mod:check and pnpm mod:test, and diff the generated .claude-plugin/types/ against the previous build's
Type check in validate2.1.323 and laterWhich mistakes are caught before runtime
Stacked AbovePrompt rows2.1.323 and laterWhether the band still keeps next(e)
Price tablelist prices read 2026-11-15Update src/pricing.ts or the price_table option when prices change

Lab 1: Inspect a mod, then record every step and keep the totals

Check the starter, read its register function and validate output, optionally load it live and watch hot reload, then build Increment 1 (turn.step and agent.spawn recording, $.session.usage() readings, /ledger status and export) and Increment 2 ($.state, $.store, /clear restoration), verified with pnpm mod:test and pnpm mod:check at each checkpoint. The outputs below were recorded offline on 2026-11-15 with Claude Code 2.1.325 at $0.00, except the live screens of Step 3 (Live: claude-sonnet-5-5, effort medium. Recorded 2026-11-15); loading a mod and running its commands makes no model request. Their paths start at /tmp/visual-mod-work, the folder they were recorded in; yours start where you unzipped the kit.

Acceptance checks

  • pnpm mod:test --upto inc2 passes unit 17/17, Increment 1 6/6 and Increment 2 11/11
  • pnpm mod:check --upto inc1 passes every required rule, 8 of 12 at Increment 1, with MLC-01 (strict validate) among them
  • The validate notes list every hook and mods API call, because each call is written in full
  1. Create the workspace and check the starter

    $ bash new-workspace.sh starter ../ledger-lab cd ../ledger-lab pnpm install --frozen-lockfile pnpm mod:check --upto start pnpm mod:test --upto start
    PASS MLC-01 claude plugin validate --strict --json passes, and reaches every src/ module [start] not yet MLC-02 hooks.json names ./register.ts, every ledger hook is registered, and every option read is declared [Increment 3] not yet MLC-03 turn.step is an async function* that delegates with yield* next(e) [Increment 1] PASS MLC-04 every gating hook has a .catch handler [Increment 1] PASS MLC-05 $ is never destructured or aliased, and src/ is pure [Increment 1] not yet MLC-06 Raster is taken from $.ui.resolve(e) only under e.surface === 'terminal' [Increment 3] PASS MLC-07 the renderer stays inside Raster and tree limits at every width [start] PASS MLC-08 calls stay on the allowlist: no $.fs, $.process, $.http, $.env, $.mcp or $.model [start] PASS MLC-09 no code reads the subagent prompt (e.prompt) [Increment 1] not yet MLC-10 the spawn guard is off by default and logs every reroute [Increment 4] PASS MLC-11 cost is labeled an estimate from a dated price table [start] not yet MLC-12 claude plugin test passes and mounts terminal, desktop and vscode [Increment 4] 7 of 12 rules pass; every required rule passes $ node --import ./kit/register-ts.mjs kit/test.ts --upto start Tests: /tmp/visual-mod-work/ledger-lab/model-ledger (Claude Code 2.1.325, 1.5 s) PASS unit 17/17 pure modules (src/) not yet inc1 0/6 Increment 1: event logging not yet inc2 0/11 Increment 2: stored totals not yet inc3 2/12 Increment 3: the rendered pane not yet inc4 1/13 Increment 4: the command and the guard not yet sf 0/4 LAB-003 regressions for SF-1 to SF-4 Required groups pass (up to unit).
  2. Read the register function and what validate sees

    $ claude plugin validate --strict --json model-ledger
    "./register.ts hooks: session.start, command.run{command=ledger}", "./register.ts answers its own command: command.run{command=ledger}", "./register.ts calls: $.command.register"
  3. Load the mod and watch hot reload (optional, live)

    $ claude --plugin-dir ./model-ledger
    ▐▛███▛█ Claude Code v2.1.325 ▝▜██████▀ Sonnet 5.5 with medium effort · API Usage Billing ▝▝ ▝▝ /tmp/visual-mod-work/ledger-lab Plugins Discover Installed Marketplaces Errors Stats 1 mod active · model-ledger * Loading… ▐▛███▛█ Claude Code v2.1.325 ▝▜██████▀ Sonnet 5.5 with medium effort · API Usage Billing ▝▝ ▝▝ /tmp/visual-mod-work/ledger-lab ❯ /plugin ● model-ledger: reloaded (2 hooks: session.start, command.run) ❯ /ledger ⎿ model-ledger: Model Ledger starter: this answer changed on save. Start LAB-001, Increment 1. ❯ ⏵⏵ auto mode on (shift+tab to cycle)
  4. Increment 1, event logging: the tests

    $ pnpm mod:test --upto inc1

    Initial: Before you write Increment 1

    $ node --import ./kit/register-ts.mjs kit/test.ts --upto inc1 Tests: /tmp/visual-mod-work/ledger-lab/model-ledger (Claude Code 2.1.325, 1.7 s) PASS unit 17/17 pure modules (src/) FAIL inc1 0/6 Increment 1: event logging failed: turn.step records both steps of a recorded read-and-answer turn at list prices failed: a step with no usage is counted as a gap, not priced failed: agent.spawn adds the subagent, and its steps are priced on its own model failed: the subagent prompt is never stored, only its short description failed: advisor calls are counted from serverToolUses, and the engine total shows what no step carried not yet inc2 0/11 Increment 2: stored totals not yet inc3 2/12 Increment 3: the rendered pane not yet inc4 1/13 Increment 4: the command and the guard not yet sf 0/4 LAB-003 regressions for SF-1 to SF-4 Required groups do not pass yet (up to inc1). [ELIFECYCLE] Command failed with exit code 1.

    Final: Once Increment 1 is in

    $ node --import ./kit/register-ts.mjs kit/test.ts --upto inc1 Tests: /tmp/visual-mod-work/ledger-lab/model-ledger (Claude Code 2.1.325, 3.2 s) PASS unit 17/17 pure modules (src/) PASS inc1 6/6 Increment 1: event logging not yet inc2 2/11 Increment 2: stored totals not yet inc3 2/12 Increment 3: the rendered pane not yet inc4 3/13 Increment 4: the command and the guard not yet sf 1/4 LAB-003 regressions for SF-1 to SF-4 Required groups pass (up to inc1).
  5. Increment 1, event logging: the contract check

    $ pnpm mod:check --upto inc1
    PASS MLC-01 claude plugin validate --strict --json passes, and reaches every src/ module [start] not yet MLC-02 hooks.json names ./register.ts, every ledger hook is registered, and every option read is declared [Increment 3] PASS MLC-03 turn.step is an async function* that delegates with yield* next(e) [Increment 1] PASS MLC-04 every gating hook has a .catch handler [Increment 1] PASS MLC-05 $ is never destructured or aliased, and src/ is pure [Increment 1] not yet MLC-06 Raster is taken from $.ui.resolve(e) only under e.surface === 'terminal' [Increment 3] PASS MLC-07 the renderer stays inside Raster and tree limits at every width [start] PASS MLC-08 calls stay on the allowlist: no $.fs, $.process, $.http, $.env, $.mcp or $.model [start] PASS MLC-09 no code reads the subagent prompt (e.prompt) [Increment 1] not yet MLC-10 the spawn guard is off by default and logs every reroute [Increment 4] PASS MLC-11 cost is labeled an estimate from a dated price table [start] not yet MLC-12 claude plugin test passes and mounts terminal, desktop and vscode [Increment 4] 8 of 12 rules pass; every required rule passes
  6. Increment 2, stored totals

    $ pnpm mod:test --upto inc2
    $ node --import ./kit/register-ts.mjs kit/test.ts --upto inc2 Tests: /tmp/visual-mod-work/ledger-lab/model-ledger (Claude Code 2.1.325, 3.4 s) PASS unit 17/17 pure modules (src/) PASS inc1 6/6 Increment 1: event logging PASS inc2 11/11 Increment 2: stored totals not yet inc3 2/12 Increment 3: the rendered pane not yet inc4 3/13 Increment 4: the command and the guard not yet sf 1/4 LAB-003 regressions for SF-1 to SF-4 Required groups pass (up to inc2).
  7. Show the solution discussion

    Compare your hooks module with the reference after each increment: node ../labs/solutions/apply-checkpoint.mjs inc1 . (then inc2) copies it over your workspace, so commit your own work first.

    turn.step stays an async generator that passes every chunk through with yield* next(e) and records the finished result; every writer calls ensureLedger first, so a ledger restores after /clear even where an organization's settings pass over classic.SessionStart.

More labs in this guide

  • Lab 2: Draw the ledger on three surfaces, then add the command and the opt-in guard

    Build Increment 3 (the pane with a terminal Raster, the Desktop and VS Code table, the band) and Increment 4 (the full /ledger command, the opt-in guard, userConfig), replay recorded sessions offline with pnpm mod:replay, and optionally run the three live tasks.

  • Lab 3: Diagnose four seeded failures, finish the policy mod, and run the failure gallery

    Diagnose and repair the four seeded failures from what Claude Code prints, finish the org-guard policy mod with tier('prepend') tests, write down the managed-settings controls, and run the failure gallery.

Fifteen ways this breaks, and how you will know

Twelve of these reproduce in the lab; the other three were observed in this guide's recorded runs. Learn the symptom first; it is what you will actually see.

  • F-01mod:seed sf-1Reproducible

    A hook waits past the 10-second limit

    Symptom
    /ledger status hangs, then Claude Code prints "model-ledger: command.run hook skipped: ran past its 10s budget" and answers with its own fallback, "model-ledger registered /ledger but no command.run hook answered it". Live, the hook settled after 10,007 ms with no model request. The test kit prints "model-ledger's command.run hook was skipped: model-ledger: exceeded 10000ms budget".
    Diagnosis
    The seeded command awaits a promise that only the next main-loop turn.complete settles, and between turns nothing does. A hook has 10 seconds of its own time, "not counting time inside next or a mods API call other than $.clock.sleep" (Mods reference). A promise of your own counts.
    Fix
    Answer from the ledger as it stands, after reading $.session.usage() again (a mods API call, which does not count). The next turn's figures show in the next status.
    Verify
    pnpm mod:test on the repaired mod passes the SF-1 regression test.
  • F-02mod:seed sf-2Reproducible

    The pane opened at start never appears, and nothing says why

    Symptom
    With open_on_start on in a 120-column terminal, no pane appears and nothing in the transcript or band mentions it until you run /ledger open.
    Diagnosis
    A pane the person did not ask for waits for 144 columns. $.ui.open resolved "{ isPlaced: false, reason: 'unasked below 144 columns (120 now): placed when the person opens it, or when the terminal is widened to 144 columns' }", and the seeded openPane ignores what it resolves to.
    Fix
    Read isPlaced. When it is false, log the reason and put "pane not shown yet; /ledger open shows it" in the band.
    Verify
    The finished mod at 120 columns prints "model-ledger: the pane is not shown yet: unasked below 144 columns (120 now): ..." with the band notice, and /ledger open docks the pane.
  • F-03mod:seed sf-3Reproducible

    Raster returned on Desktop and VS Code

    Symptom
    On 2.1.323 or later, validate --strict fails with "TS2339: Property 'Raster' does not exist on type ...". On 2.1.311, which skips the type check, nothing static: in the test kit's Desktop mount the Raster's place holds an empty box, so the bars vanish without an error.
    Diagnosis
    The hook takes Raster from $.ui.resolve(e) without checking e.surface. Only the terminal's element table has it, and the declarations type each surface's table.
    Fix
    Branch on "e.surface === 'terminal'"; Desktop and VS Code get the Box and Text table.
    Verify
    pnpm mod:check passes MLC-06, and the Increment 3 tests mount all three surfaces.
  • F-04mod:seed sf-4Reproducible

    An oversized Raster empties the pane

    Symptom
    The pane is placed and stays empty. In a live session, Claude Code prints spike-probe: ui.render hook skipped: returned the wrong shape (a tree Pane refuses: Raster "grid" columns must be a whole number from 1 to 512); the test kit prints returned a tree Pane refuses: Raster "heat" columns must be a whole number from 1 to 512.
    Diagnosis
    The seeded heat strip gives every step its own cell. A Raster takes at most 512 columns and 256 rows, and a tree at most 262,144 cells; "a tree over the nesting, element, Raster cell, or Image byte limit isn't drawn" (Mods reference).
    Fix
    Fit every Raster to the pane's bodyColumns and to one Raster's limits, and fold steps into buckets.
    Verify
    pnpm mod:check passes MLC-07, which renders 288 trees across widths, themes and session sizes.
  • F-05mod:gallery f-05Reproducible

    turn.step written as a plain async function

    Symptom
    Validate fails the module: the hook on "turn.step" is not an async generator: turn.step streams, so it takes async function* ($, e, next) { ... }.
    Diagnosis
    turn.step streams. await next(e) has no stream to pass on.
    Fix
    "async function* ($, e, next)" with "const result = yield* next(e)", returning result.
    Verify
    pnpm mod:check passes MLC-03.
  • F-06mod:gallery f-06Reproducible

    The guard assigns to the frozen event

    Symptom
    On 2.1.325, validate reports "TS2540: Cannot assign to 'model' because it is a read-only property"; on 2.1.311 validate passes. On both, the guard never reroutes at runtime, and the test kit prints "hook failed closed: model-ledger: errorKind=TypeError errorChars=63 (agent.spawn; its .catch answered)" and "Attempting to define property on object that is not extensible."
    Diagnosis
    Events are deeply frozen, so "e.model = ..." throws. The .catch handler then lets the spawn go on unchanged, which is the safe outcome for a cost guard and also hides the bug unless a test checks the model.
    Fix
    "next({ ...e, model })".
    Verify
    The Increment 4 guard tests pass.
  • F-07mod:gallery f-07Reproducible

    $ destructured, so the scan cannot read the call

    Symptom
    Validate fails the module at "const { ui } = $": "$ itself is bound to a name (bound, passed, spread, returned or read)".
    Diagnosis
    Validate and policy mods read calls from the source as written. An alias hides ui.log from the lists a policy mod relies on.
    Fix
    Write $.ui.log(...) in full, every time.
    Verify
    pnpm mod:check passes MLC-05.
  • F-08mod:gallery f-08Reproducible

    focus: false passed to $.ui.open

    Symptom
    On 2.1.325, validate reports "TS2322: Type 'false' is not assignable to type 'true'". At runtime on both versions, the hook is skipped: "model-ledger's command.run hook was skipped: model-ledger: ui.open: focus is true or left out (host check)".
    Diagnosis
    focus, closeOnEscape and holdToasts on $.ui.open, and autoFocus on a Button, accept only true.
    Fix
    Leave the key out.
    Verify
    pnpm mod:test passes /ledger open.
  • F-09Observed

    borderStyle: 'rounded' draws no border

    Symptom
    The box draws without a border. Validate passes with --strict and all 63 tests pass, because the declarations type borderStyle as a string and a test reads elements, not drawn borders. Live, 2.1.325 also printed Box borderStyle "rounded" is not a border style (the styles are single, double, round, bold, singleDouble, doubleSingle, classic, arrow, dashed, quote); the Box is drawn with no border.
    Diagnosis
    "A Box whose borderStyle names anything else, such as 'rounded', draws with no border" (Mods reference). The style is 'round'.
    Fix
    borderStyle: 'round'.
    Verify
    Look at the pane in a real terminal. Nothing offline checks a drawn border.
  • F-10mod:gallery f-10Reproducible

    Two session.start hooks without a matcher

    Symptom
    The module fails to load: on("session.start") is registered twice without a matcher; the first is at ....
    Diagnosis
    One unmatched hook per event per module.
    Fix
    Merge the two into one hook, or give each a matcher.
    Verify
    "claude plugin validate --strict" passes.
  • F-11mod:gallery f-11Reproducible

    A test registers a stub after its first call on $

    Symptom
    TypeError: on("turn.complete") after the test first called $: the hooks beneath the plugins are registered before that, as a module registers its hooks in register().
    Diagnosis
    The first call on $ loads the plugins, and the chain is fixed from then on.
    Fix
    Register every stub first, then call $.
    Verify
    The test passes.
  • F-12mod:gallery f-12Reproducible

    A mods API stub answers a bare value

    Symptom
    On 2.1.325, validate reports TS2322 on the stub's return type. On both versions, most tests fail with "test's session.usage hook was skipped: test: returned neither { value } nor { deny }", followed by the mod's own hook failing on "no implementation for session.usage".
    Diagnosis
    A stub that stands in for a mods API call answers "{ value }" or "{ deny }"; only event stubs answer the event's own result.
    Fix
    "on('session.usage', () => ({ value: { ... } }))".
    Verify
    pnpm mod:test passes.
  • F-13mod:gallery f-13Reproducible

    A policy check that throws lets the mod load

    Symptom
    Without .catch, validate passes with only a note, "gating hook without .catch: plugin.register", and the test kit shows "org-guard's plugin.register hook was skipped: org-guard: undefined is not an object (evaluating 'e.uses.env.reads')": the uploader the policy must refuse loads. With .catch, every user mod is refused with "Northstar policy check failed, so this mod was not loaded".
    Diagnosis
    A hook that throws is skipped, so a gating hook fails open. The .catch handler decides the failure outcome, and for a policy that outcome should be a refusal.
    Fix
    Keep the .catch handler, and read optional fields as optional ("e.uses.env?.reads ?? []").
    Verify
    "claude plugin validate --strict org-guard" passes, and "pnpm mod:test org-guard" passes all four tests.
  • F-14Observed

    --bare in claude -p loads no hooks module

    Symptom
    The mod does nothing in a print-mode run. The debug log says "hooks module spike-probe@inline not loaded: installed plugins that are not managed load no hooks module in this mode (--bare); built-in plugins load regardless".
    Diagnosis
    --bare and --safe-mode skip installed hooks modules. "The settings and flags that stop installed mods, such as disableAllHooks, --bare, and --safe-mode, don't stop built-in mods" (Mods overview).
    Fix
    Drop --bare when the mod should run.
    Verify
    The run's init event lists the plugin, and the mod's command answers.
  • F-15Observed

    Treating a Read(.env) deny rule as a sandbox for mods

    Symptom
    Claude's Read tool on .env is refused ("File is in a directory that is denied by your permission settings."), and a mod reads the file anyway: gallery-probe: gprobe env: $.fs.read(".env") returned 80 characters; first key NORTHSTAR_DEMO_FLAG.
    Diagnosis
    Permission rules govern Claude's tools. A mod's $.fs and $.process run as you.
    Fix
    Decide which mods may load (managed settings and a policy mod), check what a mod calls before you load it, and keep secrets out of files a mod could read.
    Verify
    "claude plugin validate --json" lists every call; a visual mod lists no $.fs, $.process, $.http or $.env.

Transfer task and rubric

Fork Model Ledger into Test Pulse, a mod that charts test-suite runs from a synthetic record you have not seen, tested offline on three surfaces with every behavior change opt-in.

Analytic rubric: each criterion described at four performance levels, from Emerging to Exemplary
Criterion0 · Emerging1 · Developing2 · Proficient3 · Exemplary
Event correctness (OBJ-001, OBJ-002)turn.step is not an async generator, or the mod counts runs it never observed, such as a Bash call that is not a test commandHooks fire, but a retried run is counted twice, a subagent's run is lost, or nothing survives /clearturn.step delegates with yield* next(e); each run is read from tool.call for Bash after next(e) returns; the cost to green comes from the steps since the last green run; state restores after /clear and a reloadProficient, and the mod handles a red, a retried and an interrupted run as the brief defines them, with a test for each
Interface across surfaces (OBJ-003)Raster reaches Desktop or VS Code, or a Raster exceeds its limitsDraws on the terminal, but the fallback loses information or a narrow width breaks the layoutTerminal Raster fitted to bodyColumns; Desktop and VS Code text fallback with the same figures; /pulse answers in one lineProficient, and the mod says why the pane is not shown when $.ui.open waits, and a long history folds into buckets instead of growing
Tests (OBJ-002 to OBJ-004)No tests, or tests that pass whatever the mod doesTests cover events but not surfaces, or stubs break the kit's rules"claude plugin test" passes with event tests, mounts on all three surfaces, and a regression test for one seeded mistakeProficient, and a test proves that a secret printed in test output never reaches $.store, a log line or the /pulse answer
Safety and trust (OBJ-005)A secret, prompt text or test output reaches the model, a log or the network (critical); or a hook that changes behavior is on by default (critical)Opt-in and labeled, but the hook that changes behavior has no .catch, or trust-boundaries.md leaves out what the mod readsCalls stay on the visual allowlist; any behavior change is opt-in with a .catch fallback; every dollar figure says estimate with its price date; trust-boundaries.md is accurateProficient, and the .catch outcome of any opt-in hook has a test, and trust-boundaries.md says which managed settings would allow or block the mod

Proficiency standard: Proficient or higher on every criterion. Proposed local standard, not an official certification.

Self-check

The full brief

ASM-001 assesses OBJ-001 to OBJ-005 on a fork you have not rehearsed. You receive a case for Tidewren Freight, a fictional carrier on the reserved .test domain: a synthetic record of a team's test-suite runs, a short brief, and the finished Model Ledger to fork. You build "Test Pulse", a mod that reads each test run from tool.call events for Bash, prices the model steps it took to get back to green from turn.step usage, draws a pass and fail history Raster on the terminal with a text fallback elsewhere, answers /pulse, and keeps any hook that changes behavior opt-in. You submit the mod folder with its tests and trust-boundaries.md. A grader adds hidden claude plugin test cases driven by a second synthetic record you have not seen, and runs static checks.

Each criterion is scored Emerging (0), Developing (1), Proficient (2) or Exemplary (3). Passing requires Proficient (2) or higher on every criterion and no critical failure.

Critical failures (any one fails the submission): (1) a hook that blocks, rewrites or reroutes anything and is on by default; (2) secret leakage: an environment value, a token, test output text or a subagent prompt copied into a command's answer, $.store, a log line or a network request; (3) a dollar figure presented as a bill rather than an estimate; (4) any call to $.fs, $.process, $.http, $.env, $.mcp or $.model; (5) real company or personal data outside the .test and example.com domains.

Teach it to a room

  • Facilitation guide and lab solutions

    A 120-minute run of show across LAB-001 to LAB-003, a plan until rehearsed, with preflight checks, misconceptions to listen for and stopping rules, plus a lab solutions guide whose one-command offline check runs 34 checkpoints at $0.00.

  • Delivery at two sizes

    Scenario designs for about 12 learners in pairs, with optional capped live tasks, and about 100 learners on the offline route only, with table facilitators and checkpoint counts at minutes 28, 62 and 104. Designs to validate in a pilot, not staffing ratios.

  • Dry run and observation

    A proposed 60-minute observed dry run: a teach-back of how mods load and fail, a seeded failure repaired live, a facilitation drill, an adaptation and blind calibration scoring. No dry run has been held yet.

  • Clearance record

    One record per instructor, packet version and audience, filled in only from an observed dry run and decided by an authorized person. Blank: nobody has been cleared to teach this guide.

  • Evaluation plan and monthly report

    A five-minute diagnostic, checks during the labs, a pilot before the first cohort, privacy rules and a monthly report template with numerators and denominators. Blank until the guide is taught.

  1. [1]Mods overview · code.claude.comchecked Nov 15, 2026
  2. [2]Create a mod · code.claude.comchecked Nov 15, 2026
  3. [3]React to events · code.claude.comchecked Nov 15, 2026
  4. [4]Draw in the interface · code.claude.comchecked Nov 15, 2026
  5. [5]Interface gallery · code.claude.comchecked Nov 15, 2026
  6. [6]Use the mods API · code.claude.comchecked Nov 15, 2026
  7. [7]Mods reference · code.claude.comchecked Nov 15, 2026
  8. [8]Test a mod · code.claude.comchecked Nov 15, 2026
  9. [9]Troubleshoot a mod · code.claude.comchecked Nov 15, 2026
  10. [10]Manage mods for your organization · code.claude.comchecked Nov 15, 2026
  11. [11]Advisor (Claude Code) · code.claude.comchecked Nov 15, 2026
  12. [12]Advisor tool (Claude API) · platform.claude.comchecked Nov 15, 2026
  13. [13]Create custom subagents · code.claude.comchecked Nov 15, 2026
  14. [14]Managed settings · code.claude.comchecked Nov 15, 2026
  15. [15]Plugin manifest reference · code.claude.comchecked Nov 15, 2026
  16. [16]CLI reference · code.claude.comchecked Nov 15, 2026
  17. [17]Pricing · platform.claude.comchecked Nov 15, 2026
  18. [18]Models overview · platform.claude.comchecked Nov 15, 2026
  19. [19]Manage costs effectively · code.claude.comchecked Nov 15, 2026
  20. [20]Claude Code CHANGELOG.md (2.1.311 through 2.1.325) · github.comchecked Nov 15, 2026
  21. [21]npm registry: @anthropic-ai/claude-code · registry.npmjs.orgchecked Nov 15, 2026
  22. [22]Node.js release index · nodejs.orgchecked Nov 15, 2026
  23. [23]npm registry: pnpm · registry.npmjs.orgchecked Nov 15, 2026
  24. [24]anthropics/claude-code-playground mods README and LICENSE (commit 569c528) · github.comchecked Nov 15, 2026
  25. [25]Settings reference · code.claude.comchecked Nov 15, 2026

Independent work. Not affiliated with or endorsed by any vendor named in this guide.

Jordan Hudgens

Written by

Jordan Hudgens

Technical educator and AI engineering leader. 16 Udemy courses, 111K students, and curricula used by 250K+ learners.

Contact Jordan