How to Resume a Previous Codex Task Using the Plugin

Use the --resume-last (or --resume) flag when running the companion script to automatically locate the most recent thread and generate a codex resume <threadId> command that restores the session via the thread/resume API endpoint.

The openai/codex-plugin-cc repository provides a Node.js companion CLI that orchestrates Codex sessions. When you need to resume a previous Codex task using the plugin, the tool handles thread discovery, payload construction, and API communication through a standardized five-step pipeline.

Overview of the Resume Workflow

The resume process flows from CLI argument parsing to backend API invocation. The companion script first identifies the latest persisted thread for the current repository, embeds resume metadata into the task request, and invokes the Codex thread/resume endpoint to restore conversation state.

Step-by-Step Resume Process

Locate the Latest Thread with --resume-last

When you provide the --resume-last flag, the companion delegates to the task-resume-candidate helper to find the most recent thread associated with the current repository and session. This lookup logic is validated in the test suite at [/tests/runtime.test.mjs#L482-L506].

Store the Thread ID

Once identified, the thread ID (e.g., thr_1) is stored in the resumeThreadId variable within the companion script's execution context. This assignment occurs in [/plugins/codex/scripts/codex-companion.mjs#L467-L482].

Build the Task Request with Resume Metadata

The buildTaskRequest function constructs the payload sent to Codex. It sets the resumeLast boolean flag and adds a resumeCommand field containing the literal CLI command string codex resume <threadId>. This embedding happens at [/plugins/codex/scripts/codex-companion.mjs#L604-L632].

Render the Resume Command for Users

Before displaying output, the formatCodexResumeCommand function in [/plugins/codex/scripts/lib/render.mjs#L102-L143] formats the resume instruction into a human-readable line:

Resume in Codex: codex resume thr_1

This gives users the exact command needed to return to the session later.

Invoke the Codex Resume API

Finally, the plugin calls resumeThread in [/plugins/codex/scripts/lib/codex.mjs#L750-L756], which POSTs to the thread/resume endpoint with the threadId and current working directory (cwd). This API call restores the conversation state on the Codex backend, allowing subsequent prompts to continue the previous task context.

Practical Code Examples

Resuming via CLI

# Resume the most recent task using the long flag

node scripts/codex-companion.mjs task --resume-last "continue implementation"

# Use the short flag alias

node scripts/codex-companion.mjs task --resume "refactor authentication"

The output will include a line similar to:

Resume in Codex: codex resume thr_1

Programmatic Resume

import { createCodexClient } from './lib/codex.mjs';

// Obtain threadId from prior task-resume-candidate lookup
const threadId = 'thr_1';
const client = createCodexClient();

// Directly invoke the resume endpoint
await client.request('thread/resume', {
  threadId,
  cwd: process.cwd()
});

Key Source Files and Functions

• /plugins/codex/scripts/codex-companion.mjs – Parses --resume-last, stores resumeThreadId, and builds the request payload with resumeCommand (lines 467-482 and 604-632).
• /plugins/codex/scripts/lib/render.mjs – Contains formatCodexResumeCommand for formatting the user-facing resume instruction (lines 102-143).
• /plugins/codex/scripts/lib/codex.mjs – Implements resumeThread which calls the Codex thread/resume API endpoint (lines 750-756).
• /tests/runtime.test.mjs – Validates the resume candidate selection logic (lines 482-506).

Summary

• Use --resume-last or --resume flags to trigger the automatic resume workflow.
• The plugin discovers the latest thread via the task-resume-candidate helper.
• The resumeCommand field embeds codex resume <threadId> into the request payload.
• The formatCodexResumeCommand function renders the executable resume command for users.
• The resumeThread function executes the API call to restore session state on the Codex backend.

Frequently Asked Questions

What flag do I use to resume the last Codex task?

Use --resume-last or its shorthand --resume when running the companion script. This triggers the thread lookup and automatically appends the resume command to the output.

How does the plugin determine which thread to resume?

The plugin queries the task-resume-candidate helper to find the most recent thread ID persisted for the current repository and session, then stores it in the resumeThreadId variable during command execution.

Can I resume a specific thread ID instead of the latest one?

The current implementation focuses on resuming the latest thread via --resume-last. To resume a specific thread, manually execute the codex resume <threadId> command shown in the plugin's output, or call the thread/resume endpoint directly with your desired ID.

Where is the actual resume API call implemented?

The HTTP POST to the Codex thread/resume endpoint is handled by the resumeThread function in lib/codex.mjs, which requires the threadId and cwd parameters to restore the correct session context.

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