SSD Nodes Learn Hosting plans →
Guides Matt ConnorBy Matt Connor

Claude Code mods and what they can reach

A Claude Code mod runs TypeScript inside the agent with your credentials in reach. See what it can touch on a VPS and the checks to run before you install one.

What a Claude Code mod is

A Claude Code mod is a plugin that ships function hooks. These are TypeScript functions that run inside Claude Code and wrap its engine events and UI surfaces. Each one controls both the input and the result of the event it wraps. The code runs in the same process as the agent, with the access of your user account. So a mod can reach every file and every network address that Claude Code itself can reach. On a VPS (virtual private server) that usually includes the login credential for your Claude account. This guide covers how a mod differs from the other ways to extend Claude Code. It then covers what security researchers showed a mod can touch, and the checks to run before you install one.

Status as of October 2026: released and on by default

Mods began as a proposal in anthropics/claude-code issue #91870 on 2026-09-03. A community update in the same issue on 2026-09-09 invited testers to try them with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude. On 2026-10-01 Anthropic staff announced that the feature was live. The Claude Code changelog lists it under v2.1.287: "Added Claude Mods: plugins may now modify deeper behavior". The mods documentation says mods are on by default, from v2.1.287 in the terminal and v2.1.286 in the Desktop app. As of 2026-11-21 the latest release is v2.1.330, released on 2026-11-20.

Released does not mean settled. The changelog has kept adding and fixing parts of the mods API since v2.1.287, including v2.1.318, which added an effort option to a mod's $.model.fork, and the README in the repository's mods directory still says the API "may change between releases without notice". Hook names and admin controls may both change. Treat each specific name in this guide as true for the builds the sources tested. Check the release notes for your own version before you depend on one.

The old flag no longer decides anything. The docs say "Claude Code v2.1.287 and later ignores the variable at any value, so a 0 there leaves mods on". If you set it during early access, remove it. To see whether mods can load on your server, check the version, then run claude plugin test from a directory that holds no mod:

claude --version
cd "$(mktemp -d)" && claude plugin test
grep -n CLAUDE_CODE_ENABLE_FUNCTION_HOOKS ~/.bashrc ~/.profile 2>/dev/null

If the output of claude plugin test includes no hooks module to load, mods can load. If it includes hooks modules are turned off here, a setting blocks them: disableAllHooks in your own settings, or your organization's policy. The command does not report the allowManagedModsOnly policy covered below. The grep line finds a leftover flag in your profile files so you can delete it. To turn off every mod you installed, set "disableAllHooks": true in ~/.claude/settings.json, which also stops your settings hooks and custom status line. To run one session without installed mods, start it with claude --safe-mode.

How a mod differs from hooks, skills, MCP and plugins

Claude Code already had four ways to extend it. A mod is a fifth way, and it sits closer to the engine than any of the others.

  • Classic shell hooks. A command listed in settings.json that Claude Code runs at an event such as PreToolUse. It runs as a separate process, reads the event as JSON and answers with an exit code or JSON. Our guide to classic Claude Code hooks and their exit codes covers the events and how a hook answers.
  • Skills. Markdown instructions, sometimes with helper scripts, that the model loads into its context when a task matches. A skill is text the model reads. Any command it leads to still passes through the normal tool permission flow.
  • MCP servers. An MCP (Model Context Protocol) server is a separate program that offers tools to the model. Each tool call is a request from the model, and Claude Code applies its permission rules to that request.
  • Ordinary plugins. A plugin is a package that bundles slash commands, subagents, skills, classic hooks and MCP server configs. The format and the marketplaces are covered in what a Claude Code plugin contains and how to install one.

A mod is a plugin whose package also holds a TypeScript module of function hooks. The difference is where that code runs and what it controls. A classic hook watches an event from outside and returns a verdict. A function hook wraps the event, like middleware in a web framework. It receives the input and decides whether to call the next handler. It can also replace the result before anything else sees it. The issue describes plugins that nest in the order they are registered, so the first one registered wraps all the rest. A hook can also register for a wildcard and see every event.

Mods can also draw UI. Function hooks attach to UI surfaces as well as to engine events, so a mod can render its own content inside the Claude Code interface. A classic Claude Code status line is a script, and Claude Code shows its printed text in one fixed place. A mod draws into the interface itself. The fake-prompt result further down depends on exactly that.

The $ interface: one object for every privileged action

Every privileged action a mod takes goes through one object, called $. Reading a file, running a command, reaching the network and drawing UI are all done through $. The design goal in the issue is tracking. If every side effect passes through one object, Claude Code can record what a mod does, and an admin can wrap that object.

Tracking is not a boundary. vanja.io looked at an engine.create hook that strips nouns such as $.fs from $ before other mods receive it. Their note is direct: stripping $.fs removes that API entry, and routing calls through $ "is not a sandbox". The model's own tools are untouched. Other parts of $ can still reach the filesystem, for example by running a process. Removing $.fs takes away one obvious path to your files and leaves the other paths open.

What pluto.security showed a mod can reach

On 2026-09-22 pluto.security published tests of mods against Claude Code v2.1.274. Four results matter for anyone who runs Claude Code on a server.

It read the Claude credential file. A test mod used its $ interface to read ~/.claude/.credentials.json. That file holds the OAuth credential for the Claude account. File permissions do not help here, because the mod runs as your user inside the Claude Code process. Setting chmod 600 on that file stops other users. It does not stop code that you loaded as yourself.

It reached the network. The same mod sent what it read to a server the researchers controlled. ufw ships with default allow outgoing. That default does not stop the request.

It drew UI that imitates Claude Code. A mod showed a prompt styled like Claude Code's own prompts and asked for a credential. A user who types a key into that prompt hands the key to the mod. In the test, nothing on screen showed that the prompt came from a plugin.

Plugin details under-reported it. pluto.security found that the plugin details view can report a mod that hooks everything as having zero hooks. A plugin with one classic hook was listed correctly. So the screen you would use to judge a mod can tell you that the mod does nothing.

Why a mod on a VPS reaches more than you expect

On a laptop, Claude Code shares the machine with your browser and your documents. On a VPS it often shares the machine with everything you deploy. A typical agent box holds the Claude login, a git deploy key in ~/.ssh, .env files with database passwords, and cloud CLI credentials. The agent often runs for days inside tmux. A mod loaded at session start runs until it is disabled, unloaded or the session ends.

A mod can reach all of that, because it has the access of the user that started claude. The controls that work are the ones that limit that user. Run Claude Code as a dedicated account that owns only the project it works on, as described in running Claude Code safely on a VPS. Keep long-lived secrets out of that account's reach. The guide on keeping secrets out of AI coding agents covers this step by step. To try a plugin you do not trust yet, use a machine you can delete afterwards, as in running coding agents in a disposable VM.

A checklist before you install a Claude Code mod

pluto.security's main advice is to treat a mod as a program that you run. Each step below follows from that.

  1. Read the module source, not the listing. The plugin details view can under-report hooks, so open the TypeScript files yourself. Note which events the mod hooks, whether it registers a wildcard, and which parts of $ it uses. A status-line mod that hooks every event needs a good reason. On current versions, claude plugin validate ./some-mod prints hooks: and calls: lines that list the events the mod handles and the $ methods it calls. Use that as a second check, not as a replacement for reading the code.
  2. Pin the version you read. A plugin that follows a branch can change after you install it. Record the exact commit you reviewed. If you install from a marketplace you control, point its entry at that commit and not at a branch name. Read the diff before each update.
  3. Distrust mods that fetch remote code at runtime. A mod that downloads code and runs it can turn malicious after your review, because the code you read is not the code that runs. Reject any mod that fetches a URL and then evaluates or imports the response.
  4. Search the installed files for network calls and generated code. Plugins install under ~/.claude/plugins/. The search below lists every line that names a URL or builds code at runtime.
  5. Treat any credential prompt inside a session as hostile. If a prompt inside Claude Code asks you to paste an API key or a password, do not type it. Exit the session. Start a new one, open /plugin and review what is installed.

The search for step 4:

grep -rnE 'https?://|eval\(|new Function|import\(' ~/.claude/plugins/

Each hit is a line to read, not proof of harm. A mod that names a URL may only link to its own documentation. A mod that builds code from a string it downloaded is the case to reject.

Admin levers: what the sources name

If you run Claude Code for a team, the mods admin documentation documents these controls for mods. Each one goes in managed settings. Do not read more into them than the docs say.

  • allowManagedModsOnly is an option on the built-in guard, set under pluginConfigs with the key cc-plugin-sec-default@builtin. No mod a user brings runs its hooks, whether it was installed, loaded with --plugin-dir or written by Claude during a session. Your organization's own mods and the mods built into Claude Code still run, and users' settings hooks and status lines keep working.
  • allowManagedHooksOnly is wider. Only your organization's mods and the built-in mods load, and it also blocks hooks in users' own settings files.
  • disableAllHooks is the widest. In managed settings it stops the mods in every installed plugin, your organization's included, and every hook in settings files, so a managed PreToolUse hook no longer blocks anything. pluto.security also names it as the switch that blocks all hooks across the organisation. Agent SDK hooks and built-in mods keep running.
  • disableSideloadFlags rejects --plugin-dir and --plugin-url at startup and keeps mods Claude writes during a session from loading. It also rejects --agents and --mcp-config.
  • sec-default is the built-in guard mod. By default, it loads ahead of every mod a user installs on a machine that has managed settings or a managed-mcp.json file, in a session running on Team or Enterprise /login credentials, or wherever hipaa-default applies. Users cannot turn it off. A user who signs in with an API key gets it on a machine with managed settings or managed-mcp.json, or wherever hipaa-default applies. A session using CLAUDE_CODE_OAUTH_TOKEN does not count as that login, even if a Team or Enterprise login is stored on the machine. If you set prependPlugins in managed settings, include sec-default@builtin to keep the guard loaded. It keeps a user's mod from changing your managed hooks, your managed instructions, the system prompt, what mods read as settings and the tool list and descriptions of connected managed MCP servers. On v2.1.323 or later, a user's mod can keep a managed MCP server from connecting; block users' mods to prevent that. Where it loads, a user's mod cannot approve a tool call that a deny rule refuses, unless you set its allowModsToOverrideDenyRules option to true.
  • hipaa-default is a built-in policy mod for organizations under HIPAA. When it applies, managed deny rules cover users' mods' direct $.fs.read, $.fs.list, $.fs.write, $.process.run and $.process.spawn calls, matched against the equivalent file tool or Bash command. Organization-owned code and built-in mods are exempt unless a hook rewrote the call. These checks cover the file call or the command's plain form, not what a program does once it runs. It loads ahead of sec-default once the session knows its organization is under HIPAA.

On Linux, managed settings live in /etc/claude-code/managed-settings.json. Settings in that file take precedence over user and project settings. Make the file owned by root so a normal user cannot edit it. A minimal file that allows only admin-installed hooks looks like this:

{
  "allowManagedHooksOnly": true
}

To block only users' mods and leave their settings hooks alone, set the guard option instead:

{
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": {
        "allowManagedModsOnly": true
      }
    }
  }
}

Use "disableAllHooks": true instead if you want no installed mods or configured hooks. Agent SDK hooks and built-in mods keep running. To confirm the guard option on a machine, start a session with --plugin-dir and a directory that holds a mod. The mod's hooks do not run, and the debug log names the mod and allowManagedModsOnly.

When a mod is the right tool

The reach that makes mods risky also makes them useful. A mod can enforce a policy at the engine, before a tool call happens, instead of asking the model to follow a rule. It can add a live pane to the interface, which a shell script cannot draw. An admin can register a mod first so that it wraps every user plugin.

Most changes do not need that reach. If you want the agent to follow a procedure, writing your own agent skill does that with text the model reads, and no new code runs as your user. If you want a check before each tool call, a classic hook works. It is a separate process with a short, documented contract. Choose a mod when the job needs to control an event's input or result. Then apply the checklist above to your own mod, as you would to anyone else's.

FAQ

What is the difference between a Claude Code mod and a plugin?

A plugin is a package format. It can bundle slash commands, subagents, skills, classic shell hooks and MCP server configs. A mod is a plugin that also ships function hooks. These are TypeScript functions that run inside the Claude Code process and wrap engine events and UI surfaces. They control both the input and the result of those events. Every mod is a plugin, but most plugins are not mods.

Can a Claude Code mod read my Claude login credentials?

Yes. pluto.security tested Claude Code v2.1.274 on 2026-09-22. In that test, a mod read ~/.claude/.credentials.json through its $ interface and sent data to an outside server. File permissions do not prevent this, because the mod runs as the same user as Claude Code. Limit what that user can read, and read a mod's source before you install it.

Does removing $.fs from a mod sandbox it?

No. An engine.create hook can strip nouns such as $.fs from the $ interface. vanja.io points out that routing calls through $ "is not a sandbox". It removes one API entry. The model's own tools still work. Other parts of the interface can still reach the filesystem, for example by running a process.

How do I stop users on a shared server from loading mods?

Set allowManagedModsOnly on the built-in guard in /etc/claude-code/managed-settings.json, under pluginConfigs with the key cc-plugin-sec-default@builtin. Users' own mods then do not run their hooks, and their settings hooks keep working. allowManagedHooksOnly also blocks hooks in users' settings files, and disableAllHooks blocks configured hooks, your managed ones included, while Agent SDK hooks and built-in mods keep running. Add disableSideloadFlags to reject --plugin-dir. The built-in sec-default guard protects what you manage and keeps deny rules in force for the model's calls. Where hipaa-default applies, managed deny rules also cover users' mods' direct file and process calls.

Are Claude Code mods stable enough to depend on?

They are released, but still moving. Mods were proposed on 2026-09-03 in anthropics/claude-code issue #91870, and testers were invited to try them with the CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 flag on 2026-09-09. Anthropic staff announced them as live on 2026-10-01, and they shipped in Claude Code v2.1.287, on by default. The changelog has kept adding and fixing parts of the mods API since then, and the repository's mods README still warns that the API may change between releases without notice. Expect hook names and the $ interface to change. Pin any mod you use to a version you have read.

Was this article useful?