Codex fork overlay capability map

[cbusillo]

Intent

Establish the durable planning surface for the fresh cbusillo/codex fork overlay. Codex CLI is the substrate; Every Code behavior should live in plugins, skills, workflows, services, or minimal host extensions only where investigation proves the need.

Finish Line

Produce an evidence-backed capability matrix and staged fork-overlay plan before implementation begins. The matrix should cover existing Codex support, existing plugin support, host-extension need, external-service option, retire/skip option, likely owner, evidence, provider coupling, upstream merge risk, and ~/.codex adaptation.

Current Status

Initial read-only capability discovery completed. No repo code or docs have been changed.

Key findings:

• Codex already has strong native substrate for plugins, local marketplaces, plugin skills, hooks, MCP, app connectors, app-server v2, review/start, thread goals, process exec, and multi-agent/subagent surfaces.
• just-every/plugin-auto-review is a small hook-driven plugin: UserPromptSubmit captures a baseline, Stop runs a bounded review, stores state under plugin data, and returns Stop feedback for findings. It uses gpt-5.5 directly today.
• just-every/plugin-ultracode is a substantial plugin/skill/workflow engine: subprocess-backed codex exec --json workers by default, optional app-server transport, journaled resume under $CODEX_HOME/ultracode/runs, dashboard, usage accounting from Codex events, cancellation, retries, and isolated worktree diff collection.
• codex-skills is mostly reusable as external/plugin skill content, but many helpers still prefer $CODE_HOME or ~/.code with $CODEX_HOME compatibility. It needs a ~/.codex-first adaptation pass, not a wholesale copy into this fork.
• Provider-worker design remains the hard decision. Codex model providers are Responses-API-shaped; native Claude/Gemini support is not just a model-list addition. agy exposes --model and models, but live agy models can hang on environment/network/credential setup, so model selection should be verified in the real runtime when needed.

Recommended next action:

Create a compact child issue for the provider-worker decision spike only, then keep the rest in this parent until the matrix shows which tracks truly need independent review. The first milestone should be a zero-binary overlay pilot plan using existing plugin, skill, hook, MCP, and app-server surfaces.

Planning helper note: initial gh-plan.py create, ensure-labels, and update-section attempts failed through the helper's automation auth path (HTTP 404 on labels, then HTTP 403 requiring repository admin rights). Local gh auth can read and write this fork, so this issue was created and updated with normal gh as the fallback. Label/Project setup can be revisited after the capability map starts.

Initial Investigation Tracks

• Map Codex plugin, hook, skill, app-server, review, MCP, and workflow surfaces.
• Inspect just-every/plugin-auto-review, just-every/plugin-ultracode, and just-every/plugins directly.
• Inspect cbusillo/codex-skills as the likely home for skills and lightweight workflow guidance.
• Treat /Users/cbusillo/Developer/code as archival evidence only, not a source tree to port from blindly.
• Spike provider-agnostic workers as the likely hard decision: native providers, OpenAI-compatible proxy, external CLIs, plugin-only runners, or minimal host substrate.

Guardrails

• Do not implement code until the matrix and staged plan exist.
• Do not create .github/github.json until real workflow names, runner/secrets policy, and release posture are known.
• Do not require the old Blob size policy check.
• Do not assume Auto Review, Ultracode, AGY/Gemini selection, or Codex Desktop behavior from summaries; inspect the actual surfaces.

[cbusillo]

Initial Capability Matrix

Read-only discovery on June 7, 2026. No repo files changed.

Capability	Existing Codex Support	Existing Plugin / External Support	Host Extension Needed?	Likely Owner	Evidence	Provider Coupling	Upstream Merge Risk	~/.codex Adaptation
Plugin marketplace and install	Strong v2 RPCs: marketplace/add, marketplace/upgrade, plugin/list, plugin/install, plugin/read, plugin/uninstall, sharing APIs	just-every/plugins is a public Codex marketplace repo	No for local marketplace pilot	Plugin / marketplace repo	codex-rs/app-server-protocol/src/protocol/common.rs, v2/plugin.rs, app-server/src/request_processors/plugins.rs	Remote curated/share paths may be OpenAI-backend-specific	Low for local marketplace, medium for remote/default changes	Use Codex plugin cache/state, avoid ~/.code
Plugin capability bundle	Plugins can aggregate skills, MCP servers, apps, and hook sources	Auto Review and Ultracode already use plugin manifests	No	Plugin repo	codex-rs/plugin/src/load_outcome.rs, .codex-plugin/plugin.json in Just Every plugins	Low	Low	Keep .codex-plugin and Codex marketplace conventions
Hooks / turn automation	Strong hook system: tool, permission, compact, session, user prompt, subagent, Stop; app-server hook notifications	Auto Review uses UserPromptSubmit and Stop	No for Auto Review-style automation	Plugin hooks	codex-rs/config/src/hook_config.rs, codex-rs/core/src/hook_runtime.rs, plugin-auto-review/hooks/hooks.json	Auto Review hardcodes review model today	Low, but hook trust is a security boundary	Store state under plugin data, not ~/.code
Auto Review	Native review exists; hooks can block/feedback at Stop	plugin-auto-review captures baseline, diffs final snapshot, runs schema review, returns Stop feedback	Maybe later for provider choice / review lifecycle UX	Plugin first, host only if lifecycle/provider gaps remain	plugin-auto-review/scripts/user-prompt-submit.js, scripts/stop.js, README	Current plugin uses gpt-5.5; native Claude/Gemini requires translation/proxy/host work	Low as plugin; medium-high if app-server/core review API changes	Already Codex plugin-shaped; verify plugin data paths
Ultracode / parallel workers	Native subagent/multi-agent and app-server thread surfaces exist	plugin-ultracode shells codex exec --json, optional app-server transport, journals resume, dashboard, worktree diffs	Maybe for clean first-class provider/lifecycle/event API	Plugin first; worker substrate spike owns hard parts	plugin-ultracode/README.md, docs/technical-reference.md, scripts/ultracode-engine.js, scripts/app-server-client.js	Codex-worker model selection is OpenAI/Codex-shaped today	Low as plugin; high if moved into core agent code	Uses $CODEX_HOME/ultracode/runs; good direction
Provider-agnostic workers	Model providers exist, but wire API is Responses-only	External CLIs like AGY can be used outside Codex; agy --model exists, agy models may hang	Probably the main spike; not yet proven	Decision spike, then plugin/proxy/host owner	codex-rs/model-provider-info/src/lib.rs; provider scout verified agy --model	High: native Anthropic/Gemini is protocol translation, not a name list	High if native Rust providers; lower with proxy/plugin CLI	Avoid new home layout; configure provider/proxy under ~/.codex
Skills and prompts	Codex supports system/plugin/user skills and app-server skills/list / extra roots	codex-skills has many reusable domain skills	No for most skills	codex-skills or plugin skill bundle	codex-rs/skills, core-skills, app-server-protocol v2/plugin.rs; skills scout	Low, except skills that call provider-specific docs/tools	Low	Rewrite path resolution to prefer $CODEX_HOME / ~/.codex
MCP / external tools	Strong MCP config/runtime/app-server status/tool/resource/OAuth surfaces	Code Bridge, LaunchPlane, GitHub, SEO, docs lookup can live as MCP/tools/services	No for most integrations	MCP package or external service	codex-rs/app-server-protocol/src/protocol/v2/mcp.rs, codex-rs/core/src/session/mcp.rs	Depends on integration	Low-medium	Keep secrets and private routing out of repo; use Codex config
Browser/app visibility	App connectors and app-server notifications exist; process exec exists	just-every/code-bridge exists as separate package	Unknown; inspect connector contracts before binary work	Plugin/MCP/app connector first	Native scout found LoadedPlugin.apps, app/list; Code Bridge evidence from handoff	Low	Medium if adding generic event bus	Prefer plugin/app connector state under Codex home
GitHub planning/CI/review workflows	Native Codex has upstream workflows and review APIs, not this fork policy	github, github-plan, repo-readiness, babysit-pr skills are reusable	No	Skills/external services	codex-skills/github*, issue #1 helper auth mismatch	Low	Low if external; medium if repo workflow policy changes	Planning helper automation token needs access to this fork
CI / workflow policy	Upstream workflows exist, including ci, rust-ci, bazel, releases, blob policy	No fork-specific policy yet	No code; policy decision later	Repo planning, later docs	.github/workflows/*	OpenAI release/signing workflows are coupled	Medium-high if fork modifies workflows	Do not create .github/github.json until decisions are real
LaunchPlane / Discord / issue sessions	Codex app-server/thread APIs may cover session control; not confirmed	LaunchPlane and Discord Blue likely external	Unknown; inspect after core matrix	External service unless app-server hook missing	Handoff plus skills	Depends on service	Low if external, high if core	Keep private ops config outside repo

Staged Overlay Plan

1. Zero-binary overlay plan: Define a first usable milestone using existing local marketplace, plugin skills, hooks, MCP, app-server client scripts, and GitHub planning skills. No Rust changes.
2. Provider-worker decision spike: Create a focused child issue to compare Responses-compatible proxy, external CLI workers, app-server thread orchestration, and minimal host worker substrate against lifecycle, cancellation, usage, sandbox/worktree, and UI visibility requirements.
3. Plugin evidence pass: Finish direct inspection of Auto Review and Ultracode behavior, especially provider assumptions, state paths, failure modes, and app-server transport limits.
4. Skills adaptation pass: Make codex-skills ~/.codex-first and split shared public skills from private .local overlays. Keep this outside the Codex binary.
5. Workflow policy later: Inspect actual fork workflows and required checks after the overlay plan is concrete; then create .github/github.json if it describes real repo settings.
6. Binary extension only after pressure: Consider host changes only for proven missing primitives, likely a provider-independent worker lifecycle/event API or generic plugin event/RPC channel.

[cbusillo]

Created child spike: #2 Provider-agnostic worker decision spike. This is the only track split out for now because it is the main architecture decision that could force host changes; other overlay tracks stay in this parent until evidence shows they need independent review.

[cbusillo]

New constraint: Codex Desktop binary replacement

A key overlay goal is to replace the Codex binary used by the Codex Desktop app, and to make that replacement survive updates of both the Desktop app and the forked CLI.

This adds a packaging/update/install track to the plan. The capability matrix should now include:

• where Codex Desktop discovers or launches the Codex binary
• whether Desktop supports an explicit binary path, channel, symlink, shim, wrapper, app-server path, or environment override
• which update mechanisms overwrite that path or cached binary
• how a forked binary can be installed atomically and rolled back
• whether the durable interface should be a binary shim, stable symlink, launch wrapper, or app-server endpoint
• how to validate compatibility after upstream Desktop and Codex CLI updates

Initial recommendation:

Create a focused child issue for this after provider-worker #2, unless Desktop discovery turns out to be a prerequisite for the zero-binary overlay pilot. The first pass should be read-only inspection of Codex Desktop launch/config behavior and current CLI install locations, not implementation.

[cbusillo]

Created child spike: #3 Codex Desktop binary replacement and re-signing strategy. This captures the product/distribution track: replacing the Codex binary inside the Desktop app bundle, re-signing safely, surviving Desktop/CLI updates, and deciding whether a patcher/installer is viable.

[shiny-code-bot]

Captured adjacent planning thread: #4 defines the Lab naming/channel decision.

Working posture for the parent capability map:

• Codex CLI Lab should be the forked CLI/channel marker.
• Codex Lab should mean a Desktop app installation that has been locally patched to use the Lab CLI.
• Treat Lab identity as additive channel/build metadata first, not a broad rename or bundle-ID change.
• Keep the first implementation proof focused on visible CLI identity and Desktop compatibility, then decide whether app name or bundle metadata should change.

Refs #4.