Using Claude Code Mods: enabled defaults, installation, and troubleshooting

Check the version first: what changed

The official v2.1.287 release on October 1, 2026 at 18:00 UTC introduced Claude Mods. They target people customizing development workflows, such as displaying context status, adding commands, or introducing interaction before tools execute. If you only need a fixed set of writing or coding instructions, an existing Skill may still be more appropriate. New functionality does not require rebuilding your configuration.

v2.1.288, released on October 2 at 20:19 UTC, added $.ui.selection() and fixed issues including Mod tool.call affecting worktree subagent paths and background sessions exiting when plugins were reloaded or disabled. If these symptoms occur, first check whether the installed version includes the fix before changing Mod code. Later fixes are not a separate product. This article checked documentation on October 4 Beijing time and did not install or run it in the reader's environment.

v2.1.289, officially released on October 3 at 23:07 UTC, further fixed installed Mods not loading in the first session after an upgrade, and plugin listings, evaluation, and updates showing stale copies for local-folder marketplaces. If Mods are missing immediately after upgrading, check the actual running version before deleting configuration.

This release also fixed user-installed Mod approvals overriding deny or ask rules inside compound shell commands on managed machines, and Read deny not applying to files referenced through IDE symlinks. Frequent VS Code sign-outs may relate to the claude auth status change in v2.1.288, which 289 reverted. These fixes address specific scenarios and do not mean all permission or sign-in problems are resolved.

Upgrade to a version containing the fix, then verify again

For native installations, run claude update. For npm installations, run npm install -g @anthropic-ai/claude-code@latest. Restart Claude Code afterward and run claude --version. An old session still running does not mean it is using the new version. claude doctor shows installation status and recent update attempts.

Homebrew users should run brew upgrade claude-code or brew upgrade claude-code@latest according to their original installation. WinGet users should run winget upgrade Anthropic.ClaudeCode. Package channels may provide versions later than the announcement, so check the version even after a successful command. If it is below 2.1.289, inspect the update channel and organizational version restrictions first.

stable generally trails latest and does not guarantee immediate availability of a newly released fix. Native installations can inspect Auto-update channel in /config; Homebrew's cask name determines the channel. Team users should follow administrator upgrade arrangements instead of disabling restrictions to force a switch. After upgrading, repeat plugin-loading and minimal-function checks to confirm whether the original symptom disappeared.

Choosing between Mods, plugins, and hooks

A plugin is the distribution and installation container. A Mod is its JavaScript or TypeScript event-handler component. These functions execute inside Claude Code and can observe, modify, or take over particular events. One plugin can also contain Skills, MCP services, and other components, so an installed plugin does not prove its Mod is running.

Choose from the desired result backward: use a Skill for repeatable work instructions; inspect settings hooks first for running existing scripts after specified events; consider MCP for external tools; and evaluate a Mod for interactive panels in the session interface or finer combinations of event handling. This also makes it easier to identify which component owns a failure.

Three checks before installation

First, run claude --version in the terminal and confirm at least v2.1.287. For first-session loading failures after upgrading or the permission issues above, also confirm that v2.1.289 fixes are included. Second, verify the actual plugin author, marketplace name, and source. Third, confirm that the personal or organizational environment permits that Mod. Meeting the software-version requirement does not establish organizational approval.

Mods run with the current user's permissions. Official guidance says they can access files, environment variables, and session content, and launch processes, network requests, and model calls. Claude Code's Bash sandbox does not isolate the Mod itself. Reviewing the author's code and plugin documentation helps determine whether these capabilities fit the actual work scope; a successful installation notice alone does not establish trust.

From installation to confirming loading

If a trusted marketplace is already registered, enter /plugin install plugin-name@marketplace-name in a Claude Code session, or run claude plugin install plugin-name@marketplace-name in an external terminal. These names are placeholders and must be replaced with the real names in the author's documentation. If the marketplace is not registered, add the source according to plugin installation documentation first. For personal use, establish the installation scope so you do not accidentally commit project-level configuration for every collaborator.

If installing or updating from an external terminal while the original session remains open, run /reload-plugins in that session; otherwise loading occurs at the next start. Then open the Installed page in /plugin and inspect the target plugin and the terminal's mods active list. Perform one small action directly related to the Mod's purpose, such as viewing its expected panel or invoking a provided command. Confirm “loaded” and “works as intended” separately.

No panel? Rule out client differences first

The current official support table separates event execution from interface rendering. Interactive terminals and the Desktop app's Code page can display Mod panels and other interface elements, although some elements are terminal-only. The VS Code extension's chat panel can execute loaded Mod hooks but does not display their interface. Headless paths such as claude -p and Agent SDK also cannot use a panel as an acceptance criterion.

Desktop WSL sessions currently do not support plugins, so conclusions for ordinary Desktop Code sessions do not apply. If content is missing only in one client, first verify loading and behavior in a terminal that supports that interface, then report the client difference to the author. Do not begin by clearing all configuration or reinstalling every dependency.

For VS Code sign-in or IDE file-reference problems, also check the Claude Code extension version in Extensions. The panel uses the extension's bundled Claude Code; upgrading the terminal CLI does not update the extension. Update the extension and reload the window before rechecking. If it still shows signed out, use Sign in in the panel. If the sign-in interface does not appear, run Developer: Reload Window. There is no need to delete credentials or clear configuration first.

Building a first Mod with verifiable results

Official guidance offers two creation paths: describe the requirement in an interactive session and use the built-in plugin-authoring skill, or write a minimal plugin following Create a mod. Start with one outcome, such as showing the current Git branch, rather than simultaneously taking over tools, changing models, and drawing several windows. The documentation says Claude Code can load the relevant JS/TS files directly without first adding a Node.js bundling step.

When Claude writes the Mod, files are placed in that session's dev-mods directory and remain subject to file approval and hot-reload confirmation. After creation, still inspect /plugin and trigger the required behavior; generated files do not mean the Mod is loaded. To retain it across sessions, follow the documentation to save the plugin directory to a stable location, then load it with --plugin-dir or distribute it through a marketplace. Do not use a temporary session directory as a long-term deployment location.

Troubleshoot loading, events, then policy

If the plugin files are available, run claude plugin validate ./some-mod, replacing the path with the actual directory. This checks the manifest and static-analysis results without running the Mod. Inspect the hooks and calls lists to confirm that the intended event is recognized. Then check whether /plugin lists the target Mod; if needed, start a session with claude --debug and inspect loading errors.

If a plugin's Skill works but its Mod does not, inspect launch arguments, disableAllHooks, and organizational restrictions. Official guidance also provides a diagnostic: run claude plugin test in a directory without a Mod. no hooks module to load indicates module loading is not globally disabled under this check; turned off here means personal settings or organizational policy blocks it; turned off in this process means Anthropic has remotely disabled it, which local settings cannot reverse. This check does not rule out allowManagedModsOnly and cannot guarantee that any third-party Mod will load.

When reporting an issue, record Claude Code version, client, plugin version, minimal triggering steps, and error text. Remove unnecessary prompts, file contents, keys, and other information from logs first. If organizational policy explicitly forbids the source, have an administrator confirm the allowed installation scope. Disabling policy is not a general troubleshooting step.

How to disable Mods: the old environment variable no longer works

v2.1.287 and later ignore CLAUDE_CODE_ENABLE_FUNCTION_HOOKS, so setting it to 0 does not disable Mods. To stop one Mod you installed, disable or uninstall its plugin on the Installed page in /plugin. The terminal also supports claude plugin disable plugin-name@marketplace-name. Disabling the whole plugin affects its other components, so inspect what else it contains first.

To temporarily exclude user-installed Mods, launch a --safe-mode session, but this also disables other customizations. disableAllHooks in user settings stops the user's Mods, settings hooks, and custom status line, while managed content still runs. If an administrator sets it in managed settings, its scope includes managed Mods and settings hooks. Built-in Mods are unaffected by this switch. Choose targeted disabling, temporary diagnosis, and organization-wide policy separately; a broad switch is not a universal fix.