Codex

Persistent memory for Codex

OnlyBots gives Codex a record of where the work stands that survives new sessions and carries over to Claude Code. It is the setup we benchmarked: 19% lower estimated token spend than cold restarts across 54 Codex runs.

Install for Codex Move work between Codex and Claude Code
Install

Set up Codex

  1. Install the CLI

    curl -fsSL https://onlybots.ai/install | bash

    Needs Node.js 18+, 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 OnlyBots codex wrapper ahead of the real one, which is what turns Codex hooks on. Add the line to your shell profile.

  3. Connect Codex

    onlybotsctl quickstart --api-base https://onlybots.ai --adapter codex

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

  4. Check it

    onlybotsctl status
onlybotsctl doctor

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

Under the hood

What happens in a Codex session

HookWhat OnlyBots 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 OnlyBots 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.

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

Use onlybotsctl 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. OnlyBots adds that through Codex lifecycle hooks.

Why does OnlyBots 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 OnlyBots.

Can I move work from Claude Code to Codex?

Yes, in two ways. If both tools are installed under the same OnlyBots profile, working state flows between them automatically, per repository. For an explicit transfer, onlybotsctl handoff export packages the task state, memory references and open questions into a signed capsule, and onlybotsctl 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.