L’expérience et la croissance
Comment Narsil gagne de l’expérience avec les tours terminés, les tests réussis et les sous-agents terminés, monte de niveau, traverse cinq étapes et fête cela, avec une XP gardée.
Ce que ça fait
Narsil grandit avec le travail qu’elle observe. Chaque tour terminé, chaque exécution de tests réussie et chaque sous-agent qui se termine bien lui donnent des points d’expérience (XP). Avec assez d’XP, elle atteint un nouveau niveau, et à certains niveaux elle passe à une nouvelle étape de sa vie : d’un nouveau-né à un serpent de mer adulte.
De votre côté, trois choses le montrent :
- Un libellé de niveau à côté de son nom, dans la bande et dans la fenêtre flottante : « ⭐ Nivel 3 · 120/300 XP » (« niveau 3, 120 des 300 XP dont ce niveau a besoin »).
- Une célébration quand elle monte de niveau : une lueur dorée, des anneaux, des étoiles et une bannière « NIVEL 3 » sur son image, et le commentaire de la bande dit « ¡He subido al nivel 3! ⭐ » (« j’ai atteint le niveau 3 ! »). Une nouvelle étape est fêtée autrement : un éclair, des rayons de lumière, une bannière « ¡ETAPA 2! » et « ¡He crecido! » (« j’ai grandi ! »).
- Son apparence. Chacune des cinq étapes a ses propres dessins, et elle bouge différemment : le nouveau-né rebondit, léger et vif, le serpent adulte se déplace lentement et lourdement.
/narsil nivel vous dit où elle en est, l’étape, et comment elle gagne de l’XP.
L’XP est un seul nombre pour toute la machine. Elle survit à la fermeture de Claude Code, et chaque conversation ouverte s’ajoute au même total. C’est une petite boucle de récompense sans aucun effet sur le travail de Claude : elle ne change que l’apparence de Narsil.
Comment ça marche à l’intérieur
Les règles : hooks/xp.ts
Toute l’arithmétique se trouve dans hooks/xp.ts, sous forme de fonctions pures sur de simples nombres. Le fichier le dit dans son premier commentaire : « the hooks module owns the store and the events » (le module de hooks possède le store et les événements). Cette séparation rend les règles faciles à tester sans moteur.
Les gains tiennent dans une table, XP_GAIN :
| Raison | XP | Quand |
|---|---|---|
turn |
10 | un tour de la conversation principale répond |
tests |
5 | une commande de tests s’exécute sans erreur |
agent |
3 | le tour propre d’un sous-agent se termine avec answer |
Les niveaux deviennent plus difficiles de façon linéaire. levelOf commence au niveau 1 et soustrait level * 100 tant qu’il le peut : le niveau 1 demande 100 XP pour atteindre le niveau 2, le niveau 2 en demande 200 de plus, le niveau 3 en demande 300 de plus, et ainsi de suite. Il renvoie le niveau, l’XP accumulée dans ce niveau (into) et l’XP dont ce niveau a besoin (needed), ce qui est exactement ce qu’affiche le libellé.
Les étapes sont une seconde table, STAGE_FROM = [1, 5, 10, 20, 35] : le premier niveau de chaque étape. stageOf(level) compte combien de ces niveaux ont été atteints. Ainsi :
| Étape | Niveaux | XP totale pour y arriver |
|---|---|---|
| 1 (nouveau-né) | 1 à 4 | 0 |
| 2 | 5 à 9 | 1 000 |
| 3 | 10 à 19 | 4 500 |
| 4 | 20 à 34 | 19 000 |
| 5 | 35 et au-delà | 59 500 |
Les totaux découlent de la règle : atteindre le niveau L demande 100 × (1 + 2 + … + (L − 1)) XP. À 10 XP par tour, le nouveau-né passe à l’étape 2 après une centaine de tours terminés environ, et l’étape 5 est encore loin. Le README énonce les mêmes règles en espagnol.
xpOf lit une valeur stockée « from any version, or none » (de n’importe quelle version, ou aucune) : tout ce qui n’est pas un nombre fini positif compte comme 0, et une fraction est arrondie à l’entier inférieur. Un store abîmé ou absent fait donc repartir Narsil de zéro au lieu de casser la bande.
D’où vient l’XP
gainXp($, reason) dans hooks/register.tsx est appelé depuis quatre endroits, répartis sur trois événements :
turn.complete, conversation principale, quand le tour se termine avecanswer. Deux branches l’appellent : la fin normale (« He terminado ») et une fin qui pose une question dans la boîte d’étape suivante de l’application de bureau. Un tour qui se termine alors qu’un travail d’arrière-plan tourne encore ne gagne pas encore d’XP : c’est le tour qui réveille la session quand ce travail rend compte qui se termine, et qui la gagne. Un tour que vous arrêtez (aborted) ou qui échoue ne gagne rien.tool.call, quand la commande correspond àTEST_COMMAND(danshooks/words.ts:npm test,pnpm test,vitest,pytest,cargo test,claude plugin testet d’autres) et que le résultat n’a pas deisError. Cette vérification ne regarde pase.agentId, si bien que les tests réussis d’un sous-agent comptent aussi.endAgent, appelé depuisturn.completequande.agentIdest défini et que la raison du sous-agent estanswer.
Le test passing tests and finished subagents earn experience; failures and stopped turns do not dans tests/narsil.test.tsx fixe tout cela.
Pourquoi elle vit dans $.store, et pourquoi elle est relue
Narsil garde deux copies de l’XP :
$.store, sous la cléxp. Les types décrivent le store comme « This plugin’s own key-value store, kept between sessions and hot reloads » (le store clé-valeur propre à ce plugin, conservé entre les sessions et les rechargements à chaud), un fichier JSON propre au plugin sous le répertoire de configuration de Claude Code. C’est ce qui permet à l’XP de survivre à une session.- L’atome
xp($.state), que la bande et la fenêtre flottante lisent pendant qu’elles dessinent, si bien qu’un changement les redessine.
Au session.start, Narsil copie la valeur stockée dans l’atome. Ensuite, chaque gain fait ceci :
const before = xpOf(await $.store.get(XP_KEY).catch(() => read($, xp)))
const after = before + XP_GAIN[reason]
await $.store.set(XP_KEY, after).catch(() => undefined)
await update($, xp, () => after)
Le commentaire au-dessus donne la raison de lire d’abord le store au lieu de se fier à l’atome : « another open conversation may have added to it since » (une autre conversation ouverte a pu y ajouter depuis). Le store est partagé par toutes les conversations du plugin, alors que chaque conversation a son propre atome. Ajouter à l’atome écraserait les gains qu’une autre fenêtre a faits depuis le démarrage de celle-ci. Le test another conversation’s experience is added to, never overwritten met le store à 50 dans le dos de la conversation et attend 60 après un tour.
Relire réduit la fenêtre pendant laquelle des gains peuvent se perdre ; ce n’est pas un verrou. Deux conversations qui gagnent de l’XP au même instant peuvent encore lire toutes les deux le même before.
Si le store échoue, le gain atteint quand même l’atome (.catch(() => read($, xp)) et .catch(() => undefined)), si bien que la bande continue de compter pendant cette session.
Les célébrations : l’atome milestone
Quand after franchit un niveau, gainXp compare les étapes avant et après et écrit l’atome milestone : { kind: 'level' | 'grew', level, stage, at }. Son type, (Milestone & { at: number }) | null, est déclaré dans types/index.d.ts. Il fait aussi ceci :
- il écrit une ligne de journal avec
$.ui.log: « 🌊 Narsil ha crecido: nivel 5, etapa 2 de 5. » ou « ⭐ Narsil ha subido al nivel 3. » ; - il remplace son commentaire dans la bande via
setMood, en gardant son humeur et son détail actuels.
Le dessin lit le jalon. sprite(mood, stage, milestone) dans hooks/sprite.ts ajoute :
- pour un niveau,
behinddessine une lueur radiale dorée, etcelebrationdessine deux anneaux qui s’élargissent, sept étoiles et une bannièreNIVEL <n>; - pour une étape, un éclair blanc, cinq étincelles, douze rayons de lumière et une bannière
¡ETAPA <n>!, avec l’image enveloppée dans une animationevolvequi la fait passer de la moitié de sa taille à sa nouvelle forme.
Pendant qu’un jalon s’affiche, le petit badge d’état près de sa tête est omis, pour que les deux ne se disputent pas le même espace.
Le battement (beat, toutes les 2 secondes) efface le jalon une fois MILESTONE_MS écoulé : 6 secondes pour un niveau, 9 pour une étape. Un minuteur par célébration aurait été plus simple à écrire, mais le battement existe déjà, et un minuteur $.clock est perdu lors d’un rechargement du mod.
Dans la bande, la célébration n’est dessinée que lorsque la conversation que montre Narsil est celle-ci (isOwnTop) : quand une autre conversation est plus importante, l’image lui appartient.
Ce que change l’étape
stageOf(levelOf(xp).level) est calculé partout où une image est produite :
- Le dessin.
artdanshooks/sprite.tschoisit la pose dessinée pour cette étape et ce thème, en se rabattant sur la pose de base de l’étape, puis sur une étape antérieure, quand l’une manque. Les boucles animées de chaque étape viennent de la tâche consignée dansodd/tasks/animated-poses.md; le deuxième guide de ce parcours traite du dessin. - Le mouvement.
STAGE_MOTIONrègle l’amplitude et la vitesse de ses mouvements : amplitude 1.15 et tempo 0.9 pour le nouveau-né, jusqu’à 0.6 et 1.4 pour l’étape 5. - Tout ce qui est hors de la bande. La fenêtre du conseil reçoit
NARSIL_STAGE; les alertes du téléphone utilisentphoneIcon(kind, stage), un PNG d’elle à cette étape tiré du dépôt ; le sujet-estadoenvoie le libelléxpet l’URLart(guide 15).
Comment on l’a demandé à l’IA
La demande d’origine pour l’expérience et les niveaux n’a pas été consignée. Les journaux de tâches publics du projet commencent plus tard.
Une demande ultérieure touche aux étapes : dans odd/tasks/animated-poses.md, L4 (2026-11-15), après la première boucle animée, l’auteur ou l’autrice a répondu :
“si me agrada, vamos a cambiar todos”
Traduction en français : oui, ça me plaît, changeons-les toutes. Le journal de tâches en fait S6 : chaque pose « at every stage 1-5, light and dark: 60 loops » (à chaque étape 1-5, clair et sombre : 60 boucles).
Reconstitution à partir de l’historique des commits
À partir de git log -- hooks/xp.ts et des commits liés :
8913cdd(2026-10-30) « feat: let Narsil earn experience and levels kept across sessions » (permettre à Narsil de gagner de l’expérience et des niveaux conservés d’une session à l’autre). L’XP, les niveaux et le store arrivent ensemble.9bfa039(2026-10-30) « feat: let Narsil grow through five stages as she levels up » (permettre à Narsil de traverser cinq étapes à mesure qu’elle monte de niveau). Le même jour, les étapes.7a964d1(2026-10-30) « feat: draw Narsil as a hatchling at stage 1 and split the art per stage » (dessiner Narsil en nouveau-né à l’étape 1 et répartir les dessins par étape), suivi le 2026-10-31 d’un commit par étape et par thème (6b96e08,e029cf0,ff02847,6a1ceb3,4055242,b7361a0,5ef599a,eed13b0).2cf7133(2026-10-31) « feat: celebrate a new level and a new stage with their own animations » (fêter un nouveau niveau et une nouvelle étape avec leurs propres animations). L’atomemilestoneet les deux célébrations.fcd68c7(2026-10-31) « feat: move Narsil by her stage, with a shadow, splashes, a softer tremble and cheap glows » (faire bouger Narsil selon son étape, avec une ombre, des éclaboussures, un tremblement plus doux et des lueurs peu coûteuses).STAGE_MOTION.- Du 2026-11-15 au 2026-11-16, les boucles animées de chaque étape (
2f08c55à673fc9f), la tâche citée plus haut.
L’ordre est parlant : d’abord les nombres, puis les étapes qui rendent les nombres visibles, puis une image par étape, puis les célébrations, puis le mouvement. Chaque pas rend la récompense plus facile à remarquer.
Un prompt à utiliser
Le prompt suivant a été écrit pour ce guide à titre de suggestion. Ce n’est pas le prompt de l’auteur ou de l’autrice.
Dans mon mod Claude Code
my-pet, donne de l’expérience à la mascotte. Mets les règles dans un module purhooks/xp.ts: 10 XP par tour terminé de la conversation principale (turn.completeavecreason === 'answer'et sansagentId), 5 quand une commande de tests (npm test,pnpm test,vitest,pytest) revient sansisErrordanstool.call, 3 quand leturn.completed’un sous-agent se termine avecanswer. Le niveau 1 demande 100 XP, chaque niveau suivant 100 de plus que le précédent ; les étapes commencent aux niveaux 1, 5, 10, 20 et 35. Garde le total dans$.storesousxppour qu’il survive aux sessions, et avant chaque gain relis le store, puisque d’autres conversations y ajoutent. Reflète-le dans un atome pour le dessin. À un nouveau niveau, écris un atomemilestoneavec l’heure, affiche « Level N » dans la bandeAbovePromptpendant 6 secondes (9 pour une nouvelle étape) et journalise-le avec$.ui.log. Teste avecclaude-code/testing: un tour à 95 XP affiche le niveau 2, et un store modifié dans le dos de la conversation est complété, pas écrasé.
Le code minimal
Écrit pour ce guide et vérifié par rapport aux types 2.1.325 ($.store.get, $.store.set, $.clock.now, $.ui.log, session.start, tool.call, turn.complete, ui.render). Il est adapté de hooks/xp.ts et de hooks/register.tsx dans narsil-pet (GPL-3.0-or-later). Les atomes sont déclarés dans types/index.d.ts comme dans le premier guide : xp: number et milestone: { kind: 'level' | 'grew'; level: number; at: number } | null.
import { atom, read, update } from 'claude-code'
import type { EngineInterface, Register } from 'claude-code'
const GAIN = { turn: 10, tests: 5, agent: 3 } as const
const STAGE_FROM = [1, 5, 10, 20, 35]
const SHOWN_MS = { level: 6000, grew: 9000 } as const
const TESTS = /\b(?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?test|vitest|jest|pytest)\b/
const xp = atom({ plugin: 'my-pet', key: 'xp' } as const, 0)
const milestone = atom({ plugin: 'my-pet', key: 'milestone' } as const, null)
function levelOf(total: number) {
let level = 1
let left = Math.max(0, Math.floor(total))
while (left >= level * 100) {
left -= level * 100
level += 1
}
return { level, into: left, needed: level * 100 }
}
const stageOf = (level: number) => STAGE_FROM.filter((from) => level >= from).length || 1
const xpOf = (v: unknown) =>
typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0
async function gain($: EngineInterface, reason: keyof typeof GAIN): Promise<void> {
// Read the store again: another conversation may have added to it.
const before = xpOf(await $.store.get('xp').catch(() => read($, xp)))
const after = before + GAIN[reason]
await $.store.set('xp', after).catch(() => undefined)
await update($, xp, () => after)
const was = levelOf(before).level
const level = levelOf(after).level
if (level === was) return
const kind = stageOf(level) > stageOf(was) ? ('grew' as const) : ('level' as const)
const at = await $.clock.now()
await update($, milestone, () => ({ kind, level, at }))
$.ui.log(kind === 'grew' ? `My pet has grown: level ${level}` : `My pet reached level ${level}`)
}
export const register: Register = (on) => {
on('session.start', async ($, e, next) => {
const stored = xpOf(await $.store.get('xp').catch(() => 0))
await update($, xp, () => stored)
return next(e)
})
on('tool.call', async ($, e, next) => {
const command = (e as { command?: unknown }).command
const result = await next(e)
if (typeof command === 'string' && TESTS.test(command) && !result.isError)
await gain($, 'tests')
return result
})
on('turn.complete', async ($, e, next) => {
const result = await next(e)
if (e.reason === 'answer') await gain($, e.agentId === undefined ? 'turn' : 'agent')
return result
})
on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
if (e.props.hasSurvey) return next(e)
const { level, into, needed } = levelOf(await read($, xp))
const shown = await read($, milestone)
const isFresh = shown !== null && (await $.clock.now()) - shown.at < SHOWN_MS[shown.kind]
const { Box, Text } = $.ui.resolve(e)
return (
<Box flexDirection="row" gap={1} minWidth={0}>
<Text dimColor>{`⭐ Level ${level} · ${into}/${needed} XP · stage ${stageOf(level)}`}</Text>
{isFresh ? (
<Text bold color="#F5B400">
{shown.kind === 'grew' ? 'I have grown!' : 'Level up!'}
</Text>
) : null}
</Box>
)
})
}
Deux simplifications par rapport à Narsil. La bande vérifie l’âge du jalon au moment de dessiner, si bien que la célébration part au premier redessin qui suit son délai ; Narsil efface l’atome lors de son battement, qui redessine à l’heure. Et cette version compte chaque tour de sous-agent qui répond, alors que Narsil ne compte un sous-agent qu’une fois, grâce à son propre registre des sous-agents en cours.
Erreurs fréquentes et comment tester
- Garder l’XP seulement dans un atome.
$.statesurvit à un rechargement du mod, pas à une nouvelle session. Tout ce qui doit durer va dans$.store. - Réécrire la valeur de l’atome dans le store. Avec deux conversations ouvertes, chaque atome est en retard sur les gains de l’autre. Lisez le store, ajoutez, écrivez.
- Se fier à une valeur stockée. Un store modifié à la main, ou écrit par une version plus ancienne, peut contenir n’importe quoi. Validez-la (
xpOf) et revenez à zéro par défaut. - Récompenser l’échec. N’accordez le tour que sur
answer, et les tests que sansisError; un tour interrompu ne gagne rien. - Célébrer pour toujours. Un jalon a besoin d’une heure de fin et de quelque chose qui redessine quand elle est passée.
- Des niveaux qui n’arrivent jamais. Vérifiez votre courbe avec des chiffres avant de la publier. Avec celle de Narsil, l’étape 5 demande 59 500 XP, soit plusieurs milliers de tours.
Pour tester, les tests de tests/narsil.test.tsx démarrent le mod avec un store défini à l’avance et le relisent. À lire : « Narsil keeps her experience across sessions, and celebrates a new level » (Narsil garde son expérience d’une session à l’autre, et fête un nouveau niveau ; 95 XP plus un tour affichent « ⭐ Nivel 2 · 5/200 XP » et « ¡He subido al nivel 2! ⭐ »), « Narsil grows at levels 5, 10, 20 and 35, and says so » (Narsil grandit aux niveaux 5, 10, 20 et 35, et le dit), « a new level plays its own celebration for a while, in the band and the window » (un nouveau niveau joue sa propre célébration pendant un moment, dans la bande et la fenêtre) et « levels need 100, 200, 300 XP more each, and odd stored values count as none » (chaque niveau demande 100, 200, 300 XP de plus, et des valeurs stockées étranges comptent comme aucune). « the celebrations stay within the Svg size limit at every stage » (les célébrations restent dans la limite de taille de Svg à chaque étape) protège quelque chose de facile à oublier : une célébration s’ajoute à une image qui a déjà sa limite de taille.
Pour aller plus loin
xpLabeldanshooks/xp.tsest le seul endroit où le libellé est écrit, si bien que la bande, la fenêtre flottante et l’état du téléphone disent la même chose.banner,behindetcelebrationdanshooks/sprite.tsdessinent les célébrations en SVG par-dessus l’image.artUrldanshooks/phone.tsconstruit l’adresse de son image à chaque étape pour le téléphone, telle que le dépôt la publie sousassets/.- Le guide suivant, le mode discret, montre comment Narsil se tait sans perdre ce qui compte ; une célébration fait partie de ce qui s’affiche encore, puisqu’elle n’est que dessinée.
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é