claude-code-mods: Claude Mods with their footprints printed

A Claude Mod is TypeScript that runs inside Claude Code's own process, hooking its events and calling its engine. Before any of that code runs, claude plugin validate prints the events it hooks and the $ calls it makes. Every mod here carries that printout in its README, unedited, with a five-line threat model beside it. Three plugins, one marketplace.

Install

Mods are early access. No hooks module loads unless CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 is set, and the API can change between releases. The mod-builder skill is instructions only and needs no flag. To turn it on for every session, merge { "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" } } into ~/.claude/settings.json; that loads the hooks module of every installed plugin that ships one. For one session, prefix the command: CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude.

The mods

cache-tax

mod · reach L2, drives Claude

The comeback price of a cold prompt cache, shown before you pay it, and a way to stop paying it while you are around. Claude Code's 1-hour cache dies after an hour of silence; the next message then re-writes the whole context at 80x the read rate on Fable 5.1 ($20 against $0.25 per million tokens). When the cache is cold and the context is over 50k tokens, cache-tax drops that message once with the price on screen and the resend goes through. For a window you set it keeps the cache warm with one cache-shared ping per idle stretch, and it keeps score of what cold writes cost this session. A model or effort switch, an edited CLAUDE.md or a changed tool list breaks the cache regardless of time, and the next message pays.

cache-tax: the prompt cache went cold 2h00m ago. Sending this re-writes 200,502 tokens at $20/MTok = $4.01 (a warm turn would have cost $0.05). Send it again to pay it, and keepwarm will then hold the cache for 3h00m. Or /clear and start from a note.

/keepwarm keep warm for six hours /keepwarm 90m a window of your own /keepwarm always arm six hours at every session start /keepwarm off stop /cache-tax the card: state, context, cold price, break-even, cold writes paid /cache-tax guard warn show the price and send instead of refusing once

Keep-warm: After 50 idle minutes, one tool-less fork over the session's own transcript refreshes the hour for the price of a cache read plus whatever it sends and the model says back, which a fork cannot cap. Every ping reads its usage back, and the loop stops the first time a ping reads nothing or writes at least a tenth of what it read. Receipt from a real session on Sonnet 5: 74k context, every ping read 75k tokens, wrote 0, $0.02.
Hooks: session.start, classic.SessionStart, command.run{command=keepwarm}, command.run{command=cache-tax}, prompt.submit, turn.step, turn.complete, session.compact
Calls: $.clock.after (via arm), $.clock.now, $.command.list, $.command.register, $.model.fork (via ping), $.session.usage, $.store.delete (via startWindow, stop), $.store.get, $.store.set, $.ui.log, $.ui.status
Reach: L2, drives Claude. No files, no processes, no direct network call; the only thing that leaves the machine is the ping, one request to the model API over your own session. Sees every prompt you type, every model request's timing and every answer's token counts.
Two forms: The hook form needs no flag and works in any Claude Code today: it warns with the price, refuses once with a setting, and powers a status-line row. The mod is the same tool where the API allows more.

README, validator output and threat model Row on the scoreboard

fable-pin

mod · reach L0, draws and remembers

Pins every subagent to the fable model by rewriting the model on agent.spawn, unless the spawn is a fork. One switch, remembered across sessions.

/fable-pin on /fable-pin off /fable-pin status

Hooks: session.start, command.run{command=fable-pin}, agent.spawn
Calls: $.command.register, $.store.get, $.store.set
Reach: L0. Its own store and one command, nothing else. Sees subagent spawns.

README, validator output and threat model Row on the scoreboard

mod-builder

skill · no hooks module

A skill that plans a mod's capability budget before a line is written, then validates the result and writes the threat model. Every idea must justify each process, file, network, model or UI capability it asks for; the plan states the reach level before code exists, and after the validator runs its printed calls line has to match the plan. It also explains what a Mod is, finds existing ones on the scoreboard, migrates a settings hook, reviews or debugs a mod, and brainstorms ideas against every mod already on GitHub. Both mods above were built with it.

/mod-builder "what is a Mod" "find a Mod for X" "build a Mod that ..." "review my Mod" "migrate this hook"

Reach: A skill is instructions, not process code, so it has no footprint of its own. It runs claude plugin validate and the bundled footprint.mjs on the mod it is building.

SKILL.md and its reference files

Why the footprint is printed

A mod runs with the process's reach: it can read files, run commands, reach the network and drive Claude, if it asks for those verbs. The only record of what it asks for is the $ calls in its source, and Claude Code's validator lists them before any code runs. Treating that list as a budget is the whole method here: plan the smallest surface that does the job, write the code, read the validator back, and explain any call the plan did not have. The scoreboard applies the same reading to every mod on GitHub nightly, so what a mod says about itself and what the validator says about it sit next to each other.