v0.1.2 — Stop-hook completion chime + LAN ASR port fix

Highlights

• Completion chime: Echo now plays a two-tone ding-dong (perfect 5th up) when Claude finishes a turn. Claude rides A5→E6 (880→1320 Hz), Codex sits an octave lower at E5→B5 (660→990 Hz) — same character, distinct register so both agents stay recognizable if they ever run in parallel. Volume bumped to 220/255 just for the chime, restored to 128 after.

How it works

Claude Code Stop hook
  → plugin/scripts/on-stop.py
  → unix socket {"action":"chime","agent":"claude"}
  → bridge.py BLE NUS write {"cmd":"chime","agent":"claude"}
  → firmware data.h::_applyJson
  → M5.Speaker.tone (gated by settings().sound)

Reactive trigger via Claude Code's native Stop hook — no rollout JSONL polling, no file-watch surface area. Matches the existing PermissionRequest / PreToolUse hook plumbing. Bridge debounces with a 500ms window so sub-agent or interrupted-turn cascades don't double-beep.

Fixes

• LAN ASR port collision: start-bridge.sh now pins STICKS3_LAN_PORT=8766 (was the default 8765). Several other local ESP buddy projects hardcode 8765 and silently take the bind, leaving Echo's /audio endpoint unreachable and voice input failing with bad status. Override via env var.

Footprint

• Firmware 50.9% of 3.2MB / RAM 30.6% of 320KB (no change vs v0.1.1)

Compatibility

• Existing settings().sound toggle gates the chime — disable in Settings menu if you don't want it.
• Codex chime is wired in firmware but no Stop-hook source yet (bridge sends agent="claude" only); future work if Codex's hook surface lands.

v0.1.1 — boot offline, shake debounce, 6 new clawd states

Highlights

• 6 new clawd character states from clawd-tank's SVG sources via a new tools/svg2echo.py pipeline (Playwright + PIL → 135×120 disposal=2 GIFs): grooving / hat_mishap / crab_walking are wired to the idle mood pool, working_pushing sits in the catalog. Complements existing fetch_clawd_assets.py which downloads prebuilt slack-emoji GIFs.

Fixes

• Boot offline mode: when BLE bridge is unreachable, Echo enters a degraded-but-functional state after 8s instead of stalling on "awaiting bridge" forever. Boot UI moved to a 78px mid-lower overlay so clawd renders even during early init.
• Persona bridge: shake / celebrate / attention / busy now correctly drive the GIF character (these were silently broken by the boot blocker).
• Shake detection rewritten: 3 high-g hits within 800ms (was: single 0.8g shock). No more false dizzy from setting the device down or walking.
• Two-clawd overlap on switch: fillSprite on activeState transition.
• Idle flicker: removed characterInvalidate self-call from openStateGif.
• HUD/GIF sync: mood burst label no longer goes stale when activeState transitions mid-burst (e.g. shake → DIZZY while "sweep" is showing).

Known limitation

Bridge char_state push has higher priority than local PersonaState one-shot. Attempted EUREKA (ultra-fast approve) and LOW_BATTERY visual states were removed because bridge.py's auto-decay to "idle" and post-approve "happy" override them within 1-2 frames.

Footprint

• Firmware 50.9% of 3.2MB / RAM 30.6% of 320KB
• LittleFS 1.1MB / 1.5MB (23 GIFs, 400KB headroom)

v0.1.0 — First public release

First public release of claude-code-stick — an M5Stack StickS3 (ESP32-S3) hardware companion for Claude Code.

🚧 v0.1 alpha. Single-developer project. Bug reports welcome via... well, not yet — Issues are intentionally closed for the first week. Watch this space.

What it does

• Permission approval over physical buttons — when Claude Code asks for permission, an animated Clawd buddy lights up on the device and you press A (approve) or B (deny). No alt-tab.
• Voice input over Wi-Fi — hold A, speak, release. Transcript is pasted into Claude Code's input box via macOS Cmd-V. Uses Alibaba Cloud DashScope's Qwen3-ASR-Flash.
• Buddy state mirrors tool activity — Edit/Write → typing, Bash → building, WebSearch → wizard, etc. 19 Clawd states. Idle clawd has random mood bursts every 8-15s so it doesn't look frozen.
• Boot status panel — Wi-Fi → BLE → Bridge handshake progress shown on screen at startup.
• Remote Wi-Fi provisioning — echo-wifi "Network" "password" from the Mac.

Architecture (briefly)

[StickS3] —BLE NUS—→ [bridge.py on Mac] —HTTPS—→ [DashScope ASR]
       \                  ↓
        —Wi-Fi HTTP—→ Unix socket: Claude Code hooks
                          ↓
                   osascript Cmd-V → focused window

The ESP32 doesn't talk to the cloud. It records audio over Wi-Fi to the Mac, exchanges JSON control messages over BLE. All TLS / API key handling stays on the Mac, where Python is well-behaved.

Hardware

• M5Stack StickS3 (ESP32-S3-PICO, ES8311 mic, 135×240 ST7789P3)
• macOS with BLE
• 2.4 GHz Wi-Fi
• Alibaba Cloud DashScope account (~free tier for casual use)

Setup

See README. If you're not a developer, the README has a copy-pasteable prompt for Claude Code / other coding agents that walks through every step.

Known limitations

• First-time Wi-Fi must be entered via USB serial (no captive portal yet)
• BLE link occasionally goes stale on macOS — fix is PWR-cycle the device
• macOS only — Linux/Windows bridge would need an alternative to osascript paste
• DashScope free tier requires Alibaba Cloud account (China-friendly; international users can use the international Singapore endpoint)

Acknowledgments

This project is a fork of anthropics/claude-desktop-buddy, whose CONTRIBUTING.md opens with "The best contribution is a fork." We took them up on that.

• Clawd animation assets from marciogranzotto/clawd-tank
• Architecture inspiration from chat-stick and xiaozhi-esp32
• Hardware platform: M5Stack StickS3

Trademark disclaimer

Not affiliated with Anthropic, Alibaba Cloud, Amazon, or M5Stack. Claude, Claude Code, Clawd, DashScope, M5Stack, and Echo are trademarks of their respective owners. Default device name "Echo" is unrelated to Amazon Echo and is fully renameable — see README Configuration.

License

MIT. See LICENSE and NOTICE.