Codex side fork

Codex Side Fork

Recover a side chat from Codex Desktop's own conversation Markdown while its renderer cache is still available. Invoke the app's live Copy as Markdown shortcut, use persisted prompt history to recover exact user-turn boundaries, remove tool activity, then create a durable task and verify every reconstructed turn through both app-server and Codex Desktop's own Markdown export. Diagnostics are a partial fallback when the renderer is no longer available.

In every command below, resolve <skill-root> to the directory containing this SKILL.md. Do not assume that the skill was installed under a particular home directory; plugin installs may load it from a managed cache.

Clarify The Request

If the user did not already specify these choices, ask concise questions before creating anything:

1. Which side chat: current side chat, exact thread ID, or remembered text to search for.
2. Output: Markdown only, durable task only, or both.
3. Durable mode: fork the parent task, create a clean task, or create a clean task with a compact parent summary.

For parent-fork mode, do not ask the user for the parent thread ID. The CLI resolves it from Codex Desktop's side-chat creation log and verifies that the result is a durable thread. An explicit parent ID is only a manual override after automatic resolution reports a real ambiguity or missing evidence.

Locate A Side Chat

Use the CLI. It searches only user prompt history and parsed user/assistant message records, not tool output or reasoning logs.

python3 <skill-root>/scripts/codex_side_fork.py find "remembered phrase"

If several candidates match, show their IDs and snippets and ask the user to choose. Do not guess.

The current side chat ID is normally available as $CODEX_THREAD_ID:

python3 <skill-root>/scripts/codex_side_fork.py inspect

Promote A Cached Side Chat Into The Main View

When the side tab is still open, preserve the durable parent thread ID, then open the side thread's deep link:

open "codex://threads/<side-thread-id>"

Codex can render the cached ephemeral conversation in the normal main-task layout while leaving the original side tab mounted. This is a temporary renderer view, not a durable conversion: the side thread still has no rollout and native thread/fork still cannot fork it.

Codex must have a custom shortcut assigned to Copy as Markdown under Settings > Keyboard shortcuts. Option+Command+M is the verified shortcut on this machine.

Use gui-copy to promote the side thread, invoke that live shortcut, and cache the clipboard synchronously:

python3 <skill-root>/scripts/codex_side_fork.py gui-copy \
  --thread-id <side-thread-id> \
  --json

The helper reads the exact shortcut from ~/.codex/keybindings.json, saves the thread currently visible in the main pane, opens the side-thread deep link, activates Codex, invokes the shortcut, waits for the clipboard to change to conversation Markdown, and writes a new mode-0600 file. It then restores the previously visible thread. It does not open the disabled Task actions menu, use screen coordinates, or schedule background work. If no shortcut is configured, stop and ask the user to assign one.

To cache Markdown that the user copied manually, use the clipboard fallback:

Cache the copied Markdown in a private temp file:

python3 <skill-root>/scripts/codex_side_fork.py capture \
  --thread-id <side-thread-id> \
  --json

The clipboard fallback only reads the clipboard. Both capture paths write a new mode-0600 file under /tmp and report its path, byte count, and SHA-256 hash without printing the transcript. Do not close the original side tab before capture succeeds. Restore the main pane afterward when no durable thread is being opened:

open "codex://threads/<durable-parent-thread-id>"

This promotion path was directly verified for an active side chat. The frontend also keeps an expired-but-open side chat mounted read-only, so this is the first recovery path to test when the GUI has blocked new submissions. Report whether promotion and export actually succeeded; do not assume they did.

Inspect And Export Markdown

Inspect the renderer capture first:

python3 <skill-root>/scripts/codex_side_fork.py inspect \
  --thread-id <side-thread-id> \
  --renderer-markdown /tmp/codex-side-fork-renderer-....md \
  --json

The parser expands Codex's previous messages wrappers, removes nested activity/tool blocks, uses Desktop prompt history for ordinary user text, and preserves assistant text as separate message blocks. It also aligns diagnostics turns with the renderer sequence. This recovers annotation-only submissions that Codex omits from both prompt history and Copy as Markdown, and moves their assistant replies back from the previous visible turn. If current prompt history has later ordinary prompts than the capture, capture Markdown again before creation.

Export a clean transcript to a real file:

python3 <skill-root>/scripts/codex_side_fork.py export \
  --thread-id <side-thread-id> \
  --renderer-markdown /tmp/codex-side-fork-renderer-....md \
  --output /absolute/path/side-chat.md

Always report the raw renderer capture path and the clean export path when one was requested. Never call a transcript complete when the CLI reports a gap.

When no renderer capture is possible, omit --renderer-markdown to use prompt history plus retained diagnostics. That fallback can be incomplete because old assistant diagnostics rotate away. Report every warning and never describe diagnostics recovery as complete when it reports gaps.

Create A Durable Task

Creation mutates Codex task state and therefore requires the user's mode choice and --confirm-create.

Fork The Parent

This uses Codex Desktop's native Continue in new task from here action in a temporary second Codex window so the child inherits the parent's real Desktop workspace and projectless metadata. While that window is still open, it appends each recovered side-chat user prompt and its assistant replies as a separate normal turn. It then closes only the temporary window and returns focus to the original window:

python3 <skill-root>/scripts/codex_side_fork.py create \
  --thread-id <side-thread-id> \
  --renderer-markdown /tmp/codex-side-fork-renderer-....md \
  --mode fork \
  --name "<task name>" \
  --confirm-create

The result includes parent_resolution with the exact Desktop log evidence. To inspect that relationship without creating anything:

python3 <skill-root>/scripts/codex_side_fork.py resolve-parent \
  --thread-id <side-thread-id> \
  --json

Create A Clean Task

python3 <skill-root>/scripts/codex_side_fork.py create \
  --thread-id <side-thread-id> \
  --renderer-markdown /tmp/codex-side-fork-renderer-....md \
  --mode clean \
  --cwd "$PWD" \
  --name "<task name>" \
  --confirm-create

For a compact parent summary, generate a factual summary from the parent context, write it to a temporary file, and add:

--parent-summary-file /absolute/path/to/summary.md

Use --markdown-out /absolute/path/side-chat.md when the user chose both outputs. Creation rejects a renderer capture that does not include every current Desktop prompt. --allow-stale-renderer is only for a user who explicitly accepts omitting the newer turns.

Desktop prompt history can rotate before a long side chat is recovered. When an earlier clean codex-side-fork Markdown export exists, merge it with the fresh renderer recovery using:

--prefix-recovery-markdown /absolute/path/to/earlier-clean-export.md

The merge is accepted only when the earlier export's trailing user turns exactly match the current recovery's leading user turns and every assistant message in the overlap also matches. The CLI rejects a different thread ID, no overlap, a gap, or any overlap mismatch.

The CLI does not add a continuation note or transcript wrapper. The final recovered user prompt remains the final user prompt in the durable task.

Creation succeeds only after all of these checks pass:

1. A fresh thread/read reconstructs the exact imported turns and user/assistant text.
2. Fork mode confirms that the child has the same Desktop workspace root, projectless classification, and projectless output directory as the parent.
3. The completed rollout remains unopened in the original window until after all recovered turns have been written and verified.
4. The thread that was visible before creation is restored.

If any check fails, the CLI leaves the newly created thread in place for inspection, restores the previous view, and reports its ID with the error.

Report The Result

After every successful durable-task creation:

1. Report the task title, thread ID, mode, raw side-chat renderer capture path, clean Markdown path when present, restored thread ID, and all recovery warnings.
2. Read thread_deeplink_markdown from the CLI result.
3. Put that clickable Markdown link on its own line as the final line of the response, in this exact form:

[Open Codex thread](codex://threads/<thread-id>)

Do not output the URI as unlinked text. Do not place text, a hard-stop marker, or a citation block after the clickable link.

Important Behavior

• The imported messages are persisted as real model-visible user and assistant history.
• Each recovered user prompt is a separate rendered turn. Assistant commentary and final answers remain attached to that prompt in their original order.
• thread/inject_items is not used. Standalone response items do not reconstruct as visible Codex turns.
• Obvious access tokens and common API-key formats are redacted before export or import.
• User prompts, assistant commentary, and assistant final answers are included. System/developer instructions, inherited parent history, tool calls, tool output, and reasoning are excluded.
• A clean task is top-level. A parent fork records forkedFromId but is not a spawned sub-agent task.
• Temporary deep-link navigation is restored to the thread that was visible before capture or creation.
• Do not create a task from an actively changing side chat without warning the user that the last assistant turn may be incomplete.
• Rollout writing is limited to the newly created thread, uses an exclusive file lock and fsync, validates all existing JSONL first, and verifies the result through app-server and Desktop Markdown before reporting success.

See protocol-and-recovery.md for the storage and API details.