Session summary
How Narsil counts what a conversation has done (turns, files, commands, failures, subagents) and keeps counting when Claude Code restarts, for /narsil resumen and a summary after a pause.
What it does
/narsil resumen (“summary”) answers a question that is hard to answer from the transcript: what has this conversation actually done so far? It prints one line:
📋 Sesión de 1 h 5 min: 4 turnos (12 min de trabajo) · 3 archivos editados (a.ts, b.ts, c.ts) · 7 comandos, 1 fallo · 2 subagentes · contexto 40 %
In English: a 1 h 5 min session, 4 turns (12 minutes of work), 3 files edited, 7 commands with 1 failure, 2 subagents, the context 40 % full. The example is the one in the comment above summaryText in hooks/watch.ts.
Narsil also shows it on her own once a conversation has been quiet for 30 minutes after a turn: a natural moment to look back, for instance after a break. It shows where her tips show (guide 11): in a small window of its own on Windows and macOS, in the band elsewhere.
If you close Claude Code and later take the conversation up again, the summary goes on adding from where it was. Narsil keeps the counts of the 20 most recent conversations.
How it works inside
What is counted: the Stats type
The counts are one value, the stats atom in hooks/register.tsx, of the type Stats declared in types/index.d.ts:
| Field | What it counts | Where it is added |
|---|---|---|
startedAt |
when the conversation’s counts began | the first time, at session.start |
turns |
finished turns of the main conversation | turn.complete, any reason |
workedMs |
the time those turns took | turn.complete, from e.durationMs |
files |
the names of the files edited, up to 200 | tool.call of a writing tool |
moreFiles |
files past the first 200, counted only | the same |
commands |
shell commands run | tool.call of Bash or PowerShell |
failures |
tool calls that returned an error | after next(e) in tool.call |
agents |
subagents started | agent.spawn |
Every change goes through one function, bumpStats($, change), which applies a pure change to the atom (starting from emptyStats(now) if there is none yet) and saves it. The helpers in hooks/watch.ts keep the rules plain: emptyStats, addFile, summaryText, statsOf.
A few details decide what the numbers mean:
- The writing tools are
Edit,MultiEdit,WriteandNotebookEdit(WRITING_TOOLSinhooks/words.ts). The file is the short detail the band shows, the file’s base name, andaddFileadds a name only once. So the summary counts distinct names: twoindex.tsfiles in different folders count as one. - Subagents’ work counts too. The
tool.callhook adds files, commands and failures whatevere.agentIdsays, whileturnscounts only the main conversation’s turns, since a subagent’sturn.completereturns before that line. - Only Claude’s calls count. The hook starts with
isClaudesCall(next.origin): a call another mod makes is not part of the session’s work (guide 1). - A failed test is a failure.
failurescounts any tool result withisError, a failing test run included. - The context is not stored:
summarizereads the current percent from theusageatom of guide 7, and leaves it out when there is none.
summaryText(stats, now, contextPercent) writes the line. It names at most three files and adds “…” after them when there are more, writes “ningún archivo editado” (“no file edited”) when there are none, leaves the subagents out when there were none, and handles the plural of every count. The length is now - startedAt, written in minutes or in hours and minutes.
Why two layers of persistence
Narsil keeps the counts in two places, and each covers a different kind of restart:
$.state, the atom. The types describe it as “plain data that survives a hot reload of the plugin’s code”. A reload of the mod, which follows any turn that edits it, keeps the counts without doing anything.$.store, one key per conversation. The store is “kept between sessions and hot reloads”.loadStatsasks$.session.id(), which the types describe as “the session’s id (the transcript file’s name)”, and uses the keystats:<id>.saveStatswrites the whole value there after every change.
At session.start, loadStats fills the atom from the store only when the atom is empty. A reload keeps the atom and skips the store; a restart of Claude Code with the same conversation has an empty atom and reads it back. The comment at that point sums it up: “The stats survive a reload of the mod, and Claude Code restarting with this conversation: only a new conversation starts them.”
The key is per conversation on purpose. The XP of guide 13 is one number for the machine, added to by everyone; a summary is about one conversation, so each has its own.
If $.session.id() fails, the key is empty and nothing is stored: the counts then last only as long as the atom.
One consequence follows from keeping startedAt: the length counts from when the conversation’s counts began, so time with Claude Code closed is included. A conversation taken up the next morning says it has lasted all night.
Keeping only 20
A key per conversation grows without end, so saveStats cleans up once per load of the module (isStatsPruned). It lists the store’s keys, keeps the ones that start with stats: other than its own, and deletes the oldest until 19 are left, so 20 remain with its own. The code relies on the order: “Oldest first: the store lists its keys in the order they were set.” The types say $.store.keys() “Returns every key set, in insertion order.” Any failure to list or delete leaves every key in place.
statsOf validates what it reads: every count must be a finite number and files an array of strings, or the stored value is ignored and the conversation starts over. The comment calls it “A stored value from any version, or none”.
The summary after a pause
The heartbeat (beat, every 2 seconds) calls tickWatch, which shows the summary when all of this holds:
- a turn has finished: the cache clock of guide 8 has a start,
c.at, which the end of each turn sets; - nothing is still running in the background (
backgroundAtStop === 0); - 30 minutes (
IDLE_SUMMARY_MS) have passed sincec.at; - this turn’s pause has not been summed up yet (
summarizedFor !== c.at); - the conversation has at least one turn;
- quiet mode is off (guide 14).
Then it calls showTip($, await summarize($), 'summary'). Reusing the tip’s display means the summary gets the tip window, the band’s three lines and the floating window for free. summarizedFor makes it once per pause: a new turn sets a new c.at, and the next pause can be summed up again.
How it was asked of the AI
The original request for the session summary was not recorded.
One recorded request touches the module the summary was born in. hooks/watch.ts began with a loop alert, a reminder for waiting permissions and the summary. In odd/tasks/fleet-view.md, L1 (2026-11-06), the author asked:
“eliminariamos la alerta de bucle, no la he sentido tan util”
In English: we would remove the loop alert, I have not found it that useful. The task log records it as S9, and 21e7288 removed it. The summary and the reminder stayed.
Reconstruction from the commit history
From git log -- hooks/watch.ts in narsil-pet:
f7a494e(2026-10-30) “feat: warn about loops, insist on waiting permissions and sum the session up”. The summary, the reminder and the loop alert arrive together.21ffc2e(2026-10-31) “fix: keep a conversation’s session summary when Claude Code restarts”. Thestats:<id>keys,statsOfand the limit of 20 (KEEP_STATS) come from here. The first version lived only in the session.36256f9(2026-10-31) “feat: let the band, window and alerts speak in Narsil’s first person”.2bcc97c(2026-11-05) “feat: open the context breakdown from the usage bars and calm loop, steps and permission alerts”.519dd73(2026-11-06) “fix: wait for background work before announcing a turn finished”. ThebackgroundAtStop === 0condition of the pause summary arrives with it.21df208(2026-11-06) “fix: ignore tool calls other mods make, so Narsil no longer sticks at working”. Its message names another mod’s calls being counted as Claude’s work;isClaudesCallkeeps them out of the counts too.21e7288(2026-11-06) “refactor: drop the loop alert, the spending count and the open-conversations line”.
The first correction is the instructive one: a summary that is lost when Claude Code restarts reports a fraction of the work, which is worse than none.
A prompt you can use
The following prompt was written for this guide as a suggestion. It is not the author’s prompt.
In my Claude Code mod
my-pet, add/my-pet summary. Keep astatsatom withstartedAt,turns,workedMs,files(distinct base names, at most 200),commands,failuresandagents. Count turns and theirdurationMsinturn.completeof the main conversation; edited files fromEditandWritecalls intool.call;Bashcalls as commands; any result withisErroras a failure; subagents inagent.spawn. Change the atom only through one function that also saves it to$.storeunderstats:plus$.session.id(). Atsession.start, load it from the store only if the atom is empty, and validate what you read. Keep only the last 20 such keys. The command prints one line like “Session of 12 min: 3 turns · 2 files edited (a.ts, b.ts) · 4 commands, 1 failure”. Test withclaude-code/testing: a stored value under the session’s key is continued, and a 25th old key is deleted.
The minimal code
Written for this guide and checked against the 2.1.325 types ($.session.id, $.store.get, $.store.set, $.clock.now, $.command.register, command.run, session.start, tool.call, turn.complete, agent.spawn). It is adapted from hooks/watch.ts and hooks/register.tsx in narsil-pet (GPL-3.0-or-later). The stats atom is declared in types/index.d.ts as Stats | null, with the type below. Pruning to 20 is left out; see saveStats.
import { atom, read, update } from 'claude-code'
import type { EngineInterface, Register } from 'claude-code'
import type { Stats } from '../types'
// type Stats = { startedAt: number; turns: number; workedMs: number;
// files: string[]; commands: number; failures: number; agents: number }
const stats = atom({ plugin: 'my-pet', key: 'stats' } as const, null)
let key = ''
const empty = (startedAt: number): Stats => ({
startedAt,
turns: 0,
workedMs: 0,
files: [],
commands: 0,
failures: 0,
agents: 0,
})
const baseName = (path: string) => path.split(/[\\/]/).pop() ?? path
async function bump($: EngineInterface, change: (s: Stats) => Stats): Promise<void> {
const now = await $.clock.now()
const next = await update($, stats, (s) => change(s ?? empty(now)))
if (key) await $.store.set(key, next).catch(() => undefined)
}
function summary(s: Stats, now: number): string {
const minutes = Math.round((now - s.startedAt) / 60_000)
const files = s.files.length
? ` (${s.files.slice(0, 3).join(', ')}${s.files.length > 3 ? '…' : ''})`
: ''
return `Session of ${minutes} min: ${s.turns} turns · ${s.files.length} files edited${files} · ${s.commands} commands, ${s.failures} failures · ${s.agents} subagents`
}
export const register: Register = (on) => {
on('session.start', async ($, e, next) => {
await $.command.register({ name: 'my-pet', description: 'My pet: summary' })
key = `stats:${await $.session.id().catch(() => '')}`
if (key === 'stats:') key = ''
// A reload keeps the atom; a restart reads the store back.
if (key && !(await read($, stats))) {
const kept = await $.store.get(key).catch(() => undefined)
if (kept && typeof kept === 'object' && typeof (kept as Stats).turns === 'number')
await update($, stats, (s) => s ?? (kept as Stats))
}
if (!(await read($, stats))) await bump($, (s) => s)
return next(e)
})
on('tool.call', async ($, e, next) => {
const path = (e as { file_path?: unknown }).file_path
if ((e.tool === 'Edit' || e.tool === 'Write') && typeof path === 'string') {
const name = baseName(path)
await bump($, (s) =>
s.files.includes(name) || s.files.length >= 200 ? s : { ...s, files: [...s.files, name] },
)
}
if (e.tool === 'Bash') await bump($, (s) => ({ ...s, commands: s.commands + 1 }))
const result = await next(e)
if (result.isError) await bump($, (s) => ({ ...s, failures: s.failures + 1 }))
return result
})
on('turn.complete', async ($, e, next) => {
const result = await next(e)
if (e.agentId === undefined)
await bump($, (s) => ({ ...s, turns: s.turns + 1, workedMs: s.workedMs + e.durationMs }))
return result
})
on('agent.spawn', async ($, e, next) => {
const result = await next(e)
await bump($, (s) => ({ ...s, agents: s.agents + 1 }))
return result
})
on('command.run', { command: 'my-pet' }, async ($, e) => {
if (e.args.trim() !== 'summary') return { text: 'Usage: /my-pet summary' }
const now = await $.clock.now()
return { text: summary((await read($, stats)) ?? empty(now), now) }
})
}
update resolves to the value it wrote, so bump saves exactly what the atom holds. The check of the stored value here is a sketch; Narsil’s statsOf checks every field.
Common mistakes and how to test it
- Counting in module variables. A reload of the mod follows any turn that edits it, and a module variable starts over. Keep counts in an atom.
- One store key for all conversations. Then every conversation’s summary is everyone’s. Key by
$.session.id(). - Loading the store over a live atom. After a reload the atom is the newer value; the store may lag by one change. Load only when the atom is empty.
- A store that grows forever. One key per conversation needs a limit and a cleanup.
- Trusting what is stored. An older version may have stored another shape. Validate field by field, and start over when it does not fit.
- Summing up at the wrong moment. A pause while background work runs is not a pause. Narsil waits for it to end, and sums up each pause only once.
To test, tests/narsil.test.tsx has four tests. “/narsil resumen sums the session up, and so does a 30-minute pause after a turn” checks the exact line (“Narsil: 📋 Sesión de 0 min: 2 turnos (1 min 24 s de trabajo) · 2 archivos editados (a.ts, b.ts) · 1 comando, 0 fallos.”) and then advances the fake clock. “a conversation taken up again keeps counting its session, kept across restarts” answers session.id with a fixed id, puts earlier counts in the store under stats: and that id, and checks the next turn adds to them. “only the last 20 conversations keep their counts, and an odd stored value is ignored” starts with 25 old keys and an invalid value. “the summary names three files at most, and counts subagents and context” tests summaryText alone.
Going further
nudgeTextandNUDGE_AFTER_MSinhooks/watch.ts, the summary’s neighbours, drive the five-minute reminder of guide 10.tookinhooks/agents.tswrites the durations (“1 min 24 s”) for the summary and for the subagents.- The next and last guide of the path shows how
/narsilitself is registered and how its words,resumenamong them, are dispatched.
Going further: how the real mod does it
These files are part of the original mods, published under the GPL v3. Code quoted on this page comes from them and keeps that license.
Did this guide help?
Every guide is free. If this one saved you time, you can buy me a coffee.
Buy me a coffee