Codex Session Transfer Limitations: 5 Critical Constraints of the /codex:transfer Command

The /codex:transfer command only works with Claude JSONL transcripts stored in ~/.claude/projects, requires a recent Codex CLI with session import support, and creates immutable single-session threads that cannot be merged or edited after import.

The session transfer feature in the openai/codex-plugin-cc repository bridges Claude Code and the Codex CLI by converting conversation transcripts into resumable Codex sessions. While this enables seamless handoffs between the two environments, the implementation imposes strict architectural boundaries that affect file locations, version compatibility, and data fidelity.

Source File Location Restrictions

The transfer command strictly requires transcripts to reside under ~/.claude/projects. According to the plugin architecture, the SessionStart hook automatically supplies the current transcript path, and the manual --source flag only accepts files inside that directory.

This restriction exists in plugins/codex/commands/transfer.md, which defines the slash command interface. The limitation prevents arbitrary filesystem access and ensures the transcript is in the JSONL format that the Codex session importer expects. Attempting to point --source at files outside this directory will cause the command to fail.

Codex CLI Version Dependencies

The session transfer relies on the external-agent session importer API that was added in recent Codex releases. If the installed Codex CLI is older and lacks the import endpoint, the plugin cannot execute the transfer.

When running on outdated versions, the command defined in plugins/codex/commands/transfer.md will detect the missing API and prompt you to upgrade rather than attempting a fallback. This hard dependency means session transfer is unavailable on legacy Codex installations, regardless of the plugin version.

JSONL Conversion Rules and Data Loss

Only Claude JSONL transcripts that satisfy Codex’s import conversion rules are accepted. The implementation in plugins/codex/scripts/lib/codex.mjs normalizes Claude turns into Codex "visible turns" during the import process.

Any Claude-specific constructs that lack Codex analogues—such as certain tool calls or internal metadata—are dropped or transformed. This can cause loss of fine-grained context, meaning the resulting thread may represent a simplified version of the original conversation rather than a byte-perfect replica.

Single-Session Continuity Constraints

Each invocation of /codex:transfer creates a new Codex thread reflecting the state of the current Claude session only. The importer does not merge with existing Codex threads or append to previously transferred sessions.

Consequently, you cannot incrementally update a Codex thread with new Claude messages without manually re-importing the entire transcript. This limitation is documented in the repository's README.md and affects workflows where users expect to maintain a single persistent thread across multiple transfer operations.

Immutable Turn Visibility

Once imported, turns become visible in the Codex UI/TUI but cannot be edited after the fact. The import process writes immutable entries to the Codex thread; modifying history would require a new import or a separate edit operation inside Codex itself.

This immutability is enforced by the session import logic in plugins/codex/scripts/lib/codex.mjs, which treats Claude transcripts as append-only historical records rather than living documents.

How to Use the Session Transfer Command

When constraints are satisfied, the workflow is straightforward:

# Transfer the current Claude session automatically

/codex:transfer

# Example output:

# codex resume 7b6f3e2c-a1d4-4f90-b2e1-9c5d7e0e8f12

# Manual override with explicit source file

/codex:transfer --source ~/.claude/projects/-Users-me-repo/2024-03-01-session.jsonl

# Resume the thread in Codex CLI

codex resume 7b6f3e2c-a1d4-4f90-b2e1-9c5d7e0e8f12

The --source parameter must point to a JSONL file within the ~/.claude/projects hierarchy, and the session ID returned matches the newly created Codex thread.

Summary

• File location locked: Transcripts must live under ~/.claude/projects due to security and format validation requirements in the plugin's command definition.
• Version dependency: Requires recent Codex CLI with the session import API; older versions trigger upgrade prompts.
• Data transformation: Claude-specific constructs may be dropped during JSONL conversion, potentially losing tool call details.
• No session merging: Each transfer creates an isolated thread; you cannot append to existing Codex sessions.
• Immutable history: Imported turns are write-once and cannot be edited within the Codex UI after import.

Frequently Asked Questions

Why can't I transfer sessions from outside ~/.claude/projects?

The plugin restricts source files to this directory to ensure format compliance and security. According to the README.md documentation, the SessionStart hook and --source validation both enforce this boundary to prevent arbitrary filesystem access and guarantee the JSONL structure matches the importer's expectations.

What happens if my Codex CLI is outdated?

The command will fail with a prompt to upgrade. The session transfer feature depends on the external-agent session importer API that only exists in recent Codex releases. Without this endpoint, plugins/codex/scripts/lib/codex.mjs cannot create the thread, and the plugin has no legacy fallback mechanism.

Can I edit transferred sessions after importing them?

No. Imported turns are immutable once written to the Codex thread. The import process creates visible but non-editable history entries. To modify the conversation, you must either perform edits within Codex after resuming or re-run the transfer with an updated transcript.

How do I resume a transferred session?

After running /codex:transfer, copy the generated codex resume <session-id> command and execute it in your terminal. The session ID corresponds to the newly created Codex thread stored in the CLI's session database. This works only if your Codex CLI version supports the session import API.

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