aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDanilo M. <danix@danix.xyz>2026-11-16 13:29:32 +0100
committerDanilo M. <danix@danix.xyz>2026-11-16 13:29:32 +0100
commit63c676e60b21334a2d21329b0d409da7908ba560 (patch)
treebafe15dcaae86c637e65cc85f5995749ed3774ac
parentff52144a55d994c642930df3378bcdb7f299e98f (diff)
downloadagent-lamp-63c676e60b21334a2d21329b0d409da7908ba560.tar.gz
agent-lamp-63c676e60b21334a2d21329b0d409da7908ba560.zip
docs: wiring and runtime notesHEADmaster
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
-rw-r--r--AGENTS.md17
-rw-r--r--README.md11
2 files changed, 28 insertions, 0 deletions
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. <danix@danix.xyz>