← Claude Code Hub
Oct 7, 2026 · 6 min read ✦ Tip #221

Claude Code mods: draw your own UI inside Claude Code

A mod is JavaScript or TypeScript that runs inside Claude Code: it draws a line above the prompt or a pane, and can hold a tool call. Claude writes one from a single sentence.

A Claude Code mod draws the craft bar above the prompt: the work, its phase, a square per slice and the agent running now

TL;DR On 2.1.287 or later, ask for make a mod that shows the current git branch above the prompt, pick Turn them on (auto and bypass modes don't even ask), and it loads when the turn ends. Before installing someone else's, claude plugin validate lists what it touches.

Update, November 10, 2026: The question in step 3 now reads Turn on the mods Claude writes in this session?, with Turn them on and Not now. Since v2.1.321, in auto and bypassPermissions modes the mod turns on without asking, and in dontAsk it doesn't load.

A mod is a Claude Code plugin written in JavaScript or TypeScript whose functions run inside Claude Code. It can draw a line above the prompt or a pane beside the transcript, add a command that answers on the spot without spending a Claude turn, and hold, rewrite or answer a tool call before it runs. It works in the terminal from 2.1.287 and in the Desktop Code tab from 2.1.286.

If you use Claude Code as your harness and like to tinker, this is the dream: with TypeScript you can add buttons, panes, views and animations, and catch commands and subagents as they happen. The docs are long and on the abstract side, and their examples are deliberately small. So I tried it on something real: a status bar for craft, my development plugin.

Where a mod fits

What it is Where it runs
Settings hook A shell command, HTTP request or prompt fired on an event Outside Claude Code
Skill A markdown file of instructions In what Claude reads
MCP A server that gives Claude tools Outside, as a separate process or service
Mod Functions Claude Code calls on each event Inside Claude Code

Because it lives inside, each of a mod's hooks decides what happens to its event: it observes and lets it through, rewrites it before it continues, or answers it so the usual behavior never runs. For the other mechanisms, the 6 extension points sorts them by the question each one answers.

Ask Claude for a mod

1. Check your version

claude --version

2. Describe it in one sentence

make a mod that shows the current git branch above the prompt

Claude works from the built-in plugin-authoring skill (you can load it yourself with /plugin-authoring) and writes the mod under ~/.claude/dev-mods/<session-id>/. In default and acceptEdits modes it asks you to approve each file, since ~/.claude is a protected path.

3. Turn it on

When Claude saves the first file, Claude Code asks Turn on the mods Claude writes in this session?. Pick Turn them on: the mod loads when the turn ends, reloads each time Claude changes it, and your answer lasts for the whole session, including after you resume it. Not now loads nothing; the files stay put and the mod loads the next time that session starts. You'll find it in /plugin, on the Installed tab.

Whether you get the question depends on the permission mode:

  • In auto and bypassPermissions there's no question: since 2.1.321 the mod turns on by itself when the turn ends.
  • In dontAsk, and in a claude -p run outside those two modes, it doesn't load, because nobody is there to approve it.

4. Keep it

The session's folder gets cleaned up over time. Copy the mod out and load it wherever you want:

claude --plugin-dir ~/mods/git-branch

This flow is interactive and I didn't capture it here: the steps come from the official guide, and the wording of the question from the Claude Code binary itself.

A real one: the craft bar

Craft runs subagents that build in phases, and I leave them working. I wanted to see at a glance whether anything was moving, without asking Claude and without spending a turn. The design is one line above the prompt with the work, its phase, a square per slice and the agent running right now:

craft retry · implement · ■■■▣▣□ 3/6 · ⠋ draw 2:14 +1

It's five hooks in a single file, hooks/register.ts, declared in hooks/hooks.json as { "modules": ["./register.ts"] }:

  • command.run on /^craft:/ records the phase when I run /craft:implement, then lets the skill run as usual.
  • agent.spawn on /^craft:/ adds the agent to the line, and turn.complete with the same agentId removes it and marks its slice as built.
  • ui.render on AbovePrompt draws the line with Box and Text, on top of whatever Claude Code already draws there.
  • /craft:bar off is answered by the mod itself, with no Claude turn, and the choice is kept in $.store for every session.
  • session.end clears the state when the session closes.
on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
  const line = pieces(state, await $.clock.now())
  if (e.props.hasSurvey || line.length === 0 || (await hidden($))) return next(e)
  const { Box, Text } = $.ui.resolve(e)
  const below = await next(e)
  const texts = line.map(piece => Text({ ...STYLES[piece.tone], children: piece.text }))
  return Box({ flexDirection: 'column', children: [Box({ key: BAR, children: Text({ children: texts }) }), below] })
})

The first live try, on 2.1.292, showed this while craft built four slices:

craft gamma · implement · □□□□ 0/4

The work, the phase, the four squares, /craft:bar off and on, and staying out of the way of Claude Code's survey all passed. Three things failed: every agent showed up as build, because the slice name sits further down its prompt; two agents spawned in the same tenth of a second overwrote each other, so the +1 never appeared; and the squares never turned green, because the first version matched them by their check command and craft rewrites those commands. The takeaway: events tell you for certain when a subagent starts and ends; what's inside its prompt, they don't. The bar still lives on a working branch, not in the published craft.

Before you install someone else's

A mod isn't sandboxed: it runs with your permissions, can read your secrets, sees every prompt and can approve tool calls for you. claude plugin validate lists the events it handles and the calls it makes, without running it. This is the real output for the craft bar:

❯ ./register.ts hooks: command.run{command=/"^craft:"/}, agent.spawn{subagentType=/"^craft:"/}, turn.complete, session.end, ui.render{component=AbovePrompt}
❯ ./register.ts calls: $.clock.every (via tick), $.clock.now, $.fs.list (via folders), $.fs.read (via readSlices), $.session.root (via folders, readSlices), $.store.get (via hidden), $.store.set (via answerBar), $.ui.invalidate, $.ui.resolve

✔ Validation passed

Two more things: in the VS Code extension's chat panel and in claude -p, hooks run but nothing gets drawn. And /diff, which you may already use, is a built-in mod: cc-plugin-diff. Another one, off by default, is You should know: a second agent that reviews your session while Claude works and flags what you might miss. And easel draws charts in the terminal, when you ask or on its own under your metrics MCPs.

Official docs: Mods overview

Found this useful? See more of wmedia.es in your Google results.

Add wmedia.es as a preferred source on Google
FREE GUIDE

Approve less, but better.

Ten minutes in, you're hitting yes without reading. That's not review, that's prayer. A 10-page guide with the five levers in order of risk.

  • 1. Rules the first match wins
  • 2. Mode a dial, not a switch
  • 3. Auto mode a classifier approves for you
  • 4. Sandbox a fence the OS puts up
  • 5. Bypass only inside a container
Are you a professional Web developer?

You'll receive the guide by email · You join the Gravitas newsletter · Unsubscribe anytime

of 10
#

Wmedia · 10 pages
FREE GUIDE · 10 pages · 5 levers

Approve less, but better.

Ten minutes in, you're hitting yes without reading. That's not review, that's prayer. A 10-page guide with the five levers in order of risk.

Are you a professional Web developer? · Unsubscribe anytime

Tired of approving permissions without reading?