M5 Paper Buddy

m5-paper-buddy

  中文 · English

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

✨ 简介

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

🎛️ 功能

🛠️ 硬件

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

🚀 快速开始

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

/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

手工模式（不走插件）：

📟 日常使用

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

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

⌨️ 控制

🔌 Transport

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

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

💰 上下文预算

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

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

设 0 隐藏进度条。

🌐 语言切换

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

📂 目录结构

📖 深入阅读

- docs/ARCHITECTURE.md —— 技术架构 / 通信协议 / daemon 与固件内部 / 踩过的坑
- docs/PRODUCT.md —— 产品思考 / 设计取舍 / 未来畅想 / 给想 fork 的人

🧩 开发

固件改完后：

daemon 改完直接重启：

看日志：tail -f ~/.claude-buddy/daemon.log

🙏 致谢

本项目参考了 Anthropic 的 claude-desktop-buddy —— Nordic UART Service + heartbeat-JSON 通信协议沿用它的形状，因此理论上这块 Paper 也能被原项目的桌面端 bridge 驱动。

内置字体是 GenSenRounded Regular，来自 M5Stack 的 M5EPD 库示例。

📜 协议

本项目使用 GPL-3.0 协议，额外附加署名要求：
任何 fork / 修改 / 再分发，都必须：
1. 保留 Copyright © 2026 op7418 版权声明
2. 在 README 或 About 里显眼地署名 "op7418 / m5-paper-buddy"
3. 衍生作品自身也必须 以 GPL-3.0…