A SMALL UPGRADE, A GOOD START
How to install Claude Code mods.
Install a Claude Code mod from its author’s marketplace or load an official sample for one session. Start with the version check below; if an installed mod does nothing, use the troubleshooting checklist.
01 / Check your version
In the terminal, use Claude Code 2.1.287 or later and check with the shell command below. Claude Desktop bundles its own copy: in a local Code-tab session, run /status and check the Claude Code row for 2.1.286 or later. Update the app if that bundled version is older. Mods are enabled by default; current versions do not need the early-access function-hooks flag.
claude --versionDo I still need the function-hooks environment variable?
No on Claude Code 2.1.287 or later. The official docs say these versions ignore CLAUDE_CODE_ENABLE_FUNCTION_HOOKS, including a value of 0. Update an older installation instead of copying an early-access flag. Use the documented settings or session flags if you want to turn mods off.
02 / Choose a mod with public source
Open the author’s repository and read its requirements. Our collection distinguishes mods with published source and setup from demonstrations without confirmed install instructions.
Are Claude Code mods safe to install? Check what they can reach
A small UI feature can still have broad access. A mod runs inside Claude Code with your user permissions: files, environment variables and settings can be accessible, including secrets kept there. Choose a creator you trust and inspect the actual plugin directory before loading it.
Read the validator’s hooks: and calls: lines
Obtain the author’s files without loading the plugin, then run claude plugin validate on its plugin directory, as in the Token Weather example below. The hooks: line names events it receives; the calls: line names mods API methods it calls. For example:
$.fs.read / $.fs.write— File reads and writes within your user account’s reach.$.process.run / $.process.spawn— Programs started as your user.$.http.fetch— Network requests; compare their purpose with the feature you wanted.$.model.complete— Model calls that use your plan or API key.
The admin reference also covers secret access and prompt changes. Passing validation is not a security verdict. Our recommendation: compare the report with the source and README, and record the revision you reviewed so you can examine changes before an update.
Does Claude Code’s Bash sandbox isolate a mod?
No. The official overview says mods are not sandboxed, and processes they start run outside the Bash sandbox. A separate experiment folder alone does not restrict their file access. Do not infer isolation from a harmless-looking preview or a “source reviewed” label.
How can I stop a mod?
Disable or uninstall its plugin in /plugin → Installed. For one session without installed mods, start claude --safe-mode; this also disables other customizations. Built-in mods are an exception and need their own disable control. Use the You Should Know guide below for that feature.
Official mod trust and sandbox boundaries · Official capability-report reference
03 / Add its marketplace and install
Follow the author’s exact marketplace and plugin names. For example, Claude Ambient publishes these shell commands:
claude plugin marketplace add barisdemirhan/claude-ambient
claude plugin install ambient@claude-ambientIts README then asks you to restart Claude Code and run /ambient. Read the full author instructions ↗
For installs made from a shell during an open session, the official docs describe /reload-plugins to load the new plugin.
04 / Or try an official sample locally
Token Weather is a small example that displays context usage. Clone the playground, inspect the plugin, and load it for one session:
git clone https://github.com/anthropics/claude-code-playground.git
cd claude-code-playground/claude-code/mods
claude plugin validate ./token-weather
claude --plugin-dir ./token-weather05 / Confirm the mod is active
In your terminal session, open /plugin and look for the dim “mods active” line below the tabs. It lists loaded installed mods; built-in mods are omitted. A plugin appearing in the Installed tab alone does not prove that its mod code loaded.
/reload-plugins
/pluginWhere will the interface appear?
Mods can draw UI in the terminal, Claude Desktop’s Code tab, and the VS Code extension. The VS Code chat panel needs extension 2.1.299+ when the session fetches feature flags, or 2.1.304+ when it does not, including Bedrock, Vertex, Foundry, LLM-gateway and telemetry-disabled sessions. Supported elements vary. Headless sessions do not display mod UI. Check each mod’s README for narrower requirements.
Claude Code mod not working? Check the symptom first
Separate a loading problem from a display problem. A mod can be active while its UI is unavailable on the surface you are using.
Installed from the shell, but absent in the open session
Run /reload-plugins inside that session, then check /plugin again. If the author’s README also requires a command or configuration, complete those steps. Installing the package alone may not open its interface.
Active mod, but no pane in VS Code
Check the VS Code extension version: 2.1.299+ for sessions that fetch feature flags; 2.1.304+ for sessions that do not, such as Bedrock, Vertex, Foundry, gateways or telemetry-disabled sessions. Update the extension instead of changing provider or telemetry settings. Check the official render-site and element tables and the mod’s README: a supported host does not guarantee that every mod draws there. Try the integrated terminal to isolate the surface. Headless runs do not draw UI; Desktop WSL sessions do not support plugins.
No installed mods load
Check the version and whether this session started with --safe-mode. Your settings or organization policy can also block mod modules while other parts of a plugin remain available. Read the refusal reason; ask your administrator about managed restrictions rather than changing policy to bypass them.
The module or a hook fails silently
Start a diagnostic session with claude --debug and search the log for the mod’s name. A “not loaded” line points to loading refusal; “hook skipped” points to a handler failure. In 2.1.304, a transcript line also names the event and earlier plugin when that plugin skips your hook. Follow the stated reason before changing code or configuration.
Your local code edits have no effect
An installed plugin runs from a cached version. For development, point --plugin-dir at your working copy, which reloads on local edits. If the line says “reload failed, the previous version stays loaded”, fix the reported error: the last working version remains active, so unchanged behavior does not prove the edit loaded. The 2.1.304 release fixes failed reloads removing that previous version’s tools and commands. Editing another checkout does not update the installed copy.
Check local files without running the mod
Run claude plugin validate against the actual plugin directory, as shown in the sample above. It can detect manifest or module problems and list hooks and API calls without executing mod code. Passing validation does not establish runtime compatibility or safety.
Official mod troubleshooting reference ↗Follow a small example
Claude Code 2.1.300: virtualText, prompt.change, and mod upgrade notes →
You Should Know: enable, disable, and check availability →
Mods vs plugins, skills, hooks, and MCP: which should you use? →
For a context display, read Token Weather’s listing. For an ambient scene, read Claude Ambient’s listing and its activation command. These use different UI behavior, so compare the author’s requirements with the symptom you see.
What does “source reviewed” mean?
We check original sources and documented setup, but do not execute every mod. Mods run with your machine permissions. Inspect code before installing; claude plugin validate lists hooks and API calls without running the mod code.
Sources and review scope
This checklist summarizes documented behavior, rather than results from installing these mods. The original documentation and each author’s README remain the source of truth.
2.1.304 release notes: VS Code display and mod reload fixes
Display and reload diagnostics reviewed October 20, 2026 against official 2.1.304 release notes and documentation; pre-install guidance reviewed October 10. Author commands remain linked examples; we have not executed the collected mods.