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

The Codex plugin for Claude Code supports task resumption via the --resume-last and --resume flags, allowing developers to continue workflows from persistent thread IDs stored in job state files.

The openai/codex-plugin-cc repository extends Claude Code with intelligent task management capabilities. When working on long-running bug fixes or multi-step refactors, you can resume previous Codex tasks without losing context. This feature leverages persistent thread IDs and session-aware filtering to ensure seamless continuity across development sessions.

Understanding the Task Resumption Architecture

Command Parsing and Flag Handling

In plugins/codex/scripts/codex-companion.mjs (lines 62-84), the handleTask function processes CLI flags including --resume-last, --resume, and --fresh. The resumeLast helper at lines 77-78 normalizes these flags into a single boolean value that determines whether to search for existing task threads.

Thread Discovery and Session Filtering

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

Execution and State Persistence

When resuming, executeTaskRun (lines 61-87) passes the discovered resumeThreadId to runAppServerTurn, allowing Codex to continue the conversation from the saved state. The enqueueBackgroundTask function (lines 84-100) persists this thread ID in state.mjs for future retrieval.

How to Resume Previous Codex Tasks via CLI

Resume the Most Recent Task

To automatically continue the latest task for your current repository:

/codex:task --resume-last

This command triggers resolveLatestTrackedTaskThread to fetch the most recent completed task and passes the resumeThreadId to the Codex App-Server.

Resume a Specific Thread

For explicit continuation of a known workflow:

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

Replace thread-xyz with the actual thread ID obtained from /codex:status or /codex:result output.

Check for Available Resumable Tasks

Before attempting resumption, verify available candidates:

/codex:task-resume-candidate

The handleTaskResumeCandidate function (lines 28-40) returns JSON indicating whether a resumable task exists:

{
  "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"
  }
}

Retrieve Thread IDs from Status and Results

Inspect ongoing or completed jobs to extract resumable thread IDs:

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

Both commands surface the threadId required for manual resumption, displaying output such as:

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

Background Execution with Automatic Resume

Queue resumable tasks for asynchronous processing:

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

The plugin stores the resumeThreadId in the job queue, allowing you to check progress later via /codex:status.

Key Implementation Files

The resumption feature spans several modules in the plugins/codex/scripts/ directory:

• plugins/codex/scripts/codex-companion.mjs: Main entry point containing handleTask, resolveLatestTrackedTaskThread, and executeTaskRun implementations.
• 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 candidate tasks.
• plugins/codex/scripts/lib/tracked-jobs.mjs: Manages job logs and filters by SESSION_ID_ENV to prevent cross-session interference.
• plugins/codex/scripts/lib/codex.mjs: Wraps the Codex App-Server API with functions like runAppServerTurn.

Summary

• Persistent thread IDs: Every Codex task stores its threadId in state.mjs, enabling resumption across sessions.
• Session-aware filtering: The plugin uses SESSION_ID_ENV to prioritize tasks from the current Claude session while providing fallback to repository-wide tasks.
• Multiple resume methods: Use --resume-last for automatic discovery or --resume <thread-id> for explicit continuation.
• Background support: Resume flags work with --background for queued asynchronous execution.
• Discovery commands: /codex:task-resume-candidate and /codex:status provide visibility into available resumable tasks.

Frequently Asked Questions

How do I find the thread ID to resume a specific Codex task?

Run /codex:status <job-id> or /codex:result <job-id> to view the job details. The output includes the threadId (labeled as "Codex session ID") and the exact command needed to resume that specific thread in the standalone Codex CLI.

What happens if I use --resume-last with no previous tasks?

The resolveLatestTrackedTaskThread function first checks for tasks matching the current SESSION_ID_ENV. If none exist, it falls back to the most recent task thread in the entire repository. If no tasks are found, the command will fail gracefully with an appropriate error message.

Can I resume tasks across different Claude Code sessions?

Yes, but with safety guardrails. While the plugin prioritizes tasks from the current session via filterJobsForCurrentClaudeSession, it will fall back to repository-wide tasks if no session-specific jobs exist. This prevents accidental cross-session interference while allowing legitimate resumption.

Does the resume feature work with background tasks?

Yes. When using /codex:task --background --resume-last, the enqueueBackgroundTask function (lines 84-100) preserves the resumeThreadId in the job queue. You can monitor these resumable background jobs using /codex:status and retrieve results with /codex:result.

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