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

> Learn how to resume interrupted Codex tasks with --resume or --fresh flags. Continue previous threads or start fresh conversations effortlessly to optimize your workflow.

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

---

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

```bash

# 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**:

```javascript
// 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

```bash

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