# agent-lamp design Date: 2026-11-16. Status: approved in brainstorming, not yet built. ## Goal Turn the IKEA TRADFRI colour bulb into a notification light for coding agents (Claude Code and opencode), so a glance at the room says whether an agent needs something. The bulb stops following the wallpaper accent: `udt-bulb` is retired and the bulb's only job becomes agent notifications. ## States and colours | State | Meaning | Colour | |--------------|------------------------------------------|--------| | `permission` | agent waits for a permission decision | purple | | `question` | agent waits for user input (questions) | amber | | `error` | agent failed or is blocked | red | | `complete` | agent finished its turn | green | Colours are module constants in `#rrggbb`, tuned on the real bulb. Display rules, evaluated every tick over all active sessions: - No active state: restore the bulb to its pre-notification snapshot, exit. - One distinct colour: that colour, steady, full brightness. - One distinct colour, and it is `permission` or `question` waiting longer than `ESCALATE` (120 s): soft breathe, brightness fading between high and low. This is the "still waiting" signal. - Several distinct colours (e.g. an error in one agent and a permission in another): slow crossfade cycle through them, about 4 s per colour. Escalation is not shown in this mode; the cycle already draws the eye. ## Architecture One executable Python script, `agent-lamp`, stdlib only, calling libcoap's `coap-client` for CoAP over DTLS-PSK (Python's stdlib cannot speak DTLS). Symlinked as `~/bin/agent-lamp`. ### CLI agent-lamp set or clear one session's state agent-lamp claude read a Claude Code hook payload on stdin agent-lamp reset clear every session, restore the bulb agent-lamp --pair HOST CODE pair with the gateway, record colour bulbs agent-lamp --selftest agent-lamp --run internal: the renderer loop `` accepts `permission`, `question`, `complete`, `error`, `clear`, plus the opencode-notifier aliases `user_message` and `user_cancelled` (both meaning `clear`). Any other word (e.g. `session_started`, `subagent_complete`) is ignored with exit 0, so callers never break. ### Claude Code mapping (`agent-lamp claude`) Reads the hook JSON (`hook_event_name`, `session_id`, `notification_type`, `tool_name`): | Hook | State | |---------------------------------------------|--------------| | Notification, `permission_prompt` | `permission` | | Notification, `elicitation_dialog` | `question` | | PreToolUse, tool `AskUserQuestion` | `question` | | Stop | `complete` | | StopFailure | `error` | | PostToolUse, UserPromptSubmit, SessionEnd | `clear` | Other notification types (`idle_prompt`, `auth_success`) are ignored. All hooks are registered `async` in `~/.claude/settings.json` so the lamp never slows the agent. ### opencode mapping The `@mohak34/opencode-notifier` plugin already runs one command for every event: `~/bin/notify-sound`. Its args become `["{event}", "{sessionID}"]`, and `notify-sound` forwards to `agent-lamp "$1" "$2"` in the background when it gets two arguments, before its quiet-mode check (quiet mutes sound, not the lamp). Claude Code calls `notify-sound claude` with one argument, so it is not forwarded and Claude events are never handled twice. Known limit: the notifier has no "permission granted" event, so an opencode permission stays purple until that session's next event or user message. ### State `$XDG_RUNTIME_DIR/agent-lamp/state.json`, `{session: {"state": s, "since": epoch}}`, read and written under `flock` on `state.lock`. A session holds at most one state; a new event replaces it, `clear` removes only that session. `reset` empties the file. ### Renderer Every state change spawns `agent-lamp --run` detached (`setsid`). `--run` takes a blocking `flock` on `run.lock`, so exactly one renderer drives the bulb and a late spawn waits its turn and then re-reads the state (it exits at once if empty). This avoids the race where an exiting renderer misses an event written while it restores the bulb. On start the renderer snapshots each bulb (`5850` on/off, `5851` brightness, `5709`/`5710` colour xy). Each tick it reads the state and applies the display rules, sending only what changed. When no state is left it restores the snapshot and exits, all while holding the state lock, so the decision to exit and the restore cannot interleave with a new event. "No lamp" mode: if `$XDG_RUNTIME_DIR/status.nolamp` holds `1`, the renderer restores the snapshot and idles (state kept). When the mode turns off it re-snapshots and resumes. The file is the quickshell `statusctl` mode format, read directly so quickshell need not be running. ### Gateway facts carried over from udt-bulb (verified on the real bulb) - Hue and saturation run 0..65279, brightness 0..254, `5712` transition in tenths of a second. - Any colour change switches a bulb on. Restoring an off bulb therefore sets colour first, then `5850: 0`. - A request setting colour and brightness at once stalls mid-fade, and a colour sent during a brightness fade is dropped. Colour and brightness go in separate requests, colour first, and the renderer never overlaps them (breathe changes brightness only, cycle changes colour only). - Pastel colours wash out to white; saturation is floored at 1.0. - After resume or login the gateway can take seconds to answer. A request that fails is retried on the next tick rather than waited for. ### Config `~/.config/agent-lamp/tradfri.json` (`host`, `identity`, `key`, `bulbs`), mode 0600, written by `--pair`. The existing `~/.config/udt/tradfri.json` is copied there once, so no re-pairing. No config or no `coap-client`: every command is a silent no-op. ## Cross-repo changes (retiring udt-bulb) - unified-desktop-theme: delete `bin/udt-bulb`; drop it from `install.sh` (link list and the post-install run) and from `udt-accent`'s helper lists; remove the bulb section from its AGENTS.md (and README if mentioned). - rofi-scripts `bin/udt-powermenu.sh`: `udt-bulb off` becomes `agent-lamp reset`. - hypr-theme `hypridle.conf`: `udt-bulb off` becomes `agent-lamp reset`; `udt-bulb on` after sleep is dropped. `sections/autostart.lua`: the shutdown hook runs `setsid -f agent-lamp reset` instead. - quickshell: `statusctl` gains a `nolamp` mode; the drawer gets a switch for it beside the other status toggles. `notify-sound` gains the forward to `agent-lamp`. - `~/.claude/settings.json`: async hooks calling `agent-lamp claude` for Notification, PreToolUse (matcher `AskUserQuestion`), PostToolUse, Stop, StopFailure, UserPromptSubmit, SessionEnd. - `~/.config/opencode/opencode-notifier.json`: command args `["{event}", "{sessionID}"]`. - Global AGENTS.md: a short operational entry saying the lamp exists, is driven automatically by hooks, and that `agent-lamp ` is available for manual signalling. - `~/.config/udt/tradfri.json` removed after the copy is verified. - my-dotfiles is a generated backup and is not touched. ## Testing `agent-lamp --selftest`, asserts only, `coap` faked: - state-word mapping, including notifier aliases and ignored words; - Claude hook JSON to state for every row of the mapping table; - the display rule chosen for: empty, one colour, escalated one colour, several colours; - `light_states` hue/saturation for a sample colour. On the real bulb, by hand: each state, escalation after 120 s, a two-colour cycle, nolamp toggle, and restore to both an on and an off bulb. ## Out of scope Per-bulb assignment, a long-lived service, stale-session expiry (logout's `agent-lamp reset` clears leftovers), Zigbee without the gateway.