Switching From Claude Code to Codex Without Losing Context

Freeze the task before changing clients

Before closing Claude Code, record the branch, commit, uncommitted changes, current objective and last verification result. Ask it to identify unfinished edits and the next useful action, then compare that account with the working tree. A handoff saying that tests passed is incomplete without the command, result and revision it describes.

Separate the material you need to move: repository rules, accumulated facts, reusable procedures and connections to external systems. Give each an explicit destination. Keep the active task in a short handoff note; keep lasting development rules beside the code; keep personal preferences out of team-wide notes. This prevents a temporary debugging workaround from becoming a permanent instruction during migration.

Record client versions and launch directories alongside that inventory. For this guide, perform the first migration between local terminal clients against the same checkout. Moving to a cloud container at the same time adds filesystem and network differences that make a failed handoff harder to diagnose. Preserve the original Claude configuration until the Codex acceptance checks pass.

Give repository instructions one editable home

Move agent-independent requirements from CLAUDE.md into a reviewed root AGENTS.md: setup commands, editing boundaries, verification commands and important architecture constraints. Codex documents startup discovery of AGENTS.md, with AGENTS.override.md taking precedence in the same directory. Check for existing overrides before assuming the new shared file will load.

Keep Claude-specific guidance in its adapter. Anthropic documents this import as a way to share the neighboring file:

@AGENTS.md

Use that as the shared-content portion of CLAUDE.md, retaining any necessary Claude-specific additions below it. Current Claude Code also supports direct AGENTS.md loading, but its default selection changes when Claude instruction files exist on the project path. Verify the actual setup rather than inferring it from filenames.

Do the same review for nested service instructions and personal defaults. A release restriction buried in a home-directory file is easy to miss when changing clients. Put team requirements in the repository and install personal preferences deliberately. The instruction synchronization guide covers maintaining those adapters after the initial move.

Reconnect MCP services with fresh authentication

Inventory the MCP services Claude actually uses, including transport, endpoint, required access and any locally launched process. Preserve remote service addresses while translating client configuration. Anthropic documents this HTTP registration syntax; replace the illustrative address with your own service:

claude mcp add --transport http company https://mcp.example.com/mcp

For Codex, OpenAI documents an MCP table in ~/.codex/config.toml. A bearer-token configuration for that same illustrative endpoint is:

[mcp_servers.company]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "COMPANY_MCP_TOKEN"

Supply the token through the environment inherited by the Codex process. Use a separately issued credential with the intended scope so the old client's access can be retired independently. The configuration contains the variable's name; keep its value out of the article's suggested handoff files and version control.

For an OAuth service, omit the bearer-token setting and authenticate through codex mcp login company. OpenAI documents codex mcp list for checking configured servers and /mcp inside the terminal interface. Confirm an actual permitted read afterward. A configured endpoint alone does not establish that authentication or source access works.

Extract useful memories instead of copying everything

Open Claude Code's /memory view and inspect the relevant notes. Anthropic documents machine-local Markdown memory under ~/.claude/projects/<project>/memory/, including a MEMORY.md index and topic files. Treat that location as material to review, rather than an implicit input Codex will discover.

For each retained fact, record its subject, evidence and date. A useful handoff might say that the invoice integration test needs a local Redis instance, identify the test configuration establishing that dependency, and give the last successful command. A note that merely says the integration is unreliable gives the incoming agent little to verify.

Put reviewed shared facts in a team-owned Markdown location or an external context store both clients can read. Keep personal notes separate. Remove credentials, obsolete experiments and unsupported conclusions before transferring them. For the first Codex task, explicitly request that it read the handoff and resolve the referenced files before proposing edits.

Link longer background from the handoff instead of pasting every old turn into the opening prompt. For ongoing retrieval across clients, see shared memory across coding agents.

Move skill packages and review their assumptions

Claude Code documents project skills at .claude/skills/<name>/SKILL.md; Codex documents repository discovery under .agents/skills. Move or distribute reviewed packages into the destination's supported location, preserving their scripts, references and relative paths. Keep one editable source and make any distributed copies reproducible.

A small portable package can start with .agents/skills/review-handoff/SKILL.md:

---
name: review-handoff
description: Review an agent handoff before resuming unfinished coding work.
---
Read the handoff and inspect the current working tree.
Check recorded facts against their referenced files.
Report contradictions and the next action before editing.

Both vendors document skill descriptions as discovery input. Test explicit invocation first, then test whether a normal handoff request selects the skill. In Codex, use $review-handoff for the explicit check.

Review every transferred package for Claude-specific tool names, argument substitutions, permission fields and dynamic command injection. Anthropic documents these as runtime features; ordinary Markdown portability does not establish equivalent execution elsewhere. Rewrite required behavior using supported mechanisms and test bundled scripts in the destination environment. Keep client-specific adaptations separate from the shared procedure. The portable skills guide develops that boundary.

Where SPYN3 fits

SPYN3 provides one MCP endpoint per workspace at https://api.spyn3.com/agent/mcp for connected systems. Its opt-in Memory & skills layer exposes memories, skills and notes through context tools any MCP client can use. Reading needs call:tools; memory writes need the separate write:memory permission. The Claude Code and Codex plugin loads context at session start and recalls relevant memories per prompt. Give Codex its own scoped key while keeping the same workspace context. Upstream credentials stay in SPYN3 rather than moving between agent configurations.

Accept the handoff in a fresh Codex session

Start Codex from the intended working directory and give it a bounded continuation task. For example, ask it to read the handoff, explain why the invoice test needs Redis, identify the next unfinished edit and retrieve one permitted record through MCP. Require file or tool evidence for each answer before allowing the edit.

1. Confirm the expected repository instructions loaded, including service-specific guidance.
2. Check that a retained memory leads to its current supporting file, rather than an unverified repeated assertion.
3. Invoke the transferred skill and inspect whether it follows the reviewed procedure.
4. Exercise a permitted MCP read and verify that a restricted operation is denied by the service's authorization controls.
5. Finish the bounded change and run the repository's real verification command.

Keep the results with the migration record. If Codex misses a fact, distinguish an unread note from an incorrect note; if a tool fails, distinguish authentication from connectivity. Once the checks pass, remove superseded configuration and revoke credentials issued solely for the retired client. Retain the reviewed handoff and shared packages so the next switch starts from maintained artifacts.