Claude Code Mods Explained: What They Are and How to Enable Them
Claude Code mods are a plugin capability that shipped on October 1, 2026 with version 2.1.287. The official changelog puts it this way: "Added Claude Mods: plugins may now modify deeper behavior." In practice, plugins can now do more than before, such as drawing UI, intercepting prompts, and stepping in before or after tool calls. The same release also shipped the first built-in mod, called "You should know". Everything below is current as of October 2026 and based on the official Claude Code changelog.
How do mods, hooks and plugins relate?
They nest inside one another rather than sitting side by side.
| Term | Meaning |
|---|---|
| plugin | The unit you distribute and install. It can bundle commands, skills, hooks and more |
| hook | Code that runs at a fixed point, such as prompt.change, agent.spawn or turn.start |
| mod | A plugin that uses the mod API (prefixed with $. in the changelog, e.g. $.ui, $.model). It can draw UI, call models and rewrite prompts |
The changelog keeps talking about "a mod's hook", "a mod's Input" and "a mod's Text", so a mod is essentially a plugin that registers hooks and can render UI elements. That is my reading of the changelog wording; check the official docs for details.
What does the built-in "You should know" mod do?
According to the 2.1.287 changelog, it is a built-in mod where a side-channel agent watches the session and flags things you or Claude may have missed. The enable command from the changelog is:
/plugin enable cc-plugin-you-should-know@builtin
The changelog also notes it applies to "first-party sessions with telemetry on". Two small follow-ups: 2.1.288 (October 2) made the hints use "we", "the main agent" or "you" depending on who makes the decision, and 2.1.290 (October 5) fixed it ignoring the language setting for its output.
What has the mod API gained in the last two weeks?
Mod-related changelog entries, by version (dates as listed in the changelog):
| Version | Date | Change |
|---|---|---|
| 2.1.288 | Oct 2 | $.ui.selection() returns the most recently selected text in fullscreen mode |
| 2.1.292 | Oct 6 | $.model.complete supports prompt caching via cache: true on text blocks; claude plugin install gains --marketplace <source> |
| 2.1.295 | Oct 8 | $.ui.notify sends a native notification through your own notification settings |
| 2.1.299 | Oct 14 | $.prompt.media and $.session.identity(), both aimed at mods installed through managed settings |
| 2.1.300 | Oct 14 | New virtualText for prompt decorations; new prompt.change hook; the agent.spawn hook can rewrite a workflow agent's prompt and model |
| 2.1.301 | Oct 15 | Input gains rows for multi-line input: Enter submits, Shift+Enter inserts a newline |
Prompt caching has a direct effect on cost. For how it works, see How to use Claude prompt caching to save money.
How do I install a mod and confirm it works?
- Upgrade to 2.1.287 or later. You need 2.1.292 or later to use
--marketplace. - Install and add the source in one step:
claude plugin install <plugin-name> --marketplace <source>. The changelog says it adds the marketplace first if needed and runs the same policy checks asclaude plugin marketplace add. - Validate with
claude plugin validate. Since 2.1.290, it lists every hook a mod registers at an "interceptable" point and whether it has a.catch(the field isgatingHookswhen you pass--json). - For automated testing you can use
claude plugin test; check the official docs for how to write tests. - Check status in
/plugin. If your organization manages Claude Code through managed settings, that may affect how mods are installed and run; see the official docs.
One known validation case: since 2.1.292, validate rejects modules that read $.state using a redeclared or reassigned top-level var.
How do I start writing my own mod?
Keep it minimal: pick one hook and do one small thing. For example, read the prompt box text in prompt.change and use virtualText to show a hint inside the input that does not become part of the draft. I could not verify the exact file layout or API signatures in the public changelog, so rely on the official docs for those. The 2.1.300 changelog mentions a built-in plugin-authoring skill that handles making and sharing mods, so you can have Claude scaffold one with you.
Run claude plugin validate as soon as you have something, then install it into a throwaway project first, not your everyday working environment.
What should I check before upgrading?
The mod API has changed many times in three weeks, and some of those changes alter behavior rather than add features. For example, 2.1.301 changed $.env.set to return {} on success and { deny } with a reason when rejected. If you have already written a mod, read the changelog entry by entry before upgrading. cdnping's changes page records line-by-line additions and removals in the official changelog, and you can subscribe by RSS.
How does this relate to the plugin directory?
Anthropic's release notes state that, as of September 25, 2026, you can submit plugins to the Claude directory through a new developer portal and see usage analytics once they are live. That note is about plugins for Claude; whether it applies equally to Claude Code mods is something to confirm in the official documentation.
Related reading
- Pointing Claude Code at a custom endpoint: Configuring custom API endpoints for Claude Code, Codex and OpenCode
- Can't connect after an upgrade: Troubleshooting Claude Code connection timeouts and errors
- Slow responses: What to do when Claude Code is slow
- Quotas and limits: Claude Max 5x vs 20x
If something looks like a service problem, first check whether Claude Code is down and the Anthropic API status.
