Claude Code mods

What it is

This page is about Claude Code itself, not game mods (that was Tuesday's MOD). A Claude Code mod is a plugin that, per Anthropic's docs, changes how Claude Code looks and behaves. It is made of JavaScript or TypeScript event handlers that Claude Code calls when something happens: a tool call, a prompt, a command or a part of the interface being drawn. A mod can draw a panel or a band above the prompt, redraw parts of the interface (the spinner, a tool row), step into a tool call, add a /command, and share data between its hooks. It cannot change the permission prompt. Mods arrived with Claude Code v2.1.287 on 2026-10-01 and are on by default.

Setup

1. Check your version. Mods need Claude Code 2.1.287 or later (update Claude Code if it is older). Nothing to turn on: mods are on by default.

   claude --versionCopy

2. The easy way: start Claude Code and describe the mod in plain words. Claude writes it with a built-in skill. Accept "Enable for this session" when it asks about hot reloading, and approve each file it saves (in default and acceptEdits modes, because ~/.claude is a protected path).

   make a mod that shows the current git branch above the promptCopy

3. Check that it loaded: run /plugin, open the Installed tab and look for a dim line like "1 mod active". To remove a mod, turn it off there.

4. Try one of Anthropic's sample mods. These live in a DevRel playground repo that says it is "not an official Anthropic product" and is provided as-is, with no support. Read the code and validate it first (validate lists what the mod does without running it), then load it for one session.

   git clone https://github.com/anthropics/claude-code-playground.gitCopy
   cd claude-code-playground/claude-code/modsCopy
   claude plugin validate ./token-weatherCopy
   claude --plugin-dir ./token-weatherCopy

5. To keep a sample mod installed instead of loading it for one session, add the sample marketplace from the mods folder, install it, then reload. (The blog's your-org/my-mods is a placeholder for your own marketplace if you publish a mod.)

   claude plugin marketplace add ./Copy
   claude plugin install token-weather@claude-code-playground-mods --scope userCopy
   /reload-pluginsCopy

Cheat sheet

• Overview, creating a mod and the sample mods repo.
• Security first. Anthropic's docs say: "Mods aren't sandboxed." A mod runs with your permissions: it can read and write your files, start processes, make network requests, read your environment variables and settings (an API key included), see every prompt and tool call, and approve a tool call before you are asked. Install mods only from authors and marketplaces you trust, and read the code first.
• Check before you install: claude plugin validate ./some-mod prints the events a mod handles and what it asks Claude Code to do, without running it.
• Token Weather (one of Anthropic's sample mods, per its README) shows a weather word for how full your context window is: Clear below 25%, Cloudy 25-49%, Showers 50-74%, Storm 75-89%, Compact soon at 90% and up. The numbers are real, not estimated. It updates once per turn, and the percentage is of the full window, not of the auto-compact point. Its README says it needs a terminal.
• Two more sample mods: Blast Radius holds a risky shell command (like a force delete) and shows what it would change; Replay Theater adds a /replay that steps through the last turn's file edits. The blog calls Blast Radius "a safety net, not a permission system."
• A mod is a plugin with a hooks/hooks.json whose modules entry points at a JavaScript or TypeScript file. Three small files: plugin.json, hooks.json and register.js.
• Turn mods off: disable the plugin in /plugin, run claude --safe-mode for one session (it also disables your other customizations), or set "disableAllHooks": true in ~/.claude/settings.json (this also turns off your settings hooks and status line).
• Where they draw: the terminal and the Code tab of the Desktop app. The docs say the VS Code extension and claude -p run mods but do not show their panels.
• The API can change between releases, so treat what Claude Code writes in .claude-plugin/types/ as the reference for your version.
• Anthropic's docs list no supported plans or operating systems, but say mods do not run in Desktop WSL sessions and that Anthropic can switch installed mods off remotely. Axo did not check further.
• Not verified by Axo: how the sample mods behave on your machine, since nothing was installed.

Axo's take

AXO

Haven't run it myself: this page comes from Anthropic's docs and blog. Try it if you wish Claude Code showed something it doesn't, like a context readout or a guard for risky commands: you describe it, Claude writes it. Read what a mod does before you install it, because the docs say mods aren't sandboxed.