Elevator pitch
Pet2Dial recreates the Codex desktop pet on an M5Stack Dial, then turns the Dial into a rotary remote for Codex tasks: rotate to browse, tap to open the matching conversation.
Story
Codex already has a pet mode inside the desktop app. Pet2Dial moves that experience out of the Mac screen and onto the desk. The result is a small physical companion that shows the selected Codex pet plus waiting, failed, review, and running task state.
The project is designed around the M5Stack Dial's strengths. The circular display makes the pet feel like a small object rather than another window. The rotary encoder becomes a natural way to browse tasks. Touch gives a direct action: tap the selected task card and Codex opens the matching conversation on the Mac.
This makes the Dial feel a little like a handheld remote for an AI coding workspace. In the idle state it is a desk pet. When the knob is turned, it becomes a task switcher for waiting, failed, review, and running work.
What makes it special
1. It is a physical extension of the Codex pet experience.
2. It converts the selected Codex custom pet atlas instead of using a generic static icon.
3. It syncs waiting, failed, review, and running task state over BLE.
4. It uses the Dial's rotary encoder for task browsing.
5. It supports tap-to-open navigation back into the exact Codex conversation.
Hardware
M5Stack Dial with M5StampS3 controller.
Mac running Codex Desktop.
USB-C cable for firmware upload.
Bluetooth Low Energy for live sync after flashing.
How it works
The project has three parts.
First, the pet converter reads the selected Codex custom pet from the local Codex pet folder. It converts the official animated pet atlas into compact RGB565 frames for the M5Stack Dial firmware.
Second, the firmware renders the pet and the task UI. The pet view keeps the pet visible, uses the pet animation for the highest-priority active state, and shows compact counts in two rows: W/F above V/R. Rotating the Dial opens a task card view where the pet shrinks and the selected task becomes readable.
Third, the Mac bridge syncs Codex state to the Dial over BLE. It sends the current pet mode plus waiting, failed, review, and running cards. When the user taps a card, the Dial sends an event back to the Mac bridge, and the bridge opens the matching Codex conversation.
Interaction model
Idle view: the pet sits on the Dial, with W/F and V/R counters above it.
Rotate: the Dial becomes a task browser.
Tap: open the selected Codex conversation on the Mac.
Rotate away: after a review card has been opened, it can leave the visible review queue.
Build steps
Clone the repository:
git clone https://github.com/zzliu-coder/pet2dial.git
cd pet2dial
Run the environment check:
python3 skill/pet2dial/scripts/pet2dial.py doctor
Create the generated working project:
python3 skill/pet2dial/scripts/pet2dial.py init --force
Install local dependencies:
python3 skill/pet2dial/scripts/pet2dial.py setup-env
Convert the selected Codex pet:
python3 skill/pet2dial/scripts/pet2dial.py convert
Build and upload the firmware:
python3 skill/pet2dial/scripts/pet2dial.py build
python3 skill/pet2dial/scripts/pet2dial.py upload
Run the BLE bridge:
python3 skill/pet2dial/scripts/pet2dial.py run-bridge
Validation
The current prototype validates the full success path: Codex pet detection, atlas conversion, PlatformIO firmware build, BLE bridge snapshot generation, M5Stack Dial upload, pet display, rotary task browsing, and tap-to-open conversation navigation.
Observed firmware usage from the working prototype:
RAM: 15.4%
Flash: 78.9%
Why M5Stack Dial
The Dial is a strong fit because the round display, touch input, rotary encoder, BLE, and ESP32-S3 are all part of the core experience. This project uses the Dial as the controller, display, input device, and BLE endpoint.
GitHub
https://github.com/zzliu-coder/pet2dial
中文摘要
Pet2Dial 把 Codex 桌面里的宠物搬到 M5Stack Dial 上。它读取 Codex 当前选择的 custom pet,把官方宠物 atlas 转成 Dial 固件资源,并通过蓝牙同步 Codex 的 waiting、failed、review、running 任务状态和计数。旋转 Dial 可以浏览任务卡片,点击卡片会打开对应的 Codex 会话。它既是桌面宠物,也是一个用于 Codex 任务切换和会话跳转的小型实体遥控器。






Comments