Claude Code to Codex Migration Guide 2026: Transfer History, Settings, and Workflow

Quick Answer

You can migrate from Claude Code to Codex by exporting your Claude Code conversation history as JSON via the /export command, transferring custom slash commands and MCP server configs manually, and pointing both tools at the same API gateway (like TeamoRouter) so you keep using the same API Key, billing, and model access. The migration is straightforward for configs and API settings but requires manual steps for conversation context. This guide covers the full process in 2026.

Why Migrate from Claude Code to Codex?

The AI coding tool landscape has shifted significantly in 2026. Codex (OpenAI's agentic coding CLI) has matured into a powerful alternative to Claude Code, with its own strengths in multi-file refactoring, sandboxed execution, and deep GitHub integration. Many developers who started with Claude Code are now evaluating whether Codex better fits their workflow, or using both tools side by side.

Common reasons for migrating include:

• OpenAI ecosystem integration: If your team already uses ChatGPT, GPT-4o, or OpenAI's API for other parts of your stack, Codex slots in natively.
• Sandboxed execution model: Codex runs code in isolated environments, reducing the risk of accidental filesystem changes.
• GitHub-native workflows: Codex has first-class support for PR reviews, issue triage, and repository-level operations.
• Cost considerations: Depending on your usage pattern, one tool may be more cost-effective than the other.

Whatever your reason, migrating does not mean abandoning Claude Code entirely. Many developers run both tools through a unified API gateway like TeamoRouter, switching between them depending on the task.

Prerequisites: Set Up a Unified Gateway First

Before migrating between tools, set up a unified LLM gateway. This is the single highest-leverage step: both Claude Code and Codex connect via standard API protocols (Anthropic and OpenAI-compatible, respectively), and a gateway that supports both means one API Key, one billing dashboard, and no per-tool credential management.

Recommended: Use the TeamoRouter Client to skip manual configuration. TeamoRouter natively supports both Anthropic-protocol (Claude Code) and /v1/responses (Codex), so both tools share the same Key and balance. This also means you do not need to install a local routing proxy, and there is no conflict with your VPN or system proxy.

Once your gateway is set up, migration proceeds in four steps: conversation history, slash commands, MCP servers, and API/credential config.

Step 1: Export and Import Conversation History

Exporting from Claude Code

Claude Code stores conversation history in a local SQLite database (typically at ~/.claude/history.db). As of 2026, you can export individual sessions:

# Export a specific session by ID
claude export --session <session-id> --format json --output session.json

# Export recent sessions (last 30 days)
claude export --recent 30 --format markdown --output claude-history/

The JSON export includes the full message tree: user prompts, assistant responses, tool calls, and tool results. The markdown export is cleaner for reference but loses the structured tool-call data.

Importing into Codex

Codex does not natively import Claude Code history files, but there are two practical approaches:

1. Reference-based workflow: Keep your exported Claude Code sessions as reference files in your project. When starting a new Codex session, point it at the exported file for context:

   text复制

   codex "Read claude-history/session-123.md and continue the refactoring work described there"
   

2. CC Switch bridge: If you use CC Switch to manage both tools, CC Switch can maintain a shared session index across providers. Configure both Claude Code and Codex in CC Switch, and the tool provides a unified session browser that works across both.

For teams migrating multiple developers, the community-maintained tool cc-migrate (on npm) automates batch export from Claude Code and reformats conversations into Codex-compatible context files.

Step 2: Transfer Custom Slash Commands

Claude Code slash commands are defined in .claude/commands/ within each project (or globally in ~/.claude/commands/). Codex uses a similar pattern with .codex/commands/.

Migration Script

The format is similar enough that a simple copy-and-rename works for most commands:

# Copy project-level commands
cp -r .claude/commands/ .codex/commands/

# Copy global commands
cp -r ~/.claude/commands/ ~/.codex/commands/

However, a few differences require attention:

• Claude Code uses %ARG% for argument placeholders; Codex uses $ARG.
• Claude Code's {{selection}} maps to Codex's {{selectedText}}.
• System-prompt overrides (Claude Code's --system-prompt flag) do not have a direct Codex equivalent; use Codex's custom instructions file instead.

Review each command after copying and update any incompatible syntax.

Step 3: Migrate MCP Server Configurations

Both Claude Code and Codex support the Model Context Protocol (MCP), and the configuration format is intentionally compatible. Copying your MCP config is the easiest step:

# Claude Code MCP config
cat ~/.claude/mcp.json

# Codex MCP config (same format)
cp ~/.claude/mcp.json ~/.codex/mcp.json

All MCP servers (filesystem, databases, APIs, web search) that work with Claude Code work identically with Codex. No migration work is needed beyond copying the JSON file.

Step 4: API and Credential Configuration

If you followed the prerequisite step and set up a unified gateway, this step is trivial: both tools already point at the same TeamoRouter endpoint. Your single API Key works for both.

If you are migrating away from a direct Anthropic API setup, here is the configuration diff:

With TeamoRouter, both tools use a single API Key. The unified approach eliminates multi-key management:

# Shared configuration with TeamoRouter
export TEAMOROUTER_API_KEY="tr-your-key-here"

# Claude Code
export ANTHROPIC_BASE_URL="https://api.teamorouter.com/anthropic"
export ANTHROPIC_API_KEY="$TEAMOROUTER_API_KEY"

# Codex
export OPENAI_BASE_URL="https://api.teamorouter.com/openai"
export OPENAI_API_KEY="$TEAMOROUTER_API_KEY"

For more on API routing and gateway setup, see TeamoRouter's AI API gateway, which provides unified access to Claude, GPT, Gemini, DeepSeek, and more.

Claude Code vs Codex After Migration: What Changes

Once migrated, be aware of the key workflow differences:

The sandboxed execution model is the biggest adjustment. Codex cannot directly run commands in your terminal; instead, it operates in an isolated environment and writes results back to your filesystem. This is safer but can feel slower for quick shell operations.

Migration Checklist

• Set up a unified API gateway (TeamoRouter recommended) so both tools share one Key and balance
• Export Claude Code session history (JSON for structure, Markdown for reference)
• Copy slash commands from .claude/commands/ to .codex/commands/
• Fix argument placeholder syntax (%ARG% to $ARG, {{selection}} to {{selectedText}})
• Copy MCP server config (mcp.json) from Claude Code to Codex
• Set environment variables for your gateway (ANTHROPIC_BASE_URL / OPENAI_BASE_URL)
• Run a test task in Codex and compare output quality against your last Claude Code session
• Verify billing: run one session and confirm charges appear correctly on your gateway dashboard

Keep Both Tools: The Hybrid Approach

Migration does not have to be all-or-nothing. Many teams in 2026 run both Claude Code and Codex simultaneously, using a gateway like TeamoRouter as the unified routing layer. This hybrid approach lets you:

• Use Claude Code for complex reasoning and architecture tasks (where Claude's long-context reasoning excels)
• Use Codex for PR reviews, issue management, and sandboxed execution (where GitHub integration shines)
• Share one API Key and balance across both tools
• Switch tools per-task without reconfiguring credentials

If you are evaluating both tools side by side, see our detailed Claude Code vs Codex comparison for task-level benchmarks and cost analysis.

FAQ

Can I migrate my full Claude Code conversation history to Codex?

Not natively. Codex does not have a direct import for Claude Code's SQLite history database. The best approach is to export Claude Code sessions as JSON or Markdown files, then reference those files when starting new Codex sessions. The community tool cc-migrate automates batch export and format conversion.

Will my Claude Code MCP servers work with Codex?

Yes. Both tools use the Model Context Protocol (MCP) and share the same configuration format. Copy your mcp.json from ~/.claude/ to ~/.codex/ and everything works. All MCP server types (filesystem, database, API, web search) are cross-compatible.

Do I need separate API Keys for Claude Code and Codex?

Not if you use a unified API gateway. TeamoRouter supports both Anthropic-protocol (Claude Code) and OpenAI /v1/responses (Codex) through a single API Key, one billing dashboard, and one balance. See TeamoRouter's AI API gateway for setup instructions.

Is Codex cheaper than Claude Code?

It depends on your usage pattern and your API provider. Codex tends to make more API calls (due to its loop-based agentic model), but each call is typically shorter. Claude Code sends longer contexts but makes fewer round trips. With a gateway like TeamoRouter that offers prompt caching at >99% hit rate and floating rates as low as 10-20% of official pricing, both tools become significantly more affordable than paying official list price directly.

What is the biggest workflow difference after switching?

Codex runs in a sandboxed execution environment, meaning it cannot directly run commands in your terminal. Commands execute in an isolated container, and results are written back to your filesystem. Claude Code runs directly in your shell. This is the single biggest adjustment: safer, but slower for quick terminal operations.

Can I use both Claude Code and Codex together?

Yes, and this is increasingly common in 2026. Many developers use a unified gateway (like TeamoRouter) with CC Switch to manage both tools from one dashboard, switching per task: Claude Code for deep reasoning and architecture, Codex for PR reviews and sandboxed execution. Both tools share the same API Key and balance.