Claude Code Mods vs Hooks: Which One Should You Use?

A mod is a plugin with a JavaScript or TypeScript module that registers event handlers. Claude Code calls them in its own process when something happens: a tool call, a submitted prompt, a request to the model, or a piece of the interface being drawn. Each handler gets ($, e, next). Call next(e) to let things continue, pass a modified copy to rewrite the event, or return without calling it to answer the event yourself.

If you've written Express or Koa middleware, you already know the model. Handlers for one event form a chain, the first mod is the outermost, and the end of the chain is Claude Code's own behavior. Anthropic's mods overview even renames things to keep them apart: inside the mods docs, "hook" means a mod's handler, and the old kind is a "settings hook". I'll use the same words here.

The short version: settings hooks talk to Claude Code through stdin, stdout and exit codes; mods are code Claude Code calls directly. Everything else in this post falls out of that.

The UI column is the headline feature, but for most of my setups it's the least important row. The ones that matter are rewriting and ordering, because that's where a guard either holds or doesn't.

The test: stop Claude from reading or cat-ing .env files, a rule I already run as a PreToolUsehook on the Mac mini that hosts my agents. Here's the whole mod, in hooks/register.ts:

import type { Register } from 'claude-code'

const ENV = /(^|[\s\/'"])\.env(\.[a-z]+)?\b/
let blocked = 0

export const register: Register = on => {
  on('tool.call', { tool: ['Read', 'Edit', 'Write'] }, ($, e, next) => {
    if (!ENV.test(e.file_path)) return next(e)
    blocked += 1
    $.ui.status(`env-guard: ${blocked} blocked`)
    return { deny: `env-guard: ${e.file_path} holds secrets. Ask the user for the specific value instead.` }
  })
  on('tool.call', { tool: 'Bash' }, ($, e, next) => {
    if (!ENV.test(e.command)) return next(e)
    blocked += 1
    $.ui.status(`env-guard: ${blocked} blocked`)
    return { deny: 'env-guard: shell access to .env files is blocked. Ask the user for the specific value instead.' }
  })
}

Plus two tiny JSON files: .claude-plugin/plugin.json with a name and version, and hooks/hooks.json containing { "modules": ["./register.ts"] }. The settings-hook version is a 9-line Python script that reads the event JSON from stdin, checks tool_input.file_path or tool_input.command, and exits 2 with the reason on stderr.

Before running anything, I validated the mod:

$ claude plugin validate ./env-guard
  ❯ ./register.ts hooks: tool.call{tool=Read|Edit|Write}, tool.call{tool=Bash}
  ❯ ./register.ts calls: $.ui.status
✔ Validation passed with warnings

That hooks: / calls: output is the best thing about the design. A mod can only touch the outside world through $, so the validator can list every file read, process and network call a mod makes without running it. You can't get that from a shell script.

All runs were claude -p --model haiku --permission-mode bypassPermissions in a scratch project with a fake .env.

• Mod alone, "read .env and tell me SECRET_TOKEN":denied. Claude quoted the deny text word for word and didn't print the value. The whole run took 8.1 seconds.
• Settings hook alone, "run cat .env":denied with the hook's stderr message.
• Both installed, "run cat .env": Claude quoted the mod'smessage, not the hook's.

That last result is the one to remember. A mod's tool.call hook runs before the PreToolUse hooks in your user, project and plugin settings. When the mod denies without calling next, those hooks never run at all. The events docs confirm it: only PreToolUse hooks from managed settings run before mods, and their block is final.

Also note bypass mode didn't matter. Both guards held under bypassPermissions, which is how most of my unattended runs are configured. If you run agents headless the way I described in my sandbox and permissions setup, either one works as a backstop.

One honest footnote: my global CLI was 2.1.286, one release before the documented minimum, and the mod still loaded through --plugin-dir. That's the early-access build. Don't depend on it; update to 2.1.287 or later.

Yes, but it rarely matters. I timed each hook script 50 times with a sample event on stdin, which is roughly what Claude Code pays to spawn it on every matching tool call:

• Python script: median 18.4 ms, p95 25.5 ms
• Bash script: median 4.9 ms, p95 5.5 ms
• Mod:no process spawn; it's a function call

Against a model turn measured in seconds, 18 ms per tool call is noise. Where it adds up is a hook with a broad matcher (every tool, every call) inside a long agent session with hundreds of calls, or a hook that does real work like a network check. Speed is a tiebreaker, not a reason to rewrite working hooks.

Pick a mod when the job needs one of these, because a settings hook can't do them:

• Live UI. A pane charting context use, a band above the prompt showing CI status, a count beside the spinner.
• Hold a call and ask. $.ui.askpauses a risky command and puts buttons in front of you. Anthropic's blast-radius sample does this for rm -rf and force pushes.
• Route a request. A turn.step hook can send one request to a different model, or log cache reads per request. That pairs well with the cost work in subagent token costs.
• Instant commands. A /deploy-status that runs your function immediately, no turn, no tokens.
• Decisions based on live state. tool.check can deny git push only while you're on main.

Most of the time, honestly. I'm keeping my existing hooks from the production hooks setup as they are. A settings hook wins when:

• You already have the script. A linter, a formatter, a Slack webhook. Wrapping it in TypeScript buys nothing.
• It isn't JavaScript. Python or Go tooling stays a hook.
• It must reach the VS Code panel or a cloud session without a plugin install. Mods ship as plugins; a hook is one line in a settings file you probably already sync.
• You want the smallest trust surface.A hook sees one event's JSON. A mod sees the whole session.

Mods are not sandboxed.They run as you, can read your env vars and settings, see every prompt, rewrite tool calls, and approve a call before you're asked. A tool.check hook can even approve something one of your own non-managed PreToolUsehooks blocked. Turning on Claude Code's sandbox only isolates Claude's Bash commands, not processes a mod starts.

Three rules I'm applying:

1. Run claude plugin validate on every third-party mod and read the calls: line. A "spinner theme" that calls $.fetch gets deleted.
2. Make guards fail closed. A hook that throws or times out is skipped and the chain continues, so the command runs. Attach a .catch that returns a deny.
3. Put real policy in managed settings. On Team and Enterprise, the built-in sec-default mod loads first and stops user mods from overriding deny rules. For a client team, ship guards through a private plugin marketplace and pin them with prependPlugins.

Default to a settings hook. Graduate to a mod when you want to see something, rewrite something, or hold state. And if you care about guards, remember the order: a mod you install runs ahead of your project hooks, so one bad mod can make those hooks irrelevant. The same logic I used in skills vs MCP applies here: pick the smallest thing that does the job.

If you're rolling Claude Code out to a team and want guards, mods and plugin distribution set up without the trial and error, tell me what you're running and I'll tell you what I'd lock down first.