Your own status pet
Narsil was built by talking to Claude Code. Each guide in this path explains one of its features: what it does for the person using it, the hooks and state behind it, the design decisions, and the request that started it.
Where the original request was recorded, the guide quotes it word for word. Where it was not, the guide says so and reconstructs it from the commit history.
The guides
- 1States at a glanceHow Narsil turns the session's events into five states, one sentence about the current step and a short comment, drawn in the band above the prompt.
- 2Drawing and animationsHow Narsil is drawn: one pose per state, light and dark art in one SVG, animated loops made from AI videos, and the 131072-character limit of the band.
- 3Every conversation in one placeHow Narsil gathers the state of every open conversation in a local hub, ranks them error first, pages them four at a time and forgets the silent ones after an hour.
- 4Tasks and subagentsHow Narsil rebuilds a conversation's task list from TodoWrite, TaskCreate, TaskUpdate and the desktop app's plan, and shows each subagent as a chip with its type, model and time.
- 5The floating windowHow Narsil shows an always-on-top window when Claude is minimized or something waits for you, and why its local server listens only on 127.0.0.1 behind a page key and a mod token.
- 6Voice and alertsHow Narsil picks a random phrase for each moment, says it aloud with Windows' or macOS's own voices, and tells you through the floating window or a system notification.
- 7Context and limitsHow Narsil draws each conversation's context bar, estimates when it fills at the pace of the last 15 minutes, suggests /compact once, and shows the 5-hour and weekly limits.
- 8The cache clockHow Narsil counts down the prompt cache from the start of the last request, 60 minutes on a subscription and 5 with an API key, and why the next turn costs more once it goes cold.
- 9Reactions to commandsHow Narsil reads the shell commands Claude runs: she cheers passing tests, notices failing ones, and warns about commands that cannot be undone without ever blocking them.
- 10Permissions that waitHow Narsil insists once when a permission, a question or a plan has waited five minutes for you, and why it checks on a heartbeat instead of setting a timer.
- 11Tips with HaikuHow Narsil asks Haiku for one short tip about the work in progress: what context she sends, the exact prompt, how often she speaks up, the deep mode and the tip window.
- 12Next stepsHow Narsil proposes up to three next steps 15 minutes after a turn, from the project's commits, its uncommitted changes and its pending tasks, and puts the one you pick in the prompt.
- 13Experience and growthHow Narsil earns experience from finished turns, passing tests and finished subagents, levels up, grows through five stages and celebrates, with XP kept across sessions.
- 14Quiet modeHow /narsil discreto silences Narsil without losing the alerts that matter: what stops, what still gets through, and why the line is drawn at "she needs you".
- 15Alerts on your phone and watchHow /narsil movil sends what needs you to a private ntfy.sh topic while you write from away, with a daily limit, a silent state topic, an optional key that seals the content, and Web Push.
- 16Session summaryHow 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.
- 17Your own /commandsHow /narsil is registered as one slash command with many subcommands, how its words are dispatched, how the bare command doubles as help, and how to test it.