The $ object
The areas of the engine interface every hook receives, with their real signatures and where narsil-pet and narsil-check use each one.
What it does
Every hook receives $, the engine interface. A mod has no Node and no DOM, so $ is how it reaches the screen, its saved data, the clock, the network, processes, files, the session, the model, tools and commands. This guide walks through the areas the two Narsil mods use, with each method’s signature as Claude Code 2.1.325 declares it.
$ has more than what is here (themes, settings, agents, telemetry and others). The declaration file, claude-code.d.ts, documents every noun and method with its doc comment and an example.
How it works inside
Each method on $ is a call through the host: it is raised as an event, so other plugins’ hooks can see it, rewrite it or refuse it, and almost every method returns a promise. Types come from the claude-code module:
import type { EngineInterface } from 'claude-code'
A helper that takes $: EngineInterface can use the same calls as a hook.
| Area | What it is for | Used in |
|---|---|---|
$.ui |
Toasts, notifications, log lines, the status line, panes, the clipboard, element tables | both |
$.store |
JSON data kept between sessions | both |
$.state |
Named values for the session, read while drawing | both, through atom, read, update |
$.clock |
The time and timers | both |
$.process |
Commands on the host | both |
$.http |
Network requests through the host | both |
$.fs |
Files | both |
$.session |
The session’s directory, id, usage and surfaces | both |
$.model |
One-off completions | both |
$.tool |
Tools the model can call | narsil-check |
$.command |
Slash commands | both |
$.mcp |
Calling a connected MCP server’s tools | narsil-check |
$.prompt |
The prompt box and submitting prompts | both |
$.audio |
Speech and sound | narsil-pet |
$.env |
Environment variables | narsil-pet |
$.plugin |
The plugin’s own name and folder | narsil-pet |
Step by step
$.ui: what the person sees
$.ui.toast('Saved 3 notes')
$.ui.log('greeter: cache warmed', { to: 'debug' })
$.ui.status('greeter: 2 tool calls')
$.ui.status(undefined)
const sent = await $.ui.notify('Tests passed', { title: 'greeter' })
if (!sent.isSent) $.ui.log(`no notification: ${sent.reason}`)
const opened = await $.ui.open({ id: 'notes', title: 'Notes' })
if (!opened.isPlaced) $.ui.log(`pane waits: ${opened.reason}`)
toast(text, options?)shows a small box for a few seconds (timeoutMs, default 4000). It does not touch the transcript or the model.log(text, options?)appends a dim line to the transcript that the model does not read, or with{ to: 'debug' }writes to the debug log only.status(text | undefined)pins one line for this plugin under the prompt;undefinedremoves it.notify(text, options?)raises a native notification through the person’s own channel and resolves{ isSent: true, channel }or{ isSent: false, reason }.open(pane)opens a pane the plugin then draws with aui.renderhook on{ component: 'Pane' }. It resolves{ isPlaced: true }or{ isPlaced: false, reason }.copy({ text, surface })puts text on the clipboard of the surface named, and resolves{ isCopied: true }or{ isCopied: false, reason }. A press handler passese.surface.resolve(e)returns the element table (Box,Text,Buttonand others) for the surface aui.renderhook draws on. The guide “Surfaces” covers it.
narsil-check’s hooks/register.tsx uses $.ui.copy and $.ui.toast together in copyRow, and opens its pane with $.ui.open({ id: PANE, title: TITLE }) on session.start. narsil-pet’s hooks/register.tsx tries $.ui.notify before its own notification script. Neither mod calls $.ui.status; the line above follows the declaration file’s example.
$.store: data across sessions
const runs = Number((await $.store.get('runs')) ?? 0) + 1
await $.store.set('runs', runs)
const old = (await $.store.keys()).filter((key) => key.startsWith('day:'))
for (const key of old) await $.store.delete(key)
get(key)resolves the value orundefined. Its type isunknown, so check or cast it.set(key, value)stores JSON data. ADatecomes back as its ISO string and anundefinedfield is dropped. It rejects a function, a cycle, or a store over 4 MiB of JSON in total.keys()resolves every key in insertion order;delete(key)removes one.
The store is a JSON file of the plugin’s own under the user’s Claude Code configuration directory. narsil-pet restores its preferences with $.store.get(PREFS_KEY) on session.start, and trims old per-session statistics with $.store.keys() and $.store.delete(key).
$.state: values for drawing
$.state holds named values for the session. They survive a hot reload of the mod’s code, and a ui.render hook that reads one is drawn again when it changes, with no call to $.ui.invalidate. Each value is declared in the mod’s contract (types/index.d.ts) under PluginState.
The raw calls take a reference whose plugin and key are literals:
const ref = { plugin: 'greeter', key: 'calls' } as const
const held = await $.state.get(ref)
await $.state.set(ref, (held.value ?? 0) + 1, { ifVersion: held.version })
get resolves { value, version } (undefined at version 0 when never written). set with ifVersion writes only while the value stands at that version. Both Narsil mods use the helpers from claude-code instead, which do this for you:
import { atom, read, update } from 'claude-code'
const calls = atom({ plugin: 'greeter', key: 'calls' } as const, 0)
const now = await read($, calls)
await update($, calls, (n) => n + 1)
The difference that matters: $.state lasts for the session and $.store lasts across sessions. To keep a state value after the session ends, write it to $.store too. A render hook never writes state ($.state.set while drawing is refused); write from a press handler or another event. narsil-pet declares all of its state in types/index.d.ts under PluginState['narsil-pet'] and creates each value with atom at the top of hooks/register.tsx.
$.clock: time and timers
const startedAt = await $.clock.now()
await $.clock.sleep(500)
const once = $.clock.after(10_000, () => $.ui.toast('Ten seconds in'))
const tick = $.clock.every(2000, () => $.ui.status('still here'))
once.cancel()
tick.cancel()
now() resolves milliseconds since the epoch. sleep(ms, options?) waits, and accepts a signal. after(ms, fn) and every(ms, fn) return a timer with cancel(). A hot reload cancels pending timers. narsil-pet starts its window with $.clock.after(10, ...) and a heartbeat with $.clock.every(2000, ...) on session.start.
$.process, $.http, $.env, $.plugin: the host
const { exitCode, stdout } = await $.process.run(['git', 'status', '--short'], { timeoutMs: 5000 })
const { ok, status, text } = await $.http.fetch('https://example.com/status')
const home = await $.env.get('HOME')
const script = `${$.plugin.root}/scripts/hello.sh`
process.run(argv, init?)runs a command by its argument vector, with no shell, and resolves{ exitCode, stdout, stderr }for any exit code.inittakescwd,env,stdinandtimeoutMs(30 s by default).http.fetch(url, init?)goes through the host and resolves{ status, ok, headers, text }.inittakesmethod,headers,body,authandsocketPath.env.get(name)resolves the variable orundefined. The name must be a string literal, so validate can list what the module reads.plugin.rootis the plugin’s folder (absolute) andplugin.nameits manifest name. Both are plain strings, not calls.
narsil-check runs package managers and gh with $.process.run and queries registries and OSV.dev with $.http.fetch. narsil-pet reads OS with $.env.get and builds script paths from $.plugin.root.
$.fs: files
const path = `${await $.session.cwd()}/notes.json`
if (await $.fs.exists(path)) {
const notes = JSON.parse(await $.fs.read(path)) as unknown
await $.fs.write(path, JSON.stringify(notes, null, 2))
}
const entries = await $.fs.list(await $.session.cwd())
read(path) resolves the text (or bytes with { as: 'bytes' }) and rejects when the file is missing or over 4 MiB. write(path, text) creates the file and its directories. exists(path) and list(path?) do what they say; each list entry has name, kind, size, mtimeMs and isLink. narsil-check’s readJson helper is $.fs.exists followed by $.fs.read.
$.session: the session itself
const cwd = await $.session.cwd()
const id = await $.session.id()
const usage = await $.session.usage()
const inApp = (await $.session.surfaces()).some((s) => s !== 'terminal')
cwd() is the directory the session runs in, id() its id, usage() when it began and how full the context window is, and surfaces() every surface it draws on. narsil-pet reads all four; narsil-check reads cwd().
$.model: completions
const reply = await $.model.complete({
model: 'haiku',
system: 'Answer in one line.',
prompt: 'Name a color.',
maxTokens: 50,
})
const color = reply.isAnswered ? reply.text : `no answer: ${reply.reason}`
const forked = await $.model.fork({ prompt: 'Summarize this session in one sentence.' })
complete runs one completion with no tools and no history and always resolves a result: isAnswered with text, or isAnswered: false with a reason. fork runs one tool-less completion over the session’s own transcript. Both count toward the session’s cost. narsil-pet writes its tips with $.model.complete({ model: 'haiku', ... }) and its deeper tips with $.model.fork; narsil-check asks Haiku why an upgrade is risky.
$.tool and $.command: what the model and the person can call
on('session.start', async ($, e, next) => {
await $.command.register({
name: 'notes',
description: 'Show the notes count',
argumentHint: 'clear',
})
await $.tool.register({
name: 'add_note',
description: 'Add a note to the list.',
inputSchema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
})
return next(e)
})
on('command.run', { command: 'notes' }, async ($, e) => {
const count = Number((await $.store.get('count')) ?? 0)
return { text: e.args.trim() === 'clear' ? 'Cleared.' : `${count} notes` }
})
on('tool.call', { tool: 'mcp__greeter__add_note' }, async ($, e) => {
const text = (e as unknown as { text?: unknown }).text
if (typeof text !== 'string') return { deny: 'A note needs text.' }
return { result: `Added: ${text}` }
})
command.register declares /<name>; a command.run hook on { command: '<name>' } answers it with { text }. tool.register declares a tool named mcp__<plugin>__<name>; a tool.call hook on that name answers it. Both register from session.start. This pattern is adapted from narsil-check’s hooks/register.tsx, which registers its four task-list tools in registerTools and answers each with { result } or { deny }.
$.mcp, $.prompt, $.audio
const result = await $.mcp.call('example-server', 'list_items', { limit: 5 })
await $.prompt.fill({ text: 'Run the tests again' })
await $.prompt.submit({ text: 'List the files changed today' })
await $.audio.speak('Done')
mcp.call(server, tool, args?)calls a tool on a connected MCP server with the engine’s own connection and resolvescontentblocks andisError. narsil-check reads the desktop app’s session servers this way.prompt.fill({ text })puts text in the prompt box as a draft. narsil-pet uses it when you pick a suggested next step.prompt.submit({ text })queues a prompt that starts its own turn once the session is idle. narsil-check uses it to hand a task to Claude.audio.speak(text)speaks with the platform’s synthesizer. narsil-pet falls back to it when its own voice script is not available.
Common mistakes and how to test it
- Treating
$.stateas permanent. It ends with the session. Persist through$.store. - Writing state while drawing.
$.state.setinside aui.renderhook is refused. Write fromonPressor another event. - Computed state keys or env names.
pluginandkeyin a state reference, and the name passed to$.env.get, must be literals in the source. - Ignoring the result shapes.
$.model.complete,$.ui.notify,$.ui.openand$.ui.copyresolve a result that says whether it worked instead of rejecting. CheckisAnswered,isSent,isPlacedorisCopied. - Forgetting that calls can fail. Both mods wrap optional calls in
.catch(() => undefined)so one failure does not stop a hook.
claude plugin validate lists every $ call the module makes (calls: $.state.get, $.ui.toast, ...), the state keys it reads and writes, and the env names it uses. Type-checking against the declaration file catches a wrong method name or argument before a session loads the mod.
Going further
- narsil-pet
hooks/register.tsx:session.startuses$.command.register,$.store.get,$.env.get,$.session.usage,$.session.cwd,$.clock.afterand$.clock.everyin one hook. - narsil-check
hooks/register.tsx:registerToolsfor$.tool.register, thetool.callhooks onmcp__narsil-check__...that answer them, andcopyRowfor$.ui.copy. - Both
types/index.d.tsfiles: thePluginStatedeclarations behind everyatom.
Going further: how the real mod does it
These files are part of the original mods, published under the GPL v3. Code quoted on this page comes from them and keeps that license.
Did this guide help?
Every guide is free. If this one saved you time, you can buy me a coffee.
Buy me a coffee