DEV Community: Pawel

Claude Code Mods Aren't Sandboxed. Neither Is Your Understanding of "Sandboxed".

Pawel — Sun, 04 Oct 2026 13:49:49 +0000

Two statements about Claude Code mods, both true, both from Anthropic's own docs:

The module runs in a sandbox of its own, with no DOM and no Node.
"Mods aren't sandboxed."

The first two days of the mods launch have been one long argument about which of these is the lie. Neither is. The confusion comes from the word "sandbox" doing two different jobs, and once you separate them, the real trust boundary snaps into focus. It is not where most people think it is.

Sandbox #1: the JavaScript runtime

When you write a mod, your module gets a private little world. No document. No window. No Node globals. If your code wants to touch anything outside itself, files, processes, the network, the UI, it goes through one object: $.

export function register(on) {
  on("tool.call", { tool: "Bash" }, async ($, e, next) => {
    const listing = await $.fs.readDir("/tmp");   // through $, not fs
    return next(e);
  });
}

This is sandbox #1. It is a language-level sandbox: it constrains how your code reaches the outside world, not whether it can. Every capability lives behind the $ API, which means the engine can see every request, log it, and (in theory) gate it. Think of it like a phone where every app must use the official APIs. The APIs still include the camera.

Sandbox #2: the one that does not exist

Here is what the documentation says, and I am quoting because paraphrasing would soften it:

"A mod is code that runs with your permissions. It can read and write your files, start processes, and make network requests. Install mods only from authors and marketplaces you trust."

And:

"Mods aren't sandboxed. If you turn on sandboxing, the sandbox isolates the Bash commands Claude runs, and a process that a mod starts runs outside it."

Read that second one twice. Claude Code has a sandboxing feature, and it sandboxes Claude's Bash commands. A mod that starts its own process steps cleanly outside of it. The fence was built around the agent, not around the extension.

The capability list gets worse the further you read. A mod can:

Read your secrets: environment variables and settings files, "including an API key you keep in either".
Approve tool calls you blocked: a mod that approves tool calls can green-light one "that an ask rule would prompt for, or that one of your own PreToolUse hooks blocked". Your hook said no. The mod says yes. The mod wins.
Rewrite events before you see them: hooks form a chain, and a mod can observe, rewrite, or fully answer any event. Including the ones your audit logger was counting on.

So when someone says "mods are sandboxed", they are describing the JS runtime. When Anthropic says "mods aren't sandboxed", they are describing your files, your processes, your network, and your API keys. Both true. The second one is the one that matters.

The one hard boundary

There is exactly one thing Anthropic drew a hard line around, and it is telling:

"A mod can restyle much of Claude Code's interface, but not the permission prompt. It can't change what a prompt shows you."

A mod can redraw almost the entire UI, panes, bands above the prompt, toasts, but the permission dialog stays Claude Code's own. Whatever else a mod draws, the moment that asks "are you sure?" cannot be faked, restyled, or have its contents swapped.

Think about why that specific line exists. If a mod could restyle the permission prompt, it could show you "run tests?" while actually approving rm -rf. Anthropic hardened the one UI element where your eyes are the security control, and left everything else open. That tells you exactly what threat model they designed for: the mod is untrusted code with your privileges, and the permission prompt is the last honest surface in the room.

The mental model that actually works

Stop picturing a browser iframe. The right mental model is much older and much simpler:

Installing a mod is giving someone your shell.

Not a restricted shell. Not a shell with an auditor watching. Your shell, with your env vars, your files, your network, and the ability to overrule the guardrails you built for the agent. The JS-runtime sandbox is real engineering, it keeps modules from stepping on each other and gives the engine a clean interception point, but it was never a security boundary between the mod and your machine.

Once you have that model, the hygiene checklist writes itself:

claude plugin validate before you install, not after. It lists the events a mod handles and what it asks Claude Code to do, file reads, network requests, without running any code. Read it like you would read the permissions screen on a phone app. If a context-bar mod wants network access, ask why.
Know your off switches. Disable one plugin from the Installed tab in /plugin. Start a session with --safe-mode to drop all customizations. Set "disableAllHooks": true in ~/.claude/settings.json for the wide kill switch. Organizations get allowManagedModsOnly, which stops user-installed mods from loading while skills, commands, and MCP servers keep working.
Audit the small ones hardest. A 40-line UI mod feels safe because it is small. But 40 lines is enough to read ~/.claude/settings.json, exfiltrate an API key, and approve the tool call that covers its tracks. Size is not a security property.

None of this means you should not install mods. It means you should install them the way you would hand your laptop to a colleague: only to people you trust, and knowing exactly what they can reach while they have it.

So here is my question: what does your claude plugin validate say about the mods you have already installed? And did you read it before, or just now?

I Built My First Claude Code Mod Without Writing Code: Claude Wrote It, Validated It, and Hot-Reloaded It

Pawel — Sat, 03 Oct 2026 09:19:53 +0000

I wanted one thing: to see my context window without typing /context.

Not a dashboard. Not a plugin I install and configure for twenty minutes. Just a small bar above the prompt that tells me how full the window is, the way the /context command does, but always on screen. One sentence of a prompt later, it was there.

This is the story of the first Claude Code mod I built without writing a single line of code. Claude wrote it, validated it, tested it, and hot-reloaded it into my session. I just watched.

What a mod actually is

Claude Code mods (shipped in v2.1.287, on by default) are small JavaScript or TypeScript modules that live inside a plugin. They see every event in your session as it happens: tool calls, the prompt you submit, turns starting and ending, and every piece of the interface as it is drawn.

That last part is the new bit. Mods can rewrite what Claude Code does and draw their own UI: a pane, a band above the prompt, a status line entry, a toast. Everything the engine draws is a component you can hook into.

And here is the part that still feels strange: you do not need to learn the API to try one. You describe the mod you want, and Claude Code builds it.

Step 1: ask for it

Open any project, run claude, and paste a prompt like this:

Create a mod that draws my context window as a stacked bar above the prompt, one colour per category like /context, toggled with /context-bar.

Claude Code loads its own plugin-authoring skill, reads the engine's type declarations, and writes three or four files into a session folder under ~/.claude/dev-mods/. Then it asks one question: allow hot reloading for this session?

Say yes. When the turn ends, the bar appears above your prompt.

That is the moment that sold me. I did not open an editor. I did not read the docs. I described a UI in plain English, and it showed up.

Step 2: make Claude validate its own homework

Before I even looked at the code, I asked for two things while the session was still warm:

Run claude plugin validate on the folder. The validator reads the module the way the engine will and names anything the engine would refuse. Think of it as a compiler for mods: non-negotiable.
Write a tests/ file and run claude plugin test. That exercises the hooks against the real engine. No TypeScript toolchain needed on your machine.

This is the difference between "Claude wrote something plausible" and "the engine will actually load this". An LLM will happily produce a mod that looks right and fails at load time. Validate and test are what separate the magic from the garbage.

Step 3: peek under the hood (optional, but worth it)

Curiosity won, so I read the code. A mod is one module exporting register:

export function register(on) {
  on("ui.render", { component: "AbovePrompt" }, ($, e, next) => {
    const { Box, Text } = $.ui.resolve(e);
    return Box({
      paddingX: 1,
      children: [Text({ children: "hello from my mod" })],
    });
  });
}

The shape is middleware. Your hook runs, then next(e) hands the event to the next plugin in the chain, then to Claude Code itself. Every hook does one of three moves:

Observe: call next(e), then look at the result. Record every file edit, take a reading after each turn.
Rewrite: call next with a modified event. Change what the rest of the chain sees.
Answer: skip next entirely and serve the event yourself. Refuse a tool call, handle a slash command.

One detail I stole from Addy Osmani's guide: do not keep history in a module-level let. Hot reload is a fresh load, register runs again, and module variables start over. Keep readings in $.state, declared in a small types contract, and they survive reloads. If you skip the contract, claude plugin validate stops you with an error that names the fix. The tooling here is genuinely good.

Step 4: make it permanent

The session folder dies with the session. Copy the mod somewhere stable:

mkdir -p ~/.claude/mods
cp -R ~/.claude/dev-mods/<session-id>/context-bar ~/.claude/mods/context-bar

Keep the manifest in .claude-plugin/plugin.json, the hooks/ folder with its module, and the types/ contract if the mod keeps state. Copy tests/ too, so you can rerun the tests after an update.

Then tell Claude Code where it lives. The one place that reaches every session, including the ones the desktop app starts, is the env block of your user settings file. Open ~/.claude/settings.json and add:

{
  "env": {
    "CLAUDE_CODE_PLUGIN_DIRS": "/Users/you/.claude/mods/context-bar"
  }
}

Use the full path, not ~. Several mods are separated with a colon. For a one-off terminal session, claude --plugin-dir ~/.claude/mods/context-bar does the same without touching settings.

Open a new session in any project. The bar is above the prompt before you type anything, and /context-bar hides it.

Two things that bit me

Early access means churn. The API can change between releases, so a mod written today may need a touch-up after an update. Rerun claude plugin validate after every upgrade. It is cheap insurance.

Check which claude you are running. The desktop app bundles its own engine, and the one on your PATH may be older. Mine was, and its validator did not recognize the hooks module at all. Validate with the app's bundled binary, or update the CLI first. This cost me twenty confused minutes staring at an error that was not mine.

Why this feels different

I have used hooks, slash commands, and skills. A settings hook runs a shell command per event and passes JSON over stdin and stdout. A mod loads once, keeps state, draws UI that updates as events happen, and can call back into Claude Code: open a pane, run a process, register a slash command, register a tool the model can call. Some of Claude Code's own features are built as mods, including AGENTS.md support and the /diff pane. Their source is public, so you can read how the team builds them.

But the real shift is the loop. The skill for writing mods ships inside Claude Code, so the agent modifies its own runtime, in the same session, and hot reload shows you the result on the next turn. I kept asking for tweaks ("add a legend line with per-category token counts", "show a toast when context crosses 85%") and watched the bar change. It felt less like configuring a tool and more like pair programming with the tool itself.

If you could describe a mod in one sentence, what would it do?