Codex Passport

Codex session notifications and quota visualization on FoloToy AI Passport, with an Android companion.

从零开始：中文一步步入门 · 中文介绍 · Python / uvx guide · Downloads

Synthetic fixtures rendered on the physical device; no account or real conversation data.

What it does

• Computer → encrypted BLE → Passport, or computer → private LAN/WireGuard → Android → encrypted BLE → Passport.
• Meaningful completion, failure, interruption, approval and input notifications across local Codex sessions. Starts and housekeeping update silently; internal guardian/memory workers are excluded.
• Durable delivery queue, device acknowledgements, offline replay, and one active BLE sender with phone fallback.
• Remaining quota compared with remaining cycle time. Orange means faster consumption, green balanced, blue slower.
• Native 240×320 Passport dashboard and physical-button controls. Material 3 Expressive Android overview, notification and connection pages.

Phone notifications show bounded titles and summaries for up to four sessions. Passport has two pages: the original large quota dashboard and a compact quota view with the three most recently updated visible sessions. Progress cards show a title, current state and one short summary; there are no conversation controls. This version does not resume conversations, send replies or approve actions. Those stay in Codex. Hooks need existing sessions to restart after installation; incremental logs are a compatibility fallback, not a stable API or Codex Mobile push integration. Other computers need their own collectors.

Get started

The beginner guide covers tool installation, backup/app-only flashing, APK installation without ADB, relay configuration, pairing, a real notification test, startup, switching, troubleshooting and removal. It uses the verified macOS + Android + Passport setup. Linux host deployment needs platform adaptation; Windows host deployment has not been validated.

Download the ready-made Android APK and Passport firmware v0.2.0. Upgrade the Python relay, Android APK and Passport firmware together to 0.2.0 to enable device progress cards. Existing BLE bonds and relay settings are retained. The APK is debug-signed. Back up the device before flashing and write only the app at 0x10000 on the documented hardware layout, preserving its other partitions.

Python installation

Requires Python 3.10+ and a working, logged-in Codex CLI. Install uv, then try:

uvx --from 'codex-passport-sync==0.2.0' codex-passport --help

If your configured mirror has not synchronized this new package, add --index https://pypi.org/simple to the uvx or uv tool install command to prioritize official PyPI.

For persistent hooks, install a persistent tool environment instead:

uv tool install 'codex-passport-sync[ble]==0.2.0'
uv tool update-shell

Open a new terminal, then:

codex-passport install-hooks
export COMPUTER_LAN_IP="replace-with-this-computers-private-IP"
codex-passport serve --host "$COMPUTER_LAN_IP" --port 18765

Keep that terminal open. Configure Android's Connection page with http://YOUR_COMPUTER_IP:18765 and the contents of ~/.local/state/codex-passport/relay-token. Allow Bluetooth permissions and enter the current six-digit Passport code in the phone's system pairing dialog. Restart existing Codex sessions to load the hooks. The address is the relay API, not wireless ADB or a WireGuard endpoint.

Add --ble "Passport-XXXXXX" using your device's actual advertised name for computer BLE. First pairing requires the computer's OS dialog and Bluetooth permission. The [ble] extra is required for this route. Select the sender on Android's Connection page; a failed computer connection falls back to the phone and stays there until selected again. Do not install permanent hooks from a temporary uvx environment, whose cache can be removed.

PyPI package · Wheel downloads · All installation options and state paths

Daily controls and scope

The backlight sleeps after 60 seconds without alerts/buttons. Encrypted BLE frames now include up to three bounded session titles and summaries. Unsupported emoji/rare glyphs are omitted on the device; spaces, Latin and basic CJK characters use a bundled OFL font. An authenticated private relay and paired BLE protect access; bounded phone summaries can still contain private context. Keep the relay within your private network/VPN. Do not expose its HTTP port publicly. The computer must stay awake and run the collector.

Both BLE routes, route switching, replay and physical controls were validated. Updates do not change the selected page; progress updates stay silent unless an alert is due. Off-LAN WireGuard and battery endurance were not measured. See the validation record for the exact evidence and limitations.

Development and attribution

Build instructions · MIT license · Third-party notices

Application code is independently authored. Official FoloToy BSP, Material Components and other dependencies retain their own licenses. The reference application was studied, not copied. This is a community project, not an official OpenAI or FoloToy product.