Claude Code mod · Wizard1209/rainbow-spinner

rainbow-spinner architecture

A style is a colour field over Claude Code's spinner line, the working indicator under the chat, field(x, t, line) → [r, g, b], with an optional glyph of its own before the word. The clock, the pictures, the fallback to text and the stored choice are shared, so styles are written independently of each other.

tempertemper: rims of colour spread from the middle of the word, each letter one colour
holoholo: narrow bands of colour run inside the letters of the word
bloombloom: a pastel rainbow flows along the line behind a plant that grows from seed to flower
/spinner switches between these and off, the default, which leaves the line to Claude Code.

Layers

Imports point one way. styles/ and core/ import nothing from Claude Code, so both are tested as plain functions.

Claude Code: the engine events: session.start · command.run · ui.render · ui.message API: $.store · $.state · $.clock · $.command · $.env · $.fs · $.process · $.plugin $.ui.resolve → Box · Text · Client · Image · $.ui.blit · $.ui.invalidate · $.ui.log hooks/*.ts(x): engine adapters style off: every drawing hook hands its event to next(e) register.tsx entry point: spinner · command · warning spinner.tsxthe line spinner-client.tsxclock, spans terminal.tsfacts, capsOf wezterm.tsthe WezTerm module's folder command.ts/spinner warning.tsxthe reply box hooks/styles/: the styles off is a tag in index.ts: no file, nothing drawn index.ts OFF · STYLES · FALLBACK · TAGS · findStyle · tagOf temper.tstext · 40 ms holo.tsimage · 40 ms bloom.tstext · 80 ms, sprite film-band.tsshared FILM_BAND hooks/core/: pure functions, no engine style.ts the contract: Style · Field · Glyph · Line · letterAt · lineOf line.tstextFrame, echo picture.tsJetBrains Mono atlas rims.tsthe rims field choice.tschoose() colour.tsRgb, OKLab, evenLut film.tsthin-film colour duration.ts42s · 3m 7s rgba.tsRgba, inked caps.tsFacts → Caps (classify) · needs(style) · check → Verdict · itermFont png.tsits own deflate core/wezterm.tsmarker, stateText import { atom, read, update }, types On · Register · ClientSurface findStyle · tagOf · FALLBACK · TAGS · OFF type Style · rims · film · fromOklch · evenLut · inked hooks → core

The style contract

A style draws nothing: the core samples its field, as text or as a picture of the word.

// hooks/core/style.ts
type Field =
  (x: number, t: number, line: Line) => Rgb
// the middle of glyph, space and word
type Line = { centre: number }

type Style = {
  // what /spinner takes
  tag: string
  // image: the word as a picture
  output: 'text' | 'image'
  // milliseconds between frames
  frameMs: number
  // the field repeats: the word's pictures
  // are made for one loop and kept
  loopMs?: number
  field: Field
  // absent: the core's star
  glyph?: (t: number) => Glyph
  // glyph() names Nerd Font icons
  nerdGlyph?: boolean
  // the glyph as a picture, two cells wide
  sprite?: (t: number) => Rgba
}
seedU+F0E62500 ms
sproutU+F0E66500 ms
leafU+F032A500 ms
cloverU+F0816500 ms
palmate leafU+F07A61200 ms
lotusU+F0CD1500 ms
The plant of bloom: glyph names each stage's Nerd Font codepoint, sprite is a 50 × 48 px picture of the same icon.
The field of holo over the line Thinking… (1s), sampled two ways: as text, one sample per cell; as a picture, a sample in every pixel column. The glyph is at x = 0, the word at 2 to 10, the tail from 11, the centre of the line at 5.
The bands of holo are about two letters wide, so it sets output: 'image'.

What the terminal can show

Two questions decide how a style is drawn: does the terminal show pictures, and does it draw the plant's icons. check answers for the line, the /spinner reply and the reply box alike, so the three agree.

Factsgathered by terminal.ts env$.env.get of: KITTY_WINDOW_ID · TERM · LC_TERMINAL TERM_PROGRAM · TMUX WT_SESSION · CLAUDE_CODE_NO_FLICKER CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN fullscreenengine's isFullscreen itermFontplutil, iTerm2 only imagesRefused$.state, every time weztermModulealive, WezTerm only StylefindStyle(chosen($)) Capsclassify(facts) picturesshows pictures nerdGlyphsdraws the icons yes | unknown | { no: why, detail? } needs(style)the best way first a way: the list of caps it takes holo [[pictures]] bloom [[nerdGlyphs], [pictures]] temper [[]] from output · nerdGlyph · sprite Verdict check(style, caps, FALLBACK) a way whose caps are all usable: ok, the style's plan no such way: the fallback's plan, the reasons, and the ask of the first way held back by one reason with an ask plantag · word · glyph word picture | text glyph nerd | picture | own spinner.tsx · the line ui.render Spinner draws the plan; a word not drawable(text) sends the whole line to FALLBACK's text command.ts · the reply refresh(), check, row(tag, verdict): 'spinner: holo' 'spinner: holo → temper · reasons' warning.tsx · the box ui.render CommandOutput with '→': style still chosen, check; an ask: box(tag, verdict) replaces the row
The fallback is temper. Two reasons carry an ask, what to ask Claude for: on iTerm2's main screen (Claude Code's classic renderer), to turn on fullscreen mode; in WezTerm without the mod's WezTerm module, to set it up.
TerminalpicturesnerdGlyphsholo drawsbloom draws
kitty, Ghostty*yesyesthe word as a picturethe plant as a font icon
iTerm2, fullscreen modeyesyes with a Nerd Font in the profilethe word as a picturethe plant as a font icon, or as a picture
iTerm2, main screenno, with an askyes with a Nerd Font in the profiletemper; the reply is a boxthe plant as a font icon, or temper and a box
WezTermyes with the mod's WezTerm module, else no, with an askyesthe word as a picture, placed by the module; without it temper, and the reply is a boxthe plant as a font icon
Windows Terminal*, Terminal.app*nonotempertemper
tmux*, any other terminal*unknownno; in tmux, as the kitty or iTerm2 around itpictures are tried; after three refusals in a row with none taken, as where pictures is no
Tested in kitty, iTerm2 and WezTerm; the versions are in the README. Terminals marked * follow Claude Code's documentation and are not tested.

A frame

spinner.tsx answers each render of the line with a client component: code the engine keeps running between renders, with its own state and timer. It keeps the clock. For text it computes the colours itself; for pictures it posts the time, and the hook swaps the pictures in place. In WezTerm the hook writes one loop of the word's frames to a file and marks the word's cells, and the mod's WezTerm module places the frames.

the engine spinner.tsx core/line.ts ui.render Spinner chosen($) findStyle · check(…).plan: the word and the glyph as text <Client key="line"> props: tag, text, activity, part: 'line' SpinnerLine(props, surface) spinner-client.tsx the clock: surface.every(frameMs) start = Date.now() loop every frameMs (temper 40 ms, bloom 80 ms) textFrame(style, text, activity, t) t = Date.now() − start Frame: glyph · word[] · tail[] setState({ t }) only if the frame has changed the engine redraws one Text of coloured spans
As text: temper, bloom with its plant as a font icon, and every line drawn as the fallback.
the engine spinner.tsx core/picture.ts+ the style's sprite ui.render Spinner check(…).plan, parts(plan, text): word? glyph? a plan with pictures: the line is drawn with them Row: Image and Client holo: the glyph's Client key="line" · Image key="word" · the tail's Client bloom: Image key="glyph" · the Client of word and tail, key="line" source: the last picture in shown, else the frame at t = 0 SpinnerLine(clock: true) spinner-client.tsxkey="line", clock: true surface.every(frameMs) loop every frameMs (holo 40 ms, bloom 80 ms) surface.post({ t, tag, text }) ui.message element: 'line' word: picturePng(field, text, loopTime(t)) from the wordPictures cache once this frame of the loop has been made glyph: style.sprite(t), the stage's picture: one object while the stage holds word: PNG 25·n × 48 px, n letters glyph: Rgba 50 × 48 px $.ui.blit({ key, source }) key 'word': every frame key 'glyph': only when sprite returns another object than the one shown ok | deny ok: shown[requestId] keeps the word and the glyph's frame time; refused = 0 deny: refused + 1; shown keeps the glyph shown before, so a refused glyph is sent again on the next frame if refused ≥ 3 in a row: one count for the word and the glyph picturesRefused($) terminal.ts: imagesRefused = true, unless the session has had a picture taken (imagesShown). From then pictures is { no }, and holo, and bloom without icons, are drawn to FALLBACK's plan the line is redrawn at once, as text
As pictures: the word of holo outside WezTerm, and the plant of bloom where it is not a font icon. $.ui.blit replaces a picture without a redraw of the line.

State

WhereWhatLives
$.storestyle: the chosen tagacross sessions
the WezTerm module's folderalive, which the module rewrites while it runs; each pane's state file (the mod's) and ack file (the module's); one PNG of frames for each of a pane's last two wordsthe state and ack until a minute without change while the pane is open; the PNGs stay
$.stateimagesRefused, imagesShown: whether the terminal has refused a line's pictures, whether it has taken onethe session
the hooks moduleshown: the plan and the last pictures of each line; wordPictures: the word's PNGs for one loop; the facts gathered about the terminalwhile the module is loaded
the clientits clock: the start, the timer, the last frameone Client instance

Adding a style

One new file in hooks/styles/ and one entry in STYLES: /spinner takes the tag from there, and tests/styles.test.ts holds every registered style to the contract. tests/caps.test.ts and tests/command.test.tsx list the styles by name: add the tag there too.

// hooks/styles/tide.ts
import { fromOklch } from '../core/colour'
import type { Style } from '../core/style'

// A wave of hue from the centre outwards.
export const tide: Style = {
  tag: 'tide',
  output: 'text',
  frameMs: 80,
  field: (x, t, line) => {
    const d = Math.abs(x - line.centre)
    const h = (d * 20 - t * 0.05) % 360
    const hue = h < 0 ? h + 360 : h
    return fromOklch(0.75, 0.12, hue)
  },
}

// hooks/styles/index.ts
import { tide } from './tide'
export const STYLES: readonly Style[] =
  [temper, holo, bloom, tide]