How Claude Session Transfer to Codex Preserves Conversation Context

When transferring a Claude session to Codex, the plugin reads the original JSONL transcript, wraps it as a migration payload, and imports it via the Codex app-server to recreate the exact turn-by-turn history in a new thread.

The openai/codex-plugin-cc repository enables seamless migration of conversation history between AI assistants. When you initiate a Claude session transfer to Codex, the system preserves every turn of your dialogue by treating the Claude transcript as an external agent session that Codex can import and continue. This process ensures that no context is lost when switching from Claude to Codex, allowing you to resume work on the same codebase without restarting the conversation.

How the Transfer Mechanism Works

The context preservation relies on a five-step pipeline that validates, migrates, and records the session data. Each step is implemented in specific modules within the plugin's source code.

Locating the Claude Transcript

The process begins with resolveClaudeSessionPath in plugins/codex/scripts/lib/claude-session-transfer.mjs. This function locates the JSONL file specified via the --source CLI flag or the CODEX_COMPANION_TRANSCRIPT_PATH environment variable. It validates that the file uses the .jsonl extension and enforces a security constraint that the file must reside inside Claude’s ~/.claude/projects directory (lines 20-44).

Building the Migration Payload

Once located, the transcript is wrapped by externalAgentSessionMigration in plugins/codex/scripts/lib/codex.mjs. This function constructs a migration payload that tells the Codex app server to import a session consisting of that single JSONL file (lines 81-96). The payload marks the source as an external agent, enabling Codex to parse the Claude-specific message format.

Importing via the App-Server

The actual context transfer happens in importExternalAgentSession, which calls requestExternalAgentSessionImport to communicate with the Codex app-server. The server stores the transcript and creates a new thread containing the same series of turns that Claude produced (lines 58-71). This RPC communication ensures the heavy lifting of thread creation happens within the Codex runtime while the plugin acts as a coordinator.

Recording the Session Mapping

After a successful import, Codex writes an entry to ~/.codex/external_agent_session_imports.json. This ledger maps the source file’s canonical path and its SHA-256 content hash to the generated imported_thread_id. The helper importedThreadIdForSource reads this registry to retrieve the existing thread ID if the same transcript is imported again, preventing duplicate threads (lines 61-78).

Exposing the Thread to Users

Finally, executeTransfer in plugins/codex/scripts/codex-companion.mjs returns a payload containing the new thread ID and a ready-to-run resume command (codex resume <thread-id>). The rendered output confirms that the Claude conversation history is now visible in Codex (lines 25-33).

Implementation Details from the Source Code

The architecture relies on strict validation and cryptographic hashing to ensure integrity. The resolveClaudeSessionPath function performs filesystem checks to confirm the transcript exists and is readable before any network requests are made. When externalAgentSessionMigration builds the payload, it preserves the exact byte content of the JSONL file to ensure that Codex receives the unmodified conversation history.

The SHA-256 hashing mechanism in importedThreadIdForSource serves two purposes: it detects if the transcript has changed since the last import and acts

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