Install a Claude Mod

What you need

• Claude Code 2.1.287 or later. Check with claude --version and update if yours is older. There is nothing to switch on: mods load by default.
• A place that draws. A mod's panes and bands show in the terminal and in the Code tab of the Claude Desktop app. See where mods show up.
• For mods with boards and buttons, a terminal that reports the mouse.

1. Install the mod

Most mods publish their own repository as a plugin marketplace. Add it once, then install the mod from it. Each listing on this site shows the exact pair of commands, with a copy button.

claude plugin marketplace add <owner>/<repo>
claude plugin install <mod>@<marketplace>

The marketplace name after @ comes from the repository's .claude-plugin/marketplace.json. It is often the same as the mod, and sometimes not: secret-redactor@awesome-claude-code-function-hooksis one mod inside a marketplace of several. Inside a session, /plugin install <mod>@<marketplace>does the same as the second command.

2. Load it and check

Start claude. If a session was already open when you installed from the shell, run/reload-plugins in it. Then run /plugin: a dim line under the tabs names every mod the session loaded, such as 1 mod active · cc-arcade. Mods built into Claude Code are not counted there. If your mod is missing from that line, see troubleshooting.

After that, run the mod's own command, such as /arcade, or do whatever its listing says starts it.

Review a mod before you install it

A mod is not sandboxed. It runs inside Claude Code with your permissions: it can read and write your files, start programs, make network requests, read environment variables and settings, see every prompt and tool call, and call a model on your plan. Install mods only from authors you trust.

To see what a mod does without running it, clone its repository and validate the plugin directory:

git clone https://github.com/<owner>/<repo>
claude plugin validate ./<repo>

The hooks: line lists the events the mod handles. tool.call or prompt.submitthere means it sees, and can change, every tool call or every prompt. The calls: line lists what it asks Claude Code to do: $.fs.read and $.fs.write touch files, $.process.runstarts programs, $.http.fetch goes to the network, $.env.get and$.settings.read read values that can hold API keys, and $.model.complete spends your usage. If the plugin is in a subfolder of the repository, validate that folder.

Try a mod without installing it

Clone the repository and load it for one session. Edits to the hooks module reload when you save.

git clone https://github.com/<owner>/<repo>
claude --plugin-dir ./<repo>

Where mods show up

A mod's hooks run in every kind of session that loads it. What it draws appears only in some of them.

A mod that only guards tool calls or redacts output works wherever its hooks run. A mod that draws a game or a pane needs one of the first two rows. Each listing's Surfaces line names where the mod is meant to be used.

Update or remove

claude plugin marketplace update <marketplace>
claude plugin update <mod>@<marketplace>

claude plugin uninstall <mod>
claude plugin marketplace remove <marketplace>

You can also disable or uninstall a mod's plugin from the Installed tab in /plugin. After an update from the shell, run /reload-plugins in any open session.

Turn mods off

• One mod: disable or uninstall its plugin in the Installed tab of /plugin.
• Every installed mod, for one session: start with claude --safe-mode. It also turns off your other customizations.
• Every installed mod, in every session: set "disableAllHooks": true in ~/.claude/settings.json. Your settings hooks and custom status line stop too, and the plugins stay installed.

None of these stops the mods built into Claude Code, such as the /diff pane; most of those can be disabled one by one in /plugin. In an organization, an administrator can set allowManagedModsOnly in managed settings so that only the organization's own mods load.

If you turned mods on during early access

Before 2.1.287, mods needed the CLAUDE_CODE_ENABLE_FUNCTION_HOOKS variable. Remove it from theenv block of ~/.claude/settings.json and from your shell profile. Claude Code 2.1.287 and later ignores it, so setting it to 0 does not turn mods off: use one of the options above.

Troubleshooting

• Nothing the mod adds appears. Check claude --version says 2.1.287 or later, then look for the mod in the line /plugin shows. If it is not there, start claude --debug and look in the debug log for a line with the mod's name and not loaded:; the reason follows the colon.
• No mod loads at all. In your shell, run claude plugin test from a folder that holds no mod. no hooks module to load means mods can load. hooks modules are turned off here means disableAllHooks or your organization's policy is blocking them.
• No mod loads in a folder you opened for the first time. Start claude there and accept the trust prompt.
• Keys go to the prompt instead of the mod. The pane does not have keyboard focus. Click it, or press Ctrl+X then Tab.
• Nothing happens when you click. Your terminal does not report the mouse. The mod's slash commands still work.
• It works in the terminal and not in the Desktop app. The mod uses a place or an element that only the terminal draws.
• A mod broke after a Claude Code update. Events and methods can change between releases. Update the mod, and if it still fails, check its repository for an issue.

Anthropic's Troubleshoot a mod page lists every message Claude Code prints when it refuses or skips a mod.

Mods you already have

Some of Claude Code's own features are mods, such as /diff. /plugin lists them underBuilt-in in the Installed tab. One of them, "You should know", runs a side agent that shows a note above the prompt when it finds something you might miss. It is off by default; where it is available, turn it on with:

/plugin enable cc-plugin-you-should-know@builtin

Anthropic also shares three sample mods, token-weather, blast-radius andreplay-theater, in theclaude-code-playground repository. Try them with --plugin-dir as above.

For mod authors

Load your mod with claude --plugin-dir while you work: Claude Code writes TypeScript declarations for your exact build into .claude-plugin/types/ in the mod's folder. claude plugin validatechecks what Claude Code reads from the mod, and claude plugin test runs its tests without a session. Anthropic's documentation starts at the mods overview, the built-in mods are published as source in themods folderof the Claude Code repository, and the community discussion lives inanthropics/claude-code#91870.