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
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
|
# agent-lamp Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Drive the IKEA TRADFRI colour bulb as a notification light for Claude Code and opencode, and retire `udt-bulb`.
**Architecture:** One Python script, `agent-lamp`, stdlib only, calling libcoap's `coap-client`. Event commands record per-session states in a JSON file under `$XDG_RUNTIME_DIR/agent-lamp/` and spawn a detached renderer (`--run`), single-instance through `flock`, that snapshots the bulb, shows steady / breathing / cycling colour, and restores the snapshot when nothing is left. Hooks in Claude Code and the opencode notifier feed it; quickshell gets a `nolamp` mode.
**Tech Stack:** Python 3 stdlib, libcoap `coap-client`, bash, QML.
**Spec:** `docs/superpowers/specs/2026-11-16-agent-lamp-design.md`
**House rules for every task:** commits are GPG-signed by default (never disable signing, check `git log -1 --format=%G?` shows `G`); commit messages end with `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`; no em dashes; no personal data (a pre-commit hook enforces it). Only edit live repos, never `~/Programming/GIT/my-dotfiles`.
## Files
| Path | Change |
|------|--------|
| `agent-lamp/agent-lamp` | create: the whole tool |
| `~/bin/agent-lamp` | symlink to the above |
| `~/.config/agent-lamp/tradfri.json` | copied from `~/.config/udt/tradfri.json` |
| `~/.claude/settings.json` | add hooks |
| `~/.config/opencode/opencode-notifier.json` | command args |
| `quickshell/desktop/modules/status/{statusctl,notify-sound,StatusPage.qml,README.md,test-statusctl.sh,test-notify-sound.sh}`, `quickshell/shared/Status.qml` | `nolamp` mode, forward to agent-lamp |
| `unified-desktop-theme/{bin/udt-bulb,bin/udt-accent,install.sh,AGENTS.md}` | retire udt-bulb |
| `rofi-scripts/bin/udt-powermenu.sh` | `agent-lamp reset` |
| `hypr-theme/{hypridle.conf,sections/autostart.lua}` | `agent-lamp reset` |
| `~/.config/opencode/AGENTS.md` | operational entry |
---
### Task 1: Event words and Claude hook mapping
**Files:**
- Create: `~/Programming/GIT/agent-lamp/agent-lamp`
- [ ] **Step 1: Write the skeleton with the failing selftest**
Create `agent-lamp` with this content, then `chmod +x agent-lamp`:
```python
#!/usr/bin/env python3
# agent-lamp - IKEA TRADFRI bulb as a notification light for coding agents
# Copyright (C) 2026 Danilo M. <danix@danix.xyz>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License version 2 as
# published by the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
"""Light an IKEA TRADFRI colour bulb when a coding agent needs you.
Usage: agent-lamp STATE SESSION permission|question|error|complete|clear
agent-lamp claude 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, list its bulbs
agent-lamp --selftest
Purple: a permission waits. Amber: a question waits. Red: an agent failed.
Green: an agent finished. A permission or question left waiting starts to
breathe; several agents wanting different things cycle through their
colours. When nothing is left the bulb goes back to how it was. Unknown
state words do nothing, so hook callers never break. Without a paired
gateway or without coap-client, every command does nothing.
"""
import json
import sys
# Colours are tuned on the real bulb; only the hue survives the saturation
# floor, so they are effectively hue picks.
COLOURS = {"permission": "#a000ff", "question": "#ffa000",
"error": "#ff0000", "complete": "#00ff40"}
CLEARS = ("clear", "user_message", "user_cancelled")
def word(w):
"""The state a CLI or opencode-notifier event word means, or None."""
if w in COLOURS:
return w
return "clear" if w in CLEARS else None
def from_claude(payload):
"""(state, session) for a Claude Code hook payload, or None to ignore."""
raise NotImplementedError
def selftest():
assert word("permission") == "permission"
assert word("complete") == "complete"
assert word("user_message") == "clear"
assert word("user_cancelled") == "clear"
assert word("session_started") is None
assert word("reset") is None
def hook(event, **kw):
return from_claude({"hook_event_name": event, "session_id": "s", **kw})
assert hook("Notification", notification_type="permission_prompt") == ("permission", "s")
assert hook("Notification", notification_type="elicitation_dialog") == ("question", "s")
assert hook("Notification", notification_type="idle_prompt") is None
assert hook("PreToolUse", tool_name="AskUserQuestion") == ("question", "s")
assert hook("PreToolUse", tool_name="Bash") is None
assert hook("Stop") == ("complete", "s")
assert hook("StopFailure") == ("error", "s")
for clearing in ("PostToolUse", "UserPromptSubmit", "SessionEnd"):
assert hook(clearing) == ("clear", "s")
assert hook("SubagentStop") is None
assert from_claude({"hook_event_name": "Stop"}) is None
assert from_claude([]) is None
print("ok")
def main():
args = sys.argv[1:]
if args == ["--selftest"]:
return selftest()
sys.exit(__doc__.split("\n\n")[1])
if __name__ == "__main__":
main()
```
- [ ] **Step 2: Run it, expect failure**
Run: `./agent-lamp --selftest`
Expected: `NotImplementedError` traceback from `from_claude`.
- [ ] **Step 3: Implement `from_claude`**
Replace the `from_claude` body:
```python
def from_claude(payload):
"""(state, session) for a Claude Code hook payload, or None to ignore."""
if not isinstance(payload, dict) or not payload.get("session_id"):
return None
event = payload.get("hook_event_name")
if event == "Notification":
state = {"permission_prompt": "permission",
"elicitation_dialog": "question"}.get(payload.get("notification_type"))
elif event == "PreToolUse":
state = "question" if payload.get("tool_name") == "AskUserQuestion" else None
else:
state = {"Stop": "complete", "StopFailure": "error", "PostToolUse": "clear",
"UserPromptSubmit": "clear", "SessionEnd": "clear"}.get(event)
return (state, payload["session_id"]) if state else None
```
- [ ] **Step 4: Run it, expect pass**
Run: `./agent-lamp --selftest`
Expected: `ok`
- [ ] **Step 5: Commit**
```bash
git add agent-lamp
git commit -m "feat: event words and Claude Code hook mapping
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```
---
### Task 2: Session state and the display rule
**Files:**
- Modify: `~/Programming/GIT/agent-lamp/agent-lamp`
- [ ] **Step 1: Add the failing tests**
Add at the end of `selftest()`, before `print("ok")`:
```python
# apply: a session holds one state; the same state again keeps its
# start time, so repeated notifications do not reset the escalation.
s = {}
assert apply(s, "a", "permission", 10) and s == {"a": {"state": "permission", "since": 10}}
assert not apply(s, "a", "permission", 20) and s["a"]["since"] == 10
assert apply(s, "a", "complete", 30) and s["a"] == {"state": "complete", "since": 30}
assert apply(s, "b", "error", 30)
assert apply(s, "a", "clear", 40) and list(s) == ["b"]
assert not apply(s, "a", "clear", 40)
assert apply(s, None, "reset", 50) and s == {}
assert not apply(s, None, "reset", 50)
# frame: what the bulb shows at a moment, (colour, brightness) or None.
def st(state, since=0):
return {"state": state, "since": since}
assert frame({}, 0) is None
assert frame({"a": st("complete")}, 500) == (COLOURS["complete"], BRIGHT)
assert frame({"a": st("error"), "b": st("error")}, 5) == (COLOURS["error"], BRIGHT)
# Waiting past ESCALATE breathes; a finished agent never does.
waiting = ESCALATE + BREATHE
dim_at = waiting if int(waiting // BREATHE) % 2 else waiting + BREATHE
assert frame({"a": st("permission")}, dim_at) == (COLOURS["permission"], DIM)
assert frame({"a": st("permission")}, dim_at + BREATHE) == (COLOURS["permission"], BRIGHT)
assert frame({"a": st("question")}, dim_at) == (COLOURS["question"], DIM)
assert frame({"a": st("question", dim_at - 1)}, dim_at) == (COLOURS["question"], BRIGHT)
assert frame({"a": st("complete")}, dim_at) == (COLOURS["complete"], BRIGHT)
# Several colours cycle in priority order, at full brightness.
two = {"a": st("error"), "b": st("permission")}
assert frame(two, 0) == (COLOURS["permission"], BRIGHT)
assert frame(two, CYCLE) == (COLOURS["error"], BRIGHT)
assert frame(two, 2 * CYCLE) == (COLOURS["permission"], BRIGHT)
assert frame(two, dim_at)[1] == BRIGHT
```
- [ ] **Step 2: Run it, expect failure**
Run: `./agent-lamp --selftest`
Expected: `NameError: name 'apply' is not defined`
- [ ] **Step 3: Implement `apply`, `frame` and their constants**
Below `CLEARS` add:
```python
# Highest first: the order a multi-colour cycle walks.
PRIORITY = ("permission", "question", "error", "complete")
WAITING = ("permission", "question")
# Calibration. Brightness 0..254. Times in seconds.
BRIGHT = 254
DIM = 60
ESCALATE = 120 # a wait this long starts to breathe
BREATHE = 2 # each half of a breath
CYCLE = 4 # each colour of a multi-colour cycle
```
Below `from_claude` add:
```python
def apply(sessions, session, state, now):
"""Record one event in sessions, in place. True if anything changed."""
if state == "reset":
changed = bool(sessions)
sessions.clear()
return changed
if state == "clear":
return sessions.pop(session, None) is not None
if sessions.get(session, {}).get("state") == state:
return False
sessions[session] = {"state": state, "since": now}
return True
def frame(sessions, now):
"""(colour, brightness) the bulb shows at `now`, or None for nothing."""
active = [p for p in PRIORITY if any(v["state"] == p for v in sessions.values())]
if not active:
return None
if len(active) > 1:
return COLOURS[active[int(now // CYCLE) % len(active)]], BRIGHT
state = active[0]
since = min(v["since"] for v in sessions.values() if v["state"] == state)
if state in WAITING and now - since > ESCALATE and int(now // BREATHE) % 2:
return COLOURS[state], DIM
return COLOURS[state], BRIGHT
```
- [ ] **Step 4: Run it, expect pass**
Run: `./agent-lamp --selftest`
Expected: `ok`
- [ ] **Step 5: Commit**
```bash
git add agent-lamp
git commit -m "feat: per-session state and the steady, breathe, cycle rule
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```
---
### Task 3: Gateway, renderer, CLI and pairing
**Files:**
- Modify: `~/Programming/GIT/agent-lamp/agent-lamp`
- [ ] **Step 1: Add the failing tests**
Add at the end of `selftest()`, before `print("ok")`:
```python
# colour_state: hue from #rrggbb, saturation floored to full.
assert colour_state("#ff0000") == {"5707": 0, "5708": HUE_MAX, "5712": FADE}
pale = colour_state("#8080ff")
assert (pale["5707"], pale["5708"]) == (round(HUE_MAX * 2 / 3), HUE_MAX)
# show and restore against a fake gateway that records every request.
global coap
real, sent = coap, []
def fake(method, url, ident, key, payload=None):
sent.append((method, url, payload))
return json.dumps({LIGHT: [{"5850": 0, "5851": 120, "5709": 1, "5710": 2}]})
coap = fake
try:
auth, urls = ("i", "k"), ["u1"]
shown = show(urls, auth, ("#ff0000", BRIGHT), (None, None))
assert shown == ("#ff0000", BRIGHT)
# Colour first, brightness after, in requests of their own.
assert [p[LIGHT][0] for _, _, p in sent] == [
colour_state("#ff0000"), {"5850": 1, "5851": BRIGHT, "5712": FADE}]
sent.clear()
assert show(urls, auth, ("#ff0000", BRIGHT), shown) == shown and sent == []
show(urls, auth, ("#ff0000", DIM), shown)
assert [p[LIGHT][0] for _, _, p in sent] == [{"5850": 1, "5851": DIM, "5712": FADE}]
sent.clear()
snap = snapshot(urls, auth)
assert snap == [{"5850": 0, "5851": 120, "5709": 1, "5710": 2}]
sent.clear()
restore(urls, auth, snap)
# An off bulb gets its colour back, then is switched off.
assert [p[LIGHT][0] for _, _, p in sent] == [
{"5709": 1, "5710": 2, "5712": FADE}, {"5850": 0}]
coap = lambda *a, **k: None
assert snapshot(urls, auth) is None
assert show(urls, auth, ("#ff0000", BRIGHT), (None, None)) == (None, None)
finally:
coap = real
```
- [ ] **Step 2: Run it, expect failure**
Run: `./agent-lamp --selftest`
Expected: `NameError: name 'colour_state' is not defined`
- [ ] **Step 3: Implement the gateway, renderer, CLI and pairing**
Replace the import block with:
```python
import colorsys
import contextlib
import fcntl
import json
import os
import secrets
import shutil
import subprocess
import sys
import time
from pathlib import Path
```
Below the calibration constants add:
```python
TICK = 1 # renderer loop period
FADE = 20 # transition, tenths of a second
TIMEOUT = 5 # per gateway request
CONFIG = Path.home() / ".config/agent-lamp/tradfri.json"
RUNTIME = Path(os.environ.get("XDG_RUNTIME_DIR") or "/tmp")
DIR = RUNTIME / "agent-lamp"
# quickshell's statusctl mode file; read directly so the shell need not run.
NOLAMP = RUNTIME / "status.nolamp"
# IPSO object ids the gateway uses: 15001 devices, 3311 light control,
# 5850 on/off, 5851 brightness, 5707 hue, 5708 saturation, 5709/5710 colour
# xy, 5712 transition. Hue and saturation run 0..65279.
DEVICES, LIGHT = "15001", "3311"
HUE_MAX = 65279
```
Below `frame` add:
```python
def coap(method, url, ident, key, payload=None):
"""The response body of one coaps request, or None on any failure."""
cmd = ["coap-client", "-m", method, "-u", ident, "-k", key, "-B", str(TIMEOUT)]
if payload is not None:
cmd += ["-e", json.dumps(payload, separators=(",", ":"))]
try:
out = subprocess.run(cmd + [url], capture_output=True, text=True,
timeout=TIMEOUT + 2, check=True).stdout
except (subprocess.SubprocessError, OSError):
return None
return out.strip()
def put(url, auth, state):
return coap("put", url, *auth, {LIGHT: [state]}) is not None
def colour_state(colour):
"""The 3311 state fading to #rrggbb. Pastels wash out to white on the
bulb, so saturation is floored to full and only the hue counts."""
h, _, _ = colorsys.rgb_to_hsv(*(int(colour[i:i + 2], 16) / 255 for i in (1, 3, 5)))
return {"5707": round(h * HUE_MAX), "5708": HUE_MAX, "5712": FADE}
def show(urls, auth, target, shown):
"""Move the bulbs from `shown` to `target`; the new shown state.
The gateway drops part of a request setting colour and brightness at
once, so they go separately, colour first, and only what changed is sent.
On a failed request the old state is returned, so the next tick retries.
"""
colour, level = target
ok = True
for url in urls:
if colour != shown[0]:
ok &= put(url, auth, colour_state(colour))
if level != shown[1]:
ok &= put(url, auth, {"5850": 1, "5851": level, "5712": FADE})
return target if ok else shown
def snapshot(urls, auth):
"""Each bulb's on/off, brightness and colour, or None if one is silent."""
snap = []
for url in urls:
try:
light = json.loads(coap("get", url, *auth))[LIGHT][0]
snap.append({k: light[k] for k in ("5850", "5851", "5709", "5710")})
except (TypeError, ValueError, KeyError, IndexError):
return None
return snap
def restore(urls, auth, snap):
"""Put the bulbs back as snapshot. Any colour change switches a bulb on,
so an off bulb gets its colour first and is switched off after."""
for url, s in zip(urls, snap):
put(url, auth, {"5709": s["5709"], "5710": s["5710"], "5712": FADE})
put(url, auth, {"5850": 1, "5851": s["5851"], "5712": FADE} if s["5850"]
else {"5850": 0})
def configured():
"""The gateway config, or None when there is nothing to drive."""
try:
cfg = json.loads(CONFIG.read_text())
except (OSError, ValueError):
return None
if not cfg.get("bulbs") or not shutil.which("coap-client"):
return None
return cfg
@contextlib.contextmanager
def locked():
"""Hold the state lock: every read-modify-write of the state is inside."""
DIR.mkdir(parents=True, exist_ok=True)
with open(DIR / "state.lock", "w") as f:
fcntl.flock(f, fcntl.LOCK_EX)
yield
def load():
try:
return json.loads((DIR / "state.json").read_text())
except (OSError, ValueError):
return {}
def save(sessions):
tmp = DIR / "state.json.tmp"
tmp.write_text(json.dumps(sessions))
tmp.replace(DIR / "state.json")
def nolamp():
try:
return NOLAMP.read_text().strip() == "1"
except OSError:
return False
def update(session, state):
"""Record one event and wake the renderer if the state changed."""
if not configured():
return
with locked():
sessions = load()
changed = apply(sessions, session, state, time.time())
if changed:
save(sessions)
if changed and state != "reset":
subprocess.Popen([sys.executable, str(Path(__file__).resolve()), "--run"],
stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL, start_new_session=True)
def wait_renderer(seconds):
"""Return once no renderer holds the run lock, or after `seconds`.
`reset` runs right before logout, suspend or poweroff; waiting lets the
renderer restore the bulb before the network goes.
"""
DIR.mkdir(parents=True, exist_ok=True)
end = time.monotonic() + seconds
with open(DIR / "run.lock", "w") as f:
while time.monotonic() < end:
try:
fcntl.flock(f, fcntl.LOCK_EX | fcntl.LOCK_NB)
return
except BlockingIOError:
time.sleep(0.2)
def run():
"""The renderer: one at a time, by the run lock; a late one waits its
turn and exits at once if nothing is left by then. The exit decision and
the restore happen under the state lock, so no event slips between them.
"""
cfg = configured()
if not cfg:
return
auth = cfg["identity"], cfg["key"]
urls = [f"coaps://{cfg['host']}:5684/{DEVICES}/{b}" for b in cfg["bulbs"]]
DIR.mkdir(parents=True, exist_ok=True)
with open(DIR / "run.lock", "w") as lock:
fcntl.flock(lock, fcntl.LOCK_EX)
snap, shown = None, (None, None)
while True:
with locked():
target = frame(load(), time.time())
paused = nolamp()
if (target is None or paused) and snap:
restore(urls, auth, snap)
snap, shown = None, (None, None)
if target is None:
return
if not paused:
# ponytail: a silent gateway (just after resume) is retried
# every tick, no backoff; add one if it ever floods the log.
if snap is None:
snap = snapshot(urls, auth)
if snap is not None:
shown = show(urls, auth, target, shown)
time.sleep(TICK)
def pair(host, code):
ident = "agent-lamp-" + secrets.token_hex(4)
base = f"coaps://{host}:5684"
reply = coap("post", f"{base}/15011/9063", "Client_identity", code, {"9090": ident})
try:
key = json.loads(reply)["9091"]
except (TypeError, ValueError, KeyError):
sys.exit(f"agent-lamp: pairing with {host} failed: {reply or 'no reply'}")
bulbs = []
for dev in json.loads(coap("get", f"{base}/{DEVICES}", ident, key) or "[]"):
info = json.loads(coap("get", f"{base}/{DEVICES}/{dev}", ident, key) or "{}")
# Colour bulbs report a hue; white-spectrum ones only a colour temperature.
if "5707" in (info.get(LIGHT) or [{}])[0]:
bulbs.append(str(dev))
print(f"{dev}: {info.get('9001', '?')}")
CONFIG.parent.mkdir(parents=True, exist_ok=True)
CONFIG.write_text(json.dumps({"host": host, "identity": ident, "key": key,
"bulbs": bulbs}))
CONFIG.chmod(0o600)
print(f"{len(bulbs)} colour bulb(s) recorded in {CONFIG}")
```
Replace `main()` with:
```python
def main():
args = sys.argv[1:]
if args == ["--selftest"]:
return selftest()
if args == ["--run"]:
return run()
if len(args) == 3 and args[0] == "--pair":
return pair(*args[1:])
if args == ["reset"]:
update(None, "reset")
return wait_renderer(15)
if args == ["claude"]:
try:
event = from_claude(json.load(sys.stdin))
except ValueError:
return
if event:
update(event[1], event[0])
return
if len(args) == 2:
state = word(args[0])
if state:
update(args[1], state)
return
sys.exit(__doc__.split("\n\n")[1])
```
- [ ] **Step 4: Run it, expect pass**
Run: `./agent-lamp --selftest`
Expected: `ok`
- [ ] **Step 5: Check the no-config path is silent**
Run: `HOME=$(mktemp -d) ./agent-lamp permission s; echo "exit $?"; ./agent-lamp bogus s; echo "exit $?"; ./agent-lamp; echo "exit $?"`
Expected: `exit 0`, `exit 0`, then the usage block and `exit 1`.
- [ ] **Step 6: Commit**
```bash
git add agent-lamp
git commit -m "feat: gateway, renderer, CLI and pairing
The renderer snapshots the bulb, shows the frame each tick and restores
the snapshot when no state is left or the nolamp mode is on.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```
---
### Task 4: Install and verify on the real bulb
**Files:**
- Create: `~/bin/agent-lamp` (symlink), `~/.config/agent-lamp/tradfri.json` (copy)
- [ ] **Step 1: Install**
```bash
ln -s ~/Programming/GIT/agent-lamp/agent-lamp ~/bin/agent-lamp
mkdir -p ~/.config/agent-lamp
install -m 600 ~/.config/udt/tradfri.json ~/.config/agent-lamp/tradfri.json
```
- [ ] **Step 2: Walk the states with the user watching the bulb**
Run each, one at a time, asking the user what the bulb shows:
```bash
agent-lamp permission t1 # purple, steady
agent-lamp question t1 # amber, steady (t1 replaced)
agent-lamp error t2 # cycle amber / red, ~4 s each
agent-lamp clear t1 # red, steady
agent-lamp complete t2 # green, steady
agent-lamp clear t2 # back to the pre-test state
```
Then escalation: `agent-lamp permission t3`, wait 2+ minutes, expect purple breathing; `agent-lamp reset` restores the bulb and returns once it has.
Then restore-to-off: switch the bulb off with its remote, `agent-lamp complete t4`, expect green; `agent-lamp clear t4`, expect off.
Then nolamp: `agent-lamp error t5`; `printf '1\n' > "$XDG_RUNTIME_DIR/status.nolamp"`, expect the pre-test state within a second; `printf '0\n' > "$XDG_RUNTIME_DIR/status.nolamp"`, expect red; `agent-lamp reset`.
Check `pgrep -f 'agent-lamp --run'` prints nothing after each final clear.
- [ ] **Step 3: Tune**
If a colour reads wrong, adjust `COLOURS` (or `DIM`, `CYCLE`, `BREATHE`) per the user, re-run `./agent-lamp --selftest`, and commit:
```bash
git add agent-lamp
git commit -m "tune: colours on the real bulb
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```
Skip the commit if nothing changed.
---
### Task 5: Claude Code hooks
**Files:**
- Modify: `~/.claude/settings.json` (not a repo)
- [ ] **Step 1: Add the hooks**
Use the `update-config` skill, or edit with a short Python script, to add these entries under `hooks`, keeping the existing Notification (`notify-sound claude`) and UserPromptSubmit (`ponytail-reinject.sh`) hooks as they are. Each event gets one more group:
```json
"Notification": [{"hooks": [{"type": "command", "command": "~/bin/agent-lamp claude", "async": true}]}],
"PreToolUse": [{"matcher": "AskUserQuestion", "hooks": [{"type": "command", "command": "~/bin/agent-lamp claude", "async": true}]}],
"PostToolUse": [{"hooks": [{"type": "command", "command": "~/bin/agent-lamp claude", "async": true}]}],
"Stop": [{"hooks": [{"type": "command", "command": "~/bin/agent-lamp claude", "async": true}]}],
"StopFailure": [{"hooks": [{"type": "command", "command": "~/bin/agent-lamp claude", "async": true}]}],
"UserPromptSubmit": [{"hooks": [{"type": "command", "command": "~/bin/agent-lamp claude", "async": true}]}],
"SessionEnd": [{"hooks": [{"type": "command", "command": "~/bin/agent-lamp claude", "async": true}]}]
```
(These are appended groups: for Notification and UserPromptSubmit the list then holds two groups.)
- [ ] **Step 2: Validate**
Run: `python3 -m json.tool ~/.claude/settings.json >/dev/null && echo valid`
Expected: `valid`
- [ ] **Step 3: Verify live**
In a new Claude Code session, ask it to run a command that needs permission: bulb turns purple; approve: bulb clears (PostToolUse); at the end of its turn: green; send a prompt: back to the pre-test state.
---
### Task 6: quickshell `nolamp` mode and the notify-sound forward
**Files:**
- Modify: `quickshell/desktop/modules/status/statusctl:28`
- Modify: `quickshell/shared/Status.qml` (property, count, setMode, toggleMode, ModeFile)
- Modify: `quickshell/desktop/modules/status/StatusPage.qml` (row after Quiet)
- Modify: `quickshell/desktop/modules/status/notify-sound`
- Modify: `quickshell/desktop/modules/status/test-statusctl.sh`, `test-notify-sound.sh`, `README.md`
All paths below are under `~/Programming/GIT/quickshell`.
- [ ] **Step 1: Failing statusctl test**
In `desktop/modules/status/test-statusctl.sh`, after the `quiet toggle from 1` check, add:
```bash
# nolamp keeps agent-lamp's bulb dark; a plain mode like quiet.
"$ctl" nolamp set 1
check "nolamp set 1" "1" "$("$ctl" nolamp get)"
"$ctl" nolamp toggle
check "nolamp toggle from 1" "0" "$("$ctl" nolamp get)"
```
Run: `desktop/modules/status/test-statusctl.sh`
Expected: FAIL lines for both nolamp checks (`unknown mode: nolamp`).
- [ ] **Step 2: Add the mode to statusctl**
In `desktop/modules/status/statusctl` change:
```bash
MODES="dnd presentation nolock quiet"
```
to
```bash
MODES="dnd presentation nolock quiet nolamp"
```
Run: `desktop/modules/status/test-statusctl.sh`
Expected: all `ok`, exit 0.
- [ ] **Step 3: Failing notify-sound test**
Read `desktop/modules/status/test-notify-sound.sh` to the end first. It fakes `paplay` in `$tmp/bin`; add a fake `agent-lamp` the same way, right after the `paplay` fake:
```bash
printf '#!/bin/sh\nprintf "%%s %%s\\n" "$1" "$2" >> "%s/lamp"\n' "$tmp" > "$tmp/bin/agent-lamp"
chmod +x "$tmp/bin/agent-lamp"
```
and before the final pass/fail summary add:
```bash
# Two arguments (opencode's event and session) are forwarded to agent-lamp,
# even in quiet mode; Claude's single argument never is.
rm -f "$tmp/lamp"
"$here/notify-sound" claude
"$here/notify-sound" permission ses1
"$here/statusctl" quiet set 1
"$here/notify-sound" complete ses2
sleep 0.2
check "lamp forward" "permission ses1|complete ses2" "$(paste -sd'|' "$tmp/lamp" 2>/dev/null)"
```
Run: `desktop/modules/status/test-notify-sound.sh`
Expected: FAIL `lamp forward`.
- [ ] **Step 4: Forward in notify-sound**
In `desktop/modules/status/notify-sound`, directly after `here=...` and before the quiet check, add:
```bash
# opencode's notifier passes its event and session id: forward them to the
# agent lamp, before the quiet check, since quiet mutes sound and not light.
# Claude Code passes one argument and has hooks of its own for the lamp.
if [[ $# -eq 2 ]] && command -v agent-lamp >/dev/null; then
agent-lamp "$1" "$2" </dev/null >/dev/null 2>&1 &
fi
```
Also extend the header usage comment line for opencode to `notify-sound <event> <session>`.
Run: `desktop/modules/status/test-notify-sound.sh`
Expected: all `ok`, exit 0.
- [ ] **Step 5: Status singleton**
In `shared/Status.qml`:
After the `quiet` property add:
```qml
// Keeps agent-lamp's bulb dark; agent-lamp reads the file itself, so
// this is only the drawer's view of it.
readonly property bool nolamp: nolampFile.value
```
Change `activeCount` to add `+ (root.nolamp ? 1 : 0)`:
```qml
readonly property int activeCount: (root.dnd ? 1 : 0) + (root.presentation ? 1 : 0)
+ (root.nolock ? 1 : 0) + (root.quiet ? 1 : 0)
+ (root.nolamp ? 1 : 0)
```
In `setMode`, after the `quiet` branch:
```qml
} else if (name === "nolamp") {
nolampFile.write(on);
```
In `toggleMode` add:
```qml
else if (name === "nolamp") root.setMode("nolamp", !root.nolamp);
```
After the `quietFile` ModeFile:
```qml
ModeFile { id: nolampFile; path: root.dir + "/status.nolamp" }
```
- [ ] **Step 6: Drawer row**
In `desktop/modules/status/StatusPage.qml`, after the Quiet `StatusRow` add:
```qml
Rectangle {
width: page.width
height: 1
color: Qt.alpha(Theme.text, 0.08)
}
StatusRow {
width: page.width
mode: "nolamp"
label: "No lamp"
description: "Keeps the agent lamp dark, for a film. Agents still notify on screen."
value: Status.nolamp
}
```
- [ ] **Step 7: README**
In `desktop/modules/status/README.md`: add `nolamp` to the mode list in the first paragraph, add `$XDG_RUNTIME_DIR/status.nolamp` to the files block, and after the `quiet` paragraph add:
```markdown
`nolamp` keeps the agent lamp (the sibling agent-lamp repo) dark. The shell
does nothing with it: agent-lamp's renderer reads the file each second and
restores the bulb while it is 1, keeping the agents' states for when it
turns off. `notify-sound` forwards the opencode notifier's two arguments
(`<event> <session>`) to `agent-lamp`, before the quiet check.
```
- [ ] **Step 8: See it**
Reload quickshell, open the drawer's status page, screenshot (`grim -o DP-1 <scratchpad>/status.png`, path in the session scratchpad) and check the No lamp row renders and toggles `statusctl nolamp get`.
- [ ] **Step 9: Commit**
```bash
git add desktop/modules/status shared/Status.qml
git commit -m "status: nolamp mode and the agent-lamp forward
nolamp keeps agent-lamp's bulb dark; notify-sound forwards opencode's
event and session to agent-lamp before the quiet check.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```
---
### Task 7: opencode notifier args
**Files:**
- Modify: `~/.config/opencode/opencode-notifier.json` (not a repo)
- [ ] **Step 1: Edit**
Change `"args": ["{event}"]` to:
```json
"args": [
"{event}",
"{sessionID}"
]
```
Run: `python3 -m json.tool ~/.config/opencode/opencode-notifier.json >/dev/null && echo valid`
Expected: `valid`
- [ ] **Step 2: Verify live**
Restart opencode, trigger a permission prompt: purple; answer and send a message: restored.
---
### Task 8: Retire udt-bulb
**Files:**
- Delete: `unified-desktop-theme/bin/udt-bulb`, `~/bin/udt-bulb` symlink
- Modify: `unified-desktop-theme/install.sh:108,437-439`, `unified-desktop-theme/bin/udt-accent:670-674,938-939`, `unified-desktop-theme/AGENTS.md:65,283-295,369`
- Modify: `rofi-scripts/bin/udt-powermenu.sh:65,71,77`
- Modify: `hypr-theme/hypridle.conf:14,19,59`, `hypr-theme/sections/autostart.lua:33-40`
- [ ] **Step 1: unified-desktop-theme**
In `~/Programming/GIT/unified-desktop-theme`:
```bash
git rm bin/udt-bulb
command rm ~/bin/udt-bulb
```
`install.sh:108`: drop `udt-bulb` from the `for f in ...` list.
`install.sh:437-439`: delete the whole `c_bulb() { ... }` function and the blank line after it.
`bin/udt-accent:670-672`: these three comment lines
```python
# The LED strip waits up to 20 s for its address broadcast, the bulbs
# up to 5 s per bulb for the gateway. All of them read files written above;
# udt-tv is a single UDP datagram to the TV launcher.
```
become
```python
# The LED strip waits up to 20 s for its address broadcast. All of them
# read files written above; udt-tv is a single UDP datagram to the TV
# launcher.
```
and line 674 drops `"udt-bulb", ` from the tuple.
`bin/udt-accent:938-939`: drop `"udt-bulb", ` from the `helpers` set.
`AGENTS.md`: delete the `udt-bulb` paragraph (lines 283-295, from "`udt-bulb` does the same" to "separately."); line 65 "keyboard, strip, bulbs and TV" becomes "keyboard, strip and TV"; line 369 "the LED strip and the TRADFRI bulbs do" becomes "and the LED strip do" (fix the list's commas so it reads right).
Check nothing is left: `grep -rn -i 'bulb\|tradfri' --exclude-dir=.git .` prints nothing.
Run: `bin/udt-accent --selftest && bin/udt-palette --selftest && bash -n install.sh && tests/ini-merge.sh`
Expected: all pass.
```bash
git add -A
git commit -m "Retire udt-bulb: the bulb is now agent-lamp's
The TRADFRI bulb no longer follows the wallpaper accent. It became a
notification light for coding agents, in the separate agent-lamp repo.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```
- [ ] **Step 2: rofi-scripts**
In `~/Programming/GIT/rofi-scripts/bin/udt-powermenu.sh`, each of the three `udt-bulb off` lines (65, 71, 77) becomes `agent-lamp reset`.
Run: `bash -n bin/udt-powermenu.sh && grep -c 'agent-lamp reset' bin/udt-powermenu.sh`
Expected: `3`
```bash
git add bin/udt-powermenu.sh
git commit -m "powermenu: restore the agent lamp instead of udt-bulb off
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```
- [ ] **Step 3: hypr-theme**
In `~/Programming/GIT/hypr-theme`:
`hypridle.conf:14`: `udt-bulb off` becomes `agent-lamp reset`.
`hypridle.conf:19`: delete `; udt-bulb on` (the line ends with `udt-ledstrip on`).
`hypridle.conf:59`: `udt-bulb off` becomes `agent-lamp reset`.
`sections/autostart.lua`: the comment becomes
```lua
-- The LED strip goes dark on logout and the agent lamp goes back to how it
-- was. Poweroff and reboot do the same in udt-powermenu.sh, since rc.6 drops
-- the network before Hyprland hears this.
```
and `hl.exec_cmd("setsid -f udt-bulb off")` becomes `hl.exec_cmd("setsid -f agent-lamp reset")`.
Run: `grep -rn 'udt-bulb' . --exclude-dir=.git` prints nothing; `luac -p sections/autostart.lua 2>/dev/null || lua -e 'loadfile("sections/autostart.lua")'` reports no syntax error (skip if neither is installed and say so).
```bash
git add hypridle.conf sections/autostart.lua
git commit -m "agent-lamp reset replaces udt-bulb on sleep and logout
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
```
Tell the user hypridle reads its config at start, so the change applies after a hypridle restart or the next login.
- [ ] **Step 4: Push all three repos**
`git push` in unified-desktop-theme, rofi-scripts, hypr-theme and quickshell (each `origin` may fan out to several remotes; that is expected).
- [ ] **Step 5: Remove the old config**
After Task 4 passed with the copied config: `command rm ~/.config/udt/tradfri.json`.
---
### Task 9: Global AGENTS.md entry and agent-lamp docs
**Files:**
- Modify: `~/.config/opencode/AGENTS.md` (not a repo; the file Claude Code's CLAUDE.md imports)
- Modify: `~/Programming/GIT/agent-lamp/README.md`, `AGENTS.md`
- [ ] **Step 1: Global entry**
In `~/.config/opencode/AGENTS.md`, after the "Shell aliases in agent shells" section and before the `---` above "Declarative preferences", add:
```markdown
## Agent lamp
A TRADFRI colour bulb in the room is a notification light for agents,
driven by `agent-lamp` (repo `~/Programming/GIT/agent-lamp`). Purple: a
permission waits; amber: a question waits; red: failed or blocked; green:
finished. Claude Code hooks and opencode's notifier drive it automatically,
so normal use needs no action. For a signal no hook covers (e.g. a long
background job finished, or blocked outside a tool call), run
`agent-lamp <permission|question|error|complete|clear> <session-id>`; the
lamp clears on the user's next prompt. Never run `agent-lamp reset` or
`--pair` unasked: reset clears every agent's state. `statusctl nolamp` (the
quickshell drawer's "No lamp") keeps it dark; respect it, do not toggle it.
(verified: 2026-11-16, depends on the hooks in `~/.claude/settings.json`
and the notifier's command args; re-check if those change.)
```
- [ ] **Step 2: Repo docs**
In the agent-lamp `README.md`, add after Usage:
```markdown
## Wiring
- Claude Code: async hooks running `agent-lamp claude` on Notification,
PreToolUse (matcher `AskUserQuestion`), PostToolUse, Stop, StopFailure,
UserPromptSubmit and SessionEnd.
- opencode: `@mohak34/opencode-notifier` with `"command": {"path":
"notify-sound", "args": ["{event}", "{sessionID}"]}`; quickshell's
`notify-sound` forwards both arguments to `agent-lamp`.
- `agent-lamp reset` at logout, suspend and poweroff.
- `$XDG_RUNTIME_DIR/status.nolamp` holding `1` keeps the bulb dark.
```
In the agent-lamp `AGENTS.md`, add before "Conventions":
```markdown
## Runtime
- State: `$XDG_RUNTIME_DIR/agent-lamp/state.json`, every read-modify-write
under `flock` on `state.lock`. The renderer (`--run`) holds `run.lock`
for its whole life; event commands spawn one only when the state changed.
- Install is a symlink, `~/bin/agent-lamp`, so edits are live; a running
renderer keeps the old code until it exits.
- The known limit: opencode's notifier has no "permission granted" event,
so an opencode permission stays purple until that session's next event.
```
Run: `./agent-lamp --selftest && grep -c '—' README.md AGENTS.md`
Expected: `ok`, then `0` for both files.
```bash
git add README.md AGENTS.md
git commit -m "docs: wiring and runtime notes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>"
git push
```
|