m5-paper-buddy

中文 · English

把 M5Paper 变成 Claude Code 的物理桌面搭档

---

✨ 简介

用一块 M5Paper V1.1（4.7" 电子墨水屏 / 540×960 / GT911 触摸 / ESP32）做你的 Claude Code 伴侣屏。开着多个 Claude Code 窗口的时候，这块墨水屏会实时镜像每个 session 的项目、分支、上下文占用、最新回复和活动日志。Claude 要调用工具时，完整的命令 / diff / 内容会全屏弹出等你在硬件按键或触屏上确认。

---

🎛️ 功能

📊 多会话 Dashboard	左列显示所有在跑的 Claude Code 窗口，点一下切换 focus；右列显示 model + 上下文窗口占用进度条
🔐 硬件审批	PreToolUse 全屏审批卡，完整显示 Bash 命令 / Edit diff / Write 预览。PUSH 同意、DOWN 拒绝；DND 模式（长按 UP）自动批准
💬 触屏回答	AskUserQuestion 最多 4 个选项做成大按钮，点一下选项 label 直接回传给 Claude
🔁 FIFO 队列	多个窗口同时请求审批时，一次弹一个，当前处理完自动弹下一个
🀄 中英双语	内置 3.4MB CJK TTF，UI 支持 EN / 中文 切换（设置页里点）；所有 prompt / 回复 / 活动都能显示中文
🔌 双 Transport	USB 串口（默认、零配置）或 BLE（Nordic UART、macOS 配对 passkey），自动选择
⚙️ 设置页	右上角点 SETTINGS / 设置，查看 transport、电量、会话数、DND、预算、运行时长、最后消息
🐱 猫伙伴	底部一只 ASCII 猫跟状态变化表情（idle/busy/attention/celebrate/DND/sleep）
🔌 Claude Code 插件	一条 /buddy-install 搞定 PlatformIO + Python 依赖 + mklittlefs 架构补丁 + hooks 合并 + 固件/字体刷录 + daemon 后台启动

---

🛠️ 硬件

• M5Paper V1.1（4.7" 电子墨水屏、540×960、GT911 电容触摸、ESP32、16MB Flash）
• 一条 USB-C 线（初次烧录必须，之后可以换 BLE）

---

🚀 快速开始

前置：PlatformIO Core、Homebrew（Apple Silicon 下装 mklittlefs 用）、一台 M5Paper V1.1。

# 克隆
git clone https://github.com/op7418/m5-paper-buddy.git
cd m5-paper-buddy

# 作为 Claude Code 插件安装（推荐）
# 把本仓库 plugin/ 目录加到 Claude Code 的 plugin 路径下，然后：
/buddy-install

/buddy-install 会自动：

1. 验证 PlatformIO 已装
2. 装 Python 依赖（pyserial、BLE 模式额外装 bleak）
3. Apple Silicon 下自动修复 PlatformIO 自带 x86_64 mklittlefs（brew install mklittlefs + symlink）
4. 把 hook 配置合并进 ~/.claude/settings.json（自动备份原文件）
5. 如果 Paper 已插 USB，刷 firmware + 字体
6. 后台启动 daemon

手工模式（不走插件）：

pio run -e m5paper -t uploadfs          # 刷字体进 LittleFS（~90s）
pio run -e m5paper -t upload            # 刷固件（~30s）
python3 tools/claude_code_bridge.py --budget 200000

# 然后把 plugin/settings/hooks.json 的 hooks 块手动合并到
# ~/.claude/settings.json

---

📟 日常使用

装完以后 Claude Code 里有这几个斜杠命令：

命令	作用
/buddy-install	首次安装 / 重新校验环境
/buddy-start	启动 daemon（幂等）
/buddy-stop	停止 daemon
/buddy-status	看 daemon pid、串口、hooks 安装情况、日志尾部
/buddy-flash	重新编译 + 烧录固件和字体（stop → flash → start）

状态目录：~/.claude-buddy/（pid、log）。

---

⌨️ 控制

按键 / 区域	Dashboard 状态页	审批卡片
PUSH（中）	触发一次重绘	同意
DOWN（下）	切换 demo 模式	拒绝
UP（上）	短按：强制 GC16 全刷（清残影）· 长按 1.5s：切换 DND 勿扰	—
点会话行	切换 dashboard focus 到该 session	—
点右上 SETTINGS	打开设置页	—
点选项卡片	—	回答 AskUserQuestion

---

🔌 Transport

默认 BUDDY_TRANSPORT=auto —— 有 USB 走 USB，没有就 BLE。

BUDDY_TRANSPORT=ble    /buddy-start
BUDDY_TRANSPORT=serial /buddy-start

BLE 首次连接会触发 macOS 系统配对对话框，Paper 屏幕上显示 6 位 passkey，你输进去即可。以后自动重连。

---

💰 上下文预算

屏幕上的进度条显示 当前 focus 的 session 的上下文窗口占用量 ÷ 上限，读取自 session transcript JSONL 里最后一条 assistant 消息的 usage.input_tokens + output_tokens。

默认上限 200K（Claude 4.6 标准上下文）。要用 1M 上下文的 4.7 beta：

BUDDY_BUDGET=1000000 /buddy-start

设 0 隐藏进度条。

---

🌐 语言切换

默认英文。点 SETTINGS → 第一行 language / 语言 → 切换到中文。选择写入 NVS，重启保留。

---

📂 目录结构