Most people still treat Claude Code like a chat box with extra tools. That was already the wrong mental model. After September 14, 2026, it is also outdated.
Anthropic shipped function hooks behind one environment variable. They named the product surface Claude Mods. A mod is not another skill you paste into CLAUDE.md. It is TypeScript that loads inside Claude Code’s own process, sits in the request path, and can draw UI, rewrite tool calls, or touch the host without spending a single model token.
I spent an evening in the official source, not a press brief. The four built-in mods live in anthropics/claude-code/mods. Each one is a complete plugin folder: plugin.json, hooks/hooks.json, a register.ts that exports one function, and tests that call the same $ object the engine uses in production. When I opened mods/diff/hooks/hooks.json, the description was almost a product spec: the pane, the refresh on edits, the first-edit open, and the ask that rides a file’s hunks on the next prompt.
That is the whole story in one file. Claude Code is no longer only a model plus a loop. The loop itself is now a plugin host.
Why Claude Code mods vs plugins is the question people should be asking
The naming is messy on purpose. Anthropic already had plugins. Plugins already had hooks. Hooks already ran shell scripts on SessionStart and PostToolUse. Then they added function hooks and told the issue tracker they would call the new thing Claude Mods.
Here is the split that actually matters when you sit down to customize a session.
A skill teaches the model a procedure. It costs tokens when it loads. A classic hook runs a command outside the engine when an event fires. A plugin is a zip of skills, agents, MCP servers, and those classic hooks that you install with /plugin. A mod is a plugin whose behavior is a TypeScript function hooked into the engine as register(on, options).
The $ object is the audit surface. Every side effect a mod wants (read a file, spawn a process, fetch a URL, draw a pane) goes through $. Admins can strip nouns off $ so lower plugins cannot call them. Registration order is the middleware stack. First registered sits outermost. next is Express-shaped. If that sentence made you nod, you already know how to reason about this.
Skills still win when you want the model to know a workflow. Classic hooks still win when you want a deterministic shell gate. Mods win when you want the harness itself to change: a live diff pane, a context meter that does not ask the model anything, a rewriter that swaps npm for pnpm before the command runs.
If you only remember one line from this post, make it that last one.
The flag, the date, and what I actually found in the repo
Function hooks do not load unless you opt in. Put this in ~/.claude/settings.json:
{
"env": {
"CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1"
}
}Or run one session with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude.
Boris Cherny posted “landing now” on September 14. The design thread is issue #91870, opened September 3, with the product name locked on September 9. There is still no glossy docs page that treats mods as a first-class product. The source is the docs.
The four mods that already ship in the binary:
diff is the /diff pane. Uncommitted changes, file by file, hunks refreshing as Claude edits. You have used this even if you never heard the word mod.
agents-md is why Claude Code can read AGENTS.md the way it reads CLAUDE.md. Default is claude-md-or-agents-md. You can load both, load only Claude’s file, or drop personal files and keep the org file. That option lives in user settings under pluginConfigs.agents-md@builtin, not in the project .claude/settings.json. I had to read the agents-md README twice before that last part stuck.
telemetry adds $.telemetry for first-party events. Installed plugins cannot use it. If you turned analytics off, it sends nothing.
sec-default sits outermost on Team, Enterprise, or any machine with managed settings. It keeps org hooks, prompt content, and tool policy out of reach of plugins a person installs. It adds no extra policy of its own. If you are on a personal Pro plan at home, this one is mostly quiet.
You can run a built-in from source with claude --plugin-dir mods/diff and typecheck the lot with tsc -p mods/tsconfig.json. The test command is claude plugin test mods/diff. The test harness hands the engine’s own $ to the mod, then sits underneath it. A call the test leaves unanswered throws and names the event. That is how you know the contract is real.
Official source: anthropics/claude-code/mods.
The scan that should change what you install
On September 17, karanb192 published a nightly scanner against Claude Code 2.1.274. The repo is awesome-claude-code-mods. It does not just list names. It runs claude plugin validate on every candidate and prints the footprint: which events the mod hooks, which $ calls it makes.
The September 17 pass found 72 mods across 142 candidate repos. Thirty run host processes. Eleven write files. Twenty-four read files. Fourteen reach the network. Twenty-four see every tool call. Twenty-three see every prompt. Three fail to validate on that version.
Reach is labeled L0 through L3. L0 draws and remembers. L1 reads. L2 writes, runs a process, or drives Claude. L3 talks to the network. The author is careful: footprint is capability, not proof of misuse. A PR tracker has to call gh. That is L3 for a boring reason.
A week earlier the same scanner, on a smaller set, is what The New Way wrote up: 14 of 31 public mods could run host code. The number went up because the catalog grew, not because the design got safer.
This is the part most “what’s new in Claude Code” posts skip. You are loading TypeScript into the same process that holds your repo, your prompts, and your tool stream. That is the feature. It is also the risk.
I will not tell you to disable the flag. I will tell you to read the footprint row before you install a party trick that draws Tetris above the prompt.
Claude Code mods vs plugins vs skills: pick with a job, not a vibe
People keep asking for a winner. There is no winner. There is a job.
Want the model to follow a house style, a test ritual, or a deploy checklist? Write a skill. Skills are cheap when they stay small. They get expensive when you dump a novel into SKILL.md and load it every turn.
Want a hard stop on rm -rf, a formatter after every Write, or a Slack ping when Claude blocks on permission? Use a classic hook. Shell in, JSON out. Deterministic. No model in the loop.
Want to share a bundle with your team: commands, agents, an MCP server, a couple of hooks? That is a plugin. /plugin marketplace add, /plugin install, toggle it off when the context tax is too high.
Want a live pane, a token ledger that does not ask Opus anything, or a rewriter that edits the tool call before bash sees it? That is a mod. Zero tokens for the behavior itself. Full process access if the author asked for it.
The ugly middle is the skill-shaped plugin that is actually a pile of prompt text pretending to be infrastructure. Those eat context and still cannot draw a pane. If your customization only talks to the model, it is not a mod. Stop calling it one.
Three mods I would install before I installed anything fun
Skip the arcade ports for a week. The useful ones are boring.
context-lens pins context-window fill, growth per turn, and a rough count of turns left before compaction. You stop guessing when the session is about to fall over.
token-ledger pins session cost, last-turn cost, tokens in and out, cache hit ratio. If you just moved to Opus 5.5, this is how you notice that xhigh is eating the 40% price cut.
budget-guard only wakes up near a limit you set. Past the line it refuses tool calls and asks before the next prompt. That is the opposite of a toy.
Install path is the same shape every time. Enable the flag. Add the marketplace. Install by name. Restart Claude Code. The pinned line shows after the first answer, not at the splash screen. If you see nothing, the flag is off or the version is older than 2.1.269.
I would run claude plugin validate on the folder before I trusted a fourth mod from a stranger. The awesome list already did that work for the public set. Use it.
The 8-minute test you can run tonight
Do this on a throwaway repo. Do not learn the flag on the company monorepo.
Confirm your Claude Code version is 2.1.269 or newer. Merge the env flag into ~/.claude/settings.json. Start a session and ask for /plugin-types so the engine writes .claude/types/claude-code.d.ts. That file is the contract. Open it. Search for telemetry, Pane, fs, http. You are looking at what a mod is allowed to name.
Then install one dashboard mod from a marketplace you recognize. Restart. Send a short prompt that causes one file edit. Watch the pinned line. If the number moves and your prompt did not mention tokens, the behavior is running in-process. That is the proof.
If you want the built-in version of the same idea, run claude --plugin-dir against a clone of anthropics/claude-code/mods/diff and type /diff after an edit. You are now looking at a first-party mod the same way Anthropic does.
Stop there. Do not install five L3 mods in the same hour. The $ object composes. So do the surprises.
What this means if you already live in CLAUDE.md
A lot of teams spent 2026 stuffing rules into markdown and calling it governance. That still works. The CLAUDE.md pattern that blew up earlier this year is still the right place for taste, naming, and “do not refactor the world.” Mods do not replace that file. The agents-md mod even teaches the engine to treat AGENTS.md as a sibling of it.
What mods replace is the fantasy that you can prompt the harness into being observable. You cannot. Observability is a pane and a counter. Those belong in process, not in a system prompt you hope the model rereads.
If you want the longer picture of why the harness matters more than the next model bump, the learn-claude-code walkthrough is still the cleanest map of the loop. Read that, then come back to the mods/ folder. The folder is the next chapter of the same book.
And if your agent also has to touch decks and spreadsheets, keep that work in a tool with a real file format. OfficeCLI is the open-source version of that idea. A mod that draws a pretty banner will not save you from a corrupted pptx.
New to the terminal agent itself? Start with TechWave Arena’s Mastering Claude Code beginner’s guide, then come back here for the mods layer.
The honest limits, because the API will move
Anthropic says the function-hook API can change between releases without notice. Custom mods are early access. Built-ins are already in your binary, which is why /diff does not feel experimental.
sec-default only seats outermost on managed machines and Team or Enterprise orgs. A random Pro user installing community mods does not get that shield for free.
Three public mods already failed validation on 2.1.274. That number will bounce every time the $ contract shifts. Pin versions. Read changelogs. Treat an L3 mod like you treat a native npm postinstall script that phones home.
The other limit is taste. The community shipped Doom, Tetris, and a 260K-parameter toy model inside plugins within a day of the flag. That is delightful. It is also how you end up with a coding session that is a video game with a compiler attached. Keep the fun mods in a side profile.
Common questions about Claude Code mods
What is the difference between a Claude Code mod and a plugin?
A plugin is the package. A mod is a plugin whose hooks are TypeScript functions running inside the engine. Every mod is a plugin. Most plugins are still the older kind: skills, slash commands, MCP, classic shell hooks. If there is no register(on, options) and no function-hooks module, you are not looking at a mod.
How do I enable Claude Code function hooks?
Set CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 in ~/.claude/settings.json under env, or prefix a single claude launch with that variable. Restart. If nothing new loads, your build is older than the flag or the mod never validated.
Are Claude Code mods safe?
They are as safe as the code you load into the same process as your repo. As of the September 17 scan, 30 of 72 public mods can run host processes and 14 can reach the network. Read the footprint. Prefer L0 dashboards from authors you can name. Keep sec-default in the picture if you are on a team plan.
Do Claude Code mods use tokens?
The hook logic itself does not. Drawing a pane, rewriting a tool call, or pinning a cost line happens in process. If a mod then calls $.model or stuffs extra prompt text, that part costs tokens like anything else. Ask the author, or read the register module.
If you try only one thing
Turn the flag on. Install a context or cost pane. Watch one real session without asking the model how much context it used.
That is the test that separates this release from another model bump.
1 comment