Claude Code mods arrived on October 1, 2026, and they let you change how Claude Code itself behaves. In Anthropic’s words, they are "small TypeScript functions that change how Claude Code works," and they ship inside plugins. A mod can rewrite a prompt, stop or change a tool call, add a command, or draw new panels in the interface.
This piece covers what Claude Code mods are and how they differ from hooks, plugins, skills and subagents. It also covers where mods live and how to share them. It ends with an example for WordPress and Drupal teams and the security checks to run first.
The short version: a mod is a plugin with a JavaScript or TypeScript file that runs inside Claude Code. Use one when a settings hook cannot do the job. Examples are a pane, a custom command or a question before a risky command. If a shell script hook already works, keep it. Review every mod like a WordPress plugin from an unknown author, because mods are not sandboxed.
What Claude Code mods are
Anthropic’s mods overview defines a mod as "a plugin that changes how Claude Code looks and behaves," built from event handlers. Claude Code calls a handler when something happens. That might be a tool call, a prompt or part of the screen being drawn.
Each handler can do one of three things with the event:
- Observe it. Note what is happening and let it continue.
- Rewrite it. Change the event before Claude Code acts on it.
- Answer it. Handle the event itself, so the usual behavior never runs.
The docs say mods are JavaScript or TypeScript. Claude Code loads .js and .ts files directly, with no Node.js install, bundler or build step. A small mod has three files: a manifest, a hooks.json file and the code.
Some of Claude Code’s own features are now mods, including the /diff pane. You also do not have to write one by hand. Ask Claude Code for a mod in plain words, and it writes one using a built-in skill called plugin-authoring.
What a mod can do that a settings hook cannot
Claude Code already had hooks that run a shell command, HTTP request or prompt on an event. The docs now call those "settings hooks." A settings hook runs outside Claude Code. A mod runs inside it. That lets a mod:
- Draw a pane beside the transcript or a band above the prompt, with tabs, buttons and text fields.
- Restyle parts of Claude Code’s own screen, such as the spinner or a tool call’s row.
- Hold a tool call while it asks you a question, or answer the call without running the tool.
- Add a `/command` that runs your code at once, with no Claude turn.
- Share data between its handlers, so one can count something and another can display it.
There are limits. A mod cannot change the permission prompt. Each handler has a 10-second time limit, and Claude Code skips one that times out. In the VS Code chat panel and cloud sessions, handlers run but nothing a mod draws appears.
Claude Code mods compared with hooks, plugins, skills and subagents
The options overlap. This table pulls together Anthropic’s own comparisons.
| Option | What it is | Pick it when |
|---|---|---|
| Mod | JavaScript or TypeScript functions Claude Code runs in its own process | You want a pane, a band above the prompt, a custom command, or to rewrite an event |
| Settings hook | A shell command, HTTP request or prompt run on a lifecycle event | You want to block, allow or log an event with a script you already have |
| Skill | A `SKILL.md` file of instructions Claude reads | You keep pasting the same instructions into chat |
| Subagent | A worker with its own context that returns a summary | A side task would flood your main conversation |
| Plugin | The package that bundles any of the above | You want to reuse a setup across repositories or share it |
Two points matter for planning. A mod is a plugin whose hooks.json has a modules key. So one plugin can ship a mod, a skill and an MCP server. And Claude Code mods see subagents’ work too: the tool call handler fires for calls a subagent makes.
Settings hooks are not going away. The admin page says "Nothing about them is deprecated."
Where Claude Code mods live and how you share them
Because a mod is a plugin, it follows plugin rules. The plugin install guide lists three install scopes:
- User scope: on for you in every project, recorded in `~/.claude/settings.json`.
- Project scope: on for everyone in the repository, recorded in `.claude/settings.json`, which you commit. Each collaborator still installs the plugin once.
- Local scope: on for you in one repository, recorded in `.claude/settings.local.json`.
A mod Claude writes for you goes into a session folder under ~/.claude/dev-mods/ and loads only in that session. Claude Code deletes that folder after a cleanup period. To keep the mod, copy its folder elsewhere and load it with claude --plugin-dir.
Sharing follows the plugin path too. The create a mod guide lists four routes. Send a few people the folder or a .zip. List the mod in a private marketplace for your team. Have an administrator push it through managed settings. Or submit it to Anthropic’s directory.
Events and methods can change between releases. Anthropic suggests noting the version you tested with in your README. If you build Claude Code mods for clients, put that in your handoff notes.
A practical example for WordPress and Drupal teams
Claude Code sometimes runs WP-CLI or Drush against a database. You want certain commands stopped every time, with a message that tells Claude what to do instead.
Anthropic’s events guide shows a handler that refuses force pushes. We adapted its pattern to refuse database drops and resets. The syntax follows the docs, but we have not run this exact code. Test it on a scratch project first.
export function register(on) {
on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
if (/\bwp\s+db\s+(drop|reset)\b|\bdrush\s+sql[:-]drop\b/.test(e.command)) {
return { deny: 'Database drops are not allowed here. Ask the developer first.' }
}
return next(e)
})
}When the pattern matches, the command never runs and Claude reads the deny text as the result. Every other command goes on to the normal permission check.
A PreToolUse settings hook with a shell script can block the same commands. If your team already has that script, keep it. A mod is the better tool when you want more than a block. The docs show a handler that pauses a risky command and asks you to run it or refuse it. Another example puts the current git branch above the prompt. That helps when one session touches staging and production.
Drupal teams using Claude Code on upgrades before the Drupal 10 end of life on December 9, 2026, should consider a guard like this. The same goes for teams patching issues such as the recent Webform vulnerability on live sites.
The security model: review mods like plugins
Anthropic’s blog post says: "Mods run with the same access to your machine as Claude Code itself," and they are not sandboxed. A loaded mod can read and write files anywhere your account can. It can start programs, make network requests and read API keys. It sees every prompt and tool call. It can approve a tool call before you are asked, and it can spend your plan’s usage.
.env denied, the admin docs say a mod can still read that file directly.
To see what a mod does before you load it, run claude plugin validate on its folder. The hooks: line lists the events it handles. The calls: line lists what it asks Claude Code to do. Look for file writes, process starts, network fetches and environment reads.
We covered a related risk in Plugin4Shell: a pinned plugin is not always pinned. Claude Code mods raise the stakes, because a plugin can now act inside the session. For the repository side, see GitSpawn.
What Team and Enterprise admins get
On Team and Enterprise plans, a built-in mod called sec-default loads ahead of every mod a user installs. The same applies on any machine with managed settings. Users cannot turn it off. The admin guide says it protects managed hooks, managed instructions, managed MCP servers and the system prompt from users’ mods. Where it loads, a user’s mod cannot approve a call that a deny rule refuses.
The guard adds no other limits. A user’s mod can still read files, start processes and rewrite prompts. API key users, and those on Bedrock, Google Cloud or Foundry, get the guard only with managed settings.
Admins have a few switches:
- `allowManagedModsOnly`: blocks every mod a user brings, while settings hooks keep working.
- `disableSideloadFlags`: rejects `–plugin-dir`, so nobody loads a mod from a folder.
- `disableAllHooks`: the widest switch, which also turns off settings hooks and status lines.
Agencies can also ship their own policy mod. The admin guide includes one that refuses any user’s mod that starts processes.
Versions, plans and where Claude Code mods run
Claude Code mods need v2.1.287 or later, and they are on by default. The Claude Code changelog entry for 2.1.287 reads "Added Claude Mods: plugins may now modify deeper behavior" in full. Versions 2.1.288 to 2.1.290 added mod features and fixed mod bugs. As of October 6, 2026, 2.1.290 is the latest.
The mods pages we read set a version requirement, not a plan requirement.
Mods run in the CLI, including editor terminals and the JetBrains plugin, and in the Desktop app’s Code tab. Desktop sessions in WSL do not load plugins, so mods do not run there. If anyone set CLAUDE_CODE_ENABLE_FUNCTION_HOOKS during early access, remove it. Newer versions ignore it.
Do Codex, Antigravity or Grok Build have mods?
Not in the same form, based on each vendor’s own docs as of October 6, 2026. All three support plugins and hooks. In each case, hooks run scripts or commands outside the agent.
- OpenAI Codex: The Codex hooks page says hooks “run scripts or MCP tools during the Codex lifecycle,” and plugins can bundle them.
- Google Antigravity: Google’s docs say its hooks “run custom scripts or shell commands,” and plugins can ship hooks. Our [Antigravity plugins review](/artificial-intelligence-ai/antigravity-plugins-plan-review/) covers the new plugin installs.
- xAI Grok Build: The product page lists plugins and hooks. It says hooks “Run scripts on file edits and tool calls,” and plugins bundle them.
We found no in-process extension API that can redraw the interface in any of the three. That may change, so check before you plan around it. For a broader look at the two leading terminal agents, see our Claude Code vs OpenAI Codex comparison.
Frequently Asked Questions
What are Claude Code mods?
Plugins with JavaScript or TypeScript code that Claude Code runs in its own process. The code can watch, change or replace events such as tool calls, prompts and screen drawing.
When were Claude Code mods released?
October 1, 2026, in Claude Code v2.1.287. Anthropic announced them on its blog the same day.
How is a mod different from a Claude Code hook?
A settings hook runs a shell command, HTTP request or prompt outside Claude Code. A mod runs inside it, so it can draw panes, add commands, hold a tool call to ask you a question and share data between handlers.
Is a mod the same as a plugin?
A mod is a kind of plugin. It is a plugin whose `hooks.json` points to a code file. One plugin can ship a mod alongside skills, subagents and MCP servers.
Do I need to know TypeScript to use mods?
No. Describe the mod you want, and Claude Code writes it with its built-in `plugin-authoring` skill. Have someone who reads code review it before you keep it.
Are Claude Code mods sandboxed?
No. Anthropic says mods run with the same access as Claude Code itself. A mod can read files, start programs, make network requests and read API keys. Install mods only from sources you trust.
How do I check what a mod does before installing it?
Run `claude plugin validate` on the plugin’s folder. The `hooks:` line lists the events it handles, and the `calls:` line lists what it asks Claude Code to do, such as read files or make network requests.
Can my organization block mods?
Yes. Admins can set `allowManagedModsOnly` in managed settings to stop users’ own mods from loading, while the organization’s mods still run. Other settings block folder loading or turn off all hooks.
Do OpenAI Codex or Google Antigravity have something like mods?
Both have plugins and hooks, as does xAI’s Grok Build. Their docs describe hooks that run scripts or commands. We found no in-process extension like mods in any of them as of October 6, 2026.
