# How to Resume a Previous Codex Task Using the Plugin

> Effortlessly resume your previous Codex task with the companion script. Learn to use the `--resume-last` flag to automatically restore your session via the thread/resume API endpoint.

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

---

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

```bash

# 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

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