From 63c676e60b21334a2d21329b0d409da7908ba560 Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Mon, 16 Nov 2026 13:29:32 +0100 Subject: docs: wiring and runtime notes Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 17 +++++++++++++++++ README.md | 11 +++++++++++ 2 files changed, 28 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 3eada0c..70fde0f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,23 @@ longer follows the wallpaper accent. - 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. diff --git a/README.md b/README.md index 3d90699..f3f7af0 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,17 @@ Turns an IKEA TRADFRI colour bulb into a notification light for coding agents. P agent-lamp --pair HOST CODE pair with the gateway agent-lamp --selftest +## Wiring + +- Claude Code: async hooks running `agent-lamp claude` on Notification, + PreToolUse (matcher `AskUserQuestion`), PostToolUse, Stop, StopFailure, + UserPromptSubmit and SessionEnd. +- opencode: `@mohak34/opencode-notifier` with `"command": {"path": + "notify-sound", "args": ["{event}", "{sessionID}"]}`; quickshell's + `notify-sound` forwards both arguments to `agent-lamp`. +- `agent-lamp reset` at logout, suspend and poweroff. +- `$XDG_RUNTIME_DIR/status.nolamp` holding `1` keeps the bulb dark. + ## License Copyright (C) 2026 Danilo M. -- cgit v1.2.3