v0.2.0 Phone Bridge Walkthrough

v0.2.0 turns OCdex from a promising LAN bridge into a more dependable daily remote-control surface. The important change is not just a larger UI. It is that the bridge now treats a phone and a desktop browser as peers looking at the same bridge-managed Codex session.

Start With One URL

Run the bridge:

npm run phone

The printed /?token=... URL is the shared entrypoint. In v0.2.0, opening that same default URL from multiple browsers joins the same new bridge instead of creating one new bridge per device. That makes the default path match the intended workflow: start from the desktop, open the phone, keep working in one shared thread.

Attach To A Headless App-Server

The bridge can still start a local Codex app-server for simple use, but v0.2.0 also supports attaching to an existing endpoint:

CODEX_APP_SERVER_URL=ws://127.0.0.1:45213 npm run phone
CODEX_APP_SERVER_SOCK=/Users/admin/.codex/app-server-control/app-server-control.sock npm run phone

Use this when Codex Desktop Remote Connection and OCdex should point at the same headless app-server. The app-server itself stays local; only the token-protected bridge is reachable from the LAN.

Keep History Discoverable

OCdex now warms history after completed turns with thread/read and a scan-backed thread/list. The polling path also prefers thread/read for selected-thread updates, which avoids unnecessary thread resume side effects during background refresh.

The UI suppresses overlapping refreshes and repeated background errors, so a short app-server restart does not flood the chat log.

Use The Interface Like A Small Desktop

The browser surface now includes a left thread list, a central conversation, and a right artifact panel. The release also adds model selection, sandbox and approval controls, Markdown rendering, local image previews, image attachments, and simple/cyberpunk/botanical themes.

The run-state banner reports connection, execution, approval, history sync, completion, and error states. It avoids duplicate live-region updates, respects reduced-motion settings, and uses higher-contrast status colors.

Notifications Without Surprises

Startup notifications are opt-in through ntfy, Pushover, or Discord. If the bridge cannot detect a LAN IPv4 URL, v0.2.0 sends a readable notification body without provider-specific undefined link fields.

That keeps notification failures from hiding the actual bridge state in headless, VPN-restricted, or IPv6-only environments.

Validation Trail

The release was checked with Node syntax validation, the Node test suite, VitePress build, whitespace diff validation, local API smoke tests, and GitHub Actions. The review feedback on PR #2 was addressed before merge.