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

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.

1. Change the value in the button's onPress
2. Ask for a redraw with $.ui.invalidate('ui.render')
3. 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.