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.

INSTALL / TERMINAL
claude --version

Do 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:

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:

INSTALL / TERMINAL
claude plugin marketplace add barisdemirhan/claude-ambient
claude plugin install ambient@claude-ambient

Its 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:

INSTALL / TERMINAL
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-weather

Read Token Weather’s setup and limitations ↗

05 / 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.

CLAUDE CODE / INTERACTIVE SESSION
/reload-plugins
/plugin

Where 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.

Token Weather · Claude Ambient

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.

Official Mods documentation ↗

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.