claude-color

Live docs & demo → edocksil.github.io/claude-color

Drive a wired VIA-compatible keyboard's RGB from Claude Code status — see at a glance whether Claude is working, waiting for you, idle, or hit an error, without looking at the terminal.

• working → blue-purple
• waiting for you (permission / input) → amber, breathing
• idle (turn done, session alive) → deep green
• error (a turn ended on an API/session failure) → red, breathing
• Claude Code exits / no session running → your normal lighting is restored

Why claude-color

Built to be correct under real conditions, not just a demo:

• Multi-session aware — one keyboard, many Claude Code sessions, resolved by priority (error > waiting > working > idle).
• Survives crashes & sleep — sessions are tracked by their Claude process; dead ones are pruned, and a reconcile on logon, unlock and every five minutes restores your lighting when no session is running.
• Accurate status — distinguishes a real permission prompt (amber) from a finished-but-idle session (green) via Claude Code's notification_type.
• Restores your lighting — captures your real keyboard color and puts it back, with a guard against capturing its own status colors.
• Windows-first, keyboard-generic (any wired VIA RGB keyboard), 127 tests.

Requirements

• Windows 11, Python 3.11+. Install from PyPI with pip (or uv).
• Any wired keyboard exposing a VIA raw-HID interface with an RGB matrix, connected by USB cable. VIA support is most commonly provided by QMK firmware with VIA enabled, but only the VIA protocol is required — not QMK itself. Developed and validated on the Keychron Q6 Max. Wireless is not supported (wired only). See docs/COMPATIBILITY.md.
• Optional but recommended: the qmk_hid binary on your PATH (primary backend). Without it, the built-in Python hidapi backend is used.

Install

From PyPI:

pip install claude-color           # or: uv tool install claude-color

Then set it up (run from any terminal):

claude-color doctor                # confirm the keyboard is detected
claude-color test                  # cycle working/waiting/idle/error, then restore
claude-color install               # wire the Claude Code hooks into %USERPROFILE%\.claude\settings.json

Make sure your Python (or uv) scripts bin dir is on PATH so Claude Code — and the scheduled reconcile task — can invoke claude-color.

git clone https://github.com/Edocksil/claude-color && cd claude-color
uv tool install --editable .       # exposes `claude-color` on PATH, tracking your clone
claude-color install

Demo

claude-color test cycles working → waiting → idle → error (showing breathing where configured), then restores your lighting. To eyeball a single state, use claude-color set <state> --timeout <seconds> (applies it briefly, then restores).

claude-color test                 # ~2s per color (quick check)
claude-color test --dwell 30      # hold each color 30s (slow demo)
claude-color set error --timeout 5 # briefly show error, then restore

Configure

Everything is tunable in %LOCALAPPDATA%\claude-color\config.toml (created on first run). Every option and its default:

[breathing] is per-state opt-in: a state listed there breathes at the given speed; remove the line to keep it solid, and an empty [breathing] means every state is solid. Only waiting and error breathe by default.

Not sure which effect indices your keymap uses? Run claude-color probe — it cycles the RGB-matrix effects so you can spot which is solid and which breathes, then set solid_effect_index / breathing_effect_index. Known values per board live in docs/COMPATIBILITY.md.

How it works

flowchart LR
    CC["Claude Code hooks"] -->|"SessionStart · UserPromptSubmit · Notification · Stop · StopFailure · SessionEnd"| K["claude-color hook"]
    K --> S["state.json<br/>(per session, by PID)"]
    S -->|"winner: error &gt; waiting &gt; working &gt; idle"| KB["keyboard RGB<br/>(VIA raw-HID)"]
    R["claude-color reconcile<br/>(logon / unlock / every 5 min)"] --> S

Claude Code fires hooks (SessionStart, UserPromptSubmit, Notification, Stop, StopFailure, SessionEnd). Each runs claude-color hook, which updates a per-session state file (%LOCALAPPDATA%\claude-color\state.json) and pushes the highest-priority color (error > waiting > working > idle) across all live sessions — StopFailure fires when a turn ends on an API/session error, setting that session to error. Sessions are tracked by their Claude process id; dead ones are pruned, and a scheduled claude-color reconcile (logon, unlock, and every five minutes) restores your lighting when no Claude is running. When the last session ends, the lighting captured at first SessionStart is restored.

The five-minute tick is also what bounds a stale status. Hooks are fire-and-exit, so a session that goes silent — you interrupt a turn, or dismiss a prompt, neither of which fires any Claude Code hook — has nothing to re-evaluate it. The tick gives waiting_max_minutes something to run on, so a wrong amber clears within about fifteen minutes instead of lasting until the next real event. The task is Windows-only and needs one elevated claude-color install to register; without it the hooks still work, but nothing ticks.

Troubleshooting

• No color changes: run claude-color doctor. If available: False, check the USB cable (wireless is not supported) and try backend = "hidapi" or set vid/pid.
• Animation instead of solid color: fix solid_effect_index.
• Colors never restore: baseline capture may be unsupported on your firmware via the active backend; try backend = "hidapi". Logs are in %LOCALAPPDATA%\claude-color\claude-color.log.
• Uninstall: claude-color uninstall.

License

MIT — © 2026 Edocksil.