Session Router for Codex

Local-only VS Code extension and Router Service for multiple user-authorized Codex accounts.

This is an independent third-party extension and is not affiliated with or endorsed by OpenAI.

MVP capabilities

• Add ChatGPT-backed Codex accounts using their email address or a memorable label, then complete the official browser authorization flow.
• Remove accounts from the Router while preserving their local Codex home as a safety measure.
• Keep each account in an isolated Codex home; SQLite stores references, never token values.
• Show the active account, remaining quota, usage windows, and reset time.
• Switch accounts manually from the status bar, command palette, or account panel.
• Optionally enable experimental automatic switching. When the active account is exhausted, the Router selects the available account with the most remaining quota and runs the same protected checkpoint, recovery, and isolated-window handoff used for manual switching.
• Refresh account quota locally without switching accounts automatically.
• Checkpoint the latest session before a switch.
• After the user explicitly selects an account, prefer native thread resume (Level 1) and fall back to continuation-context recovery (Level 2).
• Open the workspace in a new VS Code window whose CODEX_HOME is the selected account's isolated home, without copying auth.json between accounts.
• Automatically open the recovered local thread in the official Codex conversation editor. If the official extension changes its internal local-thread route, the recovery remains saved and can be retried with Codex Router: Open Recovered Session.

The Router Service binds only to 127.0.0.1:39200. Its state is stored in ~/.codex-session-router/database.sqlite.

Install

Install codex-session-router-1.5.4.vsix from VS Code with Extensions: Install from VSIX..., then reload the window. The status bar item Codex Router opens the account panel.

The extension declares the official openai.chatgpt extension as a required dependency because it uses that extension's bundled Codex runtime when a standalone Codex CLI is not on PATH.

To add an account, run Codex Router: Add Account, enter the account email address (or a memorable label), and complete the official ChatGPT browser authorization. This MVP supports managed ChatGPT browser sign-in only. It does not collect API keys.

Automatic switching is off by default. Enable it from the account panel. Account cards show switching, success, and failure states. The UI prefers the email returned by Codex over generic labels and truncates long addresses while keeping the complete value available as hover text.

Commands

• Codex Router: Accounts
• Codex Router: Add Account
• Codex Router: Remove Account
• Codex Router: Switch Account
• Codex Router: Open Recovered Session
• Codex Router: Refresh Quota
• Codex Router: Start Service

Privacy and security

Account metadata, quota snapshots, and session checkpoints remain on the local machine. The Router binds only to 127.0.0.1, does not provide telemetry, and never copies or prints Codex token values. Codex itself manages credentials in each isolated Codex home.

Development

npm install
npm run check
npm run bootstrap
npm run router
npm run package:vsix

Sprint 0 probes remain available through npm run probe and npm run switch-probe.

Recovery boundary

Codex sessions are stored inside their account's Codex home. A thread therefore cannot normally be resumed under a different account. The Router creates a new, read-only recovery turn containing the task goal, latest state, and next action. It does not copy credentials or mutate Codex databases. The target workspace is then opened in a separate VS Code window so the official Codex extension starts with the matching isolated CODEX_HOME. The source window stays open to protect unsaved editor changes.

Isolated-window launching currently targets local VS Code sessions. Remote SSH and WSL extension hosts fail with an explicit message instead of silently opening a window with the wrong account.