Text of code.claude.com › docs › en › plugins › mods › create as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Create a mod - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. A mod is a Claude Code plugin with an entry file, called the hooks module: a JavaScript or TypeScript file whose functions Claude Code calls when events happen. To make one: Ask Claude to write it : describe what you want in a Claude Code session Write it yourself : follow the tutorial to learn how a mod’s code works.

You don’t need Node.js, a bundler, or a build step, because Claude Code loads .js and .ts files directly. If you haven’t decided whether a mod is the right tool, read the comparison on the overview first. Use Claude Code v2.1.287 or later. In your shell, run claude --version to check. To see whether mods can load for you, see Check whether mods can load . Ask Claude for a mod Describe the mod you want in an interactive Claude Code session, and Claude writes it.

Claude works from a built-in skill named plugin-authoring , which tells it where to write the mod, which events and methods your version has, and how the mod gets loaded. Claude can load the skill when you ask for a mod, or you can load it yourself by running /plugin-authoring at the Claude Code prompt. In auto and bypassPermissions permission modes , Claude Code can load the mod without asking you . To be asked first, start a new session in default or acceptEdits mode, or switch to either mode before you ask for the session’s first mod.

In some sessions , the mod can’t load. 1 Describe the mod Ask for the mod in your own words, for example make a mod that shows the current git branch above the prompt . Claude writes the mod in a directory of its own in the session’s mods folder, which is ~/.claude/dev-mods/ followed by the session’s ID. A mod’s full path looks like ~/.claude/dev-mods/3f2a9c1e-5b7d-4e8a-9c21-6d0f4b8a7e13/git-branch/ . In the default and acceptEdits permission modes , Claude Code asks you to approve each of the mod’s files before Claude creates it, because the mods folder is a protected path .

Approve each file as it comes up. 2 Approve the mod When Claude saves the first file, Claude Code asks whether to enable hot reloading for the session. Hot reloading runs the mods Claude writes in this session and picks up each later change. You don’t see this question in a session that loads new mods without asking or can’t load them . Choose one of these answers: Turn them on : the mods in the session’s mods folder load when the turn ends, and reload at the end of each turn that changes them.

Your answer lasts for the session, including after you resume it. Not now : nothing loads for now. The files stay where Claude wrote them, and the mods load the next time that session starts. To keep a mod from ever loading, delete its directory. 3 Check that the mod loaded Run /plugin at the Claude Code prompt and press Tab until the Installed tab is selected. It lists the mod, and you can turn it off there. 4 Try the mod Use what you asked for.

For the example prompt, the current branch name appears above the prompt box. If the mod doesn’t do what you wanted, tell Claude what to change. The mod reloads at the end of each turn that changes its files, so you can try the change as soon as Claude finishes. If a transcript line that starts with the mod’s name says the change didn’t load , paste that line into your next message when you ask Claude for a fix.

Claude doesn’t see the line unless you paste it. Use the mod in other sessions A mod Claude wrote loads only in the session that made it, and Claude Code deletes that session’s mods folder once it’s older than cleanupPeriodDays . To keep the mod, copy its directory out of the mods folder to a place of your own, such as ~/mods/git-branch . Then choose how to load it: In a session you start : in your shell, run claude --plugin-dir ~/mods/git-branch For other people : add it to a marketplace so they can install it Sessions that load a mod without asking Claude Code can enable hot reloading without asking in auto and bypassPermissions modes, and the mods load when the turn ends.

When you resume a session, interactively or with claude -p , the mods already in its mods folder can load without asking. To keep a mod from loading when you resume, delete its directory. Sessions where a mod Claude writes can’t load A mod Claude writes doesn’t load in these cases, and Claude Code doesn’t ask to load it: Nobody is there to approve : the session is in dontAsk mode , or it’s the claude -p run that writes the mod, in default or acceptEdits mode, which can’t show you the hot reloading question.

An interactive session where the workspace isn’t trusted : you haven’t accepted the trust prompt for the directory Mods are disabled : you started with --safe-mode or --bare , you set disableAllHooks , or your organization’s managed settings block it Write a mod yourself In this tutorial you build a mod named first-mod that counts the tool calls Claude makes, shows the count beside the spinner while Claude works, and adds a /tally command that prints it.

You then read the type declarations Claude Code writes beside your mod and run claude plugin validate . Together they show you the events and methods your version offers and what Claude Code reads from your code. This recording shows the finished mod. The spinner counts tool calls, /tally prints the count, and an edit to the code takes effect while the session runs: You write three files: first-mod/ ├── .claude-plugin/ │ └── plugin.json └── hooks/ ├── hooks.json └── register.js plugin.json : the plugin’s manifest hooks.json : points to your code file register.js : your code, called the hooks module 1 Create the plugin directory Create the two directories that hold the files: Bash or Zsh PowerShell mkdir -p first-mod/.claude-plugin first-mod/hooks New-Item - ItemType Directory - Force first - mod\.claude - plugin , first - mod\hooks 2 Write the manifest A mod is a plugin, and a mod needs a manifest .

This mod’s manifest has no special fields. Save this as first-mod/.claude-plugin/plugin.json : first-mod/.claude-plugin/plugin.json { "name" : "first-mod" , "version" : "0.1.0" , "description" : "Counts Claude's tool calls, shows the count beside the spinner, and adds a /tally command" , "author" : { "name" : "Your Name" } } 3 Tell Claude Code where your code is When Claude Code loads a plugin, it reads the plugin’s hooks/hooks.json .

The modules key in that file gives the path to your code, and having it is what makes the plugin a mod. List one path, relative to hooks.json . Here it points to register.js , which you write in the next step. Save this as first-mod/hooks/hooks.json : first-mod/hooks/hooks.json { "description" : "The first-mod hooks module" , "modules" : [ "./register.js" ] } 4 Write the code This file is the mod’s code, called the hooks module.

When the mod loads, Claude Code calls the register function the file exports and passes it a function named on . Each call to on registers an event handler, called a hook, for the event it names. Save this as first-mod/hooks/register.js : first-mod/hooks/register.js // The count, shared by the hooks below let calls = 0 // Claude Code calls this once when the mod loads export function register ( on ) { // Runs when the session starts, before your first prompt on ( 'session.start' , async ( $ , e , next ) => { // Add the /tally command await $ . command . register ({ name: 'tally' , description: 'Show how many tool calls Claude has made' , }) // Let the session start as usual return next ( e ) }) // Runs each time Claude is about to use a tool on ( 'tool.call' , async ( $ , e , next ) => { calls += 1 // Ask Claude Code to draw the interface again, so the new count shows $ . ui . invalidate ( 'ui.render' ) // Let the tool run as usual r

The rest of this page is on the live site.