Claude Mods Explained: What the New Plugin Layer Can Do, and How to Turn On 'You Should Know'

Claude Code 2.1.287, released on 1 October 2026, added two lines to the changelog that are easy to skim past: "Added Claude Mods: plugins may now modify deeper behavior" and "Added You should know, a built-in mod where a side agent watches your back and flags things you or Claude might miss." Behind those lines is a new layer of the plugin system that has been in early access since September, and it changes what a plugin can touch: not just a shell script that fires on an event, but the status line, toasts, a pane beside the transcript, sounds, the system prompt, and the tool calls themselves.

This post explains what a mod is, how it differs from the hooks, skills and plugins you already know, what the built-in "You should know" mod does and how to turn it on, and, because this site is about knowing when your agent is done, what a mod can and cannot do for notifications. Everything here is based on the 2.1.287 and 2.1.288 builds and the bundled plugin-authoring documentation; the API is explicitly early access and moves between releases, so check the declaration file in your own build before relying on a name.

Hooks, skills, plugins, mods: where mods fit

The existing extension points each live at a different depth. Classic hooks are commands in settings.json that run on lifecycle events such as Stop or PreToolUse; they get JSON on stdin and can block or allow, but they cannot draw anything or keep state across events. Skills and plugins bundle prompts, commands, agents and those classic hooks into something installable. What none of them could do was participate in the interface or in the engine's own decisions.

A mod is a plugin whose hooks are functions rather than commands. The plugin folder gains a hooks/hooks.json that names one TypeScript or JavaScript module, and that module exports a single function, register(on, options). Inside it you call on(event, matcher, hook) to subscribe to engine events, and every hook has the same shape: ($, e, next). e is the event's input, next(e) passes it on to the other plugins and then the engine, and $ is the engine interface, the only way out of the module's sandbox, because a mod runs with no DOM and no Node. Through $ a mod reaches the display ($.ui), the clock, the model, the session's messages, the filesystem, processes, audio, and settings.

Three things make this "deeper" than a classic hook. A mod can answer an event itself instead of calling next, which is how it denies a tool call or replaces what the engine would have drawn. It can rewrite the event on the way through, by calling next({ ...e, command: e.command.trim() }) for example. And it can keep state: in $.state for the session and $.store across sessions, with a small type contract so claude plugin validate can check the keys.

What a mod can draw and do

• Status line text. $.ui.status(text) from any hook; undefined clears it. The bundled example sets it to failed: <command> when a Bash call errors.
• Toasts. $.ui.toast(text). The bundled band example toasts "That turn took 140s" from a turn.complete hook when a turn ran longer than two minutes.
• A band above the prompt or a full pane. A ui.render hook returns a small JSX tree (Box, Text, Button, resolved per surface, so the same mod draws in the terminal, the desktop app, VS Code and mobile). A pane is opened with $.ui.open({ id, title }).
• Sound. $.audio.play({ asset }), the asset being a file shipped inside the mod.
• Tool calls. on('tool.call', { tool: 'Edit' }, ...) can deny an edit to .env, rewrite a command, or await the result and react to it.
• Prompts. prompt.submit sees and can rewrite what you typed; prompt.compose can add, replace or drop sections of the system prompt.
• Slash commands. $.command.register({ name, description }) in session.start, answered by a command.run hook.

The events cover the turn's start, steps and completion, the session's start and end, tool calls, what the interface draws, and, usefully for migration, the classic hook events themselves as classic.Stop, classic.SessionEnd and so on, with e being exactly what the shell hook would have received on stdin.

The smallest useful mod

Three files. .claude-plugin/plugin.json with a name, version and description; hooks/hooks.json containing { "modules": ["./register.ts"] }; and the module. This one puts a toast and a status-line note on the screen when a turn finishes, which is the terminal-local cousin of a done notification:

import type { Register } from 'claude-code'

export const register: Register = (on) => {
  let startedAt = 0

  on('turn.start', async ($, e, next) => {
    startedAt = await $.clock.now()
    $.ui.status(undefined)
    return next(e)
  })

  on('turn.complete', async ($, e, next) => {
    const seconds = Math.round(((await $.clock.now()) - startedAt) / 1000)
    $.ui.status(`last turn: ${seconds}s`)
    if (seconds > 60) $.ui.toast(`Claude is done after ${seconds}s`)
    return next(e)
  })
}

Run claude plugin validate <folder> to have the engine read the manifest and module the way it will at load time and report anything it would refuse. Load it for one session with claude --plugin-dir <folder>; in an interactive session the folder is watched and saving the file hot-reloads the module. claude plugin test <folder> runs any *.test.ts beside it against the engine. There is also a bundled plugin-authoring skill that writes a mod into a per-session folder and asks you, once, whether to enable hot reloading for the session; that is the quickest way to get one running from inside Claude Code.

"You should know": the first built-in mod

The flagship use of the new layer is a mod Anthropic ships inside the CLI. "You should know" runs a side agent alongside your session that watches what you and Claude are doing and surfaces things either of you might have missed: a decision that was made without being mentioned, an assumption that deserves a second look, a detail that was skipped. The 2.1.288 release note describes the notes it writes as saying "we", "the main agent" or "you" depending on who was responsible for a decision, which tells you something about its tone: it is a reviewer, not a linter.

Turning it on is one command:

/plugin enable cc-plugin-you-should-know@builtin

Two conditions apply, and they rule out some readers. It works in first-party sessions only, meaning sessions that talk to Anthropic's own API rather than a gateway or a third-party provider, and it requires telemetry to be on. If your organisation sets DISABLE_TELEMETRY or runs through a gateway, the mod will not run. It is opt-in, so nothing changes until you enable it, and /plugin disables it again.

Is it worth the context? The trade-off is the usual one for a side agent: on long, multi-step tasks where Claude makes many small decisions, a second pair of eyes that says "you should know the migration also dropped an index" can save a bad merge; on short, tightly scoped tasks it is mostly noise, and a side agent is one more thing consuming your usage. Treat it like any other subagent: try it on one real session, then decide.

What this means for notifications

A mod can toast, change the status line and play a sound when a turn completes, which covers the "I am sitting at this terminal but looking at another window" case neatly, with no shell scripts and no terminal-notifier. What a mod cannot do, by design, is reach your phone or a machine you are not sitting at: it runs inside the session's process, with no Node and no network of its own beyond what $ exposes, and it is gone when the session ends. For the "I walked away" case, the classic Stop and Notification hooks, or the newer idle_prompt notification hooks that 2.1.288 fixed to stop firing while background agents are still running, remain the right tool, and they are what our notifications guide and AI Done Now are built on.

Caveats before you build one

• Early access means it moves. The reference itself says the API changes between releases and that the generated declaration file is the authority. Pin your Claude Code version in a team rollout, and re-run claude plugin validate after each update.
• Mods have more reach, so review them harder. A mod that hooks prompt.compose can change the system prompt; one that hooks tool.call can rewrite commands before they run. A plugin from a marketplace that opts into function hooks deserves a read before it is enabled fleet-wide.
• Hot reload is per session and opt-in. The engine asks you, once, before it starts loading a watched folder; no permission mode or hook can answer that question for you.
• Headless sessions load fresh. claude -p loads a mod once and never watches the folder, and nobody is there to answer the hot-reload question, so develop interactively and run headless.

Related reading

If you have not written classic hooks yet, start with the hooks guide; most of what a mod does begins as a shell hook you outgrew. For the other headline change of the same week, Sonnet 5.5 becoming the default Sonnet model and Ultracode becoming its own effort toggle, see our effort levels post.