WatchPet

WatchPet is a standalone SwiftUI watchOS app that mirrors the Codex pet overlay on your wrist.

What is included

• A watch dashboard that polls a local bridge for the current Codex thread status.
• The Codex-style status bubble: status label, thread title, and current activity body.
• Sprite-sheet rendering for the built-in Codex pets with the same 8 x 9 frame layout.
• A fixed full-screen watch view with Digital Crown pet selection that stays synced to Codex.
• A tiny Node bridge that serves /state, /avatars, and pet sprite assets from Codex.

Running the bridge

For the watch simulator:

node bridge/codex-pet-bridge.js --serve

The app defaults to http://127.0.0.1:47873/state.

To let the watch follow the live Codex pet notification and change the live pet inside an already-running Codex window, quit Codex and relaunch it with Electron remote debugging enabled:

/Applications/Codex.app/Contents/MacOS/Codex --remote-debugging-port=9222

Then start the bridge normally. The bridge probes port 9222 by default, or you can set a different port with WATCHPET_CODEX_DEBUG_PORT=9223 or --codex-debug-port 9223. Without that Codex debug port, the bridge falls back to the latest local session JSONL, and pet changes are still written to Codex's persisted state, but Codex will not update its current window until it reloads.

For a real Apple Watch, bind the bridge to your Mac's network interface:

WATCHPET_HOST=0.0.0.0 node bridge/codex-pet-bridge.js --serve

Then long-press the watch dashboard, open the Bridge section, and set the URL to:

http://<your-mac-lan-ip>:47873/state

Codex mirroring

When the Codex debug port is available, the bridge reads the live Codex avatar overlay first, so the watch uses the same visible pet notification title and body that Codex is showing. If the overlay cannot be reached, it falls back to the active local thread and then the latest Codex session JSONL, preferring the current workspace. The activity maps into the same overlay-style states:

Check the /state response's source field when verifying exactness: codex-avatar-overlay means the watch is mirroring the live Codex pet overlay, while codex-active-session or codex-session means it is using the session fallback.

• Running / Thinking
• Needs input
• Ready
• Blocked
• Info

It also extracts built-in pet sprite sheets from the installed Codex app bundle, discovers custom pets from ~/.codex/pets/<pet-name>/pet.json, and accepts POST /select-pet?id=<pet-id> from the watch. That endpoint updates Codex's persisted selected-avatar-id and, when the Codex debug port is available, forwards the same live persisted-atom-update message that Codex's own pet picker sends. The watch does not keep a permanent local pet override, so pet changes made directly in Codex are picked up on the next bridge poll.

Codex does not currently expose the floating pet overlay as a stable public API, so this bridge mirrors the same local session source instead of subscribing to private in-memory UI state. If Codex later writes exact overlay state, the bridge will honor ~/.codex/watch-pet-state.json or WATCHPET_STATE_FILE.

Project

Open WatchPet.xcodeproj in Xcode and run the WatchPet scheme on a watchOS simulator or device.