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.

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

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

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.

$.ui.open id is required. Everything else is optional.

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.

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.

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.

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

onPress $.ui.invalidate('ui.render') 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.

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.

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.

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.

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.

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.