Skip to content
Back to search

m5-paper-buddy

📟 Claude Code physical companion on M5Paper V1.1 e-ink. Multi-session dashboard, hardware approval (buttons + touch), AskUserQuestion option cards, CJK, USB/BLE, installable as a Claude Code plugin. / Claude Code 实体搭档,把 M5Paper 变成 Claude Code 的多会话看板 + 硬件审批面板。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/op7418--m5-paper-buddy/badge.svg)](/listings/op7418--m5-paper-buddy)

HTML

<a href="/listings/op7418--m5-paper-buddy"><img src="/api/listings/op7418--m5-paper-buddy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 233 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # m5-paper-buddy
  2. <p align="center">
  3. <a href="README.md"><b>中文</b></a> · <a href="README.en.md">English</a>
  4. </p>
  5. <p align="center">
  6. <img src="https://github.com/user-attachments/assets/49a543f3-ad1a-4735-a5d1-ef98867cff1e" alt="m5-paper-buddy on an M5Paper V1.1" width="540">
  7. </p>
  8. <p align="center">
  9. <a href="LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-blue.svg" alt="GPL-3.0"></a>
  10. <img src="https://img.shields.io/badge/hardware-M5Paper%20V1.1-orange" alt="M5Paper">
  11. <img src="https://img.shields.io/badge/firmware-ESP32%20%2B%20PlatformIO-brightgreen" alt="ESP32">
  12. <img src="https://img.shields.io/badge/daemon-Python%203-yellow" alt="Python">
  13. <img src="https://img.shields.io/badge/integration-Claude%20Code%20Plugin-7F52FF" alt="Claude Code">
  14. <img src="https://img.shields.io/badge/i18n-EN%20%2F%20中文-lightgrey" alt="i18n">
  15. </p>
  16. <p align="center"><b>把 M5Paper 变成 Claude Code 的物理桌面搭档</b></p>
  17. ---
  18. ## ✨ 简介
  19. 用一块 **M5Paper V1.1**(4.7" 电子墨水屏 / 540×960 / GT911 触摸 / ESP32)做你的 Claude Code 伴侣屏。开着多个 Claude Code 窗口的时候,这块墨水屏会**实时镜像**每个 session 的项目、分支、上下文占用、最新回复和活动日志。Claude 要调用工具时,完整的命令 / diff / 内容会**全屏弹出**等你在**硬件按键**或**触屏**上确认。
  20. ---
  21. ## 🎛️ 功能
  22. | | |
  23. | --- | --- |
  24. | 📊 **多会话 Dashboard** | 左列显示所有在跑的 Claude Code 窗口,点一下切换 focus;右列显示 model + 上下文窗口占用进度条 |
  25. | 🔐 **硬件审批** | `PreToolUse` 全屏审批卡,完整显示 Bash 命令 / Edit diff / Write 预览。PUSH 同意、DOWN 拒绝;DND 模式(长按 UP)自动批准 |
  26. | 💬 **触屏回答** | `AskUserQuestion` 最多 4 个选项做成**大按钮**,点一下选项 label 直接回传给 Claude |
  27. | 🔁 **FIFO 队列** | 多个窗口同时请求审批时,一次弹一个,当前处理完自动弹下一个 |
  28. | 🀄 **中英双语** | 内置 3.4MB CJK TTF,UI 支持 EN / 中文 切换(设置页里点);所有 prompt / 回复 / 活动都能显示中文 |
  29. | 🔌 **双 Transport** | USB 串口(默认、零配置)或 BLE(Nordic UART、macOS 配对 passkey),自动选择 |
  30. | ⚙️ **设置页** | 右上角点 `SETTINGS` / `设置`,查看 transport、电量、会话数、DND、预算、运行时长、最后消息 |
  31. | 🐱 **猫伙伴** | 底部一只 ASCII 猫跟状态变化表情(idle/busy/attention/celebrate/DND/sleep) |
  32. | 🔌 **Claude Code 插件** | 一条 `/buddy-install` 搞定 PlatformIO + Python 依赖 + mklittlefs 架构补丁 + hooks 合并 + 固件/字体刷录 + daemon 后台启动 |
  33. ---
  34. ## 🛠️ 硬件
  35. - **M5Paper V1.1**(4.7" 电子墨水屏、540×960、GT911 电容触摸、ESP32、16MB Flash)
  36. - 一条 USB-C 线(初次烧录必须,之后可以换 BLE)
  37. ---
  38. ## 🚀 快速开始
  39. **前置**:[PlatformIO Core](https://docs.platformio.org/en/latest/core/installation/)、Homebrew(Apple Silicon 下装 `mklittlefs` 用)、一台 M5Paper V1.1。
  40. ```bash
  41. # 克隆
  42. git clone https://github.com/op7418/m5-paper-buddy.git
  43. cd m5-paper-buddy
  44. # 作为 Claude Code 插件安装(推荐)
  45. # 把本仓库 plugin/ 目录加到 Claude Code 的 plugin 路径下,然后:
  46. /buddy-install
  47. ```
  48. `/buddy-install` 会自动:
  49. 1. 验证 PlatformIO 已装
  50. 2. 装 Python 依赖(`pyserial`、BLE 模式额外装 `bleak`)
  51. 3. Apple Silicon 下**自动修复** PlatformIO 自带 x86_64 `mklittlefs`(`brew install mklittlefs` + symlink)
  52. 4. 把 hook 配置合并进 `~/.claude/settings.json`(自动备份原文件)
  53. 5. 如果 Paper 已插 USB,**刷 firmware + 字体**
  54. 6. 后台启动 daemon
  55. **手工模式(不走插件)**:
  56. ```bash
  57. pio run -e m5paper -t uploadfs # 刷字体进 LittleFS(~90s)
  58. pio run -e m5paper -t upload # 刷固件(~30s)
  59. python3 tools/claude_code_bridge.py --budget 200000
  60. # 然后把 plugin/settings/hooks.json 的 hooks 块手动合并到
  61. # ~/.claude/settings.json
  62. ```
  63. ---
  64. ## 📟 日常使用
  65. 装完以后 Claude Code 里有这几个斜杠命令:
  66. | 命令 | 作用 |
  67. | --- | --- |
  68. | `/buddy-install` | 首次安装 / 重新校验环境 |
  69. | `/buddy-start` | 启动 daemon(幂等) |
  70. | `/buddy-stop` | 停止 daemon |
  71. | `/buddy-status` | 看 daemon pid、串口、hooks 安装情况、日志尾部 |
  72. | `/buddy-flash` | 重新编译 + 烧录固件和字体(stop → flash → start) |
  73. 状态目录:`~/.claude-buddy/`(pid、log)。
  74. ---
  75. ## ⌨️ 控制
  76. | 按键 / 区域 | Dashboard 状态页 | 审批卡片 |
  77. | --- | --- | --- |
  78. | **PUSH**(中) | 触发一次重绘 | **同意** |
  79. | **DOWN**(下) | 切换 demo 模式 | **拒绝** |
  80. | **UP**(上) | 短按:强制 GC16 全刷(清残影)· 长按 1.5s:切换 **DND 勿扰** | — |
  81. | 点会话行 | 切换 dashboard focus 到该 session | — |
  82. | 点右上 `SETTINGS` | 打开设置页 | — |
  83. | 点选项卡片 | — | 回答 `AskUserQuestion` |
  84. ---
  85. ## 🔌 Transport
  86. 默认 `BUDDY_TRANSPORT=auto` —— 有 USB 走 USB,没有就 BLE。
  87. ```bash
  88. BUDDY_TRANSPORT=ble /buddy-start
  89. BUDDY_TRANSPORT=serial /buddy-start
  90. ```
  91. BLE 首次连接会触发 macOS 系统配对对话框,Paper 屏幕上显示 6 位 passkey,你输进去即可。以后自动重连。
  92. ---
  93. ## 💰 上下文预算
  94. 屏幕上的进度条显示 **当前 focus 的 session 的上下文窗口占用量** ÷ 上限,读取自 session transcript JSONL 里最后一条 assistant 消息的 `usage.input_tokens + output_tokens`。
  95. 默认上限 200K(Claude 4.6 标准上下文)。要用 1M 上下文的 4.7 beta:
  96. ```bash
  97. BUDDY_BUDGET=1000000 /buddy-start
  98. ```
  99. 设 0 隐藏进度条。
  100. ---
  101. ## 🌐 语言切换
  102. 默认英文。点 `SETTINGS` → 第一行 **language / 语言** → 切换到中文。选择写入 NVS,重启保留。
  103. ---
  104. ## 📂 目录结构
  105. ```
  106. src/
  107. ble_bridge.cpp/h # Nordic UART Service,双向行缓冲 TX/RX
  108. stats.h # NVS 状态(approvals/denials/level/DND/language)
  109. paper/
  110. main.cpp # UI、状态机、触屏、设置页、i18n
  111. data_paper.h # TamaState + JSON 协议解析(UTF-8 安全)
  112. xfer_paper.h # status 响应、name/owner/unpair 命令
  113. buddy_frames.h # ASCII 猫的 6 个状态帧
  114. data/cjk.ttf # CJK 字体,通过 uploadfs 刷进 LittleFS
  115. partitions-m5paper.csv # 3MB app + 13MB LittleFS 分区表
  116. platformio.ini
  117. plugin/ # Claude Code 插件打包
  118. plugin.json # manifest
  119. commands/ # /buddy-* 斜杠命令
  120. scripts/ # install / start / stop / status / flash / common
  121. settings/hooks.json # 要合并到 ~/.claude/settings.json 的 hooks 块
  122. README.md # 插件自身的 README
  123. tools/claude_code_bridge.py # daemon: HTTP → serial/BLE 桥接
  124. ```
  125. ---
  126. ## 📖 深入阅读
  127. - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** —— 技术架构 / 通信协议 / daemon 与固件内部 / 踩过的坑
  128. - **[docs/PRODUCT.md](docs/PRODUCT.md)** —— 产品思考 / 设计取舍 / 未来畅想 / 给想 fork 的人
  129. ---
  130. ## 🧩 开发
  131. 固件改完后:
  132. ```bash
  133. pio run -e m5paper # 只 build
  134. pio run -e m5paper -t upload # 烧固件
  135. pio run -e m5paper -t uploadfs # 更新 LittleFS(字体变了才需要)
  136. ```
  137. daemon 改完直接重启:
  138. ```bash
  139. /buddy-stop && /buddy-start
  140. # 或:
  141. plugin/scripts/stop.sh && plugin/scripts/start.sh
  142. ```
  143. 看日志:`tail -f ~/.claude-buddy/daemon.log`
  144. ---
  145. ## 🙏 致谢
  146. 本项目参考了 Anthropic 的 [`claude-desktop-buddy`](https://github.com/anthropics/claude-desktop-buddy) —— Nordic UART Service + heartbeat-JSON 通信协议沿用它的形状,因此理论上这块 Paper 也能被原项目的桌面端 bridge 驱动。
  147. 内置字体是 GenSenRounded Regular,来自 M5Stack 的 `M5EPD` 库示例。
  148. ---
  149. ## 📜 协议
  150. 本项目使用 **[GPL-3.0](LICENSE)** 协议,额外附加**署名要求**:
  151. > **任何 fork / 修改 / 再分发,都必须:**
  152. >
  153. > 1. 保留 `Copyright © 2026 op7418` 版权声明
  154. > 2. 在 README 或 About 里**显眼地署名** "op7418 / m5-paper-buddy"
  155. > 3. 衍生作品自身也必须 **以 GPL-3.0 或更高版本开源**,并**公开完整源代码**
  156. 换句话说:你可以自由 fork / 改 / 用在商业场景里,但改完的版本也必须开源 + 署名。合了就必须开源,不接受闭源衍生。
  157. 详见 [LICENSE](LICENSE) 文件里的 "Attribution & derivative obligations" 段落。
  158. <details>
  159. <summary>第三方组件</summary>
  160. - `data/cjk.ttf`:GenSenRounded Regular,来自 M5EPD 库示例,字体本身的许可条款适用于该文件
  161. - Nordic UART Service UUID 与 heartbeat JSON schema:参考自 anthropics/claude-desktop-buddy(MIT)
  162. </details>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.