ADR-514: Claude Code follows the active theme through the ways-theme mod, over externalised theme layers¶
Summary¶
- Decided: A Claude Code mod,
ways-theme, makes Claude Code follow the theme chosen in ways settings and draws its transcript in that theme. The theme is chosen in one place,theme.active; the mod is installed or removed through the mod manager, off by default, and every setting it reads is a ways setting. Themes are split into three layers: the palette (the.themefile), the roles derived from it with the contrast floors applied, and per-target mappings from roles to another program's colour keys, which a theme file can pin. Claude Code gets one fixed custom theme,custom:ways, whose file the mod rewrites at session start; installing the mod selects it over the person's theme and uninstalling gives theirs back. On the terminal surface the mod frames replies and tool groups in the theme's ground and a border, redraws the transcript headless with a port of skins' renderer, and sets the person's message on the theme's gradient. Onewaysexport, read every 5 s, configures the drawing, and none of skins' menus, slash commands or settings store is ported. A missing, failing or slowwaysdoes nothing. - Trades away: Four columns of every framed row on the terminal. The person's own Claude Code theme while the mod is installed, though it comes back on uninstall. The theme's border and rule glyphs, marks and ornament, which Claude Code's chrome cannot take. Exact colours: text roles are lifted to read on terminal backgrounds the theme does not paint, so they can sit further from the file's values than on the theme's own screens. Selection through settings.json and repair, where a supported mod call would be simpler, until Claude Code lets a mod select a custom theme. About 14k vendored lines that this project maintains and skins' later releases do not reach. A
waysprocess every 5 s in each open session. - One-way? No. Reversible: uninstalling the mod restores the person's theme, removes the theme file and stops the drawing, and the theme layers are additions to the theme file format that a theme need not use.
- Probes: Confident (one place): you want the theme picked once, in ways settings, and Claude Code to follow it with no theme setting of its own in the mod. Not confident (web later): you are content that the web surface gets no frame and only what Claude Code's custom theme gives it, until the terminal surface has settled.
- Inversion: Between a Claude Code theme maintained by hand beside each agent-ways theme, and Claude Code drawn entirely by agent-ways. The record sits between them: agent-ways supplies colours through Claude Code's own theme file and redraws only the components a mod may render, while Claude Code keeps its chrome, its menus and every surface but the terminal.
Context¶
ADR-513 has every agent-ways surface follow theme.active. Claude Code, the program those surfaces sit beside, keeps its own theme, so a session under Miami Nights draws agent-ways in neon violet and Claude Code in its default dark.
Claude Code takes custom themes: a JSON file in themes/ naming a built-in base and overriding colour tokens, selected in settings.json as custom:<name>. It watches the folder and reloads a changed file. A mod's $.config.set refuses a custom theme, which /theme accepts (anthropics/claude-code#105739). Claude Code paints no ground under the transcript, and a mod cannot set the terminal's background, so its text lands on whatever background the terminal has. A mod's ui.render can wrap the element the engine draws for a transcript entry.
An agent-ways theme holds slots; the roles every surface draws are derived from them with the contrast floors applied (ADR-504 §4). A second program needs those roles mapped to its own keys, and a theme may want a key the mapping does not give.
Colours alone leave Claude Code's layout as it is. skins (hellosverre/claude-skins, MIT) is a mod that redraws the transcript through ui.render: tool rows on a rail, shell output as cards, tables, code, charts, the spinner and a box around the person's message. It keeps its own themes and settings store and is configured inside Claude Code, through /skin, a settings pane and a gallery. Tried in one project, its drawing helped, and its menus were hard to navigate.
Decision¶
- Three theme layers.
- Palette: the
.themefile's slots and keys (ADR-504 §4, ADR-513). - Roles: derived once from the palette with the floors applied, the same roles every agent-ways surface draws.
ways settings theme export <name> --rolesprints them as JSON, so another program can read them without agent-theme. -
Targets: a default mapping from roles to each target program's keys, held in agent-theme (
target.rs), with each key's contrast floor. A theme file may carry a[target.<name>]table ofkey = "#rrggbb", and an entry there wins over the mapping. A key the target does not list is a parse error. Claude Code is the one target;ways settings theme export <name> --claude-codeprints its custom theme. -
Roles on a ground agent-ways does not paint. For a target that draws on the terminal's own background, the roles are derived again (
Roles::derive_on) with every text role lifted to its floor on the theme's bg, its selection ground, and a band of common terminal grounds of the theme's kind: black and#2a2a2afor dark, white and#e8e8e8for light. The gradient is dropped, since the target does not paint it. A background token, such as a diff or a message background, is shaded only as far as the body text still reads on it. -
One fixed Claude Code theme. Claude Code has one custom theme for agent-ways,
custom:ways, in<config dir>/themes/ways.json. At the start of an interactive session the mod readstheme.activethroughways settings get, exports that theme with--claude-code, or Claude Code's own dark forterminal, and rewrites the file when its content changed. It does the same mid-session whenever the export of item 10 changes, on that export's 5 s read, so a switch of theme or an edit to its colours reaches the file, and a rewrite that failed is tried again on each later read. Claude Code reloads it live, so every open session follows. A headless session changes nothing. -
The mod manager installs it.
ways-themeis a mod undermods.ways-theme(ADR-512), installed from the mod tab in ways settings or withways manage mod install ways-theme --commit. It defaults to not installed. The mod adds no theme setting: its theme istheme.active, and its render settings are ways settings (item 11). Its Claude Code floor is 2.1.309, the release it was seen running on, whose engine wrote the type declarations that carry every call it makes. The floor is checked at install, so a Claude Code downgraded afterwards is not caught. -
Selection through the settings merge. While
mods.ways-theme.installholds and Claude Code lists the mod installed in that target, the settings merge that repair and the mod manager run (ADR-500) owns settings.json'sthemekey there. A wanted mod still pending, on a Claude Code below its floor or with noclaudeon PATH, claims nothing. - Installing claims the key for
custom:waysand keeps the value it held. The claim is made even over a theme the person chose. A livecustom:waysis never kept as that value. - A value the person sets after the claim is their later choice: kept, and neither claimed again nor replaced on uninstall.
- Uninstalling gives back the kept value, or removes the key when it held none, and removes
ways.json. A livecustom:wayswith the merge's record lost is the mod's own and is removed the same way. - Each install, uninstall and repair what-if names the key's value before and after, and
ways.jsonwritten or removed. - Repair lays down a default
ways.jsonbefore it selects it, so the folder watch holds from the first session. -
The mod itself selects nothing, because
$.config.setrefuses a custom theme. When Claude Code lets a mod select one, selection moves into the mod and the merge gives up the key. -
The frame layer. On the terminal surface, the mod's
ui.renderwraps the element the engine draws for an assistant message (AssistantMessage), a tool use (ToolUse) and a tool group (ToolGroup) in the theme's ground with a border, which costs four columns per row. The frame's colours are Claude Code theme keys, so it draws only while Claude Code's selected theme iscustom:ways, read from thethemerow of/configat session start, on eachconfig.setof the row, which the mod observes and passes on unchanged, and on the 5 s read of item 10. Under another theme the person picked in/themeor/config, or a row that cannot be read, the frames and the person's message box (item 13) step aside for Claude Code's own drawing, and selectingcustom:waysagain brings them back. It hands back the engine's own element, unframed, in the ctrl+o transcript, for a tool row expanded on its own, or for a very long reply. The ctrl+o transcript is read from the line that closes a turn (TurnDuration), the one row whoseisExpandeddescribes the whole view. Verbose mode is a standing preference, not a view: under it every row reportsisExpanded, so the mod readsisExpandedas false and frames as it does with verbose off, the ctrl+o transcript included. One predicate decides framing for this layer and the skins layer (item 9), from one state. On any other surface, the web surface included, it does nothing.
Note, 2026-10-28, after review of the mod branch: the claim waited only on
mods.ways-theme.install, so a Claude Code below the floor kept no mod and still lost its theme; item 5 now waits on the mod being installed. The floor was 2.1.312, resting on$.config.set, which the mod does not call to select a theme; item 4 now sets it at 2.1.309. ctrl+o was read from a person's composer row, whoseisExpandedis that row's own drawing under a speaker label; item 6 now reads the turn line. A pin in a theme's[target.claude-code]table is exported as given and is now checked at its token's floor, as the mapping's colours are.Note, 2026-10-28, after a live run under the operator's own settings: item 6 handed back the engine's element in verbose mode, and Claude Code reports every row as expanded under verbose, so a person running with
verbose: truesaw no frames and no gradient box. Item 6 now treats verbose as a preference and frames under it; the cost is that the ctrl+o transcript under verbose is framed too, since a hook cannot tell it from the main view. The operator runs with verbose on and asked for the frames and the box.Note, 2026-10-28, after the operator picked Claude Code's built-in
darkin/theme: the frames drew whenever the ways theme had colours, without checking Claude Code's selection, so every reply drew in dark's orangeclaudeoutline on its grayuserMessageBackground, whatever the ways theme. Item 6 now frames only whilecustom:waysis selected, and item 13's box steps aside with the frames. In the same session,theme.activemoved to Miami Nights whileways.jsonkept the earlier theme until a new session, so the frames named Claude Code keys still holding the old colours. Item 3 now rewrites the file mid-session whenever the live export changes, and retries a rewrite that failed.
-
Fail-safe. Each
wayscall is bounded at 1.5 s. A missingways, a non-zero exit, output that does not parse, a call past its bound, or a refused write leavesways.jsonas it was and writes one line to the debug log. A failure in the frame layer hands back the engine's element. -
What Claude Code cannot take. A theme's borders, rule glyphs, marks, presence, event glyphs, waypoints and ornament reach agent-ways' own surfaces only. Its gradient reaches Claude Code in the person's message alone (item 13). Claude Code takes colours through its tokens and the renderer's mapping from the roles. Its chrome outside the components a mod may render keeps its own glyphs and layout.
-
skins' renderer, headless. The renderer of skins (hellosverre/claude-skins, MIT, commit 985ad63) is ported into the mod, with its licence kept at
hooks/skins/LICENSEand a header on each ported file naming its source. Kept: the tool rows on a rail with their fold, open and copy controls, shell output as a card, tables, highlighted code and diff fences, math, Mermaid and data charts, markdown with alerts and task lists, the spinner, the turn footer, the usage band above the prompt, and the outline around the person's message. Removed:/skinand every other slash command, the settings and gallery panes, the design tool and its skill, the settings store, skins' theme files, the update check, and the Compact button. The renderer's colours come from the theme's roles through a fixed mapping; underterminalit takes skins' own terminal look, the terminal's sixteen colours. -
One source of configuration.
ways settings theme export --modprints one JSON object: the theme's name and kind, its roles as Claude Code's grounds take them, its gradient, the words in effect, and the render settings. The mod reads it at an interactive session's start and every 5 s after, each read bounded at 1.5 s, and holds it to the contract key for key. An unchanged export redraws nothing. An export that fails or breaks the contract keeps the last good look, or, before there is one, leaves every row Claude Code's own, and logs one debug line per distinct reason. -
The theme controller in ways. The render settings are ways settings under
mods.ways-theme:rail,tables(on, text, off),shimmer,charts,markdown,icons(unicode, ascii),frames,prompt_box(off, frame, gradient),copy,copy_style(verbose, compact; added 2026-10-29),paths(wrap, truncate),spinner_wordsanddone_words. They are edited in the Claude Code section of theways settingstheme tab, beside the palette the theme maps to in Claude Code and the words in effect, or withways settings set. A value a project's config sets is shown with that file, and a change made in the tab writes the user config, under the project value. Claude Code offers no control over the drawing. -
The
[words]table. A theme file may carry[words]:spinner, shown while a turn runs, anddone, the verbs of a turn's done line, each 1 to 12 entries of 1 to 24 characters with no control character. Miami, Miami Nights and Tampa carry theirs.mods.ways-theme.spinner_wordsanddone_wordswin over the theme's list, list by list, and a slot neither sets keeps Claude Code's own words. -
The gradient prompt box. With
prompt_boxatgradient, the default, the person's message on the terminal is drawn on the theme's gradient, mixed in OKLab, in the theme's body colour. A message under 4 lines sweeps the gradient across each line, padding rows included; one of 4 lines or more runs it down the lines, whatever the theme's own axis. Text is laid out by grapheme, so an emoji sequence is never split, and a line keeps its own leading indentation. A message with an image or a pasted block, the ctrl+o transcript or an expanded row (read as in item 6, so verbose does not count), a view under 12 columns, a theme with no gradient, and theterminaltheme take the outline instead. A message holding a control character or longer than 4,000 characters keeps Claude Code's own drawing, as every surface but the terminal does, and so does every message while another Claude Code theme thancustom:waysis selected (item 6).framedraws the outline every time undercustom:ways, andoffleaves Claude Code's own. -
One frame per row. The frames of item 6 and skins' outline are one set: while
custom:waysis selected, each reply, tool row and tool group sits in one frame, andframesswitches them off. A shell call's card is that call's frame, so its row is not framed again, and inside a frame the rail draws no connector. -
The copy controls. skins' inline copy controls are kept, and
mods.ways-theme.copy, default on, switches them off. A press copies one form of a block:markdown, as written;native, its own form, a table as CSV, a fence's code, a suggestion as typed;text, as drawn, with no border glyph or padding. A block offers the forms whose copied text differs, so a table offers up to three, a fence two, and a suggestion or a wide span one, drawn asCopy. A one-column table of plain cells copies the same CSV and text, and offers two. A diff fence addsnew only, and the reply offersmarkdownandtext. A form is labelled by the format it copies:nativereadscsvon a table and the fence's language, orcode, on a fence.mods.ways-theme.copy_style(added 2026-10-29) draws the labels as words,Copy as: markdown · csv · text, the default, or as glyphs,compact, from one table of words and glyphs keyed by format. On the terminal the controls draw only under the fullscreen layout. -
Surfaces. The terminal is the surface this record designs for. Off the terminal, a surface that draws SVG keeps the cards skins draws there, the desktop's among them; the person's message, the frames, the gradient and every other row are Claude Code's own.
Note, 2026-10-28, after the skins trial: the record had the mod add no setting of its own (item 4), kept the gradient out of Claude Code (item 8), and borrowed no code from the prior art. The operator said "I vote we strip out a lot of the ui stuff that makes it run inside claude code and move that over to a claude theme controller in ways", and items 9 to 16 port skins' renderer without its menus and put its settings in ways.
Note, 2026-10-29, after the copy blocks and their review: on the terminal, text a reply hands the person to copy draws as a block of its own outside every frame, so a selection over it takes no border glyph, padding space or wrap break, and its Copy takes the text whole. There are five forms. A
!shell suggestion. A/slash command: the bare name on a line of its own, or with its arguments in a code span or a one-line fence, where the name is one$.command.list()lists; a sentence that opens on a command name and a route such as/healthstay prose. A fence's code, less the indentation of the list item it sits in. A code span wider than 60% of its row, less that indentation. A table, which Copy takes as CSV with its header row undercopy_as: content, each code span in a cell kept as written. The operator also said to "remove the folding content. it's just obscuring the output". An opened tool row had stopped at 20 lines behind ashow allcontrol, which a row printed into the terminal's scrollback cannot press, and the desktop's code and diff cards had stopped at 80 and 30 lines with "N more lines". Every line now draws and a long one wraps. A block past what one drawing or one Svg document holds keeps Claude Code's own drawing, as a reply past one drawing does. The chevron that opens a tool row (item 9) stays.Note, 2026-10-29, after the operator tried the copy controls: on Claude Code's main screen a transcript row is printed into scrollback, so a click on Copy there copied nothing and raised no toast, and under the fullscreen layout it worked. The terminal now draws the controls only under the fullscreen layout. The operator then asked: "The 'look' of it could be a little more polished. We could have a little divider between the text, and maybe the lower right stuff which is 'copy reply' could be consistent with casing, and 'Copy' could be more obvious. I'm realizing that setting copy_as in the theme control isn't as helpful - perhaps we could simplify - copy turns it off and on, and we have a 'verbose' mode for copy. 'Verbose' is: 'Copy As: markdown | native | text' (each three options is clickable) and 'Compact' is a 'copy' glyph, and some glyphs that signify markdown, native and text."
copy_asis removed, with no retirement entry, since the operator said none is needed (2026-10-30: it is now retired, after a config still holding it had the wholemods.ways-themeentry ignored and repair uninstall the mod; a file that holds it is told so, and the rest of the entry loads). Each press now picks its form, andcopy_stylepicks words or glyphs (item 15). A·separates the forms on a frame, a|under ascii icons, and a block with one copy draws a boldCopyin the accent. The reply's control readsCopy reply as: markdown · text. The operator went on: "if we already technically 'know' what format native is, we could swap out the text 'native' for the format it actually copies as", and "so we keep a little table of compact and verbose terms for each format type". The native form is now labelledcsvon a table and by the fence's language on a fence,codewhere the fence names none, and every word and glyph comes from one table keyed by format.
The figure for this record is two screenshots of Claude Code 2.1.312 under Miami Nights, taken during the work and described here because the corpus keeps figures as SVG. The first shows the welcome block and a typed prompt: the prompt box's border is neon pink, the header and status text are lavender, and the transcript sits on the terminal's own near-black. The second shows the frame layer's prototype: the user's prompt on a violet bar, each reply in a violet block inside a rounded lavender border, and a collapsed tool line ("Listed 1 directory (ctrl+o to expand)") left unframed between them.
Consequences¶
Positive¶
- One choice in ways settings themes agent-ways and Claude Code together, and a change reaches open sessions live.
- Another program can follow agent-ways themes by reading the roles export or adding a target mapping, without its own copy of the palettes.
- A theme can pin any Claude Code token where the mapping falls short, in the same file as its palette.
- Text stays readable on common terminal backgrounds the theme does not paint.
- A broken or missing
waysnever breaks Claude Code. - The transcript takes the theme's colours, words and gradient in its tool rows, cards, tables, charts and the person's message.
- Every setting the drawing reads is edited where the theme is chosen, and Claude Code carries no menu for it.
Negative¶
- Framed rows lose four columns, which narrow terminals feel first.
- The frame layer and the renderer depend on the element names and props Claude Code's engine passes to
ui.render; a Claude Code release that changes them leaves rows unframed or misdrawn until the mod follows. - Selection runs through settings.json and repair, so a person who sets
/themeby hand after the claim keeps their choice, and the mod's colours apply only whilecustom:waysis selected. - Installing the mod replaces the person's theme until uninstall, which a person who chose their own theme may not expect.
- Lifting onto the ground band moves text colours further from a theme's own values, most for themes whose bg is far from black or white.
- Each session start runs up to two
wayscalls, bounded at 1.5 s each, before the theme file is current. - About 14k lines are vendored, an 84 KB bundle of beautiful-mermaid's layout among them. This project maintains them, and a fix in skins arrives only when ported by hand.
- Each open session starts a
waysprocess every 5 s. - The bundled Miami, Miami Nights and Tampa files carry
[words], so they no longer source as shell. - A shell card in a resumed session shows "Output" in place of its command.
Neutral¶
- The web surface gets whatever Claude Code's custom theme gives it, and no frame.
[target.<name>]and[words]are tables in the theme file, as[[waypoints]]is (ADR-513 item 15), so a theme file that uses one no longer sources as shell.- The mod carries the
waysversion, since it callsways settingsverbs. - The looks project (MIT) supplied ideas only. skins' code is ported under its licence.
Alternatives Considered¶
- A hand-written Claude Code theme beside each agent-ways theme. Two files per theme drift apart, and a user theme would need its Claude Code twin written by hand. A mapping derives both from one palette.
- The mod selects its theme with
$.config.set. Claude Code 2.1.312 refuses a custom theme there. Filed as anthropics/claude-code#105739; selection moves into the mod once the call accepts one. - One custom theme file per agent-ways theme. Switching themes would change the selected name in settings.json, which the mod cannot write. One fixed name whose content changes needs settings.json touched only on install and uninstall.
- Keep the person's theme on install ("Keep theirs", declined by the operator). The mod would do nothing visible for anyone with a theme already chosen.
- Ship the frame layer in a later change ("Later, own PR", declined by the operator), or drop it ("Drop it", declined by the operator). The colours alone leave replies on the terminal's own background, which is the look the operator asked the mod to change.
- Set the terminal's background with OSC 11. A mod has no call that writes to the terminal outside the engine's rendering, and a background changed under the person's terminal would outlive the session.
- Export only the roles and let each target map them. Every target would carry its own copy of the floors. The mapping in agent-theme applies them once, and the roles export stays for programs agent-ways does not map.
- Install skins as it is. Its drawing is configured through menus inside Claude Code, which the operator found inconvenient, and it keeps a second set of themes beside agent-ways'.
- Port the renderer in a later release ("Next increment", declined by the operator). The operator chose one release carrying both the theme and the drawing.
- Pick up a settings change through a file watch. The mod API reads and writes files and offers no watch, so the mod polls the export.