codex-session-handoff

name

codex-session-handoff

description

Resume and hand off Codex sessions across OpenClaw ACP runtime, direct acpx sessions, native Codex CLI, and local tmux-backed interactive Codex runs. Use when the user wants the exact `codex resume` command for an existing Codex session, wants a local terminal attached to a Codex session, wants to continue an ACP/acpx Codex session from Terminal, or wants to collaborate live in a persistent tmux session running the real interactive `codex` command instead of ACP/acpx.

Codex Session Handoff

Choose the correct collaboration mode first, then either hand off an existing Codex session or create a persistent local tmux session that runs the real interactive Codex CLI.

Mode selection

If the user has not made the mode explicit, ask a short clarifying question:

• 一起做 / 实时协作 / 本地 tmux / 真实 codex → use live tmux mode
• 后台运行 / 你先跑 / 不用我盯着 → use background ACP/acpx handoff mode

Do not default to ACP/acpx when the user explicitly asks for a real local Codex terminal or tmux workflow.

Live tmux mode

Use this mode when the user wants to collaborate in a visible, persistent terminal session.

Rules

• Do not route through ACP or acpx.
• Do not use codex exec for the main collaborative session.
• Start a persistent tmux session and run the interactive codex command directly inside it.
• Keep the working directory explicit with codex -C <cwd> or codex --cd <cwd>.
• Prefer --no-alt-screen so scrollback remains capturable from tmux.

Start flow

1. Resolve or confirm the project directory.
2. Create a durable tmux session name, for example codex-<project>-<timestamp>.
3. Start a detached tmux session that runs interactive Codex in that directory.
4. Wait briefly and capture the pane to confirm Codex started.
5. Return the exact local attach command to the user.

Recommended launch shape:

cd <cwd> && codex --no-alt-screen -C <cwd> "<initial prompt>"

Typical attach command to return:

tmux attach -t <session>

If useful, also provide the stronger variant:

tmux attach -d -t <session>

Before every later turn, inspect tmux first

When the user comes back and asks to continue, do not blindly send a new prompt immediately.

First inspect whether the user already typed into that tmux session or whether Codex already answered there.

Use tmux scrollback capture first, for example:

tmux capture-pane -pt <session>:0.0 -S -300 | tail -n 300

Check for:

• the latest user input already entered in tmux
• the latest Codex reply already visible in tmux
• whether the session is still alive

If the user already entered something in tmux, acknowledge that state before doing anything else. Do not duplicate the same input into Codex again.

If the session died, say so clearly and offer to start a fresh tmux-backed interactive Codex session.

Background ACP/acpx handoff mode

Use this mode when the user wants Codex work to continue mostly on its own in the background, or when the user already has an ACP/acpx/native session handle and wants the native resume command.

Resolve one handle into the native Codex session id, then hand the user a ready-to-run terminal.

Handles

Accept any of these as the input handle:

• OpenClaw ACP runtime session key, for example agent:codex:acp:...
• acpx session name, for example oc-codex-...
• acpx record id, for example 019c...
• native Codex session id, for example 019c...

Resolution flow

1. If the handle is a native Codex session id, use it directly.
2. If the handle is an acpx record id, read ~/.acpx/sessions/<record-id>.json and take acp_session_id.
3. If the handle is an acpx session name, scan ~/.acpx/sessions/*.json, match .name, then resolve carefully:
   • If exactly one record matches, use it.
   • If multiple records match across different directories, do not blindly pick by name; prefer the acpx record id captured at session creation time, or disambiguate by cwd.
4. If the handle is an OpenClaw ACP runtime session key, read ~/.openclaw/agents/codex/sessions/sessions.json, get the acpx record id from acp.identity.acpxRecordId or the encoded runtimeSessionName, then read ~/.acpx/sessions/<record-id>.json and take acp_session_id.

Commands

After resolution, tell the user the exact interactive command. Prefer native Codex -C/--cd so the working root is explicit:

codex resume -C <cwd> <native-session-id>

Equivalent fallback if needed:

cd <cwd> && codex resume <native-session-id>

When the user wants to send one follow-up prompt without entering interactive mode, keep the cwd explicit as well:

cd <cwd> && codex exec resume <native-session-id> "<prompt>"

Scripts

Use the bundled script for handle resolution in background handoff mode:

python3 <OPENCLAW_SKILLS_DIR>/codex-session-handoff/scripts/codex_session_handoff.py resolve <handle>

This prints JSON with:

• native_session_id
• interactive_command
• exec_resume_template
• cwd

To open Terminal and attach it immediately:

python3 <OPENCLAW_SKILLS_DIR>/codex-session-handoff/scripts/codex_session_handoff.py open-terminal <handle>

This opens Terminal and runs Codex with the resolved working directory made explicit:

codex resume -C <cwd> <native-session-id>

Delivery

For live tmux mode

1. Ask whether the user wants to work together live or run in the background if the intent is not explicit.
2. Start a persistent tmux session with interactive Codex when the user chooses live collaboration.
3. Return the exact tmux attach -t <session> command.
4. On every follow-up turn, inspect tmux history before sending anything new.
5. Tell the user what you found in tmux if they have already interacted there.

For background ACP/acpx handoff mode

1. Resolve the handle to native_session_id and cwd.
2. Tell the user the exact codex resume -C <cwd> <native-session-id> command.
3. Prefer acpx record id over session name when the session was just created or when duplicate names may exist.
4. Open Terminal with the bundled script so the attached session is already visible when requested.
5. If a terminal was opened, include the resolved working directory, native session id, and acpx record id when available.