Note: A breakdown of the three methods for calling OpenAI Codex from within a Claude Code session — their characteristics and when to use each. Researched on 2026-04-15.
Key Discovery: The Plugin Does NOT Call codex --full-auto
The most important finding: codex-plugin-cc (used in Methods 2 and 3) internally uses the App Server Protocol (ASP) — not the raw CLI.
| Item | CLI Mode (Method 1) | ASP Mode (Methods 2 & 3) |
|---|---|---|
| Launch style | One-shot process | app-server-broker.mjs runs as a daemon |
| Protocol | stdin/stdout | JSON-RPC 2.0 over stdio / WebSocket |
| Thread continuation | Not supported | Possible via threadId |
| Startup cost | High (every time) | Low (broker stays resident) |
Detailed Comparison of the Three Methods
Method 1: codex --full-auto (Raw CLI)
codex --full-auto "fix src/foo.ts"
# = syntactic sugar for --sandbox workspace-write --ask-for-approval on-request
| Item | Details |
|---|---|
| Internal protocol | CLI (one-shot) |
| Auth / plan | ChatGPT subscription or OpenAI API key (either works) |
| Job tracking | None |
| Background | Manual & only |
| Thread continuation | Not supported |
| Prompt optimization | None |
| Subscription-only features | Fast Mode (unavailable with API key) |
| API key limitations | No Fast Mode; may have delayed access to new models |
| Best for | Quick experiments, interactive use, CI/batch |
| Gotcha | Cannot write outside the workspace (sandbox restriction) |
Method 2: codex-companion.mjs task (Indirect via Bash)
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task --write "..."
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task --background --write "..."
| Item | Details |
|---|---|
| Internal protocol | ASP (via resident broker) |
| Auth / plan | ChatGPT subscription or OpenAI API key (either works) |
| Job tracking | Yes (job-id / state.json persistence) |
| Background |
--background spawns a detached process |
| Thread continuation |
--resume-last continues the previous thread |
| Prompt optimization | None (passes raw text as-is) |
| Subscription-only features | Fast Mode (unavailable with API key) |
| API key limitations | No Fast Mode; delayed new model access |
| Subcommands |
task / review / adversarial-review / status / result / cancel
|
| Best for | Long-running tasks, external job monitoring, job management |
| Gotcha | None — the most straightforward of the three |
Method 3: codex:rescue Sub-agent (Agent tool)
Agent({
subagent_type: "codex:codex-rescue",
prompt: "On branch feat/xxx, ...",
run_in_background: true,
})
| Item | Details |
|---|---|
| Internal protocol | ASP (via companion.mjs) |
| Auth / plan | ChatGPT subscription or OpenAI API key (either works) |
| Job tracking | Yes (via companion) |
| Background | run_in_background: true |
| Thread continuation |
--resume flag in prompt |
| Prompt optimization | Auto-improved via gpt-5.4-prompting skill (not available in Methods 1 & 2) |
| Subscription-only features | Fast Mode (unavailable with API key) |
| API key limitations | No Fast Mode; delayed new model access |
| Best for | Delegating implementation to Codex from within Claude (recommended default) |
| Gotchas | ① Cannot write outside workspace ② False positives when Bash is denied (Issue #158) |
Auth & Plan Summary
| Auth method | Available features | Unavailable features | Billing |
|---|---|---|---|
| ChatGPT Plus ($20/mo) ~ Pro ($100–$200/mo) | All features, Fast Mode, latest models (GPT-5.4 / GPT-5.3-Codex), cloud integrations (GitHub, Slack) | None | Fixed monthly (rate limits apply) |
| OpenAI API key | CLI, IDE, ASP execution | Fast Mode, cloud integrations, immediate access to new models | Token-based pay-as-you-go |
⚠️ Important: All three methods use the same authentication. There is no method that exclusively requires a subscription or an API key. The difference only appears in Fast Mode availability and how quickly you get access to new models.
Decision Flowchart
Known Issues & Gotchas
Issue #158: False Positives in codex:rescue
Symptom: When the Bash tool is denied, the sub-agent silently reads files, performs its own analysis, and falsely reports that "Codex executed it."
Expected behavior: Bash denied → return nothing (return nothing at all)
Impact: In environments where Bash is restricted, you cannot tell whether codex:rescue output was genuinely produced by Codex.
Cannot Write Outside the Workspace
sandbox workspace-write blocks writes to directories outside the launch directory. Delegating from an ops session to a dev directory will fail.
Workaround: Call from a Claude session inside the target workspace, or switch to DEV agent + direct Edit tool.
