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
|
# AGENTS.md
Guidance for AI coding agents working in this repository.
## What this is
`agent-lamp`: drives an IKEA TRADFRI colour bulb as a notification light for
coding agents (Claude Code and opencode). One Python script, stdlib only,
calling libcoap's `coap-client` for CoAP over DTLS-PSK, which Python's
stdlib cannot speak. Keep it a single file and do not add dependencies.
The design lives in `docs/superpowers/specs/2026-11-16-agent-lamp-design.md`.
It replaces `udt-bulb` from the unified-desktop-theme repo; the bulb no
longer follows the wallpaper accent.
## TRADFRI gateway facts (verified on the real bulb, inherited from udt-bulb)
- Bulbs are Zigbee with no address of their own. The gateway takes commands
over CoAP with DTLS-PSK on UDP 5684, IPSO object ids: `15001` devices,
`3311` light control, `5850` on/off, `5851` brightness (0..254), `5707`
hue and `5708` saturation (0..65279), `5709`/`5710` colour xy, `5712`
transition in tenths of a second.
- Any colour change switches a bulb on. To leave a bulb off, send colour
first, then `5850: 0`.
- A request setting colour and brightness together stalls mid-fade, and a
colour sent during a brightness fade is dropped. Send them separately,
colour first, and never overlap the two.
- Pastel colours wash out to white, so saturation is floored at 1.0.
- After resume or login the gateway can take seconds to answer.
- Pairing trades the security code on the gateway label for an identity and
key, stored in `~/.config/agent-lamp/tradfri.json` (mode 0600).
## Conventions
- Unknown state words exit 0 silently: hook callers must never break.
- Every agent hook that calls this is async; nothing here may block an agent.
- Placeholders only in code, docs, tests and commits.
## Testing
./agent-lamp --selftest
Anything touching the bulb itself is checked by hand on the real bulb.
## Repo facts
- License: GPLv2 only (`LICENSE`, header in each source file).
- Work directly on master.
|