Pager

A physical Claude Code remote for your desk.

Pager is a small touchscreen companion that gives you ambient awareness of
Claude Code and Claude Cowork sessions, and lets you approve or deny
tool-use prompts with a tap — without context-switching away from your main
work. It pairs with the Claude desktop app over Bluetooth LE using
Anthropic's documented
Hardware Buddy protocol
(Nordic UART Service + newline-delimited JSON), and runs on an M5Stack
CoreS3 SE.

  ┌──────────────────────────────┐
  │  Pager - working       14:23 │
  │  approve: Bash      Sun 26   │
  │     2 running, 1 waiting     │
  │  /\    /\ /\                 │
  │  ▓▓▓▓▓▓▓▓░░░░  31.2k (~480)  │
  │                              │
  │  10:42  git push             │
  │  10:41  yarn test            │
  │  active now                  │
  └──────────────────────────────┘

When a permission prompt blocks a session, the screen takes over with the
tool name and the full call. You approve with a tap or hold-to-deny.

→ See PAGER_SPEC.md for the v1 specification and
BACKLOG.md for known limits and follow-ups.

Hardware

• M5Stack CoreS3 SE (SKU K128-SE) — ESP32-S3, 2.0″ IPS touch (320×240), 8 MB PSRAM, 16 MB flash, USB-C powered.
• USB-C cable.

The "SE" matters: it has no battery and no IMU. The firmware is written
to that constraint and won't surface battery / tilt UI even though the
Hardware Buddy protocol allows for it. Anthropic's reference firmware
(claude-desktop-buddy,
MIT) targets the regular CoreS3 with a pet character pack instead — this
is a fresh, independent implementation with a pager-style UI. No code is
shared; only the documented wire protocol.

Experimental: M5Stack Dial

The same codebase also builds for the M5Stack Dial — ESP32-S3, 1.28″ round
240×240 touch panel with a rotary encoder. Flash with
pio run -e dial -t upload instead of the default env.

The encoder is the headline difference: approvals use rotate-then-press.
Rotate clockwise to arm Approve, counter-clockwise to arm Deny, watch the
coloured arc fill around the perimeter, then push the encoder to commit. A
"press to Approve/Deny" hint appears once the arc crosses the arm threshold.
Touch fallback is still wired — the on-screen Approve / Deny buttons respond
to taps and long-press — so no-rotation operation works too.

Glance / Recent / Settings are repositioned for the round canvas; the
sparkline, date, token bar, and second transcript entry are dropped to
fit. Upload requires --no-stub (configured in platformio.ini) because
the Dial's USB-CDC stub handoff is even flakier than the CoreS3 SE's — flash
runs ~2 min via the ROM bootloader but is reliable. See BACKLOG.md for
what's still rough.

Build & flash

1. Install PlatformIO Core
   or the VS Code extension.

2. Plug the CoreS3 SE into your machine over USB-C.

3. From the repo root:

   pio run -t upload
   pio device monitor
   

The first build pulls M5Unified, NimBLE-Arduino, and ArduinoJson (~30 MB).

CoreS3 SE download-mode quirk

The CoreS3 SE doesn't have a dedicated BOOT button. If pio run -t upload
hangs on Connecting...... for 10+ seconds, put the board into download
mode manually: long-press the RESET button for ~3 seconds until the green
LED lights up, release, then retry the upload. PlatformIO usually
triggers this automatically, but the manual ritual works when it doesn't.

Pair with Claude

1. In Claude for macOS or Windows, enable Help → Troubleshooting → Enable
   Developer Mode.
2. Open Developer → Open Hardware Buddy… and click Connect.
3. Pick Claude-Pager-XXXX from the scanner.
4. The Pager displays a 6-digit passkey. Type it into the OS prompt.
5. Verify sec: true in the Hardware Buddy window's stats panel — that
   means the link is encrypted.

If pairing misbehaves after a reflash (old bond data on one side, fresh on
the other), click Forget this device in Claude, then power-cycle the
Pager and try again.

Project layout

pager/
├── include/
│   ├── config.h          BLE UUIDs, firmware version, capacities, NVS keys
│   └── lv_conf.h         LVGL 9 configuration (RGB565, dark theme, fonts)
├── src/
│   ├── main.cpp          composition root, BLE↔queue↔protocol↔UI wiring
│   ├── audio/chime.*     generated double-chirp on approval arrival
│   ├── ble/nus.*         NimBLE NUS peripheral + LE SC bonding
│   ├── persistence/      NVS-backed settings + counters
│   ├── proto/protocol.*  Hardware Buddy JSON parse/build/dispatch
│   ├── state/session.*   in-memory snapshot model + PSRAM ring buffer
│   ├── system/clock.*    RTC + epoch/TZ formatting helpers
│   ├── system/dial_encoder.*  Dial rotary encoder (IRAM ISR, GPIO 41/40)
│   └── ui/               LVGL port, router, view widgets
├── scripts/              diagnostic helpers + LVGL-xtensa pre-build patch
├── PAGER_SPEC.md         v1 specification (read this before redesigning)
├── BACKLOG.md            known limits and follow-ups
├── HANDOFF.md            cross-machine bring-up notes
├── CLAUDE.md             design rules for Claude Code instances
├── platformio.ini
├── LICENSE
└── README.md

The composition root in src/main.cpp is the only place that knows about
every module — modules in ble/, proto/, state/, ui/ never call
each other directly. See CLAUDE.md for the design rules.

What works today

Verified end-to-end against Claude for macOS in Developer Mode, with both
synthetic prompts (via scripts/blefake.py) and a real Claude permission
prompt for an actual pwsh invocation:

• Pairing with the LE Secure Connections passkey flow (DisplayOnly IO
  capability, AES-CCM-encrypted link, bond persists across reboots and
  host sleep/wake).
• Ambient Glance view with everything you want to know in one screen:
  • Status pill that colour-codes session state at a glance
    (green=idle, amber=working, red=waiting, gray=disconnected,
    violet=focus mode).
  • Heartbeat msg rendered as a subtitle ("approve: Bash", "1 idle", …).
  • Counters (running · waiting), today's tokens, last two transcript
    entries from snapshot.entries.
  • Token-burn sparkline above the today bar — last ~10 min of
    per-tick deltas, so you can see whether you're sprinting or drifting.
  • Local clock in the top-right (HH:MM, BM8563-backed, synced from
    the desktop's {"time":[epoch,tz]}).
  • Updates within ~1 s of each heartbeat.
• Approval takeover: when a prompt:-bearing heartbeat arrives, the
  screen flips to a full-screen tool-call review with green Approve and
  hold-to-Deny. The decision round-trips back to the desktop in well
  under 500 ms.
• Bezel buttons (the three orange marks below the LCD on the CoreS3
  SE): tap right = Approve, hold left ~400 ms = Deny while an approval
  is up; tap centre on Glance to toggle focus mode. Mirrors the on-screen
  layout, so you can act on a prompt without reaching for the screen.
• Focus mode: long-press anywhere on Glance — or tap the centre
  bezel button — to silence the chime and pin the backlight dim for
  60 min. Re-press to exit early. Useful in calls and meetings.
• Recent view (PSRAM-backed ring of the last ~64 turn events).
• Settings view (device name override, owner name, chime toggle,
  forget-bonds button).
• Local NVS-persisted approval / denial counters.
• Time sync from desktop into the BM8563 RTC.
• Soft chime on prompt arrival (configurable, off by default).

BACKLOG.md tracks what's not yet covered (24 h soak,
font-size tuning, etc.).

Diagnostic scripts

If something on the protocol layer breaks, these are the tools that
earned their keep during initial bring-up. All assume bleak and
pyserial are available (PlatformIO's bundled Python has both):

• scripts/blecli.py — connects as a generic BLE central, prints the
  GATT structure, and round-trips a {"cmd":"status"}.
• scripts/blefake.py — simulates Claude Desktop. Sends a heartbeat
  with a synthetic permission prompt and waits for the device's
  decision. Use this to verify the approval UI without depending on
  Claude actually emitting one.
• scripts/pagermon.py — long-running USB-CDC monitor that reconnects
  across drops. pio device monitor dies on the first drop; this one
  keeps logging.
• scripts/fix_lvgl_xtensa.py — pre-build hook that strips LVGL's
  ARM-only .S files (Helium, NEON) from libdeps before compile. Wired
  in platformio.ini, runs automatically.

HANDOFF.md has the longer story of what each one
caught.

License

MIT. See LICENSE.

The Hardware Buddy BLE protocol is specified by Anthropic in
claude-desktop-buddy/REFERENCE.md.
This firmware implements that protocol from the spec; no code is copied
from upstream.