Claude Code mods: plugins that can rewrite what Claude Code does

Claude Code could already be customized through settings, permission rules, slash commands, skills and a status line. Claude Code 2.1.287, released on October 1, adds a deeper layer: mods. The release notes say plugins “may now modify deeper behavior.” The same day, Anthropic’s developer blog published a tutorial by Addy Osmani that builds one from an empty folder. This article summarizes what mods are, what the tutorial builds and what to watch. We read the tutorial and Anthropic’s public source and did not build or run these mods ourselves.

What a mod is

A mod is a Claude Code plugin whose behavior lives in a JavaScript or TypeScript module. The tutorial describes the layout: a normal plugin with a .claude-plugin/plugin.json manifest, a hooks/hooks.json that names one module, and a module that exports register(on, options). Inside it, on(event, matcher?, hook) adds a hook, and every hook has the same shape: it receives $ (the mods API), e (the event’s input) and next.

Hooks form a chain like middleware. Your hook runs, next(e) passes the event to other plugins and then to Claude Code’s own behavior, and a hook can do one of three things:

Move	How	Example
Observe	call next(e), then look at the result	Record every file edit, take a reading after each turn
Rewrite	call next({ ...e, command })	Change what the rest of the chain sees
Answer	return { deny: "…" } without calling next	Refuse a tool call, or serve a command or tool yourself

The events cover tool calls, the prompt as submitted, turns starting and finishing, the session starting and ending, slash commands, and ui.render, which is every part of the interface as it is drawn. The module runs in a sandbox with no DOM and no Node, so everything outside it goes through $, which exposes ui, session, state, store, fs, process, clock, http, tool, command, model and more.

How it differs from settings hooks

A settings hook runs a shell command for each event and passes JSON over stdin and stdout. A mod is loaded once and stays in the session, so it can keep state, draw UI that updates as events happen, and call back into Claude Code to open a pane, run a process, register a slash command or register a tool the model can call. Anthropic also says some of Claude Code’s own features are built as mods, including AGENTS.md support and the /diff pane. Their source is public in the mods folder of the repository, which also holds sec-default and telemetry.

The tutorial’s three mods

Token Weather reads how full the context window is after each turn and draws one line above the prompt: a weather icon and word (Clear under 25%, Cloudy, Showers, Storm from 75%, Compact soon from 90%), the percentage, the tokens used out of the window, a small chart of recent turns and how much the last turn added. It is about 80 lines. The tutorial also offers a shortcut: paste a prompt into Claude Code and let it write the mod for you.

Blast Radius holds a Bash call when the command is something like rm -rf, git reset --hard, git clean, a force push or a database migration. It works out what the command would touch, using the tools’ own dry runs such as git status --porcelain and git clean -n, and opens a pane with Proceed and Cancel. Cancel returns a refusal with the reason to Claude. It uses the “answer” move above.

Replay Theater records every Edit and Write call during a turn, with the file and the text before and after. When the turn ends, pressing r or typing /replay opens a pane that walks through the edits one diff at a time. It never blocks or changes an edit; it only observes.

Trying one

The tutorial requires Claude Code 2.1.287 or later and says mods are on by default. You load a mod from a folder with claude --plugin-dir ./token-weather, and saving the file reloads the module in place. claude plugin validate checks the manifest and the module, and claude plugin test runs the plugin’s tests against the real runtime. Sharing works like any plugin: put the mod in a marketplace, a folder or a GitHub repository with a .claude-plugin/marketplace.json, then /plugin marketplace add, /plugin install and /reload-plugins. For plugins in general, see our note on Claude Marketplace.

Two practical details from the tutorial: keep data in $.state rather than in module variables, because every save reloads the module and resets them, and a hook has 10 seconds of its own time per dispatch, though time spent waiting inside a $ call does not count against it. Anthropic warns that the API can change between releases and that the type declarations Claude Code writes into the mod’s .claude-plugin/types/ folder are the authority for your version.

What to be careful about

• A mod is code with Claude Code’s access. Anthropic says a mod runs on your machine “with the same access Claude Code has, and it’s written by its publisher, not Anthropic,” and advises reading the repository first and installing only from people you trust. A mod can see every event and can rewrite or answer tool calls, which is what makes it powerful and also what makes an untrusted one risky.
• A guard mod is not a permission system. The tutorial says Blast Radius reads the command text, so $(…), aliases and scripts that call rm get past it, and recommends permission rules for a hard block.
• Organizations have a layer above mods. The sec-default mod in the repository keeps an organization’s classic hooks, managed settings, tool policy and deny rules out of reach of the plugins a person installs. According to its description it sits outermost on a machine with managed settings or for Team and Enterprise organizations, unless managed prependPlugins says otherwise.
• Sharing and discovery go through the Claude directory. Anthropic’s launch post says plugins that include mods can be installed from the Claude directory or with /plugin in the CLI, and that you share a mod by packaging it in a plugin and submitting it to the directory. The tutorial gives claude.ai/directory/manage as the submission address. A link to your own marketplace also still works.

The release notes also list a built-in mod called “You should know,” where a side agent flags things you or Claude might miss. It is enabled with /plugin enable cc-plugin-you-should-know@builtin and is described as for first-party sessions with telemetry on. We did not try it.

Editorial review: October 1, 2026 (AI). Prepared from Anthropic’s tutorial on claude.dev, read in full the same day, the v2.1.287 release notes and the public mods folder README. We did not build, run or test any mod. Images are Anthropic’s, reproduced with credit and a link to the source.

Correction, October 3, 2026: an earlier version of this article said the Claude directory did not yet accept plugins that include mods. Anthropic’s launch post and tutorial say it does, and we have corrected the sentence above.