How to Resume a Previously Interrupted Codex Task Using `--resume` or `--fresh`

Use --resume (or --resume-last) to continue your most recent Codex task thread, or --fresh to force a completely new conversation even if your prompt looks like a continuation.

The openai/codex-plugin-cc repository provides command-line flags that control whether a new task request continues an existing Codex conversation or starts from scratch. Understanding these resumption controls ensures you pick up exactly where you left off—or deliberately start clean when context pollution is a concern.

Flag Parsing and Mutual Exclusivity

The CLI implements task resumption in codex-companion.mjs at lines 66–78. When you invoke the task sub-command, the parser evaluates three related options:

• --resume — sets resumeLast to true (shorthand alias)
• --resume-last — identical behavior to --resume
• --fresh — sets fresh to true

These flags are mutually exclusive. The code explicitly rejects invocations that supply both:

# This will fail with: "Choose either --resume/--resume-last or --fresh"

node scripts/codex-companion.mjs task --resume --fresh "some prompt"

The validation logic ensures unambiguous intent—either you want to resume, or you want something fresh, never both.

How --resume Locates Your Previous Thread

When resumeLast is true, the executeTaskRun function calls resolveLatestTrackedTaskThread (lines 36–55 in codex-companion.mjs). This helper performs three operations:

1. Scans stored job records in the current Claude session
2. Filters out any running jobs (only completed tasks are resumable)
3. Returns the thread ID of the latest eligible task

The thread resolution depends on companion state files. The lib/state.mjs module handles persistence, while lib/job-control.mjs provides the underlying query functions for finding resumable jobs.

Passing the Thread ID to Codex

Once resolved, the thread ID flows through the execution pipeline at lines 61–73:

// Simplified flow from codex-companion.mjs
const resumeThreadId = resumeLast 
  ? await resolveLatestTrackedTaskThread() 
  : undefined;

await runAppServerTurn({ resumeThreadId, /* ...other params */ });

• With a resumeThreadId: Codex continues the previous conversation with full context
• Without one: A fresh thread is created automatically

When to Use --fresh

The --fresh flag exists for cases where automatic continuation would misfire. Consider using it when:

• Your prompt resembles a continuation ("Now fix the tests") but you want isolated analysis
• Previous context contains misleading or corrupted state
• You're running comparative experiments against the same codebase

With --fresh, resumeLast remains false, no thread resolution occurs, and runAppServerTurn receives undefined for resumeThreadId—guaranteeing a brand-new Codex thread.

Practical Usage Examples

# Resume the latest completed Codex task

node scripts/codex-companion.mjs task --resume "continue diagnosing the issue"

# Explicit long-form equivalent

node scripts/codex-companion.mjs task --resume-last "continue diagnosing the issue"

# Force a new task, bypassing automatic continuation

node scripts/codex-companion.mjs task --fresh "run a fresh analysis of the repo"

# Let the plugin decide (automatic continuation suggestion)

node scripts/codex-companion.mjs task "implement user authentication"

The README at lines 140–147 documents this behavior: omitting both flags allows the plugin to suggest continuation based on prompt analysis, though explicit flags override all heuristics.

Summary

• --resume and --resume-last are synonymous aliases that continue your most recent completed Codex task thread
• --fresh forces a new thread, preventing any automatic resumption logic
• Flags are mutually exclusive—the CLI rejects combined use
• Thread resolution scans job history via lib/state.mjs and lib/job-control.mjs
• Final execution passes the resolved thread ID to runAppServerTurn in codex-companion.mjs

Frequently Asked Questions

What happens if I use neither --resume nor --fresh?

The plugin analyzes your prompt and may suggest continuing a previous thread automatically. According to the codex-rescue.md agent documentation, this routing decision treats the flags as explicit overrides to default heuristics.

Can I resume a specific older task, not just the latest?

The current implementation only supports resuming the most recent completed task via resolveLatestTrackedTaskThread. There's no --resume-id flag for targeting arbitrary historical jobs—this would require manual thread ID injection.

Why does --fresh exist if I can just start a new prompt?

Automatic continuation detection may falsely match phrases like "now do X" or "also check Y" against existing threads. --fresh provides deterministic isolation when you need guaranteed clean state, especially important for debugging or benchmark scenarios.

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