Paiban user manual

This manual covers everything: Banban (the device), Paiban Hub (desktop app), the Paiban mini program (WeChat) and the cloud relay. On first use, read sections 1–4 in order; look up the rest when you need it.

The Hub and the device show Chinese text for now; Chinese labels are given in quotes where you need to find them.

• 1. What Paiban is
• 2. What you need
• 3. Installing
• 4. First-time setup
• 5. Connecting agents
• 6. Using Banban
• 7. Paiban Hub
• 8. Mini program
• 9. Different networks: the cloud relay
• 10. Updating, resetting, migrating
• 11. Troubleshooting
• 12. Data and privacy

1. What Paiban is

AI agents such as Claude Code and Codex keep stopping to ask "may I run this command?" or "may I edit this file?". Paiban sends those questions to Banban on your desk: it lights up and looks at you expectantly; click to approve, tilt to deny. When the job is done it shows a happy face. You no longer have to watch the terminal.

Claude Code / Codex / Qwen / Kimi / Gemini
        │ hooks (local)
        ▼
   Paiban Hub (PC) ── LAN / cloud relay ──▶ Banban
                                             ▲ Bluetooth
                                     Paiban mini program

2. What you need

• Hardware: Waveshare ESP32-S3-LCD-1.47B and a USB-C data cable; optionally the 3D-printed case (hardware/proto-147) and a 602025 LiPo battery.
• Computer: Windows 10/11 x64, with your agents installed.
• Phone: WeChat.
• Network: 2.4 GHz Wi-Fi (Banban has no 5 GHz) without a captive portal (hotel or corporate login pages block it).

3. Installing

The latest versions are on the project site and under Releases.

3.1 Flash the firmware

First time, flash the full image paiban-firmware-v*-merged.bin (16 MB, includes the partition table):

pip install esptool
esptool.py --chip esp32s3 --baud 921600 write_flash 0x0 paiban-firmware-v0.5.1-merged.bin

To update later, flash -app.bin at 0x10000; Wi-Fi, reminders, settings and account binding are kept:

esptool.py --chip esp32s3 --baud 921600 write_flash 0x10000 paiban-firmware-v0.5.1-app.bin

If the computer does not see the board, hold BOOT while plugging in USB to enter download mode. Press RST or replug afterwards.

3.2 Install the Hub

1. Download paiban-hub-v*-win-x64.zip and unzip it somewhere permanent (e.g. D:\paiban-apps\PaibanHub).
2. Run PaibanHub.exe. If Windows says it protected your PC, choose "More info → Run anyway" (the app is not code-signed yet).
3. The first run adds a Start menu shortcut and starts with Windows by default (can be turned off in Settings).

Updating: quit the Hub (tray icon → right-click → 退出 / Quit), overwrite the whole folder with the new version and start it again. Settings and login live in %APPDATA%\拍板 Hub and are kept.

3.3 Mini program

Until the mini program is published, import miniapp/ from the repo into WeChat DevTools and use "Preview" to open it on your phone. Accounts and the cloud relay need WeChat Cloud (see miniapp/README.en.md).

4. First-time setup

1. Power Banban: the screen shows a setup QR code and the light breathes white.
2. Wi-Fi from the mini program: "我的 → 添加设备" (Me → Add device), scan the code on Banban's screen (or pick BANBAN-xxxx from the list). Enter the Wi-Fi name and password and tap "测试连接" (Test) first: Banban really tries to connect and tells you whether the password is wrong, the network was not found, or the signal is too weak.
3. Finding the computer: on the same Wi-Fi, the Hub broadcasts on the LAN every 2 seconds and Banban connects by itself; the dot in the top-left of its screen turns green.
4. Not found? The router may isolate devices from each other (guest networks often do). In the mini program choose a manual computer address and enter the address shown on the Hub's overview page (e.g. 192.168.1.20:8765).
5. Connect an agent: in the Hub, "接入 agent" (Connect agents) → "接入" (Connect) next to Claude Code or another client.
6. Try it: on the Hub's overview page, "测试审批" (Test approval). Banban shows an approval; click to approve.

5. Connecting agents

One click on the Hub's "接入 agent" page. The Hub writes hooks into each client's config file, backs it up first, and "撤销" (Undo) removes only the lines Paiban wrote — your own configuration is untouched.

• Sent for approval: running commands, editing or writing files — anything with side effects. Reading and searching never bother you.
• Notifications: task finished (with the agent's last message), needs your attention (e.g. it asked you something), error.
• If the Hub is not running: the hook fails and the agent asks in the terminal as usual; nothing hangs.
• After changing the Hub port: click "重新写入" (Rewrite) for each connected client.

Other programs can use the Hub too:

# send a notification
curl -X POST http://127.0.0.1:8765/notify -d '{"title":"Backup done","body":"12 GB","agent":"nightly"}'
# ask for approval and wait: allow / deny / defer (defer = handed back or timed out)
curl -X POST http://127.0.0.1:8765/approve -d '{"agent":"deploy","summary":"Ship to production","detail":"v2.3.1","timeout":120}'

6. Using Banban

6.1 One button plus motion

The screen is used sideways with the USB port on the right. BOOT is the only button.

After 60 s without input the screen dims (Banban gets sleepy); approvals and reminders wake it. On battery it saves more: dim after 30 s, screen off after 3 min; a button press, pick-up, tap or approval wakes it at once (see 6.8).

How tilt-to-approve avoids accidents: after an approval appears, Banban must first rest level and still for a moment before tilting counts; you then tilt it (about 20° by default) and hold steadily for 1 s (any wobble, or a recent shake or tap, restarts the timer); only left/right tilt counts, not tipping forward/back (e.g. picking it up to read); after one decision it must return to level before tilting works again. In the mini program, "设置 → 倾斜灵敏度" (tilt sensitivity) offers sensitive (15°, 0.8 s), medium (20°, 1 s) and stiff (28°, 1.3 s); you can also switch tilt off and use the button only.

6.2 Four pages

• Clock: time, date, Banban's face and the overall agent state (idle / working / waiting for you / done).
• Agents: the last 6 agent sessions with project, current activity, state and duration.
• Info: name, Wi-Fi, IP, battery, Bluetooth, cloud relay, Hub address, firmware. Long press shows the setup QR code.
• Play: play with Banban; tilt it and it rolls around.

6.3 Faces and lights

6.4 Approvals

• The screen shows which agent, what it wants to do ("运行 npm test" = run npm test, "修改文件 report.md" = edit report.md), the details and the time left.
• Timeout (90 s by default, configurable in the Hub) hands the decision back to the computer; the agent asks in the terminal as usual.
• When the Hub window and the mini program are also open, whichever decides first wins; the same approval closes everywhere else.

6.5 Notifications, reminders, ask a question

• Notifications: pop up when a task finishes, needs a look or fails, and close after 20 s; the last 6 also show in the mini program.
• Reminders: add them in the mini program's "提醒" (Reminders) page — time, every day / weekdays / weekends / chosen weekdays / once, and text; up to 12. They live on Banban and ring even without a network. Click = done, long press or shake = snooze 10 minutes.
• Ask a question: in the mini program's "问一句" (Ask) page pick who answers (only the agents installed on the computer are listed: Claude Code / Codex / Gemini / Qwen / Kimi) and type. The question travels via Banban to the computer and that agent answers; Banban's title bar says e.g. "Codex 的回答" (Codex's answer), and the current answer and history in the mini program are tagged with the agent too. Needs Hub 0.3, firmware 0.6 and mini program 0.6 or later.

6.6 Do not disturb

Long press BOOT on the clock page, lay Banban face down, or switch it on in the mini program. The light stays off and notifications do not pop up; approvals still show (otherwise the agent would hang).

6.7 Banban's mood

Banban has moods, so its idle face is no longer the same all day:

• Daily rhythm: lively in the morning, drowsy after lunch, very sleepy late at night; it greets you once each in the morning, at noon, in the evening and late at night.
• Weather: the Hub sends the local weather every 30 minutes (Hub settings → 板板的心情 / Banban's mood; can be turned off or set to a city). The clock's bottom bar shows e.g. "18° 小雨 · 一切安静" (18° light rain · all quiet); rain makes it listen to the rain, snow makes it happy, heat makes it sweat, cold makes it pout.
• How you treat it: a tap makes it happy, three taps give heart eyes; a shake makes it dizzy and repeated shaking annoys it; a violent shake scares it ("救命——", help!) and then it sulks; picked up after a long rest it gets curious ("要带我去哪？", where are we going?); left tilted, its eyes look downhill. Left alone for hours it feels a bit lonely.
• Work: finished tasks cheer it up, errors make it sad; it is listless when the battery is very low.
• Little habits: every 10–45 s while idle it does something small at random: looks around, hums, yawns, daydreams, thinks about snacks, stretches, dozes off… more often when it is happy and awake.

The mini program's home page shows Banban's current mood. Needs firmware 0.7 and Hub 0.4 or later.

6.8 Power saving (battery)

Mini program "设置 → 省电" (Settings → Power saving) has three choices: save on battery (default), always save, never save.

Below 3 % battery for 2 minutes Banban goes into deep sleep to protect the battery; after charging, press BOOT to wake it.

7. Paiban Hub

Closing the window minimizes it to the tray (or quits, if you change that in Settings). The tray icon reflects the state — not running, waiting for a device, device online, approval waiting; hover for details, right-click for a test notification or to quit.

7.1 Overview ("概览")

• Banban's status, address, firmware, model, connection (LAN / cloud relay) and uptime.
• Pending approvals: approve / deny / hand back right from the computer.
• Agent sessions, recent notifications and decisions, counters (approved / denied / handed back / notifications).
• Test buttons (approval, notification, agent list) to see Banban react without any agent.

7.2 Connect agents ("接入 agent")

See section 5. Each card shows whether the command was found, the config file, the approval capability and notes; "打开位置" (Show) opens the config file in Explorer.

7.3 Account ("账号")

Log in / out of the cloud relay and manage the account's devices — see section 9.

7.4 Activity ("动态")

The last 500 events: agent events, approvals, devices connecting and leaving, errors, filterable by approvals / devices / problems.

7.5 Settings ("设置")

8. Mini program

The mini program talks to Banban over Bluetooth, so the phone needs to be nearby (about 10 m).

9. Different networks: the cloud relay

Work laptop + Banban at home, a laptop on a phone hotspot, the future 4G model — all use the cloud relay. Full steps and the security model are in the cloud relay guide. In short:

1. Log in the computer (once per computer): Hub "账号 → 登录" shows a QR code; scan it with the mini program under "我的 → 电脑与云端中转 → 扫码绑定电脑".
2. Bind Banban (once per device): "绑定到账号" on the Hub's Account page, or in the mini program after Wi-Fi setup; confirm on Banban.
3. From then on it picks the route by itself: LAN on the same Wi-Fi, the relay otherwise, never asking twice.
4. Log out / unbind: Hub "账号 → 登出"; the phone can unbind computers and devices remotely.

The relay runs several replicas: when it is updated, connections move to another replica within a second or two, Banban does not show a disconnect, and approvals sent meanwhile are delivered afterwards.

10. Updating, resetting, migrating

• Firmware: flash -app.bin at 0x10000 (3.1); settings are kept. The Info page shows the version.
• Hub: overwrite the folder (3.2).
• Factory reset: mini program "设置 → 恢复出厂设置". Clears Wi-Fi, reminders, settings and the relay token; the claim key used for binding is kept, so after giving Banban away the new owner binds it by confirming on the device.
• Re-detect pins: when the motion sensor or battery was not detected; the device reboots.
• From "Lingxi"-era versions: settings migrate automatically and old hooks are replaced — see docs/rename.md (Chinese).

11. Troubleshooting

Banban keeps saying "正在找拍板 Hub" (looking for the Hub) - Is the Hub running (icon in the tray)? - Same Wi-Fi? Guest networks and AP isolation block the broadcast → enter the Hub address manually. - The first time, Windows Firewall asks whether PaibanHub may use the network: allow "Private networks".

The agent asks me, but Banban does nothing - Does "接入 agent" show the client as connected? Codex needs /hooks trust once. - Is Banban in do-not-disturb? (Approvals still show, but the light stays off.) - Does the Hub's activity page show the event? If not, click "重新写入" (Rewrite).

Wi-Fi test says the network was not found: Banban only supports 2.4 GHz; give the 2.4 GHz band its own name on dual-band routers.

Tilt works the wrong way round: mini program "设置 → 倾斜方向反过来" (invert tilt), or "校准正放" (calibrate).

"Ask" says the command failed: does that agent's command in Hub settings run in a terminal? e.g. echo hi | claude -p.

"Ask" stays at "thinking" or says not logged in: the command-line Claude Code / Codex must be logged in once in a terminal; the desktop app's login does not carry over.

Battery shows "未检测到" (not detected): normal without a battery; with one, use "重新识别引脚" (re-detect pins).

Cloud relay issues: see the cloud relay guide · FAQ.

12. Data and privacy

• LAN mode: messages stay between your computer and Banban. The Hub's hooks only accept requests from the same machine.
• Mini program: profile (nickname, avatar), device list and usage stats are stored in WeChat Cloud; without WeChat Cloud they stay on the phone.
• Cloud relay: stores only an HMAC of the account (never the WeChat openid), computer names, device ids and token hashes; approval content is forwarded, not stored. The database is backed up daily and kept 30 days. The server can currently see messages in transit; end-to-end encryption is next.
• Leaving: log out in the mini program ("我的 → 退出登录"); unbind computers and devices one by one under "电脑与云端中转".