ai-hardware-buddy
A Claude Code plugin that mirrors your session — running tools,
permission prompts, transcripts, token usage — to a small ESP32 BLE
device with a TFT screen. Originally a port of Anthropic's
claude-desktop-buddy
firmware; this project drives that firmware from Claude Code (the
CLI / IDE-extension / web), replacing the Claude Desktop app's built-in
Hardware Buddy GUI.
Works on Linux, macOS, and Windows — the plugin ships a single Go
binary, no separate runtime install. MIT licensed.
Companion project: claude-desktop-buddy
Two repos, one pet.
This repo is the Claude Code plugin — the bits that let the buddy
approve tool calls, mirror sessions, and track tokens for your CLI
sessions. Its sibling is the firmware that runs on the device
itself:
| M5StickC Plus | CYD ESP32 |
|---|
| Claude Desktop | Anthropic's built-in Hardware Buddy | Web flasher → Claude Desktop GUI |
| Claude Code | This plugin | Web flasher → this plugin |
Each side runs standalone. The CYD firmware works with Claude
Desktop's GUI without this plugin, and this plugin works with any
board running buddy firmware — you don't need the CYD if you already
have an M5.
What it does
- Surfaces Claude Code permission prompts on the device — tap-to-approve
via a real
PreToolUse hook.
- Mirrors session lifecycle (
SessionStart, UserPromptSubmit,
PostToolUse, Stop, Notification, PreCompact, SubagentStop) —
the pet's mood + HUD reflect what Claude is doing.
- Pushes token usage parsed from Claude Code's transcript JSONL —
cumulative, today, and the rolling 5-hour quota window.
- Auto-recovers from BLE drops when you move rooms or power-cycle the
device.
- Self-contained: the plugin's
bin/hwbuddy is a single statically-built
Go binary that runs as both the MCP server and the hook-side CLI.
Install
Two steps the first time (plus one-time pairing).
1. Pair your device with the OS (one-time)
Linux:
bluetoothctl
[bluetoothctl]> agent KeyboardOnly
[bluetoothctl]> default-agent
[bluetoothctl]> scan le
# wait for [NEW] Device EC:E3:XX:XX:XX:XX Claude-XXXX
[bluetoothctl]> scan off
[bluetoothctl]> pair EC:E3:XX:XX:XX:XX
# device shows a 6-digit passkey; type it
[bluetoothctl]> trust EC:E3:XX:XX:XX:XX
[bluetoothctl]> exit
macOS: System Settings → Bluetooth → pair with passkey display.
2. Install the plugin
In Claude Code:
/plugin marketplace add https://github.com/skitzo2000/ai-hardware-buddy
/plugin install hardware-buddy@ai-hardware-buddy
Or from a local checkout:
/plugin marketplace add /path/to/ai-hardware-buddy
/plugin install hardware-buddy@ai-hardware-buddy
Restart claude so the plugin's hooks load and the MCP server starts.
No edits to your ~/.claude/settings.json are required.
3. (Optional) $HWBUDDY_ADDRESS for auto-attach
If you have a single buddy on a stable MAC, set this in your shell rc:
export HWBUDDY_ADDRESS=EC:E3:XX:XX:XX:XX
The MCP server will auto-connect when it starts and you skip the
/hwb-connect step.
4. Verify
In Claude Code:
/hwb-ping # MCP server liveness + BLE state
/hwb-test # synthetic approval prompt on the device
Slash commands
| Command | What it does |
|---|
/hwb-ping | Server liveness + BLE state. |
/hwb-connect [--address MAC] | Attach the MCP server's BLE link. |
/hwb-status [...] | Manually push session counters + msg. |
/hwb-tokens [--transcript PATH] | Parse transcript, push tokens. |
/hwb-test | Fake approval prompt — verify touch zones. |
Architecture
┌──────────────┐ PreToolUse / events ┌───────────┐ BLE NUS ┌────────────┐
│ Claude Code ├─────────────────────────►│ hwbuddy │◄───────────►│ ESP32 │
│ (session) │ stdio + unix socket │ MCP srv │ JSON lines │ pet │
└──────────────┘ └───────────┘ └────────────┘
