claude-status-box 1.0.0

package/README.md

@@ -0,0 +1,65 @@
+# claude-status-box
+
+Drives the **claude-status** ESP32-C3 BLE indicator box (3 LEDs + buzzer +
+button) from Claude Code hooks on macOS. Installs a `claude-status` CLI.
+
+| State | Box | Meaning |
+|---|---|---|
+| `working` | green blinking | Claude is doing things |
+| `waiting` | red solid + beeps (20 s) | needs your attention |
+| `idle` | blue solid | done / ready |
+| `off` | everything off | — |
+
+The box also has a hardware button that acts as a real **spacebar** (it's a
+BLE keyboard) — with the keybinding this package installs, one press accepts
+the highlighted option in Claude Code's select prompts.
+
+Voice tip: with Claude Code voice in **hold** mode (`"voice": {"enabled":
+true, "mode": "hold"}` in `~/.claude/settings.json` — the default), holding
+the box's button is push-to-talk: dictation while held, stops on release.
+This package doesn't change voice settings; set the mode to taste.
+
+## Install
+
+```sh
+npm install -g claude-status-box
+```
+
+Postinstall does everything:
+
+1. Compiles a tiny Swift CoreBluetooth helper to `~/.claude-status/bin/`
+   (needs Xcode Command Line Tools: `xcode-select --install`).
+2. Installs 9 Claude Code hooks into `~/.claude/settings.json` (backup kept,
+   nothing else in the file is touched, re-install is idempotent).
+3. Adds `space → select:accept` (Select context) to `~/.claude/keybindings.json`
+   so the box's button accepts select prompts (never clobbers an existing
+   space binding).
+4. Pings the device.
+
+One-time hardware setup: power the box and pair **claude-status** in
+System Settings > Bluetooth (it appears as a keyboard — that's what keeps
+macOS holding a persistent connection).
+
+## How it works
+
+Hooks run `claude-status <state>` (async, debounced — repeated same-state
+events within 20 s never touch the radio). The Swift helper uses the
+connection macOS already holds to the device as a BLE HID keyboard
+(`retrieveConnectedPeripherals`, no scanning) and writes the state string to
+the custom GATT characteristic — sub-second, no daemon.
+
+macOS attributes the Bluetooth permission to your **terminal app** — allow it
+once in System Settings > Privacy & Security > Bluetooth if prompted.
+
+## Commands
+
+```sh
+claude-status test              # cycle working → waiting (buzzer!) → idle
+claude-status doctor            # full diagnostic: helper, device, hooks
+claude-status install-hooks     # re-run setup (also after moving npm prefix)
+claude-status uninstall-hooks   # remove our hooks, leave everything else
+claude-status write <payload>   # raw characteristic write (debug: g1, rb, z1, x…)
+claude-status working|waiting|idle|off   # what the hooks call
+```
+
+`npm uninstall -g claude-status-box` removes the hooks and `~/.claude-status/`.

package/bin/claude-status.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+'use strict';
+
+const { STATES, DEVICE_NAME } = require('../lib/constants');
+const helper = require('../lib/helper');
+const debounce = require('../lib/debounce');
+const hooks = require('../lib/hooks');
+const keybindings = require('../lib/keybindings');
+
+const USAGE = `usage:
+  claude-status <working|waiting|idle|off>   set indicator state (used by Claude Code hooks)
+  claude-status test                         cycle states on the device (LEDs + buzzer)
+  claude-status doctor                       diagnose device, helper, and hook setup
+  claude-status install-hooks                compile helper + (re)install Claude Code hooks
+  claude-status uninstall-hooks              remove our hooks from ~/.claude/settings.json
+  claude-status write <payload>              raw characteristic write (firmware debugging)`;
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// Hook path: must be fast and must never fail the hook. Repeated same-state
+// calls short-circuit before any BLE work.
+function setState(state) {
+  if (debounce.shouldSkip(state)) return;
+  debounce.record(state);
+  const res = helper.runHelper([state]);
+  if (res.code !== 0) {
+    debounce.clear();
+    helper.logError(`set ${state} failed (code ${res.code}): ${res.stderr.trim()}`);
+  }
+}
+
+function installHooks() {
+  const build = helper.ensureBuilt();
+  if (build.ok) {
+    console.log(build.skipped ? 'helper: up to date' : 'helper: compiled');
+  } else {
+    console.warn(`helper: NOT built — ${build.error}`);
+  }
+
+  const report = hooks.installHooks();
+  console.log(`hooks: installed ${report.added} (replaced ${report.removed}) → ${report.binPath} <state>`);
+  if (report.backupPath) console.log(`backup: ${report.backupPath}`);
+
+  const kb = keybindings.installBinding();
+  if (kb.status === 'conflict') {
+    console.warn(`keybinding: NOT set — space is already bound to "${kb.existing}" in the Select context`);
+  } else {
+    console.log(`keybinding: space → select:accept (${kb.status}) — the box's button acts as Space`);
+  }
+
+  if (build.ok) {
+    const ping = helper.runHelper(['ping'], { timeoutMs: 10_000 });
+    if (ping.code === 0) {
+      console.log(`device: ${DEVICE_NAME} connected ✓`);
+    } else {
+      console.warn(`device: not reachable yet — ${ping.stderr.trim() || 'run `claude-status doctor`'}`);
+    }
+  }
+}
+
+async function test() {
+  const build = helper.ensureBuilt();
+  if (!build.ok) {
+    console.error(build.error);
+    process.exit(1);
+  }
+  console.log('cycling states — watch the box:');
+  const steps = [
+    ['working', 'green blinking'],
+    ['waiting', 'red solid + beeps 0.5s on/0.5s off (auto-stops after 20s)'],
+    ['idle', 'blue solid'],
+  ];
+  for (const [state, expect] of steps) {
+    const res = helper.runHelper([state], { timeoutMs: 10_000 });
+    console.log(`  ${state.padEnd(7)} → ${res.code === 0 ? `ok (${expect})` : `FAILED: ${res.stderr.trim()}`}`);
+    if (res.code !== 0) process.exit(1);
+    await sleep(3000);
+  }
+  debounce.clear();
+  console.log('done — box should be blue (idle).');
+}
+
+function doctor() {
+  const { runDoctor } = require('../lib/doctor');
+  const checks = runDoctor();
+  let failed = 0;
+  for (const c of checks) {
+    if (!c.ok) failed++;
+    console.log(`${c.ok ? '✓' : '✗'} ${c.label}${c.detail ? ` — ${c.detail}` : ''}`);
+  }
+  process.exit(failed ? 1 : 0);
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+
+  if (STATES.includes(cmd)) {
+    setState(cmd);
+    return; // always exit 0 — hooks must never see a failure
+  }
+
+  switch (cmd) {
+    case 'test':
+      await test();
+      break;
+    case 'doctor':
+      doctor();
+      break;
+    case 'install-hooks':
+      installHooks();
+      break;
+    case 'uninstall-hooks': {
+      const report = hooks.uninstallHooks();
+      console.log(`hooks: removed ${report.removed}`);
+      if (report.backupPath) console.log(`backup: ${report.backupPath}`);
+      console.log(`keybinding: ${keybindings.uninstallBinding().status}`);
+      break;
+    }
+    case 'write': {
+      if (rest.length !== 1) {
+        console.error(USAGE);
+        process.exit(64);
+      }
+      const res = helper.runHelper(['write', rest[0]], { timeoutMs: 10_000 });
+      if (res.code !== 0) {
+        console.error(res.stderr.trim() || `helper exited ${res.code}`);
+        process.exit(1);
+      }
+      console.log('ok');
+      break;
+    }
+    default:
+      console.error(USAGE);
+      process.exit(64);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/lib/constants.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const os = require('node:os');
+const path = require('node:path');
+
+const DEVICE_NAME = 'claude-status';
+const STATES = ['working', 'waiting', 'idle', 'off'];
+
+// Claude Code hook event → indicator state
+const HOOK_EVENTS = {
+  UserPromptSubmit: 'working',
+  PostToolUse: 'working',
+  ElicitationResult: 'working',
+  PermissionRequest: 'waiting',
+  Elicitation: 'waiting',
+  Notification: 'waiting',
+  Stop: 'idle',
+  SessionStart: 'idle',
+  SessionEnd: 'idle',
+};
+
+// Identifies hooks written by this package (bare or absolute-path command),
+// regardless of which npm prefix installed them.
+const OUR_HOOK_RE = /(^|\/)claude-status (working|waiting|idle|off)\b/;
+
+const HOME_DIR = path.join(os.homedir(), '.claude-status');
+const HELPER_BIN = path.join(HOME_DIR, 'bin', 'claude-status-helper');
+const HELPER_HASH_FILE = path.join(HOME_DIR, 'helper.sha256');
+const ERROR_LOG = path.join(HOME_DIR, 'last-error.log');
+
+const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+const BACKUP_PREFIX = 'settings.json.claude-status.bak.';
+const BACKUPS_TO_KEEP = 3;
+
+// The box's hardware button sends a real Space keypress; this binding makes
+// Space accept the highlighted option in Claude Code's select prompts.
+const KEYBINDINGS_PATH = path.join(os.homedir(), '.claude', 'keybindings.json');
+const KEYBINDING_CONTEXT = 'Select';
+const KEYBINDING_KEY = 'space';
+const KEYBINDING_ACTION = 'select:accept';
+
+const STATE_FILE = path.join(os.tmpdir(), 'claude-status.state');
+const STATE_TTL_MS = 20_000;
+
+const SWIFT_SRC = path.join(__dirname, '..', 'src', 'claude-status-helper.swift');
+const INFO_PLIST = path.join(__dirname, '..', 'src', 'helper-Info.plist');
+
+const HELPER_TIMEOUT_MS = 3000; // helper's own wall clock
+const NODE_KILL_MS = 4000;      // backstop: kill the helper if it somehow hangs
+
+module.exports = {
+  DEVICE_NAME,
+  STATES,
+  HOOK_EVENTS,
+  OUR_HOOK_RE,
+  HOME_DIR,
+  HELPER_BIN,
+  HELPER_HASH_FILE,
+  ERROR_LOG,
+  SETTINGS_PATH,
+  BACKUP_PREFIX,
+  BACKUPS_TO_KEEP,
+  KEYBINDINGS_PATH,
+  KEYBINDING_CONTEXT,
+  KEYBINDING_KEY,
+  KEYBINDING_ACTION,
+  STATE_FILE,
+  STATE_TTL_MS,
+  SWIFT_SRC,
+  INFO_PLIST,
+  HELPER_TIMEOUT_MS,
+  NODE_KILL_MS,
+};

package/lib/debounce.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const fs = require('node:fs');
+
+const { STATE_FILE, STATE_TTL_MS } = require('./constants');
+
+// True when `state` was already sent within the TTL — the caller can skip
+// BLE entirely. Hook storms (PostToolUse firing "working" constantly) hit
+// this path; the TTL keeps a missed write self-healing under activity.
+function shouldSkip(state) {
+  try {
+    const [last, at] = fs.readFileSync(STATE_FILE, 'utf8').trim().split(' ');
+    return last === state && Date.now() - Number(at) < STATE_TTL_MS;
+  } catch {
+    return false;
+  }
+}
+
+// Record optimistically before writing over BLE; atomic rename prevents
+// torn reads from concurrent async hook invocations.
+function record(state) {
+  const tmp = `${STATE_FILE}.tmp.${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, `${state} ${Date.now()}\n`);
+    fs.renameSync(tmp, STATE_FILE);
+  } catch {
+    try { fs.unlinkSync(tmp); } catch {}
+  }
+}
+
+// Clear after a failed write so the next hook event retries instead of
+// being suppressed for the TTL.
+function clear() {
+  try { fs.unlinkSync(STATE_FILE); } catch {}
+}
+
+function current() {
+  try {
+    const [state, at] = fs.readFileSync(STATE_FILE, 'utf8').trim().split(' ');
+    return { state, ageMs: Date.now() - Number(at) };
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { shouldSkip, record, clear, current };

package/lib/doctor.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const fs = require('node:fs');
+
+const {
+  DEVICE_NAME,
+  HOOK_EVENTS,
+  HELPER_BIN,
+  SETTINGS_PATH,
+  ERROR_LOG,
+} = require('./constants');
+const { findSwiftc, isBuilt, runHelper } = require('./helper');
+const { readSettings, installedHookCount, globalBinPath } = require('./hooks');
+const debounce = require('./debounce');
+
+const PING_EXPLANATIONS = {
+  0: null,
+  2: 'Bluetooth off or permission denied — enable Bluetooth for your terminal app in System Settings > Privacy & Security > Bluetooth',
+  3: `"${DEVICE_NAME}" is not connected — power it on and pair it in System Settings > Bluetooth`,
+  4: 'ping timed out — Bluetooth may be initializing, or the TCC permission prompt is waiting for you',
+  missing: 'helper binary not compiled — run `claude-status install-hooks`',
+};
+
+function runDoctor() {
+  const checks = [];
+  const add = (ok, label, detail) => checks.push({ ok, label, detail });
+
+  add(process.platform === 'darwin', 'macOS', process.platform);
+
+  const swiftc = findSwiftc();
+  add(!!swiftc, 'swiftc (Xcode CLT)', swiftc || 'missing — run `xcode-select --install`');
+
+  const built = isBuilt();
+  add(built, 'helper compiled & current', built ? HELPER_BIN : 'missing/stale — run `claude-status install-hooks`');
+
+  if (built) {
+    const ping = runHelper(['ping'], { timeoutMs: 10_000 });
+    const explanation = PING_EXPLANATIONS[ping.code] ?? ping.stderr.trim();
+    add(ping.code === 0, `device "${DEVICE_NAME}" reachable`, ping.code === 0 ? ping.stdout.trim() : explanation);
+  }
+
+  let settingsOk = true;
+  try {
+    readSettings();
+  } catch (err) {
+    settingsOk = false;
+    add(false, 'settings.json valid', err.message);
+  }
+  if (settingsOk) {
+    add(true, 'settings.json valid', SETTINGS_PATH);
+    const expected = Object.keys(HOOK_EVENTS).length;
+    const count = installedHookCount();
+    add(count === expected, `hooks installed (${count}/${expected})`,
+      count === expected ? 'all events wired' : 'run `claude-status install-hooks`');
+  }
+
+  const { bindingInstalled } = require('./keybindings');
+  add(bindingInstalled(), 'keybinding space → select:accept',
+    bindingInstalled() ? 'box button accepts select prompts' : 'run `claude-status install-hooks`');
+
+  const binPath = globalBinPath();
+  add(fs.existsSync(binPath), 'CLI on expected path', binPath);
+
+  const state = debounce.current();
+  add(true, 'debounce state', state ? `${state.state} (${Math.round(state.ageMs / 1000)}s ago)` : 'none');
+  if (fs.existsSync(ERROR_LOG)) add(true, 'error log', ERROR_LOG);
+
+  return checks;
+}
+
+module.exports = { runDoctor };

package/lib/helper.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync, spawnSync } = require('node:child_process');
+
+const {
+  HELPER_BIN,
+  HELPER_HASH_FILE,
+  ERROR_LOG,
+  SWIFT_SRC,
+  INFO_PLIST,
+  HELPER_TIMEOUT_MS,
+  NODE_KILL_MS,
+} = require('./constants');
+
+function findSwiftc() {
+  for (const [cmd, args] of [['xcrun', ['--find', 'swiftc']], ['which', ['swiftc']]]) {
+    try {
+      const out = execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      if (out) return out;
+    } catch {
+      // try next
+    }
+  }
+  return null;
+}
+
+function sdkPath() {
+  try {
+    return execFileSync('xcrun', ['--sdk', 'macosx', '--show-sdk-path'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function sourceHash() {
+  return crypto.createHash('sha256').update(fs.readFileSync(SWIFT_SRC)).digest('hex');
+}
+
+function isBuilt() {
+  try {
+    fs.accessSync(HELPER_BIN, fs.constants.X_OK);
+    return fs.readFileSync(HELPER_HASH_FILE, 'utf8').trim() === sourceHash();
+  } catch {
+    return false;
+  }
+}
+
+// Compile the Swift helper if missing or stale. Never throws.
+function ensureBuilt() {
+  if (isBuilt()) return { ok: true, skipped: true };
+
+  const swiftc = findSwiftc();
+  if (!swiftc) {
+    return {
+      ok: false,
+      error: 'swiftc not found — install Xcode Command Line Tools (`xcode-select --install`), then run `claude-status install-hooks`',
+    };
+  }
+
+  fs.mkdirSync(path.dirname(HELPER_BIN), { recursive: true });
+  const args = [
+    '-O', SWIFT_SRC,
+    '-o', HELPER_BIN,
+    '-Xlinker', '-sectcreate', '-Xlinker', '__TEXT', '-Xlinker', '__info_plist', '-Xlinker', INFO_PLIST,
+  ];
+  // The raw toolchain swiftc can't resolve the SDK on its own (fails with
+  // "unable to load standard library") — pin it explicitly.
+  const sdk = sdkPath();
+  if (sdk) args.unshift('-sdk', sdk);
+  try {
+    execFileSync(swiftc, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 120_000 });
+  } catch (err) {
+    const detail = (err.stderr || err.message || 'unknown swiftc failure').toString();
+    try {
+      fs.mkdirSync(path.dirname(ERROR_LOG), { recursive: true });
+      fs.writeFileSync(ERROR_LOG, `[${new Date().toISOString()}] swiftc failed:\n${detail}\n`);
+    } catch {}
+    return { ok: false, error: `helper compilation failed (details in ${ERROR_LOG})` };
+  }
+  fs.writeFileSync(HELPER_HASH_FILE, sourceHash() + '\n');
+  return { ok: true, skipped: false };
+}
+
+// Run the helper. Returns { code, stdout, stderr } — code is null-ish
+// mapped to 'missing' when the binary isn't built, 4 on kill-by-timeout.
+function runHelper(args, { timeoutMs = HELPER_TIMEOUT_MS } = {}) {
+  if (!fs.existsSync(HELPER_BIN)) {
+    return { code: 'missing', stdout: '', stderr: 'helper not compiled — run `claude-status install-hooks`' };
+  }
+  const res = spawnSync(HELPER_BIN, [...args, '--timeout', String(timeoutMs)], {
+    encoding: 'utf8',
+    timeout: timeoutMs + (NODE_KILL_MS - HELPER_TIMEOUT_MS),
+  });
+  if (res.error || res.signal) {
+    return { code: 4, stdout: res.stdout || '', stderr: (res.stderr || '') + (res.error ? res.error.message : `killed by ${res.signal}`) };
+  }
+  return { code: res.status, stdout: res.stdout || '', stderr: res.stderr || '' };
+}
+
+function logError(line) {
+  try {
+    fs.mkdirSync(path.dirname(ERROR_LOG), { recursive: true });
+    let existing = '';
+    try { existing = fs.readFileSync(ERROR_LOG, 'utf8'); } catch {}
+    if (existing.length > 50_000) existing = existing.slice(-25_000);
+    fs.writeFileSync(ERROR_LOG, existing + `[${new Date().toISOString()}] ${line}\n`);
+  } catch {}
+}
+
+module.exports = { findSwiftc, ensureBuilt, isBuilt, runHelper, logError };

package/lib/hooks.js

@@ -0,0 +1,155 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+const {
+  HOOK_EVENTS,
+  OUR_HOOK_RE,
+  SETTINGS_PATH,
+  BACKUP_PREFIX,
+  BACKUPS_TO_KEEP,
+} = require('./constants');
+
+// Absolute path the hooks should invoke — hook shells are non-interactive
+// and may not have the npm global bin on PATH.
+function globalBinPath() {
+  const invoked = process.argv[1];
+  if (invoked && path.basename(invoked) === 'claude-status') return invoked;
+  try {
+    const prefix = execSync('npm prefix -g', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (prefix) return path.join(prefix, 'bin', 'claude-status');
+  } catch {}
+  return path.join(path.dirname(process.execPath), 'claude-status');
+}
+
+// Returns { settings, raw } — raw is null when the file doesn't exist yet.
+// Throws with a friendly message on unparseable JSON (never overwrite that).
+function readSettings() {
+  let raw = null;
+  try {
+    raw = fs.readFileSync(SETTINGS_PATH, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    return { settings: {}, raw: null };
+  }
+  try {
+    return { settings: JSON.parse(raw), raw };
+  } catch {
+    throw new Error(`${SETTINGS_PATH} is not valid JSON — left untouched; fix it and run \`claude-status install-hooks\``);
+  }
+}
+
+function backupSettings(raw) {
+  if (raw == null) return null;
+  const dir = path.dirname(SETTINGS_PATH);
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '').replace('T', '-');
+  const backupPath = path.join(dir, `${BACKUP_PREFIX}${stamp}`);
+  fs.writeFileSync(backupPath, raw);
+  const backups = fs.readdirSync(dir)
+    .filter((f) => f.startsWith(BACKUP_PREFIX))
+    .sort()
+    .reverse();
+  for (const stale of backups.slice(BACKUPS_TO_KEEP)) {
+    try { fs.unlinkSync(path.join(dir, stale)); } catch {}
+  }
+  return backupPath;
+}
+
+function writeSettings(settings) {
+  fs.mkdirSync(path.dirname(SETTINGS_PATH), { recursive: true });
+  const tmp = `${SETTINGS_PATH}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+  fs.renameSync(tmp, SETTINGS_PATH);
+}
+
+// Remove every hook entry whose command matches ours, pruning emptied
+// matcher groups and event keys. Mutates `settings`; returns removal count.
+function stripOurHooks(settings) {
+  let removed = 0;
+  const hooks = settings.hooks;
+  if (!hooks || typeof hooks !== 'object') return removed;
+  for (const event of Object.keys(hooks)) {
+    if (!Array.isArray(hooks[event])) continue;
+    for (const group of hooks[event]) {
+      if (!group || !Array.isArray(group.hooks)) continue;
+      const before = group.hooks.length;
+      group.hooks = group.hooks.filter(
+        (h) => !(h && typeof h.command === 'string' && OUR_HOOK_RE.test(h.command))
+      );
+      removed += before - group.hooks.length;
+    }
+    hooks[event] = hooks[event].filter((g) => !g || !Array.isArray(g.hooks) || g.hooks.length > 0);
+    if (hooks[event].length === 0) delete hooks[event];
+  }
+  if (Object.keys(hooks).length === 0) delete settings.hooks;
+  return removed;
+}
+
+function addOurHooks(settings, binPath) {
+  if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
+  for (const [event, state] of Object.entries(HOOK_EVENTS)) {
+    if (!Array.isArray(settings.hooks[event])) settings.hooks[event] = [];
+    settings.hooks[event].push({
+      hooks: [
+        {
+          type: 'command',
+          command: `${binPath} ${state}`,
+          timeout: 5,
+          async: true,
+        },
+      ],
+    });
+  }
+  return Object.keys(HOOK_EVENTS).length;
+}
+
+// Idempotent install: strip ours everywhere, then append the 9 hooks.
+function installHooks() {
+  const { settings, raw } = readSettings();
+  const backupPath = backupSettings(raw);
+  const removed = stripOurHooks(settings);
+  const binPath = globalBinPath();
+  const added = addOurHooks(settings, binPath);
+  writeSettings(settings);
+  return { added, removed, backupPath, binPath };
+}
+
+function uninstallHooks() {
+  const { settings, raw } = readSettings();
+  if (raw == null) return { removed: 0, backupPath: null };
+  const backupPath = backupSettings(raw);
+  const removed = stripOurHooks(settings);
+  writeSettings(settings);
+  return { removed, backupPath };
+}
+
+// How many of our hooks are installed per expected event (for doctor).
+function installedHookCount() {
+  let settings;
+  try {
+    ({ settings } = readSettings());
+  } catch {
+    return null;
+  }
+  let count = 0;
+  for (const event of Object.keys(HOOK_EVENTS)) {
+    const groups = settings.hooks?.[event];
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      for (const h of group?.hooks ?? []) {
+        if (h && typeof h.command === 'string' && OUR_HOOK_RE.test(h.command)) count++;
+      }
+    }
+  }
+  return count;
+}
+
+module.exports = {
+  globalBinPath,
+  readSettings,
+  installHooks,
+  uninstallHooks,
+  installedHookCount,
+};

package/lib/keybindings.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  KEYBINDINGS_PATH,
+  KEYBINDING_CONTEXT,
+  KEYBINDING_KEY,
+  KEYBINDING_ACTION,
+} = require('./constants');
+
+function read() {
+  let raw = null;
+  try {
+    raw = fs.readFileSync(KEYBINDINGS_PATH, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    return {
+      obj: { $schema: 'https://www.schemastore.org/claude-code-keybindings.json', bindings: [] },
+      raw: null,
+    };
+  }
+  try {
+    return { obj: JSON.parse(raw), raw };
+  } catch {
+    throw new Error(`${KEYBINDINGS_PATH} is not valid JSON — left untouched`);
+  }
+}
+
+function write(obj) {
+  fs.mkdirSync(path.dirname(KEYBINDINGS_PATH), { recursive: true });
+  const tmp = `${KEYBINDINGS_PATH}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n');
+  fs.renameSync(tmp, KEYBINDINGS_PATH);
+}
+
+function findContext(obj) {
+  if (!Array.isArray(obj.bindings)) obj.bindings = [];
+  return obj.bindings.find(
+    (b) => b && b.context === KEYBINDING_CONTEXT && b.bindings && typeof b.bindings === 'object'
+  );
+}
+
+// Idempotent: adds space→select:accept in the Select context. Never clobbers
+// a user's own space binding — reports a conflict instead.
+function installBinding() {
+  const { obj } = read();
+  const entry = findContext(obj);
+  if (entry) {
+    if (entry.bindings[KEYBINDING_KEY] === KEYBINDING_ACTION) return { status: 'present' };
+    if (KEYBINDING_KEY in entry.bindings) {
+      return { status: 'conflict', existing: entry.bindings[KEYBINDING_KEY] };
+    }
+    entry.bindings[KEYBINDING_KEY] = KEYBINDING_ACTION;
+  } else {
+    obj.bindings.push({ context: KEYBINDING_CONTEXT, bindings: { [KEYBINDING_KEY]: KEYBINDING_ACTION } });
+  }
+  write(obj);
+  return { status: 'added' };
+}
+
+// Removes only our exact binding; drops the context entry if it becomes empty.
+function uninstallBinding() {
+  let state;
+  try {
+    state = read();
+  } catch {
+    return { status: 'skipped' };
+  }
+  if (state.raw == null) return { status: 'absent' };
+  const entry = findContext(state.obj);
+  if (!entry || entry.bindings[KEYBINDING_KEY] !== KEYBINDING_ACTION) return { status: 'absent' };
+  delete entry.bindings[KEYBINDING_KEY];
+  if (Object.keys(entry.bindings).length === 0) {
+    state.obj.bindings = state.obj.bindings.filter((b) => b !== entry);
+  }
+  write(state.obj);
+  return { status: 'removed' };
+}
+
+function bindingInstalled() {
+  try {
+    const entry = findContext(read().obj);
+    return !!entry && entry.bindings[KEYBINDING_KEY] === KEYBINDING_ACTION;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { installBinding, uninstallBinding, bindingInstalled };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "claude-status-box",
+  "version": "1.0.0",
+  "description": "Drive the claude-status ESP32-C3 BLE indicator box (LEDs + buzzer + button) from Claude Code hooks",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "esp32",
+    "ble",
+    "status-light",
+    "hooks"
+  ],
+  "license": "MIT",
+  "bin": {
+    "claude-status": "bin/claude-status.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "src",
+    "scripts"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "preuninstall": "node scripts/preuninstall.js"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,69 @@
+'use strict';
+
+// Postinstall must NEVER fail the npm install — every problem becomes a
+// warning plus an actionable next step, and we always exit 0.
+
+function main() {
+  if (process.platform !== 'darwin') {
+    console.log('claude-status: macOS only — skipping setup.');
+    return;
+  }
+  if (process.env.CI) {
+    console.log('claude-status: CI detected — skipping setup.');
+    return;
+  }
+  if ((process.getuid && process.getuid() === 0) || process.env.SUDO_USER) {
+    console.log('claude-status: running as root — skipping setup so nothing lands in root\'s home.');
+    console.log('  Run `claude-status install-hooks` as your normal user to finish.');
+    return;
+  }
+
+  const helper = require('../lib/helper');
+  const hooks = require('../lib/hooks');
+  const { DEVICE_NAME } = require('../lib/constants');
+
+  const summary = [];
+
+  const build = helper.ensureBuilt();
+  summary.push(build.ok ? '✓ BLE helper compiled' : `✗ BLE helper: ${build.error}`);
+
+  try {
+    const report = hooks.installHooks();
+    summary.push(`✓ Claude Code hooks installed (${report.added} events → ${report.binPath} <state>)`);
+    if (report.backupPath) summary.push(`  settings backup: ${report.backupPath}`);
+  } catch (err) {
+    summary.push(`✗ hooks: ${err.message}`);
+  }
+
+  try {
+    const keybindings = require('../lib/keybindings');
+    const kb = keybindings.installBinding();
+    summary.push(kb.status === 'conflict'
+      ? `△ keybinding: space already bound to "${kb.existing}" in Select context — left as is`
+      : `✓ keybinding: space → select:accept (box button acts as Space)`);
+  } catch (err) {
+    summary.push(`✗ keybinding: ${err.message}`);
+  }
+
+  if (build.ok) {
+    const ping = helper.runHelper(['ping'], { timeoutMs: 10_000 });
+    if (ping.code === 0) {
+      summary.push(`✓ ${DEVICE_NAME} is connected`);
+    } else {
+      summary.push(`△ ${DEVICE_NAME} not reachable: ${ping.stderr.trim() || 'unknown'}`);
+      summary.push('  (power the box on and pair it in System Settings > Bluetooth, then `claude-status doctor`)');
+    }
+  }
+
+  console.log('\nclaude-status setup:');
+  for (const line of summary) console.log(`  ${line}`);
+  console.log('  run `claude-status doctor` any time to re-check.\n');
+}
+
+try {
+  main();
+} catch (err) {
+  console.warn(`claude-status postinstall hit an unexpected error: ${err.message}`);
+  console.warn('  run `claude-status install-hooks` to retry.');
+}
+process.exitCode = 0;

package/scripts/preuninstall.js

@@ -0,0 +1,27 @@
+'use strict';
+
+// Cleanup on uninstall — must never block npm from removing the package.
+
+const fs = require('node:fs');
+
+try {
+  if (process.platform === 'darwin' && !(process.getuid && process.getuid() === 0)) {
+    const hooks = require('../lib/hooks');
+    const { HOME_DIR, STATE_FILE } = require('../lib/constants');
+
+    try {
+      const report = hooks.uninstallHooks();
+      console.log(`claude-status: removed ${report.removed} hooks from settings.json`);
+    } catch (err) {
+      console.warn(`claude-status: could not remove hooks — ${err.message}`);
+    }
+    try {
+      require('../lib/keybindings').uninstallBinding();
+    } catch {}
+    try { fs.rmSync(HOME_DIR, { recursive: true, force: true }); } catch {}
+    try { fs.unlinkSync(STATE_FILE); } catch {}
+  }
+} catch (err) {
+  console.warn(`claude-status preuninstall: ${err.message}`);
+}
+process.exitCode = 0;

package/src/claude-status-helper.swift

@@ -0,0 +1,129 @@
+// claude-status-helper — write a short status string to the claude-status
+// ESP32 over BLE, using the connection macOS already holds to it as a HID
+// keyboard (no scanning: retrieveConnectedPeripherals).
+//
+// usage: claude-status-helper <state> | write <payload> | ping
+//        [--name <peripheral-name>] [--timeout <ms>]
+//
+// exit codes: 0 ok (ping: device present) · 2 bluetooth off/denied/unsupported
+//             3 device not connected · 4 timeout · 5 service/char missing
+//             6 write failed · 64 usage
+
+import CoreBluetooth
+import Foundation
+
+// Note: macOS hides the HID service (1812) from third-party CoreBluetooth
+// apps, so we look the connected device up by the battery / device-info
+// services the firmware also exposes.
+let RETRIEVAL_SERVICES = [CBUUID(string: "180F"), CBUUID(string: "180A")]
+let STATUS_SERVICE = CBUUID(string: "4FAFC201-1FB5-459E-8FCC-C5C9C331914B")
+let STATUS_CHARACTERISTIC = CBUUID(string: "BEB5483E-36E1-4688-B7F5-EA07361B26A8")
+
+func die(_ code: Int32, _ message: String) -> Never {
+    FileHandle.standardError.write((message + "\n").data(using: .utf8)!)
+    exit(code)
+}
+
+var deviceName = "claude-status"
+var timeoutMs = 3000
+var positional: [String] = []
+var iter = CommandLine.arguments.dropFirst().makeIterator()
+while let arg = iter.next() {
+    switch arg {
+    case "--name":
+        guard let v = iter.next() else { die(64, "--name requires a value") }
+        deviceName = v
+    case "--timeout":
+        guard let v = iter.next(), let n = Int(v), n > 0 else { die(64, "--timeout requires a positive integer (ms)") }
+        timeoutMs = n
+    default:
+        positional.append(arg)
+    }
+}
+
+var payload: Data? = nil
+var pingOnly = false
+switch positional.first {
+case nil:
+    die(64, "usage: claude-status-helper <state>|write <payload>|ping [--name <n>] [--timeout <ms>]")
+case "ping":
+    pingOnly = true
+case "write":
+    guard positional.count == 2 else { die(64, "write requires exactly one payload argument") }
+    payload = positional[1].data(using: .utf8)
+case let cmd?:
+    guard positional.count == 1, cmd.utf8.count <= 32 else { die(64, "state must be a single token of at most 32 bytes") }
+    payload = cmd.data(using: .utf8)
+}
+
+final class Writer: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate {
+    var central: CBCentralManager!
+    var peripheral: CBPeripheral?
+
+    func start() {
+        central = CBCentralManager(delegate: self, queue: .main)
+    }
+
+    func centralManagerDidUpdateState(_ c: CBCentralManager) {
+        switch c.state {
+        case .poweredOn:
+            let match = c.retrieveConnectedPeripherals(withServices: RETRIEVAL_SERVICES)
+                .first { $0.name == deviceName }
+            guard let p = match else {
+                die(3, "no connected peripheral named \"\(deviceName)\" — pair it in System Settings > Bluetooth")
+            }
+            if pingOnly {
+                print("found \(deviceName)")
+                exit(0)
+            }
+            peripheral = p
+            p.delegate = self
+            c.connect(p)
+        case .poweredOff:
+            die(2, "Bluetooth is powered off")
+        case .unauthorized:
+            die(2, "Bluetooth permission denied — allow your terminal app in System Settings > Privacy & Security > Bluetooth")
+        case .unsupported:
+            die(2, "Bluetooth LE is not supported on this machine")
+        default:
+            break // .resetting/.unknown — wait; the timeout is the backstop
+        }
+    }
+
+    func centralManager(_ c: CBCentralManager, didConnect p: CBPeripheral) {
+        p.discoverServices([STATUS_SERVICE])
+    }
+
+    func centralManager(_ c: CBCentralManager, didFailToConnect p: CBPeripheral, error: Error?) {
+        die(4, "connect failed: \(error?.localizedDescription ?? "unknown error")")
+    }
+
+    func peripheral(_ p: CBPeripheral, didDiscoverServices error: Error?) {
+        guard error == nil, let service = p.services?.first(where: { $0.uuid == STATUS_SERVICE }) else {
+            die(5, "status service not found on \(deviceName) — wrong firmware?")
+        }
+        p.discoverCharacteristics([STATUS_CHARACTERISTIC], for: service)
+    }
+
+    func peripheral(_ p: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) {
+        guard error == nil, let ch = service.characteristics?.first(where: { $0.uuid == STATUS_CHARACTERISTIC }) else {
+            die(5, "status characteristic not found on \(deviceName) — wrong firmware?")
+        }
+        p.writeValue(payload!, for: ch, type: .withResponse)
+    }
+
+    func peripheral(_ p: CBPeripheral, didWriteValueFor ch: CBCharacteristic, error: Error?) {
+        if let e = error {
+            die(6, "write failed: \(e.localizedDescription)")
+        }
+        central.cancelPeripheralConnection(p)
+        exit(0)
+    }
+}
+
+let writer = Writer()
+writer.start()
+DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(timeoutMs)) {
+    die(4, "timed out after \(timeoutMs) ms")
+}
+dispatchMain()

package/src/helper-Info.plist

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleIdentifier</key>
+	<string>com.claude-status.helper</string>
+	<key>CFBundleName</key>
+	<string>claude-status-helper</string>
+	<key>NSBluetoothAlwaysUsageDescription</key>
+	<string>Sends Claude Code status to the claude-status LED device.</string>
+</dict>
+</plist>