DEV Community: Haruki Nakada

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

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

How common is this?

$.process.run doesn't use a shell

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

Detecting the OS

Opening a file with the default app

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

Fix: launch PowerShell's SoundPlayer

Five things to watch

The weight of launching PowerShell

Small Windows differences

Summary

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

File layout

1. plugin.json

2. hooks/hooks.json

3. hooks/register.tsx

The three arguments

Branch on e.surface

Use theme color names

4. Validate what you wrote

5. Load it

Try it in the terminal

Try it in the desktop app

Check that it loaded

Get the type definitions

Rules for writing $

Next

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

What a mod does

What mods can do

Where mods can draw

Where mods run

What the desktop app needs

Components available in the desktop app

How to turn mods off

Look at real mods

How this series is organized

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

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

Branch on `e.surface`

Rules for writing `$`