Explore a thin-fork path: stock Codex engine with Lab features moved to plugin, MCP bridge, and a minimal patch series

[cbusillo]

Objective

Decide whether Codex Lab should stop being a full fork of openai/codex and instead run a stock (or near-stock) Codex engine with its differentiating features moved to the extension layers upstream now supports. This issue records the 2026-09-16 research comparing four paths — continue the fork, return to Every Code, pivot to T3 Code, or a thin fork — and proposes bounded spikes. It authorizes no implementation, cutover, or release change.

Finish Line

An owner decision on the engine strategy, backed by two spike results (hook-based review dogfood; account-rotation outside the engine), with a successor plan that either supersedes the convergence/release milestones under #498/#230 or records why the full fork stays.

Current Status

State: exploratory, waiting for owner review. Research performed 2026-09-16 against origin/main f6fd999 (lab.7), openai/main 2d90e05, just-every/code v0.6.189, and pingdotgg/t3code v0.0.42. No code changed.

Motivation: the full-fork cost is structural

• 1,913 fork-only commits since 2026-06-07; 624 merged PRs; 12 Lab-only crates; 752 upstream files modified (~43k changed lines across 597 Rust files) plus ~101k lines in new files.
• 85% of all merged PR lines are upstream convergence. Five convergence PRs (Integrate current upstream Codex snapshot with Every Code contracts #465, Merge OpenAI Codex upstream through aea26afa #516, Converge Codex Lab with upstream snapshot #630, Draft: converge to openai/codex cbfd999d #782, Converge on upstream a62e98d1 while preserving Lab contracts #907) total ~1.42M of 1.71M merged lines. Each catch-up is 165k–390k lines and 4h–5 days wall clock; Converge on upstream a62e98d1 while preserving Lab contracts #907 was 42h, 827 commits, 3,138 files, and main was 272 upstream commits behind six days later.
• Upstream velocity: ~1,460 commits/month, 34 new crates in 90 days, accelerating.
• Both remedies failed: Automate low-token recurring upstream convergence #634 automation never produced a working refresh (every scheduled candidate stopped at ~213 conflicts); Prove native module maintenance cost across a pinned upstream upgrade #911 module extraction showed no measurable repair savings and closed do-not-expand.
• September 2026: 14 product PRs vs 32 CI/release PRs. The installed Lab home runs gpt-5.6-sol while the stock ~/.codex runs gpt-6-astra (Prove installed Astra compatibility on lab.8 #849 still open). The fork is behind on the thing it exists to deliver.
• Daily use is split roughly evenly: ~137 stock sessions and ~105 Lab sessions in the last 14 days. Stock already has the just-every marketplace and plugin-auto-review data present.

Existing Substrate (upstream openai/main, 2026-09-16)

Now upstream, so no longer fork-justifying:

• Hooks: Claude-compatible engine (codex-rs/hooks), events SessionStart/End, UserPromptSubmit, Pre/PostToolUse, PermissionRequest, Pre/PostCompact, Stop, SubagentStart/Stop, Interrupt. Stop can block and inject continuation fragments; async hooks (hook_config.rs async, 8 concurrent); loaded from hooks.json, [hooks] TOML, and plugin hook sources.
• Plugins (codex-rs/plugin, core-plugins): contribute skills, MCP servers, apps, hooks; local/git/npm marketplaces.
• Multi-agent: spawn_agent/wait_agent/send_input/resume_agent/close_agent/list_agents with roles (codex-rs/agent-roles).
• Local models: --oss, --local-provider lmstudio|ollama, models-manager.
• Remote: app-server --listen ws://, --remote-control, app-server-daemon (desktop/mobile), tcp-tunnel.
• Config: chatgpt_base_url is supported.

Still fork-only: multi-account and rate-limit-aware switching (upstream is single-account; client_tests.rs "rejects_account_switches"); per-role model provider or external-command agents (child_config.rs forces child provider = parent); background/auto code review (Guardian is approval review, not code review).

Options Considered

A. Continue the full fork

Rejected on the evidence above unless a concrete, measured reduction in owned upstream files is named first (per #778's own rule).

B. Return to Every Code (just-every/code)

Alive (daily releases, 100 commits/30d) and has every feature natively: switch_active_account_on_rate_limit, Auto Review in a worktree, patch-harness validation, claude/agy/copilot subagents, browser. But code-rs is a hard fork that does not take upstream crates: no hooks, no plugins, no multi-agent v2, no gpt-6-astra, models top out at claude-opus-4.8; effectively one maintainer; all 20 of our PRs (#489–#578) were closed unmerged. This is the trade #28 already rejected (desktop/iOS compatibility, upstream parity). Not the base; remains a rollback and idea source.

C. Pivot to T3 Code over stock Codex, Claude Code, and Antigravity

Confirmed strengths: MIT; thin client over codex app-server with per-instance Binary path (packages/contracts/src/settings.ts), shadow-home multi-account, pooled limits UI with reset credits, native rendering of Codex collab-agent events, mobile/remote (t3 serve, T3 Connect, LAN, Tailscale), providers added quickly via ACP.

Confirmed blockers for our feature set:

• Automatic account failover refused by maintainers (feature: Add "!cmd" user shell execution openai/codex#2471, Anthropic ToS concern; Performance: Browser becomes unresponsive with very large answers (>5,000 lines) openai/codex#5863 closed without comment). Manual switching triggers open bug Format Markdown tables so that they are readable by humans openai/codex#8259 "already has an active writer" (root cause known, unfixed).
• Cross-provider delegation (Crit openai/codex#5733) closed by an automated sweep; no design.
• Codex hooks may not run under T3 (Run codex at a safe environment openai/codex#5024: new hooks need TUI trust sign-off T3 never surfaces). Claude Stop-hook output display broken (Improve MCP startup error messaging openai/codex#5297).
• Codex subagent lifecycle partially broken (perf(tui): cap redraw scheduling to 60fps openai/codex#8499, load models from disk and set a ttl and etag openai/codex#7722; fix PR Support absolute paths and ~ expansion in @ file mentions/fuzzy search openai/codex#11996 opened 2026-09-16).
• Protocol bindings pinned to upstream 2026-07-19 (UPSTREAM_REF 678157a); Codex 0.150 broke resume (WSL vsock error prevents any command execution (UtilBindVsockAnyPort: socket failed 1) openai/codex#8322), fixed in ~10h; 0.151–0.154 shipped with no regen.
• Test auth::tests::enforce_login_restrictions_logs_out_for_workspace_mismatch failing openai/codex#5447: helper ran with --dangerously-skip-permissions and executed user prompts (53 rogue runs on one machine); mitigation PR core: add Session::history_snapshot and use in compact task to avoid … openai/codex#4169 merged 2026-09-07, issue open; Codex title generation still agentic in cwd. Default permission mode is Full access; telemetry on by default.
• Perf Restore direct-store login account flows #695 open since March (maintainer cannot reproduce on 0.0.40/Codex 0.153.3; related ingestion-lag issues Add working directory to resume search openai/codex#5110, feat: phase 2 consolidation openai/codex#11306, brew upgrade codex not working openai/codex#5681 open). Data-loss reports Aug–Sep: New worktrees set to a new branch do not checkout the branch itself, just the commit openai/codex#11084, Add lighthearted joke to README openai/codex#8773, Fix toasts on Windows under WSL 2 openai/codex#7137.
• "Mostly not accepting contributions"; many closures are automated sweeps.

Verdict: right architecture, not ready, and it structurally refuses two of our four features. Treat as an optional client to evaluate, not a dependency. Re-evaluate when openai#5024, openai#8259, openai#8499/openai#11996 are closed and the pin passes Codex 0.154.

D. Thin fork (proposed): stock engine, features in supported layers

Feature	Current footprint (vs merge-base a62e98d)	Proposed home	Loss
Background Review	15 files, +11.3k (with validation)	Lab plugin: async/blocking Stop hook runs a reviewer via codex exec/review/start; findings return as hook feedback; persistence in plugin data. just-every/plugin-auto-review is this shape and is already installed in ~/.codex.	TUI/desktop status cells; review/* app-server methods (#231, #787, #784)
Automatic Validation	(above)	PostToolUse/Stop hooks (shellcheck, cargo check) in the same plugin; also works in Claude Code	validation/completed event (#785)
Claude / Antigravity subagents	39 files, +12.9k	agent-bridge MCP server (spawn/wait/send/cancel over claude -p, agy, codex exec), ported from core/src/agent/external_command.rs and external-agent-sessions. Native spawn_agent cannot host this (provider forced = parent); MCP is the supported seam and works from Codex, Claude Code, and T3	Tool-call granularity instead of native agent items; cancel/usage plumbing must be reimplemented (#85, #577, #906, #910)
Multi-account auto-switch	47 files, +15.8k (login, secrets, core, TUI)	Spike a local auth proxy on chatgpt_base_url that rotates tokens on 429 (CLIProxyAPI-style). Fallback: rebased patch series carrying only auth_accounts.rs, account_switching.rs, and the manager.rs/server.rs hunks	Proxy: TUI account views. Patch: ~5k lines to rebase per release instead of ~300k
Daemon behind ChatGPT desktop/iOS (#385)	supervisor + Lab engine	Same supervisor over stock codex app-server + app-server-daemon	None
owner-control-, browser crate, code-bridge-, core-skills, TUI extras, version	~60k lines	Drop, or keep as separate services (code-bridge already is one); upstream ships browser/computer-use plugins	TUI polish

What this retires: bi-weekly convergence merges, upstream-convergence.yml, the 14 Lab-only workflows, self-hosted release/signing runners, provenance/Bazel/V8 caching work (#853–#857, #875, #876), and most of milestones 3, 6, 7, 8. New cadence: install the upstream standalone package + codex plugin marketplace add, or rebase a ≤5k-line patch per release.

Risks

• Hook-based review may feel worse than in-engine review (latency, blocking-Stop UX in the desktop app). Needs a week of dogfood.
• The auth proxy must own per-account token refresh; unproven. Rotation across ChatGPT accounts is also a terms-of-service question for the owner.
• MCP-hosted subagents lose native cancel/usage integration; the bridge must reimplement what external_command.rs does today.
• Migration is real work (rough guess 4–8 weeks) during which lab.7 stays frozen; product issues Preserve applicable AGENTS instructions in Background Review context #787/Present post-turn review and validation as one coherent completion block #784/Enable automatic functional validation in installed Codex Lab defaults #785 pause.
• T3 and Every Code both depend on single vendors who do not accept feature contributions; the thin-fork path deliberately depends on neither.

Open Questions

• Does blocking Stop-hook feedback render acceptably in the ChatGPT desktop app and iOS client, or only in the TUI?
• Can the chatgpt_base_url proxy handle ChatGPT token refresh per account without engine changes? If not, is the login-crate patch really ≤5k lines after dropping the TUI views?
• Which of the ~60k lines of TUI/app-server/protocol changes does anyone actually use daily? (Session-level evidence, not issue count.)
• Should the orchestrator stay Codex, or does the MCP bridge make Claude Code an equal peer for some workflows?

Proposed Spikes (each separately authorized)

1. Zero-code dogfood (1 week): enable plugin-auto-review and a PostToolUse shellcheck hook on stock Codex 0.154 in ~/.codex; use alongside Lab. Optionally point a T3 Codex instance at the same binary for a side-by-side.
2. Auth-proxy spike (1–2 weeks): prototype rotation via chatgpt_base_url; decide proxy vs minimal patch.
3. Bridge spike: stand up agent-bridge MCP with spawn/wait/cancel for claude and agy from the existing external-command code; verify from Codex and Claude Code.

Related

• Launch Codex Lab and establish post-cutover roadmap #498 roadmap owner; Sync Codex Lab with current openai/codex substrate #230/Automate low-token recurring upstream convergence #634/Complete one pinned upstream catch-up and return to harness development #902 convergence; Extract Codex Lab runtime behind extension and native agent-provider boundaries #778/Isolate the first native-provider integration behind a Lab-owned module #909/Prove native module maintenance cost across a pinned upstream upgrade #911 extraction result; Detect code-present-but-unreachable regressions during upstream convergence #664 reachability gate.
• Rework durable Background Review around upstream review primitives #231, Make Background Review trustworthy for daily dogfood #570, Preserve applicable AGENTS instructions in Background Review context #787, Present post-turn review and validation as one coherent completion block #784, Enable automatic functional validation in installed Codex Lab defaults #785 Background Review and validation; Restore native external-agent routing with default roles and V2 plaintext tasks #906, Bound external workers through the existing execution path #910, Harden external-agent spawn graph and cancellation handling #85, Surface external-agent permission denials instead of empty successful results #577 external agents; Codex Lab multi-auth MVP #115, Surface per-account Codex reset credits and reset recommendation #383, Switch execution accounts only after terminal authentication failure #599, Add explicit opt-in quota-window priming for enrolled accounts #600, Restore login account removal #697, Restore login account switching #698 accounts; Prove persistent Codex Lab engine behind official Mac and iOS clients #385, Prove stable native remote control with separate execution auth #381, Auto-recover stale iOS remote task streams without daemon restart #388 remote/iOS; TUI shows ChatGPT login for local --oss providers in lab.7 #922–Explore local-model fallback when cloud rate limits are exhausted #925 local models.
• Codex fork overlay capability map #1, Provider-agnostic worker decision spike #2, Codex Lab MVP dogfood plan #28 original overlay/plugin-first intent; Classify Codex Lab feature ownership after upstream sync #232 ownership matrix.
• Every Code reference: ../code-prealign-new-skills/code-rs (account_switching.rs, review_store.rs, patch_harness.rs, agent_defaults.rs).
• T3 Code: pingdotgg/t3code issues Restore direct-store login account flows #695, feature: Add "!cmd" user shell execution openai/codex#2471, Run codex at a safe environment openai/codex#5024, Test auth::tests::enforce_login_restrictions_logs_out_for_workspace_mismatch failing openai/codex#5447, Crit openai/codex#5733, Format Markdown tables so that they are readable by humans openai/codex#8259, WSL vsock error prevents any command execution (UtilBindVsockAnyPort: socket failed 1) openai/codex#8322, perf(tui): cap redraw scheduling to 60fps openai/codex#8499, Support absolute paths and ~ expansion in @ file mentions/fuzzy search openai/codex#11996; docs/user/providers-codex.md, permission-modes.md, telemetry.md.

[shiny-code-bot]

Superseded by the existing plans after owner agreement and independent Opus 5 / Gemini 3.1 Pro review.

Research and decisions are incorporated in:

• Launch Codex Lab and establish post-cutover roadmap #498: roadmap and the tooling -> measured convergence -> lab.8 installed finish line.
• Automate low-token recurring upstream convergence #634 / Sync Codex Lab with current openai/codex substrate #230: finite proof, honest timing/cost attribution, admission scope and later repeatability; implementation is split into Prepare complete inventory and resumable convergence execution #927 and Complete one timed pinned convergence after lab.7 #928.
• Extract Codex Lab runtime behind extension and native agent-provider boundaries #778: stock/extension, MCP bridge and auth-proxy alternatives with explicit unresolved feasibility.
• Rework durable Background Review around upstream review primitives #231 / Plugin lifecycle hooks for workspace preparation and quality providers #149: review and validation hook lifecycle questions.
• Prepare and publish exact-provenance Codex Lab lab.8 #929 / Prove installed Codex Lab release acceptance through lab.8 #843 and milestone 9: distinct publication and installed acceptance.

The original body is preserved as research. Closing as not planned/superseded does not claim the hook, auth-proxy or bridge spikes were executed, authorize migration, adopt the cost estimates, or waive native product contracts. #909/#911 and milestone 8 remain closed do-not-expand.

Current status (September 17): #927 and #928 are complete; qualified PR #934 landed at d83017f after 9h02m15s from the original unpaused start. #908 was already consolidated through merged PR #933. One recovery does not complete #634's ordinary-refresh/automation proof.

Next action is #929: finish the fresh complete nonpublishing rehearsal on fb8fbcf (the merged annotation repair #937), then verify the artifacts and obtain final release review before publication approval. Independent #787 is draft PR #936 with exact-head CI green; separate complete-workspace approval and installed dogfood remain pending. Broad thinning and the unexecuted spikes remain with their existing later owners. Current planning and reconciliation remain in #498.

[cbusillo]

Reopened 2026-09-19 at the owner's direction. This issue was closed as superseded without its spikes being run, and the plans it was folded into all continue the full fork, so the question it asked was never answered. It is reopened as that decision, not as a migration: nothing here authorizes cutover, and lab.8 (#929) proceeds independently.

Evidence added since it closed:

• A real spawn from installed lab.7 showed Antigravity Gemini receiving an encrypted task instead of text. The cause sits inside the native external-agent integration this issue sizes at 39 files: upstream's encrypted-argument mechanism was never designed for external recipients. Fixed in PR fix(core): deliver plaintext tasks to external agents #947 (Deliver plaintext tasks to external agents and accept code-prefixed agent names #943). An MCP tool argument is plain text, so that class of bug cannot occur in the bridge shape proposed here.
• Ratchet down the fork's edits inside upstream-owned files #946 independently re-proposed module extraction and was corrected against Prove native module maintenance cost across a pinned upstream upgrade #911's do-not-expand result.
• Host audit the same day: 65% of the last 125 merged PRs touched no non-test product Rust.

Order: spike 3 (agent bridge) first, because #947 gives a working reference and a concrete acceptance check (spawn each provider, expect PONG); spike 1 (zero-code dogfood on stock Codex) in parallel since it needs no code; spike 2 (auth proxy) last, as the one place the thin fork might fail. Time estimates in the original body should be ignored.

Paused until the spikes report: further convergence-automation investment beyond #634's existing finish line, release-verifier hardening, and the extraction step in #946.