aboutsummaryrefslogtreecommitdiffstats
path: root/AGENTS.md
blob: 3eada0c5d7c5b01de4b4f0c5df042eafea6919af (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
# 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.