How the OpenAI Codex Plugin Handles Thread Resumption and Task Continuity

The Codex plugin persists session identifiers in the repository’s .codex/ directory and uses the --resume flag to reload previous Codex jobs, enabling seamless task continuity between Claude Code and the standalone Codex CLI.

The openai/codex-plugin-cc repository provides a bridge between Claude Code and the standalone Codex CLI, solving the problem of long-running tasks that outlive a single IDE session. By implementing thread resumption and task continuity mechanisms, the plugin ensures that background jobs, rescue operations, and conversation histories remain accessible even after the original Claude Code session ends.

Creating Persistent Threads with /codex:transfer

When you need to move a conversation from Claude Code to the standalone Codex application, the plugin generates a persistent thread identifier that both environments can reference.

In plugins/codex/scripts/transfer.ts, the /codex:transfer command spawns a persistent Codex thread that records the current Claude Code session ID. The script then outputs a shell command of the form codex resume <session-id> that you can execute in your terminal. This command opens the exact same conversation state inside the Codex TUI or web interface, preserving all conversational context without duplication.

The session ID acts as a bridge between the ephemeral Claude Code window and the durable Codex backend, ensuring task continuity when switching interfaces.

Delegating and Persisting Tasks with /codex:rescue

For background operations and sub-agent workflows, the plugin implements a rescue mechanism that stores task metadata locally for later retrieval.

Handing Off to the Rescue Sub-Agent

The plugins/codex/agents/rescue.ts file implements the sub-agent that receives delegated work from Claude Code. When you invoke /codex:rescue, this agent captures the Codex session parameters—including the model, effort level, and task description—and serializes them to a JSON file within the repository’s .codex directory. This persistence layer ensures that task configuration survives even if the Claude Code process restarts.

Resuming from the Latest Session

The plugins/codex/scripts/rescue.ts wrapper handles the CLI interface for rescue operations. When you append the --resume flag to /codex:rescue, the script inspects .codex/rescue/latest.json to locate the most recent session file. It extracts the stored session ID and re-invokes the Codex CLI with that identifier, causing Codex to attach to the existing conversation thread rather than spawning a new one.

This mechanism guarantees that thread resumption works across days or system restarts, as long as the .codex directory remains intact.

Background Execution and Status Tracking

For tasks that run asynchronously, the plugin implements a protocol-based tracking system that maintains continuity through task IDs.

The plugins/codex/scripts/lib/app-server-protocol.d.ts file defines the App-Server protocol used to communicate with the Codex application server. When you run /codex:rescue --background, the plugin registers the job with the server, which returns a unique task ID. The plugin stores this identifier locally, enabling subsequent commands to reconnect with the running process.

Later invocations of /codex:status or /codex:result retrieve the stored task ID and query the Codex server for current progress or final output. If you need to abort a background job, /codex:cancel uses the same task ID to send a cancellation request to the server. Because the task ID persists in the local .codex state, you can check on or terminate background jobs long after the original Claude Code window has closed.

Practical Workflow for Thread Resumption

The following commands demonstrate the complete lifecycle of a resumable Codex task:

# Start a long-running rescue job in the background

/codex:rescue --background investigate flaky test

# Check execution progress using the stored task ID

/codex:status

# Retrieve the final result and session identifier

/codex:result

# Later—resume the exact same rescue thread

/codex:rescue --resume

# Transfer a Claude Code session to Codex for direct continuation

/codex:transfer

# → Output: codex resume <session-id>

Each command leverages the persistent storage in .codex/ to maintain task continuity across sessions.

Summary

• /codex:transfer in plugins/codex/scripts/transfer.ts creates persistent threads by printing codex resume <session-id> commands that bridge Claude Code and the Codex CLI.
• /codex:rescue with the --resume flag reads .codex/rescue/latest.json to reconnect to previous sessions instead of starting fresh.
• Background jobs use the App-Server protocol defined in app-server-protocol.d.ts to register task IDs, enabling status polling via /codex:status and /codex:result.
• The .codex/ directory serves as the local state store for session metadata, ensuring thread resumption survives IDE restarts.
• Task IDs and session IDs are the primary primitives that enable the plugin to maintain continuity across the Claude Code and Codex boundaries.

Frequently Asked Questions

Where does the Codex plugin store session information for resumed threads?

The plugin writes session metadata to JSON files within the repository’s .codex/ directory. Specifically, /codex:rescue operations store data in .codex/rescue/latest.json, while background task IDs are persisted locally to enable later status checks via /codex:status.

How do I transfer a Claude Code conversation to the standalone Codex CLI?

Run the /codex:transfer command. According to the implementation in plugins/codex/scripts/transfer.ts, this spawns a persistent Codex thread and prints a command in the format codex resume <session-id>. Executing this command in your terminal opens the exact conversation state in the Codex application.

Can I resume a Codex job that was started in the background?

Yes. The /codex:rescue --resume command looks up the most recent session file stored in .codex/rescue/latest.json and re-invokes Codex with the previous session ID. This works regardless of whether the original job was foreground or background, as long as the session file exists.

What happens if I cancel a running Codex task?

The /codex:cancel command retrieves the stored task ID from the local .codex state and sends a cancellation request to the Codex app-server via the protocol defined in app-server-protocol.d.ts. After cancellation, you can still resume the thread later using /codex:rescue --resume to pick up from the point of interruption.

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