Troubleshooting & FAQ

The light isn't changing color

1. Confirm the ClawLight CLI sees your sessions: run clawlight and check the dashboard.
2. Confirm status LEDs are enabled: press l in the dashboard (they're off by default).
3. Confirm the light is plugged in over USB and detected (see below).

The menu-bar icon is gray but I have sessions running

Gray means the ClawLight CLI sees no live sessions. If you do have sessions running, the ClawLight CLI may be watching the wrong state directory — restart it, or reinstall the hooks and login agent with clawlight install.

The light is stuck red

Red means a session is waiting on you. Open the TUI (clawlight) to find which session needs input; once you respond, the color clears automatically.

The light isn't detected

• Use a data-capable USB-C cable — charge-only cables won't expose a serial port.
• The ClawLight CLI auto-detects the XIAO ESP32-C6 by its USB vendor ID. If your board enumerates differently, test with clawlight led --port <device>, then pin it permanently via led_port in ~/.claude/clawlight/config.json.

FAQ

Which coding agents are supported? Claude Code, opencode, Codex CLI, and GitHub Copilot CLI. See supported agents for what clawlight install does for each and any per-agent quirks.

Does this work on Windows or Linux? Yes — the ClawLight CLI runs on macOS, Windows, and Linux. See the ClawLight CLI repo for per-platform notes.

Can I use my own ESP32? The firmware is open source and targets the Seeed Studio XIAO ESP32-C6 — the only board the ClawLight CLI auto-detects. Another board may work if you flash compatible firmware onto it and pin its serial device via led_port.

Can multiple machines drive one light? The light mirrors the machine it's plugged into over USB, so one machine drives it at a time.

My Copilot session doesn't show up Copilot fires no event when its TUI opens, so ClawLight only sees a session once you submit its first prompt. Type something and it'll appear. If Copilot was already running when you installed ClawLight, restart it too.

My opencode session doesn't show up opencode only loads plugins at startup, so restart any session that was already running when you ran clawlight install.

My Codex sessions are missing Codex support needs Codex CLI 0.144 or newer, and requires a one-time approval: run /hooks inside Codex and approve the new clawlight hook entries.