# Claude Code mods: an install guide for your agent · Code Cave

> Source: <https://gist.github.com/CodeCave0000/89fa887e69f475b2245777d06596e6f0>
> Published: 2026-10-08 23:43:41+00:00

**This file is for your agent.** It is written as instructions for Claude Code, which is why it is in English.
You don't need to read it. Give it to Claude Code and say which mods you want, for example:

`Read https://gist.githubusercontent.com/CodeCave0000/89fa887e69f475b2245777d06596e6f0/raw/claude-mods-codecave.md and install token-weather, blast-radius, replay-theater and cache-tax.`

From the Code Cave video on Claude Code mods · [https://www.youtube.com/@codecave0000](https://www.youtube.com/@codecave0000)

You are Claude Code. The user gave you this file so you can install one or more of the seven mods from the video. Follow these steps.

1. 
**Which mods.** Install only the mods the user named. If they said "all" or named none, list the seven with one line
each and ask which ones they want. The four the video keeps for everyday use: token-weather (the forecast above the
prompt), blast-radius (the brake before a delete), replay-theater (the replay at the end of a turn) and cache-tax (the
keepwarm for breaks).
2. 
**Version.** Mods are on by default from Claude Code 2.1.287 in the terminal, and from 2.1.286 in the Desktop app.
Run`claude --version` (in the Desktop app's Code tab:`/status` , the Claude Code row). If the version is lower, tell
the user and ask before you run`claude update` .
3. 
**Validate before installing.** A mod runs inside Claude Code with the user's own permissions: it can read and write
files, run processes, reach the network and see every message the user types. For each mod, get its source (the clone
or the marketplace below), run`claude plugin validate <folder>` , and show the user the two lines that matter:
  - `hooks:` the events the mod sits on
  - `calls:` what it asks Claude Code to do (for example`$.fs.read` ,`$.process.run` ,`$.http` ,`$.model.complete` )
 Say in plain words what that means, and wait for the user's go-ahead. The footprints listed below come from `claude plugin validate` on 2026-10-08 (Claude Code 2.1.294). If what you see differs, point out the difference before
installing.
4. 
**Install** with the exact commands listed for that mod, with`--scope user` where it is listed. A mod installs like any
plugin, and most take two lines:`claude plugin marketplace add <GitHub repo>` adds the source, then`claude plugin install <mod>@<marketplace>` installs the mod. Anthropic's three samples (token-weather, blast-radius,
replay-theater) come from one clone of their repository instead: clone it once, add its`claude-code/mods` folder as a
local marketplace, and install each sample with one line. Do not install these mods from any other source. If the user
asks for a mod that is not in this file, validate it the same way, tell them where it comes from, and install it only
if it comes from a source they trust.
5. 
**The band above the prompt.** token-weather, replay-theater, cache-tax and reflect-mod all draw in the band above the
prompt. Anthropic's samples note that the band is shared: another mod that draws there can take it from them. If the
user installs more than one of these, tell them, and if one of them stops showing, that is the first thing to check.
blast-radius draws its own pane in a terminal about 144 columns wide or more; in a narrower terminal it falls back to the
band, and if another mod holds the band its Proceed and Cancel buttons may not show (the command is then refused after
10 minutes). Suggest a wide terminal to anyone who relies on blast-radius.
6. 
**Load.** Mods load when a session starts. In a session that is already open, the user runs`/reload-plugins` .`/plugin` shows what loaded: a dim line under the tabs gives the count and the names, such as`1 mod active · first-mod` .
7. 
**Report.** Say what you installed, how to use each one (the commands and keys below), and how to turn it off (end of
this file).

Some mod READMEs were written during the early access and say to set `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`. Skip that step:
from Claude Code 2.1.287 mods are on by default, and Claude Code ignores that variable.

- Claude Code 2.1.287 or later in the terminal; the Desktop app from 2.1.286.
- Works in the terminal and in the Claude app's Code tab. In the VS Code extension the hooks run, but nothing a mod draws is shown.
- Docs: [https://code.claude.com/docs/en/plugins/mods/overview](https://code.claude.com/docs/en/plugins/mods/overview)
- Anthropic's announcement: [https://claude.com/blog/claude-code-mods](https://claude.com/blog/claude-code-mods)

Anthropic's own sample mod. The model remembers nothing between messages: every turn, Claude Code sends it the whole
conversation again, and that is the context window. When the window fills up, the conversation is compacted into a summary
and details are lost. token-weather shows how full the window is, as weather, in a band above the prompt: ☀ Clear under
25%, ☁ Cloudy from 25%, ☂ Showers from 50%, ☇ Storm from 75%, and ↯ Compact soon from 90%. Beside it: the percentage, the
tokens used out of the window, a chart of the last 12 turns, and how much the last turn added (`▲ +N last turn`). It
reads only the session's usage figures (`$.session.usage`, a free call) and draws them. It updates once per turn.

- Footprint: `hooks: session.start, turn.complete, ui.render{AbovePrompt}` ·`calls: $.session.usage, $.ui.invalidate, $.ui.resolve`
- Source: [https://github.com/anthropics/claude-code-playground/tree/main/claude-code/mods/token-weather](https://github.com/anthropics/claude-code-playground/tree/main/claude-code/mods/token-weather)

Clone the repo where the user keeps tools (ask if unsure) and leave it there: the marketplace is added from that folder, and the mods stop loading if the clone is moved or deleted.

```
git clone https://github.com/anthropics/claude-code-playground.git
cd claude-code-playground/claude-code/mods
claude plugin marketplace add ./
claude plugin install token-weather@claude-code-playground-mods --scope user
```

To try it for one session without installing: `claude --plugin-dir ./token-weather` (from the same folder).

Replaces API keys, email addresses and public IP addresses with a placeholder (`[REDACTED-SECRET-…]`, the same placeholder
for the same value) before they reach the model or the transcript, and shows a short notice that a value was hidden. The
real value is kept in the mod's memory, for this session only, and is never written to disk. On the way into a tool call
(a command, a file write) the placeholder is swapped back for the real value; on the way out, the tool's result is hidden
again, so a `cat .env` or a `Read` of a config file comes back with the placeholder too. Keys are recognised by their
shape (`sk-ant-`, `ghp_`, `AKIA`, JWTs and more) and by entropy. Free and open source (MIT).

Its README still asks for `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`, from the early access: skip that step.

- Footprint: `hooks: prompt.submit, tool.call, prompt.context` ·`calls: $.ui.notice, $.ui.toast`
- Source: [https://github.com/ray-amjad/awesome-claude-code-function-hooks/tree/main/plugins/secret-redactor](https://github.com/ray-amjad/awesome-claude-code-function-hooks/tree/main/plugins/secret-redactor)

```
claude plugin marketplace add ray-amjad/awesome-claude-code-function-hooks
claude plugin install secret-redactor@awesome-claude-code-function-hooks
```

Anthropic's own sample mod. It catches `rm -rf` (also `rm -r` and `rm -f`), `git reset --hard`, `git clean`,
`git push --force` and database migrations (`manage.py migrate`, `db:migrate`, `alembic upgrade`, `prisma migrate`) just
before they run, and shows what would change (how many files, what size, their names) with two buttons: Proceed (1) and
Cancel (2). Cancel has the focus, so Enter refuses. After Cancel the model is told the command was cancelled, and it
reports that nothing changed. It reads the command's text: it is one more layer before Claude Code's permission prompt, not
a replacement for it. For its side pane the terminal should be about 144 columns wide (see step 5).

- Footprint: `hooks: tool.call{Bash}, ui.render{Pane}, ui.render{AbovePrompt}` ·`calls: $.clock.now, $.process.run, $.session.cwd, $.ui.close, $.ui.invalidate, $.ui.open, $.ui.resolve, $.ui.toast`
- Source: [https://github.com/anthropics/claude-code-playground/tree/main/claude-code/mods/blast-radius](https://github.com/anthropics/claude-code-playground/tree/main/claude-code/mods/blast-radius)

```
claude plugin install blast-radius@claude-code-playground-mods --scope user
```

It needs the local marketplace from mod 1: run that mod's first three commands first if they have not run.

A file tree on the right of the terminal. In the terminal it needs `/tui fullscreen` and a terminal at least 110 columns
wide. Files shimmer purple while Claude reads them, orange while it writes them and green when they are committed; every
changed file shows `+N -N` (lines added and removed); the branch and the git status sit at the top, and a commit shows at
the bottom of the pane. It searches the whole tree, including folders not opened yet, sends a selected file to the model
as context, and shows sizes. It reads the folder and git, and runs `git` when asked to.

- Footprint: `hooks: session.start, command.run{filetree}, tool.call, ui.message, classic.FileChanged, prompt.submit, ui.render{Pane} …` ·`calls: $.fs.list, $.fs.read, $.fs.stat, $.process.run, $.session.cwd, $.state.get/set, $.ui.open/close/copy/toast …`
- Source: [https://github.com/data-goblin/claude-code-filetree](https://github.com/data-goblin/claude-code-filetree)

```
claude plugin marketplace add data-goblin/claude-code-filetree
claude plugin install filetree@claude-code-filetree
```

To use it inside a session: `/tui fullscreen`, then `/filetree`.

Anthropic's own sample mod. After a turn that edited files, a Replay button waits above the prompt
(`▶ Replay: 8 edits (press r)  [ Replay ]`). `r` (or `/replay`) opens a pane that steps through every edit of that turn, in
the order Claude made them: the file, the deleted lines in red, the added lines in green (`n` next, `p` previous,
`c` close). It only records the Edit, Write and MultiEdit calls and reads the files to draw the diffs; it never blocks,
changes or delays an edit.

- Footprint: `hooks: session.start, command.run{replay}, tool.call, turn.start, turn.complete, ui.render{AbovePrompt}, ui.render{Pane}, ui.close` ·`calls: $.clock.sleep, $.command.register, $.fs.exists, $.fs.read, $.session.cwd, $.ui.close/invalidate/open/resolve`
- Source: [https://github.com/anthropics/claude-code-playground/tree/main/claude-code/mods/replay-theater](https://github.com/anthropics/claude-code-playground/tree/main/claude-code/mods/replay-theater)

```
claude plugin install replay-theater@claude-code-playground-mods --scope user
```

It needs the local marketplace from mod 1.

Part of the claude-reflect project (about 1,700 stars on GitHub). Install `reflect-mod`, not `claude-reflect`: the same
marketplace lists both. Every short message from the user (up to 500 characters, not a slash command, not an
acknowledgement like "ok") is checked by one small model call (Haiku). When it spots a correction worth keeping, for
example "no, in this project we use pnpm", a band above the prompt shows the rule it wrote and offers to save it in one
click: to `./CLAUDE.md` (this project) or to `~/.claude/CLAUDE.md` (every project), or to edit it first. The rule also
applies in the current session at once, and CLAUDE.md loads it in every session after. `remember: <rule>` skips the check
and goes straight to the band. Each check is a model call on the user's own plan: tell the user before installing.

- Footprint: `hooks: prompt.submit, ui.render{AbovePrompt} …` ·`calls: $.model.complete, $.fs.read/write (CLAUDE.md), $.ui …` (run`claude plugin validate` on the repo's`mod/` folder for the full list)
- Source: [https://github.com/BayramAnnakov/claude-reflect](https://github.com/BayramAnnakov/claude-reflect) (the`mod/` folder)

```
claude plugin marketplace add bayramannakov/claude-reflect
claude plugin install reflect-mod@claude-reflect-marketplace
```

The only one of the seven that deals with money. Anthropic's prompt cache keeps the conversation for an hour (on a subscription), so inside that hour each turn reads only what is new, cheaply. After an hour of quiet the cache is gone, and the next message, even two words, has the model read the whole conversation again. cache-tax holds such a "cold" message once, in a session with 50,000 tokens of context or more, and shows its estimated price (an upper bound, the API equivalent; on a subscription it uses quota, not money). Sending it again goes ahead; the decision stays with the user. After a cold send it arms at least three hours of keepwarm by itself.

Before a break, `/keepwarm 90m` keeps the cache warm for a window the user picks (`/keepwarm` alone arms six hours,
`/keepwarm off` stops). After 50 minutes of quiet it sends the model one tiny ping that asks for nothing, so the hour starts
again, and it stops by itself when the window ends. While a window is armed, a row above the prompt shows warm or cold, the
window and the next ping. Pings cost tokens, so suggest a window the user will really come back in. `/cache-tax` shows the
status.

The 50-minute schedule needs a one-hour cache. A subscription has it by default. With an API key, usage credits or a cloud
provider the cache lasts five minutes unless the `promptCacheTtl` setting is `"1h"`: ask which the user has, and if they
need it, offer to set it.

- Footprint: `hooks: config.set{key=theme}, ui.render{component=AbovePrompt}, session.start, classic.SessionStart, command.run{command=keepwarm}, command.run{command=cache-tax}, prompt.submit, turn.step, turn.complete, session.compact` ·`calls: $.clock.after (via arm), $.clock.now, $.command.list, $.command.register, $.config.list, $.env.get, $.model.fork (via ping), $.session.id, $.session.model, $.session.usage, $.store.delete (via prune, startWindow, stop), $.store.get, $.store.set, $.ui.invalidate, $.ui.log, $.ui.resolve, $.ui.status`
- Source: [https://github.com/karanb192/cache-tax](https://github.com/karanb192/cache-tax)

```
claude plugin marketplace add karanb192/claude-code-mods
claude plugin install cache-tax@claude-code-mods
```

After installing from the terminal, in a session that is already open: `/reload-plugins`.

Claude Code ships with a built-in skill for writing mods, `plugin-authoring`: use it. This is the request from the video:

```
Write me a mod that counts the tool calls you make and shows the count beside the spinner while you work, like 'Thinking · tool calls: 3'. Keep it small, and hot reload it in this session.
```

In the video this produced a small folder, with hot reloading turned on for that session (`2. Enable for this session`),
so there was no need to restart Claude Code:

```
tool-call-counter/
├── .claude-plugin/plugin.json     name, version, description
├── hooks/
│   ├── hooks.json                 points at the code: { "modules": ["./register.ts"] }
│   └── register.ts                the functions
├── tests/counter.test.ts          a test
└── types/ · tsconfig.json         Claude Code's types for TypeScript
```

The `register.ts` it wrote:

``` python
import { atom, read, update } from 'claude-code'
import type { Register } from 'claude-code'

const count = atom({ plugin: 'tool-call-counter', key: 'count' } as const, 0)

export const register: Register = on => {
  on('turn.start', async ($, e, next) => {
    await update($, count, () => 0)
    return next(e)
  })

  on('tool.call', async ($, e, next) => {
    await update($, count, n => n + 1)
    return next(e)
  }).catch(($, e, next) => next(e))

  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    const n = await read($, count)
    const base = e.props.message ?? e.props.word
    return next({ ...e, props: { ...e.props, message: `${base} · tool calls: ${n}` } })
  })
}
```

The function on `tool.call` counts, the function on the Spinner's render adds the count to it, and `turn.start` resets it
every turn. On the next turn the spinner reads `tool calls: 3`. A mod built this way lasts for that session only, so it can
be tried without committing to anything. If the user likes it, save it as a plugin and install it, or:

```
claude plugin validate ./tool-call-counter
claude --plugin-dir ./tool-call-counter          # one session
```

- One mod: `/plugin` → Installed → disable or uninstall.
- All mods, for one session: `claude --safe-mode` (it also turns off the user's other customizations).
- All mods, in every session: `"disableAllHooks": true` in`~/.claude/settings.json` (the user's settings hooks and custom
status line stop too).
- To see what is loaded: `/plugin` shows a small line,`N mods active · …` .

A community catalogue that scans GitHub, [https://mods.aidojo.si](https://mods.aidojo.si), counted 2,692 mods a week after the launch: 1,373 of
them write files or run processes, and 327 use the network. If the user asks for one of them, apply step 3 before anything
else, and install only from a source the user trusts.

Code Cave · [https://www.youtube.com/@codecave0000](https://www.youtube.com/@codecave0000)