How to move a coding-agent session from Claude Code to Codex

Your coding session needs an exit before it needs rescue

An AI coding session starts as something disposable: ask for a small change, look at the diff, move on. Then it accumulates useful state. The agent has read the repository, found an awkward edge case, run commands, made decisions, and left behind tool output that explains why the next step is what it is.

At that point, switching tools should be a workflow decision, not a reason to start over.

Maybe the current provider is degraded. Maybe a quota is about to interrupt the work. Maybe Codex is better for the next phase than Claude Code, or the reverse is true. The important point is broader: a long-running session should have an exit before it needs one.

Agent Airlift is a local CLI for making that exit explicit. It takes an observable coding session, turns it into a deterministic handoff bundle, and gives a fresh session in another tool something real to inspect before it continues.

This is not about treating every coding session as fragile. It is about making useful work portable when a change of harness is the sensible next move.

What an honest handoff can preserve

There is a hard boundary here. A tool cannot copy a model’s hidden state or chain-of-thought into another model. Pretending otherwise makes a transfer harder to trust.

What can move is the observable trail around the work:

• user and assistant messages;
• tool calls and tool results;
• selected repository context;
• decisions, command history, and current objective;
• timestamps, warnings, and source provenance; and
• fields the importer can preserve or explicitly account for.

That is enough to make a new session useful when it is represented well. The destination agent does not receive a mystical continuation of the old agent. It receives a readable record of what happened, what matters now, and where to verify it.

This distinction shapes the product. Agent Airlift normalizes observable data into a canonical session before it produces a handoff document or a target-shaped export. That canonical record becomes the reference point for the rest of the bundle.

Move a Claude Code session into Codex

The direct CLI workflow is intentionally plain. Given a Claude Code session JSONL file and the project directory it worked in, run a migration. The source and project paths below are local placeholders:

agent-airlift migrate \
  --session /path/to/claude-session.jsonl \
  --project /path/to/project \
  --out ./airlift-out \
  --source claude-code \
  --targets codex \
  --provider-health none

--provider-health none is deliberate here. A handoff can be an explicit choice without any external health signal. The output is where the value becomes concrete:

airlift-out/
├─ raw/          source session, project snapshot, optional health signal
├─ normalized/   canonical-session.json
├─ replay/       agent-airlift.session.jsonl
├─ exports/      HANDOFF.md, AGENTS.md, Codex-shaped output
└─ audit/        conversion-report.md, warnings.json,
                 dropped-fields.json, import-diagnostics.json, ci-gate.json

HANDOFF.md is the page a person should read first. It organizes the current objective, important files, decisions already made, commands that ran, errors or risks, open questions, recommended next actions, and a resume prompt. AGENTS.md supplies the project context alongside it.

That is a materially better starting point than pasting the last prompt into a new tool. A last prompt usually omits the failed build, the tool result that revealed the failure, the files that matter, and the reasoning that made a particular implementation worth keeping.

The next move is simple: inspect HANDOFF.md, review the audit material when the work is sensitive, then open a fresh Codex session with the bundle available. Codex can verify the evidence instead of guessing what happened before it arrived.

The bundle is the handoff

Claude Code session JSONL + selected project files
                    ↓
          tolerant import + raw preservation
                    ↓
 canonical session: turns, tool records, provenance, hashes
                    ↓
 replay record + readable handoff + Codex-shaped export + audit trail
                    ↓
              fresh Codex session

Each layer has a separate job.

The importer accepts supported Claude Code, Codex, and flat JSONL shapes. It is designed to record malformed input as structured warnings instead of failing without an explanation. The raw source session stays in the bundle, so the normalized interpretation is never the only copy of the record.

The canonical session makes the transfer deterministic. Each turn carries its role, content, timestamps, source provenance, structured tool calls and results, preserved metadata, and hashes. That lets the product produce readable exports for a target tool without quietly turning a summary into the source of truth.

The replay record and target-shaped export serve different audiences. The replay representation preserves a normalized trail. The Codex-shaped export makes that trail legible to the destination workflow. The handoff document translates the important current state into a form a person and a new agent can both audit quickly.

What makes the transfer auditable

The bundle is useful because it can account for itself.

1. Raw evidence remains available. The source JSONL and a snapshot of the selected project files are kept under raw/.
2. Canonical turns are identifiable. Every normalized turn includes source and canonical SHA-256 hashes, so later artifacts can point back to a specific record.
3. Tool activity stays structured. Tool calls and tool results are captured as records instead of being flattened into an attractive but unverifiable narrative.
4. Import behavior is reported. import-diagnostics.json and conversion-report.md record the detected format, confidence, mapped records, malformed rows, warnings, and accounting state.
5. Uncertainty is visible. Data the importer can retain remains in metadata; unmapped fields are listed in dropped-fields.json instead of disappearing silently.
6. Exports are checked against the source of truth. ci-gate.json verifies balanced accounting, hashes, replay consistency, and correspondence between exports and the canonical session.

That is a practical standard for a sensitive workflow. You do not have to assume that the new session received everything. You can inspect what entered the conversion, what the importer recognized, what it could not map, and what it emitted.

The checked-in realistic Claude Code fixture shows the intended shape. Its migration imported 11 turns, captured four tool calls and three tool results, preserved a nested field, emitted zero warnings, and passed the audit gate. Those numbers describe that fixture, not an average or a promise for every session. Their purpose is to make the path testable.

Codex to Claude Code follows the same contract

The direction can reverse without changing the principle. A Codex session is imported as observable data, normalized into the same canonical form, and emitted as a readable handoff bundle for Claude Code. Review the handoff and audit artifacts, then begin a fresh Claude Code session with that evidence in reach.

The storage formats and native conveniences of the tools differ. The contract does not: preserve what can be observed, state what could not be mapped, and make the transfer inspectable before the next agent acts.

Provider health is confirmation, not control

Most people already know when a session is worth moving. A provider-health signal can corroborate that judgment, but it should not replace it.

Agent Airlift can run with health disabled, consume a local health file, or refresh a health signal when the user asks. When a signal suggests a provider is degraded, the optional integrations can recommend a handoff. They still invoke the same explicit migration pipeline; they do not choose a destination tool, block a manual transfer, or trigger an invisible transfer.

This is the right amount of automation for the boundary. Health data is helpful context. The user remains responsible for deciding when their work should move.

Try it before you need it

Agent Airlift is intentionally narrower than an agent-teleportation story.

• It does not reconstruct hidden model state or chain-of-thought.
• The default contract is not a guaranteed native resume.
• A transfer is explicit; the tool does not autonomously move a session between harnesses.
• The core migration stays local and does not upload generated artifacts.

Codex and Claude Code native-shaped session files can be installed as an opt-in convenience, but the portable contract is the readable handoff bundle. That is what should remain useful even when a target tool changes how it stores its own sessions.

If a coding session is becoming valuable enough that a provider change, a quota boundary, or a different tool would be disruptive, try Agent Airlift on GitHub. Run a migration on a non-critical session first, inspect HANDOFF.md and the audit artifacts, and make the next handoff a workflow you can explain.