Claude Code mods run inside the process with your permissions. Vet them before you install

Claude Code 2.1.287 introduced mods: plugins whose JavaScript or TypeScript functions run inside the Claude Code process. They can draw panes, rewrite tool calls and add commands. They also run with your permissions and sit outside the sandbox, which makes “read it before you install it” a real step rather than a platitude.

How they differ from hooks

A settings hook is a shell command, HTTP request or prompt that Claude Code runs on an event. A mod is a function Claude Code calls in its own process, according to the Claude Code docs . That’s why a mod can do things a hook can’t: redraw the spinner, hold a tool call while it asks you a question, or answer a call without running the tool.

If all you need is to block or log an event with a script you already have, the docs themselves point you at a settings hook. Mods are for the cases where you want state shared between handlers, or something on screen.

A small mod is three files: .claude-plugin/plugin.json, hooks/hooks.json and a code file. The modules key in hooks.json points at the code, and that key is what turns a plugin into a mod. You can try one without installing anything:

claude --plugin-dir ./first-mod

Claude Code watches a directory loaded this way and hot-reloads the module when you save, so the edit loop is short. The docs also describe claude plugin test, which fires events at your hooks and checks the results with no session, sign-in or network.

What a mod can reach

Anthropic’s docs are blunt here. Once loaded, a mod can read and write files anywhere your account can, start processes, make network requests, read environment variables and settings files (including API keys kept in either), and see every prompt and tool call in the session. It can rewrite a prompt or tool call, and it can approve a tool call before you’re asked.

Mods aren’t sandboxed. If you’ve turned on sandboxing, it isolates the Bash commands Claude runs, and a process a mod starts runs outside it. A mod that approves tool calls can approve one that an ask rule would have prompted for, or one that your own PreToolUse hook blocked. The docs say mods can’t restyle the permission prompt, so what the prompt shows you stays honest.

If you wrote guardrails with hooks (we covered a PreToolUse guardrail recently), a third-party mod is the thing that can route around them. Treat installing one the way you’d treat adding a dependency that runs as you.

Read what it does first

You don’t have to eyeball the source cold. Clone the plugin and run validate on the directory:

claude plugin validate ./some-mod

Per the docs, validate runs static analysis on the hooks module without executing it. The output has a hooks: line listing the events the mod handles, with filters, and a calls: line listing every mods API method it uses. A module that touches environment variables also gets env reads: and env writes: lines, and one that uses persistent state gets state reads: and state writes:.

That works because a hook can only act outside its own code by calling the mods API, so the list of calls is the list of capabilities. A spinner tweak that lists $.ui calls is unremarkable. A “formatting helper” whose calls include network access, process spawning and an env read of your API key deserves a hard look at the source.

Validate has a limit worth stating: it tells you what a mod can ask for, not whether the request is reasonable. You still have to read the code behind the risky calls.

The same rules that make the analysis possible (string-literal event names, no aliasing $, imports only from inside the plugin) also make a mod harder to hide things in. A module that fails validation for those reasons is a reason to say no.

Where to start

Anthropic publishes sample mods in its claude-code-playground repository, including blast-radius, which holds a risky shell command such as rm -rf or a force push and shows what it would change before you proceed. The docs say the samples are shared as-is, without support. Some Claude Code features are mods too: /diff and the AGENTS.md loader appear under Built-in in /plugin.

To switch installed mods off for one session, start with --safe-mode. To switch them all off everywhere, set "disableAllHooks": true in ~/.claude/settings.json, which also stops your settings hooks and custom status line. Neither touches built-in mods. Organizations can restrict which mods load through managed settings.

Next step: before your team installs its first mod, agree that claude plugin validate output goes in the review.