Make Your First Claude Code Mod

Mods let you change how Claude Code looks and behaves, and you don't have to write the code. You describe the feature, Claude Code builds it, and you see it on screen in the same session.

What this helps you do

Add the feature you wish Claude Code had. Start with a mod that only shows something on screen, such as your current project and a reminder to run tests before you commit. If you can see it, you know it works.

Once that works, make a second mod that reacts to what Claude does, such as stepping in when Claude is about to run a command.

A mod is a small plugin with code that runs inside Claude Code. Claude Code calls it when something happens, like a tool call, a prompt you send, or part of the screen being drawn. The mod can watch that moment, change it, or take it over. Anthropic introduced mods on October 1, 2026, and the official mods overview covers everything they can do.

Before you start

• Claude Code v2.1.287 or later in the terminal. In your shell, run claude --version to check. If it's older, update Claude Code.
• Using the Code tab of the Claude Desktop app instead? Mods work there from v2.1.286. Type /status in a local session and read the Claude Code row.
• A project folder you trust. A mod Claude writes only loads in a folder where you've accepted the trust prompt.
• A normal interactive session. Mods Claude writes need you there to approve them, so they don't load in claude -p runs.
• On a Team or Enterprise plan, your admin can limit which mods load. If nothing loads, ask them.

Terms to know

• Mod: a plugin with JavaScript or TypeScript code that changes how Claude Code behaves or what it shows.
• Plugin: a package that adds features to Claude Code. A mod is one kind of plugin.
• Band above the prompt: a strip of space just above where you type. Mods can draw text there.
• Hot reloading: Claude Code loads the mod as soon as Claude finishes writing it, and reloads it after every change, without restarting.
• Tool call: each action Claude takes, such as reading a file or running a terminal command.
• Display mod: a mod that only shows something. Reactive mod: a mod that responds when something happens.

Step-by-step

1. Open your terminal, go to your project folder, and type claude to start a session.
2. Paste the first prompt from the next section and press Enter. Claude loads its built-in plugin-authoring skill, which tells it how to write a mod for your exact version. You can also run /plugin-authoring yourself first.
3. Approve the files. In the default permission mode, Claude Code asks before it creates each file, because mods live in a protected folder. Approve each one as it comes up.
4. When Claude saves the first file, Claude Code asks whether to turn on hot reloading. Choose Enable for this session.
5. Wait for Claude's turn to end. The mod loads, and your project name and test reminder appear just above the prompt.
6. Confirm it loaded. Run /plugin and press Tab until the Installed tab is selected. Your mod is listed there, and you can turn it off from that screen.
7. Ask for changes in plain words, such as "make the reminder yellow" or "only show it when I have uncommitted changes." The mod reloads when Claude finishes each change.
8. Keep it for future sessions. A mod Claude writes lives in a temporary folder for that session only, at ~/.claude/dev-mods/ followed by the session ID. Ask Claude to copy the mod folder to ~/mods/. Then start future sessions with claude --plugin-dir ~/mods/[MOD-FOLDER-NAME].
9. Once the display mod works, try the reactive prompt below.

Copy this

Paste the first prompt into a new Claude Code session. Replace [BRACKETED] parts with your own details. Use the second prompt once your first mod works.

FIRST MOD (shows something on screen)
Build me a Claude Code mod called [project-reminder]. In the band above the prompt, show the current project folder name and the reminder: "Run tests before you commit." Keep it to one line. Explain what each file does before you create it, then load it in this session so I can see it.

SECOND MOD (reacts to what Claude does)
Build me a Claude Code mod called [commit-guard]. When Claude is about to run a git commit command, pause and ask me "Did the tests pass?" with Yes and No options. Yes lets the commit run. No cancels it and tells Claude to run [TEST COMMAND, e.g. npm test] first. Explain what it will do before you create the files.

KEEP IT
Copy the mod you just built into ~/mods/ and give me the exact command to load it in future sessions.

Things to know

• Start with something you can see. A display mod either shows up above the prompt or it doesn't, so you know right away whether it works. A reactive mod only shows itself when its moment happens.
• Mods run with your permissions. A mod can read and write your files, run programs, and make network requests. Mods are not sandboxed. Build your own or install them only from people you trust.
• Check a mod before you install someone else's. In your shell, run claude plugin validate ./[MOD-FOLDER]. The hooks: and calls: lines list what it listens for and what it asks Claude Code to do.
• Where mods work: the Claude Code terminal app, the Code tab of the Desktop app, and the VS Code extension (version 2.1.299 or later). Mods don't load in WSL sessions inside the Desktop app.
• Turn mods off anytime. Disable one in /plugin, or start Claude Code with --safe-mode to skip every installed mod for one session.
• Some built-in features are mods. The /diff pane is one. Run /plugin and look under Built-in to see them.
• Want ideas? Anthropic shares sample mods in its claude-code-playground repository, including one that shows how full your context window is and one that holds risky commands for your approval.
• New to plugins in general? 17 Claude Code plugins and skills to review is a good next read.

If something goes wrong

• Nothing appears above the prompt: run claude --version. If it's older than 2.1.287, update Claude Code and try again.
• The mod isn't in /plugin: you may have chosen Not now for hot reloading. Restart or resume that same session to load it, or ask Claude to load it again.
• A transcript line says the mod's change didn't load: copy that line and paste it into your next message. Claude doesn't see it unless you paste it.
• It worked yesterday and is gone today: mods Claude writes only load in the session that made them. Copy the folder out and use claude --plugin-dir (step 8).
• Still nothing: check whether you started with --safe-mode or --bare, or whether your organization blocks user mods. The mods troubleshooting page lists every reason a mod can stay silent.

Final check

Your reminder shows above the prompt, your mod appears in the Installed tab of /plugin, and it loads again when you start a new session with claude --plugin-dir ~/mods/[MOD-FOLDER-NAME]. If all three are true, your first mod works.