Release v1.6.0

Author: lowcache

DEVELOPMENT.md

@@ -6,6 +6,24 @@ one bug that ever took this plugin down on load was a syntax-level mistake that
 amount of live testing would have caught, because the shell simply refused to load the
 service and said nothing.
 
+## How it fits together
+
+- `pulse-svc.luau` is a headless service and the single source of truth. Hook events
+  arrive over IPC; every 5 s it also reads Claude Code's session files (hookless
+  detection, liveness, Esc-interrupt correction). It publishes a rollup to the
+  `claude.pulse` shared-state key.
+- `pulse.luau` (bar) and `orb.luau` (desktop) only render `claude.pulse`. The panels
+  (`sessions`, `answer`, `ask`, `consent`) render state and send IPC back; none holds
+  logic of its own.
+- `claude.luau` is the one place that talks to a model: the `/claude` launcher, and a
+  second `[[service]]` registration (`claude-ask`) so the ask panel's poke has an
+  IPC-addressable receiver.
+- `hooks/pulse.py` turns Claude Code hooks into events; `hooks/consent.py` is the
+  approval gate; `hooks/install.py` wires both into `~/.claude/settings.json`;
+  `hooks/pulse-emit` is the agent-agnostic emitter. The event format is in
+  [PROTOCOL.md](PROTOCOL.md).
+- `shim/noctalia-mcp.py` is the MCP server that gives `/claude` sessions desktop tools.
+
 ## The shell
 
 ```sh
@@ -90,6 +108,7 @@ The gates cannot tell you whether a panel renders or an IPC event lands. For tha
 ```sh
 ln -s "$PWD" ~/.local/share/noctalia/plugins/claude-companion
 noctalia msg plugins enable lowcache/claude-companion
+python3 ~/.local/share/noctalia/plugins/claude-companion/hooks/install.py   # hooks point at the symlink
 
 # reload after an edit
 noctalia msg plugins disable lowcache/claude-companion

PROTOCOL.md

@@ -156,6 +156,86 @@ pulse-emit tool_start - < hook.json          # session id from hook JSON
 PULSE_PID=$PPID pulse-emit turn_end aider-$PPID  # retire when that process exits
 ```
 
+## Ready-made adapters
+
+These setups call `pulse-emit` by name, so put it on your PATH once (catalog path shown; use your dev symlink if that's how you installed):
+
+```sh
+ln -s ~/.local/state/noctalia/plugins/materialized/community/claude-companion/hooks/pulse-emit ~/.local/bin/pulse-emit
+```
+
+Each one was checked against that project's current source on 2026-09-19; the opencode plugin was also run live, end to end. What you get differs by agent, because each exposes different hooks.
+
+### Gemini CLI
+
+`~/.gemini/settings.json`. Hooks are on by default, and Gemini expands `$GEMINI_SESSION_ID` (shell-escaped) before running the command. Keep these in your user settings: project-level hooks are blocked in untrusted folders.
+
+```json
+{
+  "hooks": {
+    "BeforeAgent":  [{ "hooks": [{ "type": "command", "command": "pulse-emit turn_start $GEMINI_SESSION_ID" }] }],
+    "BeforeTool":   [{ "matcher": "*", "hooks": [{ "type": "command", "command": "pulse-emit tool_start $GEMINI_SESSION_ID" }] }],
+    "Notification": [{ "hooks": [{ "type": "command", "command": "pulse-emit needs_attention $GEMINI_SESSION_ID" }] }],
+    "AfterAgent":   [{ "hooks": [{ "type": "command", "command": "pulse-emit turn_end $GEMINI_SESSION_ID" }] }],
+    "SessionEnd":   [{ "hooks": [{ "type": "command", "command": "pulse-emit session_end $GEMINI_SESSION_ID" }] }]
+  }
+}
+```
+
+`Notification` only fires for tool-permission prompts, which is exactly the needs-you case.
+
+### Codex CLI
+
+`~/.codex/hooks.json` (Codex's Claude-style hooks, enabled by default in current builds). The session id arrives as JSON on stdin, which is what `pulse-emit`'s `-` session argument reads. Two things to know: Codex shows a **Hooks need review** prompt the first time and runs nothing until you trust them, and this file rejects unknown keys, so don't add comments.
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit":  [{ "hooks": [{ "type": "command", "command": "pulse-emit turn_start -" }] }],
+    "PreToolUse":        [{ "hooks": [{ "type": "command", "command": "pulse-emit tool_start -" }] }],
+    "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "pulse-emit needs_attention -" }] }],
+    "Stop":              [{ "hooks": [{ "type": "command", "command": "pulse-emit turn_end -" }] }],
+    "SessionEnd":        [{ "hooks": [{ "type": "command", "command": "pulse-emit session_end -" }] }]
+  }
+}
+```
+
+The older `notify = [...]` setting in `config.toml` still works, but it only fires at the end of a turn and passes JSON as an argument, so the hooks above are the better fit.
+
+### opencode
+
+a plugin at `~/.config/opencode/plugin/pulse.ts`. opencode has no hook for quitting, so the plugin hands over its own process id and the pulse retires the session when opencode exits.
+
+```ts
+// Drives the Noctalia pulse from opencode. pulse-emit must be on PATH.
+export const Pulse = async ({ $ }) => {
+  const emit = (event, sid) =>
+    $`pulse-emit ${event} ${sid}`.env({ ...process.env, PULSE_PID: String(process.pid) }).quiet().nothrow()
+  return {
+    "chat.message": async (input) => { await emit("turn_start", input.sessionID) },
+    "tool.execute.before": async (input) => { await emit("tool_start", input.sessionID) },
+    "permission.ask": async (input) => { await emit("needs_attention", input.sessionID) },
+    event: async ({ event }) => {
+      const p = event.properties
+      if (event.type === "session.idle") await emit("turn_end", p.sessionID)
+      else if (event.type === "session.error" && p.sessionID) await emit("error", p.sessionID)
+      else if (event.type === "session.deleted") await emit("session_end", p.info.id)
+    },
+  }
+}
+```
+
+### aider
+
+`~/.aider.conf.yml`. aider has one hook: a command it runs whenever it's your turn again (a reply finished, or it's asking you to confirm something). It passes no session id, but the command runs as a direct child of aider, so `$PPID` is aider itself: one session per aider, retired when it exits.
+
+```yaml
+notifications: true
+notifications-command: "PULSE_PID=$PPID pulse-emit turn_end aider-$PPID"
+```
+
+Expect less here than elsewhere: a session appears once the first reply lands, there's no working state in between, and that one command can't tell "done" from "please confirm", so it reports done.
+
 ## Control events (not lifecycle)
 
 Everything above describes the eight **lifecycle** events, which say what an agent is

claude-companion

@@ -50,7 +50,7 @@ local ASK_NOTE = table.concat({
 }, " ")
 
 -- claude only; this is the single backend seam.
--- A quick-ask is promised as read-only (README "Usage"), so it must NOT inherit
+-- A quick-ask is promised as read-only (README "Use"), so it must NOT inherit
 -- the user's Claude config, where pre-authorized permissions would let a plain
 -- question run commands or edit files: --tools "" strips every built-in tool,
 -- --strict-mcp-config (with no --mcp-config) strips inherited MCP servers, and

claude.luau

@@ -90,16 +90,18 @@
           runtimeInputs = [
             pkgs.luau
             pkgs.python3
+            pkgs.coreutils
+            pkgs.gnugrep
+            pkgs.gnused
           ];
+          # Suite list comes from scripts/run-widget-specs.sh (D15); a copy here drifted
+          # and silently skipped the consent and ask suites.
           text = ''
             root="''${1:-$PWD}"
-            echo "── pulse-svc ──"; "${pulseSvcRunner pkgs}/bin/pulse-svc-test" "$root"
-            echo "── pulse ──";  "${pulseRunner pkgs}/bin/pulse-test" "$root"
-            echo "── orb ──";    "${orbRunner pkgs}/bin/orb-test" "$root"
-            echo "── answer ──"; "${answerRunner pkgs}/bin/answer-test" "$root"
-            echo "── sessions ──"; "${sessionsRunner pkgs}/bin/sessions-test" "$root"
-            echo "── shim (compositor abstraction) ──"; python3 "$root/tests/shim_spec.py"
-            echo "── manifest (settings contract) ──"; PLUGIN_ROOT="$root" python3 "$root/tests/manifest_spec.py"
+            echo "── widget specs ──"; bash "$root/scripts/run-widget-specs.sh" "$root"
+            for spec in "$root"/tests/*_spec.py; do
+              echo "── $(basename "$spec") ──"; PLUGIN_ROOT="$root" python3 "$spec"
+            done
           '';
         };
     in

nix/flake.nix

@@ -1,10 +1,10 @@
 # Claude Companion — a Claude Code companion for Noctalia v5.
 # Not a chat client: the terminal does the agentic work; this is the shell-side
-# body — senses, hands, and an attention pulse. See README.md for the design.
+# body — senses, hands, and an attention pulse. See DEVELOPMENT.md for the design.
 
 id = "lowcache/claude-companion"
 name = "Claude Companion"
-version = "1.5.1"
+version = "1.6.0"
 # Plugin API level this manifest targets — mandatory as of the Noctalia 5 beta
 # manifest parser (replaces the older min_noctalia gate). 3 is the oldest-supported
 # level and covers every feature this plugin uses ([[panel]], ui controls, plugin IPC