How to Carry Context Between Claude Code and Codex

Published August 19, 2026 · by the AQ team

When you switch from Claude Code to Codex mid-task (or the other way), two layers of context move and two do not. Everything in git moves: files, branches, commits, and stashes are tool-agnostic. Your instruction files move if you unify them: keep one AGENTS.md as the source of truth and have CLAUDE.md import it, and both CLIs start every session with the same project knowledge. What does not move is the session itself. Each CLI stores its transcripts locally in its own format, and as of August 2026 neither tool can resume the other's session. So the reliable recipe is: unify the instruction files once, commit or stash work in progress, and have the outgoing agent write a short handoff note that the incoming agent reads first.

What "context" actually means here

Developers who say "I lost all my context switching CLIs" are usually talking about four different things at once. They behave very differently at the boundary:

• Repository state. The working tree, branches, commits, uncommitted changes. Lives in git, fully portable.
• Instruction files. CLAUDE.md, AGENTS.md, rules files: the standing knowledge you wrote down (build commands, conventions, architecture notes). Portable if you structure them once.
• The session transcript. The running conversation: what you asked, what the agent tried, what failed, the plan it was halfway through. Stored per tool, in per-tool formats, not portable between them.
• Tool-side memory. Notes the tool accumulates for itself across sessions (Claude Code's auto memory is the clearest example). Per tool and per machine, not portable.

The pain people describe on forums ("spent months teaching one tool my project, switched, lost everything") is almost always layers three and four. The fix is to push as much knowledge as possible down into layers one and two, where switching costs nothing.

Layer 1: repo state moves by itself

This layer needs no tooling, just discipline at the moment you switch. Commit work in progress on the task branch (a WIP commit you will squash later is fine), or stash it if it is genuinely throwaway. The incoming CLI sees exactly the same tree, and a plain git worktree per task keeps two tools from trampling each other if the old session is still running somewhere.

An underrated part of this layer: the git log itself is context. Small commits with real messages give the incoming agent a readable history of what has already been tried. Both Claude Code and Codex will read recent commits when you ask them to get oriented, and a good log beats any amount of re-explaining.

Layer 2: one instruction file both CLIs read

The two tools look for different files. Codex reads AGENTS.md: the repository root file, plus a global one at ~/.codex/AGENTS.md, as of August 2026. AGENTS.md is an open format stewarded under the Linux Foundation and read by many other agents (Cursor, Gemini CLI, and others). Claude Code reads CLAUDE.md, not AGENTS.md, and Anthropic's own docs recommend bridging the gap with an import rather than duplicating content.

The clean setup is one source of truth, AGENTS.md, with CLAUDE.md as a thin pointer:

# CLAUDE.md
@AGENTS.md

## Claude Code specific notes
(anything only Claude Code should see goes here)

Claude Code expands the @AGENTS.md import at session start, so both tools load identical project instructions and you edit them in exactly one place. If you have no Claude-specific additions, a symlink does the same job on macOS and Linux:

ln -s AGENTS.md CLAUDE.md

(On Windows, symlinks need Developer Mode or Administrator rights, so prefer the import.) Starting from zero, both CLIs will scaffold the file for you: /init in Codex generates an AGENTS.md from what it detects in the repo, and /init in Claude Code does the same for CLAUDE.md. Claude Code also ships an /import command that copies an existing AGENTS.md into CLAUDE.md as a one-time migration, but the live import or symlink is better because the files can never drift.

Whichever direction you migrate, move the durable knowledge here: build and test commands, code conventions, directory layout, "always do X before committing" rules. Every fact you promote from a chat message into this file is context that survives any tool switch forever.

Layer 3: sessions do not transfer, so learn both resume commands

Both CLIs persist sessions locally and resume them well, within themselves:

• Claude Code stores transcripts as JSONL under ~/.claude/projects/, one file per session. Run claude --continue to reopen the most recent session in the current directory, or claude --resume to pick from a list. Our guide to resuming and searching Claude Code sessions covers this in depth.
• Codex stores transcripts as JSONL under ~/.codex/sessions/. Run codex resume for a picker of past sessions, or codex resume --last to jump straight back into the most recent one.

What neither tool offers, as of August 2026, is importing the other's transcript. The formats are different, and neither CLI has a supported way to load a foreign session. Pasting chunks of one tool's transcript into the other works about as well as pasting any long document: the model reads it as reference material, not as its own conversation. A last resort, not a workflow.

The handoff note: the 2 minutes that make switching cheap

Since the transcript cannot move, distill it. Before you leave the outgoing tool, ask it to write the distillation to a file:

Write a handoff note to HANDOFF.md covering:
1. The goal of this task, in one sentence
2. What has been changed so far and why (list the files)
3. What was tried and did NOT work, and what we learned
4. The exact next step you were about to take
5. How to verify: the test or command that proves it works

Then start the incoming CLI with "Read HANDOFF.md and continue the task." Point four is the one people skip and regret: the record of dead ends is what stops the second agent from cheerfully re-attempting the approach that just failed. The same note works in the other direction, and if you finish the task instead of switching, the note folds naturally into the PR description. Committing it on the task branch lets the note travel with the work to any machine.

If you switch between the same pair of tools often (a common pattern is drafting in one CLI and reviewing or continuing in the other when a usage limit hits), put the handoff instruction in AGENTS.md itself as a standing rule, so any agent asked to "hand off" knows the format without being told.

At a glance

Switching vs running both at once

Much of the switching pain comes from serializing two tools on one checkout. If you switch for capability (one model is better at the plan, the other at the grind) rather than a usage limit, it is often simpler to run both in parallel on separate worktrees, or to keep one session running while the other takes a subtask. Then nothing needs to be carried at all: each session keeps its own context for the whole life of its task, and git integrates the results.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. AQ does not translate session transcripts between vendors either (nothing does, honestly), but it removes the environment half of the switching problem. Both CLIs run as real terminals inside the same workspace, on the same VM, in the same isolated git worktree, so layer one is shared by construction: when you open a Codex tab next to a running Claude Code tab, it is already on the same branch, with the same uncommitted files and the same dependencies installed.

The sessions themselves are persistent tmux sessions on the VM, streamed live to the browser. They survive a closed laptop and resume from any device, so the Claude Code session you stepped away from stays alive and scrollable next to the Codex session that took over. And because teammates can open the same workspace and watch the same live sessions, the context stops being trapped with one person: whoever picks the task up next reads the same terminals, not a secondhand summary. Each engineer signs into the CLIs with their own Claude and OpenAI accounts, so running both side by side needs no shared keys and AQ never marks up model usage.

If you switch CLIs mid-task even occasionally, do the AGENTS.md unification today; it costs ten minutes once. The handoff note costs two minutes per switch. AQ earns its place when the switching happens across a team: same worktree, both sessions live, everyone able to see them.