Gli stati a colpo d'occhio
Come Narsil trasforma gli eventi della sessione in cinque stati, una frase sul passo in corso e un breve commento, disegnati nella fascia sopra il prompt.
Cosa fa
Narsil vive nella fascia subito sopra il prompt. Basta uno sguardo per rispondere alla domanda che ti fai più spesso mentre Claude lavora: devo fare qualcosa adesso?
La fascia mostra tre cose:
-
Uno stato, in maiuscolo e con il suo colore. Narsil parla spagnolo, quindi le etichette sono in spagnolo:
Etichetta Significato Quando appare TRABAJANDOAl lavoro Claude sta pensando, leggendo, cercando, modificando o eseguendo comandi. PARADAFerma, in attesa di te La conversazione aspetta il tuo prossimo messaggio. TE NECESITAHa bisogno di te Una domanda, un piano da approvare o un permesso da decidere. TERMINADAFinito Claude ha terminato la sua risposta. ERRORErrore Il turno si è fermato perché qualcosa è andato storto. -
Una frase che dice esattamente cosa sta facendo Claude, come “Estoy editando: register.tsx” (“Sto modificando: register.tsx”) o “Te necesito: tengo una pregunta para ti” (“Ho bisogno di te: ho una domanda per te”).
-
Il commento di Narsil sotto quella frase, scelto a caso tra alcune righe per ogni momento, come “Tecleando con mis aletas.” (“Scrivo con le mie pinne.”) mentre si modifica un file.
Fuori dal terminale la fascia disegna anche Narsil, con una posa per ogni stato (il disegno è l’argomento della prossima guida). Nel terminale disegna invece una piccola faccina di testo, come ~(•ᴗ•)~ 💻.
Il vantaggio è che non devi leggere la trascrizione per sapere a che punto sono le cose. Un TE NECESITA giallo è un motivo per tornare; un TRABAJANDO blu è un motivo per continuare a fare altro.
Come funziona dentro
Lo stato non è qualcosa che Claude Code consegna a una mod. Narsil lo costruisce da sé a partire dagli eventi della sessione, lo conserva in un unico valore e disegna quel valore.
Un valore, due livelli: umore e stato
La mod conserva un solo valore di stato, l’atom pet in hooks/register.tsx, con tre campi: mood, detail e line. Il suo tipo, Pet, è dichiarato in types/index.d.ts.
mood è più fine dei cinque stati. Gli umori sono dodici: greeting, idle, thinking, talking, reading, searching, writing, running, asking, scared, celebrating e failed. I cinque stati si ricavano dall’umore con statusOf in hooks/sprite.ts:
greetingeidlesono fermi (PARADA).askingè in attesa (TE NECESITA).celebratingè finito (TERMINADA).failedè errore (ERROR).- Tutti gli altri umori sono al lavoro (
TRABAJANDO), compresoscared.
Il motivo dei due livelli è che lo stato risponde a “devo intervenire?”, e per questo bastano cinque risposte; l’umore risponde a “cosa sta succedendo esattamente?”, e guida la frase, il commento e la posa. Conservare solo l’umore e ricavarne lo stato significa che i due non possono mai essere in disaccordo.
L’umore scared è un buon esempio del perché la separazione conta. Quando una chiamata a uno strumento fallisce a metà turno, Narsil sembra spaventata e la frase dice “Ha fallado un paso (Bash); sigo trabajando” (“Un passo è fallito (Bash); continuo a lavorare”). Lo stato resta TRABAJANDO, perché Claude sta ancora lavorando e a te non viene chiesto nulla. Solo un turno che termina con un fallimento diventa ERROR.
Gli eventi che Narsil ascolta
Ogni cambio di umore passa per una sola funzione, setMood in hooks/register.tsx, che scrive l’atom pet e invia il nuovo stato alla finestra mobile. Gli hook che la chiamano:
session.start: una nuova conversazione inizia comegreeting, che conta come ferma.turn.start: il tuo prompt avvia un turno; l’umore diventathinking. L’hook agisce solo quandoe.agentIdnon è definito, così il turno di un subagente non azzera la conversazione principale.turn.step: l’output del modello arriva a pezzi. Un pezzothinkingmantiene l’umore suthinking; il primo pezzotextdel ciclo principale lo cambia intalking(“Estoy escribiendo la respuesta”, “Sto scrivendo la risposta”). Questo hook è un generatore asincrono: restituisce conyieldogni pezzo che riceve, così il flusso arriva allo schermo senza modifiche.tool.call: l’evento più informativo. Il nome dello strumento sceglie l’umore attraversoMOOD_BY_TOOLinhooks/words.ts(Readè lettura,GrepeWebSearchsono ricerca,EditeWritesono scrittura,BashePowerShellsono esecuzione), edescribeCalltrasforma l’input della chiamata nel breve dettaglio dopo i due punti: il nome base del file per uno strumento sui file, il pattern per una ricerca, la prima riga di un comando.AskUserQuestionedExitPlanModesono gestiti a parte (ASKING_TOOLS): impostanoasking, perché lo strumento stesso è il momento in cui Claude si ferma e aspetta.classic.PermissionRequest: una finestra di permesso a cui devi rispondere. L’hook chiama primanext(e)e impostaaskingsolo quando nessun hook delle impostazioni l’ha già decisa e la modalità non èbypassPermissions.turn.complete: il turno termina, ede.reasondecide lo stato.answerdiventacelebratingcon il tempo impiegato (“He terminado (en 2 min)”),abortedtorna aidlecon “lo has detenido tú” (“l’hai fermato tu”), e qualsiasi altro motivo diventafailed.
Perché è stata presa ogni decisione
I commenti in hooks/register.tsx danno le ragioni, e vale la pena leggerli come note di progetto:
- I permessi usano
classic.PermissionRequest, nontool.check. Il commento spiega che l’askditool.checkarriva prima che la modalità di permesso decida la chiamata, quindi con “bypass permissions”, una regola o il classificatore automatico Narsil darebbe falsi allarmi (“cry wolf”, gridare al lupo). Il motore generaPermissionRequestsolo quando sta per mostrarti la finestra. - Un turno finito non è sempre “finito”. Nell’hook
classic.StopNarsil conta i task in background ancora in corso (e.background_tasks). Se ce ne sono,turn.completela mostra ancorarunninge in attesa di loro, invece di annunciare una fine che non è reale. - Una domanda nel riquadro del passo successivo dell’app desktop è una domanda. Quando un turno termina con lo strumento
mcp__ccd_turn__wrap_updell’app desktop che porta unask, l’hooktool.callconserva quel testo (turnAsk), eturn.completemostraaskingcon quel testo invece dicelebrating. - Solo le chiamate di Claude la muovono.
tool.callinizia conisClaudesCall(next.origin)(inhooks/watch.ts): la chiamata di un’altra mod, come narsil-check che legge la sua sessione all’avvio, non è lavoro di Claude. - Le parole vivono in un solo file.
hooks/words.tscontiene tutte le etichette (STATUS_LABEL), il costruttore delle frasi (headline), i commenti (LINESepick) e la tabella degli strumenti. Il modulo degli hook decide cosa è successo;words.tsdecide come dirlo. Così le etichette restano identiche ovunque compaiano: la fascia, la finestra mobile, il telefono e/narsil estado. - Narsil parla in prima persona. Le frasi sono scritte come se parlasse Narsil (“Estoy leyendo”, “Sto leggendo”), una scelta registrata nella cronologia dei commit (vedi sotto).
Cosa disegna la fascia
L’hook ui.render per { component: 'AbovePrompt' } legge lo stato e restituisce un albero di elementi Box, Text, Button e Svg ottenuti da $.ui.resolve(e). Cede il posto a un sondaggio (e.props.hasSurvey) e a /narsil ocultar.
Nel terminale disegna una riga: la faccina di testo da FACE, l’etichetta in grassetto nel suo colore e la frase. Sulle altre superfici disegna l’immagine con Svg a 132 per 118 pixel, e accanto una colonna con ● LABEL · Narsil · level, la frase in grassetto e il commento attenuato. I colori vengono da STATUS_COLOR in hooks/sprite.ts: blu #3B8BFF per al lavoro, grigio per ferma, giallo #F5B400 per ha bisogno di te, verde per finito e rosso per errore.
Ogni testo che può crescere viene disegnato con wrap="truncate-end" dentro un box con minWidth={0}, così un nome di file lungo viene tagliato dentro la fascia invece di allargarla.
La fascia che vedi oggi disegna la più importante di tutte le tue conversazioni aperte, non solo quella corrente; la terza guida di questo percorso spiega questa parte. Quando la conversazione mostrata è un’altra, la frase inizia con il nome di quella conversazione e il commento viene omesso.
Come è stata chiesta all’IA
La richiesta originale per gli stati non è stata registrata. I log pubblici dei task del progetto (odd/tasks/fleet-view.md e odd/tasks/animated-poses.md) iniziano più tardi, e nessuno dei due riguarda la prima fascia.
Ricostruzione dalla cronologia dei commit
Da git log -- hooks/register.tsx hooks/words.ts in narsil-pet:
b1187f3(2026-10-30) “feat: show Narsil above the prompt with clear states and /narsil” (mostra Narsil sopra il prompt con stati chiari e /narsil). La fascia, i suoi stati e il comando/narsilarrivano insieme nel primo commit del modulo degli hook.8e29583(2026-10-30) “fix(band): keep long text from widening the desktop band” (evita che il testo lungo allarghi la fascia desktop). La regola diminWidth={0}e del troncamento vista sopra viene da qui.2027f06(2026-10-30) “fix(alerts): only alert when a permission dialog needs your answer” (avvisa solo quando una finestra di permesso ha bisogno della tua risposta). Il passaggio aclassic.PermissionRequest, spiegato nel commento del codice citato sopra.0cfc369(2026-10-31) “refactor: move Narsil’s wording and labels out of the hooks module” (sposta i testi e le etichette di Narsil fuori dal modulo degli hook). È qui che nascehooks/words.ts.c73bc13(2026-10-31) “feat: let Narsil speak of herself in the first person” (fa parlare Narsil di sé in prima persona), seguito da36256f9“feat: let the band, window and alerts speak in Narsil’s first person” (fa parlare la fascia, la finestra e gli avvisi in prima persona con la voce di Narsil).2532e7c(2026-11-02) “feat: alert as a question when a turn ends asking in the desktop app’s next-step box” (avvisa come domanda quando un turno termina chiedendo qualcosa nel riquadro del passo successivo dell’app desktop).519dd73(2026-11-06) “fix: wait for background work before announcing a turn finished” (aspetta il lavoro in background prima di annunciare che un turno è finito). Il suo messaggio dice che un turno che si ferma con shell, monitor o subagenti in background ancora in corso ora mostra Narsil in attesa di loro.
Lo schema è chiaro anche senza i prompt: una prima versione che associava gli eventi agli stati, poi una serie di correzioni ogni volta che uno stato mentiva (un falso allarme, una falsa fine, una domanda persa).
Un prompt che puoi usare
Il prompt seguente è stato scritto per questa guida come suggerimento. Non è il prompt usato per costruire Narsil.
Crea una mod di Claude Code chiamata
my-petche mostri lo stato della conversazione nella fascia sopra il prompt (ui.rendersuAbovePrompt). Conserva un unico valore di stato in un atom con uno stato (al lavoro, ferma, in attesa, finito, errore) e una frase di una riga. Impostalo daturn.start(al lavoro),tool.call(al lavoro, con lo strumento e il nome base del file nella frase; in attesa perAskUserQuestionedExitPlanMode) eturn.complete(finito suanswer, ferma suaborted, errore negli altri casi). Ignora gli eventi che hannoagentIdimpostato. Disegna l’etichetta in grassetto nel suo colore e la frase dopo, troncata in modo che non allarghi mai la fascia. Verifica ogni API sui tipi di plugin-authoring, dichiara l’atom intypes/index.d.tse aggiungi un test conclaude-code/testingche verifichi che una chiamata aReadmostri il nome del file.
Il codice minimo
Questa è una versione ridotta dell’idea, scritta per questa guida e verificata sui tipi di Claude Code 2.1.325. È adattata da hooks/register.tsx, hooks/words.ts e hooks/sprite.ts in narsil-pet (GPL-3.0-or-later); i colori sono lo STATUS_COLOR di Narsil.
Il tipo dello stato, in types/index.d.ts (indicato da "types" in plugin.json):
export type Status = 'working' | 'idle' | 'waiting' | 'done' | 'error'
export type Pet = { status: Status; headline: string }
declare module 'claude-code' {
interface PluginState {
'my-pet': { pet: Pet }
}
}
Il modulo degli hook, hooks/register.tsx:
import { atom, read, update } from 'claude-code'
import type { Register } from 'claude-code'
import type { Status } from '../types'
const LABEL: Record<Status, string> = {
working: 'WORKING',
idle: 'IDLE',
waiting: 'NEEDS YOU',
done: 'DONE',
error: 'ERROR',
}
const COLOR: Record<Status, string> = {
working: '#3B8BFF',
idle: '#8A90A6',
waiting: '#F5B400',
done: '#22B573',
error: '#F0435A',
}
const VERB: Record<string, string> = {
Read: 'reading',
Grep: 'searching',
Edit: 'editing',
Write: 'editing',
Bash: 'running',
}
const pet = atom({ plugin: 'my-pet', key: 'pet' } as const, {
status: 'idle',
headline: 'Waiting for your message',
})
export const register: Register = (on) => {
on('turn.start', async ($, e, next) => {
if (e.agentId === undefined)
await update($, pet, () => ({ status: 'working', headline: 'Thinking' }))
return next(e)
})
on('tool.call', async ($, e, next) => {
if (e.agentId === undefined) {
const input = e as unknown as Record<string, unknown>
const file = typeof input.file_path === 'string' ? input.file_path.split(/[\\/]/).pop() : ''
const isAsking = e.tool === 'AskUserQuestion' || e.tool === 'ExitPlanMode'
await update($, pet, () =>
isAsking
? { status: 'waiting', headline: 'I have a question for you' }
: {
status: 'working',
headline: `I am ${VERB[e.tool] ?? 'working'}${file ? `: ${file}` : ''}`,
},
)
}
return next(e)
})
on('turn.complete', async ($, e, next) => {
const result = await next(e)
if (e.agentId !== undefined) return result
const status: Status =
e.reason === 'answer' ? 'done' : e.reason === 'aborted' ? 'idle' : 'error'
await update($, pet, () => ({
status,
headline: status === 'error' ? 'I stopped on an error' : 'Done',
}))
return result
})
on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
if (e.props.hasSurvey) return next(e)
const s = await read($, pet)
const { Box, Text } = $.ui.resolve(e)
return (
<Box flexDirection="row" gap={1} minWidth={0}>
<Text bold color={COLOR[s.status]}>{`● ${LABEL[s.status]}`}</Text>
<Text wrap="truncate-end">{s.headline}</Text>
</Box>
)
})
}
Tre dettagli reggono il progetto. Ogni hook che si limita a osservare termina chiamando next(e), così il comportamento di Claude Code prosegue. turn.complete attende prima next(e) e reagisce al turno ormai concluso. E l’hook di render legge l’atom con read, che iscrive il disegno: ogni update ridisegna la fascia.
Errori comuni e come testarlo
Questi vengono dal codice e dalle correzioni di Narsil:
- Reagire ai subagenti come se fossero la conversazione principale. Anche i subagenti generano
turn.start,tool.calleturn.complete, cone.agentIdimpostato. Narsil verificae.agentId === undefinedprima di toccare lo stato principale. - Allarmi che la modalità di permesso ha già risolto. Rilevare “ha bisogno di te” da
tool.checkscatta anche con bypass permissions. La correzione di Narsil (2027f06) ascoltaclassic.PermissionRequeste lo ignora comunque quando ha risposto un hook delle impostazioni (result.decision) o la modalità èbypassPermissions. - Un “finito” che non è finito. Un turno può terminare mentre il lavoro in background continua. Narsil legge
background_tasksinclassic.Stopprima di decidere (519dd73). - Testo che allarga la fascia. Sul desktop una frase lunga spinge fuori il layout. Usa
minWidth={0}sulla colonna ewrap="truncate-end"sul testo (8e29583). - Inghiottire il flusso. Un hook
turn.stepè un generatore: se non restituisce conyieldogni pezzo ricevuto danext(e), la risposta smette di arrivare allo schermo. - Ignorare i sondaggi. Quando
e.props.hasSurveyè vero, la fascia appartiene al sondaggio; restituiscinext(e).
Per testare, claude plugin test . esegue i file *.test.tsx della mod. Il tests/narsil.test.tsx di Narsil è un buon modello: avvia una sessione con $.session.start, chiama strumenti con $.tool.call, monta la fascia con $.ui.mount e cerca i testi con find. Tra i test da copiare per nome ci sono “a new conversation shows as stopped and ready, on every surface” (una nuova conversazione appare ferma e pronta, su ogni superficie), “a permission dialog you must answer pops up as a question” (una finestra di permesso a cui devi rispondere compare come domanda) e “an ask the mode settles by itself (bypass permissions) raises no alarm” (una richiesta che la modalità risolve da sola, con bypass permissions, non genera allarmi). Il log dei task di Narsil registra che, nella shell dell’autore, claude plugin test . richiedeva CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (odd/tasks/fleet-view.md, L6). Esegui anche claude plugin validate .claude-plugin/plugin.json: confronta le letture e le scritture dei tuoi atom con types/index.d.ts.
Una nota sulle superfici: il README di Narsil dice che la fascia funziona nel terminale, nell’app desktop, in VS Code e nell’app mobile. I tipi della 2.1.325 documentano AbovePrompt come “Raised on the terminal, desktop and mobile surfaces only” (generato solo sulle superfici terminale, desktop e mobile). Prova sulle superfici che ti interessano invece di affidarti a una delle due affermazioni.
Per andare oltre
La versione completa in narsil-pet aggiunge molto attorno allo stesso nucleo:
setMoodinhooks/register.tsxè l’unico punto d’ingresso per ogni cambiamento, e invia anche lo stato all’hub locale (pushOverlay).headlineeLINESinhooks/words.tscontengono la frase per ciascuno dei dodici umori e tre commenti per ognuno;describeCallcostruisce il dettaglio per file, pattern, query, URL, comandi e subagenti.- L’hook
tool.callriconosce anche i comandi di test (TEST_COMMAND) per festeggiare i test superati, e avvisa dei comandi che non si possono annullare (dangerOf), senza bloccarli. startWaitingestopWaitinginsistono una volta su un permesso o una domanda rimasti in attesa per cinque minuti.announceparla e notifica nei momenti chiave (inizio, fine, domanda, errore), esendStatusinvia lo stato al telefono.FACEinhooks/sprite.tsè la faccina del terminale per ogni umore;spritedisegna l’immagine completa, trattata nella prossima guida.
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è