Byte by Mahmud logoByteby Mahmud

Byte

You Can Now Mod Claude Code. Read the Fine Print Before You Install One.

Technology6 min read3 views

You Can Now Mod Claude Code. Read the Fine Print Before You Install One.

Mahmud Hasan

Mahmud Hasan

October 3, 2026

On October 1st, Anthropic did something it hasn't done before with Claude Code: it handed developers the keys to the agent's internals. A new feature called mods lets you write small TypeScript functions that hook directly into Claude Code's session events — rewriting prompts before they reach the model, intercepting tool calls, answering permission requests, and even redrawing the interface. Mods install with a single /plugin command and they're on by default in Claude Code 2.1.287.

There's a catch, and Anthropic printed it in plain English rather than burying it: mods aren't sandboxed. A mod runs with the same access to your machine as Claude Code itself. That makes this the most powerful extension point ever shipped for an AI coding agent — and the one with the sharpest edge.

What actually shipped

A mod is a JavaScript or TypeScript module that loads for the session and registers event handlers through an exported register function. It plugs into events like session.start, turn.start, turn.complete, prompt.submit, tool.call, command.run, and ui.render. On each one, the mod can run before the default behavior, after it, or instead of it — three moves the docs describe as observe, rewrite, or answer. Returning something like { deny: "..." } without calling next() means the event never reaches Claude Code at all.

The module has no DOM and no Node; everything outside itself goes through the mods API, written as $. It's a deliberately narrow programming surface — but "narrow" means a programming surface, not a permission boundary. The module can still read your files, start processes, and make network requests.

Mods ride inside Claude Code's existing plugin system, which has been around since October 2025 for bundling commands, subagents, MCP servers, and hooks. Installation is familiar territory: add a marketplace, install the plugin, done — from the CLI or the desktop app. Mods can target the terminal, the desktop, or both, and they stack: when several mods hook the same event, they run in load order, with the first-loaded mod seeing the event first and the result last. They come with Claude Code 2.1.287 and are on by default.

The examples tell you the range

Anthropic shipped three official sample mods, each one solving a small, real annoyance working developers will recognize instantly.

  • Token Weather (about 80 lines of code) draws a live forecast of how full your context window is, above the prompt, with a sparkline of the previous twelve turns.
  • Blast Radius intercepts dangerous shell commands — rm -rf, hard Git resets, force pushes — holds the call, previews what it would affect, and offers Proceed or Cancel.
  • Replay Theater records the file edits from a turn and lets you step through the diffs one change at a time.

But the most important example isn't a sample at all. Anthropic is moving its own features onto the mod system: /diff is already a mod you can disable or replace, and AGENTS.md loading plus telemetry are built-in mods too, with more to follow. That matters more than the API surface. Extension APIs the vendor doesn't use itself tend to rot; one that carries the product's own features has to keep working, and it hands everyone reference implementations written by the people who designed the system.

Building one is deliberately cheap

The fastest path is the one Anthropic wants you to take: ask Claude Code to build the mod for you. Describe what you want in plain language, let it scaffold the plugin, iterate with hot reload, and copy the folder out when you're happy. The launch post's best line — "You can also use Claude Code to mod Claude Code" — isn't marketing fluff: the cost of a personal tool drops to one descriptive sentence and a few rounds of hot reload.

The manual path is a skeleton of known files: .claude-plugin/plugin.json for metadata, hooks/hooks.json naming the module to load, and the module itself exporting register. During development, every save reloads the module without a restart — though a reload is a fresh load, so anything that must survive goes in $.state, not module-level variables. The generated TypeScript types in .claude-plugin/types/ are the authority for your installed version, since the API can change between releases. When you're ready to share, claude plugin validate and claude plugin test run the plugin against the real Claude Code runtime before anyone else touches it.

Good first mods to try: a session cost meter, a confirmation step before production commands, a CI status pane, secret redaction on tool output, audit logging of tool calls. Keep them small — and expect to regenerate them now and then as the API moves.

Now the part worth reading twice

A code editor extension can read your files. A mod can do that — and also rewrite the prompt you typed, change a tool call before it runs, and approve a permission request on your behalf. That last one is the one to sit with. The permission prompt is the point where a person stays in the loop with a coding agent, and a mod is allowed to answer it. A careless or hostile mod doesn't need an exploit. It only needs to be installed.

The docs list exactly what a loaded mod can do, including "read your secrets: environment variables and settings files." There is one hard line: a mod can restyle much of the interface but not the permission prompt itself. It can't change what a prompt shows you, so the dialogue asking you to approve a command stays Claude Code's own. You'll always see the actual request — even if a mod can answer it for you.

For teams, there's an actual backstop. On Team and Enterprise plans — and any machine with managed settings — a built-in mod called sec-default loads first and blocks risky behavior like overriding a permission-deny rule. The load-order design makes this work: the first mod to load sees each event first and the result last, so a security default that loads first can't be quietly undone by something installed later. Admins can load their own mods early too, and they get marketplace allow and block lists. Individuals get no such backstop. If you work alone, you are the admin, and the review step is yours.

Practical rules, then, none of them exotic:

  • Install mods the way you'd install packages: read the source, trust the publisher, never install a plugin folder from a link you can't vouch for.
  • Treat internal mods like production code: review them, pin versions, keep an audit trail.
  • On Team and Enterprise: use the marketplace lists, leave sec-default loading first, and test the load order on purpose by trying to override a deny rule with a second mod.
  • Start with one guardrail that pays for itself — production-command confirmation or secret redaction — before you collect a library of fun ones.

Why this launch is bigger than it looks

The old settings hooks could run a shell command and exchange JSON; they couldn't rewrite events, draw live UI, or replace a built-in. Mods can — they're interventions inside the agent loop, not bolted-on additions. And Anthropic dogfooding it is the tell: when a vendor moves /diff and AGENTS.md support onto the same mechanism it hands to strangers, it's saying the extension point isn't a side door, it's becoming the architecture.

Expect the library of private, unglamorous mods to dwarf the public ones: every team's house rules, every company's audit requirement, every developer's "I keep forgetting to check this" — encoded as event hooks that load before anything else gets a word in.

Just remember what the permission boundary actually is now. It's not a sandbox. It's whoever wrote the last mod you installed. Choose accordingly.

References

Comments

Leave a comment

Your email stays private — only your name is shown.

Back to all articles

More in Technology