What Data Is Transferred During a Session Handoff to Codex?

During a session handoff to Codex, the system transfers the entire Claude session transcript—a JSON‑Lines file containing the complete conversation history, including user prompts, assistant replies, tool outputs, and timestamps—which Codex then imports into its internal ledger format.

The openai/codex-plugin-cc repository enables seamless context migration between Claude and Codex through the /codex:transfer command. When you invoke this command, the plugin captures the full Claude conversation state and rehydrates it within Codex’s runtime environment, allowing you to continue development workflows without losing historical context.

The Claude Session Transcript Structure

The session handoff to Codex relies on a single JSON‑Lines (.jsonl) file that encodes the complete Claude conversation history. Each line in this file represents a discrete message object containing:

• Message content (user prompts and Claude responses)
• Role identifiers (user, assistant, or tool)
• Timestamp metadata marking when each interaction occurred
• Embedded tool results generated during the session

This chronological sequence preserves the exact state of your working session, ensuring Codex can reconstruct the conversation flow without ambiguity.

How the Session Handoff Works

Locating and Validating the Transcript

The handoff process begins by resolving the transcript file location through two possible mechanisms:

1. Environment Variable: If CODEX_COMPANION_TRANSCRIPT_PATH is set, the system uses this value as the default source.
2. CLI Argument: The --source <path> flag explicitly points to the transcript file.

The helper module plugins/codex/scripts/lib/claude-session-transfer.mjs performs rigorous validation through the resolveClaudeSessionPath function. This validation ensures the file:

• Ends with the .jsonl extension
• Resides within Claude’s authorized ~/.claude/projects directory
• Resolves to an absolute path before processing

Importing into the Codex Ledger

Once validated, the plugins/codex/scripts/lib/codex.mjs module orchestrates the actual data transfer:

1. The module emits a "transferring" progress event to indicate active migration.
2. It parses the JSON‑Lines file, converting each line into a structured message object.
3. It creates a Codex ledger entry that mirrors the Claude conversation sequence, preserving roles and metadata.
4. This ledger becomes the persistent starting state for subsequent Codex commands (/codex:run, /codex:review, etc.).

The resulting ledger maintains the same message sequence and role assignments (user, assistant, tool), enabling Codex to continue the conversation as if it had originated the session.

Error Handling and Security Constraints

The transfer mechanism includes strict boundaries to prevent data leakage:

• No auxiliary data: Only the JSONL transcript is transferred—no filesystem artifacts, secrets, or environment variables leave the local machine.
• Version compatibility: If the Codex installation lacks Claude session support, the system throws an error directing you to update (npm install -g @openai/codex@latest).
• Path restrictions: Transcripts outside the ~/.claude/projects directory trigger immediate exceptions, preventing arbitrary file reading.

Practical CLI Examples

Transfer via Environment Variable

Set the transcript path globally and invoke the transfer:

export CODEX_COMPANION_TRANSCRIPT_PATH=~/my-project/.claude/projects/session-123.jsonl
codex-companion.mjs transfer --json

Transfer via Explicit Source Path

Specify the transcript directly using the --source flag:

codex-companion.mjs transfer --source ~/.claude/projects/session-123.jsonl --json

Inspecting the Transferred Ledger

After transfer, verify the imported conversation state programmatically:

import { readLedger } from "@openai/codex";

const ledger = await readLedger("<generated-session-id>");
console.log(JSON.stringify(ledger, null, 2));

This invocation reads the newly created ledger entry, displaying the preserved message history in Codex’s internal format.

Summary

• Data scope: The session handoff to Codex transfers only the Claude transcript file (JSONL format), containing the complete conversation history with roles, timestamps, and tool outputs.
• Source files: Validation occurs in claude-session-transfer.mjs, while import logic resides in codex.mjs.
• Security model: Data transfer is restricted to authorized paths within ~/.claude/projects and excludes all non-conversation data.
• Entry point: The codex-companion.mjs CLI handles the transfer sub-command, supporting both environment variables and explicit file paths.

Frequently Asked Questions

What file format does the Claude session transcript use?

The transcript uses JSON‑Lines (.jsonl) format, where each line represents a separate JSON object encoding a single message from the conversation. This structure efficiently stores chronological message sequences while maintaining parseability for line-by-line streaming.

How does Codex validate the transcript file during a handoff?

The system validates the transcript through the resolveClaudeSessionPath function in claude-session-transfer.mjs. It verifies the file has a .jsonl extension, resolves it to an absolute path, and ensures it resides within the authorized ~/.claude/projects directory to prevent unauthorized file access.

What happens to the transferred conversation data in Codex?

Codex creates a ledger entry that replicates the transcript’s message sequence, preserving the original roles (user, assistant, tool) and metadata. This ledger becomes the active conversation state, allowing subsequent Codex commands to reference the full historical context as if Codex had generated the entire session itself.

Can I transfer a session if my Codex version is outdated?

No. The codex.mjs module checks for Claude session transfer capability during initialization. If your Codex version predates this feature, the system emits a clear error message instructing you to update to the latest version using npm install -g @openai/codex@latest before retrying the handoff.

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