Claude Code mods getting started: in-session hooks, custom UI, default-on at 2.1.287

Anthropic published Getting started with Claude Code mods on Oct 1, 2026 (Addy Osmani): the developer guide for Claude Code mods—in-session JavaScript or TypeScript plugins that sit in a hooks middleware chain and can observe, rewrite, or answer tool and UI events.

This is the platform story, not a version-bump note. Companion same-day: npm @anthropic-ai/[email protected] and CHANGELOG ## 2.1.287 (“Added Claude Mods…”). The guide is explicit: Claude Code 2.1.287 or later; mods are on by default—nothing to turn on.

What a mod is

Per the primary: under the hood, mods are hooks that ship inside plugins. Each mod is a small JS/TS module that runs inside your session and sees events as they happen—tool calls, prompt, turns, session, slash commands, and ui.render. A hook can pass the event along (next), change it, or answer without calling next (for example deny, or serve a result).

Mods can also draw custom UI. The guide demos an AbovePrompt band (above the prompt) and panes opened via $.ui.open. Put durable session data in host-held $.state—module-level variables reset on hot reload; $.state survives it. On each load, Claude Code writes type declarations into the mod’s .claude-plugin/types/ folder; those are the authority for that build.

Walkthrough examples

Osmani’s guide walks three demos:

• Token Weather — context-window forecast in an AbovePrompt band
• Blast Radius — holds a risky Bash command and opens a pane with Proceed/Cancel (a safety net that reads command text—not a hard permission system; Anthropic notes aliases and scripts can still get past)
• Replay Theater — step through the last turn’s Edit/Write diffs (related to the /diff pane pattern)

Built-ins ship as mods

Claude Code uses the same system for some of its own features. Source for built-ins—including AGENTS.md support (agents-md) and the /diff pane (diff)—lives in the public anthropics/claude-code mods/ tree, with tests. Earlier ATN coverage tracked AGENTS.md via Mods; today’s guide is the full getting-started platform piece with default-on at 2.1.287+.

API still moving; install like a package

Anthropic states the API can change between releases. Treat types under .claude-plugin/types/ as the contract for your build, not a frozen public API.

On sharing and install, Anthropic’s warning (paraphrased): a mod is code that runs inside Claude Code on your machine with the same access Claude Code has, written by its publisher, not Anthropic—read the repo first and only install from people you trust. This desk does not audit third-party mods. No paid mod marketplace SKUs were confirmed on this pass; directory submit for plugins that include mods is still framed as future (“once the Claude directory accepts…”).

Who should care

Builders extending Claude Code in-session—custom UI, tool middleware, or hot-reload-friendly state—start at the Osmani guide, confirm claude --version is 2.1.287+, and read first-party examples under mods/. Prefer primary + npm + CHANGELOG over secondary rollout write-ups.