--resume vs --fresh Flags for Rescue Tasks in the Codex Plugin

The --resume flag continues an existing Codex task thread while preserving context, whereas --fresh forces a brand-new thread, and when neither is provided the plugin prompts you to choose if a resumable thread exists.

The Codex plugin for Claude Code provides a rescue command that forwards complex coding tasks to a specialized sub-agent. Understanding the difference between --resume and --fresh flags for rescue tasks ensures you either continue ongoing investigations or start completely new coding sessions without unintended context carryover. These execution-mode flags control whether codex-companion.mjs reuses persisted task state or creates fresh threads.

How the Rescue Command Handles Thread State

According to the source code in plugins/codex/commands/rescue.md, the rescue command (/codex:rescue) acts as a thin forwarder that launches the codex:codex-rescue sub-agent via the Agent tool and returns its stdout verbatim. The command supports two optional flags that determine whether to attach to an existing "task thread" or instantiate a new one.

The --resume Flag: Continuing Existing Threads

When you append --resume to a rescue command, the sub-agent attaches your new request to the already-running Codex task thread. This preserves all previous context, intermediate results, and conversation history accumulated during prior rescue work.

In plugins/codex/commands/rescue.md (lines 45-48), the flag is explicitly kept in the forwarded request with the instruction to "Leave --resume … in the forwarded request". When the sub-agent builds the final task command, it includes --resume, which instructs codex-companion.mjs to locate and reuse the persisted task state.

Use this flag when you need the model to remember previous debugging steps, partial implementations, or architectural decisions made earlier in the session.

The --fresh Flag: Starting New Threads

The --fresh flag forces the creation of a completely new Codex thread, ignoring any previous rescue work and clearing all prior context.

Like --resume, this flag is preserved in the forwarded request (as documented in rescue.md lines 45-48). The sub-agent adds --fresh to the underlying task command, which causes codex-companion.mjs to abandon any existing persisted state and begin execution from scratch.

Use --fresh when you want to ensure no contamination from previous debugging sessions, when switching to entirely unrelated tasks, or when you suspect prior context is causing incorrect assumptions.

Default Behavior: Automatic Thread Detection

If you invoke /codex:rescue without either flag, the plugin checks for a resumable thread (task‑reschedule‑candidate).

As implemented in plugins/codex/commands/rescue.md (lines 23-38), when a resumable thread exists, the user receives a one-time prompt asking whether to Continue current Codex thread or Start a new Codex thread. The chosen option then automatically injects either --resume or --fresh before the sub-agent is invoked, ensuring consistent behavior without requiring explicit flag memorization.

Implementation Architecture

The actual thread handling logic resides in plugins/codex/scripts/codex-companion.mjs, which parses --resume, --fresh, and --resume-last to decide whether to instantiate a new task or reconnect to existing persisted state (see the flag documentation at lines 82-90).

Crucially, these flags are execution-mode flags—they influence the routing logic of the rescue sub-agent but are not passed to the downstream Codex model as part of the natural-language prompt. They exclusively control the lifecycle of the task thread managed by the companion script.

Practical Usage Examples

Here are the three primary patterns for invoking rescue tasks:

# Explicitly continue an existing rescue thread

codex:rescue --resume "Investigate why my CI build fails"

# Force a brand-new rescue thread

codex:rescue --fresh "Add unit tests for the new payment endpoint"

# Let the plugin decide (prompts if resumable thread exists)

codex:rescue "Refactor the data-access layer"

Programmatic usage via the Claude Code API follows the same pattern—simply include the flag in the arguments field of the rescue command.

Testing and Validation

The behavior of these flags is rigorously verified in the test suite. According to tests/commands.test.mjs (lines 105-127), unit tests verify correct flag forwarding using assertions like assert.match(rescue, /--resume\|--fresh/). Additional runtime tests in tests/runtime.test.mjs validate the underlying task command options (--resume-last, --resume) that the rescue command ultimately invokes.

Summary

• --resume attaches to existing threads via codex-companion.mjs, preserving all context and intermediate results from previous rescue work.
• --fresh forces new thread creation in codex-companion.mjs, ignoring any previous rescue state and starting execution from scratch.
• When neither flag is provided, the plugin checks for task‑reschedule‑candidate in rescue.md and prompts for user selection before proceeding.
• Both flags are handled in plugins/codex/commands/rescue.md but executed by plugins/codex/scripts/codex-companion.mjs.
• These are execution-mode flags that control sub-agent routing logic, not model prompts.

Frequently Asked Questions

What happens if I use both --resume and --fresh together?

The source code does not explicitly define this edge case, but based on the implementation in codex-companion.mjs, these flags represent mutually exclusive execution modes. You should use one or the other to avoid undefined behavior, as the script expects a single thread management directive.

Can I resume a task after restarting my IDE?

Yes. The --resume flag works with persisted task state managed by codex-companion.mjs. As long as the task state files exist in your environment and you invoke the rescue command with --resume, the Codex rescue sub-agent can reconnect to the previous thread regardless of IDE restarts or session interruptions.

Does --fresh delete previous task history?

No, --fresh does not delete persisted history; it simply creates a new thread and ignores previous state for the current session. Previous task threads may still remain accessible via --resume-last or other mechanisms in codex-companion.mjs, but the current rescue operation starts with a completely clean slate.

Why does the plugin prompt me sometimes but not others?

The interactive prompt only appears when you omit both flags and a resumable thread (task‑reschedule‑candidate) exists. If no previous rescue work is detected in the state managed by codex-companion.mjs, the command proceeds immediately with a fresh thread without prompting, effectively defaulting to --fresh behavior automatically.

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