Claude Code Mods Explained: Hooks vs Mods vs Skills vs MCP (2026)
By: Evgeny Padezhnov
Claude Code Mods Explained: Hooks vs Mods vs Skills vs MCP (2026)
Four ways to extend the same agent, what each one can actually change, and which one to reach for.
Updated 5 October 2026 · Claude Code 2.1.289
On 1 October 2026 Claude Code v2.1.287 shipped Claude Code mods: TypeScript function hooks that run inside the agent. The awesome-claude-code-mods list counted 359 across 373 repos on day one and over 1,000 within 48 hours. Most questions since then are a version of "how is this different from the hooks, skills and MCP servers I already have?"
Here is the short answer. I run a fleet of autonomous Claude Code agents on one Linux box, so the comparison comes from use, not only from the docs.
What a Claude Code mod is
A mod is a folder of TypeScript that Claude Code loads into its own process. Its hooks can intercept a tool call (deny it, rewrite its arguments, retry, or act on its result), rewrite the prompt and the system prompt, draw panes, bands above the prompt, status-line entries and toasts, and add slash commands. It can reach the network, files, processes and the model, with your own permissions and no sandbox.
Mods ship as plugins, and the catalog has no payments. The API is early access: the first lines of the types file say it "may change between releases without notice."
Hooks vs mods vs skills vs MCP: the comparison
| Settings hook | Mod | Skill | MCP server | |
|---|---|---|---|---|
| What it is | A command in settings; JSON on stdin, answer on stdout | TypeScript function hooks inside the agent | Instructions and scripts the model loads when relevant | An external process that exposes tools over the Model Context Protocol |
| Where it runs | A separate process | Inside Claude Code | In the model's context; scripts via the agent's tools | Its own process, local or remote |
| What it can change | Answer at fixed lifecycle events, e.g. deny a tool call in PreToolUse |
Tool calls, prompt, system prompt, UI, slash commands | What the model knows | Which tools the model can call |
| UI | No | Panes, bands, status line, toasts | No | No |
| Surfaces | Wherever your settings load | Full in the CLI and desktop app; hooks only, no UI, in VS Code, claude -p and the SDK |
Wherever the agent runs | Wherever the agent runs |
| Distribution | A settings entry | Plugins from git marketplaces (pin a SHA) or the Claude directory | A folder you install | A package or endpoint you configure |
| Trust model | Your script, your rights | Like a browser extension: someone's code, your rights | Text the model follows, plus its scripts | Code you run or a service you trust |
The column that matters is "what it can change". Skills and MCP servers give the model knowledge or tools; the model still decides. Settings hooks and mods sit between the model and the engine and can overrule it.
Only mods rewrite the prompt and system prompt and draw UI.
When to pick which
- The model should know how to do something (a deploy procedure, a writing style): a skill. See how to tell if Claude Code skills fire.
- The model should reach a system it cannot reach today (a database, a tracker): an MCP server. Our 1,939 MCP tool calls in production show which parts get used.
- You need a hard rule the model cannot argue with (no force push): a mod with a
tool.callhook, or a settings hook if a plain shell command suits you better. - You want to see something while you work (token usage, CI state): a mod. Nothing else here draws UI.
- You want to change what enters the conversation: a mod, via
prompt.submitandprompt.compose.
Early mods people shipped line up with this: a token-usage graph, rm -rf protection, a file-edit journal, a CI panel built in about 20 minutes. Anthropic moved its own /diff into a mod.
Anatomy of a mod: three files
A mod is a folder with three files:
.claude-plugin/plugin.json { "name", "version", "description" }
hooks/hooks.json { "modules": ["./register.ts"] }
hooks/register.ts export const register: Register = (on, options) => { ... }
plugin.json can also carry author and userConfig. The whole contract lives in register.ts.
Every hook is ($, e, next): $ is the engine interface, e is the frozen event input, and next(e) runs the plugins beneath you and then the engine's own behaviour. Return without calling next and you answer yourself.
The smallest useful mod blocks one command:
import type { Register } from 'claude-code'
export const register: Register = on => {
on('tool.call', { tool: 'Bash' }, ($, e, next) => {
if (/\bgit\s+reset\s+--hard\b/.test(e.command)) {
$.ui.toast('blocked: git reset --hard')
return { deny: 'git reset --hard drops uncommitted work' }
}
return next(e)
})
}
The model receives the deny reason as an error result, and you see the toast. Our fuller version, safe-shell, keeps the rules as a table of regex and reason:
[/\bgit\s+push\b[^;&|]*\s(--force(?!-with-lease)\b|-f\b)/, 'force push rewrites shared history'],
[/\bgit\s+reset\s+--hard\b/, 'git reset --hard drops uncommitted work'],
[/\b(DROP|TRUNCATE)\s+(TABLE|DATABASE|SCHEMA)\b/i, 'destructive SQL'],
We tested that rule set on 21 commands: 12 blocked, 9 passed. The smaller example above passes claude plugin validate and tsc too. Check yours with claude plugin validate <dir>, which lists what the module hooks and calls and anything the engine would refuse, then load it with claude --plugin-dir <folder>. The module has no Node and no require, and a helper that receives $ must sit at the top level of the file.
Are Claude Code mods safe?
A mod runs with your permissions and no sandbox, so installing one is the same decision as installing a browser extension. Pin marketplace plugins to a commit SHA, so the code you reviewed is the code that runs.
The nearest published data covers skills, not mods. The "Agent Skills in the Wild" study (Yi Liu et al., arXiv 2601.10338) scanned 31,132 skills: 26.1% had at least one vulnerable pattern, 5.2% showed signs of malice, and skills with scripts were 2.12x more likely to be vulnerable. Before installing a mod:
- Read
register.tsand runclaude plugin validateto see what it hooks and calls. - Look for network calls, environment-variable reads and code fetched at runtime.
- Pin the commit SHA; review again before moving the pin.
Our fleet's angle: from a settings gate to a mod
In June 2026 I built a settings-based PreToolUse security gate for the fleet. In three months it raised 752 approval requests; I made 18 decisions, 734 timed out, and agents spent about 57 hours frozen.
The full story is in our Claude Code hooks case study. The lesson: the mechanism worked, the human-approval process did not, and deterministic deny rules carry the weight.
Mods change three things for that design. The deny rules can live inside the agent instead of a separate command, with the reason returned to the model as an error result. A toast or status-line entry can tell me what was blocked without anyone waiting on a card. And because mods can hook classic events as classic.<Event>, a move from settings hooks does not have to happen in one step.
Three things do not change.
Under claude -p, in VS Code and in the SDK only the hooks run, so a headless agent gets the deny but nobody sees the toast. The API is early access, and the CLI also keeps a remote switch for mods: on our box claude plugin test refused to run because the switch was saved off, so what we verified is validate, tsc and a run of the rules.
A mod also does not replace our rule for agents touching prod: snapshot first, name the rollback before the change, deploy only via a script with a health gate.
FAQ
Are Claude Code mods the same as plugins?
A mod is distributed as a plugin: a folder with .claude-plugin/plugin.json and a hooks module. You install it from a git marketplace or the Claude directory.
Do mods work in VS Code?
Partly. In VS Code, claude -p and the SDK the hooks run, but there is no UI; panes, toasts and the status line need the CLI or the desktop app.
Are mods sandboxed? No. A mod runs with your own permissions and can reach files, processes and the network, so review it and pin the commit SHA.
Can a mod block a command?
Yes. A tool.call hook with the matcher { tool: 'Bash' } can return { deny: 'reason' }, and the model receives the reason as an error result.
Do I need TypeScript?
No, but it helps. The hooks module can be TypeScript or JavaScript, as an ES module; TypeScript gives you the types from the claude-code types file. For a plain shell command, classic settings hooks still exist.
Information is accurate as of the publication date. Terms, prices, and regulations may change — verify with relevant professionals.