How to Use the `codex:codex-rescue` Subagent for Bug Investigation and Resolution

The codex:codex-rescue subagent forwards rescue requests from Claude to the Codex companion runtime via a lightweight Bash wrapper, enabling deep root-cause analysis and second-implementation workflows without blocking the main thread.

The codex:codex-rescue subagent serves as a deterministic bridge between Claude and the Codex runtime in the openai/codex-plugin-cc repository. Unlike skills that inspect files or reason directly, this subagent strictly packages user prompts and delegates all heavy lifting—repository analysis, code generation, and execution—to the Codex companion script. This design keeps the subagent minimal while unlocking powerful debugging capabilities.

What the codex-rescue Subagent Does

The subagent is defined in plugins/codex/agents/codex-rescue.md. It declares:

• Name: codex-rescue
• Default model: sonnet
• Available tools: Bash only

The subagent never inspects the repository, runs skills, or produces its own solution. Its sole responsibility is forwarding requests to plugins/codex/scripts/codex-companion.mjs.

How Forwarding Logic Works

Lines 22‑34 of the agent file implement the core forwarding behavior:

1. Strips routing flags from the original prompt: --background, --wait, --resume, --fresh, --effort, --model
2. Adds defaults: --write unless read-only mode is requested
3. Executes: node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task …
4. Returns: raw stdout from the companion script

This ensures the subagent remains stateless and predictable.

Invoking the Subagent: CLI Methods

The CLI interface lives in plugins/codex/commands/rescue.md. It supports both foreground and background execution modes.

Foreground Execution (Default)

Run the rescue task synchronously and wait for completion:

codex rescue "Fix the failing unit test in tests/state.test.mjs"

• No --background flag → subagent runs inline
• The Agent tool stays in scope; no forked subagents
• --write is added by default, allowing file modifications

Background Execution

For long-running diagnoses, run asynchronously:

codex rescue --background "Investigate why the render command hangs on large inputs"

• Immediately returns control to Claude
• Codex operates independently on the task
• Check status via companion state management in plugins/codex/scripts/lib/state.mjs

Controlling Model Selection and Effort

The subagent supports fine-grained control over Codex behavior without embedding these parameters in the task text.

Model Mapping

User Input	Resulting Flag
spark	--model gpt-5.3-codex-spark
Any explicit model name	Passed through unchanged
(default)	No --model flag set

codex rescue --model spark --effort high "Rewrite codex-companion.mjs for better error handling"

Effort Control

The --effort <value> parameter is passed directly to the runtime:

codex rescue --effort maximum "Perform exhaustive root-cause analysis on the memory leak"

• Available values: low, medium, high, maximum
• Does not pollute the forwarded prompt text

Session Continuation and Fresh Starts

Manage Codex session state with resume controls:

Continue previous session:

codex rescue --resume "Apply the remaining fixes from the last Codex run"

• Adds --resume-last to the companion task
• Codex reloads prior context from plugins/codex/scripts/lib/state.mjs

Force fresh session:

codex rescue --fresh "Start completely new analysis of the auth flow"

• Omits --resume-last even if previous state exists

Programmatic Invocation via Agent Tool

Bypass the CLI and invoke directly from Claude's tool use:

{
  "type": "Agent",
  "subagent_type": "codex:codex-rescue",
  "prompt": "Diagnose why the status command returns a timeout error"
}

The subagent forwards this prompt to the companion and returns raw results. This is the mechanism used by plugins/codex/commands/rescue.md internally.

Optional Supporting Skills

The subagent definition references two optional skills:

• codex-cli-runtime: Tightens prompts before forwarding (formatting only)
• gpt-5-4-prompting: Enhances prompt structure for better Codex results

Critical restriction: These skills may only refine the prompt. The subagent must not use them to read files, reason, or generate solutions.

Summary

• The codex:codex-rescue subagent acts as a minimal forwarding bridge—all intelligence resides in codex-companion.mjs
• Use codex rescue for CLI access, Agent tool for programmatic access
• Control execution mode with --background (async) vs default (sync)
• Manage sessions with --resume and --fresh
• Tune quality with --model and --effort without affecting prompt content
• The companion script in plugins/codex/scripts/codex-companion.mjs handles all repository operations, code generation, and file writes

Frequently Asked Questions

What is the difference between codex rescue and running Codex directly?

codex rescue invokes the codex:codex-rescue subagent, which is a thin wrapper that validates and forwards requests. Direct Codex execution would require manual environment setup and argument parsing. The subagent ensures consistent flag handling, session management, and integration with Claude's tool system.

Can the codex-rescue subagent modify files in my repository?

Indirectly, yes. The subagent adds --write by default when forwarding to the companion script, which grants Codex permission to modify files. Use read-only mode explicitly if you want analysis without changes. The subagent itself never touches files—only the Codex runtime does.

How do I check the status of a background rescue task?

The companion script manages job state in plugins/codex/scripts/lib/state.mjs. Use codex-companion.mjs directly with appropriate status commands, or invoke another rescue request with --resume to reconnect to the previous session context.

Why does the subagent strip certain flags from my prompt?

Routing flags like --background, --wait, --resume, --fresh, --effort, and --model are consumed by the subagent's forwarding logic (lines 22‑34 of codex-rescue.md). These control how the request is delivered, not what Codex should do. The subagent maps them to appropriate companion script arguments before sending the cleaned task description.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}