Skip to content
Claude Code Mods

Custom themes: recolor the Desktop app and add a backdrop with a mod

A mod can now recolor the Claude Desktop app's Code tab and draw a backdrop behind the chat. What $.theme does, which versions it needs and how to undo it.

Published . Checked against Claude Code v2.1.329. This site is unofficial; the sources under each section are Anthropic's own pages.

Themes are mods

A theme is a mod that calls $.theme.set. It can pass colors, which recolor the Desktop app's Code tab in light and dark mode, and a backdrop, which the Desktop or mobile app draws behind the conversation. $.theme.clear() takes both off. Claude Code in the terminal keeps its own colors and draws no backdrop.

The pieces arrived across three releases:

  • v2.1.319: $.theme.set and $.theme.clear replace $.ui.backdrop, which this release removed.
  • v2.1.323: the backdrop takes a scene name and a top-level overrideColorScheme. Before it, the fields were id and backdrop.colorScheme.
  • v2.1.324: colors in the Code tab. Check the Claude Code version shown in the Code tab, not your terminal's.

Source: Draw in the interface with a mod (opens in a new tab), Mods reference (opens in a new tab)

Ask Claude for a colors mod

The quickest way is to describe the colors. Start a local session in the Code tab and enter a prompt such as make a mod that makes the app cream in light mode and dark brown in dark mode. Claude writes the mod's files and asks you about them and about hot reloading. The Code tab changes color when the mod loads, and you can tell Claude what to adjust.

Source: Draw in the interface with a mod (opens in a new tab)

Write a colors mod yourself

makeColors builds a full theme from a few hex colors. Ask Claude in the Code tab to copy make-colors.js and make-colors.d.ts from its plugin-authoring skill into your mod's hooks/ folder, add the usual plugin.json and hooks.json, then set the colors when the session starts. This is the docs' paper example:

~/.claude/skills/paper/hooks/register.js
import { makeColors } from './make-colors.js'

const { theme } = makeColors({
  label: 'Paper',
  // surface-0 is the background, text-primary is the main text, and text-muted is the faint text
  light: {
    gray: { anchors: { 'surface-0': '#efe6d3', 'text-primary': '#2a241d', 'text-muted': '#6a5f50' } },
  },
  dark: {
    gray: { anchors: { 'surface-0': '#1f1a15', 'text-primary': '#f0e7d7', 'text-muted': '#aca08d' } },
  },
})

export function register(on) {
  on('session.start', async ($, e, next) => {
    await $.theme.set({ colors: theme })
    return next(e)
  })
}

A mod under ~/.claude/skills/ loads when a session starts, so start a new local session in the Code tab to see it. With these values the background is cream in light mode and dark brown in dark mode.

Source: Draw in the interface with a mod (opens in a new tab)

Put a backdrop behind the conversation

A backdrop takes two parts: a $.theme.set call that names a scene, and a ui.render hook on the Backdrop render site that draws it. Neither a reload of the mod nor --resume keeps the backdrop, so set it in session.start. This example from the docs needs v2.1.323 or later and adds a /plain command that takes the backdrop off:

hooks/register.js
export function register(on) {
  on('session.start', async ($, e, next) => {
    await $.theme.set({ backdrop: { scene: 'night-sky' }, overrideColorScheme: 'dark' })
    await $.command.register({ name: 'plain', description: 'Take the backdrop off' })
    return next(e)
  })
  on('ui.render', { component: 'Backdrop' }, async ($, e, next) => {
    // This hook runs for every mod's backdrop, and another mod can use the same scene
    if (e.props.plugin !== $.plugin.name || e.props.scene !== 'night-sky') return next(e)
    const { Box, Text } = $.ui.resolve(e)
    return Box({ backgroundColor: 'blue', children: [Text({ children: ['Night sky'] })] })
  })
  on('command.run', { command: 'plain' }, async ($) => {
    const cleared = await $.theme.clear()
    return { text: cleared.reason }
  })
}

$.theme.set resolves with isDrawn: true when a connected Desktop or mobile app says it draws backdrops. Otherwise isDrawn is false and reason says why, which is what you get in the terminal.

Source: Draw in the interface with a mod (opens in a new tab), Mods reference (opens in a new tab)

One theme per session

A session has one theme. Any mod that calls $.theme.set replaces the backdrop and colors another mod set, and any mod that calls $.theme.clear() removes them, whichever mod set them. So pass colors and backdrop in the same call, run one theme mod at a time, and call $.theme.clear() only when the user asks for it.

Note

Updating an older mod: change $.ui.backdrop({ id: 'your-backdrop' }) to a $.theme.set call, and $.ui.backdrop(undefined) to $.theme.clear().

Source: Draw in the interface with a mod (opens in a new tab)

When colors don't show, and how to remove them

If a mod's colors don't appear in the Code tab, the docs list these causes:

  • An old Desktop app: update it, restart it and start a new local session in the Code tab.
  • The mod didn't load: compare its files and paths with the example above.
  • A refused theme: ask Claude to run the mod's makeColors call, and fix any entry in its problems list that starts with Desktop won't paint this theme.
  • Another mod called $.theme.set or $.theme.clear() after yours.

To remove a theme, turn the mod off first, because a mod that is still on can set its colors again: move its folder out of ~/.claude/skills/ or out of the mods folder Claude wrote it to, or disable its plugin from Manage plugins. Then start a new local session. If colors stay, open Settings from the Code tab, search for code appearance and select Remove colors.

Source: Draw in the interface with a mod (opens in a new tab)