How to Resume Previous Codex Tasks in Claude Code: Complete Guide

The Codex plugin for Claude Code allows you to resume previous tasks using the --resume-last or --resume flags with the /codex:task command, which automatically retrieves the persistent thread ID from job state files and continues the conversation through the Codex App-Server.

The openai/codex-plugin-cc repository implements robust task resumption capabilities that enable developers to continue interrupted or long-running Codex workflows without losing context. By persisting thread IDs in state.mjs and maintaining session-aware job tracking, the plugin ensures you can pick up exactly where you left off. This guide covers the CLI commands, underlying architecture, and practical examples for resuming previous Codex tasks.

Understanding the Resume Architecture

The resumption logic resides in plugins/codex/scripts/codex-companion.mjs and operates through a coordinated pipeline of flag parsing, job discovery, and thread restoration.

Task Command Handling and Resume Flags

The handleTask function (lines 62-84) parses CLI flags including --resume-last, --resume, and --fresh to determine whether to initiate a new task or continue an existing one. When --resume-last is detected, the resumeLast boolean is normalized (lines 77-78) and passed to the execution pipeline.

Locating the Latest Resumable Task

The resolveLatestTrackedTaskThread function (lines 36-55) implements the discovery logic for resumable tasks. It first searches for the most recent completed task job belonging to the current Claude session using session-aware filtering. If no session-specific job exists, it falls back to the most recent task thread in the repository via findLatestTaskThread.

Session-Aware Job Filtering

The plugin respects the SESSION_ID_ENV environment variable to prevent cross-session interference. The filterJobsForCurrentClaudeSession helper ensures that resume operations only consider jobs created within your active Claude session, maintaining isolation between different development contexts.

Thread Execution and Persistence

When resuming, executeTaskRun (lines 61-87) calls the Codex App-Server via runAppServerTurn, passing the resumeThreadId parameter to continue the conversation from the saved state. The enqueueBackgroundTask function (lines 84-100) persists this resume metadata, allowing background jobs to maintain continuity across checks via /codex:status.

Resuming Tasks via CLI Commands

The Codex plugin exposes several slash commands that expose the resume functionality to end users.

Automatically Resume the Most Recent Task

Use the --resume-last flag to automatically continue the latest task for your current session or repository:

/codex:task --resume-last

Behind the scenes, this invokes resolveLatestTrackedTaskThread to fetch the thread ID and passes it as resumeThreadId to the Codex App-Server.

Resume a Specific Task by Thread ID

For explicit control, use the --resume flag with a known thread ID:

/codex:task --resume thread-xyz "Add logging to the payment service"

You can obtain the thread ID from previous /codex:status or /codex:result output.

Check for Resumable Tasks Beforehand

The /codex:task-resume-candidate command (implemented in handleTaskResumeCandidate, lines 28-40) returns a JSON payload describing the most recent resumable task:

/codex:task-resume-candidate

Example output:

{
  "available": true,
  "sessionId": "abcd1234",
  "candidate": {
    "id": "task-20240501-xyz",
    "status": "completed",
    "title": "Codex Task",
    "summary": "Fix flaky test",
    "threadId": "thread-xyz",
    "completedAt": "2024-05-01T12:34:56Z"
  }
}

Inspect the available field to determine whether to proceed with --resume-last.

Retrieve Thread IDs from Status and Result Commands

When you need to resume a task in the standalone Codex CLI rather than through Claude Code, extract the thread ID using:

/codex:status task-20240501-xyz
/codex:result task-20240501-xyz

Both commands surface the threadId in their output, displaying lines such as:

Codex session ID: thread-xyz
Resume in Codex: codex resume thread-xyz

Copy the codex resume command to continue work directly in the Codex CLI.

Resume Background Tasks

For long-running operations, combine resume flags with background execution:

/codex:task --background --resume-last "Refactor authentication flow"

The plugin queues the job via enqueueBackgroundTask, preserving the resumeThreadId in the job state managed by plugins/codex/scripts/lib/state.mjs. Check progress later with /codex:status.

Key Implementation Files

The resume functionality spans several modules in the repository:

• plugins/codex/scripts/codex-companion.mjs: Entry point containing handleTask, resolveLatestTrackedTaskThread, and executeTaskRun.
• plugins/codex/scripts/lib/state.mjs: Persists job metadata including threadId to the filesystem.
• plugins/codex/scripts/lib/job-control.mjs: Provides findLatestResumableTaskJob for locating candidates.
• plugins/codex/scripts/lib/tracked-jobs.mjs: Manages job logs and session association via SESSION_ID_ENV.
• plugins/codex/scripts/lib/codex.mjs: Wraps the App-Server API (runAppServerTurn) to handle resume thread IDs.

Summary

• Use --resume-last to automatically continue the most recent task for your current Claude session, falling back to the repository's latest thread if needed.
• Use --resume <thread-id> for explicit resumption of specific tasks when you know the thread identifier.
• Check /codex:task-resume-candidate to programmatically verify resumable tasks exist before attempting resumption.
• Retrieve thread IDs via /codex:status or /codex:result to resume work in the standalone Codex CLI using codex resume <thread-id>.
• Background tasks support resumption through persistent storage in state.mjs and session-aware filtering in tracked-jobs.mjs.

Frequently Asked Questions

How does the Codex plugin know which task to resume when using --resume-last?

The plugin checks plugins/codex/scripts/lib/tracked-jobs.mjs to filter jobs by the current SESSION_ID_ENV, then calls resolveLatestTrackedTaskThread in codex-companion.mjs to locate the most recent completed task. If no session-specific job exists, it falls back to the latest task thread in the repository, ensuring you always resume relevant work.

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

By default, the session-aware filtering in filterJobsForCurrentClaudeSession prevents cross-session resumption to avoid context confusion. However, if no jobs exist for the current session, the resolver falls back to the most recent thread in the repository via findLatestTaskThread, allowing you to resume work from previous sessions if explicitly desired.

Where is the thread ID stored between sessions?

Thread IDs are persisted in plugins/codex/scripts/lib/state.mjs, which writes job metadata to the filesystem. The enqueueBackgroundTask function ensures that resumeThreadId is included in this persistent state, enabling the plugin to retrieve and reuse thread IDs even after Claude Code restarts.

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

The --resume flag requires an explicit thread ID argument (e.g., --resume thread-abc123) and is handled by the resume parameter logic in handleTask. The --resume-last flag is a boolean convenience option that triggers resolveLatestTrackedTaskThread to automatically discover and use the most recent resumable thread for your current session or repository.

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