SLOPSHOPPER

status-band

A line above the prompt that says, in plain English, what Claude is doing right now and for how long

newbandguardtimer
v0.1.0no licenseupdated 2026-10-03carlvellotti/mods-starter/mods/status-band
A shopper browsing a rack in a slop shop
Preview · a replayed session in a sandbox
claude · ~/work/app · status-band
› fix the failing auth test and add an audit log call ⏺ Read(src/auth.ts) ⎿ Read 6 lines ⏺ Update(src/auth.ts) ⎿ Added 2 lines, removed 1 line ⏺ Bash(bun test) ⎿ 3 pass, 1 fail ● Done. refresh now rejects expired claims and logs an audit event. ✻ Worked for 42s · done 4:20 PM Waiting on you 42s Done ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── › ? for shortcuts

Draws

Band
Waiting on you 42s Done
README

Claude Code mods starter

Five small, commented mods you can run, read, and change, plus prompts for asking Claude to build your own.

Built and checked against Claude Code v2.1.287, the release where mods launched (October 1, 2026). The mods API is marked early access, so names can change between releases. Run claude --version to see yours.

What a mod is

A mod is a small TypeScript or JavaScript file that Claude Code runs inside itself while you work. It can watch what Claude does, change or block it, and draw things on screen, such as a line above the prompt or a side panel. It ships as a normal Claude Code plugin, so you install, update, and turn it off with /plugin.

The formula

Almost every mod idea fits one sentence:

When [trigger], [watch / change / block] [what], show it in [place], using [data].

Examples from this repo:

| Mod | When | Move | Show it in | Using | | :- | :- | :- | :- | :- | | status-band | a turn starts, a tool runs, a turn ends | watch | the band above the prompt | the tool name and a clock | | panel-with-buttons | Claude edits a file | watch | a pane, opened by /edits | the file path | | guard | Claude runs a risky shell command | block (ask first) | the question dialog | the command text | | slash-command | you type /plain-recap | answer | the transcript | the conversation and a small model | | dashboard | every 60 seconds | watch | a pane, opened by /dashboard | a JSON URL |

Write your idea in that shape before you start. It tells you which event to hook, which move to make, and which surface to draw on.

Cheat sheet

Six places a mod can show something

| Place | How | Notes | | :- | :- | :- | | Band above the prompt | ui.render hook on { component: 'AbovePrompt' } | Always there, shared by every mod. Terminal and Desktop. | | Pane | $.ui.open({ id }), then a ui.render hook on { component: 'Pane' } | A sidebar in a wide fullscreen terminal, otherwise a box above the prompt. | | Status line | $.ui.status('text') | One line under the prompt, shown as ⚠ your-mod: text. | | Toast | $.ui.toast('text') | Pops up at the top right for 4 seconds. | | Transcript line | $.ui.log('text') | A dim line in the conversation. Claude does not read it. | | Built-in parts | ui.render hook on Spinner, ToolUse, AssistantMessage, and others | Restyle or replace what Claude Code already draws. The permission prompt is off limits. |

Eight events worth knowing

| Event | Fires when | | :- | :- | | session.start | The session starts, and again each time the mod reloads. Register commands and start timers here. | | prompt.submit | You send a prompt. Rewrite it, add hidden context, or drop it. | | turn.start | Claude starts working on your prompt. | | tool.call | Claude is about to use a tool (read, edit, run a command). Watch, change, or refuse it. | | turn.complete | Claude finished (or you interrupted). Has the answer, the duration, and token usage. | | command.run | Someone runs a slash command. Answer your own commands here. | | ui.render | Claude Code is about to draw a place on screen. Return what to draw. | | classic.<Name> | Any settings-hook event, such as classic.Stop or classic.PermissionRequest. |

Three moves

Every hook gets ($, e, next): $ is what the mod can call, e is the event, and next passes the event along.

| Move | Code | Example | | :- | :- | :- | | Observe | return next(e) | Count tool calls and let them run. | | Rewrite | return next({ ...e, text: 'new text' }) | Trim a prompt before it is sent. | | Answer | return { deny: 'reason' } (no next) | Refuse a command. Claude reads the reason. |

Try the templates

Clone this repo, then pick a mod.

In the terminal, load one or more mods for a single session:

claude --plugin-dir ./mods/status-band
claude --plugin-dir ./mods/guard --plugin-dir ./mods/slash-command

In the Desktop app (Code tab), where you can't pass flags, add the folders to the env block of ~/.claude/settings.json. Use absolute paths, separated by : (or ; on Windows), then start a new session:

{
  "env": {
    "CLAUDE_CODE_PLUGIN_DIRS": "/Users/you/claude-mods-starter/mods/status-band:/Users/you/claude-mods-starter/mods/dashboard"
  }
}

As an install, once this repo is on GitHub:

/plugin marketplace add carlvellotti/mods-starter
/plugin install status-band@mods-starter

To check that a mod loaded, run /plugin and open the Installed tab. A line such as 1 mod active · status-band should name it.

What each template does once loaded:

| Mod | Try this | | :- | :- | | status-band | Ask Claude anything that uses tools. The band reads Working 12s Reading README.md, then Waiting on you 41s Done when Claude finishes. In the terminal, a permission prompt covers the band while it is open. | | panel-with-buttons | Ask Claude to edit a file, then type /edits. Press c to clear, x or Esc to close. | | guard | Ask Claude to run rm -rf some-folder. You get a Proceed / Cancel question first. | | slash-command | After a few turns, type /plain-recap, or /plain-recap focus on open risks. | | dashboard | Type /dashboard. Change the URL and fields in /config (or under pluginConfigs in settings). |

Ask Claude to build one

You don't have to write code. Claude Code has a built-in plugin-authoring skill for this.

  1. Describe it. In a session, say what you want using the formula, for example make a mod that shows the current git branch above the prompt. Typing /plugin-authoring first loads the skill explicitly. PROMPTS.md has 12 prompts to copy.
  2. Approve. Claude writes the mod to ~/.claude/dev-mods/<session-id>/<mod-name>/. You approve each file (that folder is protected), and on the first file Claude Code asks Enable hot reloading for this session? Pick Enable for this session. The mod loads when Claude's turn ends.
  3. Iterate. Try it, then tell Claude what to change. It reloads at the end of each turn that edits it.
  4. Keep it. That folder is deleted after cleanupPeriodDays. Copy the mod somewhere of your own, such as ~/mods/git-branch, and load it with claude --plugin-dir ~/mods/git-branch.

To change a template instead, copy its folder, rename name in its .claude-plugin/plugin.json, start claude --plugin-dir ./mods/<your-copy>, and ask Claude for the change. Names must not start with claude- or look like Anthropic's own, or validation fails.

Check and test

claude plugin validate mods/guard        # what the mod hooks and calls, and any errors
claude plugin validate --strict mods/guard
claude plugin test mods/guard            # runs mods/guard/tests/*.test.ts, no session needed

Read the hooks: and calls: lines that validate prints. They are the mod's ingredient list: every event it listens to and every capability it uses ($.http.fetch, $.process.run, $.fs.write, and so on).

If a mod does nothing:

  • Run claude plugin validate on its folder and fix what it reports.
  • Start with claude --debug and search the log for the mod's name.
  • A message containing the rollout switch served off means mods are turned off for your account from Anthropic's side. No local setting changes that.

Safety

  • Mods are not sandboxed. A mod runs with your permissions. It can read and write your files, run programs, make network requests, read secrets in your environment, see every prompt and tool call, submit prompts as you, approve tool calls, and spend your usage. Turning on Claude Code's sandbox does not contain a mod.
  • Read the code before you install a mod, including these. Each template here is under about 100 lines on purpose. Run claude plugin validate and read the calls: line.
  • Install only from people and marketplaces you trust. A marketplace can update a mod after you install it.
  • The guard is a seatbelt, not a lock. It matches command text, so other spellings get through. Keep real protections (backups, branch protection, database permissions).
  • To turn mods off, disable them in /plugin, or start with claude --safe-mode.

Layout

.claude-plugin/marketplace.json   lists the five mods so /plugin can install them
mods/<name>/
  .claude-plugin/plugin.json      the plugin's name, version, description, settings
  hooks/hooks.json                points at the code file
  hooks/register.ts(x)            the mod itself
  tests/*.test.ts                 tests for `claude plugin test`
PROMPTS.md                        prompts to paste into Claude Code

Further reading

Source 1 files
hooks/register.tsx 105 lines
1// status-band: one line above the prompt that says what Claude is doing.
2//
3// Pattern: WATCH events (turn.start, tool.call, turn.complete) and SHOW the
4// result in the band above the prompt (the AbovePrompt render site).
5// Works in the terminal and in the Desktop app's Code tab.
6
7import type { Register } from 'claude-code'
8
9// What the band shows. These reset when the mod reloads, which is fine here.
10let mode: 'idle' | 'working' | 'waiting' | 'done' = 'idle'
11let activity = ''
12let startedAt = 0 // when the current turn started, in milliseconds
13let lastTurnMs = 0 // how long the last turn took
14
15// Turn a tool call into a short plain-English phrase.
16function describe(tool: string, input: Record<string, unknown>): string {
17  const file = String(input.file_path ?? input.notebook_path ?? '').split('/').pop()
18  if (tool === 'Read') return 'Reading ' + file
19  if (tool === 'Edit' || tool === 'Write' || tool === 'NotebookEdit') return 'Editing ' + file
20  if (tool === 'Bash') return 'Running a command: ' + String(input.command ?? '').slice(0, 40)
21  if (tool === 'Grep' || tool === 'Glob') return 'Searching the code'
22  if (tool === 'WebFetch' || tool === 'WebSearch') return 'Looking something up online'
23  if (tool === 'Task' || tool === 'Agent') return 'Handing work to a helper agent'
24  if (tool === 'TodoWrite') return 'Updating its to-do list'
25  if (tool === 'AskUserQuestion') return 'Asking you a question'
26  if (tool.startsWith('mcp__')) return 'Using ' + tool.split('__')[1]
27  return 'Using ' + tool
28}
29
30// 65000 ms -> "1m 05s"
31function clock(ms: number): string {
32  const s = Math.max(0, Math.round(ms / 1000))
33  const m = Math.floor(s / 60)
34  return m > 0 ? `${m}m ${String(s % 60).padStart(2, '0')}s` : `${s}s`
35}
36
37export const register: Register = on => {
38  // Once per session: redraw every second while Claude works, so the time ticks.
39  on('session.start', async ($, e, next) => {
40    $.clock.every(1000, () => {
41      if (mode === 'working' || mode === 'waiting') $.ui.invalidate('ui.render')
42    })
43    return next(e)
44  })
45
46  // A turn begins: start the stopwatch.
47  on('turn.start', async ($, e, next) => {
48    startedAt = await $.clock.now()
49    mode = 'working'
50    activity = 'Reading your request'
51    $.ui.invalidate('ui.render')
52    return next(e)
53  })
54
55  // Claude is about to use a tool. Say which, let it run, then carry on.
56  on('tool.call', async ($, e, next) => {
57    activity = describe(e.tool, e as Record<string, unknown>)
58    mode = e.tool === 'AskUserQuestion' ? 'waiting' : 'working'
59    $.ui.invalidate('ui.render')
60    const result = await next(e) // the tool runs here (and any permission prompt)
61    mode = 'working'
62    activity = 'Thinking about what it found'
63    $.ui.invalidate('ui.render')
64    return result
65  })
66
67  // Claude Code is about to show a permission prompt: Claude is waiting on you.
68  // (In the terminal the prompt covers the band while it's open.)
69  on('classic.PermissionRequest', async ($, e, next) => {
70    mode = 'waiting'
71    activity = 'Needs your OK: ' + describe(e.tool_name, (e.tool_input ?? {}) as Record<string, unknown>)
72    $.ui.invalidate('ui.render')
73    return next(e)
74  })
75
76  // The turn ended. Subagent turns (agentId set) are ignored.
77  on('turn.complete', async ($, e, next) => {
78    if (e.agentId === undefined) {
79      mode = 'done'
80      lastTurnMs = e.durationMs
81      activity = e.isAborted ? 'Stopped' : 'Done'
82      $.ui.invalidate('ui.render')
83    }
84    return next(e)
85  })
86
87  // Draw the band. Returning next(e) means "draw nothing of mine".
88  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
89    if (e.props.hasSurvey || mode === 'idle') return next(e)
90    const { Box, Text } = $.ui.resolve(e)
91    const elapsed = mode === 'done' ? lastTurnMs : (await $.clock.now()) - startedAt
92    // "waiting" is a permission prompt or a question; "done" means it's your turn to type.
93    const label = mode === 'working' ? 'Working' : 'Waiting on you'
94    const color = mode === 'waiting' ? 'yellow' : mode === 'done' ? 'green' : 'cyan'
95
96    return (
97      <Box flexDirection="row" columnGap={1}>
98        <Text bold color={color}>{label}</Text>
99        <Text dimColor>{clock(elapsed)}</Text>
100        <Text wrap="truncate">{activity}</Text>
101      </Box>
102    )
103  })
104}
105