# Claude Code Mods

> Source: https://aiwiki.ai/wiki/claude_code_mods
> Updated: 2026-10-02
> Fact-checked: 2026-10-02
> Categories: Anthropic, Developer Tools, Software Development
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/) - attribute to "AI Wiki (aiwiki.ai)"
> Cite as: AI Wiki. "Claude Code Mods." aiwiki.ai, 2 Oct 2026. https://aiwiki.ai/wiki/claude_code_mods
> From AI Wiki (https://aiwiki.ai), the free encyclopedia of artificial intelligence. Reuse freely with attribution.

**Claude Code Mods** are extensions that change the behavior and interface of [Claude Code](https://aiwiki.ai/wiki/claude_code). [Anthropic](https://aiwiki.ai/wiki/anthropic) announced their launch on October 1, 2026. Distributed inside plugins, mods can intercept prompts and tool calls, add interactive interface elements, and replace selected built-in features.[1]

## Development and release

Anthropic discussed the underlying function-hook design in its public Claude Code repository on September 3, 2026. A September 9 update adopted the product name Claude Mods and opened testing through an environment variable. The issue received a launch update on October 1. In this terminology, a function hook is the implementation mechanism, while a mod is a plugin that uses it.[2]

Mods are enabled by default in Claude Code 2.1.287 and later. The preview variable `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` is ignored, even when set to `0`. Installed updates load into an existing session through `/reload-plugins`.[3]

## Structure and execution

A mod has an ordinary plugin manifest and a hooks module written in JavaScript or TypeScript. Claude Code loads these files directly, without a separate Node.js installation or bundling step. The `modules` entry in `hooks/hooks.json` points to one module, using a path relative to that configuration file.[4]

| File | Role |
|---|---|
| `.claude-plugin/plugin.json` | Plugin identity and metadata |
| `hooks/hooks.json` | Location of the hooks module |
| Hooks module | Exported `register` function that registers event handlers |

Developers can load a local directory with `--plugin-dir`. Claude Code watches it and reloads its module after changes, running registration again. It also generates declarations in `.claude-plugin/types/` for the installed build. Anthropic identifies those declarations as authoritative when documentation and runtime versions differ, because events and methods can change between releases.[4]

### Event handling

Handlers receive the mods API as `$`, an event object, and a `next` function. Calling `next` passes control to another handler or, at the end of the chain, Claude Code's normal behavior. A handler can inspect the eventual result after awaiting that call. It can also pass a modified copy of the event onward, or return its own answer without invoking subsequent handlers. The event object itself is immutable.[5]

The outermost handler receives the input first and the result last. This ordering determines which modifications later handlers see and whether they run. Matchers restrict a handler to selected events, such as calls to a particular tool.[5]

Failure behavior matters for enforcement. If an unhandled error or timeout occurs before a handler calls `next`, Claude Code skips that handler and continues. If it fails after the next handler has returned, that result remains. A registered error handler can instead return a refusal when a guard fails.[5]

### The mods API

The `$` argument groups operations into namespaces for interface access, files, processes, networking and session data. The module has no direct Node.js APIs or independent network and filesystem access; it reaches those resources through the mods API. A mod can register commands for users and tools for Claude, or arrange background work through timers. `$.store` provides persistent JSON storage for the plugin.[6]

Model calls can run outside the main conversation. `$.model.complete` uses the session's credentials for a separate prompt without conversation history; `$.model.fork` asks a question using the current conversation. Both consume the user's subscription usage or API allocation.[6]

Calls through the API also become events. For example, a file-read API call produces an event that an earlier mod can inspect, change or refuse. This provides a mechanism for administrator-supplied mods to restrict later mods' operations.[6]

## Interface customization

Mods draw at designated locations, including panes, a band above the prompt, and selected existing components. A `ui.render` handler returns a tree describing its output. `$.ui.resolve(e)` supplies the elements available on the current surface, including text, boxes and controls. Buttons and text inputs can invoke callbacks, while invalidation requests a redraw after data changes.[7]

Rendering support depends on the host interface. A terminal pane can move above the prompt when the window is narrow. Some elements, such as raster grids, are terminal-specific. Claude Code validates returned trees and falls back to its own rendering when a tree is invalid.[7]

The permission prompt is excluded from these rendering locations. Mods cannot change the information that prompt displays. The separate question dialog supports limited modification, subject to preserving its original dialog reference.[7]

### Supported sessions

Session support:[3]

| Environment | Hooks | Mod interface |
|---|---|---|
| Terminal CLI | Supported | Supported |
| Desktop app's Code tab | Supported, except WSL sessions | Supported with surface-specific limits |
| VS Code chat panel | Supported | Not displayed |
| Print mode and Agent SDK | Supported | Not displayed |
| Cloud session | Supported when the plugin reaches the session | Not displayed |

### Built-in and example mods

Anthropic publishes source for several mods included in Claude Code:[8]

| Source directory | Function |
|---|---|
| `diff` | Displays uncommitted file changes in a pane and refreshes them during work |
| `agents-md` | Controls loading of project `AGENTS.md` instructions, including a default fallback when the project lacks its own `CLAUDE.md` |
| `sec-default` | Protects organizational settings and policy from user-installed mods |
| `telemetry` | Handles built-in analytics events and sends nothing where analytics are disabled |

These source directories contain complete plugins and tests. The instruction-file mod has options to read both instruction formats, use only the usual `CLAUDE.md` behavior, or retain only managed instructions.[8]

Anthropic's launch tutorial also presents three examples. Token Weather displays context usage above the prompt. Blast Radius pauses selected shell commands and presents their expected effects with controls to continue or cancel. Replay Theater lets users step through file edits from a turn. These examples demonstrate observation, intervention and review interfaces; the tutorial also describes sharing them through plugin marketplaces.[9]

The built-in You should know mod, introduced in version 2.1.287, runs a side agent that identifies potential omissions while Claude works. The release notes specify first-party sessions with telemetry enabled and give `/plugin enable cc-plugin-you-should-know@builtin` as the activation command.[15] The mod starts disabled, and availability can depend on the organization.[3]

## Permissions and organizational controls

Mods execute with Claude Code's access to the computer and are not sandboxed. Anthropic therefore advises treating installation as a decision to trust executable code. The launch announcement describes prompt rewriting, tool-output redaction, permission decisions and custom audit logging as possible mod behaviors. Existing plugin marketplace controls also apply to plugins containing mods.[1]

The [Claude Code sandbox](https://aiwiki.ai/wiki/claude_code_permissions_and_sandboxing) isolates Bash commands, but does not enclose a process started by a mod. Mods can also approve some tool calls without prompting.[3]

On machines with managed settings, and for users signed in on Team or Enterprise plans, the built-in `sec-default` guard normally runs before user-installed mods. It protects managed instructions, settings and hooks. Where the guard applies, user mods cannot override tool-deny rules by default, and blocks from managed `PreToolUse` hooks remain final.[10]

Those protections concern Claude's tool calls. They do not automatically restrict a mod's own filesystem or process operations. A mod can still read a file through its API even when a tool rule denies Claude access to that file. Administrators can prevent such mods from loading or restrict their API operations with a policy mod.[10]

The managed `allowManagedModsOnly` option excludes user-supplied mods, including local development mods. Organizational mods qualify through specific managed configuration and local-directory requirements. Administrators can order policy mods with `prependPlugins`; an explicit list must retain `sec-default@builtin` to preserve the default guard.[10]

## Disabling mods

The controls differ in scope:

| Control | Effect |
|---|---|
| Disable the containing plugin in `/plugin` | Turns off that plugin. Managed plugins cannot be disabled through this panel.[13] |
| Set `"disableAllHooks": true` in personal settings | Stops user-installed mods. Organizational mods continue running.[12] |
| Start with `claude --safe-mode` | Troubleshoots a session without installed plugins or other customizations. Authentication, model selection, built-in tools and permissions still work; managed settings policy remains applicable.[16] |

`disableAllHooks` has broader reach when an administrator sets it in managed settings: it stops mods from all installed plugins, including organizational ones. Built-in mods remain active in either case and have separate controls. This setting also affects custom status-line and file-suggestion commands.[12]

## Validation and testing

`claude plugin validate` examines the plugin manifest and statically analyzes its hooks module without executing the mod. Its output identifies registered events and API calls. This is a way to inspect requested capabilities before loading the plugin.[4]

Automated tests run through `claude plugin test` and use the `claude-code/testing` module. They send events through the mod's handlers and check the responses. Test stubs supply answers that would otherwise come from Claude Code, so tests need no signed-in session or network access and do not run real models, stores or tools.[11]

The test interface can also mount mod UI and exercise controls. A failed test produces a nonzero exit status for continuous integration. Drawing tests validate the returned element tree, but do not verify how the application paints it. Layouts still need inspection in a running session.[11]

### Diagnosing a mod that does not run

For loading failures, hot-reloaded development sessions display a diagnostic line in the transcript. Ordinary interactive sessions put that information in the debug log, which `claude --debug` enables. A print-mode run with `--plugin-dir` reports loading problems on stderr in its default text-output format; refusals by another mod still go to the debug log.[14]

Running `claude plugin test` from a directory without a mod checks whether mods can load, without installing one:[14]

| Message | Meaning |
|---|---|
| `no hooks module to load` | Mods are permitted, but the directory contains none to test |
| `hooks modules are turned off here` | Settings or organizational policy block mods |
| `hooks modules are turned off in this process` | Anthropic has remotely disabled installed mods |

This check does not report `allowManagedModsOnly`; a user-installed mod may still be refused under that policy.[14]

## Relationship to other extensions

[Settings hooks](https://aiwiki.ai/wiki/claude_code_hooks) run configured handlers at lifecycle events; [skills](https://aiwiki.ai/wiki/claude_skills) supply instructions, and [Model Context Protocol](https://aiwiki.ai/wiki/model_context_protocol) servers supply external tools. Mods run within Claude Code and draw interfaces. Plugins can combine these extension types.[3]

## References

1. Anthropic. [Customize Claude Code with mods](https://claude.com/blog/claude-code-mods). October 1, 2026.
2. Anthropic, Claude Code repository. [Mods - make Claude 10x more extensible, issue 91870](https://github.com/anthropics/claude-code/issues/91870). Opened September 3, 2026; updated October 1, 2026.
3. Anthropic. [Mods overview](https://code.claude.com/docs/en/plugins/mods/overview). Claude Code documentation. Accessed October 2, 2026.
4. Anthropic. [Create a mod](https://code.claude.com/docs/en/plugins/mods/create). Claude Code documentation. Accessed October 2, 2026.
5. Anthropic. [React to events with a mod](https://code.claude.com/docs/en/plugins/mods/events). Claude Code documentation. Accessed October 2, 2026.
6. Anthropic. [Use the mods API](https://code.claude.com/docs/en/plugins/mods/api). Claude Code documentation. Accessed October 2, 2026.
7. Anthropic. [Draw in the interface with a mod](https://code.claude.com/docs/en/plugins/mods/interface). Claude Code documentation. Accessed October 2, 2026.
8. Anthropic, Claude Code repository. [Mods README](https://github.com/anthropics/claude-code/blob/main/mods/README.md). Accessed October 2, 2026.
9. Addy Osmani. [Getting started with Claude Code mods](https://claude.dev/blog/getting-started-with-claude-code-mods/). Anthropic developer blog. October 1, 2026.
10. Anthropic. [Manage mods for your organization](https://code.claude.com/docs/en/plugins/mods/admin). Claude Code documentation. Accessed October 2, 2026.
11. Anthropic. [Test a mod](https://code.claude.com/docs/en/plugins/mods/test). Claude Code documentation. Accessed October 2, 2026.
12. Anthropic. [All settings: disableAllHooks](https://code.claude.com/docs/en/settings-reference#disableallhooks). Claude Code documentation. Accessed October 4, 2026.
13. Anthropic. [Install and manage plugins](https://code.claude.com/docs/en/plugins/install). Claude Code documentation. Accessed October 4, 2026.
14. Anthropic. [Troubleshoot a mod](https://code.claude.com/docs/en/plugins/mods/troubleshoot). Claude Code documentation. Accessed October 4, 2026.
15. Anthropic, Claude Code repository. [Release v2.1.287](https://github.com/anthropics/claude-code/releases/tag/v2.1.287). October 1, 2026.
16. Anthropic. [CLI reference](https://code.claude.com/docs/en/cli-reference). Claude Code documentation. Accessed October 4, 2026.