Start here
A mod is a small JavaScript plugin that runs inside Claude Code. Mods arrived in v2.1.287 on 1 October 2026; this machine runs 2.1.299. A mod does three kinds of things.
1. It draws
Panes beside or above the conversation, a strip above the prompt, lines under the prompt, toasts and extra lines in the transcript. It can also restyle parts Claude Code draws itself: the spinner, tool rows and the question dialog.
2. It reacts
Claude Code tells the mod about every turn, tool call, prompt, compaction, subagent and message from another session. The mod can watch the event, change it, or answer it itself. For example, it can refuse a git push before the command runs. Every $ call a mod makes is an event too, so one mod can hook another mod's calls. Tested: the mods mod catches every other mod's status line and redraws them all as one row.
3. It acts on its own
It runs timers, submits a prompt, and runs slash commands such as /clear. It can register its own slash commands and tools, call a small model, read files, run processes and copy text to the clipboard. It can also send one extra request over the session's own transcript ($.model.fork). That request is served from the session's prompt cache, and its reply never joins the conversation.
How to read this page
Every idea says where it draws and how you use it. "How you use it" is one or more of these six marks:
Every idea also carries a status:
- tested here: I ran it in the playground today.
- in the docs: Anthropic's docs or this build's type file say it works.
- inferred: nobody has tried it yet.
Where the ideas came from
- Your sessions. Three Sonnet agents read only what you typed: about 1,500 messages across roughly 120 sessions, covering my work repo, commerce/visualizer/payment/access-manager, and claudegeneral/claude-config.
- Your skills. An Opus agent mapped
cmd-clarify, session-handoff and lesgoo onto the mods docs and the type file. - The playground, morning. A Claude session (Haiku 5.5) in a herdr pane, running two test mods I wrote,
showcaseandidle-probe. - The playground, afternoon and evening. Seven working mods, all loaded in a browser terminal on a local server: xterm.js and node-pty, Claude Code 2.1.299, fullscreen, a fresh Haiku session per page load. The "Proven today" tab lists them.
- Other people's mods. A Sonnet agent searched the web; see the "Others' mods" tab.
Where mods draw
There are four groups, each with its own picture: around the prompt, in the transcript, panes, and dialogs and alerts. In each picture, a purple dashed outline marks something a mod draws, and a grey outline marks Claude Code's own part, which no mod can change. The numbers match the list beside the picture. The table under each picture has the details.
A. Around the prompt
Always on screen. Use these for things you want to see at a glance, without asking.
- 1Band above the prompt. A strip all mods share, for live state: a run strip, a stuck checkpoint, a resume picker. Its buttons fire when you type their digit into the empty prompt. All mods draw it as one tree, so each mod must stack its line on the other mods' lines (tested).👁 view⌨ digit🖱 click
- PThe prompt is Claude Code's. A mod can put a draft or a dim suggestion into it, but cannot redraw it.
- 2Autocomplete rows under the prompt while you type, such as handoff slugs after
resume.⌨ arrows + Enter - 3Status line. One pinned line per mod, above your status-line command's output. It always starts with
⚠ name:, and the mod cannot remove that. Another mod can catch the line and draw it elsewhere (see 6).👁 view only - 4Hint tail. Text a mod adds at the end of the dim hint line. It draws grey, like the rest of the line. Quiet and always visible: the place for a gauge.👁 view only
- 5Footer mode label. A word next to Claude Code's own mode labels, such as "away". A mod can draw its own tree there. Tested: context-meter shows
calm 65 · relay 75there, at the right end of the first status-line row.👁 view only - 6Hint row, own tree. A mod can replace the hint line with its own drawing: coloured, and more than one row. Tested: the
modsmod draws every mod's status as one coloured row at the very bottom, without the⚠.👁 view only - 7Toast, classic renderer. One line at the right under the prompt for a few seconds. In fullscreen it is a box at the top right (see D).👁 view
| Surface | How you use it | Limits |
|---|---|---|
| Band above the prompt | Type a digit into the empty prompt and pause, and the band button with that hotkey fires. For other keys, give the band the keyboard with Ctrl+X Tab or a click. [-], or Ctrl+X Ctrl+A, collapses it. | At most half the screen, prompt included. Tested: typing 2 pressed "waive". All mods share one tree: a mod must call next(e) and stack its line with the result, or it replaces the other mods' band. Tested: the handoffs line drew above the mr-board line. |
| Autocomplete rows | The rows appear below Claude Code's own. Choosing one writes its text over the word. | In the docs, not tested. |
| Status line | View only. | Always prefixed ⚠ modname:; the mod cannot remove it. Drawn above the status-line command's output. Every $.ui.status call is an event that another mod can hook; next.origin.plugin names the mod that called. Tested. A wide emoji (☕) garbled the row ("pwarm"); 🛡 drew fine. |
| Hint tail | View only. | Terminal only; cut at the line's end. Draws grey (#999999, read from the terminal), not green. Tested. |
| Hint row, own tree | View only. | Coloured, more than one row, drawn at the bottom of the footer. Tested. |
| Footer mode label | View only. | Tested: a mod's own tree shows at the right end of the first status-line row. |
| Prompt draft and suggestion | Press Enter to send it, or edit it first. | In the docs. |
B. In the transcript
Lines that scroll with the conversation. Use these for a record of what happened.
- 1Info notice under the logo when a session starts.👁 view only
- 2Your message. A mod can restyle how it is shown.👁 view only
- 3Tool row and its result. A mod can restyle, shorten or add a line.👁 view
- 4A guard's refusal. Not a drawing: the mod refused the call and Claude reads the reason.⚡ automatic
- 5Spinner. Words after its verb, or a replacement.👁 view only
- 6Tool progress while a tool runs. Terminal only.👁 view only
- 7Claude's reply. A mod can restyle it; Markdown links can run the mod's action on click.👁 view🖱 links
- 8Turn duration line. Terminal only.👁 view only
- 9Line under the answer. One line per reply: context, cache, time. Its label names every mod that hooks the turn end, for example
agents-dock+context-meter+keep-warm+cc-plugin-agents-md:.👁 view only - 10Log line. A dim line for you that Claude does not read, so it costs no context. Its label is only its own mod's name, so a mod that wants its own label under the answer uses a log line.👁 view only
- 11Command output. What a mod's slash command prints./ command
Restyling a message or a tool row changes only what you see. Claude still reads the original. Neither the line under the answer nor a log line reaches the model. Tested today: 5, 9 and 10.
C. Panes
The only big canvas: tabs, buttons, text fields, dropdowns, Markdown, code, diffs and coloured grids. Where a pane sits depends on the terminal's width.
Wide fullscreen terminal (110 columns or more): docked on the right
- 1The pane, docked floor to ceiling on the right. Drag its edge, or press Ctrl+X then an arrow, to resize it./ open🖱 click⌨ keys
- 2Pane tabs. With two or more panes open, one shows at a time and the rest become tabs.
✕closes the pane.🖱 click⌨ Ctrl+X X closes - 3Buttons used as tabs inside one pane. A plain button shows its hotkey, like
2: Agents.⌨ hotkey🖱 click - 4Text field. Type, then Enter. While it has focus, hotkeys type letters instead.⌨ type + Enter
- 5Dropdown. Enter opens it, the arrows move, Enter picks.⌨ keys🖱 click
Narrow terminal or a herdr split: a framed block above the prompt
- 1Inline pane. The same pane, above the prompt, taking a third of the space by default. Ctrl+X then Up or Down changes its height.
- !Width rule. A pane you open (by a command or a button) appears at any width. A pane the mod opens by itself, from a timer for example, waits until the terminal is 144 columns wide, or 110 once you have opened it yourself. In herdr splits, open panes from a command.
| Action | Mouse | Keyboard |
|---|---|---|
| Open a pane | Click a button that opens it | Run its command, such as /mods-mrs |
| Give it the keyboard | Click inside it | Ctrl+X then Tab |
| Move between controls | Click the control | Tab, or Up and Down |
| Press a button | Click it | Its hotkey, or Enter when it has focus |
| Scroll a tall pane | Mouse wheel (fullscreen) | Page Up, Page Down, Home, End |
| Resize it | Drag its edge | Ctrl+X then an arrow |
| Hand the keyboard back | Click the prompt | Esc |
| Close it | Click the ✕ | Ctrl+X then X (or Esc, if the mod allows it) |
Not tested here: dragging the edge and wheel scrolling. Clicks are tested on the Click or keyboard tab. The rest of the table comes from the docs; the pane, tabs and hotkeys were tested today. Also tested: a pane docks on the right only; there is no left placement. A pane stayed about 56 columns wide whatever columns the mod asked for.
D. Dialogs and alerts
Things that ask you something, or try to get your attention.
C12 is stuck and needs you
- 1Toast. Top right in fullscreen, gone after about 4 seconds.👁 view🖱 click dismisses, hover holds
- 2Lines above the question dialog. The only place a mod can add to the dialog.👁 view only
- QThe question dialog is Claude Code's: you answer with a digit, the arrows and Enter, or a click.
- 3The question text inside it can be rewritten by a mod (tested: the round number).
- 4Notice under the dialog. One line of context; gone when you answer.👁 view only
- 5A held tool call. The mod pauses a command and asks you, in the same dialog style.⌨ digit or Enter🖱 click
- ✕The permission prompt cannot be drawn on or changed. A mod can only approve or refuse the call before it appears.
- 6Desktop notification, outside the terminal, for when you have walked away. Needs a notification channel set first; today it returned "no-channel".👁 view
Pictures: which element draws where
| Element | Terminal | Inside herdr or tmux | Desktop app |
|---|---|---|---|
| Raster (coloured cells: maps, heat maps, sparklines) | Yes | Yes (tested: the lesgoo map) | No; draw text instead |
| Image (real pictures) | Only kitty or Ghostty | No; the alt text shows | No |
| Svg | No | No | Yes |
Click or keyboard
What you can do with each thing a mod draws. Mouse clicks work only where the terminal reports clicks: Claude Code's fullscreen mode, and the Desktop app. In the classic renderer, everything is keyboard only.
| Element | Mouse | Keyboard | Notes |
|---|---|---|---|
| Button | A click presses it. Tested: plain and bracketed buttons, in the band and in a pane. | Its hotkey (one digit or one lowercase letter); Enter when it has focus; Tab to reach it | In the terminal, bracketed buttons like [ Save ] don't show their hotkey; plain buttons show it as 1: Save. A mod can restyle a button on hover. Tested: a hover style turned the box blue under the pointer and cleared when the pointer left. A click on a pane button does not give the pane the keyboard: typing its hotkey right after did nothing. |
| Band button with a digit hotkey | Click | Type the digit into the empty prompt and pause. No focus needed. | The fastest input there is. Tested today. |
| Input (text field) | Click to focus. Tested: the typing then went into the field, not the prompt. | Type; Enter submits (tested) | While the field has focus, every printable key goes into it, so hotkeys stop working. |
| Select (dropdown) | A click opens it. A click on an option does nothing: it neither moves the highlight nor picks. Pick with the arrows and Enter. | Enter opens it, the arrows move, Enter picks | Closed, it shows Label: value ▾. Tested: after a keyboard pick, clicks on the dropdown stopped opening it until another control (the text field) was clicked. |
| Link | Ctrl-click or Cmd-click opens it (the terminal's own behaviour) | — | In Markdown, a plain click can run the mod's own action instead. Tested: only a click on the URL text, shown as (https://…), ran the action. A click on the link's own words did nothing. |
| Toast | A click dismisses it (tested); hovering holds it | — | It disappears by itself after about 4 seconds. |
| Text you selected with the mouse | Select as usual | A mod command or button can then read it | A mod can read your selection and write to the clipboard ($.ui.copy). That gives clean copies without broken spacing. |
| Client region | Full pointer input: down, move, up, drag | Keys while it has focus | For custom widgets and animation. It lives in a separate file of the mod. |
| Status line, hint tail, spinner, log line, line under the answer, footer label | — | — | View only. |
| Slash commands a mod adds | — | Type /name; autocomplete lists them | A command registered as "immediate" runs even while Claude is working, without starting a turn. A name allows letters, digits, _ and - only, no colon. So the playground mods use a mods- prefix, such as /mods-mrs. |
Keys while a pane or the band has the keyboard
| Key | What it does |
|---|---|
| Tab · Up · Down | Go to the next control. Up and Down scroll instead when the drawing is taller than its space. |
| Enter | Press the button, submit the field, or pick in the dropdown |
| A hotkey | Press that button (not while a text field has focus) |
| Page Up · Page Down · Home · End | Scroll |
| Ctrl+X then an arrow | Resize the pane |
| Ctrl+X then X | Close the pane |
| Esc | Give the keyboard back to the prompt (and close the pane, if the mod set that) |
A mod cannot rebind Tab or the arrow keys, cannot read raw keys, and cannot press another mod's buttons.
Mouse clicks, tested 2026-10-14 in Claude Code 2.1.299, fullscreen mode, inside a browser terminal (xterm.js) driven from Chrome. Every click was checked against the mod's own log. Working: both band buttons, both pane buttons, the hover style, focusing the text field, opening the dropdown, the link's URL text, the toast, and the pane's ✕ (the mod saw the close as made by a person). Not working: clicking a dropdown option, and clicking a link's words. Not tested: herdr and the Desktop app, dragging, the wheel, and the band's [-]. Your own settings use "tui":"default", which has no mouse tracking, so none of these clicks reach a mod in your normal sessions.
Proven today in the playground
Seven mods now run together in the browser terminal: first what each one does, then what the cache measurements showed. After that come the morning's tests with the showcase and idle-probe mods, their edge cases, and the gotchas found while building. I added the colours; the text is what the terminal drew, or what the mod's source draws.
Top picks
The ten ideas I'd build first, in order. The first three replace machinery you already run: the Stop hook, the herdr relay script and the status-line context estimate. The rest answer the pains that came up most in your sessions.
All ideas
Pick an area. Each idea gives what it does, where it draws, how you use it, what it reads, and the pain from your sessions it answers.
Mods other people built
A Sonnet agent is still searching the web for published mods. This tab fills in when its report arrives.
Where a mod is the wrong tool
Things a mod should not try, or cannot do.