Move from Claude Code to Codex without losing context

Three operational reasons drive the switch: the context limit hit on Claude Code (200,000 Sonnet tokens, saturated after 3-4 hours of refactoring), the cost of output tokens on long sessions, and Codex CLI's specialization in running chained shell tasks via its --full-auto mode. Many teams use Claude Code for architectural exploration, then Codex for the mechanical implementation and the tests.

The switch fails when the new agent starts the analysis over. By default, Codex ignores CLAUDE.md and MEMORY.md files and the session JSONL stored in ~/.claude/projects/. Without an explicit bridge, the user manually re-pastes 40 minutes of context, gets three decisions wrong and breaks the shared worktree. A structured handoff solves this in 2 minutes instead of 40.

The target format fits into five blocks: current objective, repository and branch, locked decisions, current tests, next actions. Five blocks, under 2,000 tokens, no ambiguity about who picks up what.

Step 1 — Freeze the Git state. In the Claude Code terminal, run git status then git stash push -u -m "handoff-$(date +%s)" if any files are modified. This command saves even untracked files (-u) and prevents Codex from overwriting work in progress. Note the returned hash.

Step 2 — Sync the session into Tramya. Run tramya sync --project $(basename $PWD). The companion reads the Claude Code JSONL, extracts the objective, decisions and branch state via the get_project_context API. The last-read date is shown to confirm nothing was missed.

Step 3 — Generate the handoff. Call tramya handoff --to codex --format markdown > HANDOFF.md. The resulting file is typically 1,200 tokens: objective, branch, worktree, 3 to 8 recent decisions, the result of pytest or npm test, and the next 3 ordered actions.

Step 4 — Launch Codex in the same worktree. Run codex --model gpt-5-codex --config-file HANDOFF.md. Codex loads the brief before the first turn and continues with the listed actions, with access to the same files as Claude Code.

The rule is simple: one Git worktree per active agent. Two CLIs writing into the same folder corrupt the caches (.claude/, .codex/) and cause merge conflicts on generated files. The command git worktree add ../projet-codex feature/refactor-auth creates a sibling folder that shares the Git history but isolates the working files.

In practice, Claude Code stays in ~/projects/tramya on the main branch. Codex picks up in ~/projects/tramya-codex on feature/refactor-auth. Both see all the commits, but their uncommitted changes do not interfere. The Tramya handoff automatically includes the absolute path of the target worktree, so Codex does not open the wrong folder at launch.

At the end of the Codex session, run git worktree remove ../projet-codex once the branch is merged. Never delete the folder by hand with rm -rf: the .git/worktrees/ file would keep a dead reference that would block the next worktree add on the same name.

1. "Codex does not see my AGENTS.md." Codex CLI looks for the file at the root of the Git repository, not in the current subfolder. Run cd $(git rev-parse --show-toplevel) before codex, or create a symbolic link ln -s CLAUDE.md AGENTS.md to reuse the instructions already written for Claude.

2. "fatal: not a git repository." The target worktree has no readable .git folder. Check with git worktree list. If the worktree shows as "prunable," regenerate it via git worktree repair.

3. "Codex repeats the analysis already done." The handoff was not loaded. Check that HANDOFF.md appears in the first system prompt: codex --show-context | head -50. If missing, relaunch with --config-file using an absolute path, not a relative one.

4. "MCP tool not found: get_project_context." The Tramya MCP server is not declared in ~/.codex/config.toml. Add the [mcp_servers.tramya] section with the launch command, then relaunch Codex.

5. "Merge conflict in .claude/settings.local.json." This file has no business being in Git. Add it to .gitignore, run git rm --cached .claude/settings.local.json, then commit.