aboutsummaryrefslogtreecommitdiffstats
path: root/docs/superpowers/specs/2026-11-16-agent-lamp-design.md
blob: c65536defa02911dda4f7489e5c4b4963b467b53 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
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 <state> <session>   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

`<state>` 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 <state> <session>`
  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.