From e13880480330fc7421fd1b06a5669b118c59f2bb Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Mon, 16 Nov 2026 13:05:12 +0100 Subject: Initial commit: agent-lamp agent notification light agent-lamp drives an IKEA TRADFRI colour bulb as a notification light for coding agents, Claude Code and opencode. This commit holds the approved design spec, the repo docs and the GPLv2 license; the script itself follows. Co-Authored-By: Claude Opus 5.5 --- .../specs/2026-11-16-agent-lamp-design.md | 171 +++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-16-agent-lamp-design.md (limited to 'docs/superpowers/specs') diff --git a/docs/superpowers/specs/2026-11-16-agent-lamp-design.md b/docs/superpowers/specs/2026-11-16-agent-lamp-design.md new file mode 100644 index 0000000..c65536d --- /dev/null +++ b/docs/superpowers/specs/2026-11-16-agent-lamp-design.md @@ -0,0 +1,171 @@ +# 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. -- cgit v1.2.3