Claude Code mods: what they are, how to install one, and whether they’re safe

Claude Code mods are plugins that change how Claude Code looks and behaves from the inside: they can add a pane beside your conversation, a band above the prompt, a new /command, or a rule that stops a risky command before it runs. You install one like any other plugin, with /plugin install name@marketplace, or you can simply ask Claude to write one for you. Mods arrived in Claude Code version 2.1.287 on October 1, 2026, are switched on by default, and come with one big warning from Anthropic: a mod “runs with your permissions” and isn’t sandboxed. Here’s what they do, where to find them and how to stay safe.

What are Claude Code mods?

A mod is a Claude Code plugin that contains JavaScript or TypeScript code. Claude Code calls that code whenever something happens, such as Claude reaching for a tool, you sending a prompt, or part of the screen being drawn, and the mod can watch the event, change it, or take it over completely.

That makes mods different from the ways you could already customise Claude Code. Settings hooks, skills, status lines and MCP servers all work from outside. A mod runs inside Claude Code, so it can do things they can’t:

Based on Anthropic’s comparison in the mods overview.

Mods aren’t a separate product or subscription. They are part of Claude Code, so they work wherever you already use it, on a Pro, Max, Team or Enterprise plan or with an API key, in every country where Claude is available.

Claude Code mod examples

You may already be running some. Anthropic built several of Claude Code’s own features as mods: the pane behind /diff, the loader that reads AGENTS.md files, and an optional side agent called You should know, which watches longer tasks and puts a note above the prompt when it spots something you might miss. It is off by default, and you turn it on with /plugin enable cc-plugin-you-should-know@builtin. To see the built-in mods, run /plugin and open the Installed tab, where they are listed under Built-in.

Anthropic also shares three sample mods in its claude-code-playground repository on GitHub, as they are and without support:

• token-weather: draws a “forecast” of how full your context window is above the prompt.
• blast-radius: holds a risky shell command, such as rm -rf, git reset --hard or a force push, shows what it would delete or overwrite, and gives you Proceed and Cancel buttons.
• replay-theater: adds a /replay command that steps through the file edits Claude made in the last turn.

Blast Radius is the kind of guard that might have helped the developer who said Claude Code wiped his C: drive. For more ideas, Anthropic’s documentation suggests a pane that charts your token use after each request, a count of tool calls beside the spinner, and a mod that sends certain requests to a different model.

How to install a Claude Code mod

A mod installs as a plugin, from a marketplace. You type the plugin’s name, an @, then the marketplace’s name:

1. Check your version. In your shell, run claude --version. You need 2.1.287 or later in the terminal; the Code tab of the Claude Desktop app supports mods from 2.1.286 (type /status there to check).
2. Add the marketplace if it isn’t Anthropic’s official one: /plugin marketplace add owner/repo for a GitHub repository, or a full git URL or local folder.
3. Install the mod: in a session, /plugin install name@marketplace; from your shell, claude plugin install name@marketplace.
4. Load it. If you installed from the shell while a session was open, run /reload-plugins in that session. Otherwise it loads next time you start Claude Code.
5. Confirm it’s running. Run /plugin. A dim line under the tabs reads something like 1 mod active · first-mod.

To try a mod for one session without installing it, download its folder (for example with git clone) and start Claude Code with claude --plugin-dir ./that-mod.

Is there a Claude Code mods marketplace?

There is no separate store just for mods. Mods use the same plugin marketplaces as every other Claude Code plugin, and a marketplace is simply a GitHub repository (or other git repository) with a catalogue file in it. Anthropic runs three general ones:

You can browse the official catalogue in the Discover tab of /plugin or on the web at Claude Marketplace, which shows install counts and marks some plugins “Anthropic verified”. Mods on GitHub from other people install the same way once you add their repository as a marketplace, but they haven’t been checked by Anthropic, which is why the next two sections matter.

How to make your own Claude Code mod

You don’t need to write code. Describe what you want in a normal Claude Code session, for example “make a mod that shows the current git branch above the prompt”, and Claude writes it using a built-in skill called plugin-authoring (you can also load it yourself with /plugin-authoring). Anthropic’s guide sets out what happens next:

• Claude saves the mod in ~/.claude/dev-mods/, in a folder named after the session. Claude Code may ask you to approve each file, because ~/.claude is a protected folder.
• Claude Code then asks whether to enable hot reloading. Choose Enable for this session and the mod loads at the end of the turn, and reloads each time Claude changes it.
• A mod Claude writes only loads in that session and is eventually cleaned up. To keep it, copy its folder somewhere of your own, such as ~/mods/git-branch, and start Claude Code with --plugin-dir pointing at it, or add it to a marketplace to share it.

If you’d rather write one by hand, a basic mod is three files: a plugin.json manifest, a hooks.json file, and a register.js or .ts file with your code. There is no build step, and claude plugin validate ./my-mod checks it without starting a session.

Are Claude Code mods safe?

Only as safe as the person who wrote them. Anthropic’s documentation is blunt that a mod “is code that runs with your permissions” and tells you to install mods “only from authors and marketplaces you trust”. Once loaded, a mod can:

• read and write files anywhere your account can, start programs and make network requests;
• read your secrets, including API keys in environment variables or settings files;
• see every prompt you send and every tool call Claude makes, and rewrite them;
• approve a tool call before you are asked;
• spend your usage by calling a model on your plan or API key.

Mods aren’t sandboxed, even if you turn on Claude Code’s sandbox. Two limits do hold: a mod can restyle much of the interface but not the permission prompt, and on Team and Enterprise plans, or any machine with managed settings, a built-in guard stops a mod overriding your deny rules or your organisation’s managed hooks. Watch your usage too, since a mod that calls a model draws from the same limits covered in our guide to making Claude Code usage last.

Before installing someone else’s mod, clone it and run claude plugin validate on the folder. Its hooks: and calls: lines list the events the mod handles and what it asks Claude Code to do, such as reading files or reaching the network, without running any of it.

How to turn Claude Code mods off

• One mod: disable or uninstall it in the Installed tab of /plugin.
• Every installed mod, for one session: start with claude --safe-mode, which also switches off your other customisations.
• Every installed mod, permanently: set "disableAllHooks": true in ~/.claude/settings.json. This also stops your settings hooks and custom status line.

None of these stop the built-in mods, which have their own switches in /plugin. At work, administrators can block user-installed mods or allow only the organisation’s own with the allowManagedModsOnly setting, much as they can switch off Claude subscription access.

Claude Code mod not working?

Work through these, from Anthropic’s troubleshooting page:

• Old version: update Claude Code to 2.1.287 or later.
• Not named in /plugin: if the mods active line doesn’t list it, it didn’t load. Start Claude Code with claude --debug and look for a line ending not loaded: with the reason.
• Check mods can load at all: run claude plugin test in your shell from a folder with no mod in it. “no hooks module to load” means mods work; “hooks modules are turned off here” means disableAllHooks or your organisation is blocking them; “the rollout switch served off” means Anthropic has turned installed mods off remotely.
• Refused by your organisation: a message mentioning allowManagedModsOnly means only your company’s mods may run.
• A typo in the mod: claude plugin validate catches a misspelt event or a broken manifest.
• Nothing appears on screen: check where you are running it (below).

Where Claude Code mods work

From Anthropic’s mods overview.

So a mod that guards commands works almost everywhere, while one that draws a pane needs the terminal or the Desktop app.

Do Claude Code mods work in the cloud?

Only in a limited way for now. A cloud session, the kind you start at claude.ai/code, in the Claude mobile app or from the Desktop app, will run a mod’s code, but nothing the mod draws appears there, and getting the mod into the session is the hard part. Anthropic’s cloud documentation says a cloud session starts from a fresh copy of your repository, and:

• There is no plugin browser, so you can’t run /plugin install there.
• Mods you installed on your own computer don’t come with you. They live in your user settings, which stay on your machine.
• Turning a plugin on in your repository doesn’t work either. Cloud sessions ignore the plugins and marketplaces listed in a repository’s .claude/settings.json.

The route Anthropic documents is through your organisation. On Team and Enterprise plans, an owner can set plugins in Organization settings › Claude Code › Managed settings on claude.ai, and a cloud session fetches those settings before it installs plugins. Anthropic’s documentation doesn’t describe a way for Pro or Max users to add their own mod to a cloud session.

Two workarounds get you most of the way:

• Use Remote Control. Start Claude Code on your own computer and steer it from claude.ai or your phone. Your mods run on your machine as normal, and their panes show in its terminal.
• Use a settings hook for guard rails. If all you want is to block risky commands, a settings hook committed to your repository’s .claude/settings.json does carry over to cloud sessions that use one repository, unlike a mod.

Last checked: October 9, 2026, against Claude Code 2.1.296 and Anthropic’s mods documentation.

Frequently asked questions

What are Claude Code mods?

Mods are Claude Code plugins containing JavaScript or TypeScript code that runs inside Claude Code. They can add panes, buttons and commands, change how the interface looks, and watch, rewrite or block tool calls and prompts. They arrived in Claude Code 2.1.287 on October 1, 2026.

How do I install a Claude Code mod?

Add the mod’s marketplace if needed with /plugin marketplace add owner/repo, then run /plugin install name@marketplace in a session, or claude plugin install name@marketplace in your shell. Run /reload-plugins if a session was already open.

Is there a Claude Code mods marketplace?

Not a separate one. Mods are plugins, so they come from the same plugin marketplaces: Anthropic’s official one (claude-plugins-official), its community one (claude-community), or any GitHub repository set up as a marketplace.

Where can I download Claude Code mods from GitHub?

Anthropic’s three sample mods, token-weather, blast-radius and replay-theater, are in the claude-code/mods folder of its claude-code-playground repository. Clone it and run claude --plugin-dir with a mod’s folder to try one for a session.

Are Claude Code mods safe?

Only if you trust the author. Mods run with your permissions and aren’t sandboxed, so they can read your files and API keys, see your prompts and approve tool calls. Run claude plugin validate on a mod’s folder first to see what it does.

Do Claude Code mods cost anything?

Mods are part of Claude Code and don’t cost extra, but a mod that calls a model uses your plan’s usage or your API key, just as Claude does.

Do mods work in VS Code?

Partly. In the VS Code extension’s chat panel a mod’s code runs, but anything it draws, such as a pane, doesn’t appear. Drawings show in the terminal, including VS Code’s integrated terminal, and in the Claude Desktop app’s Code tab.

How do I turn off Claude Code mods?

Disable one in the Installed tab of /plugin, start a session with claude --safe-mode to skip all installed mods, or set "disableAllHooks": true in ~/.claude/settings.json to stop them every time.

Why is my Claude Code mod not working?

Check you are on Claude Code 2.1.287 or later, that /plugin names the mod as active, and run claude plugin test to see whether a setting, your organisation or Anthropic has turned mods off. claude --debug shows the reason a mod didn’t load.

Do Claude Code mods work in the cloud?

Partly. A cloud session runs a mod’s code but shows nothing it draws, and it doesn’t load mods installed on your computer or turned on in your repository. On Team and Enterprise plans an owner can add plugins through managed settings on claude.ai; otherwise use Remote Control to run Claude Code, and your mods, on your own machine.

Sources: Anthropic’s Claude Code documentation (mods overview, create a mod, troubleshoot a mod, manage mods for your organization, Anthropic’s marketplaces, cloud environments), Claude Code changelog, Anthropic sample mods.