You spend your days in Claude Code, and there is always one small thing missing. Seeing how full your context is, for example. Or being stopped before a command that wipes everything.
Claude Code mods, often searched for as "Claude Mods", are plugins that change how it looks and behaves. Anthropic announced them on 1 October 2026.
So let's see what a mod can do, how to get one without writing a line of code, and what it can do on your computer.
What a mod changes in Claude Code
Until then, you tuned Claude Code from the outside: a script ran next to it, or it was handed a file of instructions to read. Neither could touch the screen.
A mod is a plugin (an extension you install in Claude Code) whose code runs inside Claude Code itself.
According to the mods overview in the documentation, that opens up four things:
- Draw its own interface. A pane beside the conversation or a band above the input box, with tabs, buttons and text fields;
- Redraw Claude Code's interface. The row that appears when Claude reads a file, the animated text while it works, the dialog where it asks you a question;
- Step into an action. Hold a command while it asks for your opinion, or answer it without running it;
- Add a command. A
/somethingthat runs your code at once, even while Claude is busy.
To give you an idea, Anthropic shares three sample mods, provided as they are:
- token-weather draws a "forecast" of your context (what Claude keeps in mind from the conversation) above the input box;
- blast-radius holds a risky command, such as
rm -rf, and shows what it would change before letting you decide; - replay-theater adds a
/replaycommand that steps through the file edits of the last answer.
You are probably using a mod already without knowing it. The /diff command, which opens a pane with the changes in progress, is one. So Anthropic builds part of Claude Code with the same tool we all have from here on (mods).
How do you create a Claude Code mod without coding?
What is missing for you? For me, it is the Git branch. I have lost count of the times I let Claude work on the wrong one (and noticed too late...).
You only have to ask in your own words, in an open session (a conversation in progress with Claude Code).
For example "make a mod that shows the Git branch above the input box". The guide to creating a mod describes what follows:
- Claude writes the mod in a folder kept for your session, under
~/.claude/dev-mods/; - Claude Code asks you a question when the first file is saved. (For example "Enable hot reloading for this session?");
- You accept, and the mod loads once Claude has finished answering;
- You ask for a change. The mod reloads at the end of each answer that edits it, with no restart (that is what hot reloading means).
In short, just like skills and routines!
Nothing happens? Check your version with claude --version. At launch, mods needed at least Claude Code 2.1.287 in the terminal, and version 2.1.286 in the desktop app.
If you are new to the tool, our Claude Code course covers sessions, commands and permissions from the start.
A mod written by Claude loads only in the session that created it. Claude Code then deletes that folder after a delay set in your settings. To keep the mod, copy its folder somewhere else (or simply ask it to). 😉
Once the folder is copied, load it at startup with the --plugin-dir flag:
claude --plugin-dir ~/mods/git-branchInstalling a mod written by someone else
A mod installs like any plugin, from a marketplace (a catalogue of plugins):
/plugin install token-chart@your-orgBut before you install a stranger's mod, you had better know what you are handing over.
What a mod can read and do on your machine
Installing a mod is a bit like leaving your keys with a tradesman while you are at work. He comes to put up a shelf, but he has the run of the whole flat.
Anthropic says it plainly: a mod runs with your permissions, and it is not isolated from the rest of the machine.
Once loaded, it can do six things:
- Act as you. Read and write every file your account can open, start programs, send requests over the internet;
- Read your secrets. Your settings files, where people often keep their API keys (the codes that link a program to your account);
- See your session. Every message you send, every action Claude takes;
- Change your session. Rewrite a message, or send one as if you had typed it;
- Decide without you. Approve an action before you are asked;
- Spend your plan. Call a model on your subscription or your API key.
One thing is out of its reach: a mod cannot redraw the permission prompt. What that prompt shows you is therefore always true.
Even if you turn on Claude Code's sandbox (a mode that shuts its commands inside an isolated space), it isolates only the commands Claude runs. A program started by a mod runs outside it.
Reading what a mod does before you install it
You do not have to take the author's word for it (and we would advise against it anyway).
Get the plugin's files, then run this command on its folder. It reads the code without running it.
claude plugin validate ./first-modThe hooks line lists the events the mod listens to. The calls line lists what it asks Claude Code to do. The page written for administrators names the calls to look for.
Call in the calls line | What the mod can do |
|---|---|
$.fs.read, $.fs.write | Read or write your files |
$.process.run | Start a program under your name |
$.http.fetch | Send data over the internet |
$.env.get, $.settings.read | Read your settings, API keys included |
$.model.complete | Call a model on your plan |
$.prompt.submit | Send a message in your place |
A mod that shows the Git branch has no reason to call $.http.fetch. If the line is there, you know you should read the code, or walk away. 😉
Turning off a mod
To turn off a single mod, disable its plugin in the Installed tab of the /plugin command.
If you want to turn them all off for one session only, start claude --safe-mode, which also turns off your other customisations.
If you want that for good, you can also turn them all off once and for all with "disableAllHooks": true in ~/.claude/settings.json.
Mod, hook, skill or MCP server, which one should you pick?
Four mechanisms look alike, and a mod is not always the right one.
If you paste the same instructions into every conversation, you need a skill, which stores those instructions in a file.
| Mechanism | What it is | Can draw on screen | Pick it when |
|---|---|---|---|
| Mod | JavaScript or TypeScript functions that Claude Code calls | Yes | You want a pane, a band, a command, or to change an action |
| Settings hook | A script run at a set moment of the session | No | You already have a script to block, allow or log an action |
| Skill | A file of instructions that Claude reads | No | You keep repeating the same instructions |
| MCP server | An outside program that gives Claude tools | No | Claude has to reach an outside service |
Keep the third column in mind. Only a mod can draw something in Claude Code. For everything else, the other three often do the job, and they are easier to review.
A plugin is a box. It can hold a mod, a skill and an MCP server at the same time. So installing "a plugin" does not tell you what is inside.
Where do mods work?
A mod's code runs almost everywhere its plugin is loaded. What it draws, however, appears only in the terminal and in the desktop app:
| Where you run Claude Code | The mod's code runs | What it draws appears |
|---|---|---|
| Terminal, including an editor's own | Yes | Yes |
| Code tab of the desktop app | Yes | Yes, apart from a few terminal-only elements |
| WSL session (Linux on Windows) in the desktop app | No | No |
| Chat panel of the VS Code extension | Yes | No |
Claude Code run by a script (claude -p, Agent SDK) | Yes | No |
| Cloud session | Yes, if the plugin is loaded there | No |
So if you work in the VS Code extension, a mod that blocks a dangerous command does its job. A mod that opens a pane will show nothing.
In a company, an administrator can limit which mods are allowed. The allowManagedModsOnly setting lets only the organisation's mods load. A mod Claude writes during a session is then refused as well.
What does a mod's code look like?
You do not need to read this part to use a mod. It is here for the curious.
A small mod fits in three files:
plugin.json, which gives the plugin's name and version;hooks.json, which says where your code is;register.js, which holds that code.
Here is a complete register.js, taken from Anthropic's example. It counts Claude's actions and adds the total to the waiting line.
// The counter, shared by both functions
let calls = 0
// Claude Code calls register once, when the mod loads
export function register(on) {
// Before each of Claude's tool calls
on('tool.call', async ($, event, next) => {
calls += 1
// Ask Claude Code to draw the interface again
$.ui.invalidate('ui.render')
// Let the tool run as usual
return next(event)
})
// Each time Claude Code draws the waiting line
on('ui.render', { component: 'Spinner' }, async ($, event, next) => {
// Keep the original line and add the counter at the end
return next({ ...event, props: { ...event.props, suffix: ' · tool calls: ' + calls + '…' } })
})
}The first function fires before each of Claude's actions, and adds one to the counter. The second fires when Claude Code draws the waiting line, and sticks the total onto it.
Each function passed to on is a hook (a function Claude Code calls when an event happens).
It receives three things:
$gathers everything a mod is allowed to ask of Claude Code;eventdescribes the event, for example the tool's name and its arguments;nextpasses the event on to the other mods, then to Claude Code.
Yes, you do need some JavaScript, and even then it is fiddly! 👀
Don't worry, you will probably never have to write this code yourself. Ask Claude for it, then review what it produced with claude plugin validate.
Frequently asked questions about Claude Code mods
What is a mod in Claude Code?
A mod is a plugin that changes how Claude Code looks and behaves. It is made of JavaScript or TypeScript functions that Claude Code calls when an event happens.
It can draw a pane or a band, add a command, or change one of Claude's actions before it runs. Anthropic announced mods on 1 October 2026.
Do you need to know how to code to create a mod?
No. You describe what you want in a session, and Claude writes the mod for you, then Claude Code asks you to enable hot reloading.
That mod loads only in the session that created it. To keep it, copy its folder and run claude --plugin-dir followed by its path.
Is a Claude Code mod dangerous?
It can be. A mod runs with your permissions and with no isolation. It can read your files and API keys, see every message and approve an action without you.
Before you install a mod, run claude plugin validate on its folder. The command lists what it listens to and what it asks for, without running its code.
Do mods work in VS Code?
Partly. In the chat panel of the VS Code extension, a mod's code runs but nothing it draws appears.
Panes and bands appear only in the terminal and in the Code tab of the desktop app. The integrated terminal of VS Code counts as a terminal.
How do you turn mods off?
For a single mod, disable its plugin in the Installed tab of /plugin. For all of them during one session, start claude --safe-mode.
To turn them off in every session, add "disableAllHooks": true to ~/.claude/settings.json. Your settings hooks stop too.