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