Manage mods for your organization - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. A mod is a plugin that runs code inside Claude Code with the permissions of the user who installed it. Mods aren’t sandboxed. Through managed settings , you decide whether mods run on your users’ machines, which ones, and in what order.
You can also install a mod of your own that watches or refuses what other mods do. This page is for the person who deploys managed settings for Claude Code, whether as a file, through MDM, or from the claude.ai admin console. Mods are on by default in Claude Code v2.1.286 and later. Start with the section that matches what you came to do: Keep users’ own mods out, with or without mods of your own : Stop user-installed mods from loading See what your users get when you change nothing : Know what happens by default Leave mods on with other limits : Choose how much to allow These cases are covered on other pages: You haven’t deployed managed settings before : start with Deploy managed settings You want to control which plugins users can install : see Manage plugins for your organization Stop user-installed mods from loading To keep every mod your users bring from running its hooks, set the allowManagedModsOnly option on the built-in guard , a policy mod that Claude Code loads ahead of every mod a user installs.
The option goes in managed settings under pluginConfigs , keyed by cc-plugin-sec-default@builtin : managed-settings.json { "pluginConfigs" : { "cc-plugin-sec-default@builtin" : { "options" : { "allowManagedModsOnly" : true } } } } With the option set in managed settings: No mod a user brings runs its hooks : that covers a mod in a plugin the user installed, a mod loaded with --plugin-dir , and a mod Claude wrote during a session Your organization’s mods still run : a mod that counts as your organization’s isn’t checked.
Every other mod counts as a user’s and is refused. That includes a mod your organization turns on for its members on claude.ai. If none counts as yours, no installed mod runs its hooks. Users can’t undo it : the guard reads the option from managed settings only, so the same entry in a user, project, or local settings file, or in a file passed with --settings , changes nothing A file or MDM policy covers every provider : when you deliver the option as a file or through MDM, it works the same way on Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry.
For delivery from the claude.ai admin console, see Platform availability Users’ other customizations keep working : their hooks in settings files and in plugins’ hooks/hooks.json , status lines, and /goal aren’t affected Built-in mods keep running : mods built into Claude Code, such as AGENTS.md support, each have their own switch To confirm the option on a user’s machine, start Claude Code there with --plugin-dir and the path of a directory that holds a mod, such as claude --plugin-dir ./first-mod .
The mod’s hooks don’t run, and the transcript and the debug log have the guard’s message , which names the mod and allowManagedModsOnly . If the message isn’t there, see Check that a policy is in force and the rules that decide whether an option takes effect . If you set CLAUDE_CODE_ENABLE_FUNCTION_HOOKS to 0 during early access, replace it with this option. Claude Code v2.1.287 and later ignores the variable at any value, so a 0 there leaves mods on.
Know what happens by default With no mod settings of your own, this is what your users get: Mods are on. A user can install a plugin that contains a mod from any marketplace your plugin settings allow, or load one from a directory with --plugin-dir . A built-in guard runs first. Claude Code loads a built-in mod named sec-default@builtin ahead of every mod a user installs. Users can’t turn it off. /plugin and the debug log list it as cc-plugin-sec-default .
The guard loads when either of these is true: The machine has managed settings or a managed-mcp.json file The session runs on /login credentials for a Team or Enterprise plan A user with an API key, or on Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry, gets the guard only on a machine with managed settings or managed-mcp.json . A session that runs on a long-lived CLAUDE_CODE_OAUTH_TOKEN doesn’t count as that login either, even when a Team or Enterprise login is stored on the machine.
When the guard loads, it blocks a user’s mod from rewriting: The system prompt Your managed CLAUDE.md and other managed instructions The answer a mod gets when it reads settings The tool list and tool descriptions of a managed MCP server that has connected On v2.1.323 or later, a user’s mod can keep a managed MCP server from connecting. In that user’s session, /mcp lists the server as held by that mod. To prevent it, stop user-installed mods from loading .
Apart from what the guard blocks, a user’s mod acts as that user. The mod keeps that user’s permissions: it can still read and write files, start processes, and make network requests. It can also rewrite tool calls and the user’s prompts, deny a tool call, add or remove tools, and draw in the interface. When a user’s mod approves Claude’s call with the guard loaded, these outcomes hold by default , whichever settings file has the rule or hook: A call that a deny rule refuses stays refused A call that an ask rule would prompt for still prompts A call that a PreToolUse hook blocked stays blocked A mod’s own calls can skip your checks.
To limit a user’s mod, keep it from loading or handle its calls in a policy mod . Files and programs : $.fs and $.process calls can skip permission rules and PreToolUse hooks. With Read(.env) denied, a mod can still read that file with $.fs.read or start a program that does. Tools : calls such as $.tool.call and $.mcp.call can skip permission rules, permission prompts, a hook’s ask , and the auto mode classifier. Without the guard, a user’s mod can skip more checks.
See what it can skip . The guard’s source is public in the mods/sec-default directory of the Claude Code repository . Know which controls still apply Your existing controls cover mods within these limits: Hooks in settings files run alongside mods. See where settings hooks run in the order . For Claude’s calls, deny rules take precedence over a user’s mod where the guard loads. To let a user’s mod approve some calls that a deny rule refuses, set allowModsToOverrideDenyRules .
Managed hooks run first. A PreToolUse hook in managed settings runs before any mod’s tool.call hook, and when that managed hook blocks a tool call, no mod’s tool.call hook runs for that call. If the call goes ahead and a mod rewrites it, your managed hooks run again on the rewritten call, so by default they can still block it. PreToolUse hooks from other settings files and from plugins run after the last mod. If a mod answers the tool call itself, the tool never runs and neither do those hooks.
See The order mods run in . Network policy covers $.http.fetch . Your organization’s policy doesn’t allow WebFetch : Claude Code also refuses every mod’s $.http.fetch request. See WebFetch availability . You turn off the WebFetch tool with CLAUDE_CODE_DISABLE_WEB_FETCH or a WebFetch deny rule , in managed settings or any other settings file : mods can still make $.http.fetch requests. To stop them for every mod your users install, keep user-installed mods from loading , or hook http.fetch in a policy mod and refuse requests from users’ mods.
Give that hook a .catch handler that refuses too, because Claude Code skips a hook that fails and the request then goes ahead. If you only restrict which plugins users can install , fewer mods load, but those you allow still make these requests. You set CLAUDE_CODE_DISABLE_NONES
The rest of this page is on the live site.