Session Router for Codex

On the normal account-switch path, the Router reloads the current VS Code window exactly once and reopens the same Codex thread in place. This is a window reload, not a restart of the VS Code process or the whole application. The extension no longer creates an isolated VS Code window or copies a checkpoint into a replacement thread.

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.
• Enroll an existing ChatGPT login from the default ~/.codex home automatically on first launch, without asking the user to authorize that already logged-in account again.
• Remove accounts from the Router while preserving their local Codex home as a safety measure.
• Keep credentials in isolated Codex homes while sharing the native Codex session directories.
• Show this window's verified 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, current-window reload, and recovery flow used for manual switching.
• Refresh account quota locally without switching accounts automatically.
• Preserve every stored rollout file through the switch. Existing conversation tabs keep their original thread ids and can continue under the selected account by sending the next message.
• Give every account and workspace pair a separate native Codex SQLite history index. The shared rollout files remain intact, while the official history UI sees only conversations indexed for this exact project.
• Preserve only conversation tabs explicitly open in this window during a switch. Each tab must still be active (not archived) and its native cwd must exactly match the single workspace folder. The Router no longer scans or bulk-indexes a block of older project history during a handoff.
• Keep conversation history in the official Codex history UI. The Router account panel intentionally does not duplicate conversation titles or provide a second history list.
• Keep routing and recovery ownership isolated across Router-managed windows. A project may be open under one Codex account route at a time; attempting to open the same project or native thread under a different account is blocked until the other window releases its lease.
• Verify that the original thread is present in the account's shared native session store before committing a switch; never create a replacement thread or a competing background writer.
• Reload only the current VS Code window with the selected account's isolated CODEX_HOME, without copying auth.json between accounts or opening another VS Code instance.
• Restore every open Codex conversation editor from its complete native URI after the reload. If a tab cannot be restored immediately, the handoff and full tab snapshot remain available for retry with Codex Router: Open Recovered Session.
• Keep the official Codex sidebar user-controlled. A switch does not force the sidebar to reopen, and restored conversation editor tabs continue to work while the sidebar is closed. The Router closes only the sidebar location used by the audited Codex build; an unrelated Explorer sidebar is left alone.

The Router Service binds only to the fixed loopback endpoint 127.0.0.1:39200; workspaces cannot redirect it to a remote host. Every management request is authenticated with a random per-installation secret stored owner-only at ~/.codex-session-router/api-secret. Router state is stored in ~/.codex-session-router/database.sqlite. Account/project history indexes are stored as owner-only generations below ~/.codex-session-router/project-state/. Existing account SQLite databases are left untouched.

Install

Install codex-session-router-1.9.4.vsix from VS Code with Extensions: Install from VSIX..., then reload the window. The status bar item Codex Router opens the account panel. Version 1.9.4 requires VS Code 1.101 or newer because its local service uses the Node 22 runtime shipped with that release.

When upgrading from 1.9.1, reload every VS Code window that uses the Router before switching an account. The first 1.9.2-or-newer window replaces the shared v9 Router Service with protocol v10, so an older window's Router controls remain offline until that window also reloads. Existing Codex conversations and rollout files are not removed. Each older window also performs one controlled migration reload to select its clean project index; a generating turn may be interrupted and unsent draft text cannot be preserved.

The Router declares the official openai.chatgpt extension as a runtime dependency because it uses that extension's conversation editor and verified bundled Codex runtime. VS Code installs the dependency with the Router but leaves Codex installed when the Router is removed. A same-version CLI on PATH is only a fallback when that audited bundle is unavailable. Project-index isolation is currently verified against official Codex extension 26.5803.61601. The Router fails closed and keeps Codex views hidden when another official version is installed, until that version's state-only history behavior has been reviewed and added to the compatibility gate. Its native Router operations likewise require the bundled codex-cli 0.147.0-alpha.6.5; an unrelated CLI found on PATH cannot silently substitute a different SQLite or thread-list implementation. The official extension's development-only chatgpt.cliExecutable override and WSL runtime mode are blocked until their project-index behavior is separately verified.

On first launch, the Router detects an existing ChatGPT-backed Codex login in ~/.codex and adds that physical route locally without starting another OAuth flow. If an older isolated route uses the same login, both routes are grouped into one account card and the real default route is preferred.

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. Refresh reconciles every cached Router label with account/read from that entry's actual CODEX_HOME. Physical routes are grouped by a locally HMAC-blinded provider identity, so one login appears as one account card; historical duplicate Router entries can be removed from that card.

Commands

• Codex Router: Accounts
• Codex Router: Add Account
• Codex Router: Remove Account
• Codex Router: Switch Account
• Codex Router: Open Recovered Session
• Codex Router: Restore History Before Uninstall
• 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 or raw provider account IDs. Provider identity keys stored by the Router are HMAC-blinded with a random local secret. 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 credentials and rollout files both normally live below CODEX_HOME, but they do not need the same isolation boundary. The Router keeps each account's credentials separate and links every managed account to the canonical native Codex sessions, archived_sessions, and shell_snapshots directories. No rollout content is copied during a switch.

The Router saves the selected account and every explicitly open Codex conversation URI. It verifies each captured thread against the active sessions tree and the exact workspace cwd; an archived or cross-project tab aborts the switch instead of being imported. It then closes the Codex-owned editor tabs needed for the handoff and performs one reload of the same VS Code window on the normal path. It does not force the official Codex sidebar to reopen. Before activating the official extension, the Router applies both the account's CODEX_HOME and the account/project pair's clean CODEX_SQLITE_HOME, then restores the captured tabs from the unchanged rollout files. An in-progress turn can be interrupted by the reload, and unsent draft text cannot be preserved; after the tab returns, send 继续 (or any next instruction) to resume it under the selected account.

Upgrading from an older Router creates a new project index while all previous SQLite databases and rollout files remain in place. It does not delete, rewrite, or archive old conversations. Only verified open tabs are selectively indexed into the new view; old, archived, and other-project rows from a previously contaminated index are not copied forward.

The official VS Code extension does not expose a standalone command or App Server RPC for restarting only its Codex App Server. Its internal reconnect action reloads the VS Code window instead. The Router therefore treats the single current-window reload as the supported account-boundary change; it does not kill the extension-owned App Server process or try to manage it as an independent daemon.

Each managed window publishes a short-lived local lease for its selected project root and open native thread ids. Different projects can use different Codex accounts concurrently. The same project cannot be owned by two different account homes at once, because Codex does not provide a cross-home writer lock that would make that arrangement safe. Project discovery and the lease are exact-path based. Version 1.9.2 requires exactly one local workspace folder and fails closed for empty or multi-root windows rather than guessing which project owns the history index. Normal window shutdown releases the lease immediately; after a crash it expires automatically.

The switch/recovery transaction and the official Codex history view use the account/project SQLite index on the currently tested Codex extension. The Router panel shows accounts and routing state only; use the history control in the official Codex conversation UI to find restored conversations. This is a view boundary rather than access control: explicitly opening a valid conversation URI can index that conversation, and a future OpenAI extension that stops using state-only history queries must be revalidated before the same guarantee can be made. The runtime compatibility gate currently permits official Codex 26.5803.61601; unknown versions are blocked rather than silently falling back to the old global history index.

Uninstall

Before removing the extension, run Codex Router: Restore History Before Uninstall if you want to verify the migration explicitly. The extension also registers VS Code's uninstall hook and performs the same migration automatically: every conversation found in any completed Router project index is re-indexed in the normal ~/.codex SQLite history. Rollout files, Router project indexes, credentials, and account data are not deleted. After uninstalling, use Developer: Restart Extension Host (or reload the window) so the official Codex extension starts without the Router's per-project environment.

Before a handoff is committed, the target account's native App Server must successfully thread/read every captured thread from the target project index. Only resolved official Codex conversation editors count as restored; an unresolved placeholder tab is retained for retry and never reported as success.