Difference Between `--resume` and `--fresh` Flags in Codex: Routing Controls Explained

The --resume flag forces the Codex runtime to continue the most recent rescue thread by injecting --resume-last into the task command, while --fresh explicitly starts a brand-new task session that ignores any prior work.

The openai/codex-plugin-cc repository provides these routing controls to help developers manage how new tasks relate to previous Codex sessions. Understanding the difference between --resume and --fresh flags in Codex is essential for controlling whether your investigation builds upon existing rescue work or begins as an independent analysis.

How --resume and --fresh Work Under the Hood

Both flags operate as routing controls in the Codex CLI Runtime skill, determining how the plugin interprets your intent regarding prior repository state.

The --resume Flag

When you provide --resume, the plugin strips this flag from your input and automatically adds --resume-last to the underlying task invocation. This forces the runtime to continue the most recent rescue thread for the repository, regardless of whether your prompt wording seems ambiguous.

According to the implementation in plugins/codex/skills/codex-cli-runtime/SKILL.md (lines 31-34), this mode tells the system to "always use task --resume-last, even if the request text is ambiguous."

The --fresh Flag

Conversely, --fresh strips the flag from your task text but does not add --resume-last to the command. This ensures the runtime starts a brand-new task, creating a completely independent investigation that ignores any existing rescue threads.

The same source file specifies this behavior as "always use a fresh task run, even if the request sounds like a follow-up."

When to Use Each Flag

Choosing the correct flag depends on whether you want to build upon previous Codex work or start clean.

• Use --resume when you explicitly want to continue working, apply the top fix from a previous run, or build upon the last session's context. This maintains continuity with the existing rescue thread.
• Use --fresh when you need a new, independent investigation or fix, even if your natural language sounds like a follow-up question. This prevents the runtime from inheriting context from previous sessions.

If you omit both flags, the plugin will offer to continue the latest rescue thread based on its interpretation of your request, as documented in the repository's README.md (lines 40-48).

Implementation Details in the Source Code

The flag handling logic resides in the Codex CLI Runtime skill at plugins/codex/skills/codex-cli-runtime/SKILL.md. This file defines the transformation rules that convert user-facing commands into internal task invocations.

The user-facing documentation in README.md reinforces that these flags provide explicit control over the default behavior, while plugins/codex/commands/rescue.md documents how end-users access these options via the /codex:rescue command.

Code Examples

The following examples demonstrate how these flags transform into internal commands:

# Continue the most recent rescue thread (resume mode)

/codex:rescue --resume apply the top fix from the last run

# → Internally becomes: task --resume-last "apply the top fix from the last run"

# Start a brand-new task, ignoring any prior rescue work (fresh mode)

/codex:rescue --fresh investigate why the tests are flaky

# → Internally becomes: task "investigate why the tests are flaky"

Notice that --resume injects the --resume-last parameter into the underlying task command, while --fresh results in a clean task invocation without resume parameters.

Summary

• --resume strips the flag and adds --resume-last to continue the most recent rescue thread, ideal for building upon previous work.
• --fresh strips the flag and starts a new task without resume parameters, perfect for independent investigations.
• Both behaviors are defined in plugins/codex/skills/codex-cli-runtime/SKILL.md and exposed to users via the /codex:rescue command.
• Omitting both flags leaves the decision to the plugin's default interpretation logic.

Frequently Asked Questions

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

The source code in plugins/codex/skills/codex-cli-runtime/SKILL.md does not explicitly define this conflict scenario. According to the implementation logic, each flag serves an opposite purpose—one forces continuation while the other forces a fresh start. You should specify only one flag to ensure predictable behavior, as the plugin expects mutually exclusive routing directives.

Can I resume a specific rescue thread instead of just the last one?

The current implementation only supports --resume-last as the underlying mechanism when using --resume. The flag is designed to continue the most recent rescue thread specifically, not arbitrary historical threads. For targeted recovery of specific sessions, you would need to use the underlying task command directly with appropriate identifiers.

Why does the plugin strip these flags from the task text?

The flags are stripped because they are routing controls meant for the plugin's command parser, not for the underlying task execution. The plugin consumes these flags to determine the execution mode, then passes only the remaining task description to the runtime. This ensures the actual task content remains clean and focused on the work to be performed.

Where can I find the official documentation for these flags?

The authoritative documentation resides in three locations within the openai/codex-plugin-cc repository: the implementation details in plugins/codex/skills/codex-cli-runtime/SKILL.md (lines 31-34), user-facing descriptions in README.md (lines 40-48), and command syntax in plugins/codex/commands/rescue.md.

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