DEV Community: Haruki Nakada

Claude Code mods in the desktop app: a one-page summary and what to recheck after updates

Haruki Nakada — Wed, 14 Oct 2026 13:09:37 +0000

This series covered the minimum steps for using Claude Code mods in the desktop app's Code tab, and answers to the problems people search for most. Here is the whole thing on one page.

Everything on one page

Question	Answer	Part
What are mods?	JS/TS functions that run inside Claude Code. They draw panes and bands and can intercept tool calls	1
Where do they render?	Only in the terminal and the desktop Code tab. Desktop from 2.1.286	1
How to build one	Three files: `plugin.json`, `hooks.json`, `register.tsx`. Branch on `e.surface` per surface	2
Panes	Open with `$.ui.open({ id })`, draw in the `ui.render` `Pane` while checking `e.requestId`	3
Bands, status line, toasts	`AbovePrompt`, `$.ui.status`, `$.ui.toast`	4
Nothing renders	Static check, runtime environment, component rules. Search the debug log for the mod's name	5
Broken on desktop	Auto-open from 144 columns, colors by theme name, Svg needs width and height, don't set `isInteractive`	6
Doesn't work on Windows	`$.process` launches programs Windows doesn't have. Replace with the API. Sound via SoundPlayer	7
Asking from a button does nothing	The press only queues; the clock sends	8
Distributing and installing	Add `marketplace.json` and push. `/plugin install name@marketplace-name`	9
Is it safe?	No sandbox. Read `validate` output and the four APIs, pin with `sha`	10

When the version goes up

Mods are a brand-new feature, and each version adds events, APIs and components. The behavior in this series was checked on 2.1.286 to 2.1.288. When the version goes up, recheck in this order:

Run /status in the desktop app to see the bundled Claude Code version
Read the type definitions written out when loading with --plugin-dir (.claude-plugin/types/). They're more accurate than the web pages
The workarounds (Windows sound, sending $.prompt.submit from a clock) become unnecessary once the core fixes them. Try the straightforward way first

See real mods

To see real mods, the modscode reviewed gallery lists mods written for the desktop app that run on Windows and passed the review, each with a UI preview and code. To search them from inside a conversation with Claude, connect the modscode MCP connector.

This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.

Is a Claude Code mod safe? How to check an unsandboxed mod before installing it

Haruki Nakada — Tue, 13 Oct 2026 13:09:45 +0000

A Claude Code mod is code that runs without a sandbox, with your permissions. It can read and write files, read environment variables (including API keys), launch programs and use the network. Before installing, list the APIs the mod uses with claude plugin validate, check in the code why it uses $.http, $.env, $.process and $.fs, and install it pinned to the sha of the commit you read.

What a mod can reach

The "decide whether to trust a mod" section of the official overview lists what an installed mod can do:

Capability	Details
Runs on your PC as you	Reads and writes files anywhere your user can, launches programs, uses the network
Reads secrets	Environment variables and settings files, including any API keys stored there
Sees the session	Every prompt you send and every tool call Claude makes
Changes the session	Rewrites prompts or tool calls, sends prompts as if typed by a person, messages other sessions
Acts without asking	Approves tool calls before you're asked
Uses your quota	Calls the model with your plan or API key

And mods are not sandboxed. Even with Claude Code's sandbox turned on, only the Bash commands Claude runs are isolated; processes started by a mod run outside it.

One thing is protected: a mod can't redraw the permission prompt. It's built so a mod can't disguise what the confirmation screen shows. However, a mod can answer "allow" before the prompt is ever shown (the "acts without asking" row above).

Why reading the code is enough

For a mod's code to touch files, the network or processes, it must go through the $ API. Inside a hook there's no fetch, no process and no require (part 5). And at load time, Claude Code statically checks the source and only allows $ calls written out in full.

So if you search for $.http, $.process, $.fs and $.env, you'll find every place the mod touches the outside. The official docs also say this is why Claude Code can list "what it does" before installing a mod.

1. List it with `claude plugin validate`

Clone the mod's repo and run the check from a shell. It doesn't launch anything, so the mod's code doesn't run during validation.

git clone https://github.com/someone/some-mod
claude plugin validate .\some-mod

Look at these lines in the output:

Line	What it tells you
`hooks:`	Which events it intercepts (`tool.call`, `tool.check`, `prompt.submit` and so on)
`calls:`	Which APIs it calls (`$.http.fetch`, `$.process.run` and so on)
`env reads:`, `env writes:`	Which environment variables it reads or writes
`state reads:`, `state writes:`	`$.state` values

If something looks off, read that line in the code.

2. Check the reason for four APIs

Most mods are one or two files of a few hundred lines. Even if you can't read all of it, search for these four and confirm "why is this needed" for each, and you can spot almost anything dangerous.

Search for	What to check
`$.http`	Is the destination host written in the code? What is being sent?
`$.env`	Which names does it read? Where does it pass the values?
`$.process`	Is the program name written in the code? Does it launch a shell (`sh`, `bash`, `powershell.exe`, `cmd.exe`) or `curl`?
`$.fs`	Where does it read and write? Does it read keys or config under your home folder?

The ones to be most wary of are mods that both read ($.fs, $.env) and send ($.http), because that shape can ship what it read to the outside. That's fine if the reason is clear, but if a mod that only shows a clock in the band reads environment variables and talks to the network, don't install it.

Other things worth checking:

Does it intercept tool.check or tool.call and return "allow"? That lets tools through without confirmation
Where does it call $.prompt.submit from? It can start turns without the person knowing (part 8)
Does it call $.model? That uses your quota
Is there code you can't read? Minified one-liners, eval, new Function, base64 blobs, import() with a computed path. If you can't read it, don't install it

3. Pin the version

What you read is the contents of one commit. A marketplace that points to the author's latest changes every time the author pushes. With auto-update on, code you haven't read comes in.

Auto-update is off by default for marketplaces you added yourself. Keep it off for unfamiliar authors
To pin to the commit you read, make your own marketplace and put that commit in the source sha (part 9)
When updating, read the diff from the version you read last, then bump the sha

4. Keep watching after install

If an installed mod worries you, disable it in the Installed tab of /plugin. To stop everything and see what happens, start with --safe-mode (part 1).

In an organization, admins can set policies such as "load only the organization's mods" (allowManagedModsOnly). You can also write a mod that refuses to load other mods (the plugin.register event). Details are on the official "Manage mods for your organization" page.

The 13 checks in the modscode review

The modscode review applies the checks above mechanically to 1,383 public mods. Of the 1,383 public mods on GitHub it read, 49 were written for the desktop app, work on Windows, and passed the review (as of 2026-10-06).

There are 13 checks, grouped into 4 by idea:

Group	Checks	Related part
Usable on desktop	Written for the desktop app / installable from the desktop app (listed in `marketplace.json`) / works on Windows	Parts 6, 7, 9
Readable	Entry points read (every module named by `hooks.json`) / parseable / self-contained code (no external packages or `require`) / readable (no minified code, `eval`, or encoded blobs)	End of step 2 above
Outside access is visible	Calls are visible (network and program launches written in place) / fixed destinations (the https host for fetch is in the code) / no shell	Table in step 2 above
Keeps secrets	Doesn't send what it reads (doesn't both read and send) / no keys (no API keys or private keys in the source) / open license	Step 2 above and the rules for copying code

In numbers, 167 don't work on Windows and 269 can't be installed from marketplace.json. "Written for the desktop app" is especially strict; many mods written for the terminal drop out there.

However, as the modscode pages themselves say, this review does not guarantee that any mod is safe. It only checks whether the code is in a machine-readable shape and whether its outside access is visible. You still need to read before installing. Use the review as a pointer to where to start reading.

Summary

Mods run without a sandbox, with your permissions
Use claude plugin validate to get hooks:, calls: and env reads:
Search for $.http, $.env, $.process and $.fs and confirm the reasons. Be especially careful with mods that both read and send
Pin to the sha of the commit you read, keep auto-update off, and read the diff before bumping

If you need to explain what mods are to someone else, What are mods is a short summary.

This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.

How to distribute and install a Claude Code mod with marketplace.json and /plugin install

Haruki Nakada — Mon, 12 Oct 2026 17:50:43 +0000

A mod is a plugin, so it's distributed and installed the same way as any plugin. To distribute, put .claude-plugin/marketplace.json in the repo and push. To install, add the marketplace with /plugin marketplace add owner/repo, then install with /plugin install name@marketplace-name. In the desktop app you can also install from + next to the prompt → Plugins → Add plugin (official install page).

Terms

Term	Meaning
Plugin	A single folder holding mods, skills, commands, MCP servers and so on. A mod is one kind
Marketplace	A JSON file (`marketplace.json`) listing plugins and where to fetch each one. Usually kept in a GitHub repo
Plugin id	`name@marketplace-name`. Used to install, remove and configure

Distributing: add marketplace.json

The simplest setup is to make the mod's own repo the marketplace. Put marketplace.json next to plugin.json.

hello-band/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
└── hooks/
    ├── hooks.json
    └── register.tsx

{
  "name": "hello-tools",
  "owner": { "name": "Your Name" },
  "description": "A mod that shows one line above the prompt",
  "plugins": [
    { "name": "hello-band", "source": "./" }
  ]
}

name, owner and plugins are required. owner requires name
Each entry in plugins requires name and source
source: "./" points to the repo root (one level above .claude-plugin/)
Match the entry's name to the name in plugin.json (the official docs say to)
The marketplace name uses letters, digits, ., _ and -, and starts with a letter or digit. Official names like claude-plugins-official, names that look official, and names containing non-ASCII letters are rejected

Validate before pushing.

claude plugin validate .

It's public the moment the files are pushed. There's no application process. If the repo is private, it becomes a private marketplace that only people who can clone it can install from.

Listing several mods in one repo

As your mods grow, you can create one repo for the marketplace and line them up under plugins/.

{
  "name": "hello-tools",
  "owner": { "name": "Your Name" },
  "plugins": [
    { "name": "hello-band", "source": "./plugins/hello-band" },
    { "name": "hello-pane", "source": "./plugins/hello-pane" }
  ]
}

To list a mod that lives in another repo, make source an object.

{
  "name": "hello-band",
  "source": {
    "source": "github",
    "repo": "your-name/hello-band",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Pinning a version

A github source can have ref (a branch or tag) and sha (a 40-character lowercase commit). With sha, only that commit's contents are distributed. Even if the author changes things later, users won't get them until the marketplace's sha is updated.

When you list someone else's mod in your marketplace, pinning to the sha of the commit you read is the safe choice (part 10).

Bumping the version

If you put a version in plugin.json, bump it every time you change something. If you push without bumping, users' claude plugin update says "already up to date" and they keep the old copy. For git marketplaces you can also omit version, in which case the commit SHA becomes the version.

Installing: with commands

Type these inside a Claude Code session.

/plugin marketplace add your-name/hello-band
/plugin install hello-band@hello-tools

your-name/hello-band on the first line is the GitHub owner/repo. What follows @ on the second line is the name in marketplace.json, not the repo name. Mixing these up and getting "not found" is very common.

Add # like owner/repo#v1.2.0 to pin to a branch or tag
For non-GitHub hosts use an https://...git URL; for a local folder use a path starting with ./
Both in one step: /plugin install hello-band --marketplace your-name/hello-band (Claude Code 2.1.275 and later)

/plugin install inside a session doesn't install immediately; it opens a details screen. There you review the contents (commands, hooks, MCP servers and so on) and pick a scope.

Scope	Applies to	Settings file written
User	All your projects	`~/.claude/settings.json`
Project	Everyone working in this repo	`.claude/settings.json` (committed)
Local	Only you, only this repo	`.claude/settings.local.json`

You can do the same from a shell.

claude plugin marketplace add your-name/hello-band
claude plugin install hello-band@hello-tools

When installed from a shell, type /reload-plugins in an open session to load it.

Installing: from the desktop app UI

The official install page describes these steps for the desktop app's Code tab (local or SSH sessions):

Press + next to the prompt and choose Plugins → Add plugin
A list of marketplace plugins opens; pick the one to install
Choose the scope (user, project or local)

To disable or remove later, use + → Plugins → Manage plugins. This screen isn't available in cloud sessions.

However, the steps to add a marketplace itself from the desktop app UI aren't on the official page, so that is not verified. The list above shows only plugins from marketplaces you've already added. The terminal, local desktop sessions and VS Code read the same settings files, so if you run claude plugin marketplace add in a shell, it should show up in the desktop list as well. Whether typing /plugin marketplace add in the Code tab prompt works the same way on desktop is also not verified.

After installing, open a new session in the desktop app and check whether the band or pane appears.

Updating

By the user: claude plugin update hello-band@hello-tools, or Update now in the Installed tab of /plugin
Auto-update: off by default for marketplaces you added yourself. You can turn it on per marketplace in the Marketplaces tab of /plugin

With auto-update on, whatever the author pushes keeps coming in. Mods are code that runs without a sandbox, so for marketplaces from unfamiliar authors it's safer to leave it off and read before updating (part 10).

Don't rename

Don't change the name of a published mod. Users' installs are recorded as name@marketplace-name, so renaming makes the mod disappear for people who installed it. If you really must rename, map the old name to the new one with renames in marketplace.json. If you only want to change the display name, use displayName.

Distributing to Windows users

A source that uses command (a folder produced by a local command) with mode: "link" can't be installed on Windows (official marketplace reference). If you have Windows users, use copy. With ordinary github or ./ sources you don't need to worry about this.

Finding mods you can install

Among public mods on GitHub, fewer than you'd expect are listed in their repo's own marketplace.json and installable with the steps in this article. In the modscode review, 269 of 1,383 didn't meet this condition (as of 2026-10-06).

All 49 mods in the modscode reviewed gallery can be installed from their repo's marketplace.json, and each page shows the install commands. If you want to search reviewed mods inside a conversation with Claude, or have Claude read a mod's UI structure and review results, you can also connect the modscode MCP connector to Claude (read-only, no login).

This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.

Claude Code mod button calling $.prompt.submit doesn't work the first time (where to call it)

Haruki Nakada — Sun, 11 Oct 2026 13:09:41 +0000

If you call $.prompt.submit inside a mod button's onPress or inside a command, Claude sometimes doesn't start. In the versions I tested, a $.prompt.submit called inside the press event was thrown away when the event ended, with no error. Have the button only store what to send in a variable, and send it from a clock created in session.start. That works reliably.

Versions checked: Claude Code 2.1.286 to 2.1.288 (October 2026, desktop Code tab).

Symptom

Put a button in a mod's panel, and when pressed, send a request to Claude. It's the first thing you want to build.

t.Button({
  key: 'ask',
  label: 'Decide now',
  onPress: async () => { await $.prompt.submit({ text: 'Check the market and decide' }) },
})

Pressing it doesn't start Claude. Sometimes pressing twice works, which made the cause slow to find. Sending from inside a command (/xxx) behaved the same.

What the official docs say

On the official API page, $.prompt.submit sits in the section about starting a turn from background work. Three key points:

$.prompt.submit({ text }) waits until the session is idle, then starts a new turn
It resolves when the turn starts, so don't await it inside a handler that runs while Claude is working
Claude reads the text after a line saying your mod sent it. With asUser: true, it's sent as the person's own words without that line

The example given also sends from inside a clock ($.clock.every) created in session.start.

What I observed

The official text goes as far as "it waits, so don't await it". It does not say that a call inside an event gets thrown away. What follows is what I saw in my versions.

A $.prompt.submit called inside a button's onPress or a command hook disappeared when the event ended, and no turn started
No exception, and nothing reached .catch
Moving the same call into a clock made it work every time

Why it gets dropped is not verified. But together with the fact that the official example sends from a clock, I believe the right place to start a turn is a clock, not an event.

Fix: the press only queues, the clock sends

The button only puts "what to send" into a variable, and a 1-second clock finds it and sends it.

let toSend = null

// Button: just queue it
onPress: () => {
  toSend = 'Check the market and decide'
  $.ui.toast('Sending...')
}

// Create the clock once in session.start
on('session.start', async ($, e, next) => {
  $.clock.every(1_000, () => frame($))
  return next(e)
})

async function frame($) {
  if (!toSend) return
  const text = toSend
  toSend = null            // clear before sending (so the next tick doesn't send it twice)
  await $.prompt.submit({ text })
}

There's up to a 1-second delay between pressing and sending, but you barely notice it. Show "Sending..." in a toast or the panel right after the press so there's no doubt whether the press registered.

frame takes $, so put it at the top level of the same file. If you pass $ to a function created inside a hook or to a function in another file, the static check fails and the whole mod doesn't load (part 5).

For the same reason, start external processes from the clock

Work that starts an external process with $.process.run (opening a file in the default app, playing a sound) was also sometimes killed when the event ended if started inside the event. Route that to the same clock too. Processes started from the clock keep running beyond the event.

Remember "any work that outlives a single event starts from the session.start clock" and you won't get lost. The official docs also describe running work that spans more than one event on a clock started in session.start.

Keep only one clock

If you create a clock per feature, you hit a different trap. In my versions, writing settings ($.config.set) reloaded the plugin and ran register again, so clocks multiplied and the same work ran twice.

The official explanation says that on reload the previous clocks stop and the new load creates its own. It may be fixed in newer versions, but which version changed it is not verified. To be safe either way, I follow two rules:

Only one place in the mod owns the clock
Stop the previous clock before creating a new one

let timer = null

function startClock($) {
  try { timer?.cancel?.() } catch { /* do nothing if there isn't one */ }
  timer = $.clock.every(1_000, () => frame($))
}

The clocks returned by $.clock.every and $.clock.after have cancel() (official).

Re-rendering too fast recreates the button you're pressing

There was one more cause of "I pressed it but nothing happened". If you re-render the panel every second, the button can be recreated mid-press.

Only animated graphics every second
The normal view every 5 seconds

Splitting it like this fixed it. Calling $.ui.invalidate('ui.render') only when a value changes cuts wasted re-renders in the first place.

How to word what you send

Text sent with $.prompt.submit looks to Claude like "a request that came from a mod".

Normally don't set asUser. Claude reads it knowing it came from a mod
Use asUser: true only when you want it treated the same as something a person typed

A mod that asks Claude something with one button can also start turns without the person knowing. From the installer's side, where a mod calls $.prompt.submit from is one of the things worth checking (part 10).

Summary

Symptom	Cause	Fix
Asking from a button or command doesn't start Claude	`$.prompt.submit` inside the event was dropped (in my versions)	Queue in a variable, send from the `session.start` clock
Opened apps or sounds get cut off	Processes are killed when the event ends	Start them from the clock as well
The same work runs twice	Clocks are created in more than one place	One clock, stop it before creating a new one
The press feels registered but nothing happens	Re-rendering recreated the button	Re-render every 5 seconds

You can read real mods that ask Claude from a button, with their code, in the modscode reviewed gallery. Comparing how they create clocks and place buttons shows the patterns clearly.

This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.

Claude Code mod works in the terminal but breaks in the desktop app (pane not opening, Svg shrinking, flicker)

Haruki Nakada — Sat, 10 Oct 2026 16:31:41 +0000

When a mod that works in the terminal is opened in the desktop app, these five problems come up most: a pane opened at startup does not appear (opens without a user action need 144 columns), hex colors are unreadable in the light theme, Raster is not drawn, Svg shrinks to 300x150, and an isInteractive Svg flashes black every second. All of them can be fixed by branching on e.surface.

Tested with Claude Code 2.1.286 to 2.1.288 (October 2026, Windows, 150% scaling).

1. A pane opened at startup does not appear

Even if you call $.ui.open(...) in session.start, the pane may not appear on the desktop. The official interface page has rules for this:

An open backed by a user action (a command, a pressed button, a sent prompt) is placed regardless of width
An open without one (from session.start, a timer, or turn.start) needs 144 columns. A pane the user has opened themselves at least once needs 110 columns
When there is not enough room, $.ui.open returns { isPlaced: false, reason } and waits

The desktop side panel is narrow, so assume an open at startup may not be placed. I chose to reopen on the first prompt submission.

let opened = false

on('prompt.submit', async ($, e, next) => {
  const kind = e.origin?.kind
  if (!opened && (kind === 'composer' || kind === 'bridge')) {
    opened = true
    await $.ui.open({ id: PANE, title: 'My Mod' })
  }
  return next(e)
})

The values of e.origin.kind (composer, bridge) are what I saw in the type definitions for my version. On other versions, check the type definitions (.claude-plugin/types/ from Part 2).

Other options are to open the pane from a command or a band button, or to show a toast saying it can be opened instead of opening it on your own (Part 4).

Also, the desktop app I tested (2.19675) accepted rows and columns in $.ui.open but did not use them for the pane size. Draw on the assumption that the size is whatever width the user dragged it to.

2. Hex colors are unreadable in the light theme

In the terminal you can paint with color: '#7FD1A6'. On the desktop, hard-coded colors can stand out oddly or become unreadable in the light theme. Pass theme color names instead and they render correctly in both light and dark.

Meaning	Name
Up, success	`success`
Down, removal	`diffRemovedWord`
Warning	`warning`
Dim text	`dimColor: true`

The official reference for Text also says color is a theme key or a color like 'red'. If you keep hex values in your feature code and put a single wrapper that swaps them only on the desktop, you do not have to rewrite anything.

const THEMED = { '#7fd1a6': 'success', '#f2837f': 'diffRemovedWord', '#d9b26a': 'warning' }

function themeProps(props) {
  const out = { ...props }
  const v = typeof out.color === 'string' ? out.color.toLowerCase() : null
  if (v && THEMED[v]) out.color = THEMED[v]
  return out
}

3. `Raster` is not drawn, or the surface is detected wrong

A mod that draws a grid of colored cells with Raster in the terminal cannot draw it on the desktop. Raster and Image are terminal-only, and Svg is desktop-only.

If you try to detect the surface by checking whether a component exists, like if (t.Raster), you will get it wrong, because the table from $.ui.resolve(e) contains every component name. Always branch on e.surface ('terminal' or 'desktop').

if (e.surface === 'terminal') {
  return Raster({ key: 'grid', columns, rows, cells })
}
return Svg({ source: svgOf(grid), alt: 'Heatmap', width: w, height: h })

4. `Svg` shrinks to a small box

If you do not pass width and height to Svg, the frame stays at the default 300x150 (CSS pixels), and the picture shrinks to fit inside it. This happens even if the SVG itself has a viewBox.

t.Svg({ source: svg, alt: 'Chart', width: w, height: h })

The catch is that the pane size reaches the mod only in columns and rows (bodyColumns, bodyRows), not in CSS pixels. On my screen, one pane cell measured 7.6 wide and 18.6 tall (CSS pixels).

const CELL = { w: 7.6, h: 18.6 }
const w = Math.floor(cols * CELL.w)
const h = Math.floor(rows * CELL.h)

These values may differ on other setups, so make the drawing robust to a wrong estimate:

Give the root <svg> width="100%" height="100%" and a viewBox, so it keeps its aspect ratio and fits even if the frame differs from your estimate
Estimate a little small and fill the leftover space with the background color of the outer Box

source is limited to 131,072 characters (official reference). 200 candlesticks already take tens of thousands of characters. Round coordinates to one decimal place and group identical fills into classes.

5. An `isInteractive` Svg flashes black every second

An Svg with isInteractive: true is drawn inside a frame (an iframe), so :hover and CSS animations work. However, every time the content changes, the whole frame reloads and goes black while it does. A view redrawn every second flashes every second. I also tried stacking two frames and loading in the back one, but that did not fix it.

The conclusion: do not use isInteractive; use a single image Svg.

An image Svg keeps showing the old picture until the new one is ready, so it does not flash
CSS @keyframes written inside the SVG still run in an image Svg

What you lose is roughly :hover and <title> tooltips.

Animations restart from the beginning on every redraw

Even with an image Svg, changed content becomes a new image, and CSS animations start over. If you write the animation delay as "event time minus the time the SVG was built," the animation continues from the middle even after a rebuild, because a negative delay means "already partway through."

const madeAt = Date.now()
const delay = (eventAt) => `${((eventAt - madeAt) / 1000).toFixed(2)}s`

svg += `<text class="type" style="animation-delay:${delay(caption.at)}">${esc(caption.text)}</text>`

Things that change every second (elapsed time and so on) should stay out of the SVG and go in a Text row above it. That reduces how often the SVG itself is rebuilt.

Colors go wrong when two are side by side

If you reference <linearGradient id="g"> with url(#g), the second of two side-by-side images points at the first one's gradient. Give each one a unique prefix (id="s3-g").

Two more things you will hit

You cannot style buttons, and clicks on top of the picture do not register

The desktop Button has a fixed look; you cannot set its color, shape, or size. HTML cannot go into a pane either. I tried drawing the whole screen as an Svg and layering a Client on top to catch where the user clicked, but clicks on a Client layered over the picture did not work (2.1.286 to 2.1.288). The layout I settled on is: visuals in an Svg picture, and standard Buttons placed above or below the picture for anything clickable. Writing plain: false makes the button undrawable on the desktop, so only use true or omit it.

Layouts break in the narrow pane

The usual way a pane opens on the desktop is the narrow side pane next to the conversation (about 58 columns, 440px). Layouts tuned on a wide screen broke here: charts collapsed into thin columns, axis labels overlapped, and legends were cut off.

If placing items side by side would leave a chart under 60 columns, switch to stacking them vertically
Drop legend entries that do not fit, starting from the end

Open it once in the narrow pane before you polish anything. That is the fastest route.

Checking an Svg without opening the app

Opening the desktop app every time is slow, so I put the SVG in an HTML file and screenshot it with headless Edge. The trick is to shoot at the usual panel width (about 440px).

& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --headless=new --screenshot=out.png --window-size=440,600 file:///C:/work/stage.html

Summary

Problem	Fix
Startup pane does not appear	Open from a user action (automatic opens need 144 columns)
Colors are unreadable	Pass theme color names
`Raster` is not drawn	Branch on `e.surface`, use `Svg` on the desktop
`Svg` shrinks	Always pass `width` and `height` (1 cell is about 7.6x18.6)
`Svg` flashes	Do not use `isInteractive`
Buttons cannot be styled	Visuals in Svg, clicks on standard Buttons
Layout breaks	Make the 58-column narrow pane your pass line

You can tell whether a mod written for the terminal will draw on the desktop by checking its code for an e.surface branch before installing. The modscode gallery lists only mods that explicitly target the desktop app, with reproductions of how they look in the narrow desktop panel.

This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.

Claude Code mod not loading or rendering with no error? Where to look

Haruki Nakada — Fri, 09 Oct 2026 14:14:25 +0000

When a mod does nothing and shows no error, the cause almost always falls into one of three groups: (1) it failed static analysis and the whole mod was not loaded, (2) it used something the hook runtime does not have and the hook was skipped, or (3) the tree it returned broke the component rules, so Claude Code drew its own UI instead. Start with claude plugin validate, then search the debug log for the mod's name.

Why mods fail silently

The official troubleshooting page opens with this: when a mod fails to load or a hook fails, Claude Code skips it and keeps the session going. A broken mod looks the same as a mod that does nothing.

That design keeps Claude Code itself from going down, but it leaves the author with few clues. So decide in advance where to look.

Quick reference

Symptom	Where to look	Common causes
No command, no band, nothing	1. Static analysis	Put `$` in a variable, passed `$` to a function in another file, dynamic import, an event not in this version
Loaded, but some hooks do not run	2. Runtime	Used `process` or `setTimeout`, ran over 10 seconds
The band or panel shows the default UI	3. Component rules	Passed `undefined` or `false`, missing a required field, a component not available on that surface

First step: `claude plugin validate`

claude plugin validate .\my-mod

Without starting a session, this runs the same static analysis Claude Code runs at load time. It catches misspelled events, broken manifests, and unreadable modules.

Passes but no hooks: line appears: hooks/hooks.json has no modules, or it is misspelled
An event you registered is missing from hooks:: Claude Code will not call that function either

1. It fails static analysis

At load time, the module source is analyzed, and if it fails, the whole plugin is not loaded.

Code	Fix
`const s = $.store; s.get(k)`	Write `$.store.get(k)` in full
`const { store } = $`	Do not destructure
`helper($)` (where `helper` is in another file)	You can pass `$` only to top-level functions in the same file
Passing `$` to a function created inside a hook	Move the function to the top level
`on(eventName, ...)` (name in a variable)	Write the event name as a string literal
Declaring another variable named `on` inside `register`	Rename it
`await import('./x.mjs')`	Dynamic import is not allowed. Use a top-level `import` statement
Importing a file outside the plugin	Copy it into the plugin. The only outside import allowed is `claude-code`
`require(...)`	Use ES module `import`

Three things are easy to miss:

The analysis also follows on() calls in files you import. I had a leftover test on() in a shared helper, and the mod failed
Registering the same event and matcher pair twice fails. When several features want AbovePrompt, register once and dispatch inside
Registering an event that does not exist in that version prevents the whole mod from loading

That last one hits the desktop app in particular. The desktop app bundles its own Claude Code, which can be older than your terminal version. I had a mod that registered ui.fault (the event for Client component failures). It worked in the terminal but vanished entirely on the desktop (bundled 2.1.286). The official reference now says ui.fault requires v2.1.289 or later. When you use a new event, compare the version note in the reference with the version shown by /status on the desktop.

2. It uses something the hook runtime does not have

Hooks run in an environment that is neither Node nor a browser. The official API page also says there are no Node.js APIs and no timers like setTimeout.

Not available: process, setTimeout, setInterval, Buffer, the DOM, require
Available: URL, TextEncoder/TextDecoder, AbortController, crypto (including crypto.subtle), atob/btoa, structuredClone, performance

What you want	Use instead
Wait	`$.clock.sleep(ms)`
Run once later	`$.clock.after(ms, fn)`
Run periodically	`$.clock.every(ms, fn)` (create it in `session.start`)
Current time	`await $.clock.now()`
Files, network, processes	`$.fs`, `$.http`, `$.process`

In your own code, you just rewrite these. The trouble comes when you copy in an npm package: it reads process.env the moment it loads, throws, and the whole mod silently disappears. Putting local stand-ins at the top of that package's file, scoped to that file only, got it through.

const process = { env: {} }
const setTimeout = () => 0

Time limits

The other issue is time. These are the limits from the official reference that people hit most often.

Thing	Limit
A hook's own run time per call (waiting inside `next` and APIs does not count; `$.clock.sleep` does)	10 seconds
A `.catch` handler	1 second
All `session.end` hooks	1.5 seconds combined (configurable)
`$.process.run`	30 seconds by default, 10 minutes max

Hooks that run longer than 10 seconds are skipped. If you do heavy work in a guard that blocks tool calls (tool.check), the guard itself gets bypassed, so be careful.

3. The returned tree breaks the component rules

If the tree returned from ui.render breaks the rules, Claude Code draws its own UI without any error. Your band just disappears and the default comes back, which makes this the hardest one to notice.

Code	Result
Passing a field whose value is `undefined`	May be treated as invalid
`autoFocus: false`, `focus: false`	Throws. Pass only `true`, or omit it
`plain: false` on a `Button`	Cannot be drawn on the desktop. Use `true` or omit it
`Svg` without `source` or `alt`	Not drawn (both are required)
`undefined` in `Client` props	Invalid (JSON values only)
A component not available on that surface (`Raster` on the desktop, etc.)	Invalid
Props a component does not accept (including typos)	Invalid

Conditional fields naturally let undefined slip in, so I wrap the component factories in one place and strip those values.

// Do not pass fields that have no value to components
function strip(raw) {
  const out = {}
  for (const k of Object.keys(raw)) {
    const make = raw[k]
    out[k] = typeof make === 'function'
      ? (props = {}) => make(Object.fromEntries(Object.entries(props).filter(([, v]) => v !== undefined)))
      : make
  }
  return out
}

const t = strip($.ui.resolve(e))
t.Button({ key: 'pdf', label: 'PDF', plain: true, dimColor: busy ? true : undefined, onPress })

Writing dimColor: busy ? true : undefined avoids ever passing false.

Find the one line that gives the reason

When a module fails to load, a hook is skipped, or a tree is rejected, Claude Code writes one line containing the mod's name. Where it goes depends on the session (official troubleshooting page).

Session	Where the line appears
Interactive session loaded with `--plugin-dir`	A faint line in the conversation
Normal session with a mod installed from a marketplace	Debug log only
`claude -p` with `--plugin-dir`	Standard error

In other words, when an installed mod is silent, no amount of looking at the conversation will show anything. Capture a debug log.

claude --debug-file .\mod-debug.log --plugin-dir .\my-mod

Watch the log in another window (PowerShell example).

Get-Content .\mod-debug.log -Wait | Select-String my-mod

These are the strings to look for:

Log text	Meaning
`hooks module my-mod@inline loaded ... events: ...`	Loaded, with the list of registered events
`hooks module my-mod ... not loaded:`	Rejected by settings or policy. The reason follows the colon
`hooks module did not load:`	Top-level code threw. File and line are shown
`hook skipped:`	A hook threw, timed out, or returned the wrong shape
`ui.render (Pane) refused:` / `a hook returned a tree that does not validate`	The tree broke the component rules. Reason included
`it crashed the hooks worker`	The mod was removed, for example because of a loop that never yields

A line like ui.render (Pane) refused: Text prop "bogusProp" is not allowed; the engine drew its own tells you exactly which prop on which component is wrong. Problems in group 3, component rules, are almost always solved in one look at this line.

To write your own markers, use $.ui.log('got here', { to: 'debug' }) to write to the log.

Getting a log from the desktop app

The desktop app cannot take launch flags, so the approach above does not work as is. How to capture a debug log from the desktop app is not described on the official pages, so it is not verified. My routine is to load the same mod in the terminal with --debug-file, find the reason line, fix it, and then check in the desktop app. However, things that fail only on the desktop, like an event missing from that version, do not reproduce in the terminal, so check the desktop version with /status first.

Can mods load at all?

Before blaming your mod, mods may be turned off by configuration. Run claude plugin test in a folder with no mod to see the state.

Output	Meaning
`no hooks module to load`	Mods can load (there is just nothing to test in this folder)
`hooks modules are turned off here`	Turned off by `disableAllHooks` or an organization policy
`hooks modules are turned off in this process`	Turned off remotely by Anthropic

Other causes of "nothing loads at all" include not having answered the trust prompt for a newly opened folder, and starting with --safe-mode or --bare.

Summary

Run static analysis with claude plugin validate
Check for process, setTimeout, and the 10-second limit
Check for undefined, false, required fields, and components not available on that surface
If still stuck, search the debug log for the mod's name

To see how other mods are written so they pass static analysis, read them in the modscode reviewed list. Every mod listed there is code that claude plugin validate can read.

This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.

How to show a line above the prompt in Claude Code with a mod (band, status line, toast)

Haruki Nakada — Thu, 08 Oct 2026 13:09:24 +0000

To always show a line right above the prompt, handle ui.render with { component: 'AbovePrompt' } and return a tree (the band). For a single line of text below the prompt, use $.ui.status(text). For a notification that disappears after a few seconds, use $.ui.toast(text). The last two need no render hook and can be called from anywhere in one line.

How they differ

Thing	How to show it	How long it stays	Good for
Band	Return a tree from `ui.render` for `AbovePrompt`	Until you stop returning it	Values you always want to see: price, remaining quota, state. Buttons allowed
Status line	`$.ui.status(text)`	Until you change it	One-line results of background work
Toast	`$.ui.toast(text)`	4 seconds by default	"Done" notifications
Faint line in the conversation	`$.ui.log(text)`	Stays (Claude does not read it)	A short note you want on record

The band (the strip above the prompt)

The band is the strip right above the prompt input, and all mods share one band.

let price = '—'

export function register(on) {
  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
    const { Box, Text } = $.ui.resolve(e)
    return Box({
      flexDirection: 'row',
      columnGap: 2,
      children: [
        Text({ bold: true, children: ['BTC'] }),
        Text({ color: 'success', children: [price] }),
      ],
    })
  })
}

Do not erase other mods' bands

When you return a tree for the band, it replaces whatever mods that run after yours drew in the band. To keep theirs, put the result of await next(e) inside your own Box.

on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
  const { Box, Text } = $.ui.resolve(e)
  const theirs = await next(e)
  return Box({
    flexDirection: 'column',
    children: [Text({ children: [`BTC ${price}`] }), theirs],
  })
})

If you do not want to show anything, return next(e).

Register once per mod

Registering the same event and matcher pair (ui.render with AbovePrompt) twice in one mod makes it fail to load. When your mod grows and you want both a "clock band" and a "price band," register once and lay out the sections inside it.

Reading the width

The band width arrives as e.props.bodyColumns (in columns). When things do not fit, it looked cleaner to drop whole low-priority sections than to cut text midway. A leftover count like "+3" or a truncated price looks half-finished.

Desktop text is proportional and narrow, so more characters fit than the column count suggests. If you lay out strictly by column count, you drop sections while there is still room on the right. I treat the desktop width as 1.5 times the column count.

const raw = e.props?.bodyColumns ?? e.viewport?.columns ?? 100
const cols = e.surface === 'terminal' ? raw : Math.round(raw * 1.5)

1.5 is a value I tuned on my own setup, not an official number. It may change with the font or zoom level, so leave some margin.

Band buttons and number keys

You can put a Button in the band too. According to the official reference, if a band button has a numeric hotkey, typing just that digit into an empty prompt and waiting a moment presses it. That lets you put actions like "press 1 to open" in the band.

Ask for a redraw after changing a value

As with the pane in Part 3, call $.ui.invalidate('ui.render') after changing a value. For values fetched from outside, such as a price, create a timer in session.start and refetch periodically.

on('session.start', async ($, e, next) => {
  $.clock.every(15_000, async () => {
    try {
      const r = await $.http.fetch('https://api.example.com/price')
      if (r.ok) price = JSON.parse(r.text).price
    } catch {
      // If the fetch fails, keep the previous value
    }
    $.ui.invalidate('ui.render')
  })
  return next(e)
})

There is no setInterval inside hooks. Use $.clock.every and $.clock.after for timers (Part 5).

The status line

$.ui.status('checks: 3 passing')

According to the official docs, in the terminal this shows one line below the prompt and stays until you change it. It is prefixed with ⚠ and the mod's name, like ⚠ my-mod: checks: 3 passing.

Since it needs no render hook, it is the easiest way to show results from inside a timer. The official example runs gh pr checks every minute and puts the result in the status line.

on('session.start', async ($, e, next) => {
  $.clock.every(60_000, async () => {
    const r = await $.process.run(['gh', 'pr', 'checks', '--json', 'state'])
    $.ui.status('checks: ' + (r.exitCode === 0 ? 'ok' : 'ng'))
  })
  return next(e)
})

Where and how the status line appears in the desktop app is not described on the official pages, so it is not verified. For values you always want visible on the desktop, the band, which is reliably drawn, is the safer place.

Toasts

$.ui.toast('PDF exported')

In the terminal, a toast appears at the top right with the mod's name and disappears after a few seconds. The default is 4 seconds, and you can change it with { timeoutMs }.

$.ui.toast('Backtest finished', { timeoutMs: 8000 })

There are two main uses:

Notifying that background work has finished
Standing in when you cannot open a pane on your own. The official docs also say to use a toast when you want to signal something without opening a pane

If you open a pane with holdToasts: true, toasts wait and do not appear until that pane is closed. Use it when you do not want notifications piling up while someone is reading.

Where toasts appear on screen in the desktop app is not described on the official pages, so it is not verified.

Leave a faint line in the conversation

$.ui.log('build finished')

This leaves a faint line in the conversation like ● my-mod: build finished. Claude does not read this line. To tell Claude something, use the text in a command's return value, or $.prompt.submit (Part 8).

If you pass a second argument, $.ui.log('message', { to: 'debug' }), it is written to the debug log instead of the conversation. Part 5 uses this for debugging.

Add a word to the spinner

Another easy target is the spinner line shown while Claude is working. The very first official example is a mod that appends the number of tool calls after the spinner.

on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
  return next({ ...e, props: { ...e.props, suffix: ` · tool calls: ${calls}…` } })
})

Passing a copy with modified props to next keeps Claude Code's spinner behavior and just adds text. Spinner is a site drawn in both the terminal and the desktop app.

Which to choose

A value you always want to see: the band
Results of background work: the status line (its desktop appearance is not verified, so if it matters, show it in the band too)
A "done" notification: a toast
Something to look at in detail, or with many actions: the pane from Part 3

The modscode gallery has many real mods that combine bands and toasts. Mods that show remaining usage or context size in the band are especially common, and they are good for comparing how each one drops band sections.

The following articles in this series answer common problems, starting with the most frequent one: nothing is drawn and there is no error.

This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.

How to add a side pane to Claude Code with a mod using $.ui.open and ui.render

Haruki Nakada — Wed, 07 Oct 2026 13:09:15 +0000

To show a pane from a mod, you do two things: open it with $.ui.open({ id }), and return its contents from ui.render with { component: 'Pane' }. Opening alone draws nothing. After you open it, Claude Code calls ui.render to ask what to draw in that pane, and you return a tree (nested components) only when e.requestId matches your id.

What a pane is

A pane is your own panel next to the conversation. According to the official docs, it is:

a side panel next to the conversation on a wide screen
a frame above the prompt when space is tight

If you open several panes, you switch between them with tabs labeled by title.

A minimal pane

This pane opens with /hello-pane and has a button that increments a counter. Keep the three-file layout from Part 2 and replace only register.tsx.

// The pane's name. Used as the marker when opening and drawing
const PANE = 'hello-pane'

// The value the pane draws
let count = 0

export function register(on) {
  // At session start, add the command and read the previously saved count
  on('session.start', async ($, e, next) => {
    const saved = await $.store.get('count')
    if (typeof saved === 'number') count = saved
    await $.command.register({ name: 'hello-pane', description: 'Open the hello-pane panel' })
    return next(e)
  })

  // Open with /hello-pane
  on('command.run', { command: 'hello-pane' }, async ($) => {
    await $.ui.open({ id: PANE, title: 'Hello', focus: true, closeOnEscape: true })
    // Show nothing in the conversation
    return {}
  })

  // Draw the pane
  on('ui.render', { component: 'Pane' }, async ($, e, next) => {
    // Leave other mods' panes alone
    if (e.requestId !== PANE) return next(e)

    const { Box, Text, Button } = $.ui.resolve(e)

    return Box({
      flexDirection: 'column',
      children: [
        Text({ bold: true, children: ['Hello pane'] }),
        Box({
          flexDirection: 'row',
          columnGap: 2,
          children: [
            Button({
              key: 'more',
              label: 'Add 1',
              hotkey: 'a',
              onPress: async () => {
                count += 1
                $.ui.invalidate('ui.render')
                // Keep it for the next session
                await $.store.set('count', count)
              },
            }),
            Text({ children: [`Count: ${count}`] }),
          ],
        }),
      ],
    })
  })
}

This is the hello-tabs example from the official interface page, reduced to a single screen.

Opening: `$.ui.open`

id is required. Everything else is optional.

Field	Meaning
`id`	The pane's name. Used as `e.requestId` when drawing and in `$.ui.close({ id })` when closing
`title`	Tab label when there are several panes
`focus`	Send keyboard input to the pane
`closeOnEscape`	Close with Esc
`holdToasts`	Hold toasts until the pane is closed
`rows`	Preferred height when shown above the prompt
`columns`	Preferred width when shown next to the conversation

focus, closeOnEscape, and holdToasts accept only true. Writing focus: false throws. To set one conditionally, include or omit the whole field.

const pane = { id: PANE, title: 'Hello' }
await $.ui.open(items.length > 0 ? { ...pane, focus: true } : pane)

A pane id can use letters, digits, _, and -, up to 64 characters.

Open from a command

The example opens the pane from the /hello-pane command. Opening in response to a user action (a command, a button press, a sent prompt) is the norm. An open with no user action behind it, for example from session.start or a timer, is only placed when the screen is wide enough. On the desktop, this is almost always the cause of "I started it but the pane did not appear." Part 6 covers it in detail.

If you want the command to open the pane even while Claude is working, add immediate: true to $.command.register. Without it, the command waits until the turn ends.

Drawing: `ui.render` and `Pane`

ui.render is called many times, once per place to draw. The second argument { component: 'Pane' } (the matcher) narrows it to panes, and then e.requestId tells you whether it is your pane. If it is not your pane, return next(e) to pass it on. Forget this and you will blank out other mods' panes.

The redraw cycle

A pane is a snapshot of "the last tree ui.render returned." Changing a value alone does not change the screen.

Change the value in the button's onPress
Ask for a redraw with $.ui.invalidate('ui.render')
Claude Code calls ui.render again and rebuilds the tree with the new value

This cycle is the same for every component. Claude Code redraws on its own only when the site's props or the screen width change. It does not redraw on a timer by itself. To redraw on a timer, create $.clock.every(1000, () => $.ui.invalidate('ui.render')) in session.start.

Redraws are throttled to 10 per second. Faster requests are merged into one.

Fit the width

The pane width arrives as e.props.bodyColumns (in columns). When the pane is next to the conversation (e.props.placement === 'dock'), the height arrives as e.props.scroll.bodyRows. If the tree is taller than the pane, the whole thing scrolls.

The narrow side pane you usually open on the desktop was about 58 columns (about 440px). Layouts tuned on a wide screen break here. If you make "no overlapping or clipped text at this width" your pass line from the start, you will not have to rebuild later.

Keeping values: three places

Place	How long it lasts	Good for
A top-level variable in the file	Until the mod reloads (every save during development)	Display state you can afford to lose
`$.state`	Until the session ends, or until `/clear`, `/resume`, `/branch`	Values the renderer reads that should survive a reload
`$.store`	Until the mod deletes it (saved as JSON per plugin)	Settings, history, things you want next time

The example keeps the count in $.store, so it survives closing and reopening Claude Code. $.store is limited to 4 MiB per plugin, and every session on the same PC shares one store. If two sessions read the same key and write it back, the later write overwrites the earlier one. For values written from several sessions, split the keys or re-read right before writing.

What you can draw on the desktop

A desktop pane can hold Box, Text, Button, Input, Select, Markdown, Svg, and others. HTML is not supported. You cannot put a web page into the panel as is, so draw rich visuals with Svg.

if (e.surface === 'desktop') {
  const { Svg } = $.ui.resolve(e)
  const w = 400
  const h = 120
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}" width="100%" height="100%">
    <rect x="0" y="0" width="${w * Math.min(count, 10) / 10}" height="${h}" fill="#4a90d9"/>
  </svg>`
  return Svg({ source: svg, alt: `Count ${count}`, width: w, height: h })
}

Svg needs both source and alt, and without width and height it shrinks to a small box. Part 6 explains why and how to fix it.

You cannot change how buttons look (color, shape, size). The most you can do is drop the brackets with plain: true and dim them with dimColor: true.

Keyboard

A pane receives keyboard input when it was opened with focus: true, when it is clicked, or after Ctrl+X followed by Tab. While it has focus, Tab moves to the next component, Enter presses, a button's hotkey (one digit or one lowercase letter) presses that button, and Esc returns to the prompt. On the desktop, the key is shown small next to the button label.

See real examples

Real mods that use panes can be read alongside reproductions of their UI in the modscode reviewed list. Seeing how they lay things out in the narrow desktop panel was the most useful part for me.

The next article in this series covers the band, status line, and toast, which are lighter-weight than a pane.

This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.

Why a Claude Code mod doesn't work on Windows: tail, date, open, osascript in $.process and silent sound

Haruki Nakada — Tue, 06 Oct 2026 14:06:52 +0000

Most mods written on Mac or Linux break on Windows because they use $.process to launch programs Windows doesn't have (tail, date, open, osascript, afplay, xdg-open and so on). $.process.run doesn't go through a shell, so cmd built-ins like start or dir can't be launched either. The other cause is sound: on Windows, $.audio.play plays nothing and still reports success.

Versions checked: Claude Code 2.1.284 to 2.1.288 (October 2026, Windows 11).

How common is this?

The modscode review read 1,383 public mods on GitHub and found 167 that use $.process to launch a program Windows doesn't have (as of 2026-10-06). That's roughly 1 in 8. Many still had Mac tool names left in them as-is.

`$.process.run` doesn't use a shell

The official API page says $.process.run takes an array of arguments and does not use a shell.

const r = await $.process.run(['git', 'status'])
// r is { exitCode, stdout, stderr }

Because there's no shell, this happens:

['tail', '-n', '20', 'log.txt']: Windows has no tail, so it can't start and the call rejects
['start', 'report.pdf']: start is a cmd built-in, not an executable, so it can't start
['ls'], ['cat', ...], ['date']: same, they don't exist (date is a cmd built-in and means something different anyway)
A single string like 'git status': pass an array instead

$.process.run rejects when the program can't start and when it times out (30 seconds by default). A non-zero exit code still resolves. If you don't wrap it in try/catch, the throw takes the whole hook down with it (part 5).

Programs Windows doesn't have, and what to use instead

The best fix is to not launch an external program at all and use the mods API instead. With the API you don't have to care about the OS.

Common on Mac/Linux	Used for	Replacement inside a mod
`date`	Current time	`await $.clock.now()` or `Date.now()`
`tail`, `cat`, `head`	Reading a file	Read with `$.fs.read(path)` and slice in JS
`ls`, `find`	Listing a folder	`$.fs.list(path)` (one level only, not recursive)
`test -f`	Checking existence	`$.fs.exists(path)`
`curl`	Network	`$.http.fetch(url, init)`
`osascript -e 'display notification'`, `notify-send`	Notifications	`$.ui.toast(text)`
`afplay`, `say`	Sound, speech	See the "Sound" section below
`open`, `xdg-open`	Open with the default app	On Windows only, PowerShell's `Start-Process` (below)
`pbcopy`	Clipboard	`$.ui.copy` (listed in the official API list; check the behavior in the type definitions)
`sh -c '...'`, `bash -c '...'`	One-line shell commands	Launch directly with an array, or replace with the API

Programs that ship an executable with the same name on Windows, like git or gh, work as-is, as long as they're on the PATH.

One more thing to watch: commands installed as .cmd files on Windows, like npm and npx. Whether a .cmd file can be launched directly without a shell isn't documented on the official pages, so this is not verified. If it doesn't work, launch it explicitly, e.g. ['cmd.exe', '/c', 'npm', ...].

Detecting the OS

There's no process inside a hook, so you can't use process.platform. I tell them apart by the shape of $.plugin.root (the plugin folder).

function isWindows($) {
  const root = String($.plugin.root ?? '')
  return /^[A-Za-z]:[\\/]/.test(root)   // starts with a drive letter
}

Opening a file with the default app

Instead of Mac's open report.pdf, launch PowerShell's Start-Process on Windows. Don't embed the path in the command string; pass it through an environment variable. A single ' or space in the path breaks it, and it also opens the door to injection.

async function openFile($, path) {
  if (isWindows($)) {
    await $.process.run(
      ['powershell.exe', '-NoProfile', '-NonInteractive', '-Command', 'Start-Process -FilePath $env:MOD_FILE'],
      { env: { MOD_FILE: path }, timeoutMs: 15_000 },
    )
    return
  }
  await $.process.run(['open', path])
}

Start the open from a clock, not inside the button-press event. Processes started inside an event were sometimes killed when the event ended (part 8).

No sound: `$.audio.play` succeeds silently on Windows

await $.audio.play({ asset: 'sounds/success.wav' })   // Windows: plays nothing

On Windows this plays nothing, throws nothing, and never reaches .catch. The Code tab in the desktop app runs the same executable, so it was silent there too.

In this version, the core plays sound only through globalThis.Audio or macOS afplay. On Windows it writes "no audio player on windows; not played" to the debug log and resolves as a success. From your code it never looks like a failure.

Fix: launch PowerShell's SoundPlayer

On Windows only, use $.process.run to start PowerShell and play the WAV with System.Media.SoundPlayer.

const PS_PLAY = '(New-Object System.Media.SoundPlayer $env:MOD_WAV).PlaySync()'
let soundBusy = false

async function playSound($, clip) {
  const root = String($.plugin.root ?? '')
  if (!/^[A-Za-z]:[\\/]/.test(root)) return $.audio.play(clip)
  if (soundBusy) return                           // drop sounds that arrive while one is playing
  soundBusy = true
  try {
    const wav = `${root.replace(/[\\/]+$/, '')}\\${clip.asset.replace(/\//g, '\\')}`
    await $.process.run(
      ['powershell.exe', '-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-Command', PS_PLAY],
      { env: { MOD_WAV: wav }, timeoutMs: 15_000 },
    )
  } catch {
    // don't stop the mod even if the sound fails
  } finally {
    soundBusy = false
  }
}

Five things to watch

Pass the path through an environment variable (same reason as above)
Use PCM WAV. SoundPlayer can't play MP3
Startup takes about 1 second. Drop sounds that arrive while one is playing so processes don't pile up
You can't change the volume (gain has no effect). Lower it in the WAV itself
Don't start it inside an event (button or command). Play it from a $.clock.every clock created in session.start and it plays to the end

To narrow down "no sound" problems, it helps to keep one command that plays a sound and reports the result as text. In practice, almost every "no sound" case was either the PC being muted or this path difference. Once the core supports sound on Windows, this workaround becomes unnecessary. When the version goes up, try $.audio.play first.

The weight of launching PowerShell

So far the Windows workarounds have used PowerShell. But PowerShell is a shell that can do anything. When a mod launches a shell, a reader has to check the actual command string to know whether it's safe.

The modscode review also has "doesn't use a shell" as a check (the program name is written in the code and isn't a shell). The sound workaround above trips that check.

For a mod you publish, think in this order:

If the API can do it, use the API (time, files, notifications, network)
Launch an external program only when it can't, keep the command string fixed, and pass changing values through environment variables
For "nice to have" features like sound, not playing it on Windows is also an option

Small Windows differences

Path separators: relative paths passed to $.fs are resolved from the session's working folder. When you build paths yourself, accept both \ and /
CLAUDE_CODE_PLUGIN_DIRS: when listing multiple folders, Windows separates them with ; (Mac and Linux use :)
WSL: in the desktop app's WSL sessions, plugins themselves aren't available, so mods don't run (part 1)

Summary

Symptom	Cause	Fix
A feature silently stops	`tail`, `date`, `open`, `osascript` don't exist on Windows	Replace with the mods API
`start` can't open files	`$.process.run` doesn't go through a shell	Call `powershell.exe` `Start-Process` explicitly
No sound (no exception)	`$.audio.play` succeeds silently on Windows	PowerShell SoundPlayer
Opened apps or sounds get cut off	Processes are killed when the event ends	Start them from a clock

To find out whether a mod works on Windows before installing it, search its code for $.process and look at the program names it launches. The 49 mods in the modscode reviewed gallery are only those whose code was checked to not launch programs missing on Windows.

This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.

How to make a Claude Code mod with three files that work in the desktop app

Haruki Nakada — Tue, 06 Oct 2026 14:06:48 +0000

You can build a Claude Code mod with just three files: .claude-plugin/plugin.json, hooks/hooks.json, and hooks/register.tsx. No Node.js and no build step. Claude Code loads .js, .ts, and .tsx files directly. To draw differently in the desktop app and the terminal, branch on e.surface === 'desktop'.

File layout

hello-band/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.tsx

File	Contents
`.claude-plugin/plugin.json`	The plugin's name and version. Nothing extra is needed for a mod
`hooks/hooks.json`	Lists one file to load under `modules`. This is what turns a plugin into a mod
`hooks/register.tsx`	The main code. Exports `register(on)`

The main file can be any of .js, .mjs, .cjs, .jsx, .ts, .mts, .cts, or .tsx, written as an ES module (see the Files table in the official reference). This series uses register.tsx, but register.js would have the same contents.

1. plugin.json

{
  "name": "hello-band",
  "version": "0.1.0",
  "description": "A minimal mod that shows one line above the prompt",
  "author": { "name": "Your Name" }
}

Pick a name you do not plan to change. People installing from a marketplace use hello-band@<marketplace-name>, so renaming makes it a different plugin (Part 9). Names starting with claude- look like Anthropic's own and are rejected by claude plugin validate.

2. hooks/hooks.json

{
  "modules": ["./register.tsx"]
}

The path is relative to hooks.json, and you list exactly one file. If modules is missing or misspelled, validation still passes but the plugin is not loaded as a mod (Part 5).

3. hooks/register.tsx

This mod shows one line in the strip above the prompt (the band), with different text in the desktop app and the terminal.

// How many prompts have been sent. Shared between hooks
let sent = 0

export function register(on) {
  // Count every time a prompt is sent
  on('prompt.submit', async ($, e, next) => {
    sent += 1
    // Ask for a redraw
    $.ui.invalidate('ui.render')
    return next(e)
  })

  // Draw the strip above the prompt
  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
    const { Box, Text } = $.ui.resolve(e)

    // Which app is drawing
    if (e.surface === 'desktop') {
      return Box({
        flexDirection: 'row',
        columnGap: 2,
        children: [
          Text({ color: 'success', children: ['Desktop'] }),
          Text({ dimColor: true, children: [`Sent ${sent}`] }),
        ],
      })
    }

    // Terminal
    return Text({ children: [`[terminal] sent: ${sent}`] })
  })
}

The three arguments

Every function you pass to on receives the same three arguments.

Argument	What it is
`$`	The mods API. Everything that touches the outside world (UI, files, network, processes) goes through it
`e`	The event payload. It is frozen, so to change it you pass a copy to `next`
`next`	The next step. Calling it runs the later mods and Claude Code's default behavior

return next(e) means "I only looked; pass it through unchanged." If you return a value without calling next, you have answered the event yourself.

Branch on `e.surface`

e.surface is either 'terminal' or 'desktop'. When you draw differently on desktop and terminal, always branch on this.

The component table returned by $.ui.resolve(e) contains the names of every component. Checking whether t.Svg exists does not tell you whether you are on the desktop. Svg exists only on the desktop and Raster only in the terminal, so if you get the surface wrong, nothing is drawn (Part 6).

Use theme color names

The example uses color: 'success' so the text is readable in both the light and dark desktop themes. A hard-coded hex value like '#7FD1A6' can become unreadable in the light theme (Part 6).

4. Validate what you wrote

Before launching, run the validator from your shell.

claude plugin validate .\hello-band

When it passes, you see lines like these in the output:

  ❯ ./register.tsx hooks: prompt.submit, ui.render{component=AbovePrompt}
  ❯ ./register.tsx calls: $.ui.invalidate, $.ui.resolve

✔ Validation passed

hooks: lists the events you registered, and calls: lists the APIs you use. If an event you meant to register is not under hooks:, Claude Code will not call that function either. A misspelled event name shows up as an error like "tool.calls" is not an event.

(The contents of calls: can differ slightly between versions. The two lines above show the shape.)

5. Load it

Try it in the terminal

In the terminal, --plugin-dir loads the mod for a single session. It reloads every time you save.

claude --plugin-dir .\hello-band

Try it in the desktop app

The desktop app cannot take flags at launch. The official docs describe these routes:

Turn a local folder into a marketplace and install from it. Add a folder containing marketplace.json by local path, for example claude plugin marketplace add .\my-mods, and install from there (Part 9). The terminal, local desktop sessions, and VS Code read the same settings file, so installing at user scope makes the desktop app load it too
The CLAUDE_CODE_PLUGIN_DIRS environment variable. The official reference describes it as folders loaded like --plugin-dir, for apps that cannot take the flag. On Windows, separate entries with ;. You can also put it in env in ~/.claude/settings.json
Have Claude write it. In a session, ask something like "make a mod that shows the current branch above the prompt." Claude writes it with the built-in plugin-authoring skill, and once you approve, it loads in the same session

For route 1, the official loading page says that for a marketplace added by local path, ./ sources are read in place without copying. After editing the source, changes apply at the start of the next session or with /reload-plugins, and you do not need to bump version. (A marketplace added from GitHub installs a copy, so changes do not arrive unless you bump version.)

Whether routes 2 and 3 behave the same way in the desktop app's Code tab is not stated on the official pages, so it is not verified.

If unsure, a safe split is: build with --plugin-dir in the terminal, do the final check in the desktop app. As Part 6 shows, some things break only on the desktop, so always open it there at the end.

Check that it loaded

In the terminal, open /plugin and you will see a faint line under the tabs like 1 mod active · hello-band. On the desktop, if the band shows up, it loaded. If it does not, see Part 5.

Get the type definitions

When you load with --plugin-dir or have Claude write the mod, Claude Code writes the type definitions (.d.ts) for that version into .claude-plugin/types/ inside the mod folder. They list the events, APIs, and components accurately for that version, so when in doubt, trust them over web pages (the official create page says the same).

Rules for writing `$`

One rule that even a minimal mod can trip over: at load time, Claude Code statically analyzes the source to check how you use $.

Write $, the namespace, and the function name in full, like $.store.get(k)
const ui = $.ui or const { store } = $ fails
You may pass $ only to functions declared at the top level of the same file
Write event names as string literals, like 'prompt.submit'

If this check fails, the whole mod is not loaded. Part 5 goes into detail.

You now have one line in the band. The next article in this series opens your own panel next to the conversation: a pane.

To see how other people write the three files, the modscode reviewed list shows each mod's code side by side with its UI.

This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.

What are Claude Code mods? What they can draw and where they run in the desktop app

Haruki Nakada — Tue, 06 Oct 2026 14:06:44 +0000

Claude Code mods are plugins made of JavaScript or TypeScript functions that run inside Claude Code. They can add your own panels to the screen and intercept Claude's tool calls. What they draw only shows up in the terminal claude and the Code tab of the desktop app. In the desktop app, mods work from Claude Code 2.1.286.

What a mod does

The official docs describe a mod as "a plugin that changes how Claude Code looks and behaves." Inside, it is a set of functions keyed by event, and Claude Code calls the matching function every time an event happens. Events are things like:

Claude is about to use a tool (Bash, Read, and so on)
The user sent a prompt
Claude Code is about to draw some part of the screen

The function that gets called can just observe the event, rewrite it, or answer it itself and stop the default behavior.

Claude Code already had "hooks" (shell commands written in settings.json). Mods differ in that they run as functions inside Claude Code. The official pages call a mod's function a "hook" and the settings-file kind a "settings hook."

What mods can do

A short summary of what the official overview lists:

Capability	Example
Draw your own UI	A pane next to the conversation, a band above the prompt. Tabs, buttons, and inputs are allowed
Redraw Claude Code's own UI	Tool call rows, the spinner, the question dialog
Intercept tool calls and requests	Stop a dangerous command and confirm, route to another model
Add your own commands	`/xxx` runs a function without using a Claude turn
Share values between hooks	One hook counts something, another draws it

The difference from existing tools is whether you can draw. Settings hooks, skills, and MCP servers cannot draw on the screen. Use a mod when you want a pane or a band, a skill when you keep pasting the same instructions, and an MCP server when you want to connect an external service.

Where mods can draw

The official docs call the places a mod can draw "render sites." This series covers four: the pane and the band, plus the status line and toast, which you show by just calling an API.

Name	Where it appears	Article in this series
Pane (`Pane`)	A panel next to the conversation. A frame above the prompt when space is tight	Part 3
Band (`AbovePrompt`)	The strip right above the prompt. Shared by all mods	Part 4
Status line (`$.ui.status`)	One line below the prompt	Part 4
Toast (`$.ui.toast`)	A small notification that disappears after a few seconds	Part 4

You can also redraw the spinner (Spinner), messages (UserMessage, AssistantMessage), tool rows (ToolUse and others), and the question dialog (AskUserQuestion). The only thing you cannot redraw is the permission prompt. That is so a mod cannot disguise what you are being asked to approve.

Where mods run

This is the most commonly misunderstood part. Where the functions (hooks) run and where the drawn UI is visible are two different things. Here is the official table:

Where Claude Code runs	Hooks run	Drawn UI is visible
Terminal `claude` (including terminals inside editors and JetBrains)	Yes	Yes
Desktop app Code tab (except WSL sessions)	Yes	Yes (except terminal-only components)
Desktop app WSL sessions	No (plugins are not available in WSL)	No
VS Code extension chat panel	Yes	No
`claude -p` and the Agent SDK	Yes	No
Remote Control from a phone or claude.ai	Yes (in the session on your local PC)	Only in the local terminal
Cloud sessions	Yes, if the plugin was delivered	No

In other words, mod panels do not appear in the mobile app or on claude.ai/code. They are not drawn in the VS Code extension either. If you build a mod that draws, assume it will be used in the terminal or the desktop app.

What the desktop app needs

According to the official docs, mods are enabled by default. The version requirement depends on where you run:

Terminal: Claude Code 2.1.287 or later. Check with claude --version
Desktop app: the app bundles its own Claude Code, and mods work from 2.1.286. Type /status in a local session in the Code tab and look at the version on the "Claude Code" line

The Claude Code inside the desktop app is separate from the one you installed for the terminal. Even if your terminal is up to date, the bundled desktop version may be older. When you use a new event or component, check first that the desktop version supports it. (Part 5 covers a case where registering an event that did not exist in that version made the whole mod disappear.)

Components available in the desktop app

Available UI components also differ by surface.

Component	Terminal	Desktop
`Box`, `Text`, `Button`, `Link`, `Code`, `Markdown`	Yes	Yes
`Input`, `Select`	Yes	Yes
`Svg` (SVG graphics)	No	Yes
`Client` (a region drawn by your own separate file)	Yes	Yes
`Raster` (a grid of colored cells), `Image`	Yes	No

On the desktop, Svg is the most expressive component. You can draw charts and diagrams across the whole panel. Conversely, a mod built in the terminal with Raster cannot draw on the desktop (Part 6).

How to turn mods off

The official docs give three levels:

Turn off one mod: disable or remove that plugin in the Installed tab of /plugin
Turn off everything for one session: start with --safe-mode (other settings are disabled too)
Turn off everything permanently: add "disableAllHooks": true to ~/.claude/settings.json

For the desktop app, the official install page says you can disable a plugin from the plugin management screen (+ → Plugins → Manage plugins). A later article in this series comes back to this.

Look at real mods

Seeing real mods is the fastest way to understand them. Anthropic keeps sample mods in claude-code/mods of anthropics/claude-code-playground (token-weather, blast-radius, replay-theater, and others). Claude Code's own /diff is built as a mod.

To browse public mods on GitHub in one place, you can use the modscode gallery. It read 1,383 public mods on GitHub and lists the 49 (as of 2026-10-06) that target the desktop app, run on Windows, and passed review, each with a reproduction of its actual UI. A gentler explanation of the mods concept is in What are mods. The official overview is at code.claude.com.

How this series is organized

Parts 2 to 4 are the minimum steps to build one mod for the desktop app. Parts 5 to 10 answer commonly searched problems. If you have a specific symptom, start with that part.

Part	Topic
2	The minimal three files, and branching on `e.surface`
3	Building a pane
4	Band, status line, toast
5	Nothing is drawn and there is no error
6	A mod built in the terminal breaks in the desktop app
7	It does not work on Windows
8	Asking Claude from a button does not work the first time
9	Distributing and installing through a marketplace
10	Telling whether a mod is safe

Tested with Claude Code 2.1.286 to 2.1.288 (October 2026, Windows 11). Mods are brand new and change from version to version. Anything I could not confirm in the official docs is marked "not verified."

This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.

DEV Community: Haruki Nakada

Claude Code mods in the desktop app: a one-page summary and what to recheck after updates

Everything on one page

When the version goes up

See real mods

Is a Claude Code mod safe? How to check an unsandboxed mod before installing it

What a mod can reach

Why reading the code is enough

1. List it with claude plugin validate

2. Check the reason for four APIs

3. Pin the version

4. Keep watching after install

The 13 checks in the modscode review

Summary

How to distribute and install a Claude Code mod with marketplace.json and /plugin install

Terms

Distributing: add marketplace.json

Listing several mods in one repo

Pinning a version

Bumping the version

Installing: with commands

Installing: from the desktop app UI

Updating

Don't rename

Distributing to Windows users

Finding mods you can install

Claude Code mod button calling $.prompt.submit doesn't work the first time (where to call it)

Symptom

What the official docs say

What I observed

Fix: the press only queues, the clock sends

For the same reason, start external processes from the clock

Keep only one clock

Re-rendering too fast recreates the button you're pressing

How to word what you send

Summary

Claude Code mod works in the terminal but breaks in the desktop app (pane not opening, Svg shrinking, flicker)

1. A pane opened at startup does not appear

2. Hex colors are unreadable in the light theme

3. Raster is not drawn, or the surface is detected wrong

4. Svg shrinks to a small box

5. An isInteractive Svg flashes black every second

Animations restart from the beginning on every redraw

Colors go wrong when two are side by side

Two more things you will hit

You cannot style buttons, and clicks on top of the picture do not register

Layouts break in the narrow pane

Checking an Svg without opening the app

Summary

Claude Code mod not loading or rendering with no error? Where to look

Why mods fail silently

Quick reference

First step: claude plugin validate

1. It fails static analysis

2. It uses something the hook runtime does not have

Time limits

3. The returned tree breaks the component rules

Find the one line that gives the reason

Getting a log from the desktop app

Can mods load at all?

Summary

How to show a line above the prompt in Claude Code with a mod (band, status line, toast)

How they differ

The band (the strip above the prompt)

Do not erase other mods' bands

Register once per mod

Reading the width

Band buttons and number keys

Ask for a redraw after changing a value

The status line

Toasts

Leave a faint line in the conversation

Add a word to the spinner

Which to choose

How to add a side pane to Claude Code with a mod using $.ui.open and ui.render

What a pane is

A minimal pane

Opening: $.ui.open

Open from a command

Drawing: ui.render and Pane

1. List it with `claude plugin validate`

3. `Raster` is not drawn, or the surface is detected wrong

4. `Svg` shrinks to a small box

5. An `isInteractive` Svg flashes black every second

First step: `claude plugin validate`

Opening: `$.ui.open`

Drawing: `ui.render` and `Pane`

`$.process.run` doesn't use a shell

No sound: `$.audio.play` succeeds silently on Windows

Branch on `e.surface`

Rules for writing `$`