Claude Code Mods: How to Install, Build and Secure Them (Guide)

Classical fresco style painting of a woman fitting colorful puzzle pieces with code, terminal, layout and settings icons together, illustrating Claude Code mods

Claude Code mods are small TypeScript functions that change how Claude Code behaves, how its UI looks and which features it has, and Anthropic shipped them on October 1, 2026. You can write a mod yourself or ask Claude Code to build one. Mods ship inside plugins and install with /plugin in the CLI or the desktop app. This guide covers what mods are, how they work, how to install and build them, the security rules that matter, and what Team and Enterprise admins should set up first. The details come from Anthropic’s launch post and Addy Osmani’s getting started guide.

TLDR

A mod is a function hook inside a plugin. It loads for the session, listens for events such as tool calls and prompt submits, and can observe, rewrite or answer each one. It can also draw live UI in the terminal and the desktop app. Mods need Claude Code 2.1.287 or later and are on by default. They run with the same access to your machine as Claude Code itself, so install them the way you would install a package: read the source and trust the publisher. On Team and Enterprise plans a built-in mod called sec-default loads first and admins control which marketplaces people can install from.

Thoughts

The interesting part of this launch is not the API. It is that Anthropic is moving its own features onto it. AGENTS.md support and the /diff pane are already built as mods, with source and tests published, and more built-ins are due to follow. Extension APIs that the vendor does not use itself tend to rot. One that carries the product’s own features has to stay working, and it gives everyone a set of reference mods written by the people who designed the system.

The security model deserves more attention than the launch excitement gives it. A code editor extension can read your files. A mod can do that and also rewrite the prompt you typed, change a tool call before it runs, and approve a permission request on your behalf. That last one matters most. The permission prompt is the point where a person stays in the loop with a coding agent, and a mod is allowed to answer it. A careless or hostile mod does not need an exploit. It only needs to be installed. Treat every third-party mod as code with your credentials, because that is what it is.

The load order design is the right answer for companies. The first mod to load sees each event first and sees the result last, so a security default that loads first cannot be quietly undone by something a developer installs later. Individuals get no such backstop. If you work alone, you are the admin, and the review step is yours.

The line that will change daily habits is that Claude Code can mod Claude Code. The cost of a personal tool drops to one descriptive sentence and a few rounds of hot reload. Expect far more small private mods than polished public ones: a confirmation step before production commands, a cost meter, a pane with CI status. The catch is that the API can change between releases. Keep mods small, lean on the generated types for your version, and expect to regenerate them now and then.

What Are Claude Code Mods?

Mods are small TypeScript functions that plug into Claude Code session events. They can do three kinds of things:

Change behavior. Rewrite prompts, wrap tool calls, approve or deny permission requests, redact secrets from tool output.
Customize the UI. Add panes, buttons and inputs, in the terminal, the desktop app or both.
Swap features. Turn off or replace built-ins that have moved to mods, such as /diff.

Under the hood a mod is a function hook inside a plugin. A JavaScript or TypeScript module loads for the session and registers handlers through an exported register function. The module has no DOM and no Node. Everything it does outside itself goes through the mods API, written as $.

That is different from the older settings hooks, which run a shell command and pass JSON over stdin and stdout. A mod stays loaded, keeps state, draws UI that updates as events happen, and calls back into Claude Code to open a pane, run a process, or register a slash command or a tool.

Requirements

Claude Code 2.1.287 or later.
Mods are on by default. There is nothing to turn on.
The API can change between releases. The types written to .claude-plugin/types/ when a plugin loads are the authority for your installed version.

How Mods Work

Plugin layout

A mod plugin is a folder with a few known files:

.claude-plugin/plugin.json for the plugin metadata.
hooks/hooks.json, which names the module file to load.
The module itself, which exports register.
Optional tests (*.test.ts) that run against the real Claude Code runtime.

Registering a hook looks like this:

export function register(on) {
  on("tool.call", { tool: "Bash" }, async ($, e, next) => {
    // $ is the mods API, e is the event, next passes it along
    return next(e);
  });
}

$ is the mods API: ui, session, state, store, fs, process, clock, http, tool, command and model.
e is the event.
next hands the event to Claude Code and to any other mods.

Three moves: observe, rewrite, answer

Observe. Call next, look at the result, return it unchanged.
Rewrite. Call next with a changed event, for example a safer command.
Answer. Return a result such as { deny: "..." } without calling next at all.

The main events are session.start, turn.start, turn.complete, prompt.submit, tool.call, command.run and ui.render. On each one a mod can run before the default behavior, after it, or instead of it.

Load order

Mods run in load order. The first mod to load sees an event first and sees the result last. That stacking is what makes the Team and Enterprise security default work: a mod that loads first can stop a later mod from weakening a rule.

State and hot reload

While you develop, every save reloads the module without a restart. A reload is a fresh load, so module-level variables start over. Keep anything that must survive in $.state. If the UI fails to draw, run claude --debug.

How to Install Claude Code Mods

Install from the Claude directory or with /plugin in the CLI or desktop app. The general form is:

/plugin marketplace add your-org/my-mods
/plugin install token-weather@my-mods
/reload-plugins

The official marketplace, anthropics/claude-plugins-official, is already added. Any other marketplace is a repository or folder with a marketplace.json that you add by name. The same thing works from the shell:

claude plugin marketplace add ./my-mods
claude plugin install token-weather@my-mods --scope user

For development, skip the marketplace and load a local folder:

claude --plugin-dir ./token-weather

Validate and test before you share:

claude plugin validate ./token-weather
claude plugin test ./token-weather

How to Build a Mod

The shortcut: ask Claude Code

Describe the mod in plain language: which event to watch, what to draw, what should happen on Proceed or Cancel.
Let Claude Code scaffold the plugin and the module.
Iterate with hot reload until it does what you want.
Copy the folder out when you want to keep or share it.

The manual path

Create the skeleton: plugin.json, hooks/hooks.json and the module file.
Export register and register the events you care about.
Use $ for UI, state, files, HTTP and tools. Do not reach for Node or the DOM.
Read the types in .claude-plugin/types/ for your installed version.
Run it with claude --plugin-dir while you iterate, then validate and test.

Example mods worth studying

Token Weather (about 80 lines): a forecast of how full the context window is, drawn above the prompt.
Blast Radius: holds a risky Bash call, shows what it would affect, and offers Proceed or Cancel.
Replay Theater: steps through the edits from the last turn.
The built-ins: AGENTS.md support and the /diff pane are mods, and their source is published with tests.

Ideas to try

A cost meter for the session.
Team conventions added on every prompt submit.
A map of the files Claude has read.
A confirmation step before production commands.
A CI status pane beside the conversation.
Audit logging of tool calls.
Secret redaction on tool output.

Security: A Mod Has the Same Access You Do

Mods run with the same access to your machine as Claude Code itself. They are not sandboxed. The module restrictions (no DOM, no Node, everything through $) shape how a mod is written. They do not make a third-party mod safe. A mod can still drive tools, touch the filesystem, answer permission requests and change what you see on screen.

Install from the official marketplace or from publishers you know, and read the source first.
Treat internal mods like production code: review them, pin versions, keep an audit trail.
Do not install a plugin folder from a link you cannot vouch for.
On Team and Enterprise, use the marketplace allow and block lists and leave sec-default loading first.

Team and Enterprise Controls

Marketplace allow and block lists. Admins decide which catalogs people can install from.
A security default that loads first. On Team and Enterprise plans, and on any machine with managed settings, the built-in sec-default mod loads before anything a user installs and stops those mods from doing risky things such as undoing a permission deny rule.
Your own controls. Admins can load their own mods early as well, and should keep sec-default in place.

If you are rolling this out at work, start with one guardrail that pays for itself, such as production command confirmation or secret redaction. Ship it through your approved marketplace, then test the load order on purpose by trying to override a deny rule with a second mod.

Claude Code Mods FAQ

What is a Claude Code mod in one sentence?

A small TypeScript hook, shipped inside a plugin, that can observe, rewrite or answer Claude Code session events and draw its own UI.

When did mods launch and what version do I need?

October 1, 2026. You need Claude Code 2.1.287 or later, and mods are on by default.

Do mods cost extra?

Anthropic has not listed a separate price for mods. They come with Claude Code. The admin controls are part of the Team and Enterprise plans.

Can Claude Code write a mod for me?

Yes. Describe what you want, let it scaffold the plugin, iterate with hot reload, then copy the folder out to keep it.

How is a mod different from a settings hook?

A settings hook runs a shell command and exchanges JSON. A mod stays loaded for the session, keeps state, draws live UI and calls back into Claude Code.

Are mods sandboxed?

No. The module has no DOM and no Node, but a mod has the same access to your machine as Claude Code. Only install mods from sources you trust.

Can I replace built-in features?

Yes, for the built-ins that have already moved to mods, such as /diff. You can turn them off or replace them, and more are expected to move over time.

How do I share a mod with my team?

Publish it as a plugin in a marketplace (a repository with a marketplace.json), have people add the marketplace and install from it, or submit it to the Claude directory.

Notable Quotes

“A mod can run before the event, after it, or instead of it.”
Anthropic launch post, on what a hook is allowed to do

“Mods run with the same access to your machine as Claude Code itself.”
Anthropic launch post, the security line to remember

“You can also use Claude Code to mod Claude Code.”
Anthropic launch post, on asking Claude to build the mod for you

“Mods can rewrite or replace what Claude Code does, and can even draw custom UI.”
Addy Osmani, on how mods go further than earlier plugins

“So install mods the way you’d install a package: read the repo first and only install from people you trust.”
Addy Osmani, on trusting publishers

“Put the history in $.state instead.”
Addy Osmani, on why module variables do not survive a hot reload

Read the full announcement in Anthropic’s Claude Code mods launch post.