Claude Code 2.1.287 Introduces Mods: JavaScript Plugins With Same Privileges as the CLI Itself

Anthropic's October 1 release (Claude Code 2.1.287) introduces Mods: in-process JavaScript/TypeScript plugins that run inside the Claude Code session with the same machine access as the CLI itself, enabled by default.

How Mods work

Mods hook runtime events—seven exist; the four most used are tool.call, prompt.submit, prompt.compose, and ui.render. Each handler receives an event, a next continuation, and a capabilities object $. A handler has exactly three possible actions:

• Observe: call await next(e) and return the downstream result unchanged.
• Rewrite: pass a modified event to next.
• Answer: return without calling next, vetoing the action or implementing it itself—meaning a plugin can replace slash commands or even implement a tool.

Mods on the same event form a middleware chain in load order (Express/Koa style); the first-loaded Mod sees the event first and receives the final result last.

Anthropic converted four of its own built-ins into Mods: sec-default, diff, telemetry, and agents-md. The /diff sidebar and the AGENTS.md loader are now plugins with source published in the main repository—product features and third-party extensions now live on the same extension layer.

Official examples are deliberately small

• Token Weather (~80 lines): a status line above the prompt showing context percentage, token/window ratio, a 12-turn sparkline, and last-turn delta.
• Blast Radius: intercepts Bash calls, flags dangerous commands like rm -rf or git reset --hard, runs a dry-run, and shows a Proceed/Cancel panel (a demo rm -rf build lists nine files, 1.1 MB).
• Replay Theater: records every file edit per turn and registers a /replay command to step through diffs.

Self-authored Mods and hot reload

You can describe a Mod in natural language and have Claude Code write and install it in the same session. Files live in ~/.claude/dev-mods/; hot reload re-runs register and fires session.start. Module-level variables reset on reload, while $.state persists host-side across reloads.

Requirements: 2.1.287+ (enabled by default; the September 25 preview required CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1). Each load writes a TypeScript declaration to .claude-plugin/types/, which Anthropic calls the authoritative API for that build. Version 2.1.288 (October 2) added $.ui.selection() for full-screen selected text. The README warns the API may change between versions without notice.

Permissions: read this column carefully

Anthropic's own wording: Mods have the same access to your machine as Claude Code itself. They are not sandboxed; only install Mods from trusted sources.

• A Mod on prompt.submit can read and modify every prompt before the model sees it.
• A Mod on tool.call sits between Claude and every action it takes.
• Mitigation: the built-in sec-default Mod loads first on Team/Enterprise plans or any machine with managed settings, preventing user-installed Mods from overriding permission-denial rules. It holds no policy itself; it shields org hooks, managed settings, tool policies, and denial rules from plugins. Because all capabilities flow through $, a first-loaded admin Mod can remove methods before any later plugin runs—ordering itself is the permission model.
• The security review process for Mods submitted to the Claude directory is not publicly documented.

Mods vs. the old settings hooks

| Dimension | settings hooks | Mods | |---|---|---| | Runs | Outside the process | Inside the session | | Rewrite events | No | Yes | | UI | None | Can re-render components | | Privileges | Depends on script | Same level as Claude Code | | Sandbox | N/A | Explicitly none | | Delivery | settings file | Plugin, minimum three files |

Minimal structure: .claude-plugin/plugin.json (manifest), hooks/hooks.json (modules array), register.tsx (logic exporting a single function that uses on(event, matcher?, hook)).

Community Mods appeared within hours: secret redaction on hover, inline Mermaid rendering, custom diff panels, dangerous-command guards, observability dashboards, token burn meters, even games in the terminal.

Context

In the same week: OpenAI's DevDay (Sept 29) introduced Dots persistent agents, Anthropic (Oct 1) split the coding agent into a programmable platform, and Apple (Oct 2) tightened macOS Full Disk Access citing AI agents. All three share a premise: agents are shifting from "you give them a prompt" to "they run resident on your machine manipulating files," so permission boundaries must move from the prompt layer to the code layer.

Three things to watch:

• Anthropic ships no sandbox but offers sec-default as a fallback for managed environments—governance cost pushed to platform teams.
• Opening the UI layer lets third parties reshape Claude Code's interaction model—differentiation and unpredictability at once.
• Official examples sit at 80–150 lines; the question for enterprise security teams shifts from "whether to allow Mods" to "which Mods to audit."

For teams evaluating Claude Code: treat installed Mods with the same scrutiny as locally installed code.

---

Sources and caveats

• Anthropic official announcement; claude-code repository mods README and changelog 2.1.287 / 2.1.288.
• Three in-process capabilities described by Thariq Shihipar (Anthropic Claude Code team) on a podcast.
• Ecosystem details (community Mods, claudemod.com, Claude.dev showcase) from secondary reporting, not individually verified.
• Directory submission review process not verified; noted above.
• Mac Herald's description of sec-default loading conditions corrected per Anthropic: Team and Enterprise plans, or any machine with managed settings.