harness-convert · Codex ↔ Claude Code

Move a coding session
between agents.

Your harness hit a rate limit 80% through the fix. Relocate the whole session to a live agent in two seconds and resume exactly where you left off.

~/project — claude code
> fixing the failing payments test… ✗ usage limit reached · resets in 1h # 30 min to ship. you're stuck. $ hc --from claude --to codex from : claude (ce0dc35e…) to : codex records: 243 (78 tool calls) title : "Fix the failing payments test" $ hc --from claude --to codex --write ✓ wrote rollout · resume with: $ codex resume ce0dc35e… # full history. keep going.
The problem

Rate limits don't care that you're 80% done.

When your agent goes dark mid-task you lose more than time — you can't even ask it for a handoff doc, because the thing that would write it is the thing that's down. hc reads the session transcript straight off disk. The dead harness never needs to be running, and your quota never needs to come back.

claude
limit reached
hc, 2s
transcript
read off disk
rewrite
codex
resume & ship
How it works

A session is three streams. hc maps all three.

One common interface every harness must satisfy, plus a sparse map for the extras — so any pair converts, and special pairs convert richer.

1 Common interface

Every harness maps to four records — user message, assistant reply, ToolCall, ToolResult. The universal floor that guarantees any pair resumes.

2 N² enrichment

Surplus the floor can't hold — session titles, modes — rides a sparse (from, to) map, layered on top. Never re-encodes the common stuff.

3 Dual streams

Writes both the model-context stream and the UI scrollback — including exec and diff tool cards — so history renders, not just resumes.

4 Ragged tails

The source usually died mid-tool-call. Every orphaned call gets closed, or the resumed agent would reject the history. The normal case, handled.

Install

Stdlib only. Zero dependencies.

An escape hatch can't ask you to npm install while you're on fire. One Python file, nothing to pull.

pipx install harness-convert

hc --from claude --to codex  # the whole thing