Claude Code mods, explained simply, with a first mod

A Claude Code mod is a small piece of code that runs inside Claude Code and gets a say every time something happens: Claude is about to run a tool, you send a prompt, the screen is drawn. It can watch, change, or stop that thing. You do not have to write it yourself: you can ask Claude to make one in plain words. Here is what that means in practice, what people use mods for, and the simplest one you can build today.

A mod in one sentence

A mod is a plugin with a few functions that Claude Code calls when an event happens, and each function can let the event pass, change it, or answer it itself.¹

Anthropic added mods in Claude Code v2.1.287 on October 1, 2026, and they are on by default.⁶ During early access the same thing was called function hooks. You will see both names online.

Think of Claude Code as a road and a mod as a checkpoint you put on it. Every tool call, every prompt, every redraw of the screen drives past your checkpoint. Most of the time the checkpoint waves it through. Sometimes it adds a note, changes the cargo, or says no.

What it looks like in practice

On disk, a mod is a folder with three small files: a plugin.json with its name, a hooks/hooks.json that points at your code, and the code file itself, called the hooks module.¹ Claude Code loads .js and .ts files directly, so there is no build step and no Node.js setup.²

Inside the code file you write one function, register, and in it you say which events you care about. Every handler gets three things: $, the toolbox for doing things in Claude Code (draw, show a message, run a command); e, the event itself, such as the tool name and its arguments; and next, which means "carry on as usual".²

That is the whole model. Call next(e) and nothing changes. Call next with a changed event and you rewrite what happens. Return your own answer without calling next and the normal behavior never runs.³

Anthropic's own first example is a good picture of how small this can be: about twenty lines that count Claude's tool calls and show the count next to the spinner, as in "Thinking · tool calls: 3".¹

What you can do with one

Real examples, all from Anthropic's docs and sample mods:

• Stop a risky command and say why. A mod can refuse a git push --force and give Claude a sentence it reads instead, such as "push to a new branch instead".³
• Ask you before something risky runs. The sample mod blast-radius holds a command like rm -rf or a force push, shows what it would change, and gives you buttons to proceed or cancel.⁷
• Draw something new on screen. The sample token-weather draws a forecast of your context window above the prompt.⁷ Mods can open a pane next to the transcript, with tabs, buttons and text fields.¹
• Add a command that runs instantly. The sample replay-theater adds /replay, which steps through the file edits Claude made in the last turn.⁷ A mod command runs your code at once, with no Claude turn, even while Claude is busy.¹
• Add context Claude reads. A mod can add a line only Claude sees, such as the current git branch whenever your prompt mentions a pull request.³
• Tell you when Claude is done, and what it did. A mod sees when a turn ends, including Claude's final answer, so a notification can say what happened instead of just "done".³ Ours is open source: session-pings on GitHub.

Some of Claude Code itself is now built as mods. /diff is a built-in mod, and so is AGENTS.md support. There is also an optional built-in called cc-plugin-you-should-know, which runs a side agent that watches longer tasks and shows a note above the prompt when it spots something you might miss.¹

Mods vs CLAUDE.md, plugins, skills, hooks and MCP

Claude Code now has a lot of ways to customize it, and they overlap. In plain words:

Two notes to keep this fair. First, settings hooks are not weak: a PreToolUse hook can already refuse a tool call and give Claude the reason, and it can change the call's input.⁴ If you have one that works, keep it. What a mod adds is that it runs inside Claude Code: it can draw, keep data from one call to the next, call a model, add instant commands, and change what Claude Code shows.¹ Second, a mod is not a replacement for a skill or an MCP server. A plugin can ship all three together.¹

The difference that matters most is between the first row and the mod row. A rule in CLAUDE.md is something Claude reads and usually follows. A rule in a mod is code that every tool call passes through, so Claude cannot skip it.

The simplest mod: ask Claude for it

The easiest way to make a mod is to describe it. Claude Code ships a built-in skill called plugin-authoring that tells Claude where to write a mod and which events your version has. Claude can load it on its own when you ask for a mod, or you can run /plugin-authoring yourself.²

> make a mod that stops you from editing .env files,
  and tells you to ask me instead

  Writing ~/.claude/dev-mods/<session-id>/protect-env/ ...

  Enable hot reloading for this session?
  > Enable for this session
    Not now

Here is what happens, step by step:²

1. Claude writes the mod into a folder for this session: ~/.claude/dev-mods/ plus the session ID, plus the mod's name. In the default permission mode you approve each file, because ~/.claude is a protected path.
2. When the first file is saved, Claude Code asks: "Enable hot reloading for this session?" Pick Enable for this session.
3. The mod loads when Claude's turn ends. Run /plugin and check the Installed tab to see it.
4. Try it. If it is not right, say what to change. It reloads at the end of each turn that edits it.

A mod written this way lives only in that session, and its folder is cleaned up later. To keep it, copy the folder somewhere of your own, such as ~/mods/protect-env, and start Claude Code with claude --plugin-dir ~/mods/protect-env.²

And here is the whole mod from the prompt above. It is one rule: Claude may not edit or write a .env file. When it tries, the edit does not happen, and Claude reads a short instruction instead, so it can carry on and tell you what to change.

protect-env/
├── .claude-plugin/
│   └── plugin.json      { "name": "protect-env", "version": "0.1.0" }
└── hooks/
    ├── hooks.json       { "modules": ["./register.js"] }
    └── register.js

// Matches .env, .env.local, config/.env.production, and so on
const ENV_FILE = /(^|\/)\.env(\.|$)/

export function register(on) {
  // Runs each time Claude is about to edit or write a file
  on('tool.call', { tool: ['Edit', 'Write'] }, async ($, e, next) => {
    if (ENV_FILE.test(e.file_path)) {
      // No call to next, so the edit never happens. Claude reads this text.
      return { deny: 'Editing .env files is not allowed here. Tell the user which value to change instead.' }
    }
    // Every other file: carry on as usual
    return next(e)
  })
}

We built this exact folder and ran Claude Code's own checks on it. claude plugin validate reads the code the way Claude Code will and lists what it hooks and what it calls. claude plugin test runs a small test with no session at all. Both passed on v2.1.287 (the warning is only that the manifest has no author field).

$ claude plugin validate ./protect-env
  ❯ ./register.js hooks: tool.call{tool=Edit|Write}
  ❯ ./register.js calls: nothing on $
✔ Validation passed with warnings

$ claude plugin test
(pass) blocks an edit to .env and lets other files through
 1 pass
 0 fail

The pattern is the same as the force push example in Anthropic's docs: return { deny } with a sentence Claude can act on, and call next(e) for everything else.³ Note what this mod does not catch: a shell command like echo X > .env goes through Bash, not Edit or Write. A guard only sees what you point it at.

Turning mods on and off, and the one safety note

Mods need Claude Code v2.1.287 or later. Run claude --version to check.¹ To turn them off, pick how much:¹

• One mod: disable or uninstall its plugin in /plugin, on the Installed tab.
• All installed mods, for one session: start with claude --safe-mode.
• All installed mods, everywhere: set "disableAllHooks": true in ~/.claude/settings.json. This also stops your settings hooks and custom status line.

If your company manages Claude Code, an admin can also allow only the company's own mods with a setting called allowManagedModsOnly.⁵

The safety note: mods are not sandboxed. A mod runs with your permissions. It can read and write your files, start programs, make network requests, read your environment variables and API keys, see every prompt and tool call, and spend your usage on model calls.¹ So install mods only from people you trust, and before you install one, run claude plugin validate on its folder. The hooks: and calls: lines tell you what it listens to and what it can do.¹

Why bother: rules that always hold

Panes and games are fun, and that is where most early mods are. But the most useful thing a mod gives you is simpler: a rule that holds every time.

Today, most people's rules live in CLAUDE.md: "never touch production", "don't edit .env", "ask before you delete". Claude follows them most of the time. Most of the time is the problem. A mod turns the rule into code that every tool call passes through. And a good guard does not end the session. It blocks the one action and tells Claude why, so Claude finds another way to get you the result.

It is an extra layer, not a guarantee. It sits on top of Claude Code's own permission system, it only sees what passes through the events you hook, pattern matching can miss things, and --safe-mode turns it off. But for "this must never happen" rules, it is a much better place than a sentence in a prompt. We go deeper in rules Claude Code cannot ignore.

Next reads

• Guardrails as a mod: rules Claude cannot ignore, and why a prompt rule is not enough
• Notifications as a mod: your hook pings you, a mod tells you why
• Redact sensitive data: keep secrets and personal data out of the session
• Database guard: stop destructive database actions and keep Claude read-only on production

One more thing a session cannot see on its own is what your app is doing in production. Fixter is monitoring for teams that build with coding agents: you send your logs and traces over standard OpenTelemetry, and Fixter finds the issues and bugs in your system and tells you what broke and why. You pull them straight into Claude Code over MCP and fix them there.

Frequently asked questions

What is a Claude Code mod?

A mod is a small plugin with a few JavaScript or TypeScript functions that run inside Claude Code. Claude Code calls them when something happens, such as Claude being about to use a tool, you sending a prompt, or part of the screen being drawn. Each function can watch the event, change it, or answer it itself. Mods arrived in Claude Code v2.1.287 on October 1, 2026, and are on by default.

Do I need to know how to code to make a mod?

Not really. You can describe the mod in a normal Claude Code session, for example "make a mod that stops you from editing .env files", and Claude writes it with its built-in plugin-authoring skill. Claude Code then asks whether to enable hot reloading for the session, and once you say yes the mod loads. Reading the short code it writes is still a good idea, because a mod runs with your permissions.

What is the difference between a mod and a settings hook?

A settings hook is a script you list in settings.json that runs on an event, such as PreToolUse or Stop. It can already block a tool call with a reason, change a tool call's arguments, and add context. A mod is a function that runs inside Claude Code, so it can also draw panes and bands, add slash commands that run instantly, keep data between calls, call a model, and change what Claude Code itself draws.

Are Claude Code mods safe?

A mod is not sandboxed. It runs with your permissions, so it can read and write your files, start programs, make network requests, read environment variables, and see every prompt and tool call. Install mods only from authors you trust. Before you install one, run claude plugin validate on its folder to list which events it handles and what it calls.

How do I turn mods off?

To stop one mod, disable or uninstall its plugin from the Installed tab in /plugin. To run one session without any installed mods, start Claude Code with --safe-mode. To stop every mod you installed in every session, set disableAllHooks to true in ~/.claude/settings.json, which also stops your settings hooks and custom status line.