A Claude mod is a small add-on that changes how Claude Code itself works while you use it. You write it in JavaScript or TypeScript, it runs inside Claude Code, and it reacts the moment you send a prompt, Claude calls a tool, or the screen is about to redraw.
Say you want to keep a running count of how many tools Claude has used in a session. A mod can watch each tool call, add one to a counter, and show that number next to the spinner while Claude works. A mod listens for an event, then watches it, adjusts it, or handles it in place. Anthropic set mods out in the Claude Code documentation and announced them on 1 October 2026.
Mods need Claude Code v2.1.287 or later, where support is on by default, so a recent version supports them; run claude --version to see yours. That means the feature is enabled, not that any mod is already installed for you. If you switched on the old CLAUDE_CODE_ENABLE_FUNCTION_HOOKS flag during early access, you can drop it, because current versions ignore it (turning mods on or off).
What people build with them
Skills, settings hooks, status lines, and MCP servers all sit outside Claude Code. A mod sits inside it, which opens up a different set of things (what a mod can do):
- Put something on the screen you can use: a side panel, or a strip above the prompt, with buttons and input fields.
- Change parts of the screen Claude Code draws itself, such as how a tool call or the spinner looks.
- Add your own slash command that runs your code right away, without waiting for a model reply.
- Sit in front of a tool call or a request: pause it to ask you something, answer it without running the tool, or send a specific request to a different model.
- Let its pieces share values, so something one part records can show up in another.
How a mod differs from a skill, a settings hook, and an MCP server
These four customizations overlap. The table shows what each one is and when to reach for it.
| Type | What it is | What you write | Can it draw UI |
|---|---|---|---|
| Mod | Functions in a plugin that Claude Code calls in its own process | JavaScript or TypeScript | Yes |
| Settings hook | A shell command, HTTP request, or prompt that Claude Code runs on a lifecycle event | A script and a settings entry | No |
| Skill | A set of instructions Claude reads when the task calls for it | Markdown | No |
| MCP server | An external process that gives Claude tools | A server in any language | No |
One plugin can carry a mod, a skill, settings hooks, and an MCP server at once, so they work together; pick the one that fits the job.
Getting a mod
You do not have to write one to see a mod in action: some of Claude Code's own features are mods, including the /diff command that shows your pending changes (mods built into Claude Code). To add someone else's, you install it as a plugin from a marketplace, with a command such as /plugin install name@marketplace, where name and marketplace are placeholders.
Where mods run
A mod's code runs in any session that loads its plugin (where mods run). It runs in a terminal, including an editor's built-in terminal, and in the Code tab of the Claude desktop app, except in a WSL session there, where plugins do not load at all. In the VS Code extension's chat, in claude -p and the Agent SDK, it runs but draws nothing; in a cloud session it runs only when the plugin reaches that session. A mod's interface shows in fewer places than its code runs: the terminal shows everything a mod draws, while the desktop app shows all of it except a few terminal-only elements. A mod that draws can check where it is and fall back to plain text where it cannot.
What a mod can reach, and checking it first
A mod is code that runs with your permissions and is not sandboxed (what a mod can reach). Once loaded, it can read and write any files your account can, run programs, and make network requests; read your environment variables and settings, including an API key kept there; see every prompt and tool call; rewrite a prompt or a tool call; and approve a tool call before you are asked. It can restyle most of the interface, but not the permission prompt. So install mods only from authors and marketplaces you trust. Before you install one, claude plugin validate on its folder lists the hooks and API calls the mod declares (listing what a mod does). That is only what the mod declares, not everything it will do, and gives no security audit or guarantee that the mod is safe; installing only from authors you trust lowers the risk without proving it.
Mods and the model
A mod works on the software around the model. It can rewrite a prompt before it is sent, route a request to a different model, or add a command that runs your code with no model call at all. It does not fine-tune Claude or change its weights. A command runs without a model turn only when your function does not itself call a model; when it does call one, that request counts against your plan or API key like any other.
Frequently asked questions
What is a Claude mod in simple terms?
A small add-on, written in JavaScript or TypeScript, that runs inside Claude Code and reacts to events like a prompt, a tool call, or a screen redraw. It can watch an event, change it, or handle it, which lets you add your own panels, commands, and rules.
Do I need to install anything to use Claude mods?
Mods need Claude Code v2.1.287 or later, where support is on by default, so a recent version supports them; run claude --version to check. Built-in mods like the /diff command are already there, but a third-party mod is installed separately, as a plugin from a marketplace you trust.
Are Claude mods safe to install?
A mod runs with your permissions and is not sandboxed, so it can reach your files, secrets, and session and make network requests. claude plugin validate lists the hooks and calls a mod declares, but that is not a security audit and does not prove the mod is safe, so install only from authors and marketplaces you trust.
Sources
- Claude Code documentation, Mods overview (what a mod is and what it can do), Anthropic.
- Claude Code documentation, Where mods run.
- Claude Code documentation, What a mod can reach and listing what a mod does.
- Claude Code documentation, Turn mods on or off (version requirement).
- Anthropic, Customize Claude Code with mods in TypeScript, 1 October 2026.