L'oggetto $
Le aree dell'interfaccia del motore che ogni hook riceve, con le loro firme reali e dove narsil-pet e narsil-check usano ciascuna.
Cosa fa
Ogni hook riceve $, l’interfaccia del motore. Una mod non ha Node né DOM, quindi $ è il modo in cui raggiunge lo schermo, i suoi dati salvati, l’orologio, la rete, i processi, i file, la sessione, il modello, gli strumenti e i comandi. Questa guida percorre le aree che usano le due mod di Narsil, con la firma di ogni metodo come la dichiara Claude Code 2.1.325.
$ ha più di quanto trovi qui (temi, impostazioni, agenti, telemetria e altro). Il file di dichiarazioni, claude-code.d.ts, documenta ogni nome e ogni metodo con il suo commento di documentazione e un esempio.
Come funziona dentro
Ogni metodo di $ è una chiamata che passa per l’host: viene sollevata come evento, quindi gli hook di altri plugin possono vederla, riscriverla o rifiutarla, e quasi tutti i metodi restituiscono una promise. I tipi vengono dal modulo claude-code:
import type { EngineInterface } from 'claude-code'
Un helper che riceve $: EngineInterface può usare le stesse chiamate di un hook.
| Area | A cosa serve | Usata in |
|---|---|---|
$.ui |
Toast, notifiche, righe di log, la riga di stato, i pannelli, gli appunti, le tabelle di elementi | entrambe |
$.store |
Dati JSON conservati tra una sessione e l’altra | entrambe |
$.state |
Valori con nome per la sessione, letti durante il disegno | entrambe, tramite atom, read, update |
$.clock |
L’ora e i timer | entrambe |
$.process |
Comandi sull’host | entrambe |
$.http |
Richieste di rete tramite l’host | entrambe |
$.fs |
File | entrambe |
$.session |
La directory, l’id, il consumo e le superfici della sessione | entrambe |
$.model |
Completamenti singoli | entrambe |
$.tool |
Strumenti che il modello può chiamare | narsil-check |
$.command |
Comandi slash | entrambe |
$.mcp |
Chiamare gli strumenti di un server MCP connesso | narsil-check |
$.prompt |
La casella del prompt e l’invio di prompt | entrambe |
$.audio |
Voce e suoni | narsil-pet |
$.env |
Variabili d’ambiente | narsil-pet |
$.plugin |
Il nome e la cartella del plugin stesso | narsil-pet |
Passo dopo passo
$.ui: ciò che vede la persona
$.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?)mostra un piccolo riquadro per qualche secondo (timeoutMs, predefinito 4000). Non tocca né la trascrizione né il modello.log(text, options?)aggiunge alla trascrizione una riga attenuata che il modello non legge, oppure, con{ to: 'debug' }, scrive solo nel log di debug.status(text | undefined)fissa una riga per questo plugin sotto il prompt;undefinedla rimuove.notify(text, options?)invia una notifica nativa attraverso il canale della persona e si risolve con{ isSent: true, channel }o{ isSent: false, reason }.open(pane)apre un pannello che il plugin poi disegna con un hookui.rendersu{ component: 'Pane' }. Si risolve con{ isPlaced: true }o{ isPlaced: false, reason }.copy({ text, surface })mette il testo negli appunti della superficie indicata e si risolve con{ isCopied: true }o{ isCopied: false, reason }. Un gestore di pressione passae.surface.resolve(e)restituisce la tabella di elementi (Box,Text,Buttone altri) per la superficie su cui disegna un hookui.render. La guida “Superfici” ne parla.
Il hooks/register.tsx di narsil-check usa $.ui.copy e $.ui.toast insieme in copyRow, e apre il suo pannello con $.ui.open({ id: PANE, title: TITLE }) su session.start. Il hooks/register.tsx di narsil-pet prova $.ui.notify prima del suo script di notifica. Nessuna delle due mod chiama $.ui.status; la riga sopra segue l’esempio del file di dichiarazioni.
$.store: dati tra le sessioni
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)si risolve con il valore o conundefined. Il suo tipo èunknown, quindi controllalo o convertilo.set(key, value)salva dati JSON. UnDatetorna come stringa ISO e un campoundefinedviene scartato. Rifiuta una funzione, un ciclo o uno store che superi in totale 4 MiB di JSON.keys()si risolve con tutte le chiavi in ordine di inserimento;delete(key)ne rimuove una.
Lo store è un file JSON del plugin stesso, nella directory di configurazione di Claude Code dell’utente. narsil-pet ripristina le sue preferenze con $.store.get(PREFS_KEY) su session.start e ripulisce le vecchie statistiche per sessione con $.store.keys() e $.store.delete(key).
$.state: valori per il disegno
$.state contiene valori con nome per la sessione. Sopravvivono a un ricaricamento a caldo del codice della mod, e un hook ui.render che ne legge uno viene ridisegnato quando cambia, senza chiamare $.ui.invalidate. Ogni valore è dichiarato nel contratto della mod (types/index.d.ts) sotto PluginState.
Le chiamate dirette ricevono un riferimento i cui plugin e key sono letterali:
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 si risolve con { value, version } (undefined alla versione 0 se non è mai stato scritto). set con ifVersion scrive solo mentre il valore è a quella versione. Le due mod di Narsil usano invece gli helper di claude-code, che lo fanno per te:
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)
La differenza che conta: $.state dura per la sessione e $.store dura tra le sessioni. Per conservare un valore di stato dopo la fine della sessione, scrivilo anche in $.store. Un hook di render non scrive mai lo stato ($.state.set durante il disegno viene rifiutato); scrivi da un gestore di pressione o da un altro evento. narsil-pet dichiara tutto il suo stato in types/index.d.ts sotto PluginState['narsil-pet'] e crea ogni valore con atom all’inizio di hooks/register.tsx.
$.clock: ora e timer
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() si risolve con i millisecondi trascorsi dall’epoch. sleep(ms, options?) attende e accetta un signal. after(ms, fn) e every(ms, fn) restituiscono un timer con cancel(). Un ricaricamento a caldo annulla i timer in sospeso. narsil-pet avvia la sua finestra con $.clock.after(10, ...) e un battito periodico con $.clock.every(2000, ...) su session.start.
$.process, $.http, $.env, $.plugin: l’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?)esegue un comando dal suo vettore di argomenti, senza shell, e si risolve con{ exitCode, stdout, stderr }per qualsiasi codice di uscita.initaccettacwd,env,stdinetimeoutMs(30 s per impostazione predefinita).http.fetch(url, init?)passa per l’host e si risolve con{ status, ok, headers, text }.initaccettamethod,headers,body,authesocketPath.env.get(name)si risolve con la variabile o conundefined. Il nome deve essere una stringa letterale, così validate può elencare ciò che il modulo legge.plugin.rootè la cartella del plugin (assoluta) eplugin.nameil suo nome nel manifest. Entrambi sono semplici stringhe, non chiamate.
narsil-check esegue i gestori di pacchetti e gh con $.process.run e interroga i registri e OSV.dev con $.http.fetch. narsil-pet legge OS con $.env.get e costruisce i percorsi degli script a partire da $.plugin.root.
$.fs: file
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) si risolve con il testo (o con i byte, con { as: 'bytes' }) e rifiuta quando il file manca o supera 4 MiB. write(path, text) crea il file e le sue directory. exists(path) e list(path?) fanno quello che dice il nome; ogni voce di list ha name, kind, size, mtimeMs e isLink. L’helper readJson di narsil-check è $.fs.exists seguito da $.fs.read.
$.session: la sessione stessa
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() è la directory in cui gira la sessione, id() il suo id, usage() quando è iniziata e quanto è piena la finestra di contesto, e surfaces() tutte le superfici su cui disegna. narsil-pet le legge tutte e quattro; narsil-check legge cwd().
$.model: completamenti
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 esegue un completamento senza strumenti e senza cronologia e si risolve sempre con un risultato: isAnswered con text, oppure isAnswered: false con un reason. fork esegue un completamento senza strumenti sulla trascrizione della sessione stessa. Entrambi contano nel costo della sessione. narsil-pet scrive i suoi consigli con $.model.complete({ model: 'haiku', ... }) e i consigli più approfonditi con $.model.fork; narsil-check chiede a Haiku perché un aggiornamento è rischioso.
$.tool e $.command: ciò che possono chiamare il modello e la persona
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 dichiara /<name>; un hook command.run su { command: '<name>' } gli risponde con { text }. tool.register dichiara uno strumento chiamato mcp__<plugin>__<name>; un hook tool.call su quel nome gli risponde. Entrambi si registrano da session.start. Questo schema è adattato dal hooks/register.tsx di narsil-check, che registra i suoi quattro strumenti per la lista di attività in registerTools e risponde a ciascuno con { result } o { 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?)chiama uno strumento su un server MCP connesso con la connessione del motore stesso e si risolve con blocchicontenteisError. narsil-check legge così i server di sessione dell’app desktop.prompt.fill({ text })mette del testo nella casella del prompt come bozza. narsil-pet lo usa quando scegli un passo successivo suggerito.prompt.submit({ text })accoda un prompt che avvia un proprio turno appena la sessione è inattiva. narsil-check lo usa per affidare un’attività a Claude.audio.speak(text)parla con il sintetizzatore della piattaforma. narsil-pet ricorre a questo quando il suo script vocale non è disponibile.
Errori comuni e come testarlo
- Considerare
$.statepermanente. Finisce con la sessione. Rendi persistenti i dati con$.store. - Scrivere lo stato durante il disegno.
$.state.setdentro un hookui.renderviene rifiutato. Scrivi daonPresso da un altro evento. - Chiavi di stato o nomi di variabili calcolati.
pluginekeyin un riferimento di stato, e il nome passato a$.env.get, devono essere letterali nel sorgente. - Ignorare la forma dei risultati.
$.model.complete,$.ui.notify,$.ui.opene$.ui.copysi risolvono con un risultato che dice se ha funzionato, invece di rifiutare. ControllaisAnswered,isSent,isPlacedoisCopied. - Dimenticare che le chiamate possono fallire. Entrambe le mod avvolgono le chiamate facoltative in
.catch(() => undefined), così un singolo errore non ferma un hook.
claude plugin validate elenca ogni chiamata a $ che il modulo fa (calls: $.state.get, $.ui.toast, ...), le chiavi di stato che legge e scrive e i nomi di variabili d’ambiente che usa. Il controllo dei tipi rispetto al file di dichiarazioni individua un nome di metodo o un argomento sbagliato prima che una sessione carichi la mod.
Per andare oltre
hooks/register.tsxdi narsil-pet:session.startusa$.command.register,$.store.get,$.env.get,$.session.usage,$.session.cwd,$.clock.aftere$.clock.everyin un solo hook.hooks/register.tsxdi narsil-check:registerToolsper$.tool.register, gli hooktool.callsumcp__narsil-check__...che rispondono a quegli strumenti, ecopyRowper$.ui.copy.- Entrambi i file
types/index.d.ts: le dichiarazioniPluginStatedietro ogniatom.
Per andare oltre: come lo fa la mod vera
Questi file fanno parte delle mod originali, pubblicate con licenza GPL v3. Il codice citato in questa pagina viene da lì e mantiene quella licenza.
Questa guida ti è stata utile?
Tutte le guide sono gratuite. Se questa ti ha fatto risparmiare tempo, puoi offrirmi un caffè.
Offrimi un caffè