InksPet v1.1 now pairs directly with Claude desktop as a Hardware Buddy

What is the Claude desktop Hardware Buddy API?

Hardware Buddy is a public BLE protocol exposed by the Claude desktop app for macOS and Windows, behind a Developer Mode toggle. When enabled, the app opens a standard Nordic UART Service scanner and connects to any peripheral whose advertising name starts with Claude. Everything on the wire is UTF-8 JSON, one object per newline-terminated frame.

Anthropic also publishes a reference M5StickC Plus firmware and a minimal Python test harness — it's clearly intended as an open maker API, not a closed product feature. The wire protocol is small enough that any ESP32, nRF52, or even a Raspberry Pi with a BLE dongle can implement it in a few hundred lines.

What the protocol carries

The desktop pushes three kinds of messages to the device:

• Heartbeat snapshots — total sessions open, how many are actively running, how many are blocked on a permission prompt, a one-line summary string, cumulative and today-only token counts, and the most recent transcript entries. Arrives on any state change plus a 10-second keepalive.
• Permission prompts — when Claude decides to call a tool like Bash, a read, an MCP server, or a file edit, a prompt object with a correlation id, tool name, and short hint is embedded in the next snapshot.
• Turn events — each completed assistant turn fires a one-shot event carrying the raw SDK content array (text blocks, tool calls, whatever's in the reply), capped at 4 KB.

The device can reply with exactly one thing that matters: {"cmd":"permission","id":"<correlation-id>","decision":"once"} or "deny". That message flies back over BLE and Claude honors it — the tool call runs, or it doesn't, based on your button press.

There are smaller ancillary commands too: owner (sets your Claude account first name on the device), name (sets a pet name), unpair (wipes the bond when you hit Forget), and a folder-push channel that streams arbitrary files — the reference firmware uses it to receive animated GIF character packs.

Why InksPet makes an especially good Hardware Buddy

The reference M5StickC Plus firmware is a colour LCD pet — cute, very "desk toy," decidedly not calm. InksPet takes the same protocol in a different direction:

• E-paper instead of LCD — status stays on the display with zero backlight, zero flicker, zero attention cost when you don't want it. The Buddy HUD is legible in direct sunlight and invisible in the dark.
• Peripheral RGB LED — a separate 5-LED strip on the device colour-codes state at a glance without asking you to read the screen. Yellow flash means Claude wants permission. Green solid means it's running a tool.
• Physical buttons with tactile feel — the A / B / C keys have actual travel. Approving git push by pressing a key feels different from clicking Allow in a popup because it is different. The software asking isn't the software gating.
• GIF character packs in 1-bit — drop a pack into the Hardware Buddy window and InksPet receives it over BLE, dithers the colour frames with an 8×8 Bayer matrix, and plays them back on the monochrome panel. You lose the colour; you keep the character.

We also kept the existing HTTP webhook path from InksPet v1.0 — Claude Code, Copilot, Cursor, Codex, Gemini CLI, OpenCode all still work over local hooks. The two channels run in parallel on the same device, and permission requests are source-tagged so button presses always reply on the right transport.

Pairing in under 30 seconds

End-to-end pairing from a fresh device looks like this:

1. Flash v1.1.1 from inkspet.com/flash (browser-based, one click).
2. In the Claude desktop app, turn on Help → Troubleshooting → Enable Developer Mode.
3. Open Developer → Open Hardware Buddy… and click Connect.
4. Pick Claude-XXXX from the scanner list (the 4-hex suffix is your device's Bluetooth MAC tail).
5. macOS prompts for a pairing passkey; the e-paper shows a fresh 6-digit code. Type it in.

Done. The bond persists — every subsequent time you open Claude desktop, the device reconnects silently with AES-CCM encryption and the HUD comes alive.

What you actually see on the e-paper

Once paired, the display switches to a Buddy HUD layout:

• Left sidebar — pixel-art Clawd the crab with the state name underneath. Sleeping, Idle, Working, Attention, Celebrate, Dizzy, Heart — the upstream 7 states mapped to our 12-state internal enum.
• Top of the right column — Claude's one-line summary, which is often remarkably specific. "approve: Bash", "1 session running", or (because we render Chinese fonts too) your last user prompt rendered verbatim in CJK.
• Second row — Today: 3.2K rolling token count, reset at local midnight.
• Bottom of the right column — up to three most recent transcript entries, newest first, bullet-pointed.
• Footer — Claude-EA06 device name on the left, a bonded indicator on the right confirming the link is encrypted.

When Claude asks for a tool permission, the HUD is pre-empted by the full-width PERMISSION REQUEST layout: agent name, tool, hint, three button legends. The LED flashes yellow. Press A and {cmd:"permission",decision:"once"} flies back over BLE — Claude runs the tool. Press C and Claude politely refuses to run it.

Security isn't an afterthought

Transcript snippets and tool command hints travel over the BLE link. Anyone within radio range with a ~\$30 nRF dongle could passively sniff unencrypted advertising, so the protocol is explicit about security:

• LE Secure Connections + MITM bonding — NUS characteristics are marked encryption-required. No plaintext GATT traffic until the pairing handshake succeeds.
• DisplayOnly IO capability — the device generates a new 6-digit passkey on every boot, displays it on the e-paper, and makes you type it into macOS. Resists both passive sniffing and man-in-the-middle active attacks.
• AES-CCM encryption post-pairing — all subsequent notifications and writes are encrypted with keys derived during the handshake.
• Unpair honors the desktop "Forget" — when you click Forget, Claude sends {"cmd":"unpair"} and the device wipes its stored long-term key. The next pairing generates a fresh passkey; there's no lingering state.

What's in it for Claude users

If you're running Claude desktop day-to-day, a Hardware Buddy changes the ergonomics of three specific moments:

1. When Claude needs permission for a non-trivial tool call. Instead of a modal popup that stops your typing, you glance right — the e-paper shows the tool and hint, the LED flashes yellow — and tap a physical key. You don't context-switch.
2. When you want to know if Claude is still working. You look at the LED. Solid green = yes. White dim = idle. Zero Alt-Tabs.
3. When you want to measure your own usage. Today: X.XK sitting passively on the e-paper is a more honest daily counter than any dashboard you'd remember to open.

Try it on your desk

InksPet v1.1.1 is live on inkspet.com/flash. If you already have an EleksCava device running v1.0.x, the upgrade takes about a minute via the browser-based installer. WiFi and hook config survive the update — you'll be paired to Claude desktop in under five minutes from clicking Install.

The firmware is open source under MIT, every commit is documented in the changelog, and you can always roll back to v1.0.2 if you don't want the BLE stack resident. For protocol-level details and the reference C++ source, see Anthropic's upstream claude-desktop-buddy repository.

Hardware Buddy is still officially marked "maker/developer feature" by Anthropic, which usually means the protocol will evolve before it stabilizes. InksPet tracks upstream changes — new firmware releases on inkspet.com ship the day the wire format moves.