# What is a Claude Code mod, and where does it sit next to plugins, skills, hooks and MCP? > Source: > Published: 2026-09-25 16:42:31+00:00 # What is a Claude Code mod, and where does it sit next to plugins, skills, hooks and MCP? A [Claude Code](https://stackness.dev/tools/claude-code) mod is a plugin whose behaviour lives in a [TypeScript](https://stackness.dev/tools/typescript) hooks module that runs inside Claude Code's own process. One `register(on, options)` function subscribes middleware to engine events: tool calls, prompt context, commands, UI rendering. A mod can rewrite, deny or add to what the engine does, not only react to it. The first one most people ran was the [AGENTS.md](https://stackness.dev/tools/agents-md) loader in Claude Code 2.1.277, released on 18 September 2026. Everything else about mods is early access. There is no docs page, no changelog entry that uses the word, and no marketplace listing. What exists is the source of four built-in mods in the [Claude Code repository](https://github.com/anthropics/claude-code/tree/main/mods), an environment variable, and a public design thread. ## What is a Claude Code mod? Anthropic's [mods README](https://github.com/anthropics/claude-code/tree/main/mods) defines it in one sentence: "A mod is a Claude Code plugin whose behaviour lives in a hooks module: one `register(on, options)` entry that hooks the engine's events as functions `($, e, next)`." The name came on 9 September 2026, in [issue #91870](https://github.com/anthropics/claude-code/issues/91870): "A mod is just a plugin that uses function hooks." Function hook stays the name of the primitive. Mod is the name of the thing you build with it. On disk a mod is an ordinary plugin folder: - `.claude-plugin/plugin.json` , the usual plugin manifest. - `hooks/hooks.json` with a`"modules": ["./register.ts"]` key, which is the only part that makes it a mod. - TypeScript under `hooks/` , typed against declarations that the`/plugin-types` command prints. - Tests under `tests/` , run with`claude plugin test` . The execution model is middleware, the way [Express](https://stackness.dev/tools/express) and [Koa](https://stackness.dev/tools/koa) stack handlers. Each hook receives the event and a `next` function, and the plugin registered first wraps the ones after it. Every side effect goes through the `$` object (`$.fs`, `$.http`, `$.process`, `$.store`, `$.ui` and others), so an admin can remove a capability by removing it from `$`. Hooks run in-process on the [Bun](https://stackness.dev/tools/bun) runtime bundled with the CLI. Anthropic's engineer on the thread quotes "a p99 of 50μs per hook". ## What was the first built-in mod, and what does it do? The first one users ran was `agents-md`. It makes Claude Code read AGENTS.md as project instructions when no CLAUDE.md is present. It hooks `prompt.context` to change the list of instruction files the engine renders, `tool.call` on `Read` to pick up nested files, and `session.start`. The [AGENTS.md vs CLAUDE.md post](https://stackness.dev/blog/agents-md-vs-claude-md-which-file-claude-code-reads-and-the-flag-that-decided-it) covers the precedence rules. Thariq Shihipar of the Claude Code team explained where it came from, as [quoted by Simon Willison](https://simonwillison.net/2026/Sep/18/thariq-shihipar/): "AGENTS.md support is built off of Claude Code mods, our upcoming way to customize the Claude Code harness." The repository holds four built-in mods, each at plugin version 0.1.0: | Mod | What it does | Status on 25 September 2026 | |---|---|---| | `agents-md` | Reads AGENTS.md as project instructions. One option, `instructionFiles` | Live since 2.1.277. Gated on a remote flag until 2.1.281 | | `diff` | A `/diff` pane with uncommitted changes, file by file | Source only. The live `/diff` is still the hard-coded one from 2.1.260 | | `telemetry` | Gives built-in plugins a `$.telemetry` API. Refuses installed plugins | Seated on builds with analytics on. Silent under `DO_NOT_TRACK` and on Bedrock, Vertex or Foundry | | `sec-default` | Keeps the org's managed hooks, CLAUDE.md, settings and MCP allowlist out of reach of user plugins | Seated outermost on managed and Team or Enterprise machines only | The source landed on 9 September 2026 in a commit titled "Add mods: sec-default, diff and telemetry, the hooks-module plugins built into Claude Code". `agents-md` followed on 18 September. ## How is a mod different from a plugin, a skill, a hook or an MCP server? A mod is a kind of plugin, not a new format. The difference from the other extension points is where the code runs and what it can touch. Skills, CLAUDE.md and output styles change what the model reads. Classic hooks and MCP servers run outside the process. A mod runs inside the engine, sees typed events, and can change the engine's own behaviour, including what gets rendered and which tools exist. | Extension point | What it is | Where it runs | What it can change | |---|---|---|---| | CLAUDE.md or [AGENTS.md](https://stackness.dev/tools/agents-md) | Plain-text instructions | In the context window, every request | What the model reads | | Skill ( [Agent Skills](https://stackness.dev/tools/agent-skills) ) | `SKILL.md` plus files, loaded on demand | In the context window when used | What the model reads, when relevant | | Classic hook | Script, HTTP call, prompt or subagent on an event | Separate process, matching hooks in parallel | Allow, block or add context at fixed points | | [MCP](https://stackness.dev/tools/model-context-protocol) server | External process exposing tools and data | Separate process | Which tools and data the model can call | | Plugin | A bundle of the above, installed as one unit | Wherever its parts run | Whatever its parts can | | Mod | A plugin with a TypeScript hooks module | Inside Claude Code, in order, on Bun | Tool calls, prompt assembly, commands, UI, streamed output | Under mods, classic shell hooks do not go away. The engine wraps them as `classic.*` events, so a mod sees them too. A `tool.call` hook sees MCP and built-in tool calls alike, including those made by subagents. ## What can a mod change that CLAUDE.md cannot? CLAUDE.md is text the model reads. It cannot change how it gets loaded, which is why AGENTS.md support had to be a mod. From the four sources and the design thread, a mod can: - Rewrite the system prompt, the list of instruction files, and the model's streamed output. - Deny or rewrite a tool call with typed arguments, not a regex over a shell string. - Register slash commands that keep state in `$.store` . - Draw UI: panes, bands above the prompt, [React](https://stackness.dev/tools/react) components. - Apply ordered authority, where an org plugin seated first outranks everything a user installs. - Do all of it without spending a token. The limit: the model still sees what it asked to write, "for fundamental prompt caching reasons", so a mod that rewrites output changes what you see, not what the model remembers doing. ## How do you see and disable a mod in /config? Built-in mods show up in `/plugin` under the reserved `builtin` marketplace, where you can switch them off. `agents-md` also has a `/config` row, "Project instructions". In settings it reads: ``` { "pluginConfigs": { "agents-md@builtin": { "options": { "instructionFiles": "claude-md-and-agents-md" } } } } ``` The values are `claude-md-or-agents-md` (the default), `claude-md-and-agents-md`, `claude-md` and `managed-only`. The setting counts only in `~/.claude/settings.json`, a `--settings` file or managed settings, never in a project's own settings. `disableAllHooks`, `allowManagedHooksOnly` and `--bare` do not turn it off. To load a mod you wrote, run `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir ./my-mod`. ## What is shipped today, and what is only announced? Shipped: the `agents-md` mod in 2.1.277, the published source of four built-in mods, and an opt-in flag that loads your own. Announced: general availability for user-written mods, a stable `$` API, documentation and marketplace listings. The README says the API "may change between releases without notice". Third-party directories went ahead anyway. The [awesome-claude-code-mods](https://github.com/karanb192/awesome-claude-code-mods) list counted 72 mods across 142 candidate repositories on 17 September 2026. Its scanner found that 30 of them start host processes, 14 reach the network and 24 see every tool call. Claude Code's [plugin security page](https://code.claude.com/docs/en/plugins/security) already says a plugin "can execute arbitrary code on your machine with your user privileges", and permission rules do not cover code a plugin runs itself. A mod is the same trust decision, moved closer to the engine. The same list warns that setting the flag globally loads the hooks module of every installed plugin, not only the one you meant. Two failures are already on record. A privacy setting silently disabled a local feature, when `agents-md` sat behind the remote flag `tengu_agents_md_mod` until 2.1.281 ([Szypowicz](https://blog.szypowi.cz/p/claude-code-reads-agents.md-only-when-telemetry-is-on/)). And guards ported to mods ran "enabled, running, and doing nothing" in every terminal that lacked the variable ([Practical Systems](https://www.practicalsystems.io/blog/claude-code-function-hooks-mods-layer)). ## Which extension point should a change go in? Pick the weakest one that does the job. It is easier to review and it survives API changes. - **A fact or convention the model should know:** CLAUDE.md or AGENTS.md. - **A procedure the model should follow sometimes:** a skill. - **A check that blocks or logs at a fixed point:** a classic hook. It is documented and stable. - **A new tool or data source:** an MCP server, which also works in other agents. - **A change to how the harness itself behaves, such as prompt assembly, output or UI:** a mod, pinned to a Claude Code version, until the API is declared stable. The [harness post](https://stackness.dev/blog/what-is-a-coding-agent-harness-and-which-parts-of-it-actually-change-the-output) splits a coding agent into model, instructions, tools, context management and control loop. Mods are the first supported way to change the last of those in Claude Code without forking it. Claude Code is on 9 public Stackness profiles as of 25 September 2026 ([data sources](https://stackness.dev/about/data-sources)). Agent Skills and MCP have no listings yet, so there is no usage data on mods to add. ## Key numbers - **2.1.277** , released**18 September 2026** , shipped the first mod users ran,`agents-md` ([changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) ). - **9 September 2026** is when Anthropic named the feature "Claude Mods" and published the source of three built-in mods ([issue #91870](https://github.com/anthropics/claude-code/issues/91870) ). - **4** built-in mods are in the repository:`agents-md` ,`diff` ,`telemetry` and`sec-default` . One of them,`diff` , is not live yet. - **50μs** is the p99 per hook Anthropic quotes for in-process function hooks. - **72** community mods across**142** repositories, as of**17 September 2026** .**24** of them see every tool call ([awesome-claude-code-mods](https://github.com/karanb192/awesome-claude-code-mods) ). - **0** Claude Code docs pages mention mods or function hooks, checked on**25 September 2026** . ## Quick answers **What is a Claude Code mod?** A plugin whose behaviour is a TypeScript hooks module running inside Claude Code. It hooks engine events such as tool calls, prompt assembly and UI rendering, and can change them rather than only observe them. **Are Claude Code mods the same as plugins?** A mod is a plugin. What makes it a mod is a `hooks/hooks.json` that names a TypeScript module instead of shell commands. **Can I write my own Claude Code mod today?** Yes, as an early-access experiment. Set `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1` and load the plugin with `--plugin-dir`. The API is undocumented and may change between releases. **What was the first Claude Code mod?** `agents-md`, shipped in 2.1.277 on 18 September 2026. It reads AGENTS.md when there is no CLAUDE.md. **How is a mod different from a hook?** A classic hook runs a separate process at a fixed event and returns a verdict. A mod runs in-process, in a set order, with typed arguments, and can rewrite what the engine does. **Are Claude Code mods safe to install?** They carry the same trust as any plugin: they run code with your user privileges. Read the source, check what it can reach through `$`, and pin the Claude Code version.