· Updated
Claude Code mods and plugins, explained
What a Claude Code mod is, how it differs from a plugin, a settings hook, a skill or an MCP server, what a small one looks like, and what to check before you trust one.
- claude code
- claude code mods
- plugins
- developer tools
- tokenbreak
People use "plugin" and "mod" for Claude Code almost interchangeably, and that gets confusing fast. I build Tokenbreak, which is a Claude Code mod, so I explain the difference a lot. This is the version I wish I could link people to.
Tokenbreak is an independent project and isn't affiliated with or endorsed by Anthropic. The details below follow Anthropic's mods documentation as of Claude Code v2.1.290. Mods are new, so check the docs before you build on any detail here.
The short version
- A plugin is the thing you install, from a marketplace. It can hold skills, commands, subagents, settings hooks, MCP servers and mods.
- A mod is a plugin whose code runs inside Claude Code. It's a set of JavaScript or TypeScript functions that Claude Code calls when something happens: a tool call, a prompt being sent, a turn starting, part of the screen being drawn.
- So every mod is a plugin, and most plugins aren't mods.
Mods are on by default in the terminal from Claude Code v2.1.287, and in the desktop app's Code tab from v2.1.286. Run claude --version to check yours.
What a mod can do that nothing else can
Settings hooks, skills, status line scripts and MCP servers all work from outside Claude Code: they run a script, or give Claude text or tools. A mod runs inside, so it can:
- Draw an interface: a pane beside the conversation, or a band above the prompt, with buttons and text fields.
- Redraw what Claude Code draws: the spinner, a tool call's row, the question dialog.
- Step into an event: hold a tool call while it asks you something, answer it without running the tool, rewrite a prompt.
- Add a command that runs your code at once, with no Claude turn, even while Claude is working.
- Share state between its hooks, because they live in one file. One hook can count tool calls while another shows the count.
Here's how the options compare, condensed from Anthropic's table:
| Mod | Settings hook | Skill | MCP server | |
|---|---|---|---|---|
| What it is | Functions Claude Code calls in its own process | A shell command, HTTP request or prompt run on a lifecycle event | A SKILL.md of instructions Claude reads |
A separate process that gives Claude tools |
| Can it draw on screen | Yes | No | No | No |
| You write | JavaScript or TypeScript | A script and a settings entry | Markdown | A server, in any language |
| Pick it when | You want a pane, a band, a command, or to rewrite an event | You want to block, allow or log something with a script you have | You keep pasting the same instructions | Claude needs to reach an outside system |
A plugin can hold all four, so a mod can ship next to a skill and an MCP server.
What a small mod looks like
A mod is a plugin directory with three files:
first-mod/
├── .claude-plugin/
│ └── plugin.json
└── hooks/
├── hooks.json
└── register.jshooks.json points at the code ("modules": ["./register.js"]), and register.js exports one function, register(on). Inside it, each call to on names an event and the function to run. Every hook gets three things: $, the mods API; e, the event; and next, which passes the event on, like middleware.
This one times each turn and puts the result in the status line. It's a sketch rather than a tested mod, so check names against the mods reference for your version:
// hooks/register.js: how long did Claude take?
let startedAt = 0
export function register(on) {
on("turn.start", async ($, e, next) => {
startedAt = $.clock.now()
return next(e)
})
on("turn.complete", async ($, e, next) => {
const seconds = (($.clock.now() - startedAt) / 1000).toFixed(1)
$.ui.status(`last turn: ${seconds}s`)
return next(e)
})
}Two hooks and a variable. Most good mods I've seen are about this size. Anthropic's own example in the docs counts tool calls with a tool.call hook and adds the count to the spinner with a ui.render hook on the Spinner site.
The events you'll reach for first:
session.startandsession.end, when a session begins and endsturn.startandturn.complete, around each answertool.call, before any tool runsprompt.submit, when you send a promptui.render, when a part of the screen is drawn, filtered by site:AbovePromptfor the band,Panefor a panel,Spinnerand others for Claude Code's own piecescommand.run, when someone types your command
Where a mod can draw
The band above the prompt (AbovePrompt). The spot people look at right before they type. It's narrow by nature, so it suits one line.
A pane (Pane), beside the conversation or above the prompt. The most room you get. Claude Code places a pane the user didn't ask for only on a wide window, from 144 terminal columns, so plan for it not to appear.
Claude Code's own pieces, such as the spinner and tool rows, which a ui.render hook can restyle or replace. It can't touch the permission prompt.
Where a mod draws depends on where Claude Code runs. In a terminal and in the desktop app's Code tab, hooks run and drawings show. In the VS Code extension's chat panel, claude -p, the Agent SDK and cloud sessions, hooks run but nothing a mod draws appears.
Before you trust one
A mod runs with your permissions and isn't sandboxed. Once loaded, it can read and write any file your account can, read environment variables (API keys included), see every prompt and tool call, approve tool calls for you, and make network requests. That's in Anthropic's own docs, in those words, and it's the right mental model.
So install mods only from people and marketplaces you trust, and look before you load one. Clone the plugin and run:
claude plugin validate ./some-modThe hooks: line lists every event it handles and the calls: line every API call it makes, like http.fetch or fs.read, without running anything. A mod that only draws a timer has no business with fs.read or prompt.submit. The step-by-step version is in how to install a Claude Code mod.
How Tokenbreak uses these pieces
Tokenbreak is a mod that shows ads, and pays the developer who runs it half of what advertisers pay. It registers eight hooks, on seven events, and nothing else:
| Hook | What it's for |
|---|---|
session.start, session.end |
Start up in interactive sessions, and send any impression reports still waiting when a session ends |
turn.start, turn.complete |
Know when Claude is working, to time the ads and ask our server for a turn token. Only the turn's id is read, never its text |
ui.render on AbovePrompt |
Draw the one-line Prompt Banner |
ui.render on its own Pane |
Draw the Theater pane, on wide terminals |
ui.close on that pane |
Stop the Theater, and keep it closed for a while if you closed it |
command.run for ads |
The /ads commands: login, pause, resume, report |
It never hooks prompt.submit, tool.call or anything that reads the conversation, and its test suite fails if it ever does. You can check that with claude plugin validate on the source. What it sends home is on the tracking page, request by request.
Why the ads never touch the model's context
A mod can do two different kinds of things: draw on your screen, or change what the model sees. Tokenbreak only does the first, for three reasons.
- Tokens cost money. Anything in the model's context is processed as tokens. Ads in the context would spend your plan on ads. Drawn on screen, they cost zero tokens.
- Ads shouldn't steer the agent. An advertiser's line in the context could nudge what Claude writes. That's prompt injection with a marketing budget. Claude doesn't know Tokenbreak exists.
- It doesn't need your prompts. To time an ad, it only needs to know a turn started or finished.
Building your own
Small mods make a good weekend project: a CI light in the status line, a band that shows the current branch before a risky prompt, a turn timer. The quickest start is to describe what you want in a Claude Code session and let Claude write it; Anthropic's create a mod page covers the edit-and-reload loop. Load a work in progress for one session with claude --plugin-dir ./first-mod, and it reloads when you save.
If you make a website for your mod and want it to look like a terminal, the components on this site are free shadcn components, each one install command away. The words used here are defined in the glossary.