The Claude Code logo. Image: Anthropic
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.
Jump to:
[What are mods](#what)
[Mod examples](#examples)
[How to install a mod](#install)
[Marketplace and GitHub](#marketplace)
[Make your own](#make)
[Are mods safe?](#safe)
[Turn mods off](#off)
[Mod not working](#fix)
[Where mods work](#where)
[FAQ](#faq)
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:
| Mod | Settings hook | Skill | MCP server | |
|---|---|---|---|---|
| What it is | Code inside a plugin that runs in Claude Code itself | A shell command, web request or prompt run on an event | A SKILL.md file of instructions |
An outside service that gives Claude tools |
| Can draw on screen | Yes | No | No | No |
| Written in | JavaScript or TypeScript | Any script | Markdown | Any language |
| Pick it for | A pane, a custom command, rewriting an event | Blocking or logging an event with a script | Instructions you keep repeating | Reaching an outside system |
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 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 --hardor a force push, shows what it would delete or overwrite, and gives youProceed andCancel buttons. - replay-theater: adds a
/replaycommand 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:
- 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/statusthere to check). - Add the marketplace if it isn’t Anthropic’s official one:
/plugin marketplace add owner/repofor a GitHub repository, or a full git URL or local folder. - Install the mod: in a session,
/plugin install name@marketplace; from your shell,claude plugin install name@marketplace. - Load it. If you installed from the shell while a session was open, run
/reload-pluginsin that session. Otherwise it loads next time you start Claude Code. - Confirm it’s running. Run
/plugin. A dim line under the tabs reads something like1 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:
| Marketplace | Name after @ | How you get it |
|---|---|---|
| Official | claude-plugins-official |
Added automatically the first time you open Claude Code in a terminal |
| Community | claude-community |
/plugin marketplace add anthropics/claude-plugins-community |
| Demo | claude-code-plugins |
/plugin marketplace add anthropics/claude-code |
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~/.claudeis a protected folder. - Claude Code then asks whether to enable hot re. 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-dirpointing 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 theInstalled 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": truein~/.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 activeline doesn’t list it, it didn’t load. Start Claude Code withclaude --debugand look for a line endingnot loaded:with the reason. -
Check mods can load at all: run
claude plugin testin your shell from a folder with no mod in it. “no hooks module to load” means mods work; “hooks modules are turned off here” meansdisableAllHooksor 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
allowManagedModsOnlymeans only your company’s mods may run. -
A typo in the mod:
claude plugin validatecatches a misspelt event or a broken manifest. -
Nothing appears on screen: check where you are running it (below).
Where Claude Code mods work #
| Where you run Claude Code | Mod code runs | Panes and drawings show |
|---|---|---|
| Terminal (including JetBrains) | Yes | Yes |
| Claude Desktop, Code tab | Yes | Mostly |
| Claude Desktop, WSL session | No | No |
| VS Code extension chat panel | Yes | No |
claude -p and the Agent SDK |
Yes | No |
| Cloud sessions | If the plugin reaches the session | No |
From Anthropic’s mods overview. Remote Control runs mods on your own machine and shows drawings in its terminal. So a mod that guards commands works almost everywhere, while one that draws a pane needs the terminal or the Desktop app. Our guide to cloud sessions versus local explains the difference between the two.
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.
Sources: Anthropic’s Claude Code documentation (mods overview, create a mod, troubleshoot a mod, manage mods for your organization, Anthropic’s marketplaces), Claude Code changelog, Anthropic sample mods.