diff options
| author | Danilo M. <danix@danix.xyz> | 2026-11-16 13:05:12 +0100 |
|---|---|---|
| committer | Danilo M. <danix@danix.xyz> | 2026-11-16 13:05:12 +0100 |
| commit | e13880480330fc7421fd1b06a5669b118c59f2bb (patch) | |
| tree | 647e7d64d307363d4c3c326c667d16a891eed3ee /AGENTS.md | |
| download | agent-lamp-e13880480330fc7421fd1b06a5669b118c59f2bb.tar.gz agent-lamp-e13880480330fc7421fd1b06a5669b118c59f2bb.zip | |
Initial commit: agent-lamp agent notification light
agent-lamp drives an IKEA TRADFRI colour bulb as a notification light
for coding agents, Claude Code and opencode. This commit holds the
approved design spec, the repo docs and the GPLv2 license; the script
itself follows.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 48 |
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. |
