Release Summary
Claude Mods is a feature of Claude Code, introduced in the official v2.1.287 release on October 1, 2026. It gives developers a way to change the coding agent's interface and event handling through plugins. This page covers the rollout and the choices it creates; it is not a separate product review.
The practical decision is whether your workflow needs custom interface elements or event handling inside Claude Code. A skill can supply reusable instructions, and an MCP server can connect external tools. Mods address a different need: changing how the running agent behaves or displays information.
What Changed
Add custom interface elements inside Claude Code
Mods can display information above the prompt or in a pane beside the transcript, with interactive controls. This supports a context dashboard or a project-specific panel that remains visible while Claude works. A mod can also alter selected existing interface components. Drawing has platform limits: it is available in the terminal and the Desktop app's Code tab, rather than every client.
Add event handlers that can change tool calls
A mod's JavaScript or TypeScript functions run inside Claude Code. Handlers can observe an event, rewrite it before passing it onward, or provide their own response. That makes tool-call interception and custom commands possible without asking the model to interpret a skill on every turn. The official event guide explains the handler chain; a policy-changing mod deserves closer review than a display-only customization.
Introduce the optional You should know built-in mod
The v2.1.287 release also adds You should know, which uses a side agent to flag things the user or Claude might miss. Anthropic limits this built-in option to first-party sessions with telemetry enabled. It is optional and should not be presented as available through every provider or account setup.
Compared With Previous Version
The v2.1.287 changelog records the Claude Mods rollout. Earlier function-hooks experiments should not be confused with the documented default-on release: current official instructions require v2.1.287 or later and say the old CLAUDE_CODE_ENABLE_FUNCTION_HOOKS variable is ignored.
Existing settings hooks still have a role. They run configured shell commands, HTTP requests, or prompts on lifecycle events. Mods use functions inside the agent and can draw an interface. Choose the existing mechanism when it already solves the job; the release does not require rewriting working hooks or replacing MCP integrations.
Installation and Compatibility
Check the installed version with claude --version. Mods are on by default in supported versions, although local or organization settings may prevent them from loading.
A mod installs through the plugin system. Once its marketplace has been added, use /plugin install <plugin>@<marketplace> in Claude Code, or claude plugin install <plugin>@<marketplace> in your shell. Reload an open session with /reload-plugins, and use /plugin to check whether the mod loaded. Follow the chosen author's marketplace instructions rather than copying an unverified installation command.
| Claude Code surface | Mod behavior |
|---|---|
| Terminal, including an editor's integrated terminal | Hooks and interface rendering |
| Desktop app, Code tab | Hooks and rendering, with some terminal-only elements excluded |
| VS Code extension chat panel | Hooks run; custom panes and bands do not display |
claude -p and Agent SDK |
Hooks run; no custom interface rendering |
| Desktop Code tab in a WSL session | Mods unavailable because plugins are unavailable there |
These are the official compatibility rules checked on October 4, 2026. Cloud sessions have additional plugin-distribution requirements; consult the official overview for that access path.
For authors, Claude Code can generate a mod from a description using its plugin-authoring skill. A local mod contains a plugin manifest, hooks/hooks.json, and a hooks module. Use the type declarations generated by the installed Claude Code version when API details differ from online examples.
Permissions and Known Limitations
A mod runs with the installing user's permissions and is not sandboxed. It can reach files, environment variables, processes, network requests, and session data. Claude Code's Bash sandbox does not isolate a process that a mod starts. This is a material adoption constraint for repositories containing credentials or private code.
Before loading a mod, claude plugin validate <mod-directory> lists the hooks and API calls its source declares without running the mod. That provides useful inspection information; it is not a security certification. Organization administrators can apply managed controls to user-installed mods.
The launch version is a minimum compatibility baseline, not a recommendation to pin an old build. As of this update, the official latest release is v2.1.289, published October 3. Its notes include fixes for installed mods failing to load after an upgrade, mod rendering failures, and managed-machine permission behavior. Use a maintained build containing those fixes when evaluating Mods.
Who Should Upgrade / Who Should Wait
Upgrade to a maintained supported build if you need a persistent in-agent dashboard, custom interface behavior, or an event handler that existing settings hooks cannot express. The value comes from a specific mod and its supported environment, rather than from installing the framework alone.
Wait on installing third-party mods if their code or requested capabilities cannot be reviewed, your organization blocks them, or your required UI only runs in a client that cannot render it. A working skill, settings hook, or MCP integration remains a reasonable choice when it already completes the task.
Sources
Source-based research; no hands-on installation, security audit, performance benchmark, or third-party mod evaluation was performed for this update. Launch facts are bound to v2.1.287; compatibility guidance and subsequent fixes were checked on October 4, 2026.
