https://github.com/op7418/ai-desk-card
桌面 AI 副屏 Skill：M5Paper 墨水屏 + AI Agent 推送 widget。装 Skill 后由 Agent 自动引导烧固件、配 Wi-Fi、推送内容。本地运行、无云依赖。
https://github.com/op7418/ai-desk-card
ai-agent ai-skill ambient-display claude-code codex dashboard desk-card e-ink esp32 glanceable-display m5paper secondary-display skill skills
Last synced: about 1 month ago
JSON representation
桌面 AI 副屏 Skill：M5Paper 墨水屏 + AI Agent 推送 widget。装 Skill 后由 Agent 自动引导烧固件、配 Wi-Fi、推送内容。本地运行、无云依赖。
- Host: GitHub
- URL: https://github.com/op7418/ai-desk-card
- Owner: op7418
- License: other
- Created: 2026-05-21T15:07:07.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-22T17:13:59.000Z (about 2 months ago)
- Last Synced: 2026-05-22T17:36:10.939Z (about 2 months ago)
- Topics: ai-agent, ai-skill, ambient-display, claude-code, codex, dashboard, desk-card, e-ink, esp32, glanceable-display, m5paper, secondary-display, skill, skills
- Language: Python
- Homepage: https://github.com/op7418/ai-desk-card
- Size: 2.37 MB
- Stars: 17
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.en.md
- License: LICENSE
Awesome Lists containing this project
README
# AI Desk Card · An AI-Driven Desk Companion Skill
> 🇨🇳 **中文版（主文档）: [README.md](./README.md)**
A Skill that turns an [M5Paper V1.1](https://docs.m5stack.com/en/core/m5paper)
e-ink panel into a desk companion driven by an AI agent (Claude Code,
Codex, Cursor, etc.). The agent decides what to push: weather, calendar,
todos, PR queue, AI session status, break reminders…
**Once you install the Skill, the agent walks you through firmware
flashing, Wi-Fi provisioning, and daily widget pushes** — you don't run
a single `pio` or `curl` command by hand.
```
You ──ask naturally──▶ AI Agent ──triggers──▶ Skill ──auto-runs──▶ M5Paper
```
## 30 seconds to start
```bash
npx skills add https://github.com/op7418/ai-desk-card --skill ai-desk-card
```
Or paste this to any AI Agent with shell access:
```text
Install the ai-desk-card Skill. Clone https://github.com/op7418/ai-desk-card
into ~/.claude/skills/ai-desk-card. After install, verify SKILL.md, flows/,
daemon/, src/, assets/ all exist.
```
To update an existing install:
```text
Update ai-desk-card. cd into ~/.claude/skills/ai-desk-card, git pull, and
tell me the latest commit.
```
Then assuming you have an M5Paper V1.1 and a USB-C data cable, just say:
```text
Help me set up ai-desk-card. I have an M5Paper V1.1 plugged in over USB-C.
```
The Skill will automatically:
1. Probe current state (PlatformIO, USB device, daemon, Wi-Fi)
2. Install what's missing (`pipx install platformio` if needed)
3. Compile + flash CJK font + flash firmware (~1 minute)
4. Start the daemon
5. Ask for your Wi-Fi password → provision
6. Push the first widget
After that, daily use is a natural conversation:
```text
Show today's Beijing weather on my card.
Refresh weather and unread mail every 30 min on workday 8am-10pm.
What's on my card right now?
Auto-sleep at 11pm and show my business card.
```
## What you get
- 🖥 **Ambient desk display**: a 540×960 e-ink panel sits next to your monitor — glance, don't context-switch
- 🤖 **AI-pushed content**: the agent decides what widget to send and when; you don't open a browser for weather
- 📦 **16 widget types**: weather / calendar / todo / focus / inbox / pr-queue / ai-status / git-status / now-playing / break-reminder / scratch / messages / deadlines / next-meeting / system / ai-tasks
- 🎨 **Server-side render**: daemon uses Python + Pillow; want a new widget? Edit Python, no C++
- 🔌 **Three power modes auto-switch**: USB-powered / USB-data-only / battery + BLE standby (months of life)
- 🌐 **Wi-Fi LAN, 0.2 s per frame**: local HTTP, no cloud
- 💤 **Sleep at zero watts, last frame retained**: e-ink physics; ~6 months on a charge in arch C
- 👆 **Tappable bottom-bar chips**: "Sleep" → push business card + deep sleep; "Settings" → settings page. 150 ms tap-ack flash
- ⏰ **Auto-sleep at quiet hours**: daemon flips to business card without needing the agent online
## When it fits / when it doesn't
**✅ Good fit if**:
- You want an always-on side display but don't want another bright monitor
- You already use Claude Code / Codex / Cursor and want an ambient physical output
- You like e-ink's low-strain feel (not glaring, not distracting)
- You accept a ~10 min one-time hardware setup (then zero maintenance)
**❌ Not a fit if**:
- You need fast-refresh content (stock tickers, video, animation) — e-ink can't
- You don't want to buy hardware or flash firmware
- You need rich touch interaction (touch works but e-ink is slow)
## Common scenarios
| You say | Agent does |
|------|------|
| "Help me set up ai-desk-card" | Full onboarding: probe → flash firmware → start daemon → provision Wi-Fi |
| "Show today's weather on my card" | Push weather widget |
| "Put my schedule on it" | Push calendar widget, auto-read macOS Calendar |
| "Show what I'm working on" | Push focus widget |
| "Refresh every 30 min" | Write `~/.ai-desk-card/interests.yaml` + register loop |
| "Auto-sleep at 11pm with my business card" | Configure quiet_hours, daemon handles it |
| "Card won't connect" | Run diagnostic flow → locate issue → suggest fix |
| "I changed Wi-Fi" | Run wifi-setup flow |
| "What's on my card now?" | curl the daemon for a current-frame PNG preview |
## Platform support
| Agent | Status | Notes |
|------|------|------|
| Claude Code | ✅ Primary | Native Skill + slash command convenience layer |
| Codex CLI | 🟡 Same SKILL.md format | Should work, not deeply tested |
| Gemini CLI | 🟡 Should work | Same |
| Cursor | 🟡 Works | Needs shell permission |
| Aider | 🟡 Works | Same |
| Self-built agent | ✅ | Any agent that recognizes SKILL.md + has shell access |
## Hardware you need
| Item | Notes |
|------|------|
| **M5Paper V1.1** | Primary target. ~¥600 / $90. [Official store](https://shop.m5stack.com/products/m5paper-v1-1) / Amazon / AliExpress |
| M5Paper V1.0 | Likely works, battery threshold (`4150 mV`) may need tuning |
| M5Paper S3 | Needs porting (1-2 days, BLE stack differs) |
| USB-C **data cable** | Used once for flashing. Charge-only cables don't work |
| (optional) USB-C charger | Needed for always-on Wi-Fi mode |
> ⚠️ **You don't need to pre-install PlatformIO / compilers / Python** — if the Skill detects something missing, it lets the agent install it.
## Install
### Option 1: One-line install (recommended)
```bash
npx skills add https://github.com/op7418/ai-desk-card --skill ai-desk-card
```
### Option 2: Ask the AI to install
Copy this and paste to Claude Code / Cursor / any AI Agent with shell access:
> Install the `ai-desk-card` Skill. Steps:
>
> 1. Ensure `~/.claude/skills/` exists (create if not)
> 2. Run `git clone https://github.com/op7418/ai-desk-card.git ~/.claude/skills/ai-desk-card`
> 3. Verify: `ls ~/.claude/skills/ai-desk-card/` should show `SKILL.md`, `flows/`, `plugin/`, `daemon/`, `src/`, `assets/`
> 4. Tell me when done; from then on saying "set up the card" will trigger this Skill
### Option 3: Manual clone
```bash
git clone https://github.com/op7418/ai-desk-card.git ~/.claude/skills/ai-desk-card
```
### Trigger keywords
After install, the agent auto-triggers the Skill when you mention any of:
- "card" / "desk card" / "e-ink display" / "secondary display"
- "show X on my card"
- "just got an M5Paper" / "first-time setup" / "flash firmware"
- "refresh every N min" / "auto-refresh"
- "sleep the card" / "show business card"
- "ai-desk-card"
## How it works
The Skill is a structured workflow; the agent steps through it automatically:
1. **Onboarding (flow 01)** — probe PlatformIO + USB → walk through firmware flash
2. **Transport diagnosis (flow 02)** — locate issues when device is unreachable
3. **Wi-Fi setup (flow 03)** — provision credentials into device NVS
4. **Interests (flow 04)** — first-time "what do you want to see, how often"
5. **Push widget (flow 05)** — daily hot path
6. **Schedule (flow 06)** — agent's own loop / cron registration
7. **Sleep (flow 07)** — business card + deep sleep at zero watts
Full sub-flows live in [`flows/`](./flows/). Main routing in [`SKILL.md`](./SKILL.md).
## 16 widget types
**Work staples**:
- `weather` · `calendar` · `next-meeting`
- `todo` · `focus` · `deadlines`
- `inbox` · `messages` · `pr-queue`
- `git-status` · `system` · `now-playing`
**Notes / pacing**:
- `scratch` · `break-reminder`
**AI monitoring**:
- `ai-status` · `ai-tasks`
**4 slots / 2-1-1 layout**:
```
┌────────────┬────────────┐
│ top-left │ top-right │ ← 270×280 each
├────────────┴────────────┤
│ middle │ ← 540×340 full-width
├─────────────────────────┤
│ bottom │ ← 540×280 full-width
├─────────────────────────┤
│ bottom bar (chips) │ ← 60 px, "Sleep" + "Settings"
└─────────────────────────┘
```
Plus `full` (540×960) which takes over the whole screen — used for the business card / boot splash.
Full schema in [`plugin/skills/card-widget/schemas/`](./plugin/skills/card-widget/schemas/).
## Auto-refresh (optional)
When the Skill first asks "which widgets do you want, how often", it writes `~/.ai-desk-card/interests.yaml`:
```yaml
version: 1
slots:
top-left: weather
top-right: calendar
middle: todo
bottom: inbox
schedule:
cadence: "30m" # 5m / 15m / 30m / 1h / 2h
hours: "08-22"
days: "mon-fri"
timezone: "Asia/Shanghai"
data_sources:
weather:
city: "Beijing"
calendar:
source: "macos" # or google / ics-url
todo:
source: "reminders" # or things3 / todoist
git_status:
repo: "/Users/you/code/main-project"
# At quiet_hours.start, switch to business card + deep sleep.
# Daemon handles this in the background — agent doesn't have to be online.
quiet_hours:
enabled: true
start: "23:00"
end: "07:00"
```
Three ways to trigger the refresh:
- **Agent's native loop (recommended)**: Claude Code's `/loop 30m`, `ScheduleWakeup`, etc.
- **cron**: `crontab -e` line: `*/30 8-21 * * 1-5 bash /path/to/ai-desk-card/plugin/skills/card-refresh/scripts/refresh_loop.sh`
- **No-AI fallback**: weather / system / git don't need AI — run `fallback_refresh.py` directly
## Three power-mode architectures
| Mode | State | Push latency | Battery |
|------|------|---------|------|
| **A** Always plugged | USB-C power + Wi-Fi always on | 0.2 s | n/a (powered) |
| **B** USB only | USB data cable (no Wi-Fi yet) | 1 s region / 32 s full | n/a (powered) |
| **C** Battery + BLE standby | Wi-Fi off, daemon wakes via BLE | 5 s wake + 0.2 s push | ~6 months |
Arch C is the favorite: the panel sits on your desk for months without charging; when the agent has something to push, BLE wake → bring up Wi-Fi → HTTP push → 30 s linger → drop Wi-Fi. ~0.2 mAh per push × 24 pushes/day × 6 months = 1150 mAh battery.
## Directory structure
```
ai-desk-card/
├── SKILL.md ← Agent entry point (any-agent)
├── scripts/state.sh ← State probe — JSON: daemon / transport / wifi / device / interests
├── flows/ ← 7 sub-flows (~60-100 lines each)
│ ├── 01_install.md Zero-state hardware + firmware flash
│ ├── 02_transport.md Daemon-can't-reach-device diagnostic
│ ├── 03_wifi.md Wi-Fi provisioning
│ ├── 04_interests.md interests.yaml guided setup
│ ├── 05_push.md Widget push hot path
│ ├── 06_schedule.md Scheduled-push protocol
│ └── 07_sleep.md Business card + deep sleep
├── plugin/ ← Claude Code convenience layer (slash + shared scripts)
│ ├── plugin.json
│ ├── commands/ ← /card-* commands
│ ├── scripts/ ← start.sh / stop.sh / status.sh
│ └── skills/ ← Sub-skills, called indirectly by main SKILL.md
├── daemon/
│ ├── card_daemon.py ← HTTP bridge + transport layer + background loops
│ ├── card_render.py ← Widget view renderer
│ ├── card_render_settings.py
│ └── card_render_sleep.py ← Business card renderer
├── src/ ← Firmware (frame_receiver / wifi / http / ble / touch poll)
├── assets/
│ ├── profile.yaml ← Your business-card info (shown when sleeping)
│ ├── qr.png ← Optional QR
│ └── avatar.png ← Optional avatar
├── data/cjk.ttf ← CJK font (flashed to LittleFS once)
├── platformio.ini
├── partitions.csv
├── HANDOVER.md ← Engineering handover
└── PRODUCT.md ← Product narrative
```
## How it really works (one diagram)
```
You speak M5Paper
│ ▲
▼ │
AI Agent ──────┐ │
│ triggers Skill │
▼ │
SKILL.md routing │
│ │
│ scripts/state.sh probes: │
│ · pio / firmware / daemon │
│ · device.alive / wifi │
│ · interests.yaml │
│ │
└─▶ picks one of 7 sub-flows │
│ │
▼ │
Agent executes │
│ │
▼ │
POST to daemon (127.0.0.1:9877) │
│ │
▼ │
daemon renders (Python + Pillow) │
│ │
▼ │
HTTP / USB / BLE push ──────────────┘
```
## FAQ
**Q: I really don't need to flash firmware myself?**
No. After install, just say "set up the card" — the agent probes state, installs PlatformIO (if missing), runs `pio run -t upload`, flashes the CJK font, and tells you what it's doing at each step.
**Q: I don't have M5Paper V1.1 — anything else?**
M5Paper V1.0 likely works. M5Paper S3 needs porting (BLE stack differs). Inkplate / Waveshare / etc. aren't supported yet — roadmap item.
**Q: Do I have to use Claude Code?**
No. `SKILL.md` is agent-agnostic — any agent that recognizes the format + has shell permission works (Codex / Cursor / Aider / self-built). The `plugin/` slash commands are a Claude Code convenience layer, not the core.
**Q: What about network?**
All local. Daemon runs on your machine (127.0.0.1:9877). Device and computer are on the same Wi-Fi LAN. **ESP32 only supports 2.4 GHz** — 5 GHz-only SSIDs won't connect.
**Q: Chinese characters show as tofu boxes?**
You skipped the LittleFS font flash. Ask the agent to "run uploadfs again".
**Q: How do I update the firmware?**
Say "update ai-desk-card and re-flash". The Skill pulls new code + builds + uploads.
**Q: Does it work outside macOS?**
Daemon should work on Linux (not deeply tested). Windows needs WSL2. PlatformIO is cross-platform.
**Q: Does any data go to the cloud?**
No. Daemon binds 127.0.0.1 by default (device→daemon status_report goes over LAN). Wi-Fi credentials live in device NVS, never in daemon logs or git.
## Roadmap
- M5Paper V1.0 / S3 port verification
- Inkplate / Waveshare / other e-ink board support
- Captive portal Wi-Fi provisioning (no daemon needed)
- Hardware power-button intercept (long-press 2s → render business card before deep sleep)
- More widget schemas (Feishu / WeChat / Linear / Notion)
- Multi-device dashboard sync
## Contributing
Issues and PRs welcome at https://github.com/op7418/ai-desk-card.
Most valuable contributions:
- Hardware photos / videos (helps new users see the form factor)
- Linux / Windows daemon testing reports
- M5Paper V1.0 / S3 firmware port verification
- New widget schemas + renderers
- Translation / docs improvements
## License
GPL-3.0 with attribution clause · see [LICENSE](./LICENSE)
Vendored EPDGUI framework (from upstream M5Paper_FactoryTest): MIT, © 2020 m5stack.