Write a mod for this brain

A mod is code that runs inside Claude Code with the person's permissions, on every surface they use. Doing it well means drawing something useful everywhere, reading without side effects, and failing where the person can see it, never silently and never by breaking the session.

Where this sits

Runs after: brain-retro

Hand to next: brain-sync · brain-write-script

Reserved output: writing .claude/mods/<prefix>-*/** needs this skill to have run.

Call it directly when: the person asks for something Claude Code should show or do by itself (a pane, a band, a command, a guard), or the gate refused a write under .claude/mods/; step 1 still applies.

Sequence

1. Does it earn a mod? A mod draws in Claude Code or reacts to its events. Instructions are a skill (brain-write-skill), a query is a script (brain-write-script), a fact is a practice. Nothing a mod does may be the only way something happens: the skill gate stays the enforcer, and what a pane shows can also be had from a command or a script. Run _meta/brain mods ready: a Claude Code older than 2.1.287, or the desktop app in a WSL session, runs no mods; say so.
2. Shape it with the person, in their words: where it shows (pane, band, status line, toast, command reply, a tool-call hook), what it reads and from where, what it writes (by default nothing), when it reads (start, a command, a button, a timer), and whether everyone who clones the brain gets it or it is opt-in. Read _meta/modkit/README.md for the kit, its pieces and the surface facts.
3. Start or open it. New: _meta/brain mods new <name> --dry-run, then without --dry-run; it writes .claude/mods/<prefix>-<name>/ from the starter, copies the kit and makes the link .claude/skills/<prefix>-<name>. Existing: read its README.md and hooks/register.tsx first.
4. Write it. Replace hooks/health.ts with the mod's own data source and delete the starter's parts it does not need. Grep the types the engine lays in .claude-plugin/types/ for the event or method at hand; they are this build's contract. A script the mod runs goes in ./scripts/ through brain-write-script, and the mod calls it with an argument list.
5. Test it. tests/<prefix>-<name>.test.ts: each hook on terminal and desktop at least, the empty, failed and nothing-to-show states, that a forged button press does nothing, and that a read-only mod writes nothing. Run _meta/brain mods check <name> until both steps pass.
6. See it. The session reloads a linked mod when its files are saved; a terminal session can load one with claude --plugin-dir .claude/mods/<prefix>-<name>. Ask the person to look at it in the app they use, in the light and the dark theme. A dim transcript line naming the mod is a hook that failed: read it, fix the cause, look again.
7. Record and hand on. Fill the README table: what it shows, what it reads, what it writes, which surfaces draw it, how to turn it off. An opt-in mod sets "defaultEnabled": false in its plugin.json, and the README says how to turn it on. _meta/brain lint reports nothing about it; then hand to brain-sync.

Rules a mod keeps

• Read-only unless the person asked. A button that asks Claude for something fills the prompt ($.prompt.fill) for the person to send; it never submits and never runs a write itself. An act that changes something outside the mod shows what it will do and asks first (Confirm).
• No secrets. A mod never reads .env, never puts a key in its state, a log line, a toast or a drawing, and never sends one anywhere. A system that needs a key is reached through a script that loads it, or _meta/brain secret run.
• Every press is validated. A button carries a small act ({ do: 'refresh' }) that one function checks before anything runs: never free text, a path, a URL or a command.
• Fail quiet and visible. No hook throws: a failed read keeps the last good one and shows a Failed line with Try again. A hook that guards (refuses a tool call, a prompt) gets a .catch that refuses too, so a broken guard fails closed.
• Cheap where it runs often. ui.render only reads state; process, file and network work runs in the background from a command, a button, session.start or a throttled timer, with a time limit. Hooks on tool.call and prompt.submit observe and pass on unless guarding is the point.
• Every surface gets something. Text where an element is missing, a command whose reply is text, and nothing drawn in the band when there is nothing to say (return next(e)).
• State lives in $.state, declared in types/index.d.ts; change a value's shape tag when its fields change.
• Never edit hooks/kit/. _meta/brain mods sync replaces it. A piece the kit lacks is built in the mod's own files, or proposed for the kit through brain-upstream.

In the template

When brain.json role is template, mods are the kit itself: _meta/modkit/gallery/ (the kit and its gallery) and _meta/modkit/starter/. Change them here, run claude plugin test _meta/modkit/gallery and the template's tests, and add a changelog entry. Steps 3 and 7's link and lint do not apply.

Do not

• Do not install a mod in the person's user settings or CLAUDE_CODE_PLUGIN_DIRS: it would load in every session everywhere. A brain's mods load through their link, in the brain's sessions.
• Do not let a mod block what the skill gate or a settings hook already decides; it adds a view, not a second set of rules.
• Do not open a pane at session start unasked; open it on a command, a button, or work that needs it.
• Do not edit through the link (.claude/skills/<prefix>-<name>/…) or make it by hand: write under .claude/mods/, and let mods new or mods link make the link. The gate reads a write through the link as a skill write too.

Done when

• .claude/mods/<prefix>-<name>/ holds the manifest, hooks/hooks.json, the hooks module, the kit copy, types/index.d.ts, tests and a README whose table is filled in.
• _meta/brain mods check <name> passes validate and test, and _meta/brain lint reports nothing about the mod.
• .claude/skills/<prefix>-<name> links to it, and the person has seen it work in their app.
• It writes nothing the person did not ask for, and no secret appears in its code, state or output.
• Handed to brain-sync.