Claude Code mods, and how they differ from plugins, hooks and skills

What is a mod in Claude Code?

Anthropic's definition is one sentence: “A mod is a plugin that changes how Claude Code looks and behaves.” A mod is made of JavaScript or TypeScript event handlers, and Claude Code calls one when an event happens, such as a tool call, a submitted prompt, or a part of the interface being drawn. The handler can watch the event, change it, or take it over.

Every handler is called a hook, and that word is doing double duty: a mod's handlers are functions that run inside Claude Code, while the hooks people usually have are shell commands, HTTP requests or prompts configured in a settings file, which Anthropic calls “settings hooks”. A mod's hooks are not subagents either. They are functions, in the process, with an event to read and a result to return.

What a hook does with its event comes in three shapes, and Anthropic names them. It can observe the event and let it continue unchanged. It can rewrite the event before the rest of Claude Code sees it. Or it can answer the event itself, so the usual behaviour never runs, which is how a mod refuses a command. To do anything outside its own code, such as draw, add a command, call a model, read a file or make a network request, a hook calls the mods API, passed to it as $.

A mod is a plugin on disk, so it has a plugin's shape. The manifest is .claude-plugin/plugin.json. Beside it, hooks/hooks.json names the code file under its modules key, and having that key is what makes the plugin a mod. The code file, called the hooks module, exports one register function. Installing a mod is installing a plugin, from a marketplace, which Anthropic puts as /plugin install token-chart@your-org.

That is the whole relationship in the other direction too. A plugin can hold skills, agents, settings hooks and MCP servers, and Anthropic notes that a mod can therefore “ship in the same plugin as a skill and an MCP server”. The words are not rivals; they describe different parts of one box.

Four words, one at a time

Anthropic's own documentation carries a comparison table for these four words. Here it is, with the rows that matter for this question, and then a plain sentence for each word.

Anthropic defines hooks as “user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents that execute automatically at specific points in Claude Code's lifecycle”, configured in a JSON settings file, with events in three cadences: per session, per turn, and on every tool call inside the agentic loop. A settings hook runs from outside Claude Code, and Anthropic's own comparison gives it a No in the drawing column. On macOS and Linux a command hook runs without a controlling terminal, so it cannot write to the interface directly either.

A plugin is the delivery unit: “a directory of skills, agents, hooks, MCP servers, or other components that Claude Code installs and loads as one unit”. Most plugins arrive from a marketplace, which Anthropic describes as a catalog that lists plugins and where to fetch each one, and you install one by name. A plugin that contains a hooks module is a mod, so the same folder can be both.

A skill is a file of instructions Claude reads when it is relevant, and you can also run one as a command. It changes what Claude knows and does, and it draws nothing. If what you want is a workflow Claude follows, that is a skill, and it is the wrong tool for a panel.

An MCP server gives Claude tools by connecting it to something outside. It is a process in its own right, not code inside Claude Code, and it draws nothing either.

Anthropic's advice on picking one is short: if a settings hook, a skill or an MCP server already does what you need, compare before you write a mod. The mods API is what a mod reaches for when the answer is a pane, a band above the prompt, a command of your own, or a part of the interface to redraw, and drawing is the only row in that table where the mod says Yes and the other three say No.

How to get a mod

There are two roads, and the first one is short. Describe the mod you want in an interactive Claude Code session, in your own words, and Claude writes it. Anthropic documents a built-in skill named plugin-authoring that tells Claude where to write the mod, which events and methods your version has, and how the mod gets loaded. Claude writes it into a folder of its own in the session's mods folder, which is ~/.claude/dev-mods/ followed by the session ID.

When Claude saves the first file, Claude Code asks whether to enable hot reloading for the session, and Anthropic lists two answers: Enable for this session, where the mods in that folder load when the turn ends and reload at the end of each turn that changes them, or Not now, where nothing loads and the files wait until that session starts again. In the default and accept-edits permission modes Claude Code also asks you to approve each file before Claude creates it, because the mods folder is a protected path.

The second road is writing it yourself, and a small mod is three files. There is no build step: Claude Code loads .js and .ts files directly.

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

Inside the hooks module, one exported function does the work. Every call to on registers a handler for the event it names, and the second argument is an optional filter, which Anthropic calls a matcher. Anthropic's own tutorial mod counts tool calls and shows the count beside the spinner. The two hooks that do it are these, and both share one variable:

let calls = 0

export function register(on) {
  on('tool.call', async ($, e, next) => {
    calls += 1
    $.ui.invalidate('ui.render')
    return next(e)
  })

  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

The first hook adds one to the count and asks Claude Code to draw again; the second keeps Claude Code's own spinner and appends the count to it. That is the whole pattern a mod is built from, repeated across events.

To try it before installing anything, load the folder for one session with --plugin-dir. To check what Claude Code would make of it without running it, run claude plugin validate on the folder: the hooks: line lists the events it hooks, and the calls: line lists every mods API method it calls.

The tutorial mod Anthropic uses to teach this has four hooks rather than the two above, so its own output reads like this:

  ❯ ./register.js hooks: session.start, tool.call, command.run{command=tally}, ui.render{component=Spinner}
  ❯ ./register.js calls: $.command.register, $.ui.invalidate

Validation passed

To see what a session actually loaded, run /plugin and read the dim line under the tabs, which gives the count and the names, such as 1 mod active · first-mod. The Installed tab is where you turn one off.

You do not have to write the first one. Anthropic shares three sample mods in the claude-code/mods directory of its claude-code-playground repository: token-weather, which draws a forecast of your context window above the prompt; blast-radius, which holds a risky shell command and shows what it would change before you decide; and replay-theater, which adds a /replay command. Each is a complete plugin, and Anthropic shares them as they are, without support.

Some of Claude Code's own features are mods already. Anthropic lists /diff among them, and the source of several built-in mods is public in the mods directory of the anthropics/claude-code repository, each one a complete plugin with its hooks module and tests. The Installed tab in /plugin lists them under Built-in, and those you cannot update or uninstall, though a built-in still has a switch of its own, which the next section covers.

What a mod can draw

Drawing is what a settings hook cannot do, and it is worth being exact about it. Each place a mod can draw is what Anthropic calls a render site, and Claude Code fires a ui.render event each time it is about to draw one. Your hook for that event returns what to draw there.

One part is out of reach, and Anthropic says why: “The permission prompt isn't a render site, so a mod can't change what it shows.” The question dialog is a render site, so a mod can change that one. A mod can restyle much of the interface, and it cannot change what the permission prompt tells you before you approve something.

A mod can also add a command of your own, which runs your function at once with no Claude turn, even while Claude is working. And its hooks share the variables in the module's file, so what one records another can show, which is how Anthropic's own example puts a count of tool calls in the spinner from a second hook.

Where a drawing appears depends on where Claude Code is running, and Anthropic's table is specific. In a terminal, and in the Code tab of the Desktop app apart from the elements Anthropic marks terminal-only, a mod's hooks run and what it draws appears. The VS Code extension's chat panel draws too, with extension version 2.1.299 or later, or 2.1.304 or later for a session that does not fetch feature flags. In claude -p and the Agent SDK the hooks run and nothing drawn appears. A WSL session in the Desktop app loads no plugins at all, so nothing runs there.

When a mod is the wrong tool

Anthropic's own table answers the first half of this, in its own words. It picks a mod when “You want a pane, a band above the prompt, a custom command, or to rewrite an event”; a settings hook when “You want to block, allow, or log an event with a script you already have”; a skill when “You keep pasting the same instructions into chat”; and an MCP server when “Claude needs to reach an external system”. The same table lists a tool call's arguments and result among what a settings hook can change, so rewriting a tool call is not a mod-only job. What it cannot do is draw.

The second half is safety, and Anthropic is blunt about it: “A mod is code that runs with your permissions, inside Claude Code.” Mods are not sandboxed. Once one loads, Anthropic says it can act on your machine as you, read your secrets including an API key you keep in a settings file, see every prompt and tool call in the session, rewrite a prompt or a tool call, approve a tool call before you are asked, and spend your usage by calling a model on your plan or your key. Turning on sandboxing isolates the Bash commands Claude runs, and a process a mod starts runs outside it.

That is why Anthropic's advice on installing one is about the author and not the feature list. Install mods only from authors and marketplaces you trust, and read what a mod does before you load it: claude plugin validate lists the events it handles and the calls it asks for, without running any of it. If an approval prompt in your own session is part of your safety, note that a mod can approve a tool call that an ask rule would have stopped, unless managed settings or a Team or Enterprise login are in use.

Turning one off is three different switches, and Anthropic separates them. Disable the plugin in /plugin to stop one mod. Start Claude Code with --safe-mode to stop every installed mod for one session, along with your other customisations. Set disableAllHooks in your settings file to stop every mod you installed in every session, which also stops your settings hooks and your custom status line.

Those three stop the mods you installed, and a built-in mod is different: Anthropic says the settings and flags that stop installed mods do not stop built-in ones. Its own table gives the way to turn each built-in off, which for the ones listed is /plugin. The security guard is the exception: users cannot turn it off, and it is an administrator's switch instead. It loads when the machine has managed settings or the session signs in for a Team or Enterprise plan, its options are read only from managed settings under cc-plugin-sec-default@builtin, and an administrator who sets prependPlugins has to name sec-default@builtin in that list to keep it.

One more thing to plan for: mods change between releases. Anthropic writes that the events and methods can change, and that the type definitions Claude Code writes beside your mod are the fuller reference for your build, to be trusted over any page, its own included, when they disagree. A mod you rely on is something to re-check after an update.

What people have reported

Searching Anthropic's own issue tracker for “mods” in an issue title on October 25, 2026 returns 168 issues. The one that matters for this page is the request the feature came out of, because Anthropic draws the line between a mod, a plugin and a hook there in plain sentences.

Anthropic's own words in that thread, in its September 9 update, are: “A mod is just a plugin that uses function hooks, nothing is changing there. Hopefully the ontology is not too confusing.” The same update says the engineering term of art, function hook, still exists as the documented primitive mods are built on, and that the feature would ship in weeks rather than months. It shipped: the documentation has a mods section of its own, and Claude Code carries built-in mods with published source.

The thread also shows how the decision was made. The original post on September 3 asks for engagement and says the community response likely decides whether this ships. The update on September 9 thanks people for feedback “that has materially shaped our design”, and the update on October 1 opens “We're live!” and thanks them again for being “amazing stewards of this new extensibility affordance”. That is a product decision taken in public and then delivered.

That count is a measurement with a date on it: issue counts on a live tracker move, and the caption above the row carries the day it was read.

Where Omniscio fits

Plainly: Claude Code mods are Claude Code's own. A mod loads through Claude Code's plugin system, and Claude Code decides where it draws. Nothing on this page needs Omniscio. Where it sits is one level up, at the sessions those mods run inside: it is a desktop app for running many Claude Code agents, built around one calm inbox rather than a wall of terminals, and its own harness line is “Any model, any harness — Claude Code, Codex, OpenCode, Devin, Pi, and Hermes all supported.”

The drawing question has a specific answer, and it comes from the mode Omniscio starts Claude Code in. Omniscio starts the CLI with -p, Claude Code's print mode, and --output-format stream-json --input-format stream-json. Anthropic's own table says that in claude -p and the Agent SDK a mod's hooks run and what it draws does not appear, so a pane or a band from a mod has no surface to draw into in an Omniscio agent session. Our library makes the same point about commands: stream-JSON mode does not give every slash command rich UI, so some print plain output instead of opening a panel. What a mod does to the work itself still happens, because the hooks still run.

Omniscio has a mods idea of its own, and it is a different thing with the same word. Layout Mods, in Settings → Appearance → Layout Mods, applies a preset to one of two surfaces and then lets you tune it: the projects sidebar, with the bundled Compact Rail and Labeled Rail presets, or the session list, with Calm List plus a row size and a status-badge toggle. Exactly one preset may be active per surface, your own tuning layers on top of it, and Safe Mode puts the standard layout back. Mod Studio, a Lab feature under the same tab, builds mods of your own from blocks: a card design for a list, and style rules for parts of the app, with every value kept inside set ranges.

Omniscio plugins are a third thing again, and the two are installed in different places. An Omniscio plugin adds a panel to Omniscio itself: a manifest naming the panel, its sidebar icon, the permissions it asks for, and an optional worker. It is browsed, installed and updated in Omniscio's own Marketplace, a screen of its own that opens from the store icon in the sidebar as a virtual project, while Settings → Plugins lists the plugins you already have and carries a Browse Marketplace button. A Claude Code plugin is a directory Claude Code loads inside a session, from a Claude Code marketplace.

Two defaults are worth knowing before you rely on any of that. The per-session spend cap is for sessions billed to a pay-per-use API key, and it never limits a Claude Pro or Max subscription session, which matters here because a mod can spend your usage by calling a model. And the Free plan covers 8 projects and 10 agents at once, with Pro at $20/month or $192/year. The features page lists what the app does today and the pricing page has the plans.