[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-2099":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":41,"readmeContent":42,"aiSummary":43,"trendingCount":16,"starSnapshotCount":16,"syncStatus":17,"lastSyncTime":44,"discoverSource":45},2099,"m5-paper-buddy","op7418\u002Fm5-paper-buddy","op7418","📟 Claude Code physical companion on M5Paper V1.1 e-ink. Multi-session dashboard, hardware approval (buttons + touch), AskUserQuestion option cards, CJK, USB\u002FBLE, installable as a Claude Code plugin. \u002F Claude Code 实体搭档，把 M5Paper 变成 Claude Code 的多会话看板 + 硬件审批面板。","https:\u002F\u002Fgithub.com\u002Fop7418\u002Fm5-paper-buddy",null,"C++",149,15,127,1,0,2,5,18,6,3.61,"Other",false,"main",true,[27,28,29,30,31,32,33,34,35,36,37,38,39,40],"approval-workflow","arduino","ble","claude","claude-code","claude-code-plugin","e-ink","eink","esp32","hardware","i18n","m5paper","m5stack","platformio","2026-06-12 02:00:37","# m5-paper-buddy\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"README.md\">\u003Cb>中文\u003C\u002Fb>\u003C\u002Fa> · \u003Ca href=\"README.en.md\">English\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F49a543f3-ad1a-4735-a5d1-ef98867cff1e\" alt=\"m5-paper-buddy on an M5Paper V1.1\" width=\"540\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-GPL--3.0-blue.svg\" alt=\"GPL-3.0\">\u003C\u002Fa>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fhardware-M5Paper%20V1.1-orange\" alt=\"M5Paper\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ffirmware-ESP32%20%2B%20PlatformIO-brightgreen\" alt=\"ESP32\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdaemon-Python%203-yellow\" alt=\"Python\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fintegration-Claude%20Code%20Plugin-7F52FF\" alt=\"Claude Code\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fi18n-EN%20%2F%20中文-lightgrey\" alt=\"i18n\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\u003Cb>把 M5Paper 变成 Claude Code 的物理桌面搭档\u003C\u002Fb>\u003C\u002Fp>\n\n---\n\n## ✨ 简介\n\n用一块 **M5Paper V1.1**（4.7\" 电子墨水屏 \u002F 540×960 \u002F GT911 触摸 \u002F ESP32）做你的 Claude Code 伴侣屏。开着多个 Claude Code 窗口的时候，这块墨水屏会**实时镜像**每个 session 的项目、分支、上下文占用、最新回复和活动日志。Claude 要调用工具时，完整的命令 \u002F diff \u002F 内容会**全屏弹出**等你在**硬件按键**或**触屏**上确认。\n\n---\n\n## 🎛️ 功能\n\n| | |\n| --- | --- |\n| 📊 **多会话 Dashboard** | 左列显示所有在跑的 Claude Code 窗口，点一下切换 focus；右列显示 model + 上下文窗口占用进度条 |\n| 🔐 **硬件审批** | `PreToolUse` 全屏审批卡，完整显示 Bash 命令 \u002F Edit diff \u002F Write 预览。PUSH 同意、DOWN 拒绝；DND 模式（长按 UP）自动批准 |\n| 💬 **触屏回答** | `AskUserQuestion` 最多 4 个选项做成**大按钮**，点一下选项 label 直接回传给 Claude |\n| 🔁 **FIFO 队列** | 多个窗口同时请求审批时，一次弹一个，当前处理完自动弹下一个 |\n| 🀄 **中英双语** | 内置 3.4MB CJK TTF，UI 支持 EN \u002F 中文 切换（设置页里点）；所有 prompt \u002F 回复 \u002F 活动都能显示中文 |\n| 🔌 **双 Transport** | USB 串口（默认、零配置）或 BLE（Nordic UART、macOS 配对 passkey），自动选择 |\n| ⚙️ **设置页** | 右上角点 `SETTINGS` \u002F `设置`，查看 transport、电量、会话数、DND、预算、运行时长、最后消息 |\n| 🐱 **猫伙伴** | 底部一只 ASCII 猫跟状态变化表情（idle\u002Fbusy\u002Fattention\u002Fcelebrate\u002FDND\u002Fsleep） |\n| 🔌 **Claude Code 插件** | 一条 `\u002Fbuddy-install` 搞定 PlatformIO + Python 依赖 + mklittlefs 架构补丁 + hooks 合并 + 固件\u002F字体刷录 + daemon 后台启动 |\n\n---\n\n## 🛠️ 硬件\n\n- **M5Paper V1.1**（4.7\" 电子墨水屏、540×960、GT911 电容触摸、ESP32、16MB Flash）\n- 一条 USB-C 线（初次烧录必须，之后可以换 BLE）\n\n---\n\n## 🚀 快速开始\n\n**前置**：[PlatformIO Core](https:\u002F\u002Fdocs.platformio.org\u002Fen\u002Flatest\u002Fcore\u002Finstallation\u002F)、Homebrew（Apple Silicon 下装 `mklittlefs` 用）、一台 M5Paper V1.1。\n\n```bash\n# 克隆\ngit clone https:\u002F\u002Fgithub.com\u002Fop7418\u002Fm5-paper-buddy.git\ncd m5-paper-buddy\n\n# 作为 Claude Code 插件安装（推荐）\n# 把本仓库 plugin\u002F 目录加到 Claude Code 的 plugin 路径下，然后：\n\u002Fbuddy-install\n```\n\n`\u002Fbuddy-install` 会自动：\n\n1. 验证 PlatformIO 已装\n2. 装 Python 依赖（`pyserial`、BLE 模式额外装 `bleak`）\n3. Apple Silicon 下**自动修复** PlatformIO 自带 x86_64 `mklittlefs`（`brew install mklittlefs` + symlink）\n4. 把 hook 配置合并进 `~\u002F.claude\u002Fsettings.json`（自动备份原文件）\n5. 如果 Paper 已插 USB，**刷 firmware + 字体**\n6. 后台启动 daemon\n\n**手工模式（不走插件）**：\n\n```bash\npio run -e m5paper -t uploadfs          # 刷字体进 LittleFS（~90s）\npio run -e m5paper -t upload            # 刷固件（~30s）\npython3 tools\u002Fclaude_code_bridge.py --budget 200000\n\n# 然后把 plugin\u002Fsettings\u002Fhooks.json 的 hooks 块手动合并到\n# ~\u002F.claude\u002Fsettings.json\n```\n\n---\n\n## 📟 日常使用\n\n装完以后 Claude Code 里有这几个斜杠命令：\n\n| 命令 | 作用 |\n| --- | --- |\n| `\u002Fbuddy-install` | 首次安装 \u002F 重新校验环境 |\n| `\u002Fbuddy-start` | 启动 daemon（幂等） |\n| `\u002Fbuddy-stop` | 停止 daemon |\n| `\u002Fbuddy-status` | 看 daemon pid、串口、hooks 安装情况、日志尾部 |\n| `\u002Fbuddy-flash` | 重新编译 + 烧录固件和字体（stop → flash → start） |\n\n状态目录：`~\u002F.claude-buddy\u002F`（pid、log）。\n\n---\n\n## ⌨️ 控制\n\n| 按键 \u002F 区域 | Dashboard 状态页 | 审批卡片 |\n| --- | --- | --- |\n| **PUSH**（中） | 触发一次重绘 | **同意** |\n| **DOWN**（下） | 切换 demo 模式 | **拒绝** |\n| **UP**（上） | 短按：强制 GC16 全刷（清残影）· 长按 1.5s：切换 **DND 勿扰** | — |\n| 点会话行 | 切换 dashboard focus 到该 session | — |\n| 点右上 `SETTINGS` | 打开设置页 | — |\n| 点选项卡片 | — | 回答 `AskUserQuestion` |\n\n---\n\n## 🔌 Transport\n\n默认 `BUDDY_TRANSPORT=auto` —— 有 USB 走 USB，没有就 BLE。\n\n```bash\nBUDDY_TRANSPORT=ble    \u002Fbuddy-start\nBUDDY_TRANSPORT=serial \u002Fbuddy-start\n```\n\nBLE 首次连接会触发 macOS 系统配对对话框，Paper 屏幕上显示 6 位 passkey，你输进去即可。以后自动重连。\n\n---\n\n## 💰 上下文预算\n\n屏幕上的进度条显示 **当前 focus 的 session 的上下文窗口占用量** ÷ 上限，读取自 session transcript JSONL 里最后一条 assistant 消息的 `usage.input_tokens + output_tokens`。\n\n默认上限 200K（Claude 4.6 标准上下文）。要用 1M 上下文的 4.7 beta：\n\n```bash\nBUDDY_BUDGET=1000000 \u002Fbuddy-start\n```\n\n设 0 隐藏进度条。\n\n---\n\n## 🌐 语言切换\n\n默认英文。点 `SETTINGS` → 第一行 **language \u002F 语言** → 切换到中文。选择写入 NVS，重启保留。\n\n---\n\n## 📂 目录结构\n\n```\nsrc\u002F\n  ble_bridge.cpp\u002Fh       # Nordic UART Service，双向行缓冲 TX\u002FRX\n  stats.h                # NVS 状态（approvals\u002Fdenials\u002Flevel\u002FDND\u002Flanguage）\n  paper\u002F\n    main.cpp             # UI、状态机、触屏、设置页、i18n\n    data_paper.h         # TamaState + JSON 协议解析（UTF-8 安全）\n    xfer_paper.h         # status 响应、name\u002Fowner\u002Funpair 命令\n    buddy_frames.h       # ASCII 猫的 6 个状态帧\ndata\u002Fcjk.ttf             # CJK 字体，通过 uploadfs 刷进 LittleFS\npartitions-m5paper.csv   # 3MB app + 13MB LittleFS 分区表\nplatformio.ini\nplugin\u002F                  # Claude Code 插件打包\n  plugin.json            # manifest\n  commands\u002F              # \u002Fbuddy-* 斜杠命令\n  scripts\u002F               # install \u002F start \u002F stop \u002F status \u002F flash \u002F common\n  settings\u002Fhooks.json    # 要合并到 ~\u002F.claude\u002Fsettings.json 的 hooks 块\n  README.md              # 插件自身的 README\ntools\u002Fclaude_code_bridge.py   # daemon: HTTP → serial\u002FBLE 桥接\n```\n\n---\n\n## 📖 深入阅读\n\n- **[docs\u002FARCHITECTURE.md](docs\u002FARCHITECTURE.md)** —— 技术架构 \u002F 通信协议 \u002F daemon 与固件内部 \u002F 踩过的坑\n- **[docs\u002FPRODUCT.md](docs\u002FPRODUCT.md)** —— 产品思考 \u002F 设计取舍 \u002F 未来畅想 \u002F 给想 fork 的人\n\n---\n\n## 🧩 开发\n\n固件改完后：\n\n```bash\npio run -e m5paper              # 只 build\npio run -e m5paper -t upload    # 烧固件\npio run -e m5paper -t uploadfs  # 更新 LittleFS（字体变了才需要）\n```\n\ndaemon 改完直接重启：\n\n```bash\n\u002Fbuddy-stop && \u002Fbuddy-start\n# 或：\nplugin\u002Fscripts\u002Fstop.sh && plugin\u002Fscripts\u002Fstart.sh\n```\n\n看日志：`tail -f ~\u002F.claude-buddy\u002Fdaemon.log`\n\n---\n\n## 🙏 致谢\n\n本项目参考了 Anthropic 的 [`claude-desktop-buddy`](https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-desktop-buddy) —— Nordic UART Service + heartbeat-JSON 通信协议沿用它的形状，因此理论上这块 Paper 也能被原项目的桌面端 bridge 驱动。\n\n内置字体是 GenSenRounded Regular，来自 M5Stack 的 `M5EPD` 库示例。\n\n---\n\n## 📜 协议\n\n本项目使用 **[GPL-3.0](LICENSE)** 协议，额外附加**署名要求**：\n\n> **任何 fork \u002F 修改 \u002F 再分发，都必须：**\n>\n> 1. 保留 `Copyright © 2026 op7418` 版权声明\n> 2. 在 README 或 About 里**显眼地署名** \"op7418 \u002F m5-paper-buddy\"\n> 3. 衍生作品自身也必须 **以 GPL-3.0 或更高版本开源**，并**公开完整源代码**\n\n换句话说：你可以自由 fork \u002F 改 \u002F 用在商业场景里，但改完的版本也必须开源 + 署名。合了就必须开源，不接受闭源衍生。\n\n详见 [LICENSE](LICENSE) 文件里的 \"Attribution & derivative obligations\" 段落。\n\n\u003Cdetails>\n\u003Csummary>第三方组件\u003C\u002Fsummary>\n\n- `data\u002Fcjk.ttf`：GenSenRounded Regular，来自 M5EPD 库示例，字体本身的许可条款适用于该文件\n- Nordic UART Service UUID 与 heartbeat JSON schema：参考自 anthropics\u002Fclaude-desktop-buddy（MIT）\n\n\u003C\u002Fdetails>\n","m5-paper-buddy 项目旨在将 M5Paper V1.1 电子墨水屏设备转变为 Claude Code 的多会话看板和硬件审批面板。其核心功能包括实时镜像多个 Claude Code 会话的状态、提供全屏硬件审批卡以及支持触屏回答选项，同时内置中英双语界面和 CJK 字体支持。该项目利用 ESP32 微控制器和 PlatformIO 进行开发，支持通过 USB 或 BLE 连接，并可作为 Claude Code 插件轻松安装。适合需要在物理界面上管理和审批代码操作的开发者使用，特别是在多任务处理和跨语言环境中。","2026-06-11 02:48:05","CREATED_QUERY"]