Mods in Claude Code

Home → Knowledgebase → Mods in Claude Code

Introduction

In October 2026, Anthropic added a new feature to Claude Code: mods. You can add a mod to the list of CLAUDE.md, rules, skills, agents and hooks. In my earlier article on this topic (NL|EN), I already announced this follow-up, because mods were released just after I had finished that article.

What is a mod?

A mod is a plugin for Claude Code. It is most similar to a hook. The difference is that a hook runs as a separate script outside Claude Code, while a mod runs as code inside Claude Code itself. Because of this, a mod can do much more than a hook.

Not only can you hook into more events than with hooks, you can also do very different things. Think, for example, of your own pane or bar in Claude Code with the information you want to see, of changing parts of the Claude Code interface itself, or of running a command without Claude needing an extra turn for it. And that is far from everything.

Technically, a mod is an ordinary plugin with JavaScript or TypeScript code. A mod runs in the same environment you work in yourself, so not in a sandbox. It can access everything your user account can access, and it can also use your connectors. As a result, you can also use your system’s environment variables, for example.

In this article I give two examples of a mod. The first is a mod that shows a pane with the details of the Jira story I am working on, based on the name of the branch. The second is a bar above the prompt input with a button to start a build. The first mainly shows the visual possibilities. The second shows how you can run a process outside the session and still get the result back in your session.

What I am not going to do is explain in detail how a mod is put together. Just like skills, agents and hooks, I simply build a mod with Claude Code itself. If you do want to be able to do it by hand, read the overview and the reference guide in the Claude Code documentation.

The table below shows how the different options, from CLAUDE.md to hooks, compare to a mod.

Building the first mod

For the mod that shows the details of the Jira story, I simply gave Claude Code the following instruction:

Create a mod to show a window in Claude Code. In this window I’d like to see the JIRA story title and description I’m working on. Get the issue key from the branch name.

Whether Claude asks some extra questions depends a bit on the skills you have installed and on your personal instructions. Without further instructions, however, Claude will build this mod in the scratchpad of your session. Make sure that at some point you have this mod placed in the default folder of your profile, or in a marketplace if you use one.

As you are probably used to, Claude Code will make choices itself while coding the mod, or present choices to you. In this case, the question soon came up: how do I get my credentials for Jira?

The simplest option is to handle this through the configuration of the mod. You can specify which fields you want in it, and also whether they contain sensitive data. In that case, these values are kept in secure storage. I chose to work with environment variables myself. In any case, weigh the risks of this carefully.

If you handle it through the configuration, you can look up the mod via /plugin and open the settings via the gear icon. You will then see the fields you have defined.

My first version of the mod looked as shown below. The description contains Jira’s own formatting markup.

Next, I asked Claude to format the description and to add some more details. This is the end result:

You can also see that you can have the mod carry out actions. There is a Refresh button that can fetch the data again. Claude had automatically built in that the mod checks every 30 seconds which branch you are working on. If it has stayed the same, the data is not refreshed. However, you may have changed something in Jira in the meantime and want to see that here as well. You can then do that with the Refresh button.

If you then look at the folder with the files of the mod, you will see the following:

At its core, the mod is a Claude Code plugin with a description in the plugin.json. This file also defines the configuration fields, each with a type, title and description. Here you can also define whether a field is sensitive or not.

The register.tsx is the core file of the mod. The engine loads this file via the hooks.json. The wiki.tsx is a helper module that converts the text formatted in Jira into the display in the pane.

The mod with a direct action

The first mod was mainly about the visual display. The second mod can carry out an action at any moment, without the session having to wait for it and without anything being sent to Claude. This mod can start a build via a button and show the result, without processing it in the session straight away.

The approach is the same: in a prompt, I simply asked to build this mod for me.

Create a new mod “build-app” with a button to build the software with a predefined script (via config). It should be possible to config a Powershell script or a command line batch file. When the build button is pressed, the build should be executed without a turn. The build result will show the errors, hints and warnings. When the build has finished, the result is shown in the session as a transcript, but not yet sent to the prompt. The user can choose what to do with it.

Without any further questions, this resulted in a bar above the prompt input with a simple Build button.

In the terminal it looks like this:

Tip: it is a good idea to build the mod with the command-line interface (CLI) of Claude Code. If something goes wrong with the mod, for example when loading it, you will see this in the CLI, but not always in Visual Studio Code.

At first, the settings for the build script were placed centrally in the configuration. In many situations, however, you have separate build scripts per repo or project. That is why I asked to change the mod so that you can set a project-specific build script through a configuration file in the folder where Claude runs.

I do not want to copy and paste these settings into a settings screen myself. I prefer to do it by asking Claude. The mod therefore now responds to a question about configuring the build-app. At that moment, an instruction is added to your prompt, so that Claude arranges this for you. In the session you are then asked which build script should be used, and Claude then creates the configuration file.

After setting it up, you can start the build with the button or with /build-app. You then see the progress of the build in the bar. While the build is running, you can simply carry on with what you were doing.

When the build has finished, the result is shown, together with the options to put the result in your prompt input (Put in prompt) or to ignore it (Dismiss). If you choose Put in prompt, the entire result of the build (so not just that one line) is put in your prompt input.

The technology behind it

To give some insight into what a mod can do, and to show that it really goes deeper than a hook, I have still worked out some technical details below.

• In the mod, the command.run event makes sure that /build-app is executed and, in this case, actually starts the build.
• The prompt.submit event is used to check whether the user is asking to set up the build-app. If so, the prompt is extended with the instruction to ask for the build script and with the instruction on how the settings file should be written.
• The build script is run via the engine function $.process.spawn, with PowerShell or cmd.exe depending on the type.
• Various other engine functions of Claude Code are used to support this process, such as $.session.root and $.clock.now. For drawing the UI there are functions such as $.ui.render, $.ui.open and $.ui.toast.
• The first mod, with the Jira stories, also uses $.http.fetch and a timer via $.clock.every.

The above once again makes the big difference with skills, hooks and agents clear. It shows that a mod embeds itself in Claude Code itself and can use the functions of the engine.

Added value for organisations

As a developer, you no doubt already have several ideas for a mod of your own. However, mods can also add value across an organisation. At organisation level, you can publish mods and make sure that these mods are loaded for everyone by default. The possibilities do depend somewhat on your subscription and on how you manage Claude Code centrally.

Once you have set that up, you can think of mods that check things in the area of security or privacy, of support for secure coding, or of blocking certain git actions, such as a force push or a push to main. Audit logging is also one of the possibilities.

Get started!

The main aim of this article is to introduce you to mods in Claude Code. I hope it has inspired you to start working with them yourself. Perhaps you can now finally change the things in Claude Code that you have wanted to change or add for so long. Good luck!