- Claude Code 2.1.287 arrived on October 1 with Claude Mods, allowing JavaScript and TypeScript plugins to hook into prompts, tool calls, permissions and the interface.
- Mods ship as plugins and run with the user's permissions; they are not sandboxed and can access files, processes, network requests and secrets such as API keys.
- Security controls include load order, the sec-default guard for Team and Enterprise or managed machines, allowManagedModsOnly, claude plugin validate, --safe-mode and disableAllHooks.
- Anthropic's sample mods include TokenWeather, Blast Radius and Replay Theater, while official features such as /diff and AGENTS.md support are already mod-based.
Anthropic has added Claude Mods to Claude Code 2.1.287, a version that reached npm on October 1. The feature lets plugins built with JavaScript or TypeScript connect to internal events in the coding agent, so they can watch what happens and change the outcome.
The company describes mods as a deeper layer than earlier customization options. They are installed as plugins and are meant to work in both the command-line interface and the desktop app. Anthropic’s own documentation warns that mods run with the user’s permissions, which puts the feature at the center of a broader debate about extensibility, trust and control.
What mods can alter inside Claude Code
A mod is driven by event handlers. Claude Code emits events when it calls a tool, receives a prompt, asks for permission or redraws part of the screen. A handler can observe an event, modify it or take it over, according to the documentation. That gives authors the ability to rewrite a prompt before it reaches the model, block or rewrite a tool call, handle permission requests, replace interface elements or add new features.
Developers already had ways to personalize the tool: settings files, persistent instructions in CLAUDE.md, hooks, MCP servers, status lines and output styles. Those methods could influence instructions, permissions and available tools, but they could not replace built-in features or reshape the interface. Mods are designed to go further by sitting on the same event layer that decides how prompts, tool output and permissions move through the system.
The mechanism was first discussed publicly on GitHub in early September under the name function hooks. Anthropic later rebranded the idea as Claude Mods while keeping function hooks as the technical foundation. Mods are enabled by default in version 2.1.287 and later, and their code remains active throughout a session, which allows them to remember state between events and support live panels, commands, processes or tools exposed to the model.
Anthropic is already using the architecture for some of its own work. The /diff pane and AGENTS.md support are described as mod-based, and their source has been published in the Claude Code repository. The /diff feature now ships as a mod that can be disabled or replaced. The company has said it plans to move more built-in features onto this layer over time, pointing toward a smaller core that the ecosystem can modify.
Boris Cherny, the creator of Claude Code, framed the change around individual workflows. He said on X that people approach work differently, so there is little reason for every user to have an identical experience with the agent. His description presents mods as a way to change both appearance and behavior through a simple request, then package those changes as plugins that others can install. Addy Osmani, a member of Anthropic’s technical staff, made a similar point in a blog post: mods let developers shape the tool to fit how they work rather than accepting one fixed setup.
Security boundaries, sandboxing and permission prompts
The most sensitive part of the launch is access. Anthropic states that mods are not sandboxed. If sandboxing is turned on, it isolates the Bash commands that Claude runs, but a process started by a mod runs outside that isolation. A mod can read and write files, launch processes and make network requests. It can also inspect environment variables and settings files, including an API key stored in either location. The documentation tells users to install mods only from authors and marketplaces they trust.
There is one boundary Anthropic draws clearly. A mod can restyle much of Claude Code’s interface, but it cannot change the permission prompt or what that prompt displays. The approval dialogue remains Claude Code’s own, no matter how much of the surrounding UI a mod redraws. At the same time, a mod that can approve tool calls may approve an action that a normal ask rule would question, or one that a user’s PreToolUse hook had blocked.
When multiple mods hook the same event, load order matters. They run in the sequence they load, and the first one loaded sees the event first while receiving the final result last. On Team and Enterprise plans, and on any machine with managed settings, an Anthropic-built mod called sec-default loads before user-installed mods. It is intended to stop risky behavior such as overriding permission-deny rules, and Anthropic says its source can be inspected. Administrators may load their own mods first instead, but the company advises them to include sec-default in that list to keep its restrictions.
Outside those guarded environments, mods can override some permission decisions. The plugin marketplace is also subject to controls: Team and Enterprise owners configure it in the admin console, while administrators on Claude API and third-party API plans push managed settings to machines. That turns a rollout question into a governance question: which mods load first, and who decides that order>.
Installing, validating and turning mods off
Mods are distributed like plugins and can be shared through plugin marketplaces, including GitHub repositories. Before loading one, administrators or users can run claude plugin validate against a plugin’s directory. The command lists the events the mod handles and the actions it requests, such as reading a file or making a network request, without executing the code. Anthropic’s guidance is to inspect a mod’s hooks before installation rather than after.
There are several ways to disable the feature. A single plugin can be disabled or uninstalled from the Installed tab in /plugin. Starting a session with –safe-mode turns off mods along with other customizations. Setting disableAllHooks to true in ~/.claude/settings.json provides another switch. Organizations have a separate control, allowManagedModsOnly, which prevents user-installed mods from loading while the rest of each plugin, including skills, commands, agents and MCP servers, continues to work.
Version availability is not uniform. Mods require Claude Code 2.1.287 or later and are on by default there, but on October 2 the npm registry’s stable tag still pointed to 2.1.285. The latest and next tags pointed to 2.1.287, meaning a machine that follows only the stable channel may not have mods yet. The earlier 2.1.286 release had arrived on September 30 with fixes related to secret redaction.
Mods run wherever a session loads the plugin. That includes the VS Code extension’s chat panel, claude -p, the Agent SDK and a cloud session for a plugin that reaches one. Only the terminal and the Code tab in the desktop app draw a mod’s panes and bands. A WSL session in the desktop app renders neither because plugins are not available there. Checking the actual build and installation channel is therefore necessary before assuming the feature is active.
Example mods and early experiments
Anthropic has published three sample mods in its claude-code-playground repository and shared them as-is without support. TokenWeather draws a context-window forecast above the prompt. It moves from Clear at 18 percent of a 200,000-token window to Showers at 67 percent and Storm at 81 percent, while also showing recent usage and how many tokens the latest turn added. Blast Radius holds a risky shell command such as rm -rf or a force push and shows what the command would change. Replay Theater adds a /replay command that steps through the file edits Claude made in the previous turn inside a docked pane.
Those examples run with the same user permissions as any other mod, which is why the documentation repeats the warning to inspect hooks before installation. Users began experimenting within hours of the announcement. One developer built a mod for passing credentials to Claude without leaving the underlying secret in the conversation history. Other ideas include live displays for the number of tool calls, elapsed time and token consumption, followed by a summary when a task ends.
There is also a self-modification angle. A user can ask Claude Code to create a mod, and the agent can write the TypeScript, install the plugin and hot-reload it in the same session. The tool can therefore rewrite some of the rules it operates under as part of a normal workflow. For compliance and review teams, that shifts the audit target: the relevant artifact is not only what a developer deployed, but also what the model authored and executed at runtime.
For enterprise rollouts, plugin enablement deserves its own approval step. Teams should record the plugin version, its permissions, who enabled it and how to disable it. The launch announcement does not include an independent security review, an audit, adoption or install figures, or pricing. It is also a vendor product post, and it does not report a vulnerability or an incident. The absence of those details means organizations must validate mods against their own policy, observability and change-management processes.
Taken together, Claude Code mods turn plugins into an extension layer that can touch prompts, tool calls, interface elements and permission decisions while running with the user’s own access and outside the Bash sandbox. The safeguards depend on trust, validation, load order and enterprise controls such as sec-default and allowManagedModsOnly. Because the stable npm tag still lagged at 2.1.285 on October 2, teams should verify the actual build before assuming mods are available. The practical question is less whether mods are useful than who can author them, which ones load first and how their changes are reviewed.
