# What Data Is Transferred During a Session Handoff to Codex?

> Discover what data transfers during a session handoff to Codex. Learn how your complete Claude conversation history is imported into Codex for seamless continuity.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-07-18

---

**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:

```bash
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:

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

```

### Inspecting the Transferred Ledger

After transfer, verify the imported conversation state programmatically:

```javascript
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.