Codex Thread Handoff

Codex Thread Handoff is an OpenAI Codex skill for recovering stuck Codex threads after context compaction failures, stream disconnects, or reconnect loops. It creates a safe handoff prompt so a new Codex thread can continue from the real repository state instead of relying on a broken transcript.

This project helps with common Codex recovery searches such as Codex thread recovery, Codex compact failure, responses/compact, stream disconnected before completion, error sending request for url, reconnecting 5/5, stuck Codex session, and context compaction handoff.

中文：thread-handoff 是一个 OpenAI Codex skill，用于在 Codex 线程因为上下文压缩失败、断流或重连失败而无法继续时，快速生成中文接力信息，让新线程从仓库真实状态继续工作。

Problems It Handles

responses/compact
stream disconnected before completion
compact failed
compaction failed
正在重新连接5/5
正在重新连接 5/5
reconnecting 5/5
error sending request for url

Features

• Scans recent Codex compact, stream disconnect, and reconnect failure candidates.
• Collects current Git repository state, branch, diff summary, changed files, and relevant AGENTS.md files.
• Generates a Chinese Markdown handoff prompt that can be pasted into a new Codex thread.
• Read-only by design: no workspace edits, no network calls, no paid API calls.
• Works globally when installed under ~/.codex/skills/thread-handoff.

Who It Is For

• Developers who run multiple Codex sessions in parallel and need to identify likely failed threads.
• Codex users who see responses/compact, stream disconnected before completion, or 正在重新连接 5/5.
• AI coding agent workflows that need a clean handoff from a stuck thread to a fresh thread.
• Teams that want recovery prompts grounded in git status, git diff, project instructions, and planning files.

Installation

Install as a global Codex skill:

mkdir -p ~/.codex/skills
git clone https://github.com/RyanWeb31110/codex-thread-handoff.git ~/.codex/skills/thread-handoff

Restart or open a new Codex session, then search for or invoke thread-handoff.

Usage

Scan recent failure candidates:

bash ~/.codex/skills/thread-handoff/scripts/find-compact-failures.sh

Scan a longer window:

bash ~/.codex/skills/thread-handoff/scripts/find-compact-failures.sh --hours 72

Emit machine-readable JSON for automation:

bash ~/.codex/skills/thread-handoff/scripts/find-compact-failures.sh --json

Generate a handoff prompt from a repository root:

bash ~/.codex/skills/thread-handoff/scripts/collect-handoff.sh "Continue the original stuck Codex thread goal"

中文示例：

bash ~/.codex/skills/thread-handoff/scripts/collect-handoff.sh "继续原线程目标"

Recovery Workflow

1. Run the failure scanner to find likely compact or stream disconnect candidates.
2. Run the handoff collector in the affected repository.
3. Paste the generated Markdown into a new Codex thread.
4. Ask the new thread to read repository state first: AGENTS.md, git status, git diff, and relevant planning files.
5. Continue implementation from the working tree, not from assumptions about the old chat.

Documentation

• Use cases
• FAQ
• llms.txt

Safety Notes

• Results are best-effort candidates and may not uniquely identify the failed thread.
• Logs and transcripts may contain sensitive information. Review snippets before sharing.
• This skill never retries failed paid generation calls or paid API calls.
• It does not revert, stash, reset, clean, or overwrite your working tree.

Keywords

OpenAI Codex, Codex skill, Codex thread handoff, Codex recovery, Codex compact failure, responses/compact, stream disconnected, reconnecting 5/5, context compaction, stuck Codex thread, AI coding agent recovery, developer productivity, Git working tree handoff.

License

MIT