aboutsummaryrefslogtreecommitdiffstats
path: root/AGENTS.md
blob: 70fde0fc3d4fde34b54f0e7f3da4927966b0ebe4 (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
# 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).

## Runtime

- State: `$XDG_RUNTIME_DIR/agent-lamp/state.json`, every read-modify-write
  under `flock` on `state.lock`. One renderer (`--run`) at a time holds
  `run.lock`; a second exits at once. The renderer drops `run.lock` under
  the state lock when it decides to exit, and writers spawn only after
  releasing the state lock, so no event is lost. Spawns happen only when
  the state changed.
- A colour is never sent while a brightness fade runs (`level_at`): the
  gateway would drop it.
- `coap-client` exits 0 on a 4.xx/5.xx response and prints the code on
  stderr only; `coap()` treats that as failure.
- Install is a symlink, `~/bin/agent-lamp`, so edits are live; a running
  renderer keeps the old code until it exits.
- Known limit: opencode's notifier has no "permission granted" event, so an
  opencode permission stays purple until that session's next event.

## 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.