Mods — Extending Claude Code

A Mod is an extension distributed as a plugin that runs JavaScript or TypeScript event handlers inside Claude Code. It can observe or change tool calls and prompts, add commands or tools, and draw terminal interfaces. Mods intervene more deeply in Claude Code than Skills, which provide instructions, or MCP servers, which connect external tools.

How Mods differ from Settings Hooks

The names are similar, but their execution models and purposes differ.

	Settings Hooks	Mods
Defined in	The hooks setting	JavaScript or TypeScript handlers inside a plugin
Execution	Runs a shell command, HTTP request, or prompt	Runs an event handler inside the Claude Code process
Best for	Logging, blocking, or adjusting events with existing scripts	UI, new commands or tools, and fine-grained changes to prompts or tool calls
Choose when	A script is enough for the automation	You need UI or deeper behavior changes inside the app

Mods do not replace existing Settings Hooks. If a shell script can handle the task, a Hook may be simpler.

Files inside a plugin

A Mod is a plugin, not a separate installation format. A small example might look like this:

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

hooks.json points to the handler module, and register.js registers functions for each event. A handler can pass an event through unchanged with next(e), modify it, or take over the default behavior. Implementation details can change quickly; use the official overview, events, API, and testing documentation as the source of truth.

Mods run with your user permissions

Review the code before installing

A Mod runs with the installing user's permissions and is not isolated inside the Bash sandbox. It can access files the user can access, environment variables and secrets in configuration files, conversation prompts, and tool calls. It can also start processes, make network requests, alter prompts or tool calls, and incur model usage.

Do not assume a plugin is safe just because it is listed in a marketplace. Check its author and distribution source. Before installation, inspect the events and API calls a Mod handles with this command in the plugin directory:

claude plugin validate ./some-mod

Review the hooks: and calls: entries in the output, then inspect the handler source itself. Avoid running code you have not reviewed in an environment containing personal data or credentials. This validation helps with static review; it does not guarantee that the code is safe.

In particular, check:

• Which events trigger the Mod
• Whether it calls file, process, or network APIs
• Whether it changes or replaces prompts or tool calls, or approves actions on the user's behalf
• Whether it makes model calls that consume usage or incur costs
• Whether the code matches the code from the stated distribution source

The Bash sandbox does not isolate Mods

Sandboxing Bash commands run by Claude does not contain processes a Mod starts directly. Do not treat the Bash sandbox or permission settings as safeguards for Mod code.

Organization permission policies must also be considered separately from a Mod's own code execution privileges. Managed policies control tool calls requested by Claude, but do not restrict file, process, or network APIs that a Mod invokes directly. Therefore, PreToolUse or permission rules do not make an unreviewed Mod safe to run. See the official managed settings documentation for policy behavior and scope.

In the default environment with managed settings or a Team or Enterprise login, a Mod's approval code cannot get a tool call past ask rules or PreToolUse hooks. Without those protections, a Mod can approve calls that those rules or hooks would otherwise prompt for or block. The interaction with deny rules has additional conditions, so check how your organization is configured.

Availability and disabling Mods

Mods are enabled by default according to the official documentation. They are supported in the CLI from v2.1.287 and in the Claude Desktop Code tab from the app's bundled Claude Code v2.1.286. Check the version in your environment before using them.

• See Mods loaded in the current session in the Installed tab of /plugin.
• Disable or remove a plugin to turn off an individual Mod.
• Use claude --safe-mode to disable all user-installed Mods for one session. This also disables other user customizations.
• Set disableAllHooks to disable user-installed Mods across sessions. This also disables Settings Hooks and the user status line; built-in Mods are not affected.

Built-in Mods appear separately in the Installed tab of /plugin. Unlike user-installed Mods, they are not all disabled by --safe-mode or disableAllHooks alone.

Managed organizations have a separate policy. Administrators can use managed settings to control which Mods are allowed. Check the official Mods administration documentation when configuring organization policy.

Next steps

• Plugin overview →
• Install and manage plugins →
• Run a marketplace →
• Hooks system →
• Security guidelines →

---

Next chapter: Run a marketplace →