Claude Code mods launched on October 1, 2026, and in less than a week the community had already published over 1,700 of them. If you follow Anthropic closely, you probably saw the announcement post hit 2.1 million views. What you may not have done yet is build one yourself. This tutorial shows you claude code mods how — step by step, with verified API patterns from the official docs.
Understanding claude code mods how they actually work is the prerequisite for everything else, so that is where this guide begins.
What Claude Code Mods Are (and Why They Are Different from Hooks)
Anthropic introduced mods on October 1 — small TypeScript functions that hook into Claude Code’s internal events and change what the agent does. That might sound like the existing settings hooks, but the distinction matters. The existing hooks could respond to events but not rewrite them or replace features. Claude code mods go further.
A mod is a plugin made of JavaScript or TypeScript functions that Claude Code calls every time an internal event happens — a tool call, a prompt sent, a piece of interface being drawn. The function can simply observe the event, rewrite it before it continues, or replace the expected behavior entirely, for instance by blocking a command. It is the same logic as an Express middleware, applied to the agent’s life cycle.
Claude code mods how they extend functionality: they can rewrite a prompt before it reaches the model, block or retry a tool call, approve or deny a permission request, redact secrets from tool output, and edit or replace interface elements. That is a significantly wider surface than anything previously available to Claude Code plugins.
The Middleware Chain
“When several mods hook the same event, they run in the order they load,” with the first mod to load seeing the event first and the result last. This onion-style execution means you can stack mods from different authors and each one wraps the next.
Requirements Before You Start
Before writing a single line of TypeScript, confirm your environment meets the minimum bar.
- Claude Code version: Claude code mods how they require versioning: you need Claude Code v2.1.287 or later and they are on by default. Run
claude --versionto check. Update if older. - No feature flag needed: The early-access
CLAUDE_CODE_ENABLE_FUNCTION_HOOKSvariable is ignored in these versions, including when set to 0. - Works in both surfaces: Claude code mods ship inside plugins and work in the Claude Code CLI and desktop app.
- VS Code caveat: The VS Code chat panel and
claude -prun hooks but do not show mod panes, so a pane-based mod is invisible there. - TypeScript knowledge: Basic TypeScript is sufficient. Prior knowledge of basic TypeScript and React-style JSX covers the full API.
How a Mod Is Structured
Understanding claude code mods how they are laid out on disk will save you significant debugging time.
A mod needs three files: a manifest, a hooks.json that points to your code, and one TypeScript module that registers the hook. Specifically:
- The folder is a normal plugin with a
.claude-plugin/plugin.jsonmanifest.hooks/hooks.jsonnames one module undermodules. The module exportsregister(on, options). Inside it,on(event, matcher?, hook)adds a hook.
Every hook follows the same three-argument pattern:
on("tool.call", { tool: "Bash" }, async ($, e, next) => {
// $ the mods API: ui, session, state, store, fs, process, clock, http, tool, command, model
// e this event's input, as plain data
// next passes e to other plugins and then to Claude Code's own behavior
return next(e);
});Claude code mods how they register behavior: each mod calls on inside register. on takes the event’s name, an optional matcher (a filter on the event’s fields), and the hook function.
What Events You Can Hook
Twenty events span six areas: Lifecycle (session.start, turn.start, turn.step, turn.complete, engine.create), Tools (PreToolUse, tool.call, tool.describe), UI (ui.render, ui.resolve, ui.press, ui.input, ui.select), Prompting (prompt.submit, prompt.section, prompt.context, skill.prompt), and Agents (agent.offer, agent.spawn).
Step-by-Step: Build a Secret-Redaction Mod
This is one of the clearest practical examples of claude code mods how they handle sensitive data, confirmed in the official documentation ecosystem. The goal is to strip API keys and private keys from tool output before Claude reads them.
Step 1 — Scaffold the Plugin Folder
Create a directory, for example ./redact-secrets, and add the three required files:
.claude-plugin/plugin.json— your manifest with the plugin name and descriptionhooks/hooks.json— points to your module under themoduleskeyhooks/register.ts— the TypeScript module that exportsregister
Step 2 — Write the Hook
Save your hook as hooks/register.ts. Claude code mods how they initialize: Claude Code calls register once when the mod loads, and the tool.call hook runs around every Bash and Read call. Calling await next(e) runs the permission check and the tool; the hook then returns a redacted copy of what came back.
The verified pattern from the official docs ecosystem looks like this:
export const register: Register = (on) => {
on("tool.call", async ($, e, next) => {
const result = await next(e);
// redact known secret patterns from result before Claude sees it
return redact(result);
});
};Common secret patterns to match include /sk-[A-Za-z0-9_-]{20,}/g for OpenAI- and Anthropic-style API keys, /AKIA[0-9A-Z]{16}/g for AWS access key IDs, and /gh[pousr]_[A-Za-z0-9]{36,}/g for GitHub tokens.
Step 3 — Get Type Definitions
Each time Claude Code loads or reloads a mod from a directory you pass to --plugin-dir, it writes TypeScript declaration files ending in .d.ts into .claude-plugin/types/ inside the mod’s directory. They describe the exact events, mods API methods, and elements in the Claude Code version you are running, so your editor can autocomplete and type-check your hooks.
This is the right moment to review the available API namespaces. Claude code mods how they expose the $ object: it provides namespaces including $.plugin (name, root), $.ui (resolve, invalidate, open, close, panes, focus, scroll, toast, status, log, notice, ask, copy, selection, blit), $.command (register, run, list), and $.tool (register, call, check, list).
Step 4 — Load and Hot-Reload
Start a Claude Code session with the --plugin-dir flag pointing at your folder:
claude --plugin-dir ./redact-secretsA directory loaded with --plugin-dir supports hot reloading, so every time you save register.ts the mod reloads without restarting the session. This is the fastest way to iterate on claude code mods how they behave in practice.
Step 5 — Validate and Test
Before sharing or installing in production, run the built-in validator:
claude plugin validateRun claude plugin validate on every plugin before installation. Read the hook source — it is TypeScript, not obfuscated bytecode.
The official testing framework is also available. Import expect and test from claude-code/testing, answer each tool call in Claude Code’s place so no real tool runs, fire synthetic events, and assert the output.
Step 6 — Install for Everyday Use
Once you are happy with the mod, install it as a plugin at the scope that fits your workflow. User scope enables the plugin in every project on the machine; project scope records it in the repository’s .claude/settings.json for collaborators, who still need to install it once; local scope enables it for you in this repository only.
To install an already-published community mod the command is:
claude plugin marketplace add <author/repo>
claude plugin install <mod-name>@<marketplace>After installation, run /reload-plugins in an open session.
Three First-Party Mods Worth Studying
Anthropic converted three of its own built-in features — the diff pane, the AGENTS.md loader, and telemetry — into mods at launch, establishing first-party precedent and marking the system as load-bearing rather than experimental. Reading their source in the Claude Code repository is the fastest way to understand claude code mods how they look at production quality.
The diff mod registers the /diff slash command, monitors Git workspace changes, and renders file lists and code hunks. It subscribes to a broad set of lifecycle events including session.start, command.run, tool.call, turn.complete, and prompt.submit, alongside multiple UI events. This mod demonstrates how extensions can combine command registration, repository inspection, and dynamic UI rendering in a single TypeScript module.
On October 3, 2026, Anthropic also added a built-in plugin called You Should Know. It scans Claude’s output for things you might miss. Enable it with /plugin enable cc-plugin-you-should-know@builtin.
Common Problems with Claude Code Mods (and How to Fix Them)
Mod not loading
You need Claude Code 2.1.287 or later in the terminal; check with claude --version. If your version is correct but the mod still does not appear, confirm that hooks/hooks.json references the correct module filename and that your register function is a named export, not a default export with a different name.
Pane not visible
The VS Code chat panel and claude -p run hooks but do not show mod panes. Switch to the CLI or the Desktop Code tab. Cloud and WSL sessions also do not render panes.
Hook order conflict
Claude code mods how they chain: they execute as an onion-style middleware chain in registration order, making load sequence and inter-mod trust exploitable once a hostile mod enters the chain. If two mods disagree on a permission decision, the one that loaded first wins the outer wrap. Reorder your --plugin-dir calls or adjust scopes to resolve conflicts.
Mod disabled by organization policy
Managed installations load a protective sec-default mod first, and admins can restrict which mods run. You can turn mods off per plugin in /plugin, per session with --safe-mode, or everywhere with disableAllHooks.
Security: The One Thing You Must Not Skip
Understanding claude code mods how they access your machine is non-negotiable before you install anything from a third party.
Mods run with the same access to your machine as Claude Code itself. They are not sandboxed. Anthropic’s docs say a mod runs with your permissions, is not sandboxed, and can approve tool calls; inspect it first with claude plugin validate.
The added control comes with a security tradeoff: claude code mods how they inherit Claude Code’s machine access, though organization marketplace restrictions remain and managed installations load a protective sec-default mod first.
Use --safe-mode when working in sensitive repositories until you trust your plugin stack.
What to Build Next
The community is moving fast. A community catalogue already listed 1,752 mods as of October 4, 2026. A few confirmed directions worth exploring next:
- Production safeguards: claude code mods how they protect environments — a mod can require confirmation before any command touches production config.
- Audit logging: a mod that loads first can record every call that every other mod makes.
- Context-usage visualization: a few lines of TypeScript can add a pane that charts context usage.
- Prompt policy stamping: append a policy line to every prompt before it reaches the model — for example, enforcing that the agent never prints secrets and prefers asking over allowing.
If you are already using Claude Code for automation work, pairing a custom mod with the patterns covered in Claude Code for Business gives you both the workflow structure and the TypeScript hooks to enforce it programmatically. For teams building more complex pipelines, the Claude API tutorial covers the API layer that mods can call out to via the $.http namespace.
Understanding claude code mods how they chain together is ultimately what separates a one-off experiment from a reliable engineering tool. Start with a single tool.call hook, run claude plugin validate before every install, and read the source of Anthropic’s own built-in mods before writing anything more complex. The surface is new enough that the official docs and the .d.ts files Claude generates for your exact version are your most reliable references — use them before any third-party tutorial, including this one.