claude-color — your keyboard is the Claude Code status light

Why claude-color

Correct under real conditions — not just a demo.

Anyone can flash an LED on a hook. The hard part is many sessions, crashes, and sleep. claude-color is built for those.

Concurrency

Multi-session, one keyboard

Run Claude Code in a dozen terminals; the color resolves by priority — waiting > working > idle — so the board shows what matters most.

Resilience

Survives crashes & sleep

Sessions are tracked by their Claude process id. Dead ones are pruned, and a reconcile on logon/unlock restores your lighting when nothing is running.

Accuracy

Knows waiting from idle

A real permission prompt turns the board amber; a finished-but-open session goes green — distinguished by Claude Code's notification_type, not guesswork.

Courtesy

Puts your lighting back

It captures your real keyboard color on the way in and restores it on the way out — with a guard so it never captures one of its own status colors.

Reach

Keyboard-generic

Speaks the standard VIA raw-HID protocol (usage page 0xFF60), so any wired VIA keyboard with an RGB matrix works. Validated on the Keychron Q6 Max.

Trust

Local, tested, quiet

Everything runs on your machine over USB — no cloud, no telemetry. Backed by 104 tests, Windows-first today, cross-platform on the roadmap.

How it works

Hooks in, color out.

Claude Code fires lifecycle hooks; claude-color turns them into one winning color across every live session.

Source Claude Code hooks

SessionStart · UserPromptSubmit · Notification · Stop · SessionEnd

→

Handle claude-color hook

Maps each event to a per-session state; records the owning Claude PID.

→

Resolve state.json

Prunes dead PIDs, then picks the winner: waiting > working > idle.

→

Light keyboard · VIA HID

Pushes the solid color over USB; restores your baseline when empty.

Out of band, claude-color reconcile runs on logon/unlock to recover the lighting after an ungraceful exit that never fired a Stop hook.

Get started

Three lines, then it just glows.

Requires Windows 11, a wired VIA keyboard with an RGB matrix, and uv. Everything is tunable in config.toml.

# install the CLI globally (editable)
uv tool install --editable .

# confirm the keyboard is detected
claude-color doctor

# wire the Claude Code hooks
claude-color install

# show it off: cycle the states, then restore
claude-color test --dwell 30

[colors]	working / waiting / idle as H,S,V (0–255). Defaults: 180,255,200 · 30,255,220 · 90,255,120.
backend	`auto`, `qmk_hid`, or `hidapi`.
vid / pid	Hex device filter — only if several HID devices match. Find yours with `claude-color doctor`.
solid_effect_index	Your keymap's "solid color" effect index — bump it if a status shows an animation.
staleness_minutes	A stuck session is forgotten after this (default 120).

Roadmap

nowCustomization →Linux & macOS →PyPI & releases →Wireless (custom QMK) →Multi-agent · Codex / Cursor