# What Happens When You Resume a Codex Task with the `--resume` Flag

> Learn what happens when you resume a Codex task using the --resume flag. Discover how it continues conversations from their previous state without altering the visible prompt.

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

---

**When you invoke the `codex-companion` CLI with the `task` sub-command and the `--resume` flag, the runtime locates the most recent persisted thread for your repository, sends a request to the Codex `thread/resume` API endpoint, and continues the conversation from its previous state without injecting the flag into the visible prompt.**

The `openai/codex-plugin-cc` repository provides a companion CLI that orchestrates Codex tasks within Claude Code sessions. Understanding how the `--resume` flag operates is essential for developers who need to continue interrupted coding workflows without losing context or creating duplicate threads.

## How the `--resume` Flag Is Parsed

The flag detection logic resides in `plugins/codex/scripts/codex-companion.mjs` at lines **777–785**. When the CLI initializes, it parses boolean options and sets an internal `resumeLast` variable to `true` if either `--resume` or its alias `--resume-last` is present.

The implementation enforces strict exclusivity: `--resume` is **mutually exclusive** with `--fresh`. Attempting to use both flags simultaneously triggers a validation error before any task execution begins. This guardrail ensures that users cannot simultaneously request a fresh thread and a resumed thread, preventing ambiguous state.

## Constructing the Resume Command

Once the flag is validated, the runtime prepares the user-facing output. The helper function `formatCodexResumeCommand` in `plugins/codex/scripts/lib/render.mjs` (line **106**) constructs the command string using the pattern:

```javascript
`codex resume ${threadId}`

```

This formatted command is then injected into the CLI output at lines **141–143** and **392–418** of the same file. The final printed message appears as:

```

Resume in Codex: codex resume thr_1a2b3c

```

This line serves dual purposes: it informs the user that resumption occurred, and it provides a manual fallback command if they need to re-enter the thread later outside the companion CLI.

## Resuming the Thread via the Codex API

The actual resumption mechanism is implemented in `plugins/codex/scripts/lib/codex.mjs` within the `resumeThread` function at lines **750–751**. This function forwards the stored thread ID to the Codex service's `thread/resume` endpoint.

When the API call succeeds, the previous conversation state—including all prior messages and context—is restored. The new prompt supplied by the user is then appended to this existing thread rather than spawning a new one, maintaining continuity across sessions.

## Safety Guarantees and Session Isolation

The `--resume` flag provides two critical behavioral guarantees verified by the test suite:

- **No Prompt Leakage:** The flag itself never appears in the user-visible prompt or the underlying API request payload visible to the model. The test at `tests/runtime.test.mjs` lines **719–735** explicitly verifies that `task --resume` behaves like `--resume-last` without leaking the flag into the prompt text.

- **Session Isolation:** Resumed threads are bound to the specific Claude session that created them. The test at lines **573–610** confirms that attempts to resume a task from a different Claude session are rejected, preventing cross-contamination of conversation contexts between separate environments.

## Practical Usage Examples

To resume the latest task thread for the current repository, invoke:

```bash
node scripts/codex-companion.mjs task --resume "follow up on the previous changes"

```

Alternatively, you can use the explicit long-form flag:

```bash
node scripts/codex-companion.mjs task --resume-last "continue discussion"

```

Both commands produce output similar to:

```

...
Codex session ID: thr_1a2b3c
Resume in Codex: codex resume thr_1a2b3c

```

The `resumeCommand` shown can be reused manually with the standard `codex resume <thread-id>` syntax if you need to access the thread outside the companion workflow.

## Summary

- The `--resume` flag (alias `--resume-last`) triggers the resumption of the most recent Codex thread for the current repository.
- Flag parsing occurs in `codex-companion.mjs` (lines 777–785) and is mutually exclusive with `--fresh`.
- The `formatCodexResumeCommand` function in `render.mjs` generates the display text, while `resumeThread` in `codex.mjs` (lines 750–751) executes the actual API call to `thread/resume`.
- The flag is never exposed in the prompt text, and thread resumption is restricted to the originating Claude session to maintain security boundaries.

## Frequently Asked Questions

### What is the difference between `--resume` and `--resume-last`?

There is no functional difference. `--resume` is defined as an alias for `--resume-last` in the argument parser. Both flags trigger identical behavior: locating the most recent thread for the current repository and preparing it for continuation.

### Can I use `--resume` together with `--fresh`?

No. The CLI explicitly forbids combining these flags. Because `--fresh` requests a brand-new thread while `--resume` requests continuation of an existing one, the options are mutually exclusive and will raise a validation error if used simultaneously.

### Does the `--resume` flag appear in the prompt sent to Codex?

No. According to the test suite in `tests/runtime.test.mjs` (lines 719–735), the flag is handled purely as runtime metadata. It influences which thread ID is attached to the request but is never injected into the user prompt or visible conversation history sent to the model.

### Can I resume a task that was started in a different Claude session?

No. The runtime enforces session isolation. As verified by tests at lines 573–610 of `tests/runtime.test.mjs`, attempts to resume a thread created in a different Claude session will fail. This ensures that conversation context remains strictly bound to its original session environment.