DEEPDIVE / [LAB] · CLAUDE DESKTOP BUDDY № 01 → № 02 Protocol
v1 · 2026
PRIMER / INTRO

More Than a Desktop Pet
Claude Desktop Buddy
What It Means for Developers

Anthropic open-sourced an ESP32 firmware that maps Claude Code's session state to a little pet on your desk. The real problem it solves: when Claude Code runs long tasks, approval popups interrupt you every time—Buddy eliminates this interruption with a physical button.

Hardware Cost
$25
M5StickC Plus
Behavior States
7
sleep ↔ heart
Built-in Pets
18
species × 7 anim
Open Protocol
BLE
Nordic UART + JSON
M5StickC Plus running the buddy firmware
FIG / 01 M5StickC Plus running buddy firmware — anthropic / claude-desktop-buddy
TL;DR / 30 sec

Buddy transforms agent approval from "switch windows and click" to "glance at the device and press"—what you save isn't two seconds, it's the attention context switch.

Counter-consensus insight: even if you never touch hardware, simply studying Buddy as a reference case for "what an agent approval UI should look like" is worth the $25 and an afternoon.

§ 01 / PROBLEM

The Real Problem It Solves

When Claude Code runs long tasks, the most annoying thing isn't the waiting—it's the popups.

You just hit your stride, then approve: Bash pops up—switch windows, click the button, switch back to your editor, and that thread in your head is broken. One time doesn't hurt, but they add up. The more authority you give the agent, the more popups; but without authority, the agent can't run.

What Buddy does is simple: it turns "switch back to the Claude window and click a button" into "glance at the device, reach out and press." It sounds like saving two seconds, but what you're actually saving is the attention context switch.

§ 02 / BEHAVIOR

The Device Has 7 States

State
Animation
TriggerBehavior
SLEEP
sleep
Desktop not connectedEyes closed, slow breathing
IDLE
idle
Connected, no taskBlinking, looking around
BUSY
busy
Session runningSweating, busy working face
ATTENTION
attention
Approval popupAlert expression + LED flash
CELEBRATE
celebrate
50K tokens accumulatedConfetti, jumping
DIZZY
dizzy
You shook it (IMU)Spinning eyes + wobbling
HEART
heart
Approved within 5 secFloating hearts

FIG / 02  LIVE GIFS FROM characters/bufo/ — official repo character pack

KEYMAP / Button semantics change with state
Default Viewing Pet Viewing Info During Approval
A (front) Next screen Next screen Next screen ✓ Approve
B (side) Scroll conversation Next pet Page down ✗ Reject
Long-press A Enter menu
Shake Trigger dizzy animation
Place face-down Sleep & recharge (save energy)

Auto screen-off after 30s idle / stays on during approval / any button wakes

A DAY / What it's actually like in practice
  1. 09:00 Open Claude Desktop → wakes from sleep into idle, starts blinking and looking around.
  2. 10:15 Have Code run a refactor → enters busy, starts sweating.
  3. 10:23 Halfway through, needs git push approval → switches to attention, LED flashes. Catch it in your peripheral vision, reach out and press A, approved within 5 sec → heart floating hearts.
  4. 11:40 Ran a long agent, burned 50K tokens → celebrate with confetti.
  5. 12:30 Heading out for lunch, place it face-down on the desk → enters sleep to recharge.
  6. 14:00 Come back, give it a shake → dizzy spinning eyes.
§ 03 / USEFUL

Where It's Actually Useful

Approvals don't break your workflow

You're debugging in another terminal while Claude runs batch tasks in the background. No need to switch windows—hands stay on keyboard, glance over, press once. Especially useful with dual monitors or when Claude runs on another machine.

Token consumption becomes tangible

Every 50K tokens triggers a level-up confetti burst. This number used to be buried in a webpage with no real awareness. Now a physical event happens on your desk—you genuinely notice how much you're burning, which has a non-obvious effect on cost control.

Face-down and shaking

Face-down = go to sleep, don't bother me; shake = just playing around. Sounds a bit silly, but these two gestures convey intent at a much lower cost than typing, and they're real physical actions, not software buttons.

Attention cost per approval (estimated) Shorter is better
Modal popup + mouse ~8s + flow loss
Keyboard shortcut ~3s
Buddy physical button ~1s, no focus
§ 04 / HACKING

How to Hack It

LV / 01 ZERO CODE 3 sec

Swap Pets

The firmware includes 18 ASCII species—long-press A → menu → next pet to cycle through, persists across power loss. If you just want a reskin, this step is enough.

LV / 02 ASSET PACK drag & drop

Push GIF Character Pack

Don't want ASCII? Create a set of GIFs and drag them to the Hardware Buddy window's drop target, which pushes them to the device via BLE for real-time switching. The repo's characters/bufo/ is a complete frog example.

Hardware Buddy window with Connect button and folder drop target
FIG / 03 HARDWARE BUDDY WINDOW — drag drop target on the right
my-character/
  manifest.json
  sleep.gif
  idle_0.gif      # Array: cycle through
  idle_1.gif
  busy.gif / attention.gif / celebrate.gif / dizzy.gif / heart.gif
CONSTRAINTS

96px wide / height ≤140px / total pack < 1.8MB  ·  tools/prep_character.py handles uniform scaling  ·  gifsicle --lossy=80 -O3 --colors 64 typically compresses 40~60%

LV / 03 FAST LOOP USB

USB Direct Flash (faster iteration)

Don't want to go through Bluetooth every time when iterating on characters: tools/flash_character.py characters/bufo puts assets in data/ then pio run -t uploadfs writes directly to the filesystem.

LV / 04 FIRMWARE C++

Modify Firmware

src/ structure is clean: state machine in main.cpp, one file per species animation in buddies/, BLE bridge in ble_bridge.cpp, GIF decoding in character.cpp. Add new states, new triggers (like double-click), or modify animations—just edit one file.

§ 05 / PROTOCOL

The Protocol Is Open

Nordic UART over BLE, JSON over line buffer, schema all in REFERENCE.md. The docs explicitly state: "Building your own device? You don't need any of the code here."

In other words: you don't need an M5Stick to connect, you don't have to display a pet, and you can use it entirely in reverse.

Without M5Stick

Any ESP32, nRF52, or Raspberry Pi + dongle that can run BLE can connect.

No Pet Display

A mechanical flip clock, an old Nokia screen, a fog lamp by the office door—anything that can consume those few state messages.

Reverse Integration

Feed Claude state into Home Assistant—when the agent starts running, dim the house lights; when it finishes, bring them back up.

M5StickC Plus whole device ~$25, open-source firmware, flash with PlatformIO. The barrier to entry is essentially zero.

§ 06 / ACTION

What You Can Do Right Now

TUTORIAL / Full setup demo (~80 sec)

VID / 01  PlatformIO setup → firmware flash → Developer Mode → BLE pairing → live approval interaction

  1. 01

    Start Using It

    Flash the official firmware on M5StickC Plus, try it for a week first.

  2. 02

    Swap Pets

    Long-press A → menu → next pet, try all 18 ASCII species.

  3. 03

    Reskin

    Drag a GIF character pack over, or make your own (96px wide, < 1.8MB).

  4. 04

    Modify Firmware

    Add a double-click trigger, modify animations, add new states.

  5. 05

    Connect Other Hardware

    Use the open BLE protocol to connect your existing devices to Claude's state.

  6. 06

    Reverse Applications

    Feed Claude state into Home Assistant / Stream Deck / custom keyboard macros.

Even if you never touch hardware, studying Buddy as a reference case for "what an agent approval UI should look like" is worth the $25 and an afternoon.

CLAUDE DESKTOP BUDDY · DUOLOGY
FIELD NOTE / № 01 — Product Perspective

Value

What problem Buddy solves, how to use it, how to hack it · State table + day-in-the-life narrative + action gradient

▣ Currently Reading
DEEP DIVE / № 01 — Technical Perspective →

Protocol Deep Dive

Protocol teardown + design analysis + protocol stack positioning + future predictions · The full picture of BLE to agent-hardware communication

▢ Published