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

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

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/.