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. Updated October 5, 2026 with Mark Kashef’s video on two advanced mods, one for Codex computer use and one for running parallel Claude sessions.

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.

Two Advanced Mods: Codex Computer Use and Threads (Video)

The example mods above are small. On October 5, 2026, Mark Kashef published a 15 minute walkthrough of two much larger ones, both built by prompting Claude Code. They show how far a mod can go when the goal is to add a feature Claude Code does not have. He shares the source code and the full build prompts through a link in the video description.

01:57 Mod one: Claude decides, Codex clicks

The first mod lets Claude Code drive Mac apps through the computer-use tools that ship with the Codex desktop app. In the demo Claude opens the calculator, works out a subscription cost, and writes the result into a formatted text document, without taking over the mouse. Claude chooses each step and Codex carries it out, and what Codex sees on screen is passed back to Claude before the next step. A slash command turns the mod on or off, so Claude can still use its own browser when that suits the job better.

It works because the Codex tools can be reached as an MCP server. Kashef had Claude watch the Codex app during a computer-use run to find the services involved. The finished mod has two parts:

A launcher. A script that finds and connects to the computer-use MCP server in the latest installed version of the Codex app, so an app update does not break the link.
A helper. A small local program that holds the connection open and answers the approval requests coming from the Codex side.

He adds his own gate in front of that: the first time the mod touches an app, it asks him to allow it for this chat, always allow it, or refuse. The mod runs on his existing Codex subscription, with no separate API bill. It did not work on the first attempt. He says it took about an hour of errors and retries.

07:21 Mod two: Threads, one chat that runs a team

The second mod copies a Codex feature he wanted in the Claude desktop app. One lead chat starts several separate Claude Code sessions, each on the model chosen for its part of the job, and collects their answers into a single reply. A pane on the right lists every thread with its model, its progress and its API-equivalent cost, and has controls for steering all of them from one place. Asked without the mod, Claude says the most it can do is run subagents on a chosen model.

The build prompt is worth studying for its order of work:

Load the plugin authoring skill first, so Claude rereads how mods work before writing anything.
Tell Claude to check the installed mod API and the CLI help before it declares a feature impossible. Kashef points it at claude --help to see which models and options exist.
Make each helper a normal Claude Code session with a name, a model, an effort level, a place in the sidebar and no permission prompts.
Hand work down by cost: plan with Opus, pass the notes to a Sonnet helper, finish with a Haiku check.
Use the goal command to test in stages: one thread from start to finish, then two, then more. He warns that this uses a lot of tokens.

14:40 What to take from it

Two lessons carry over to any mod. The first is that Claude often says a feature cannot be built until it is made to look at the tools it really has. Having it observe another app at work, or read its own help output, was what unlocked both builds. The second is that large mods get finished through tests. Each prompt ends with a list of concrete checks, and the calculator task is the simplest end-to-end test he could think of.

Read both against the security section below. The helper in the first mod answers permission requests so nobody has to click, and the Threads helpers skip permission prompts entirely. That is the convenience the mods exist for, and it is also the behavior that deserves the closest review. Both depend on the internals of desktop apps that change often, so expect them to need repair after updates. If you take his code, read it before you install it, as you would with any other mod.

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.

Can a mod add a feature Claude Code does not have?

Often, yes. Mark Kashef built one mod that lets Claude Code control Mac apps through Codex computer use, and another that lets one chat run several Claude sessions on different models. Both took repeated attempts and staged testing to get working.

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

“Claude essentially became the brain with access to the limbs of Codex.”
Mark Kashef, on his Codex computer-use mod

“Did I take this one prompt and have it oneshot it and work on the first time? Absolutely not.”
Mark Kashef, on what it took to build the mod

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