How to install a Claude Code mod (and check it first)
Install a Claude Code mod from a marketplace in a few commands, see what it does before it runs, keep it updated, and turn it off or remove it. Terminal and desktop app.
- claude code mods
- install claude code plugin
- claude code
- how to
- developer tools
A Claude Code mod installs the same way as any other plugin: add the marketplace it lives in, then install it by name. The part most guides skip is the one in between, checking what the mod will do before it runs on your machine. This guide covers both, plus updates and how to turn a mod off.
I build Tokenbreak, a Claude Code mod, so I use it as the example. The steps are the same for any mod. Tokenbreak is independent and isn't affiliated with or endorsed by Anthropic; the commands below follow Anthropic's plugin install docs and mods docs.
1. Check your Claude Code version
Mods need Claude Code v2.1.287 or later in the terminal. The desktop app ships its own copy of Claude Code, and mods work there from v2.1.286.
claude --versionIn the desktop app, open a local session in the Code tab, type /status and read the Claude Code row. If you're behind, update first. Mods are on by default once you're on a new enough version; there's no flag to set.
2. Add the mod's marketplace
A marketplace is a catalog of plugins, usually a GitHub repository. Anthropic's official one is added for you. For anything else, add it once:
/plugin marketplace add steven-3/tokenbreakThat's the owner/repo form. A full git URL, a local path starting with ./, or the https:// address of a marketplace.json work too. When it works, Claude Code prints Successfully added marketplace: <name>.
3. Look before you install
A mod is code that runs with your permissions, and it isn't sandboxed. It can read and write your files, read your environment variables, see your prompts and tool calls, approve tool calls, and make network requests. Anthropic's docs say so plainly, and it's worth taking seriously.
You can see what a mod does without running it. Clone the repository and validate the plugin's directory:
git clone https://github.com/steven-3/tokenbreak
claude plugin validate ./tokenbreak/plugins/tokenbreakThe output's hooks: line lists every event the mod handles, and calls: lists what it asks Claude Code to do, such as http.fetch (network), fs.read (files) or process.run (programs). Read those two lines against what the mod says it does:
- A status line widget that lists
fs.writeorprocess.runshould make you ask why. - A mod that hooks
prompt.submitortool.callcan see or change what you send and what Claude runs. Some mods need that (a guard againstrm -rfdoes). A mod that only draws something doesn't. http.fetchmeans it talks to a server. Find out which one and what it sends.
Then read the README and, ideally, the hooks module itself. Most mods are small.
For Tokenbreak, the hooks are session.start, session.end, turn.start, turn.complete, ui.render (the band above the prompt and its own pane), ui.close and command.run for /ads. It never hooks prompts or tool calls. It does call http.fetch, to our server, and the tracking page shows every request it sends.
4. Install it
In a Claude Code session:
/plugin install tokenbreak@tokenbreakThe part before @ is the plugin's name and the part after is the marketplace's. In a session this opens the plugin's details first, so you can review what it adds, then asks for a scope:
- User: you, in every project on this machine. The usual choice for a mod.
- Project: everyone who works in this repository (written to
.claude/settings.json, which you commit). - Local: you, in this repository only.
From your shell instead, without starting a session:
claude plugin install tokenbreak@tokenbreakThat installs at user scope by default (--scope project or --scope local to change it). If a session is already open, run /reload-plugins in it to load the mod; otherwise it loads next time you start Claude Code.
In the desktop app's Code tab, click + next to the prompt box, then Plugins, then Add plugin, and pick it from the list.
5. Check it loaded
Run /plugin in the terminal. A dim line under the tabs says how many mods are active and names them, like 1 mod active · tokenbreak. If yours isn't named, Anthropic's troubleshooting page goes through the reasons a mod does nothing.
Some mods need a step of their own after install. Tokenbreak shows no ads until you sign in with /ads login, which prints a link to approve in your browser with GitHub.
6. Turn on updates
Claude Code updates plugins from Anthropic's official marketplaces automatically, but auto-update is off by default for every other marketplace. For a mod you want to keep current:
/plugin → Marketplaces → tokenbreak → Enable auto-updateTo update one plugin right now, open it on the Installed tab in /plugin and choose Update now, or from your shell:
claude plugin update tokenbreak@tokenbreakUpdates land on disk while you work; the running session keeps the old version until /reload-plugins or a restart. For Tokenbreak this matters more than usual: a version older than the current minimum stops earning and shows an update notice where the ads were.
7. Turn it off, or remove it
- Pause one mod: open
/plugin, go to Installed, select it and press Space to disable it. Same place to enable it again. - Every mod, for one session: start Claude Code with
--safe-mode. That also turns off your other customizations. - Every mod you installed, everywhere: set
"disableAllHooks": truein~/.claude/settings.json. Your settings hooks and custom status line stop too. - Remove it:
/plugin uninstall tokenbreak@tokenbreak, orclaude plugin uninstall tokenbreak@tokenbreakfrom your shell.
Many mods also have their own off switch. Tokenbreak's is /ads pause 1h or /ads pause today, and /ads resume to bring the ads back, so you don't have to uninstall it for a quiet afternoon.
Where mods work
Hooks run wherever Claude Code loads the plugin, but drawing is narrower. Panes and bands appear in a terminal (including an editor's built-in terminal and the JetBrains plugin) and in the desktop app's Code tab. They don't appear in the VS Code extension's chat panel, in claude -p, in the Agent SDK or in cloud sessions, and plugins aren't available in the desktop app's WSL sessions. So a mod like Tokenbreak, which only draws, does nothing in those places.
Try one
If you've never used a mod, Anthropic's samples are a good first install: token-weather draws a forecast of your context window above the prompt, and blast-radius holds risky shell commands like a force push until you confirm. They're in the claude-code-playground repository.
Or install Tokenbreak and get paid for the wait. It shows one small, labeled, human-reviewed ad while Claude works, and you keep half of what advertisers pay. The earn page has the numbers, which are small and stated honestly, and Claude Code mods, explained covers how mods work under the hood.