Les états d’un coup d’œil
Comment Narsil transforme les événements de la session en cinq états, une phrase sur l’étape en cours et un court commentaire, dessinés dans la bande au-dessus du prompt.
Ce que ça fait
Narsil vit dans la bande située juste au-dessus du prompt. Un coup d’œil suffit pour répondre à la question que vous vous posez le plus souvent pendant que Claude travaille : dois-je faire quelque chose maintenant ?
La bande affiche trois choses :
-
Un état, en capitales et dans sa propre couleur. Narsil parle espagnol, les libellés sont donc en espagnol :
Libellé Signification Quand il s’affiche TRABAJANDOAu travail Claude réfléchit, lit, cherche, modifie des fichiers ou exécute des commandes. PARADAÀ l’arrêt, vous attend La conversation attend votre prochain message. TE NECESITAA besoin de vous Une question, un plan à approuver ou une autorisation à accorder ou refuser. TERMINADATerminé Claude a fini sa réponse. ERRORErreur Le tour s’est arrêté parce que quelque chose a échoué. -
Une phrase qui dit exactement ce que fait Claude, comme « Estoy editando: register.tsx » (« Je modifie : register.tsx ») ou « Te necesito: tengo una pregunta para ti » (« J’ai besoin de vous : j’ai une question pour vous »).
-
Le commentaire propre à Narsil sous cette phrase, tiré au hasard parmi quelques lignes prévues pour chaque moment, comme « Tecleando con mis aletas. » (« Je tape avec mes nageoires. ») pendant la modification d’un fichier.
En dehors du terminal, la bande dessine aussi Narsil elle-même, dans une pose propre à chaque état (le guide suivant traite du dessin). Dans le terminal, elle dessine à la place un petit visage en texte, comme ~(•ᴗ•)~ 💻.
L’intérêt est que vous n’avez pas besoin de lire la transcription pour savoir où en sont les choses. Un TE NECESITA jaune est une raison de revenir ; un TRABAJANDO bleu est une raison de continuer à faire autre chose.
Comment ça marche à l’intérieur
L’état n’est pas quelque chose que Claude Code transmet à un mod. Narsil le construit elle-même à partir des événements de la session, le conserve dans une seule valeur et dessine cette valeur.
Une valeur, deux niveaux : l’humeur et l’état
Le mod conserve une seule valeur d’état, l’atome pet dans hooks/register.tsx, avec trois champs : mood, detail et line. Son type, Pet, est déclaré dans types/index.d.ts.
mood (l’humeur) est plus fin que les cinq états. Il existe douze humeurs : greeting, idle, thinking, talking, reading, searching, writing, running, asking, scared, celebrating et failed. Les cinq états sont dérivés de l’humeur par statusOf dans hooks/sprite.ts :
greetingetidlecorrespondent à l’arrêt (PARADA).askingcorrespond à l’attente (TE NECESITA).celebratingcorrespond à terminé (TERMINADA).failedcorrespond à l’erreur (ERROR).- Toutes les autres humeurs correspondent au travail (
TRABAJANDO), y comprisscared.
La raison de ces deux niveaux est que l’état répond à la question « dois-je agir ? », et cinq réponses suffisent pour cela ; l’humeur répond à la question « que se passe-t-il exactement ? », qui détermine la phrase, le commentaire et la pose. Ne conserver que l’humeur et en dériver l’état garantit que les deux ne peuvent jamais se contredire.
L’humeur scared montre bien pourquoi cette séparation compte. Quand un appel d’outil échoue au milieu d’un tour, Narsil a l’air surprise et la phrase dit « Ha fallado un paso (Bash); sigo trabajando » (« Une étape a échoué (Bash) ; je continue à travailler »). L’état reste TRABAJANDO, parce que Claude travaille toujours et que rien ne vous est demandé. Seul un tour qui se termine par un échec devient ERROR.
Les événements qu’écoute Narsil
Chaque changement d’humeur passe par une seule fonction, setMood dans hooks/register.tsx, qui écrit l’atome pet et envoie le nouvel état à la fenêtre flottante. Les hooks qui l’appellent :
session.start: une nouvelle conversation commence engreeting, ce qui compte comme un arrêt.turn.start: votre prompt lance un tour ; l’humeur devientthinking. Le hook n’agit que lorsquee.agentIdest indéfini, afin que le tour d’un sous-agent ne réinitialise pas la conversation principale.turn.step: la sortie du modèle arrive en flux, par morceaux. Un morceauthinkingmaintient l’humeur àthinking; le premier morceautextde la boucle principale la fait passer àtalking(« Estoy escribiendo la respuesta », « J’écris la réponse »). Ce hook est un générateur asynchrone : il fournit (yield) chaque morceau qu’il reçoit, si bien que le flux atteint l’écran sans modification.tool.call: l’événement le plus parlant. Le nom de l’outil choisit l’humeur au moyen deMOOD_BY_TOOLdanshooks/words.ts(Readcorrespond à la lecture,GrepetWebSearchà la recherche,EditetWriteà l’écriture,BashetPowerShellà l’exécution), etdescribeCalltransforme l’entrée de l’appel en un court détail placé après les deux-points : le nom de base du fichier pour un outil de fichiers, le motif pour une recherche, la première ligne d’une commande.AskUserQuestionetExitPlanModesont traités à part (ASKING_TOOLS) : ils définissentasking, parce que l’outil lui-même est le moment où Claude s’arrête et attend.classic.PermissionRequest: une boîte de dialogue d’autorisation à laquelle vous devez répondre. Le hook appelle d’abordnext(e)et ne définitaskingque si aucun hook de paramètres n’a déjà tranché et que le mode n’est pasbypassPermissions.turn.complete: le tour se termine, ete.reasondécide de l’état.answerdevientcelebratingavec le temps écoulé (« He terminado (en 2 min) »),abortedrevient àidleavec « lo has detenido tú » (« c’est vous qui l’avez arrêté »), et toute autre raison devientfailed.
Pourquoi chaque décision a été prise
Les commentaires de hooks/register.tsx donnent les raisons, et ils méritent d’être lus comme des notes de conception :
- Les autorisations utilisent
classic.PermissionRequest, et nontool.check. Le commentaire explique que leaskdetool.checkarrive avant que le mode d’autorisation ne règle l’appel, si bien qu’en mode « bypass permissions », avec une règle ou avec le classificateur automatique, Narsil « cry wolf » (« crierait au loup »). Le moteur ne déclenchePermissionRequestque lorsqu’il est sur le point de vous montrer la boîte de dialogue. - Un tour terminé n’est pas toujours « terminé ». Dans le hook
classic.Stop, Narsil compte les tâches d’arrière-plan encore en cours (e.background_tasks). S’il y en a,turn.completela montre toujours enrunning, en train de les attendre, au lieu d’annoncer une fin qui n’est pas réelle. - Une question dans la case d’étape suivante de l’application de bureau est une question. Quand un tour se termine avec l’outil
mcp__ccd_turn__wrap_upde l’application de bureau portant unask, le hooktool.callconserve ce texte (turnAsk), etturn.completeafficheaskingavec ce texte au lieu decelebrating. - Seuls les appels de Claude lui-même la font réagir.
tool.callcommence parisClaudesCall(next.origin)(danshooks/watch.ts) : l’appel d’un autre mod, par exemple narsil-check qui lit sa session au démarrage, n’est pas le travail de Claude. - Les mots vivent dans un seul fichier.
hooks/words.tscontient tous les libellés (STATUS_LABEL), le constructeur de phrases (headline), les commentaires (LINESetpick) et la table des outils. Le module de hooks décide de ce qui s’est passé ;words.tsdécide de la façon de le dire. Les libellés restent ainsi identiques partout où ils apparaissent : la bande, la fenêtre flottante, le téléphone et/narsil estado. - Narsil parle à la première personne. Les phrases sont écrites comme si Narsil parlait (« Estoy leyendo », « Je lis »), un choix consigné dans l’historique des commits (voir plus bas).
Ce que dessine la bande
Le hook ui.render pour { component: 'AbovePrompt' } lit l’état et renvoie un arbre d’éléments Box, Text, Button et Svg issus de $.ui.resolve(e). Il cède la place à un sondage (e.props.hasSurvey) et à /narsil ocultar.
Dans le terminal, il dessine une seule ligne : le visage en texte tiré de FACE, le libellé en gras dans sa couleur, et la phrase. Sur les autres surfaces, il dessine l’image au moyen de Svg en 132 par 118 pixels, avec à côté une colonne contenant ● LABEL · Narsil · level, la phrase en gras et le commentaire atténué. Les couleurs proviennent de STATUS_COLOR dans hooks/sprite.ts : bleu #3B8BFF pour le travail, gris pour l’arrêt, jaune #F5B400 pour « a besoin de vous », vert pour terminé et rouge pour l’erreur.
Tout texte susceptible de s’allonger est dessiné avec wrap="truncate-end" dans une boîte avec minWidth={0}, afin qu’un long nom de fichier soit coupé à l’intérieur de la bande au lieu de l’élargir.
La bande que vous voyez aujourd’hui dessine la plus importante de toutes vos conversations ouvertes, et pas seulement la conversation en cours ; le troisième guide de ce parcours explique cette partie. Quand la conversation affichée est une autre, la phrase commence par le nom de cette conversation, et le commentaire est omis.
Comment on l’a demandé à l’IA
La demande d’origine pour les états n’a pas été conservée. Les journaux de tâches publics du projet (odd/tasks/fleet-view.md et odd/tasks/animated-poses.md) commencent plus tard, et aucun des deux ne couvre la première bande.
Reconstitution à partir de l’historique des commits
D’après git log -- hooks/register.tsx hooks/words.ts dans narsil-pet :
b1187f3(2026-10-30) « feat: show Narsil above the prompt with clear states and /narsil » (afficher Narsil au-dessus du prompt avec des états clairs et /narsil). La bande, ses états et la commande/narsilarrivent ensemble dans le premier commit du module de hooks.8e29583(2026-10-30) « fix(band): keep long text from widening the desktop band » (empêcher le texte long d’élargir la bande sur le bureau). La règle deminWidth={0}et de troncature décrite plus haut vient de là.2027f06(2026-10-30) « fix(alerts): only alert when a permission dialog needs your answer » (n’alerter que lorsqu’une boîte de dialogue d’autorisation attend votre réponse). Le passage àclassic.PermissionRequest, expliqué dans le commentaire de code cité plus haut.0cfc369(2026-10-31) « refactor: move Narsil’s wording and labels out of the hooks module » (sortir les formulations et les libellés de Narsil du module de hooks). C’est à ce moment qu’est néhooks/words.ts.c73bc13(2026-10-31) « feat: let Narsil speak of herself in the first person » (laisser Narsil parler d’elle-même à la première personne), suivi de36256f9« feat: let the band, window and alerts speak in Narsil’s first person » (faire parler la bande, la fenêtre et les alertes à la première personne de Narsil).2532e7c(2026-11-02) « feat: alert as a question when a turn ends asking in the desktop app’s next-step box » (alerter sous forme de question quand un tour se termine par une question dans la case d’étape suivante de l’application de bureau).519dd73(2026-11-06) « fix: wait for background work before announcing a turn finished » (attendre le travail d’arrière-plan avant d’annoncer la fin d’un tour). Son message indique qu’un tour qui s’arrête alors que des shells, des moniteurs ou des sous-agents d’arrière-plan sont encore en cours montre désormais Narsil en train de les attendre.
Le schéma est clair même sans les prompts : une première version qui associait des événements à des états, puis une série de corrections chaque fois qu’un état mentait (une fausse alerte, une fausse fin, une question manquée).
Un prompt à utiliser
Le prompt suivant a été écrit pour ce guide à titre de suggestion. Ce n’est pas le prompt utilisé pour construire Narsil.
Construis un mod Claude Code appelé
my-petqui affiche l’état de la conversation dans la bande au-dessus du prompt (ui.rendersurAbovePrompt). Conserve une seule valeur d’état dans un atome, avec un statut (au travail, à l’arrêt, en attente, terminé, erreur) et une phrase d’une ligne. Définis-la à partir deturn.start(au travail), detool.call(au travail, avec l’outil et le nom de base du fichier dans la phrase ; en attente pourAskUserQuestionetExitPlanMode) et deturn.complete(terminé suranswer, à l’arrêt suraborted, erreur sinon). Ignore les événements dontagentIdest défini. Dessine le libellé en gras dans sa couleur et la phrase après lui, tronquée pour qu’elle n’élargisse jamais la bande. Vérifie chaque API par rapport aux types de plugin-authoring, déclare l’atome danstypes/index.d.tset ajoute un test avecclaude-code/testingqui vérifie qu’un appelReadaffiche le nom du fichier.
Le code minimal
Voici une version réduite de l’idée, écrite pour ce guide et vérifiée avec les types de Claude Code 2.1.325. Elle est adaptée de hooks/register.tsx, hooks/words.ts et hooks/sprite.ts dans narsil-pet (GPL-3.0-or-later) ; les couleurs sont celles de STATUS_COLOR de Narsil.
Le type de l’état, dans types/index.d.ts (désigné par "types" dans 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 }
}
}
Le module de hooks, 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>
)
})
}
Trois détails portent la conception. Chaque hook qui se contente d’observer se termine en appelant next(e), si bien que le comportement propre de Claude Code se poursuit. turn.complete attend d’abord next(e) et réagit au tour une fois réglé. Et le hook de rendu lit l’atome avec read, ce qui abonne le dessin : chaque update redessine la bande.
Erreurs fréquentes et comment tester
Elles proviennent du code et des correctifs de Narsil :
- Réagir aux sous-agents comme s’ils étaient la conversation principale. Les sous-agents déclenchent eux aussi
turn.start,tool.calletturn.complete, avece.agentIddéfini. Narsil vérifiee.agentId === undefinedavant de toucher à l’état principal. - Des alertes que le mode d’autorisation a déjà réglées. Détecter « a besoin de vous » à partir de
tool.checkdéclenche une alerte en mode bypass permissions. Le correctif de Narsil (2027f06) écouteclassic.PermissionRequestet l’ignore quand même si un hook de paramètres a répondu (result.decision) ou si le mode estbypassPermissions. - Un « terminé » qui ne l’est pas. Un tour peut se terminer alors que du travail d’arrière-plan continue. Narsil lit
background_tasksdansclassic.Stopavant de décider (519dd73). - Du texte qui élargit la bande. Sur le bureau, une longue phrase fait déborder la mise en page. Utilisez
minWidth={0}sur la colonne etwrap="truncate-end"sur le texte (8e29583). - Avaler le flux. Un hook
turn.stepest un générateur : s’il ne fournit pas (yield) chaque morceau issu denext(e), la réponse cesse d’atteindre l’écran. - Ignorer les sondages. Quand
e.props.hasSurveyest vrai, la bande appartient au sondage ; renvoyeznext(e).
Pour tester, claude plugin test . exécute les fichiers *.test.tsx du mod. Le fichier tests/narsil.test.tsx de Narsil est un bon modèle : il démarre une session avec $.session.start, appelle des outils avec $.tool.call, monte la bande avec $.ui.mount et cherche des textes avec find. Parmi les tests qui valent la peine d’être copiés, citons « a new conversation shows as stopped and ready, on every surface » (une nouvelle conversation s’affiche à l’arrêt et prête, sur toutes les surfaces), « a permission dialog you must answer pops up as a question » (une boîte de dialogue d’autorisation à laquelle vous devez répondre apparaît comme une question) et « an ask the mode settles by itself (bypass permissions) raises no alarm » (une demande que le mode règle seul, en bypass permissions, ne déclenche aucune alerte). Le journal de tâches de Narsil consigne que, dans le shell de l’auteur ou de l’autrice, claude plugin test . nécessitait CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (odd/tasks/fleet-view.md, L6). Exécutez aussi claude plugin validate .claude-plugin/plugin.json : cette commande vérifie les lectures et écritures de votre atome par rapport à types/index.d.ts.
Une remarque sur les surfaces : le README de Narsil indique que la bande fonctionne dans le terminal, l’application de bureau, VS Code et l’application mobile. Les types 2.1.325 documentent AbovePrompt par « Raised on the terminal, desktop and mobile surfaces only » (déclenché uniquement sur les surfaces terminal, bureau et mobile). Testez sur les surfaces qui vous importent plutôt que de vous fier à l’une ou l’autre de ces affirmations.
Pour aller plus loin
La version complète de narsil-pet ajoute beaucoup de choses autour du même noyau :
setMooddanshooks/register.tsxest le point d’entrée unique de chaque changement, et elle envoie aussi l’état au hub local (pushOverlay).headlineetLINESdanshooks/words.tscontiennent la phrase de chacune des douze humeurs et trois commentaires pour chacune ;describeCallconstruit le détail pour les fichiers, les motifs, les requêtes, les URL, les commandes et les sous-agents.- Le hook
tool.callreconnaît aussi les commandes de test (TEST_COMMAND) pour fêter les tests qui passent, et avertit des commandes irréversibles (dangerOf), sans les bloquer. startWaitingetstopWaitinginsistent une fois sur une autorisation ou une question restée en attente cinq minutes.announceparle et notifie aux moments clés (démarrage, fin, question, erreur), etsendStatusenvoie l’état au téléphone.FACEdanshooks/sprite.tsest le visage du terminal pour chaque humeur ;spritedessine l’image complète, traitée dans le guide suivant.
Pour aller plus loin : comment le fait le vrai mod
Ces fichiers font partie des mods originaux, publiés sous GPL v3. Le code cité sur cette page en provient et conserve cette licence.
Ce guide vous a aidé ?
Tous les guides sont gratuits. Si celui-ci vous a fait gagner du temps, vous pouvez m’offrir un café.
Offrez-moi un café