---
title: Claude Code mods are really cool, and here is a small one to build
seo_title: Claude Code mods explained, with an example to build
date: 2026-10-03
summary: Mods are small TypeScript functions that change how Claude Code works: they rewrite a prompt, hold a risky command or draw a panel. What they are, how they differ from hooks, whether they are safe, and a small example mod that shows an article's reading time while Claude edits it.
description: What Claude Code mods are, how they differ from hooks, whether they are safe to install, and a small example mod that shows an article's reading time.
tags: [ai, claude-code, tooling]
---
Claude Code got a feature this week that I did not expect to like this much: mods. A mod is a small TypeScript function that changes how Claude Code works. It can rewrite a prompt, hold a risky command until you say yes, or draw a panel of its own. I think that is really cool. This article explains what mods are, how they differ from hooks and whether they are safe to install, then walks through one small example you can build yourself.

I am writing this two days after the announcement, so it is a first impression with a passing test suite behind it, not a review after months of use. It rests on two pages from October 1, 2026: [Anthropic's announcement](https://claude.com/blog/claude-code-mods) and [a getting-started guide on claude.dev](https://claude.dev/blog/getting-started-with-claude-code-mods/) by Addy Osmani. The mod near the end is the one thing I made rather than read about, and, [as on the rest of this site](software.html#how), it was written by an agent, with the tests as the gate.

## What is a Claude Code mod?

A Claude Code mod is a small TypeScript or JavaScript function, shipped inside a plugin, that changes how Claude Code works. Claude Code raises an event for each thing it does: a tool call, a permission question, a redraw of part of the screen. A mod hooks one of those events and can step in before it, after it, instead of it, or around it.

- **Announced:** October 1, 2026, for the Claude Code command line and the desktop app.
- **Needs:** Claude Code 2.1.287 or later, where mods are on by default.
- **Can do:** rewrite a prompt before the model sees it, block, change or retry a tool call, answer a permission request, and strip secrets out of tool output before Claude reads it.
- **Can show:** its own buttons, inputs and panels, or a replacement for a tool result, in the terminal, the desktop app or both.
- **Comes from:** the Claude directory or `/plugin`, like any plugin. You can also ask Claude Code to write one for you.

## How are mods different from hooks?

Hooks cannot rewrite an event, draw new UI or replace a feature, and mods can, according to the announcement. The guide puts it the other way round: under the hood, mods are hooks that ship inside plugins.

| What it can do | Hooks | Mods |
| --- | --- | --- |
| Rewrite an event | No | Yes |
| Draw new UI | No | Yes |
| Replace a built-in feature | No | Yes |

That is the difference between running a script when something happens and changing what happens.

## Why are Claude Code mods really cool?

**Claude can write the mod and load it into the session you are in.** The guide's shortcut is to run `claude`, describe the mod you want, and allow hot reloading when it asks. The mod appears when the turn ends. Going from an idea to a tweak in one conversation is the part I find hardest to resist.

**The built-in features are mods too, and you can read them.** The guide says some of Claude Code's own features are built as mods, including AGENTS.md support and the `/diff` pane, with source and tests in the [public repository](https://github.com/anthropics/claude-code) under `mods/`. The announcement says you can turn the `/diff` mod off in `/plugin` or replace it with your own, and that more built-in features will move over time, toward a small core you add to.

**It was built with teams in mind.** Because mods ship inside plugins, the existing plugin controls apply: admins can allow or block marketplaces. On Team and Enterprise plans, and on any machine with managed settings, a built-in mod called `sec-default` loads first and stops installed mods from doing risky things, such as overriding your permission deny rules.

## What can mods do? Three examples from the guide

The guide builds one mod from an empty folder, then tours two larger ones. They show how far the API reaches.

- **Token Weather** draws a line above the prompt that forecasts your context window, from clear to storm, with the percentage used, the token count and a small chart of recent turns. It is about 80 lines, and the guide builds it step by step. A weather report for a context window is the kind of joke that is also useful.
- **Blast Radius** holds a risky Bash command, such as `rm -rf`, `git reset --hard`, a force push or a database migration. It works out what the command would touch and opens a pane with Proceed and Cancel. Cancel sends Claude a refusal with the reason.
- **Replay Theater** records every Edit and Write in a turn. When the turn ends you can step through the changes one diff at a time. It never blocks or alters an edit.

The guide is upfront about Blast Radius's limit. It reads the command text, so command substitution, aliases and scripts that call `rm` get past it. It is a safety net, not a permission system, and a hard block belongs in permission rules.

## How do you build a Claude Code mod?

A mod is a plugin folder with three parts: a manifest, a `hooks.json` that names one module, and a module that exports `register`. Here is a small one.

I keep articles on this site to 7 to 10 minutes of reading, and the site's tests check it when I build. One older article, the Master Brief, is still over. I would rather see the number while Claude is writing than find out afterward. So the mod does one thing. When Claude edits or writes a Markdown file in `content/articles`, it counts the reading time the way the site does, shows it in the status line, and pops up a warning when it goes over 10 minutes.

First the manifest, `.claude-plugin/plugin.json`:

```json
{
  "name": "reading-clock",
  "version": "0.1.0",
  "description": "Shows the reading time of a Markdown article each time Claude edits one, and warns when it runs over the house limit.",
  "author": { "name": "Antonios Kioksoglou" }
}
```

Then `hooks/hooks.json`, which names the module:

```json
{
  "modules": ["./register.ts"]
}
```

And the module, `hooks/register.ts`. This is the whole file:

```ts
import type { Register } from 'claude-code'

const ARTICLE = /\/content\/articles\/[^/]+\.md$/
const MIN = 7
const MAX = 10

// The site's own rule: about 225 words a minute, the header and code blocks left out, never less than 1.
export const minutes = (md: string): number => {
  const words = md
    .replace(/\r\n?/g, '\n')
    .replace(/^---\n[\s\S]*?\n---\n/, ' ')
    .replace(/```[\s\S]*?```/g, ' ')
    .split(/\s+/)
    .filter(Boolean).length

  return Math.max(1, Math.round(words / 225))
}

export const register: Register = on => {
  on('tool.call', { tool: ['Edit', 'Write'], file_path: ARTICLE }, async ($, e, next) => {
    const ran = await next(e)
    if (ran.deny !== undefined || ran.isError) return ran

    const name = e.file_path.split('/').pop()
    const n = minutes(await $.fs.read(e.file_path))

    $.ui.status(`${name}: ${n} min (house rule ${MIN} to ${MAX})`)
    if (n > MAX) $.ui.toast(`${name} reads in ${n} minutes. Trim it to ${MAX} or less.`)

    return ran
  })
}
```

Here is what to look at.

- **The matcher.** `{ tool: ['Edit', 'Write'], file_path: ARTICLE }` limits the hook to those two tools and to Markdown files in `content/articles`. Everything else passes through untouched. A matcher value can be a plain value, a list or a regular expression.
- **`await next(e)` comes first.** A hook that returns without calling `next` answers for itself. One that calls it passes the event down the line and gets the result back. Here the mod lets the edit happen first and only then looks at the file. If the edit failed or was refused, it returns the result unchanged.
- **`$.fs.read`.** After an Edit the mod only knows the changed piece, so it reads the whole file. Everything outside its own code goes through `$`, because the module runs in an environment of its own, with no Node or browser.
- **`minutes`.** The site's rule: about 225 words a minute, header and code blocks left out, never less than 1. The mod cannot import code from the site, so it carries a copy, which is why I checked it against the real thing.
- **`$.ui.status` and `$.ui.toast`.** The status line always shows the number. The toast only appears over 10 minutes, so a short first draft does not nag.

## How do I know the example works?

The guide names two commands for checking a mod. I used both.

- `claude plugin validate reading-clock` passes. Its report lists what the module hooks, here `tool.call` on Edit and Write for files matching the pattern, and every call it makes on `$`: `fs.read`, `ui.status` and `ui.toast`. If I install a mod someone else wrote, that list is the first thing I will read.
- `claude plugin test reading-clock` runs five tests: the counting rule, the status line, the warning, the border between ten and eleven minutes, and that other files and edits that failed or were refused are left alone. A test stands in for Claude Code. It answers the file read and records what the mod sends to the status line, so no real file or screen is involved.

Then I broke the mod on purpose, in a copy, to see whether the tests would notice. I planted 19 mistakes, such as a wrong rate, counting the header and acting on failed edits. A few of my tests were too soft and let one through, so I tightened them. After that the tests caught all 19.

Last, I ran the mod's counting function over every article in this repository and compared it with the number the site's build gives. Every article on the site agrees, the 12-minute Master Brief included. The mod would have nagged me about that one, and fairly.

One note on versions. The command-line build on my machine is 2.1.282, older than the 2.1.287 the guide asks for, so I ran the checks there with the early-access switch, `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`. I have not run this exact file on 2.1.287 or newer, and I have not lived with it in a real session yet, so call it a first version.

## How do you start with your own mod?

Describe the mod to Claude Code and allow hot reloading when it asks. That is the guide's shortcut, and you do not have to write any of this by hand. For this one I would start with something like:

> Build a Claude Code mod called reading-clock. After any Edit or Write to a Markdown file in content/articles, count its reading time at 225 words a minute, leaving out the header and code blocks. Show it in the status line, and show a warning toast when it is over 10 minutes. Write tests, run claude plugin validate and run the tests.

Then I would read what comes back before I trust it, the same way I read a diff.

A mod made that way loads only in that session, and the guide says its folder is cleaned up later. To keep one, copy the folder out and install it like any plugin. The guide shows how to share one through a marketplace folder, and the announcement says you can submit a plugin to the Claude directory so others can find it.

The guide lists more places to start, and I have not built any of them: a cost meter, team conventions added to every prompt, and a guard for the commands that make you nervous, like `terraform apply`. In my line of work I would add a guard that asks before anything touches a live store or an ad account.

## Are Claude Code mods safe to install?

Not automatically. The announcement says mods run with the same access to your machine as Claude Code itself and are not sandboxed. The short answer is also [in the FAQ](faq.html#are-claude-code-mods-safe-to-install). The longer one:

- **A mod can do what Claude Code can do.** The guide adds that a mod is written by its publisher, not by Anthropic, so treat an install like a package: read the repository first and install only from people you trust. You can browse mods in the Claude directory or with `/plugin`.
- **The `$` list is the reach.** The module has no Node and no browser of its own, but `$` includes files, processes and network calls. Read the list `claude plugin validate` prints, then read the code.
- **Give it the least access that works.** The rule from my [article on read-only analytics agents](articles/read-only-mcp-ga4-google-ads-bigquery.html) applies here too: start with the narrowest access and widen it only when you need to.
- **The API is early.** The guide says it can change between releases. Each time Claude Code loads a mod, it writes the type declarations for your build into the mod's `.claude-plugin/types` folder. If my file stops working on a newer build, I would look there first.

## Where this leaves me

What I like most is the size of the first step. My first mod counts words and writes one line under the prompt, and I already have opinions about the next three. It is two days old, I have built exactly one small mod, and my sources are the vendor's own pages, so take my enthusiasm for what it is. Still, the first time a tool lets you change what it shows you, you start noticing what you wish it showed. That is really cool, and a little dangerous for my afternoon.

Sources: Anthropic, [Customize Claude Code with mods](https://claude.com/blog/claude-code-mods) (October 1, 2026). Addy Osmani, [Getting started with Claude Code mods](https://claude.dev/blog/getting-started-with-claude-code-mods/) (claude.dev, October 1, 2026). Mods are new and the API can change between releases, so some details here may have moved on.
