codex-handoff

Hand this session off to Codex — or pull Codex's work back into Claude. One command, both directions.

Use this when Claude tokens are running low (or you want a different model on the problem). It wraps the codex plugin's transfer, fixing the two things that make the raw command awkward: the transcript it can't auto-detect, and the fact that there is no built-in way back.

Requires the opt-in codex plugin (openai/codex-plugin-cc). If it isn't installed, say so and stop: /plugin marketplace add openai/codex-plugin-cc, /plugin install codex@openai-codex, /reload-plugins, then /codex:setup.

Argument: $ARGUMENTS — empty means go to Codex; back means return to Claude, and back <session-id> returns from a specific handoff when the checkout has more than one on record.

Preflight (both directions)

1. Resolve the companion script, preferring the version this setup pins. Never hardcode a single version — the path contains one and it changes on plugin update — but don't blindly take the newest either, or a freshly-cached release silently supersedes the pinned one:

   CODEX_PIN="v1.0.6"   # keep in step with `ref` in settings.codex.example.json
   CODEX_ROOT="$HOME/.claude/plugins/cache/openai-codex/codex"
   CODEX_COMPANION="$CODEX_ROOT/${CODEX_PIN#v}/scripts/codex-companion.mjs"
   if [ ! -f "$CODEX_COMPANION" ]; then
     CODEX_COMPANION="$(ls -1d "$CODEX_ROOT"/*/scripts/codex-companion.mjs 2>/dev/null | sort -V | tail -1)"
   fi
   

   If the pinned version is absent and a different one is used, say which — the user is running code they didn't pin. If nothing resolves, the plugin isn't installed (see above) — stop.
2. Confirm Codex is ready: node "$CODEX_COMPANION" setup --json. If ready is not true, report which check failed (node / npm / codex / auth) and stop — auth false means !codex login.
3. Resolve one state file path, used by both directions. A relative path breaks when the return leg runs from a different directory, so anchor it to the repo root and create the parent:

   ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
   SESSION_LOG="$ROOT/.claude/codex-sessions.log"
   mkdir -p "$(dirname "$SESSION_LOG")"
   

   The log holds one append-only record per handoff, keyed by session id — <utc-timestamp>\t<session-id>\t<baseline-head>. Handoff state must never live in a single-slot file: two handoffs from one checkout (a second problem the same afternoon, two agents, two worktrees of the same repo) would overwrite each other's baseline, and back would silently resume whichever was last without saying so. Everything the return leg needs is in the record it selects.