Codex v1 Subagents

Windows-only runtime patch for Codex desktop that opens subagents as interactive legacy full-task tabs instead of the non-interactive side panel. It also makes new tasks use the V1 subagent runtime without leaving a persistent Codex configuration change.

One-off run

From npm:

npx codex-v1-subagents

Or, from a downloaded/cloned copy of this repository:

& '.\launch.ps1'

The foreground launcher must remain running while Codex is open.

Install a shortcut

From npm:

npx codex-v1-subagents install

Or, from a downloaded/cloned copy:

& '.\scripts\install.ps1'

This copies the current launcher into %LOCALAPPDATA%\CodexV1Subagents and creates Codex - v1 Subagents on the Desktop and in the Start Menu. The shortcut runs that pinned local copy without contacting npm. The shortcut uses the project's distinct V1 subagents icon, leaving the official Codex shortcut visually unchanged.

Startup failures appear in a dialog and are written to %LOCALAPPDATA%\CodexV1Subagents\runtime-patch.log. The dialog includes the failure reason, whether config recovery is confirmed, and a next step. Brief config-access failures are retried automatically (up to seven attempts, with 2.55 seconds of backoff); permanent failures preserve recovery files rather than overwriting conflicting edits. Compatibility errors report the installed Codex version, the latest tested version, and the hook whose expected structure did not match.

Shortcuts installed before this detailed-dialog behavior need one reinstall (install, or install --auto-update to keep automatic updates) to refresh their local error-display wrapper. Automatic npm updates alone update the patch, not that installed wrapper.

The official Codex shortcut and installed package remain untouched.

Automatic package updates

To create a shortcut that resolves the newest npm release on every launch:

npx codex-v1-subagents install --auto-update

That shortcut runs:

npx --yes codex-v1-subagents@latest run

This mode requires npx and internet access when launching Codex. To keep the pinned local shortcut and update it only when requested, run:

npx codex-v1-subagents@latest update

Uninstall

npx codex-v1-subagents uninstall

You can always launch normal, unpatched Codex using its official shortcut.

How it works

The launcher uses Windows package activation to run Node with Codex's installed package identity, verifies that identity, and starts the unmodified Codex executable with Chromium's private CDP pipe. A user-only local pipe carries the original launcher environment and log output; it does not write environment secrets to disk. The activation helper is compiled in memory by PowerShell; no extra SDK is needed. It pauses new renderer targets, intercepts two exact JavaScript chunks at response time, validates their semantic structure, rewrites them in memory, and then lets Chromium evaluate them. Existing renderers are reloaded once through the same interceptor.

For the backend, the launcher copies Codex's current full model catalog to a unique launch directory under %LOCALAPPDATA%\CodexV1Subagents\runtime and changes only catalog entries whose multi_agent_version is v2 to v1.

During startup it transactionally adds or replaces these config.toml values:

model_catalog_json = "<generated V1 catalog>"

[features]
multi_agent = true
multi_agent_v2 = false

Once Codex is ready, the launcher removes only its changes and preserves unrelated settings that Codex updated during startup. The original config is checksummed and backed up beside it for crash recovery. The generated catalog is validated before use and deleted when Codex exits.

No debugging TCP port is opened and nothing under WindowsApps is modified. Quitting Codex discards the patch.

The catalog choice is persisted in task history. New tasks created under this launcher use V1; existing tasks that were already created as V2 remain V2.

Development

node --check runtime-patch.cjs
node --check catalog-override.cjs
node --check package-runtime.cjs
node --check bin/cli.cjs
node --test runtime-patch.test.cjs package-runtime.test.cjs catalog-retry.test.cjs
& '.\test\launch-errors.ps1'

Optional Windows package-activation test (requires Codex installed, but opens no Codex window): & '.\test\package-launch.ps1'.

Compatibility

• Current package-aware launcher and UI hooks verified with OpenAI.Codex 26.928.2636.0.
• UI hooks also verified on 26.825.6671.0, 26.901.4073.0, 26.901.5003.0, 26.901.6511.0, 26.903.8094.0, and 26.924.2738.0.

The launcher discovers hash-named renderer chunks and checks the exact UI structure it changes. Harmless package and chunk-hash updates therefore work automatically. If OpenAI changes or duplicates the relevant logic, the launcher fails closed instead of guessing.