Jonathon's AI Wiki

Claude Mods — Plugins That Modify Claude Code's Deeper Behavior

4 min read

Source: ai-research/claude-code-docs-changelog-2026-10-02.md (v2.1.287, October 1, 2026; v2.1.288, October 2, 2026).

Product: Claude Code · Date: 2026-10-01 · Version: v2.1.287+

Claude Mods are a new capability type added to the plugin system in v2.1.287 (October 1, 2026). A Mod is a plugin that modifies Claude Code’s own internal behavior rather than just adding new tools or UI panels. The first published Mod surface is $.ui.selection(), which lets a Mod read the text a user has selected in fullscreen mode.

Key Takeaways

  • Mods are a plugin subtype, not a separate install mechanism — they ship as plugins but declare a mods capability in their manifest.
  • The $.ui.selection() API (v2.1.288) is the first documented Mods surface: returns the text last selected in fullscreen mode and, when the selection is within one transcript row, that row’s data.
  • “You should know” (cc-plugin-you-should-know@builtin) is Anthropic’s own built-in Mod: a side agent that watches your session and surfaces things you or Claude might miss. Enable with /plugin enable cc-plugin-you-should-know@builtin.
  • Mods require first-party sessions with telemetry on for the built-in Anthropic mod; third-party mods follow the standard plugin trust model.
  • Deeper behavior access distinguishes Mods from ordinary plugins. Where a regular plugin can add tools and panels, a Mod can reach into the Claude Code UX loop itself.

What Changed

v2.1.287 — Claude Mods launch

  • The plugin manifest gains a Mods capability type; plugins declaring it can modify behavior Claude Code previously kept internal.
  • Built-in mod: “You should know” — a side agent that watches your session and flags overlooked items. Enable: /plugin enable cc-plugin-you-should-know@builtin. Requirement: first-party session (Anthropic API login) with telemetry on.
  • Plugin-defined agents spawned by name now run with the agent’s own prompt, tools, disallowedTools and effort instead of the defaults (fix in v2.1.288 — this broke on the initial v2.1.287 launch).

v2.1.288 — First Mods API surface

  • $.ui.selection() added as the first documented Mods API call. Returns:
    • The text last selected by the user in fullscreen mode.
    • When the selection falls within a single transcript row, that row’s data.
  • The claude plugin test fix for mods reporting as “turned off remotely” when settings were stale also landed in v2.1.288.

Relationship to Existing Plugin Types

Plugin capabilityWhat it can do
ToolsAdd new tool calls for Claude to invoke
Panes / UIAdd panels in the Claude Code interface
Bands / Status lineAdd status-bar items
Mods (new v2.1.287)Modify Claude Code’s own internal behavior loop

Mods sit above the prior capability set: a Mod can do everything a regular plugin can plus hook into Claude Code’s internal UX and behavior primitives.

Built-in Mod: “You Should Know”

“You should know” is the reference implementation of the Mods capability, shipped by Anthropic. It runs a background side agent that watches the main session and surfaces notes about items the user or Claude might miss.

  • Enable: /plugin enable cc-plugin-you-should-know@builtin
  • Requirement: Anthropic API login (claude.ai or Console); telemetry must be on.
  • Behavior: generates “You should know” notes inline in the conversation when the side agent detects something worth surfacing (exact trigger logic is not documented in the changelog; the feature is listed as first-party).
  • The fix in v2.1.287 that resolved plugin-defined agents running with wrong defaults was also a prerequisite for “You should know” running correctly.

Authoring Mods

Full authoring docs are not yet published (as of the v2.1.288 snapshot). The changelog confirms:

  • Mods are declared in a plugin manifest; no separate package format is introduced.
  • The $.ui.selection() call is the first stable API surface, implying more surfaces will follow.
  • Use claude plugin test to validate a Mod locally; the --remote flag now correctly distinguishes a locally-turned-off Mod from a remotely-turned-off one.
  • The plugin-authoring skill (bundled) covers the manifest format; the Mods capability field is expected to appear in that skill’s docs.

Open Questions

  • What other $.ui.* methods exist or are planned? The changelog names $.ui.selection() as the first; no registry of other Mods API calls is published.
  • Do Mods require a separate manifest declaration beyond capability: mods? The changelog does not document the full manifest schema for the Mods capability.
  • What does “deeper behavior” include? The “You should know” side-agent pattern suggests Mods can run background agents within the same session context, but the boundaries of what a third-party Mod may access are not published.
  • Telemetry requirement for third-party Mods? The cc-plugin-you-should-know@builtin requires telemetry on; whether this applies to all Mods or only to the built-in one is not stated.

Graph View

Backlinks