aboutsummaryrefslogtreecommitdiffstats
path: root/AGENTS.md
diff options
context:
space:
mode:
Diffstat (limited to 'AGENTS.md')
-rw-r--r--AGENTS.md48
1 files changed, 48 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3eada0c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,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.