How to Make a Claude Mod

• Claude Code v2.1.287 or later. Check with claude --version
• Or the Claude desktop app’s Code tab, from v2.1.286
• A clear idea for one small change
• Basic JavaScript helps, but is not required

A mod is a plugin with code that runs inside Claude Code.

• Start a Claude Code session in a practice folder
• Describe the mod you want
• Allow hot reloading when Claude asks
• The mod appears when Claude’s turn ends
• Ask for changes, and each one reloads in place
• Copy the folder somewhere safe to keep it

Make a mod that shows how many tool calls Claude has made this turn beside the spinner.

A small mod has three files:

.claude-plugin/plugin.json

The plugin manifest: name, version, description, and author

hooks/hooks.json

Points to your code file with a modules list

hooks/register.js

Your code, which tells Claude Code which events to run on

hooks.json: { "modules": ["./register.js"] }

Your file exports register(on). Each hook has the same shape:

export function register(on) { on("tool.call", async ($, e, next) => { // $ is the mods API, e is the event, next continues as normal return next(e); }); }

Observe

Call next(e), look at the result, and return it

Rewrite

Call next with a changed event

Answer

Return your own result without calling next, such as a deny

tool.call

Before Claude uses a tool

turn.complete

When Claude finishes a turn

session.start

When a session starts

ui.render

When Claude Code draws a part of the screen, such as the spinner or the band above the prompt

See the mods reference in Claude Code’s docs for the full list.

Use ui.render with a component, such as AbovePrompt or Spinner, and return elements such as Box and Text. You can also add panes, buttons, and text fields. Return next(e) when you have nothing to draw.

Variables in your file reset every time the mod reloads. Save data you want to keep with the mods state API, and declare its shape in a types file. Reading state while drawing makes the interface update when the state changes.

• Start a session with claude --plugin-dir ./your-mod
• Save a change, and the mod reloads without a restart
• Run claude plugin validate ./your-mod to check it and list its hooks
• Run claude plugin test ./your-mod to run your test files
• Run /plugin to see which mods are active

• Run claude plugin validate to catch contract errors
• Start with claude --debug and check the log
• Remember that each reload runs register and session start again
• Restart Claude Code if a mod does not appear after /reload-plugins

• Put the mod in a Git repository with a .claude-plugin/marketplace.json file
• Others add it with /plugin marketplace add your-org/your-repo
• Then install it with /plugin install mod-name@marketplace-name
• Or submit it to the Claude directory

• Mods run with your permissions and are not sandboxed
• Never put API keys or passwords in the code
• Ask only for the access your mod needs
• Do not auto-approve tool calls unless you are sure
• Write a short README that explains what it does

Make a Claude Code mod that [what it does]. It should run on [event] and show [what to draw, if anything] in [where]. Keep it small, store anything that must persist in mod state, never auto-approve tool calls, and add a README and one test. Then load it with hot reload so I can try it.