{"id":50953507,"url":"https://github.com/op7418/m5-paper-buddy","last_synced_at":"2026-06-18T04:01:33.346Z","repository":{"id":352243446,"uuid":"1214402572","full_name":"op7418/m5-paper-buddy","owner":"op7418","description":"📟 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 的多会话看板 + 硬件审批面板。","archived":false,"fork":false,"pushed_at":"2026-04-18T15:21:21.000Z","size":2091,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T17:11:11.797Z","etag":null,"topics":["approval-workflow","arduino","ble","claude","claude-code","claude-code-plugin","e-ink","eink","esp32","hardware","i18n","m5paper","m5stack","platformio"],"latest_commit_sha":null,"homepage":"https://github.com/op7418/m5-paper-buddy","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/op7418.png","metadata":{"files":{"readme":"README.en.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T14:27:30.000Z","updated_at":"2026-04-18T15:21:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/op7418/m5-paper-buddy","commit_stats":null,"previous_names":["op7418/m5-paper-buddy"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/op7418/m5-paper-buddy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/op7418%2Fm5-paper-buddy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/op7418%2Fm5-paper-buddy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/op7418%2Fm5-paper-buddy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/op7418%2Fm5-paper-buddy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/op7418","download_url":"https://codeload.github.com/op7418/m5-paper-buddy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/op7418%2Fm5-paper-buddy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34475375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["approval-workflow","arduino","ble","claude","claude-code","claude-code-plugin","e-ink","eink","esp32","hardware","i18n","m5paper","m5stack","platformio"],"created_at":"2026-06-18T04:01:31.290Z","updated_at":"2026-06-18T04:01:33.340Z","avatar_url":"https://github.com/op7418.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# m5-paper-buddy\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.md\"\u003e中文\u003c/a\u003e · \u003ca href=\"README.en.md\"\u003e\u003cb\u003eEnglish\u003c/b\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/49a543f3-ad1a-4735-a5d1-ef98867cff1e\" alt=\"m5-paper-buddy on an M5Paper V1.1\" width=\"540\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-GPL--3.0-blue.svg\" alt=\"GPL-3.0\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/hardware-M5Paper%20V1.1-orange\" alt=\"M5Paper\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/firmware-ESP32%20%2B%20PlatformIO-brightgreen\" alt=\"ESP32\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/daemon-Python%203-yellow\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/integration-Claude%20Code%20Plugin-7F52FF\" alt=\"Claude Code\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/i18n-EN%20%2F%20中文-lightgrey\" alt=\"i18n\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cb\u003eA physical Claude Code companion running on M5Paper V1.1\u003c/b\u003e\u003c/p\u003e\n\n---\n\n## ✨ Intro\n\nA Claude Code sidekick running on an **M5Paper V1.1** (4.7\" e-ink,\n540×960, GT911 touch, ESP32). Sits on your desk and mirrors every\nClaude Code session you have open: project, branch, model, context\nusage, recent activity, Claude's latest reply. When Claude wants to\nrun a tool, the full content shows up as a full-screen approval card\nwith hardware buttons and touch options.\n\n---\n\n## 🎛️ Features\n\n| | |\n| --- | --- |\n| 📊 **Multi-session dashboard** | Left column lists every active Claude Code window; tap a row to focus. Right column shows model + context-window progress bar. |\n| 🔐 **Hardware approval** | `PreToolUse` shows a full-screen card with the complete command / diff / preview. **PUSH** approves, **DOWN** denies. DND mode (long-press **UP**) auto-approves for batch tasks. |\n| 💬 **Touch-answer questions** | Claude's `AskUserQuestion` options render as up to 4 big tap targets; tapping sends the chosen label back as the answer. |\n| 🔁 **FIFO queue** | Multiple windows asking for approval get queued; resolving the current one automatically pops the next. |\n| 🀄 **Bilingual UI** | 3.4 MB CJK TTF shipped on LittleFS; toggle **English ↔ 中文** in the Settings page. All prompts, replies, activity lines render Chinese correctly. |\n| 🔌 **Two transports** | USB serial (default, zero-setup) or BLE (Nordic UART, macOS passkey pairing), auto-selected. |\n| ⚙️ **Settings page** | Tap **SETTINGS** (top-right) for transport / battery / sessions / DND / budget / uptime / last message / language toggle. |\n| 🐱 **Cat buddy** | A small ASCII cat in the footer reacts to state — idle / busy / attention / celebrate / DND / sleep. |\n| 🔌 **Claude Code plugin** | One `/buddy-install` handles PlatformIO + Python deps + mklittlefs arch patch on Apple Silicon + hooks merge + firmware + filesystem flashing + daemon launch. |\n\n---\n\n## 🛠️ Hardware\n\n- **M5Paper V1.1** (4.7\" e-ink, 540×960, GT911 capacitive touch, ESP32, 16MB flash)\n- USB-C cable (required for initial flash; BLE works afterwards)\n\n---\n\n## 🚀 Quick start\n\n**Prereqs**: [PlatformIO Core](https://docs.platformio.org/en/latest/core/installation/),\nHomebrew (Apple Silicon only, for native `mklittlefs`), and an M5Paper V1.1.\n\n```bash\n# Clone\ngit clone https://github.com/op7418/m5-paper-buddy.git\ncd m5-paper-buddy\n\n# Recommended: install as a Claude Code plugin.\n# Register the plugin/ directory with Claude Code, then:\n/buddy-install\n```\n\n`/buddy-install` automatically:\n\n1. Verifies PlatformIO is installed\n2. Installs Python deps (`pyserial`, `bleak` for BLE mode)\n3. On Apple Silicon, **patches PlatformIO's x86_64 `mklittlefs`**\n   (`brew install mklittlefs` + symlink) so `uploadfs` can run\n4. Merges the hook block into `~/.claude/settings.json` (backs up first)\n5. If a Paper is plugged in, **flashes firmware + filesystem (font)**\n6. Launches the daemon in the background\n\n**Manual install (no plugin)**:\n\n```bash\npio run -e m5paper -t uploadfs          # flash the font to LittleFS (~90s)\npio run -e m5paper -t upload            # flash firmware (~30s)\npython3 tools/claude_code_bridge.py --budget 200000\n\n# Then manually copy plugin/settings/hooks.json's hooks block into\n# ~/.claude/settings.json\n```\n\n---\n\n## 📟 Daily use\n\nOnce installed, these slash commands are available in Claude Code:\n\n| Command | Purpose |\n| --- | --- |\n| `/buddy-install` | First-time setup / re-verify environment |\n| `/buddy-start` | Start the daemon (idempotent) |\n| `/buddy-stop` | Stop the daemon |\n| `/buddy-status` | Daemon pid, serial device, hooks state, tail of log |\n| `/buddy-flash` | Rebuild + reflash firmware AND filesystem (stop → flash → start) |\n\nState directory: `~/.claude-buddy/` (pid, log).\n\n---\n\n## ⌨️ Controls\n\n| Button / zone | Dashboard | Approval card |\n| --- | --- | --- |\n| **PUSH** (middle) | nudge a redraw | **approve** |\n| **DOWN** (bottom) | toggle demo | **deny** |\n| **UP** (top) | short: force GC16 refresh (clears ghosting) · long ≥1.5s: toggle **DND** | — |\n| Tap session row | focus that session on the dashboard | — |\n| Tap `SETTINGS` | open settings page | — |\n| Tap option card | — | answer `AskUserQuestion` |\n\n---\n\n## 🔌 Transport\n\nDefault is `BUDDY_TRANSPORT=auto` — USB serial if plugged in, else BLE.\n\n```bash\nBUDDY_TRANSPORT=ble    /buddy-start\nBUDDY_TRANSPORT=serial /buddy-start\n```\n\nFirst BLE connect triggers macOS's system pairing dialog; the Paper\ndisplays a 6-digit passkey, you type it on the Mac. Subsequent reconnects\nare automatic.\n\n---\n\n## 💰 Context budget\n\nThe progress bar shows the **currently-focused session's**\ncontext-window usage divided by a limit, computed from the last\nassistant message's `usage.input_tokens + output_tokens` in the\nsession's transcript JSONL.\n\nDefault limit is 200K (Claude 4.6 standard context). For the 1M-context\n4.7 beta:\n\n```bash\nBUDDY_BUDGET=1000000 /buddy-start\n```\n\nSet `0` to hide the bar.\n\n---\n\n## 🌐 Language toggle\n\nDefault: English. Tap **SETTINGS → language / 语言** to switch to 中文.\nChoice persists in NVS across reboots.\n\n---\n\n## 📂 Layout\n\n```\nsrc/\n  ble_bridge.cpp/h       # Nordic UART Service, line-buffered TX/RX\n  stats.h                # NVS-backed state (approvals/denials/level/DND/language)\n  paper/\n    main.cpp             # UI, state machine, touch, settings, i18n\n    data_paper.h         # TamaState + JSON parsing (UTF-8 safe)\n    xfer_paper.h         # status responses, name/owner/unpair cmds\n    buddy_frames.h       # ASCII cat frames (6 states)\ndata/cjk.ttf             # CJK font flashed via `pio run -t uploadfs`\npartitions-m5paper.csv   # 3 MB app + 13 MB LittleFS (font needs room)\nplatformio.ini\nplugin/                  # Claude Code plugin\n  plugin.json            # manifest\n  commands/              # /buddy-* slash commands\n  scripts/               # install / start / stop / status / flash / common\n  settings/hooks.json    # hooks to merge into ~/.claude/settings.json\n  README.md              # plugin's own README\ntools/claude_code_bridge.py   # daemon: HTTP → serial/BLE bridge\n```\n\n---\n\n## 📖 Deep dive\n\n- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — technical architecture, wire protocol, daemon + firmware internals, debugging war stories\n- **[docs/PRODUCT.md](docs/PRODUCT.md)** — product thinking, design tradeoffs, future vision, notes for forkers\n\n*(Both docs are in Chinese; feel free to open a PR translating to English.)*\n\n---\n\n## 🧩 Development\n\nFirmware iteration:\n\n```bash\npio run -e m5paper              # build only\npio run -e m5paper -t upload    # flash firmware\npio run -e m5paper -t uploadfs  # refresh LittleFS (only when font changes)\n```\n\nDaemon iteration:\n\n```bash\n/buddy-stop \u0026\u0026 /buddy-start\n# or:\nplugin/scripts/stop.sh \u0026\u0026 plugin/scripts/start.sh\n```\n\nTail the log: `tail -f ~/.claude-buddy/daemon.log`\n\n---\n\n## 🙏 Credits\n\nThis project was inspired by Anthropic's\n[`claude-desktop-buddy`](https://github.com/anthropics/claude-desktop-buddy) —\nthe Nordic UART Service + heartbeat-JSON wire protocol shape is the\nsame, so in principle a Paper running this firmware can also be driven\nby that project's desktop bridge.\n\nBundled font: GenSenRounded Regular, from the M5Stack `M5EPD` library's\nexamples.\n\n---\n\n## 📜 License\n\nThis project is licensed under **[GPL-3.0](LICENSE)** with an explicit\n**attribution clause**:\n\n\u003e **Any fork, modification, or redistribution MUST:**\n\u003e\n\u003e 1. Preserve the `Copyright © 2026 op7418` notice\n\u003e 2. Visibly credit `op7418 / m5-paper-buddy` in the derivative work's\n\u003e    README or About page\n\u003e 3. Release the derivative itself under **GPL-3.0 or later** with\n\u003e    **full source code publicly available**\n\nIn short: you're free to fork / modify / use commercially, but any\nmodified version must be open-source and must credit this project.\nClosed-source derivatives are not permitted.\n\nSee the \"Attribution \u0026 derivative obligations\" section at the top of\n[LICENSE](LICENSE) for the full terms.\n\n\u003cdetails\u003e\n\u003csummary\u003eThird-party components\u003c/summary\u003e\n\n- `data/cjk.ttf`: GenSenRounded Regular, from the M5EPD library's\n  examples. The font's own license terms apply to that file.\n- Nordic UART Service UUIDs and heartbeat JSON schema reference\n  anthropics/claude-desktop-buddy (MIT).\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fop7418%2Fm5-paper-buddy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fop7418%2Fm5-paper-buddy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fop7418%2Fm5-paper-buddy/lists"}