I tuoi /comandi
Come /narsil viene registrato come un solo comando slash con molti sottocomandi, come vengono smistate le sue parole, come il comando da solo fa anche da aiuto, e come testarlo.
Cosa fa
Ogni funzionalità di questo percorso ha un interruttore o una domanda, e tutti vivono sotto un solo comando slash: /narsil. Scrivi /narsil e una parola, e Narsil risponde nella trascrizione. Scritto da solo, /narsil ti dice come è configurata ed elenca ogni parola che accetta.
Le parole, così come il codice le smista (Narsil parla spagnolo, quindi le parole sono in spagnolo):
| Comando | Cosa fa |
|---|---|
/narsil |
Mostra le impostazioni attuali e la riga d’uso. |
/narsil estado |
Dice cosa sta facendo, quante conversazioni sono aperte, e su quali superfici disegna. |
/narsil ocultar · mostrar |
Nasconde o mostra la fascia. |
/narsil silencio · voz |
Spegne o accende la voce. |
/narsil discreto · normal |
Attiva o disattiva la modalità discreta (guida 14). |
/narsil flotante |
Attiva o disattiva la finestra mobile (guida 5). |
/narsil prueba |
Invia un avviso di prova, con la voce. |
/narsil consejo · consejo profundo |
Chiede un consiglio subito, o uno sull’intera conversazione (guida 11). |
/narsil consejos on · off · cada <min> · voz |
Consigli automatici attivi o no, la loro spaziatura, detti a voce o no. |
/narsil pasos on · off |
Prossimi passi attivi o no (guida 12). |
/narsil cache · cache <min> · cache auto |
Dice, imposta o deduce quanto dura la cache del prompt (guida 8). |
/narsil resumen |
Il riassunto della sessione (guida 16). |
/narsil nivel |
Livello, stadio e come guadagna XP (guida 13). |
/narsil movil · on · off · nuevo · prueba · clave [off] |
Avvisi sul telefono (guida 15). |
La tabella “Comandos” (“comandi”) del README elenca le stesse parole, e concordano con il codice.
Un comando invece di quindici mantiene pulito il completamento automatico: scrivi /nar, e tutto ciò che Narsil sa fare sta dietro un solo nome.
Come funziona dentro
Registrare: $.command.register
Una mod dichiara un comando slash durante l’esecuzione. Narsil lo fa come prima cosa in session.start:
await $.command.register({
name: 'narsil',
description:
'Narsil, tu mascota: estado | ocultar | mostrar | silencio | voz | discreto | normal | flotante | prueba | consejo [profundo] | consejos on|off|cada <min>|voz | pasos on|off | cache [auto|<min>] | resumen | nivel | movil [on|off|nuevo|prueba|clave [off]]',
})
I tipi della 2.1.325 descrivono $.command.register come “Declares the slash command /<name> for this session, listed in the typeahead from the next keystroke on” (dichiara il comando slash /<name> per questa sessione, elencato nel completamento automatico dal tasto successivo in poi). Tre punti di quella frase danno forma al design:
- “for this session” (per questa sessione). La registrazione non sopravvive alla sessione, ed è per questo che avviene a ogni
session.start. - La specifica.
CommandSpechaname(lettere, cifre,_e-, fino a 64),description(“The one line the typeahead and/helpshow for it”, l’unica riga che il completamento automatico e/helpmostrano per esso), unargumentHintopzionale (“The hint drawn dim after the name”, il suggerimento disegnato attenuato dopo il nome) e unimmediateopzionale. “Registering a name again replaces it; a built-in’s name is refused.” (registrare di nuovo un nome lo sostituisce; il nome di un comando integrato viene rifiutato.) - Servirlo. “Serve it with a
command.runhook on{ command: "<name>" }that returns{ text }” (servilo con un hookcommand.runsu{ command: "<name>" }che restituisce{ text }).
Narsil mette l’elenco delle parole in description, così il completamento automatico e /help le mostrano tutte (la descrizione inizia con “Narsil, tu mascota”, “Narsil, la tua mascotte”). Non usa argumentHint; un suggerimento breve come [estado | resumen | …] sarebbe l’alternativa, al prezzo di mostrare meno.
Non imposta nemmeno immediate. Senza di esso, dicono i tipi, un comando scritto mentre un turno è in corso aspetta “for the turn to end” (che il turno finisca). /narsil discreto scritto a metà turno ha quindi effetto dopo il turno. Con immediate, l’hook “must not assume the turn’s state” (non deve presumere lo stato del turno), il che è molto da chiedere a un gestore che ne legge e scrive così tanto.
Servire: un solo hook command.run
L’hook è registrato con un matcher, quindi gira solo per /narsil:
on('command.run', { command: 'narsil' }, async ($, e) => {
await noteOrigin($, e.origin)
const arg = e.args.trim().toLowerCase().replace(/\s+/g, ' ')
// …
})
Non chiama mai next. I tipi spiegano cosa significa: “A hook’s own answer without next runs no command: its text is shown as the command’s output” (la risposta propria di un hook senza next non esegue nessun comando: il suo text viene mostrato come output del comando). Dato che nient’altro implementa /narsil, non c’è niente a cui passare il controllo.
Prima che venga letta qualsiasi parola succedono tre cose:
noteOrigin($, e.origin). L’origindi un comando dice da dove è arrivato, come quello diprompt.submit. Eseguire/narsildal telefono conta come scrivere da fuori (guida 15).- Normalizzare le parole.
e.argsè “Everything after the name, as typed” (tutto ciò che segue il nome, così come è stato scritto). Narsil lo ripulisce dagli spazi ai bordi, lo mette in minuscolo e comprime le sequenze di spazi, così/narsil Consejos OFFfunziona. - Gli accenti. Il gruppo del telefono accetta
movilemóvil, e il pattern della cache,/^cach[eé](?: (auto|\d{1,3}))?$/, accettacacheecaché. Le persone scrivono entrambe le forme.
Smistare: gruppi che rispondono “non è mio”
Il corpo è una catena. I tre gruppi più grandi vivono ciascuno accanto alla propria funzionalità, come funzioni che restituiscono il testo della risposta, o undefined per le parole che non sono loro:
const advice = await adviceCommand($, arg)
if (advice !== undefined) return { text: advice }
const stepped = await stepsCommand($, arg)
if (stepped !== undefined) return { text: stepped }
const phoned = await phoneCommand($, arg)
if (phoned !== undefined) return { text: phoned }
adviceCommandaccettaconsejo,consejo profundoeconsejos ….stepsCommandaccettapasos on|offecache [auto|<min>].phoneCommandaccettamovil ….
Un gruppo che riconosce la sua prima parola ma non il resto risponde con la propria riga d’uso invece che con undefined: /narsil consejo raro riceve “Uso: /narsil consejo [profundo] | consejos on | off | cada /narsil movil raro riceve “Uso: /narsil movil [on | off | nuevo | prueba | clave [off]]”. La persona vede le parole adatte a ciò che stava cercando di fare, non l’intero elenco.
Poi il gestore principale si occupa del resto da sé: resumen e nivel rispondono subito; prueba, estado e flotante hanno ciascuno un ramo; e sei parole on/off condividono una tabella, change, che associa ogni parola a una modifica delle preferenze (ocultar a { isHidden: true }, discreto a { isQuiet: true }, e così via). Una parola nota viene fusa nell’atom prefs e salvata con $.store.set('prefs', …), così ogni impostazione sopravvive alla sessione.
Il design tiene le parole di ogni funzionalità con la funzionalità. Aggiungere un gruppo di comandi a una funzionalità significa una funzione nella sua sezione e una riga nella catena.
Il comando da solo è l’aiuto
Tutto ciò che la catena non riconosce, compreso /narsil vuoto, cade alla fine, dove patch è undefined. Quel ramo legge le preferenze e le stampa: se la fascia è visibile, la voce accesa, la finestra mobile attiva; i consigli e la loro spaziatura; i prossimi passi e quanto dura la cache; una riga per la modalità discreta quando è attiva. L’ultima riga è la riga d’uso, lo stesso elenco di parole della descrizione.
Quindi non esiste una parola ayuda (“aiuto”) separata: un errore di battitura e un semplice /narsil rispondono entrambi con lo stato e le parole. Questo corrisponde al README, la cui prima riga dice che /narsil “Muestra la configuración actual y la ayuda” (“mostra le impostazioni attuali e l’aiuto”).
L’elenco delle parole vive in tre posti: la descrizione, la riga d’uso e il README. Il piano dei consigli, docs/plan-advice.md, lo dice apertamente quando aggiunge le parole consejo: “Update the command description and the usage text of /narsil.” (aggiorna la descrizione del comando e il testo d’uso di /narsil.) Tenere allineati i tre è un compito manuale in Narsil.
Cos’è la risposta
Ogni ramo restituisce { text }, un CommandRunResult. Due dei suoi campi meritano di essere conosciuti anche se Narsil non li usa. context è “What the model reads after the command’s output and the person never sees” (ciò che il modello legge dopo l’output del comando e che la persona non vede mai). isTextDisplayOnly tiene il testo fuori dalle richieste al modello, ma i tipi dicono che viene rispettato solo quando ogni plugin che aggancia il comando è incluso in Claude Code: “Any other plugin’s text stays in requests” (il testo di qualsiasi altro plugin resta nelle richieste). Quindi tutto ciò che /narsil risponde, compresa la chiave del telefono della guida 15, fa parte di ciò che il modello legge.
Come è stata chiesta all’IA
La richiesta originale per /narsil non è stata registrata. Ciò che è registrato è un passo del piano: in docs/plan-advice.md, tra i comandi che aggiungono i consigli, il piano dice:
“Update the command description and the usage text of
/narsil.”
In italiano: aggiorna la descrizione del comando e il testo d’uso di /narsil.
Questa è la formulazione del piano, non la richiesta dell’autore.
Ricostruzione dalla cronologia dei commit
Da git log -G "Narsil, tu mascota" -- hooks/register.tsx, che trova ogni commit che ha cambiato la descrizione registrata:
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). Il comando nasce con la fascia, e la sua prima descrizione dice “Narsil, tu mascota: estado | ocultar | mostrar | silencio | voz | flotante | prueba”.467a64b(2026-10-30) “feat(advice): give short, concrete tips about the work in progress” (dà consigli brevi e concreti sul lavoro in corso). Le paroleconsejo.0993bd7(2026-10-30) “feat: show a prompt-cache clock and offer next steps after a turn” (mostra un orologio della cache del prompt e offre i prossimi passi dopo un turno).pasosecache.f7a494e(2026-10-30) “feat: warn about loops, insist on waiting permissions and sum the session up” (avvisa dei cicli, insiste sui permessi in attesa e riassume la sessione).resumen.8913cdd(2026-10-30) “feat: let Narsil earn experience and levels kept across sessions” (fa guadagnare a Narsil esperienza e livelli conservati tra le sessioni).nivel.17ffb30(2026-10-31) “feat: add a quiet mode that only speaks up when Narsil needs you” (aggiunge una modalità discreta che si fa sentire solo quando Narsil ha bisogno di te).discretoenormal.d91997f(2026-10-31) “feat: send what needs you to your phone and watch through ntfy, with Narsil’s picture” (invia ciò che ha bisogno di te al telefono e all’orologio tramite ntfy, con l’immagine di Narsil).movil.5a9ee10(2026-11-01) “feat: seal phone messages with /narsil movil clave, send reset times and an Abrir Claude button” (sigilla i messaggi al telefono con /narsil movil clave, invia gli orari di azzeramento e un pulsante Abrir Claude).clave.
Il comando è cresciuto una parola alla volta, ciascuna con la funzionalità che controlla, e ogni commit ha toccato la descrizione nella stessa modifica. È l’abitudine che il piano chiede.
Un prompt che puoi usare
Il prompt seguente è stato scritto per questa guida come suggerimento. Non è il prompt dell’autore.
Dai alla mia mod di Claude Code
my-petun solo comando slash,/my-pet, con sottocomandi. Insession.start, chiama$.command.registercon il nome e una descrizione che elenchi ogni sottocomando. Servilo con un solo hookcommand.runcon matcher su{ command: 'my-pet' }che restituisca{ text }senza chiamarenext. Normalizzae.args(spazi ai bordi rimossi, minuscolo, spazi singoli). Dai a ogni funzionalità la propria funzione che restituisca la risposta per le sue parole, la propria riga d’uso per una prima parola nota con un resto sconosciuto, oundefinedper le parole che non sono sue, e concatenale. Associa le parole on/off semplici a una modifica di un atomprefssalvato con$.store.set. Per un argomento vuoto o sconosciuto, stampa le impostazioni attuali e la riga d’uso. Tieni allineati la descrizione, la riga d’uso e il README. Testa conclaude-code/testing, chiamando$.command.run({ command: 'my-pet', args, origin: { kind: 'composer' }, presentation: { isFullscreen: false, columns: 100 } }), che ogni parola risponda e che una parola sconosciuta stampi la riga d’uso.
Il codice minimo
Scritto per questa guida e verificato con i tipi della 2.1.325 ($.command.register, command.run, $.store.get, $.store.set, session.start). È adattato da hooks/register.tsx in narsil-pet (GPL-3.0-or-later). L’atom prefs è dichiarato in types/index.d.ts come { isHidden: boolean; isMuted: boolean }.
import { atom, read, update } from 'claude-code'
import type { EngineInterface, Register } from 'claude-code'
const WORDS = 'status | hide | show | mute | voice | tips on|off'
const prefs = atom({ plugin: 'my-pet', key: 'prefs' } as const, { isHidden: false, isMuted: false })
// One feature's words: its answer, its own usage line, or undefined when the words are not its own.
async function tipsCommand($: EngineInterface, arg: string): Promise<string | undefined> {
if (arg === 'tips on' || arg === 'tips off')
return `My pet: tips ${arg === 'tips on' ? 'on' : 'off'}.`
if (arg.startsWith('tips')) return 'Usage: /my-pet tips on | off'
return undefined
}
export const register: Register = (on) => {
on('session.start', async ($, e, next) => {
// Registered for this session only: every session registers it again.
await $.command.register({ name: 'my-pet', description: `My pet: ${WORDS}` })
const saved = await $.store.get('prefs').catch(() => undefined)
if (saved && typeof saved === 'object') await update($, prefs, (p) => ({ ...p, ...saved }))
return next(e)
})
on('command.run', { command: 'my-pet' }, async ($, e) => {
const arg = e.args.trim().toLowerCase().replace(/\s+/g, ' ')
const tips = await tipsCommand($, arg)
if (tips !== undefined) return { text: tips }
const change: Record<string, { isHidden?: boolean; isMuted?: boolean }> = {
hide: { isHidden: true },
show: { isHidden: false },
mute: { isMuted: true },
voice: { isMuted: false },
}
const patch = arg === 'status' ? undefined : change[arg]
if (!patch) {
// The bare command, a typo and "status" all answer with the state and the words.
const p = await read($, prefs)
return {
text: `My pet is ${p.isHidden ? 'hidden' : 'visible'}, with the voice ${p.isMuted ? 'off' : 'on'}.\nUsage: /my-pet ${WORDS}`,
}
}
const saved = await update($, prefs, (p) => ({ ...p, ...patch }))
await $.store.set('prefs', saved).catch(() => undefined)
return { text: `My pet: done (${arg}).` }
})
}
WORDS viene scritto una volta e usato sia per la descrizione sia per la riga d’uso, il che elimina uno dei tre posti che Narsil tiene allineati a mano. Il README resta da aggiornare a te.
Errori comuni e come testarlo
- Registrare una volta sola. Una registrazione dura per la sessione. Registra in
session.start, ogni volta. - Un nome già preso. “a built-in’s name is refused” (il nome di un comando integrato viene rifiutato). Scegli un nome che sia chiaramente della tua mod.
- Chiamare
nextdal tuo comando. Dietro il tuo non c’è nessun comando da eseguire; rispondi con{ text }. - Confronto esatto sull’input grezzo. Le persone scrivono spazi in più, maiuscole e accenti. Normalizza prima, e accetta le forme accentate che ti aspetti.
- Un’unica gigantesca catena di
if. Funziona, ma le parole di ogni funzionalità finiscono lontano dalla funzionalità. Lascia che ogni funzionalità possieda le sue parole e restituiscaundefinedper il resto. - Un aiuto che si disallinea. La descrizione, la riga d’uso e il README devono dire la stessa cosa. Costruisci le prime due da una sola costante, se puoi.
- Segreti nelle risposte. Il testo di un comando resta nelle richieste al modello. Stampa un segreto solo quando la persona deve copiarlo, e dillo.
Per testare, claude plugin test . esegue tests/narsil.test.tsx, dove i comandi girano tramite $.command.run({ command: 'narsil', args: 'nivel', ...TYPED }). TYPED è { origin: { kind: 'composer' }, presentation: { isFullscreen: false, columns: 100 } }: un comando scritto alla scrivania. BY_PHONE sostituisce l’origine con { kind: 'bridge' } per eseguirne uno da Remote Control. Test che vale la pena leggere per nome: “/narsil estado tells which surfaces asked to draw the band, and which never did” (/narsil estado dice quali superfici hanno chiesto di disegnare la fascia, e quali non l’hanno mai fatto), “/narsil discreto keeps her quiet, and /narsil normal brings everything back” (/narsil discreto la tiene in silenzio, e /narsil normal riporta tutto), “/narsil consejos off stops automatic tips, and /narsil consejo still answers” (/narsil consejos off ferma i consigli automatici, e /narsil consejo risponde ancora) e “/narsil movil nuevo changes the topic, and /narsil movil prueba sends one” (/narsil movil nuevo cambia il topic, e /narsil movil prueba ne invia uno).
Dove il codice e il README differiscono
Concordano su ogni parola. Una piccola svista è nel codice: la riga d’uso del ramo di ripiego è scritta 'Uso:/narsil estado | …', senza lo spazio dopo i due punti che hanno le righe d’uso dei sottogruppi. Risale a 17ffb30; prima di esso la riga diceva 'Uso: /narsil …'.
Per andare oltre
phoneCommandinhooks/register.tsxè il più chiaro dei gruppi da copiare: separa la prima parola dal resto, salva tramite un piccolo helpersave, e finisce con la propria riga d’uso.stepsCommandmostra una parola con un numero opzionale, analizzato con una sola espressione regolare e limitato (Math.min(1440, Math.max(1, …))).$.command.list()restituisce ogni comando slash che la persona può eseguire, e$.command.runne esegue uno come se fosse scritto; entrambi sono nei tipi della 2.1.325.
Questa è l’ultima guida del percorso “La tua mascotte di stato”. Il suo indice elenca tutte e diciassette le guide, dagli stati a colpo d’occhio a questi comandi, se vuoi tornare a una qualsiasi funzionalità. Per le basi su cui poggia ogni guida, le guide “Basi delle mod” trattano di cosa è fatta una mod, l’oggetto $, come installare, ricaricare, validare e testare una mod, le superfici su cui gira, e cosa significa la GPL v3 di Narsil quando ne riutilizzi il codice.
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è