Mods

Claude Mods shipped in 2.1.287 (October 1, 2026). A mod is a plugin whose code runs inside Claude Code itself. Its JavaScript or TypeScript functions are called on events: a tool call about to run, a prompt you submit, a request going to the model, a part of the screen being drawn. Each function can watch the event, change it, or answer it so the usual behavior never runs.

That is the difference from the hooks you already know. A settings hook is a shell command, HTTP call or prompt that Claude Code runs from outside and reads an answer back from. A mod is code in Claude Code's own process. It installs, updates and uninstalls like any other plugin, and the same plugin can also ship skills, agents and MCP servers.

What a mod can do

• Draw. Add a pane beside the transcript or a band above the prompt, with tabs, buttons and text fields, or restyle rows Claude Code draws itself (a tool call's row, the spinner).
• Step into a tool call or a request. Hold a call while it asks you something, answer it without running the tool, or send one request to a different model.
• Add commands that run code. A /command that runs your function at once, with no Claude turn, even while Claude is working.
• Share state across events. One hook counts tool calls, another shows the count beside the spinner.

Hooks run in every session that loads the plugin, including claude -p, the Agent SDK and cloud sessions. Drawing shows only in the terminal and in the Desktop app's Code tab.

The security point

A mod runs with your permissions and is not sandboxed. It can read and write any file your account can, start processes, make network requests, read environment variables and settings (API keys included), see every prompt and tool call, and spend your usage on model calls. Turning on sandboxing does not help here: the sandbox wraps the Bash commands Claude runs, and a process a mod starts runs outside it.

It can also approve tool calls your own guards would stop. A mod that handles tool.check answers after your permission rules and PreToolUse hooks, and its answer can replace theirs:

Your guard	Can a mod override it?
An ask rule	Yes, it can approve the call without the prompt
A block from your own PreToolUse hook	Yes, unless the hook is in managed settings
The auto mode classifier	Yes, a call the mod approves skips the classifier check
A deny rule	Not on Team or Enterprise sign-in or a machine with managed settings (by default). Anywhere else, yes

The one thing a mod cannot restyle is the permission prompt itself. Treat a mod like a dependency with root on your session: install only from authors and marketplaces you trust.

Inspect before you install

Get the plugin's files (clone the repo), then run:

claude plugin validate ./some-mod

The hooks: and calls: lines list which events the mod handles and what it asks Claude Code to do (read a file, start a process, make a network request) without running it. Since 2.1.290 the output also marks each gating hook with whether it has a .catch. To see what a session actually loaded, open /plugin: a dim line under the tabs reads like 1 mod active · name.

Turn mods off

Mods are on by default from 2.1.287 (the Desktop app from 2.1.286).

• One mod. Disable or uninstall its plugin from the Installed tab in /plugin.
• Every installed mod, one session. Start with claude --safe-mode. This also turns off your other customizations for that session.
• Every mod you installed, every session. Set "disableAllHooks": true in ~/.claude/settings.json. Your settings hooks and custom status line stop too; what your organization manages keeps running.

Organizations can go further with allowManagedModsOnly. If you set CLAUDE_CODE_ENABLE_FUNCTION_HOOKS during early access, remove it: 2.1.287 and later ignore it, so setting it to 0 no longer keeps mods off.

Built-in mods

Some of Claude Code's own features are now mods. They show under Built-in in /plugin → Installed, and --safe-mode, --bare and disableAllHooks do not stop them.

Name in /plugin	What it does
cc-plugin-agents-md	Loads AGENTS.md as project instructions
cc-plugin-diff	Draws the /diff pane
cc-plugin-plugin-authoring	Gives Claude the plugin-authoring skill for writing mods
cc-plugin-sec-default	Guards what your organization manages from user-installed mods
cc-plugin-telemetry	Sends Claude Code's analytics records
cc-plugin-you-should-know	Off by default; see below

Source for several of these is public in the mods folder of the Claude Code repo, a useful reference if you want to write one.

You should know

A built-in mod that runs a side agent while Claude works on longer tasks. When it spots something you or Claude might miss, it puts a short note above the prompt. It ships disabled. Turn it on with:

/plugin enable cc-plugin-you-should-know@builtin

It is offered for first-party sessions with telemetry on; if your org has it, it is listed under Show disabled in /plugin → Installed. Since 2.1.290 its notes follow your language setting.

Make one

Describe what you want in a session and Claude writes it, using the built-in plugin-authoring skill; edits hot-reload in the running session. Anthropic shares sample mods (a context-window forecast band, a hold-and-preview for risky shell commands, a /replay of the last turn's edits) in the claude-code-playground repo. For what other people have built, Lydia Hallie's thread asking that question is a good place to browse.

Gotchas

• "Hook" now means two things. In the mods docs, a hook is a mod's function; the settings.json kind is a "settings hook". Read which one a page means.
• Pick the smallest tool. If a settings hook, a skill or an MCP server already does the job, use it. A mod earns its place when you need a pane, a command that runs code, or to rewrite an event.
• It moves fast. Mods get API additions in nearly every release (2.1.288 through 2.1.296 added notifications, autocomplete rows, prompt caching for model calls and more). Check the changelog before relying on a detail.

Mods vs hooks vs plugins: a plugin is the package. Settings hooks are scripts Claude Code runs from outside to allow, block or log. Mods are code inside Claude Code that can change the event itself and draw on screen. More reach, so more trust required.