How to Use `--resume` and `--fresh` Flags in Codex Rescue Tasks

The --resume flag forces the Codex rescue sub-agent to continue the most recent persisted thread by injecting --resume-last into the underlying task command, while --fresh starts a new rescue thread by omitting that flag and stripping the token from the prompt.

The openai/codex-plugin-cc repository provides a Codex Rescue command for managing persistent debugging threads across sessions. When working with complex debugging workflows, you often need to either continue an existing investigation or start with a clean slate. The --resume and --fresh flags give you explicit control over thread continuity without triggering interactive prompts.

What --resume and --fresh Control

These flags determine how the rescue sub-agent handles the lifecycle of Codex threads when executing the codex:rescue command. By default, the system might prompt you to choose between continuing or starting fresh; these flags bypass that decision.

The --resume Flag

When you provide --resume, the sub-agent automatically continues the most recent persisted rescue thread for the current repository. According to the command definition in plugins/codex/commands/rescue.md, this flag signals "do not ask whether to continue—the user already chose." The sub-agent adds the internal --resume-last option to the underlying task command, ensuring your new prompt is treated as a follow-up to the previous context (e.g., "continue", "keep going", or "apply the top fix").

The --fresh Flag

The --fresh flag instructs the rescue sub-agent to start a brand-new rescue thread, even if a previous thread exists. As documented in plugins/codex/skills/codex-cli-runtime/SKILL.md, this flag causes the sub-agent to "strip that token from the task text and do not add --resume-last." This ensures Codex begins with no prior context, creating a clean investigation environment.

How Thread Continuity Works Under the Hood

The rescue command follows a specific execution flow to process these routing controls:

1. You invoke codex:rescue with either --resume or --fresh.
2. The rescue sub-agent forwards the request to the Codex companion script at plugins/codex/scripts/codex-companion.mjs.
3. Inside the companion script, the task command is constructed dynamically:
   • With --resume, the companion injects --resume-last so the new prompt is interpreted as a delta on the previous task.
   • With --fresh, no --resume-last flag is added, causing Codex to start a new thread.
4. The flags themselves are not sent as part of the natural-language task text; they are routing controls that the sub-agent strips before passing the prompt to Codex.

This design lets you explicitly dictate whether to pick up where you left off or begin a new investigation without being prompted each time.

Practical Examples

Continue the most recent rescue thread when you want to apply a fix from a previous analysis:

codex:rescue --resume "apply the top fix"

When --resume is used, the underlying command that actually executes looks like:

node plugins/codex/scripts/codex-companion.mjs task --resume-last "apply the top fix"

Start a brand-new rescue thread to investigate a build failure without previous context:

codex:rescue --fresh "investigate why the build fails on CI"

With --fresh, the command becomes:

node plugins/codex/scripts/codex-companion.mjs task "investigate why the build fails on CI"

Both commands respect additional flags such as --model, --effort, --background, or --wait that you may provide alongside --resume or --fresh.

Key Implementation Files

The behavior of these flags is defined across three critical files in the openai/codex-plugin-cc repository:

• plugins/codex/commands/rescue.md: Contains the core command definition and explains the routing logic for --resume and --fresh, explicitly stating that these flags prevent the "ask whether to continue" prompt.

• plugins/codex/skills/codex-cli-runtime/SKILL.md: Defines the CLI skill that maps user-facing flags to internal task command options, specifying how --resume "always use task --resume-last" and how --fresh strips the token.

• plugins/codex/scripts/codex-companion.mjs: The companion script that executes the task command and implements the --resume-last injection logic based on the sub-agent's instructions.

Summary

• --resume forces continuation of the most recent rescue thread by adding --resume-last to the underlying task command.
• --fresh starts a new rescue thread by omitting --resume-last and stripping the flag from the prompt text.
• Both flags bypass interactive prompts, routing directly to the Codex companion script at plugins/codex/scripts/codex-companion.mjs.
• The flags act as routing controls that are stripped from the natural language text before reaching Codex.

Frequently Asked Questions

What happens if I use both --resume and --fresh in the same command?

The rescue command definition in plugins/codex/commands/rescue.md treats these as mutually exclusive choices. You should use only one flag per invocation. If both are provided, the sub-agent's behavior is undefined, though typically the last flag processed would take precedence.

Does --resume work if there is no previous rescue thread?

If no persisted rescue thread exists for the current repository, the --resume flag will likely fail or create a new thread automatically, depending on how plugins/codex/scripts/codex-companion.mjs handles the --resume-last option when no prior state is found. The flag assumes a previous context exists.

Can I combine these flags with other Codex options?

Yes. Both --resume and --fresh are compatible with other flags like --model, --effort, --background, and --wait. The routing logic only affects the --resume-last injection; all other parameters pass through unchanged to the companion script.

Why are these flags stripped from the natural language prompt?

The flags are routing controls for the rescue sub-agent, not instructions for the Codex model itself. As implemented in plugins/codex/skills/codex-cli-runtime/SKILL.md, the sub-agent removes these tokens before constructing the final task command to prevent the model from interpreting "resume" or "fresh" as literal content in your debugging request.

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