Codex

Persistent memory for Codex

Crosshead gives Codex a record of where the work stands that survives new sessions and carries over to Claude Code. On our October 2026 GPT-6.1 Sol regression suite, it passed 48/48 trials and cost 13.3% less than writing a handoff at every boundary. Native resume was cheaper.

Install for Codex Move work between Codex and Claude Code
Install

Set up Codex

  1. Install the CLI

    curl -fsSL https://crosshead.sh/install | bash

    Needs Node.js 22+, npm, curl and tar on macOS or Linux. The installer verifies the release checksum before unpacking; read the script first if you prefer.

  2. Put it first on your PATH

    export PATH="$HOME/.onlybots/bin:$PATH"

    This puts the Crosshead codex wrapper ahead of the real one, which is what turns Codex hooks on. Add the line to your shell profile.

  3. Connect Codex

    crosshead quickstart --api-base https://crosshead.sh --adapter codex

    Quickstart creates your agent's identity, installs the Codex hooks, starts the local daemon and checks the connection.

  4. Check it

    crosshead status
crosshead doctor

    After a restart, run crosshead start to bring the daemon back.

Under the hood

What happens in a Codex session

HookWhat Crosshead does
SessionStartAttaches the session to this repository's memory.
UserPromptSubmitReturns a compact context pack (about 360 tokens at most) as additional context: the current goal, recent turns and how the last session ended.
StopRecords the turn's outcome and saves the updated working state.
PreCompact / PostCompactSaves working state immediately around compaction.
Handoffs

Moving work between Codex and Claude Code

When both adapters run under the same Crosshead profile, there is nothing to do: each tool reads the working state the other saved for the same repository.

For an explicit, auditable transfer, export a signed handoff capsule from one tool and import it in the other. The capsule carries the task state, memory references and open questions, and the receiver verifies the signature before loading it.

crosshead handoff export --source codex --target claude-code --workspace-root "$PWD" --session-id <session> --prompt "Finish the token-expiry fix"
crosshead handoff import --target claude-code --id <handoff_id> --workspace-root "$PWD" --session-id <session>

Use crosshead handoff explain --id <handoff_id> to see exactly what a capsule contains.

FAQ

Codex memory questions

Does Codex remember between sessions?

Codex reads AGENTS.md at the start of a session and can resume an earlier session's transcript. It doesn't keep a running record of where the work stands across new sessions. Crosshead adds that through Codex lifecycle hooks.

Why does Crosshead install its own codex command?

Codex only runs lifecycle hooks when hooks are enabled. The codex wrapper in ~/.onlybots/bin starts the real Codex with hooks enabled. If ~/.onlybots/bin isn't first on your PATH, Codex runs without Crosshead.

Can I move work from Claude Code to Codex?

Yes, in two ways. If both tools are installed under the same Crosshead profile, working state flows between them automatically, per repository. For an explicit transfer, crosshead handoff export packages the task state, memory references and open questions into a signed capsule, and crosshead handoff import verifies and loads it on the other side.

Is the Codex install per project?

No. The Codex adapter installs into ~/.codex/hooks.json for your user, and memory is still kept separately for each repository.