plaipin

Mirror your OpenAI Codex desktop sessions to a small ESP32 device on your local network.

The desktop app's agent activity - status, streaming output, pending approvals - is reflected on the device, and approval prompts can be answered from the device with the desktop UI updating in real time. Animated Codex Pets ride along.

Status

Pre-alpha. The daemon, shim, CLI, and ESP32-facing protocol path are complete and verified end-to-end against the bundled Codex.app.

The device UX implementation is not included in this npm package yet. Display rendering, pet sprites, approval buttons, and the SoftAP captive-portal onboarding flow are still in progress.

Requirements

• macOS with Codex.app installed at /Applications/Codex.app
• Node.js >=20
• npm, for global installation
• An ESP32 device/firmware that speaks the plaipin protocol, or plaipin demo for no-hardware testing

plaipin is distributed as a CLI-only npm package. Importing it as a JavaScript library is unsupported; internal compiled modules are intentionally not exported.

Install

The fastest path is setup, which installs the daemon, asks for consent to hook Codex.app, and runs a health check:

npm install -g plaipin
plaipin setup

setup prints a bootstrap pairing token for first-device or debug use. Save it somewhere private.

Codex.app hook

To mirror real Codex.app sessions, plaipin patches Codex.app/Contents/Info.plist to set LSEnvironment.CODEX_CLI_PATH, then ad-hoc re-signs the app bundle. plaipin setup asks before doing this. The change is reversible with plaipin uninstall.

After setup, quit and reopen Codex.app so macOS reads the new environment value:

osascript -e 'quit app "Codex"' && open -a Codex

Verify

plaipin doctor
plaipin tail

You can inject a synthetic Codex event sequence without ESP32 hardware:

plaipin demo

Common Commands

Command	What it does
plaipin setup	One-shot install, Codex.app hook, and doctor run.
plaipin install	Create ~/.plaipin/, install the shim, write and start the LaunchAgent.
plaipin hook-codex --enable	Patch Codex.app so real sessions are mirrored.
plaipin hook-codex --disable	Remove only the Codex.app hook; daemon state remains.
plaipin doctor	Check install, hook, daemon, and protocol state.
plaipin tail	Stream ESP32-facing daemon events in a terminal.
plaipin device add <name>	Pair a device over USB-CDC or wireless claim.
plaipin uninstall	Restore Codex.app, stop the daemon, and remove plaipin state.

Without the Codex.app hook, the daemon can still run but only sees its own headless app-server. If doctor reports Codex.app hook as missing, run plaipin hook-codex --enable or re-run plaipin setup.

Security Model

plaipin is designed for a trusted local network.

• Device connections use bearer tokens stored under ~/.plaipin/state/.
• Paired-device welcomes and revocation frames are MAC-signed with the device token.
• The initial bootstrap token is powerful enough to tail daemon events; treat it as a secret.
• The loopback control API is bound to 127.0.0.1.
• Uninstalling removes local state unless you pass --keep-state.

If a token is exposed, revoke or reset the device and pair again.

Uninstall / Rollback

Always use plaipin uninstall. Do not remove ~/.plaipin by hand while the hook is installed.

The hook makes Codex.app spawn ~/.plaipin/bin/codex-shim. If that file is missing while Info.plist still points at it, Codex.app can fail to launch with ENOENT.

plaipin uninstall

Flags:

• -y skips the confirmation prompt.
• --keep-state preserves ~/.plaipin/state/ pairings and ~/.plaipin/bin/ shim files for reinstall.

What uninstall does, in order:

1. Restores /Applications/Codex.app/Contents/Info.plist from ~/.plaipin/state/Info.plist.original when available.
2. Re-signs Codex.app ad-hoc so Gatekeeper still accepts it.
3. Unloads and removes ~/Library/LaunchAgents/com.plaipin.daemon.plist.
4. Removes ~/.plaipin unless --keep-state is set.

After uninstalling plaipin state, remove the global npm package if desired:

npm uninstall -g plaipin

Codex.app Signature

After hook-codex --enable, Codex.app is ad-hoc signed instead of signed by Apple's original TeamID. It should still launch and run, but spctl --assess may report it as unsigned by Developer ID.

To restore Apple's original signature, reinstall Codex.app from the official DMG or wait for an auto-update that replaces the app bundle.

Troubleshooting

Codex.app Does Not Launch

This usually means Codex.app still points at a missing plaipin shim.

# Option A: put the shim back, then uninstall safely
npm install -g plaipin
plaipin install --no-launchctl --no-hook-codex
plaipin uninstall

# Option B: manually remove the Info.plist key
/usr/libexec/PlistBuddy -c 'Delete :LSEnvironment:CODEX_CLI_PATH' \
  /Applications/Codex.app/Contents/Info.plist
codesign --force --deep --sign - /Applications/Codex.app

Doctor Says The Hook Is Missing

Run:

plaipin hook-codex --enable
osascript -e 'quit app "Codex"' && open -a Codex

App Management Permission Denied

macOS 13+ may block terminal apps from modifying /Applications/Codex.app.

Open System Settings, go to Privacy & Security -> App Management, add your terminal app, then quit and reopen that terminal before retrying plaipin hook-codex --enable.

Device Does Not Connect

Run:

plaipin doctor
plaipin device list
plaipin tail

If the pairing exists but the device stays offline, check WiFi credentials, local-network reachability, and whether multiple Macs on the LAN are advertising plaipin.

Architecture

Codex.app (Electron)
   |
   v  CODEX_CLI_PATH=...codex-shim app-server ...      (set by `plaipin hook-codex --enable`)
codex-shim (POSIX shell + small Node bridge)
   |
   v  WebSocket-over-unix-socket frames
unix:///~/.plaipin/run/app-server.sock  <------+
   |                                           |
   v                                           |
codex app-server                               |
   ^                                           |
   | owned & spawned by -----------------------+
   |
plaipind (Node/TS)
   |
   v  WebSocket + bearer
ESP32 device

Layout

src/
  cli/             plaipin CLI (commander)
  daemon/          plaipind long-running daemon
  shared/          protocol types and shared helpers
shim/              codex-shim.sh + codex-shim-bridge.js
scripts/           architectural spikes and dev tooling

Current Limitations

• Startup hydration currently resumes each known thread with a full snapshot. This is robust but slower than an excludeTurns: true hydration pass would be on large histories.
• The daemon's snapshot-to-live event model can emit a tentative item completion followed by a live refinement for the same item id.
• Pet review state is timer-bounded rather than focus-bounded, because Codex.app focus/navigation events are not visible over the app-server protocol.
• Daily persisted stats and cost calculation are planned but not implemented.
• Consumer-grade SoftAP provisioning is planned; today pairing is USB-CDC or wireless claim, depending on firmware support.

Build & Develop

npm install
npm run build
npm run typecheck
npm test

For source-checkout testing, run the built CLI directly:

node dist/cli/index.js --help
node dist/cli/index.js doctor

To test the global command locally:

npm link
plaipin --help

To smoke-test the npm artifact shape:

npm pack
npm install -g ./plaipin-*.tgz
plaipin --help

Do not commit packed .tgz artifacts.

For an isolated no-hardware demo from a checkout:

PLAIPIN_HOME=/tmp/plaipin-demo \
PLAIPIN_LAUNCHAGENTS_DIR=/tmp/plaipin-demo/LaunchAgents \
  node dist/cli/index.js install --no-hook-codex --no-launchctl

PLAIPIN_HOME=/tmp/plaipin-demo node dist/daemon/index.js
PLAIPIN_HOME=/tmp/plaipin-demo PLAIPIN_TOKEN=<from above> \
  npx tsx scripts/dev/fake-esp32.ts

License

Licensed under the Apache License, Version 2.0. See LICENSE.