ExplainedClaude CodeClaude Code modsAnthropicpluginsAI agentsagent security

Claude Code mods explained: build your first mod, and what it can reach

A Claude Code mod is a small piece of JavaScript or TypeScript that runs inside Claude Code, Anthropic's AI coding tool, and changes how it looks and what it does. It comes inside a plugin, an add-on package. I built one on my Mac, ran it, and read what a mod is allowed to touch.

Roni Das

19 min read

Published5 October 2026, 17:15 UTC

Three rings drawn on grid paper. In the centre, Claude Code. Around it, a ring labelled mods. Around that, a dashed ring labelled your machine. On the left, what a mod changes: draws panes and bands, rewrites a tool call, answers without the tool. On the right, what it reaches: your files and programs, the network and your keys, every prompt you send. — A mod sits between Claude Code and your machine

In short

A mod is a plugin with code inside. Claude Code runs that code when something happens: Claude asks to use a tool, you send a message, or part of the screen is drawn.
Mods arrived in Claude Code 2.1.287 on 1 October 2026 and are on by default. You install one by typing the command /plugin inside Claude Code, like any other plugin.
I wrote a 3-file mod that shows the current git branch above the box where you type, and adds a /where command. Nothing had to be compiled first, and the mod never asked the AI model anything.
A mod is not sandboxed: nothing walls it off from the rest of your computer. It can read and write your files, start programs, use the network, read your passwords and API keys, and see every message you send.
Before you install one, run claude plugin validate on its folder. One line of the output contains calls:, and it lists what the mod can reach, without running it.

Launched: 1 October 2026, Claude Code 2.1.287
Written in: JavaScript or TypeScript
Ships as: a plugin, installed with /plugin
Sandboxed: No, it runs as you

This page is the free part.

The course goes deeper on AI agents

₹999 in India$49 everywhere elseonce, for the whole course

The AI Engineering course covers AI agents across a run of lessons, not one page. These 4 alone are about 310 minutes of step-by-step reading, every one with code you run in the browser, all with a quiz.

Tool and Sandbox Security: Locking Down What an Agent Can Do
How to secure agent tools and code sandboxes: least privilege, microVM isolation, default-deny egress, argument validation, and resource limits.
75 min · diagrams · code you run · quiz
AI Supply Chain Security: What You Import Runs as You
Your LLM app loads weights, datasets, packages, and MCP servers you never wrote. Pin, hash, scan, sign, and verify provenance so an import cannot own you.
90 min · diagrams · code you run · quiz
Data Exfiltration and Egress Control in LLM Systems
A steered model needs no click to leak data, it writes a line of markdown. The exfiltration channels, and the egress controls that close every exit.
85 min · diagrams · code you run · quiz
Prompt Injection and the Lethal Trifecta: Why LLM Agents Leak Data
Prompt injection is the top LLM security risk. Learn why it has no clean fix, how indirect injection works, and what the lethal trifecta is.
60 min · diagrams · code you run · quizfree to read now

all part of

AI Engineering

204 lessons · about 211 hours · 10 free to read

₹999in India, by UPI

$49everywhere else, by PayPal

Get the AI Engineering course Read 10 lessons free first

You own this course

Continue with Tool and Sandbox Security: Locking Down What an Agent Can Do

pay once,
yours for life

What a Claude Code mod is

“A mod can rewrite a prompt, add new UI, replace a built-in feature, or add entirely new functionality.”

Anthropic, Customize Claude Code with mods, 1 October 2026

Claude Code is an AI tool from Anthropic that writes code for you. You describe a task. Claude, the AI model, then reads your files, runs commands and changes code until the task is done. A plugin is an add-on package for Claude Code, such as a new command or a connection to another service.

A mod is a plugin with code inside. The code is a set of small functions, written in JavaScript or TypeScript. Claude Code calls one of them each time a certain thing happens, which the docs call an event. Examples of events: Claude is about to use a tool, you send a prompt, or Claude Code is about to draw the spinner.

Each of these functions is called a hook. A hook can watch the event, change it, or handle it completely, so Claude Code's usual behaviour never runs. Why would you want that? To show something useful on screen, or to stop Claude from doing something you do not like. Claude Code already had a different thing also called hooks, now named settings hooks: a shell command, web request or prompt that you set in a settings file, which runs outside Claude Code. A mod's hooks run inside it.

Anthropic launched mods on 1 October 2026. The changelog (the list of changes in each version) for version 2.1.287 says "Added Claude Mods: plugins may now modify deeper behavior", and GitHub lists that release at 18:00 UTC (world standard time) that day. The docs say mods need 2.1.287 or later and are on by default. The latest version when I wrote this was 2.1.289.

What a mod can do

Anthropic's docs list five kinds of things a mod can do. First, it can draw its own parts of the screen. One is a pane, a box beside the conversation. Another is a band, a strip just above the box where you type. Both can hold buttons and text fields. Second, a mod can redraw parts Claude Code draws itself, such as the row for a tool call or the spinner, the small moving sign that shows Claude is working.

Third, a mod can step in when Claude asks to use a tool (a tool call) or when Claude Code sends a message to the AI model (a request). The mod can hold the tool call while it asks you a question, answer it without running the tool, or send one request to a different model. Fourth, a mod can add a /command that runs your code at once, without asking Claude anything. Fifth, its hooks can share data, so one hook can count something and another can show the count.

When two mods handle the same event, they run in the order they loaded. The launch post puts it this way: "The first mod to load sees the event first and the result last." So mods from different authors can stack.

Every hook receives a function called next. Calling next passes the event on, to the next mod and finally to Claude Code. So inside a hook, a mod makes one of three moves. Observe: note the event and call next with it unchanged. Rewrite: change a copy of the event and call next with that. Answer: return its own result and never call next. The figure shows both ideas.

Some of Claude Code's own features are now mods. The /diff pane, which shows your code changes, is one. Another loads AGENTS.md, a file of project notes for AI tools. A third, called You should know, runs a second small AI helper that shows a note above the prompt when it spots something you might miss. That one is off by default.

Two nested frames labelled mod A, loaded first, and mod B, loaded second, around a core labelled Claude Code's own behaviour. An arrow labelled event in: tool.call crosses mod A at point 1, mod B at point 2, and reaches the core. An arrow labelled result out leaves the core and crosses mod B at point 3, then mod A at point 4. Below, three moves: observe, return next(e); rewrite, return next(copy); answer, return { text }. — An event goes in through every mod, and the result comes back out the same way

Build your first mod: the plan

I wanted a mod small enough to read in one minute and harmless enough to run anywhere. It shows the current git branch in the band above the prompt, and adds a /where command that reads the branch again. Here are the steps, in the order I did them.

Check your version
Mods need Claude Code 2.1.287 or later. My everyday install was older, so I used 2.1.289. I installed it with npm, the tool that installs JavaScript programs, into a separate folder, so nothing else on the Mac changed.
Make three files
A mod is a folder with .claude-plugin/plugin.json (the plugin's name and version), hooks/hooks.json (which points at your code), and the code itself, here hooks/register.js. The modules key in hooks.json is what makes a plugin a mod.
Write the hooks
register.js shares one function, called register, with Claude Code. Claude Code calls register once, when the mod loads. It gives register one input: a function named on. You call on once for each hook you want. My mod uses three hooks: session.start, command.run and ui.render.
Check it without running it
claude plugin validate reads the folder and prints which events the mod handles and which mods API calls it makes. An API is a set of functions a program can call. The mods API is the object called $ in the code, and it is the only way a mod can reach files, programs or the network.
Load it for one session
Starting Claude Code with the --plugin-dir option, as in claude --plugin-dir ./branch-band, loads the folder for one session without installing it. Nothing needs to be compiled: Claude Code loads .js and .ts files as they are.
Keep it, or share it
To keep a mod for every session, put it in a marketplace (a list of plugins, often a git repository) and install it with /plugin install name@marketplace, where name is the mod's name and marketplace is the list's name. I did not install mine; --plugin-dir was enough for this test.

The three files

This is the whole mod. When the session starts, the session.start hook reads the branch once and adds /where. When you type /where, the command.run hook answers it itself: it never calls next, so Claude is never asked. Each time the band is drawn, the ui.render hook draws one line of text in the band above the prompt. It also calls next to get whatever mods loaded after it want to draw there, and keeps that below its own line. My first version skipped that step, which would have hidden every later mod's band.

To read the branch, the mod runs a git command that prints the current branch name, git rev-parse --abbrev-ref HEAD, through $.process.run. That call starts a real program on your machine, as you. It is harmless here, and it is also the exact kind of power the security section below is about.

My first version named the command /branch. Claude Code refused to add it, and printed a line that ends with "/branch" refused: it is the built-in /branch. Claude Code already has a /branch command, and a mod cannot add a command with the same name that way. So I renamed mine /where.

# branch-band/.claude-plugin/plugin.json
{
  "name": "branch-band",
  "version": "0.1.0",
  "description": "Shows the current git branch in the band above the prompt, and adds a /where command",
  "author": { "name": "Roni Das" }
}

# branch-band/hooks/hooks.json
{
  "description": "The branch-band hooks module",
  "modules": ["./register.js"]
}

# branch-band/hooks/register.js
// The branch name, shared by the hooks below
let branch = '(not a git repo)'

// Ask git for the branch. $.process.run uses no shell, and resolves with the exit code.
async function readBranch($) {
  try {
    const r = await $.process.run(['git', 'rev-parse', '--abbrev-ref', 'HEAD'])
    branch = r.exitCode === 0 ? r.stdout.trim() : '(not a git repo)'
  } catch {
    branch = '(git did not run)'
  }
}

export function register(on) {
  // When the session starts: read the branch once and add the /where command
  on('session.start', async ($, e, next) => {
    await readBranch($)
    await $.command.register({ name: 'where', description: 'Read the git branch again' })
    return next(e)
  })

  // /where: read it again, redraw the band, and print it. No Claude turn runs.
  on('command.run', { command: 'where' }, async ($) => {
    await readBranch($)
    $.ui.invalidate('ui.render')
    return { text: 'you are on ' + branch }
  })

  // The band above the prompt: one line with the branch.
  // await next(e) keeps whatever mods loaded after this one draw in the band.
  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
    const { Box, Text } = $.ui.resolve(e)
    const others = await next(e)
    return Box({
      flexDirection: 'column',
      children: [
        Box({
          flexDirection: 'row',
          columnGap: 1,
          children: [
            Text({ dimColor: true, children: ['git branch:'] }),
            Text({ bold: true, color: 'green', children: [branch] }),
          ],
        }),
        ...(others ? [others] : []),
      ],
    })
  })
}

The three files of the mod, copied by a script from the folder that ran, and checked byte for byte. The # lines are labels I added to show where each file starts. Claude Code also wrote a tsconfig.json and type files into the folder when it loaded the mod.

A real terminal frame of Claude Code v2.1.289 just after it started. The band above the prompt box reads git branch: (not a git repo), the mod's starting text, before git has answered. — The very first frame: the band drew before git answered

after “The three files”

Curious what sits underneath AI agents? This lesson takes it apart:

What Is in a Model File: It Is Mostly Numbers, and Loading It Runs Code: I took the features chapter's trained model and looked inside the saved file. Pickle made a 202,700-byte file. 95.9 percent of it was the raw bytes of the model's numpy arrays, and the rest named 16 classes from numpy and scikit-learn. Loading a pickle does not only read data: it imports those names and calls them. To show this safely, I built a harmless test file that writes one temp file and prints one line, and I read its call in the disassembly before loading it. Then I ran two scanners. By default, picklescan called 15 safe names in the real model suspicious and found no dangerous name in either file, and modelscan found no issue in either. Checked by name only, the obvious attack names, such as os system and builtins exec, are flagged on both lists (picklescan dangerous, modelscan CRITICAL). The reloaded model predicted identically to the bit.

57 min · diagrams · code you run · quiz

Get the AI Engineering course ₹999 in India · $49 elsewhere · pay onceor open the lesson

Continue in your course

Running it on my Mac

First I checked the mod and ran /where without opening the interactive screen. claude -p runs one prompt and prints the result. Because the mod handles /where, the AI model was not asked anything.

Then I started a normal session, where you type and Claude replies, in a test git repository I could delete later, on a branch called fix-login-timeout, and recorded the terminal with asciinema, a tool that records a real terminal session. The screenshot is a frame from that recording.

The band shows git branch: fix-login-timeout, just above the prompt box. That line is the mod's ui.render hook. When I typed /where, the command list showed it with its description, Read the git branch again, next to Claude Code's own commands.

What we measured: On my Mac, 5 October 2026, Claude Code 2.1.289: claude plugin validate listed 3 hooks and 4 calls and passed. claude -p "/where" printed branch-band: you are on fix-login-timeout. In the interactive session the band showed the branch from the second frame of the recording. No model call was made by the mod.

$ claude --version
2.1.289 (Claude Code)

$ claude plugin validate ../branch-band
Validating plugin manifest: /Users/abundance/lab-data/claude-mods-demo/branch-band/.claude-plugin/plugin.json

Validating hooks: /Users/abundance/lab-data/claude-mods-demo/branch-band/hooks/hooks.json

  ❯ ./register.js hooks: session.start, command.run{command=where}, ui.render{component=AbovePrompt}
  ❯ ./register.js calls: $.command.register, $.process.run (via readBranch), $.ui.invalidate, $.ui.resolve

✔ Validation passed

$ git branch --show-current
fix-login-timeout

$ claude -p "/where" --plugin-dir ../branch-band --setting-sources project
branch-band: you are on fix-login-timeout

Real output from my Mac, unedited. The $ lines are the commands; claude is Claude Code 2.1.289, installed with npm in a separate folder. The validate output prints full paths to my demo folder.

A real terminal frame of Claude Code v2.1.289 in the folder demo-repo. Above the prompt box is the line git branch: fix-login-timeout. The typed text /where shows a suggestion list with /where, Read the git branch again. — A real frame: the mod's band shows the branch above the prompt

Switching branch, then /where

While the session was open, I created and switched to a new branch, release-2026-10, from outside Claude Code. The band did not change on its own, because my mod reads the branch only at the start and when you ask.

Then I typed /where. The mod read the branch again, printed branch-band: you are on release-2026-10 in the conversation, and asked Claude Code to redraw, so the band changed to the new branch too. Claude Code adds the plugin's name in front of a command's text, which is why the line starts with branch-band.

A better version would read the branch on a timer with $.clock.every, so you never have to ask. I kept it simple on purpose: every extra call is one more thing a reader has to check.

A real terminal frame. The conversation shows /where and the reply branch-band: you are on release-2026-10. The band above the prompt now reads git branch: release-2026-10. — After /where: the reply and the band both show the new branch

Checking which mods a session loaded

The docs say to run /plugin to see which mods loaded. In my session the plugin screen showed 1 mod active · branch-band, and the Installed tab listed it under User, marked inline, which means loaded from a folder rather than installed.

The same tab listed three built-in plugins as on: cc-plugin-agents-md, cc-plugin-plugin-authoring and cc-plugin-telemetry. Show disabled listed one more, cc-plugin-you-should-know, which is off by default, as the docs say.

The docs also list cc-plugin-diff, the mod behind /diff, as on in interactive terminal sessions. It did not appear in my list, and I did not find out why. My session ran inside tmux, a tool that runs a terminal inside another terminal, which I used to drive the recording. That may matter.

A real terminal frame of the /plugin screen with the Installed tab selected, under the /where reply. It reads 1 mod active · branch-band. Under User: branch-band, Plugin, inline. Under Built-in: cc-plugin-agents-md, cc-plugin-plugin-authoring, cc-plugin-telemetry. Below: Show disabled (1). — The Installed tab in my session

What a mod can see and reach

A mod is code from someone else that runs on your computer. Anthropic's launch post says mods "aren't sandboxed", and the docs list what one can reach once it loads. Here is that list in plain words.

Your files. Anywhere your user account can read and write files, a mod can too, not only in your project.
Programs. Programs it starts run as you, the way my mod starts git.
The network. Web requests let it send data to any server.
Your secrets. Environment variables (named values your computer keeps for programs) and settings files are open to it. Both often hold an API key, a secret password that lets a program use a paid service.
Your session. Every prompt you send and every tool call Claude makes passes in front of it. It can rewrite them, type a prompt as if you had typed it, and send a message to another of your sessions.
Approvals. It can say yes to a tool call for you, before any prompt appears. This works even when a rule in your settings says Claude Code must ask you first. On a personal setup with no company settings, it can even approve a call that one of your deny rules (settings that block an action) refuses.
Your usage. Calls it makes to an AI model run on your Claude plan or API key, which uses up your limit or your money.
Not the permission prompt. A mod can restyle much of the screen. The permission prompt, the box where Claude Code asks you to allow an action, is the exception: a mod cannot change what it shows you.
No sandbox. Claude Code's optional sandbox limits the terminal commands Claude runs. A program that a mod starts runs outside it.

A mod in the centre with six spokes: your files, read and write anywhere your account can; programs, start them as you; the network, make requests over the internet; your secrets, environment variables, settings, API keys; your session, sees every prompt and tool call, can rewrite or approve them; your usage, call a model on your plan or key. Below: it cannot change what a permission prompt shows you, and it is not sandboxed. — What a mod can reach, from Anthropic's docs

How many public mods reach that far

Anthropic's launch post and docs give no count of mods. One community list, awesome-claude-code-mods on GitHub, scans public GitHub repositories on a schedule and reads each mod with claude plugin validate. Its README (the project's main page) for 2 October, scanned against Claude Code 2.1.287, counted 359 mods in 373 candidate repositories.

These are that list's numbers, not mine and not Anthropic's. I did not rerun the scan. They show how common the powerful calls already were one day after launch. A later version of the same README counted 1,747 mods on 4 October; I did not check whether its counting method changed.

What the mod's code can do	Mods	Share of 359
Read files	143	40%
Start programs on your machine	127	35%
See every prompt you send	111	31%
Write files	95	26%
See every tool call	79	22%
Reach the network	75	21%

Source: README of github.com/karanb192/awesome-claude-code-mods at commit 59a9911a, "As of 2026-10-02". The README also lists 21 mods that fail to validate on 2.1.287. A mod can be in several rows. Anthropic's admin docs add that a program a mod starts reaches the network with your own access, so mods that start programs can reach it too. Shares are my arithmetic, rounded.

The list itself warns that a long list of calls does not make a mod bad. A mod that shows your pull requests (proposed code changes on GitHub) has to start a program, because it runs gh, GitHub's command-line tool. Treat the numbers as a guide to which mods deserve a closer look.

A bar chart on an axis from 0 to 359 mods: read files 143, start programs on your machine 127, see every prompt you send 111, write files 95, see every tool call 79, reach the network 75. Labelled as a community scan from 2 October 2026, not Anthropic's numbers. — One community scan, 2 October 2026

How to check a mod before you install it

You do not have to run a mod to see what it asks for. This is the check I would do on any mod from someone else, using Claude Code's own tools and your own eyes.

Get the files first. Download the code, for example with git clone. Do not install it from the marketplace yet.
Run claude plugin validate. Point it at the folder. It reads the code without running it and prints a hooks: line and a calls: line, as in my output above. Modules that read or set environment variables also get env reads: and env writes: lines.
The calls: line. $.process.run and $.process.spawn start programs as you, and a program can do anything you can, including reading your keys and using the network. Treat them as full access. $.fs.read can read any file, including one full of secrets. $.fs.write changes files. $.http.fetch uses the network. $.env.get and $.settings.read can read API keys. $.env.set changes the environment for every command Claude runs afterwards. $.model.complete spends your usage. $.prompt.submit can send a prompt in your name. $.session.send and $.mcp.call reach other sessions and connected tools.
The hooks: line. tool.call and prompt.submit mean it sees every tool call and every prompt and can change them. tool.check means it can approve or deny a tool call before you see a permission prompt. session.append means it can rewrite the conversation before it is saved. A ui.render hook for the AskUserQuestion part means it can redraw the box Claude uses to ask you a question.
The source, not only the summary. The calls: line names the functions, not what they are given. Open the code and see which program $.process.run starts and with which words, which files $.fs.read opens, and where $.http.fetch sends data.
The rest of the plugin. A plugin can hold more than the mod. hooks/hooks.json can also hold settings hooks under a hooks key, which can run shell commands. The plugin can also ship MCP servers (separate programs that give Claude tools), skills, and scripts that the mod starts. validate does not check what those do.
Ask why. Every call should match what the mod says it does. My branch display needs $.process.run for git. A colour theme that asks for $.process.run, $.http.fetch or $.env.get needs a very good reason.
Trying it is running it. Loading a mod with --plugin-dir runs it at once, with the same access as installing it. For a mod you do not trust, try it inside a virtual machine or a container (a computer, or a walled-off part of one, that runs inside your own), or a separate user account that holds no keys.
Watch updates. Plugins can update themselves. Auto-update is on by default for most of Anthropic's official marketplaces and for ones added from claude.ai, and off for community, third-party and local ones. An update can change code you already checked, so pin a marketplace to a tag (a named version in git), as in /plugin marketplace add owner/repo#v1.2.0, and run validate again after every update. Whoever runs the marketplace controls what you install.
Know the off switches. Disable one mod in /plugin. Start one session with --safe-mode to skip every mod you installed. Or set "disableAllHooks": true in the settings file in your home folder, ~/.claude/settings.json, to stop them in every session. That setting also turns off your settings hooks and a custom status line.

validate is useful because a mod can only reach outside itself through $, and the docs say Claude Code will not load a mod whose use of $ validate cannot read. So the calls: line is a complete list of the functions the mod can use. It is not a list of everything those functions will do, and it cannot tell you whether the author is honest.

Companies get one more guard. On Team and Enterprise plans, and on any machine where a company sets the settings (managed settings), a built-in mod called sec-default loads first. It protects the company's own hooks and instructions and the deny rules, the settings that block an action, from users' mods. The docs say it adds no other limits. Deny rules cover Claude's tool calls only: a mod can still read a denied file itself with $.fs.read. On a personal setup without it, a mod can approve a call that a deny rule refuses.

What I could and could not check

What mods are, what they can do and what they can reach comes from Anthropic's launch post and docs, read on 5 October 2026 and linked below. The release date and time come from GitHub's release list. The scan numbers come from one community list and are labelled as such.

I wrote, validated and ran one small mod on Claude Code 2.1.289 on my Mac, and every screenshot is a frame from a real recording. My mod uses three hooks. I did not test panes, tool call hooks, model calls, the order in which several mods run, or sec-default, so those parts rely on the docs.

Questions

What is a Claude Code mod?

A plugin that contains JavaScript or TypeScript functions which Claude Code calls when something happens, such as a tool call, a prompt or part of the screen being drawn. A mod can watch, change or take over that event, draw its own panes, and add commands.

When did Claude Code mods come out?

On 1 October 2026, in Claude Code version 2.1.287. Anthropic's changelog says "Added Claude Mods: plugins may now modify deeper behavior". Mods need 2.1.287 or later and are on by default.

How do I install a Claude Code mod?

A mod installs like any plugin: run /plugin install name@marketplace in Claude Code, or claude plugin install name@marketplace in your shell. To try one for a single session without installing it, start Claude Code with --plugin-dir and the mod's folder.

Are Claude Code mods safe?

Only as safe as their author. A mod runs with your permissions and is not sandboxed: it can read and write your files, start programs, use the network, read your API keys and see every prompt. Run claude plugin validate on a mod's folder first and read its calls: line.

Do I need Node.js or a build step to write a mod?

Not to write or run the mod: Claude Code loads .js and .ts files directly, with no build step. My mod was three plain files: plugin.json, hooks.json and register.js. I only used npm to install a newer Claude Code.

How do I turn all mods off?

Start a session with --safe-mode, or set "disableAllHooks": true in ~/.claude/settings.json. Both stop the mods you installed. Claude Code's built-in mods keep running. You can disable most of them one by one in /plugin, but not the sec-default guard where it loads.

Sources

What this explainer is based on, so you can check it.

Customize Claude Code with mods Anthropic, 1 October 2026
Mods overview Anthropic, Claude Code docs
Create a mod Anthropic, Claude Code docs
Draw in the interface with a mod Anthropic, Claude Code docs
Use the mods API Anthropic, Claude Code docs
Manage mods for your organization Anthropic, Claude Code docs
Configure permissions Anthropic, Claude Code docs
Install plugins Anthropic, Claude Code docs
Claude Code changelog Anthropic on GitHub
Claude Code releases Anthropic on GitHub
awesome-claude-code-mods (community scan) karanb192 on GitHub, third party

Learn the parts behind it

Tool and Sandbox Security: Locking Down What an Agent Can DoHow to secure agent tools and code sandboxes: least privilege, microVM isolation, default-deny egress, argument validation, and resource limits.75 min lesson AI Supply Chain Security: What You Import Runs as YouYour LLM app loads weights, datasets, packages, and MCP servers you never wrote. Pin, hash, scan, sign, and verify provenance so an import cannot own you.90 min lesson Data Exfiltration and Egress Control in LLM SystemsA steered model needs no click to leak data, it writes a line of markdown. The exfiltration channels, and the egress controls that close every exit.85 min lesson Prompt Injection and the Lethal Trifecta: Why LLM Agents Leak DataPrompt injection is the top LLM security risk. Learn why it has no clean fix, how indirect injection works, and what the lethal trifecta is.60 min lesson Tool Calling Is a Contract, and the Model Will Break ItThe model never runs your functions. It emits text proposing a call, and sometimes that text is wrong. How to validate every tool call against a schema before it runs, and reject cleanly so the model self-corrects.39 min lesson Deterministic Scaffolding: The LLM Explains, It Does Not ArbitrateDeterministic scaffolding keeps control flow in code and calls the model only to classify or draft. The model recommends; code checks state and arbitrates.80 min lesson

Go deeper than the news

This explainer sits on top of our AI Engineering course: 204 lessons on RAG, evals, agents, serving, security and MLOps, many built around a real experiment. 10 lessons are free to read, with no card needed.

course 2

AI Engineering

Take models from notebook to production, with labs on real models.

204 interactive lessons
Serving, pipelines, feature stores and monitoring
RAG, fine-tuning, evals and agents
Step-by-step diagrams and quizzes
Lifetime access and all future lessons
A separate purchase from System Design

Read 10 lessons free first

In India

₹999

Pay with UPI

Everywhere else

$49

Pay with PayPal

once · yours for life

Claude Code mods explained: build your first mod, and what it can reach

Published5 October 2026, 17:15 UTC

In short

A mod is a plugin with code inside. Claude Code runs that code when something happens: Claude asks to use a tool, you send a message, or part of the screen is drawn.

Mods arrived in Claude Code 2.1.287 on 1 October 2026 and are on by default. You install one by typing the command /plugin inside Claude Code, like any other plugin.

I wrote a 3-file mod that shows the current git branch above the box where you type, and adds a /where command. Nothing had to be compiled first, and the mod never asked the AI model anything.

A mod is not sandboxed: nothing walls it off from the rest of your computer. It can read and write your files, start programs, use the network, read your passwords and API keys, and see every message you send.

Before you install one, run claude plugin validate on its folder. One line of the output contains calls:, and it lists what the mod can reach, without running it.

The course goes deeper on AI agents

₹999 in India$49 everywhere elseonce, for the whole course

Tool and Sandbox Security: Locking Down What an Agent Can Do

How to secure agent tools and code sandboxes: least privilege, microVM isolation, default-deny egress, argument validation, and resource limits.

75 min · diagrams · code you run · quiz

AI Supply Chain Security: What You Import Runs as You

Your LLM app loads weights, datasets, packages, and MCP servers you never wrote. Pin, hash, scan, sign, and verify provenance so an import cannot own you.

90 min · diagrams · code you run · quiz

Data Exfiltration and Egress Control in LLM Systems

A steered model needs no click to leak data, it writes a line of markdown. The exfiltration channels, and the egress controls that close every exit.

85 min · diagrams · code you run · quiz

Prompt Injection and the Lethal Trifecta: Why LLM Agents Leak Data

Prompt injection is the top LLM security risk. Learn why it has no clean fix, how indirect injection works, and what the lethal trifecta is.

60 min · diagrams · code you run · quizfree to read now

pay once,
yours for life

# branch-band/.claude-plugin/plugin.json { "name": "branch-band", "version": "0.1.0", "description": "Shows the current git branch in the band above the prompt, and adds a /where command", "author": { "name": "Roni Das" } } # branch-band/hooks/hooks.json { "description": "The branch-band hooks module", "modules": ["./register.js"] } # branch-band/hooks/register.js // The branch name, shared by the hooks below let branch = '(not a git repo)' // Ask git for the branch. $.process.run uses no shell, and resolves with the exit code. async function readBranch($) { try { const r = await $.process.run(['git', 'rev-parse', '--abbrev-ref', 'HEAD']) branch = r.exitCode === 0 ? r.stdout.trim() : '(not a git repo)' } catch { branch = '(git did not run)' } } export function register(on) { // When the session starts: read the branch once and add the /where command on('session.start', async ($, e, next) => { await readBranch($) await $.command.register({ name: 'where', description: 'Read the git branch again' }) return next(e) }) // /where: read it again, redraw the band, and print it. No Claude turn runs. on('command.run', { command: 'where' }, async ($) => { await readBranch($) $.ui.invalidate('ui.render') return { text: 'you are on ' + branch } }) // The band above the prompt: one line with the branch. // await next(e) keeps whatever mods loaded after this one draw in the band. on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => { const { Box, Text } = $.ui.resolve(e) const others = await next(e) return Box({ flexDirection: 'column', children: [ Box({ flexDirection: 'row', columnGap: 1, children: [ Text({ dimColor: true, children: ['git branch:'] }), Text({ bold: true, color: 'green', children: [branch] }), ], }), ...(others ? [others] : []), ], }) }) }

$ claude --version 2.1.289 (Claude Code) $ claude plugin validate ../branch-band Validating plugin manifest: /Users/abundance/lab-data/claude-mods-demo/branch-band/.claude-plugin/plugin.json Validating hooks: /Users/abundance/lab-data/claude-mods-demo/branch-band/hooks/hooks.json ❯ ./register.js hooks: session.start, command.run{command=where}, ui.render{component=AbovePrompt} ❯ ./register.js calls: $.command.register, $.process.run (via readBranch), $.ui.invalidate, $.ui.resolve ✔ Validation passed $ git branch --show-current fix-login-timeout $ claude -p "/where" --plugin-dir ../branch-band --setting-sources project branch-band: you are on fix-login-timeout

What the mod's code can do

Mods

Share of 359

Read files

143

40%

Start programs on your machine

127

35%

See every prompt you send

111

31%

Write files

26%

See every tool call

22%

Reach the network

21%

How to check a mod before you install it

You do not have to run a mod to see what it asks for. This is the check I would do on any mod from someone else, using Claude Code's own tools and your own eyes.

Get the files first. Download the code, for example with git clone. Do not install it from the marketplace yet.
Run claude plugin validate. Point it at the folder. It reads the code without running it and prints a hooks: line and a calls: line, as in my output above. Modules that read or set environment variables also get env reads: and env writes: lines.
The calls: line. $.process.run and $.process.spawn start programs as you, and a program can do anything you can, including reading your keys and using the network. Treat them as full access. $.fs.read can read any file, including one full of secrets. $.fs.write changes files. $.http.fetch uses the network. $.env.get and $.settings.read can read API keys. $.env.set changes the environment for every command Claude runs afterwards. $.model.complete spends your usage. $.prompt.submit can send a prompt in your name. $.session.send and $.mcp.call reach other sessions and connected tools.
The hooks: line. tool.call and prompt.submit mean it sees every tool call and every prompt and can change them. tool.check means it can approve or deny a tool call before you see a permission prompt. session.append means it can rewrite the conversation before it is saved. A ui.render hook for the AskUserQuestion part means it can redraw the box Claude uses to ask you a question.
The source, not only the summary. The calls: line names the functions, not what they are given. Open the code and see which program $.process.run starts and with which words, which files $.fs.read opens, and where $.http.fetch sends data.
The rest of the plugin. A plugin can hold more than the mod. hooks/hooks.json can also hold settings hooks under a hooks key, which can run shell commands. The plugin can also ship MCP servers (separate programs that give Claude tools), skills, and scripts that the mod starts. validate does not check what those do.
Ask why. Every call should match what the mod says it does. My branch display needs $.process.run for git. A colour theme that asks for $.process.run, $.http.fetch or $.env.get needs a very good reason.
Trying it is running it. Loading a mod with --plugin-dir runs it at once, with the same access as installing it. For a mod you do not trust, try it inside a virtual machine or a container (a computer, or a walled-off part of one, that runs inside your own), or a separate user account that holds no keys.
Watch updates. Plugins can update themselves. Auto-update is on by default for most of Anthropic's official marketplaces and for ones added from claude.ai, and off for community, third-party and local ones. An update can change code you already checked, so pin a marketplace to a tag (a named version in git), as in /plugin marketplace add owner/repo#v1.2.0, and run validate again after every update. Whoever runs the marketplace controls what you install.
Know the off switches. Disable one mod in /plugin. Start one session with --safe-mode to skip every mod you installed. Or set "disableAllHooks": true in the settings file in your home folder, ~/.claude/settings.json, to stop them in every session. That setting also turns off your settings hooks and a custom status line.

Questions

What is a Claude Code mod?

When did Claude Code mods come out?

On 1 October 2026, in Claude Code version 2.1.287. Anthropic's changelog says "Added Claude Mods: plugins may now modify deeper behavior". Mods need 2.1.287 or later and are on by default.

How do I install a Claude Code mod?

Are Claude Code mods safe?

Do I need Node.js or a build step to write a mod?

How do I turn all mods off?

AI Engineering

Take models from notebook to production, with labs on real models.

204 interactive lessons

Serving, pipelines, feature stores and monitoring

RAG, fine-tuning, evals and agents

Step-by-step diagrams and quizzes

Lifetime access and all future lessons

A separate purchase from System Design

Read 10 lessons free first

Claude Code mods explained: build your first mod, and what it can reach

In short

The course goes deeper on AI agents

What a Claude Code mod is

What a mod can do

Build your first mod: the plan

Check your version

Make three files

Write the hooks

Check it without running it

Load it for one session

Keep it, or share it

The three files

Running it on my Mac

Switching branch, then /where

Checking which mods a session loaded

What a mod can see and reach

How many public mods reach that far

How to check a mod before you install it

What I could and could not check

Questions

What is a Claude Code mod?

When did Claude Code mods come out?

How do I install a Claude Code mod?

Are Claude Code mods safe?

Do I need Node.js or a build step to write a mod?

How do I turn all mods off?

Sources

Learn the parts behind it

Go deeper than the news

AI Engineering

Claude Code mods explained: build your first mod, and what it can reach

In short

The course goes deeper on AI agents

What a Claude Code mod is

What a mod can do

Build your first mod: the plan

Check your version

Make three files

Write the hooks

Check it without running it

Load it for one session

Keep it, or share it

The three files

Running it on my Mac

Switching branch, then /where

Checking which mods a session loaded

What a mod can see and reach

How many public mods reach that far

How to check a mod before you install it

What I could and could not check

Questions

What is a Claude Code mod?

When did Claude Code mods come out?

How do I install a Claude Code mod?

Are Claude Code mods safe?

Do I need Node.js or a build step to write a mod?

How do I turn all mods off?

Sources

Learn the parts behind it

Go deeper than the news

AI Engineering