m5-paper-buddy

Name: m5-paper-buddy
Author: op7418

Verified

📟 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 的多会话看板 + 硬件审批面板。

127stars

14forks

C++

Installation

# Add to your Claude Code skills
git clone https://github.com/op7418/m5-paper-buddy

Getting Started

Guides for using ide extensions skills like m5-paper-buddy.

Security ReportVerified

Last scanned: 5/30/2026

{
  "issues": [],
  "status": "PASSED",
  "scannedAt": "2026-05-30T16:22:29.468Z",
  "npmAuditRan": true,
  "pipAuditRan": true
}

README.md

Frequently Asked Questions

What is m5-paper-buddy?

m5-paper-buddy is an open-source ide extensions skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by op7418. 📟 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 的多会话看板 + 硬件审批面板。. It has 127 GitHub stars.

Is m5-paper-buddy safe to use?

Yes. m5-paper-buddy passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.

How do I install m5-paper-buddy?

Clone the repository with "git clone https://github.com/op7418/m5-paper-buddy" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is m5-paper-buddy written in?

m5-paper-buddy is primarily written in C++. It is open-source under op7418 on GitHub, so you can review or fork the full source.

Are there alternatives to m5-paper-buddy?

Yes. SkillsLLM lists many other IDE Extensions skills you can browse and compare side by side. Open the IDE Extensions category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh m5-paper-buddy against similar tools.

Agentic AI for Beginners

Build your first AI agent from scratch - tool use, ReAct pattern, memory, deployment

41 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

ECC

by affaan-m

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

230,427

Popular in IDE Extensions

Top skills in this category by stars

OpenMythos

by kyegomez

A theoretical reconstruction of the Claude Mythos architecture, built from first principles using the available research literature.

14,703

VibesOS deep-project

m5-paper-buddy

✨ 简介

用一块 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 会自动：

验证 PlatformIO 已装
装 Python 依赖（pyserial、BLE 模式额外装 bleak）
Apple Silicon 下自动修复 PlatformIO 自带 x86_64 mklittlefs（brew install mklittlefs + symlink）
把 hook 配置合并进 ~/.claude/settings.json（自动备份原文件）
如果 Paper 已插 USB，刷 firmware + 字体
后台启动 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，重启保留。

📂 目录结构

src/
  ble_bridge.cpp/h       # Nordic UART Service，双向行缓冲 TX/RX
  stats.h                # NVS 状态（approvals/denials/level/DND/language）
  paper/
    main.cpp             # UI、状态机、触屏、设置页、i18n
    data_paper.h         # TamaState + JSON 协议解析（UTF-8 安全）
    xfer_paper.h         # status 响应、name/owner/unpair 命令
    buddy_frames.h       # ASCII 猫的 6 个状态帧
data/cjk.ttf             # CJK 字体，通过 uploadfs 刷进 LittleFS
partitions-m5paper.csv   # 3MB app + 13MB LittleFS 分区表
platformio.ini
plugin/                  # Claude Code 插件打包
  plugin.json            # manifest
  commands/              # /buddy-* 斜杠命令
  scripts/               # install / start / stop / status / flash / common
  settings/hooks.json    # 要合并到 ~/.claude/settings.json 的 hooks 块
  README.md              # 插件自身的 README
tools/claude_code_bridge.py   # daemon: HTTP → serial/BLE 桥接

📖 深入阅读

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

🧩 开发

固件改完后：

pio run -e m5paper              # 只 build
pio run -e m5paper -t upload    # 烧固件
pio run -e m5paper -t uploadfs  # 更新 LittleFS（字体变了才需要）

daemon 改完直接重启：

/buddy-stop && /buddy-start
# 或：
plugin/scripts/stop.sh && plugin/scripts/start.sh

看日志：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 / 修改 / 再分发，都必须：

保留 Copyright © 2026 op7418 版权声明

在 README 或 About 里显眼地署名 "op7418 / m5-paper-buddy"

衍生作品自身也必须 以 GPL-3.0 或更高版本开源，并公开完整源代码

换句话说：你可以自由 fork / 改 / 用在商业场景里，但改完的版本也必须开源 + 署名。合了就必须开源，不接受闭源衍生。

详见 LICENSE 文件里的 "Attribution & derivative obligations" 段落。

data/cjk.ttf：GenSenRounded Regular，来自 M5EPD 库示例，字体本身的许可条款适用于该文件
Nordic UART Service UUID 与 heartbeat JSON schema：参考自 anthropics/claude-desktop-buddy（MIT）