Claude Code desktop themes: how to install theme-examples, use /custom-theme and make your own mod
Short answer
Claude Code desktop themes are mods: small plugins that change the colors of the Code tab in the Claude desktop app and put an animated scene behind the chat. Update the desktop app, start a local session in the Code tab, run /plugin install theme-examples@claude-plugins-official, then type /custom-theme to pick one of 20 animated scenes. Or just tell Claude the look you want and it writes the mod for you. Themes work in local desktop sessions only for now (cloud sessions are "coming soon"), and the terminal keeps its own colors and draws no backdrop.
Anthropic's developer account (@ClaudeDevs on X) posted at 23:59 UTC on November 13 (4 AM in Dubai): "You can now build custom themes for Claude Code on desktop with mods! Change the colors, add an animated background, and make it your own." About six and a half hours later the post had 539,905 views, 11,498 likes and 4,551 bookmarks (X API, 10:30 Dubai time). That bookmark count is the tell: people saved it to try later. X counted about 190 posts a day mentioning Claude with themes or mods from November 11 to 13, then 861 in the first six and a half hours of November 14 (UTC).
The follow-up reply adds the fine print: update the desktop app first, themes work in local sessions today, cloud sessions are coming. Below is the whole setup in one place, from the docs and from the plugin's own files.
What are Claude Code desktop themes?
A theme is not a settings file. It is a mod, a plugin with hooks that Claude Code loads when a session starts. A theme mod calls one method, $.theme.set, and can pass two things to it:
- colors, which repaint the Code tab of the desktop app (light mode and dark mode can differ)
- a backdrop, a scene drawn behind the conversation, which can be animated SVG with frosted-glass panels over it
A session has one theme at a time. If two mods both call $.theme.set, the last one wins, and $.theme.clear() from any mod removes whatever theme is showing (Draw in the interface with a mod).
What do you need before you start?
| What | Requirement (Claude Code docs, Nov 14) |
|---|---|
| App | The Claude desktop app, Code tab, in a local session. The terminal draws no backdrop and keeps its own colors |
Backdrops ($.theme.set) | Claude Code v2.1.319 or later |
| The docs' backdrop example | v2.1.323 or later |
| Desktop colors | v2.1.324 or later in the Code tab |
| Mods in general | On by default. Desktop app from v2.1.286, terminal from v2.1.287 |
| Cloud sessions | Not yet. @ClaudeDevs says support is "coming soon" |
How to check your version: in a local session in the Code tab, type /status and read the Claude Code row (Mods overview). The desktop app ships its own copy of Claude Code, so updating the app is what moves this number, not updating the CLI on your machine.
How do you install the theme-examples plugin?
theme-examples is Anthropic's sample theme pack, version 0.4.3, Apache 2.0, listed in the claude-plugins-official marketplace under "design". Two ways in:
- By command. In a local Code tab session, run:
/plugin install theme-examples@claude-plugins-official - By clicking. Click the + next to the prompt box and choose Add plugins. If the menu shows Plugins instead, choose it, then Browse plugins, and search for theme-examples (desktop docs).
If the plugin list is empty, Anthropic's marketplace is not registered yet on that machine. Add it with /plugin marketplace add anthropics/claude-plugins-official and try again (Install plugins). One more catch from the plugin's README: if you have an older copy called desktop-themes, turn it off first, because both claim the same two command names.
How do you use /custom-theme?
All commands come from the theme-examples README:
| Command | What it does |
|---|---|
/custom-theme | Opens a card with every theme, grouped by light or dark window, with a preview button |
/custom-theme list | Names all twenty |
/custom-theme aurora | Applies a theme to this project. Other open sessions of the project pick it up on their next turn |
/custom-theme aurora session | Applies it to this session only |
/custom-theme off | Clears the project's theme (off session clears just this session) |
/fireworks | A short fireworks show over the theme. One also goes off when Claude says "merged". /fireworks auto off stops that |
Why /custom-theme and not /theme? Because /theme already exists. In the terminal it opens the older color-theme picker, which reads JSON files from ~/.claude/themes/ (terminal config docs). Those terminal themes recolor Claude Code's text and accents inside your terminal, and the docs note that Claude Code does not control the terminal's own color scheme. They don't touch the desktop app.
Get the AI tools worth your time
Era of Minds by Salman Ahmed: one short email with the AI tools and news that actually matter. Free.
You're in. Check your inbox.
Confirm your email and your 50 AI prompts are on their way.
Free. Unsubscribe anytime.
Which 20 scenes come with theme-examples?
Straight from hooks/themes.ts in the plugin. Seven are made for a light window and thirteen for a dark one. Eight come in four light/dark pairs.
| Name to type | Title | Window | What it shows | Twin |
|---|---|---|---|---|
honu-lagoon | Honu Lagoon | light | A live ASCII lagoon from above: a tile turtle swims by a sand island | – |
koi-mosaic | Koi Mosaic | light | A tiled koi pond from above: two koi, lily pads, slow ripples | – |
halftone-dawn | Halftone Dawn | light | A two-ink riso sunrise: halftone dots that breathe outward | halftone-dusk |
halftone-dusk | Halftone Dusk | dark | The riso sunrise on night-blue stock: an ember sun in breathing dots | halftone-dawn |
plotter-tide | Plotter Tide | light | Pen-plotter tide lines drawing themselves on warm paper | plotter-tide-night |
plotter-tide-night | Plotter Tide, Night | dark | The plotter's tide chart in pale ink on blue-black night paper | plotter-tide |
dither-dunes | Dither Dunes | light | One-bit dunes on sand paper, shaded in dots, under a terracotta sun | dither-dunes-night |
dither-dunes-night | Dither Dunes Night | dark | The same dunes after dark: pale dots on umber, an ember sun | dither-dunes |
paper-garden | Paper Garden | light | Cut-paper leaves at the edges of a warm white sheet, one coral bloom | paper-garden-kraft |
paper-garden-kraft | Paper Garden, Kraft | dark | Cut-paper leaves at the edges of dark kraft paper, one coral bloom | paper-garden |
night-reef | Night Reef | dark | The lagoon after dark: a turtle and a ray that glow as they swim | – |
snow-pines | Snow Pines | dark | An ASCII pine forest at dusk, snow drifting down through the trees | – |
braille-stars | Braille Stars | dark | A slow night sky drawn dot by dot on a braille grid | – |
teletext-clouds | Block Clouds | dark | Night clouds built from blocks on a teletext grid, drifting in | – |
vector-range | Vector Range | dark | Phosphor mountains on black; an amber beam keeps retracing them | – |
departure-board | Departure Board | dark | An amber LED board re-lettering itself, row by row | – |
blueprint | Blueprint | dark | A cyanotype sheet; a comet goes round its plotted orbit in the corner | – |
deep-water | Deep Water | dark | Light falling through deep water, and one quiet turtle | – |
aurora | Aurora | dark | Northern lights swaying over a dark ridge | – |
ember | Ember | dark | A warm glow in the corners and a few embers rising | – |
Every scene is animated, and the motion stops when your system asks for reduced motion. If your window is set to the other kind (a dark scene in a light window, say), pick its twin or change Settings, General, Appearance, as the README suggests.
How do you make your own Claude Code theme?
The fast way: ask Claude. Start a local session in the Code tab and describe it. The docs' own example prompt is make a mod that makes the app cream in light mode and dark brown in dark mode. Claude writes the mod with a built-in skill called plugin-authoring into ~/.claude/dev-mods/ plus the session's ID. In the default and acceptEdits permission modes it asks you to approve each file first (Create a mod). The Code tab changes color when the mod loads, and you tweak it by telling Claude what to change.
The hands-on way: write it. The docs walk through a mod called paper:
- In a Code tab session, ask Claude to
copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/. - Save
.claude-plugin/plugin.jsonandhooks/hooks.jsonin~/.claude/skills/paper/(copy them from the "Write a mod yourself" section of Create a mod and renamefirst-modtopaper). Mods under~/.claude/skills/load when a session starts. - Save this as
~/.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)
})
}
That code is from the docs, unchanged. Swap the six hex values for your own and start a new local session. For an animated background you add a backdrop with a scene name to the same $.theme.set call, then draw that scene in a ui.render hook on the Backdrop component. An SVG backdrop can be up to 131,072 characters, and scene names allow letters, digits, _ and -, up to 64 characters (Mods reference). Put colors and backdrop in one call: a second call replaces the first.
The quickest way to learn the backdrop part is to read theme-examples itself. Its hooks/register.tsx and its 14 scene files are meant to be copied and changed; the README says so in its second paragraph.
Why isn't my Claude Code theme showing?
- You are in the terminal. The terminal draws no backdrop and ignores mod colors. Use the Code tab of the desktop app.
- It's a cloud session. Local sessions only, for now.
- Old version. Check
/statusin the Code tab. Colors need v2.1.324+, backdrops v2.1.319+. Update the desktop app and restart. - New session or just ran /clear. theme-examples shows nothing until you send a message. In a reopened archived session, none shows at first.
- Two theme mods. Whichever ran
$.theme.setlast wins. Keep one theme mod on. - Refused colors. Ask Claude to run the mod's
makeColorscall. A problem line startingDesktop won't paint this thememeans a color pair was rejected. - Third-party provider. If you use Bedrock or another provider instead of a Claude account in Claude Desktop v5.11492.5 or earlier, the Code tab keeps its own colors.
To get rid of a theme, turn off the mod (move its folder out of ~/.claude/skills/, or disable the plugin in Manage plugins), start a new session, and if colors still stick, open Settings, search code appearance and choose Remove colors.
Is it safe to install theme mods?
Treat a theme like any other code you install. The docs put it plainly: "A mod is code that runs with your permissions. It can read and write your files, start processes, and make network requests." A pretty scene can come with hooks you didn't ask for. Before installing a community theme, clone it and run claude plugin validate on its folder; that lists every event it hooks and every API it calls without running it (Mods overview).
The Anthropic example is a good model here. Its README says it looks for one word, "merged", in Claude's replies and keeps none of it, reads none of your prompt text, stores only theme names (per project, and per session for the last 200 sessions) and "sends nothing anywhere."
What we'd do first
Install theme-examples, run /custom-theme and preview a few scenes before writing anything. If you keep several repos open, set one scene per project (Blueprint for the backend, Paper Garden for the docs site) so you always know which window you are typing into. That is the practical win here, more than looks. Then ask Claude for a colors mod in your brand palette. We could not test the desktop app on our Linux box for this post, so the steps above come from the docs and the plugin files, not from our screen.
The same evening, @ClaudeDevs also shipped a more proactive coordinator for Claude Code Projects, which pairs well with per-project themes. If you like dressing up Claude Code, try earshot, which gives it sound. For design work inside it, see Taste-Skill and Anatomy for 3D diagrams.
Get the AI tools worth your time
Era of Minds by Salman Ahmed: one short email with the AI tools and news that actually matter. Free.
You're in. Check your inbox.
Confirm your email and your 50 AI prompts are on their way.
Free. Unsubscribe anytime.
FAQ: Claude Code desktop themes, /custom-theme and mods
How do I get themes in Claude Code?
Update the Claude desktop app, open a local session in the Code tab and run /plugin install theme-examples@claude-plugins-official. Then type /custom-theme to pick one of 20 animated scenes, or /custom-theme off to remove it. You can also ask Claude, in plain words, to make a theme mod in the colors you want.
What is the /custom-theme command in Claude Code?
/custom-theme comes from Anthropic's theme-examples plugin, not from Claude Code itself. It opens a card with all 20 scenes, /custom-theme list names them, /custom-theme <name> applies one to the project, adding session applies it to one session, and /custom-theme off clears it. It is named custom-theme because /theme already opens the terminal color-theme picker.
Do Claude Code themes work in the terminal?
No. Backdrops are drawn only by the Claude desktop app and the mobile app, and mod colors apply to the desktop app's Code tab. In the terminal, /theme still lets you pick or create color themes stored as JSON files in ~/.claude/themes/, which is a separate, older system.
What version of Claude Code do desktop themes need?
Per the Claude Code docs (November 14, 2026), backdrops need Claude Code v2.1.319 or later and desktop colors need v2.1.324 or later in the Code tab. Check it by typing /status in a local Code tab session. The desktop app has its own copy of Claude Code, so update the app.
Do Claude Code themes work in cloud sessions?
Not yet. @ClaudeDevs said on November 13, 2026 that themes work in local sessions in the desktop app today and that support for cloud sessions is coming soon. No date was given.
How many themes come with theme-examples?
Twenty animated scenes, version 0.4.3: seven for light windows and thirteen for dark ones, with four light/dark pairs. Examples are Honu Lagoon, Koi Mosaic, Plotter Tide, Paper Garden, Braille Stars, Departure Board, Blueprint, Aurora and Ember. Anthropic calls it an example to read, copy and change.
Can I make my own Claude Code theme without coding?
Yes. In a local Code tab session, describe it, for example: make a mod that makes the app cream in light mode and dark brown in dark mode. Claude writes the mod with its built-in plugin-authoring skill, asks you to approve the files in the default permission mode, and the colors change when the mod loads.
Are Claude Code theme mods safe?
A theme mod is code that runs with your permissions and can read and write files, start processes and make network requests. Install only from authors you trust, and run claude plugin validate on a cloned plugin to list what it hooks and calls before you install it. Anthropic's theme-examples README says it sends nothing anywhere.
Sources
- @ClaudeDevs on X, November 13, 2026: custom themes for Claude Code on desktop with mods and the follow-up reply (metrics via X API, November 14, 2026, about 10:30 Dubai time)
- Claude Code docs: Draw in the interface with a mod, Mods overview, Create a mod, Mods reference, Install plugins, Desktop, Terminal config (read November 14, 2026)
- GitHub: anthropics/claude-plugins-official, plugins/theme-examples: README, plugin.json (v0.4.3, Apache-2.0) and hooks/themes.ts
- Theme Examples on claude.com/marketplace
Get AI news decoded weekly.
Decoded is a free weekly email from Era of Minds. The AI stories that actually matter, in plain English. Five minutes, no hype.
You're in. Check your inbox.
Confirm your email and your 50 AI prompts are on their way.
Free. Unsubscribe anytime. Free gift: 50 AI prompts that actually work, sent the moment you join. More about Decoded