Claude Code added mods, so I made three: kaizen, refine, and safety-eval. They were already running before I could explain the chain.

You can already steer Claude Code with settings, permission rules, slash commands, skills, and a status line. A mod is code sitting on that path. It can change an event before Claude Code acts, refuse the event, or paint its own UI.

Mine paint a band above the prompt, not a log I have to go find. A markdown rule is easy for the model to ignore. A settings hook starts a shell command, takes JSON in, prints JSON out, and then it’s gone. A mod stays up for the session, so the next prompt can see what the last one did.

How a mod works

A mod is a plugin with one module in it. That file can’t touch the DOM, and it can’t import Node.

$ is the only handle it gets. Through $ it can reach the UI, files, a process, and the model. e is this event. next hands e to the plugin after yours. Claude Code is the last step.

The { tool: 'Edit' } object is a filter on this one event. Drop it and the hook sees every tool. The prompt is a different event, prompt.submit. So is the session, a slash command, and the moment the UI is drawn. You subscribe to those by name.

on('tool.call', { tool: 'Edit' }, async ($, e, next) => {
  return next(e)
})

Call next and then look at what came back. That’s observe.

Call next with a different event and Claude Code gets your version. That’s a rewrite.

Return without calling next and the chain stops. That’s an answer, and Claude Code never gets the event. On a tool, that return is often { deny }.

A mod sits in a chain of hooksAn event reaches your mod, then other plugins, then Claude Code, each step by calling next. The result is passed back along dashed arrows. A curved arrow leaves your mod and stops, which is answering the event without calling next. A note says observe means call next and then look, and rewrite means call next with a changed event.eventthe datayour mod$, e, nextnext(e)resultother pluginsalso a hooknext(e)resultClaude Coderuns itanswerreturn, and the chain stopsobservecall next, then lookrewritenext with a changed event
Solid arrows are next(e). The dashes bring the result back. The rose curve means the hook returned and Claude Code was skipped.

kaizen

kaizen is the rewrite, on prompt.submit. The rewrite is not my sentence.

If the first 300 characters look like a correction, “no”, “I meant”, “don’t”, and a pile of cousins, and the last message was the assistant, it asks a model for one short rule. The band shows that rule and three buttons: Keep for this repo, Keep everywhere, Discard. Nothing is saved until I press one.

Later, a saved rule can match the words I typed. It can also match the files from the last turn. kaizen watches Edit and Write only to remember those paths. When a rule matches, the wording stays mine. It attaches up to three rules as context, extra notes on the event, and calls next with that. The model sees the notes. The prompt is still what I wrote.

refine

refine is the answer, also on prompt.submit. A slash command goes through. So does anything under 15 words, and a short follow-up. raw: goes through too, after that prefix is stripped.

Everything else hits a desk sergeant. A specific tip gets the squad. “fix the thing” at 1am does not.

I haven’t wired Jev, so the skim is local and free. It looks for vague words, whether I named a file, and whether there is a verb. 65 or above means clear enough, and the prompt is sent.

Jev is the optional analyst. One call to jev-1.13.0 on typesafe.ai, three seconds, a score from 0 to 1 for how badly the prompt needs work. Under 0.75 it was already clear, so it would be sent. If that call times out, the prompt goes through anyway.

Miss the gate and the expensive rewrite runs. That reply scores what I typed out of 100. It is not the same ruler as the 65. At 85 or above, the original was fine, so that is what gets sent. Under 85, refine fills the box with a sharper prompt, or with numbered questions if that’s all the reply had, and returns { drop }. next never runs, so this submit never becomes a turn. The squad never hears the vague one.

How refine decides whether a prompt is sentA prompt enters a cheap gate. It is sent if Jev, a needs-work score, is under 0.75, or if a local clarity score is 65 or above. Below that line a rewrite runs. If that reply scores the original at 85 or above, it is sent. Under 85 the submit is dropped and the prompt box is filled.promptcheap gateclear if Jev under 0.75or local score 65+passessentbelow the linerewriteexpensive call85 or abovereply’s score, send itunder 85drop, fill the box
Pass the cheap gate and the prompt is sent. Jev under 0.75 means it was already clear. The local score runs the other way: 65 or above. Fail the gate and the rewrite runs. Under 85 on that reply, refine drops the submit.

safety-eval

safety-eval is the observe. It keeps that { tool: 'Edit' } filter, and a matching one for Write, so those are the only tools it watches.

It calls next first, so the write finishes. Then it looks. A deleted function or class that some other file still mentions gets a flag. If a .test or .spec file sits next to the edit, the band says to run it. A brand new file in a directory where nothing else has that extension gets a flag too.

Lint stays off unless I run /safety-eval lint on. The checks wait eight seconds between runs, so a burst of edits doesn’t launch grep eight times. If something fails, it shows in the band. The file is already written. It doesn’t block.

I haven’t earned the right to trust these yet

Mods are new, and most of them haven’t been audited. Mine included. kaizen and refine call a model, so a loose trigger spends tokens on prompts that were fine. safety-eval spends grep and git, not tokens. I haven’t measured how often the score is wrong. They’re useful on the work I actually do, so I’m keeping them while I find out.

References