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

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:

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

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

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

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.

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