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

> Learn how to use the codex codex-rescue subagent to investigate and resolve bugs. Analyze root causes without blocking the main thread.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-08-04

---

**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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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:

```bash
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:

```bash
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 |

```bash
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:

```bash
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:**

```bash
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:**

```bash
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:

```json
{
  "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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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.