Want to access all premium content?
Become a paying subscriber to get access to all courses, guides like this, prompts and skills library, and $500+ worth of AI tools.
Mods let you change how Claude Code looks and works. You can add a context meter above the prompt, pause commands for review, or replay file edits. Describe what you want, and Claude writes the code.
We'll build Token Weather, install it for future sessions, and try three more ideas. You'll need Claude Code and a few minutes in Terminal.
Step 1: Update Claude Code. Get a version that supports mods.
Step 2: Pick one job. Choose something useful in every session.
Step 3: Build it in chat. Describe the mod and try it.
Step 4: Keep it installed. Load it in future sessions.
Step 5: Check before installing. Review its source and validate it.
Step 1: Update Claude Code
Open Terminal and check your version:
claude --versionYou need version 2.1.287 or later. If yours is older, run:
claude updateMods are enabled by default. Keep Claude Code current, since the mod interface can change between releases.
Step 2: Pick one job
Start with information you check often, a command you want reviewed, or a better way to read edits.
We'll build Token Weather: a line above the prompt showing how full your context window is. The context window holds the text Claude can use at once.
Mods respond to events such as prompts, tool calls, completed turns, and interface updates. They can handle an event in three ways:
Action | What it does | Example |
Observe | Reads it without changing it | Records a file edit |
Rewrite | Changes it before it continues | Adjusts a command |
Answer | Responds instead of passing it through | Refuses a tool call |
Token Weather observes events and updates its display. The command guard in Use case #1 can refuse a command.
Step 3: Build it in chat
Paste this prompt inside Claude Code:
Make a Claude Code mod called token-weather. Show my context usage on one line above the prompt.
Use a weather icon and label: under 25% Clear, 25 to 49% Cloudy, 50 to 74% Showers, 75 to 89% Storm, and 90% or higher Compact soon.
Include the percentage, tokens used out of the total window, and a small chart showing my last 12 turns. Update after every turn.
Allow hot reload when Claude asks. This lets it update the mod during the session without restarting.
The display should appear when Claude finishes its turn. To change it, ask directly: “Start Storm at 70%.”
If it doesn't appear, run claude --debug and look for an error saying a hook returned a tree that doesn't validate. Give Claude the error and ask it to fix the display.
Step 4: Keep it installed
A mod built in chat loads only in that session. Save it outside the session and install it as a plugin to keep using it.
Ask Claude:
Copy the token-weather mod into a folder called my-mods outside this session. Add the marketplace file it needs and install it for my user account so it loads in future sessions.
A local marketplace can be a folder with a .claude-plugin/marketplace.json file. Installation looks like this:
claude plugin marketplace add ./my-modsclaude plugin install token-weather@my-mods --scope userOpen a new session to check it. If Token Weather doesn't appear, run /reload-plugins, then restart Claude Code.
In the desktop app, use /plugin commands instead of claude plugin.
To publish your mod, put its folder and marketplace file in a GitHub repository. Other people can install it with these commands, using your repository and marketplace names:
/plugin marketplace add your-org/my-mods/plugin install token-weather@my-mods/reload-pluginsYou can also submit a plugin containing mods at claude.ai/directory/manage.
Step 5: Check before installing
Mods run with Claude Code's access. Before installing someone else's mod:
Read its repository and description.
Check who maintains it.
Run the validator on its folder.
claude plugin validate ./token-weatherThe validator lists the events the mod hooks into and the calls it makes. Token Weather should read session information and draw a display. If a similar mod runs commands or uses the network, check what that access is for.
For examples, browse mods/ in the anthropics/claude-code GitHub repository. You'll find implementations of features such as AGENTS.md support and the diff pane.
Use cases
Once Token Weather works, try these three mods. Build, test, and validate each one before installing it.
Use case #1: Review risky commands
Anthropic's Blast Radius sample pauses commands such as rm -rf and git reset --hard and shows what they could affect.
Try your own version:
Make a Claude Code mod called safe-stop. Before rm -rf, git reset --hard, git clean, or a force push runs, pause it and show what it would change.
Let me choose Proceed or Cancel. If I cancel, tell Claude why the command was refused.
Test it in a disposable folder. Command-text checks can miss aliases and scripts, so use permission rules for actions you need blocked.
Use case #2: Replay file edits
Anthropic's Replay Theater sample lets you review edits in the order they happened.
Make a Claude Code mod called replay. Record every file edit during a turn, including the text before and after.
Add a /replay command that lets me step through the edits one diff at a time.
Have Claude make a small change, then run /replay. Check that the replay includes every edit.
Use case #3: Get a completion ping
Get a notification when a longer turn finishes:
Make a Claude Code mod called done-ping. Show a notification when a turn lasting more than 60 seconds finishes.
Try a longer task and check when the notification arrives.
You could also build a rate-limit meter, a list of files Claude has read, or a reminder that adds team conventions to prompts. For tools you use often, try a guard for commands such as terraform apply or changes to a production kubectl context.
Confirmed limitations
Mods require Claude Code 2.1.287 or later. Their interface can change between releases, and their displays work in the terminal and desktop app.
Third-party mods run with Claude Code's access. Review their source before installing them.
Command guards can miss actions. Use permission rules when an action must be blocked.
Mods built during a session need to be installed as plugins to persist. These prompts request custom versions, so check that Claude's implementation does what you asked.
Closing
Start with Token Weather and take it through the whole process: describe it, test the display, and install it for your next session.
Then build a mod for something you check or repeat often. Use it for a few sessions and ask Claude to adjust anything that gets in your way.
See you in the next one :)