# How the OpenAI Codex Plugin Handles Thread Resumption and Task Continuity

> Discover how the OpenAI Codex plugin ensures thread resumption and task continuity by persisting session identifiers and using a resume flag for seamless job reloading.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals
- Published: 2026-07-29

---

**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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/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:

```bash

# 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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/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.