claude-session-handoff

Recover a previous Claude Code session into a Codex handoff from local transcript files, without calling Claude in the normal path.

This is for the common failure mode where Claude Code hit a token limit, lost context, or the session ended, and you want Codex to continue from the local artifacts already on disk.

The repository ships both

• a bundled Codex skill inside the plugin package for direct skill installs
• a Codex plugin package for plugin-based installs and marketplace testing

What it does

• Finds recent local Claude sessions
• Shows a short numbered picker instead of guessing
• Resolves your choice from a saved snapshot, so the picked number stays stable
• Summarizes the selected transcript into a compact Codex handoff
• Stops after the handoff so you can decide what happens next

Why this exists

Claude Code can burn through token budget and session limits fast. When that happens, the practical need is simple. Continue the work in Codex without manually reconstructing the whole thread from scratch.

The default recovery pattern is usually manual and messy: find the right transcript, inspect it, reconstruct intent, then restate the open thread to another agent. This skill makes that path deterministic and cheap.

• No Claude token usage in the normal flow
• No dependency on the claude CLI
• Works from transcript artifacts already on your machine

Requirements

• Python 3.10+
• Codex CLI
• Local Claude session transcripts on disk

Install

Install as a Codex plugin

This is the preferred path if you want the plugin to show up in Codex's plugin flow.

From the repository root:

python3 scripts/install_plugin.py

If you prefer a copy instead of a symlink:

python3 scripts/install_plugin.py --mode copy

This installs the plugin into ~/plugins/claude-session-handoff and adds it to your personal Codex marketplace at ~/.agents/plugins/marketplace.json.

Then restart Codex and open /plugins.

If you invoke the bundled skill explicitly after plugin installation, Codex may show it in namespaced form.

• $claude-session-handoff:claude-session-handoff

Install as a plain skill

From the repository root:

python3 scripts/install_skill.py

If you prefer a copy instead of a symlink:

python3 scripts/install_skill.py --mode copy

Then restart Codex.

Manual install targets

• macOS/Linux: ~/.codex/skills/claude-session-handoff
• Windows: %USERPROFILE%\.codex\skills\claude-session-handoff

Use

After installation, prompts like these should trigger the skill

• Resume my last Claude session for this repo
• Recover a Claude Code session that ended and give me a handoff
• Find my last 5 Claude sessions and ask which one to resume

Explicit invocation depends on how you installed it

• plain skill install: $claude-session-handoff
• plugin install: $claude-session-handoff:claude-session-handoff
• natural-language prompts also work through implicit matching

Normal flow:

1. Discover recent local Claude sessions
2. Show a numbered picker
3. Summarize the selected session into a Codex handoff

Plugin packaging

The plugin package lives at

• plugins/claude-session-handoff

The installable skill that SkillsLLM and manual skill installs rely on lives at

• plugins/claude-session-handoff/skills/claude-session-handoff/SKILL.md

For repo-local testing, this repository also includes

• .agents/plugins/marketplace.json

That lets Codex surface the plugin when you open this repository locally. The current public Codex docs still describe the official global Plugin Directory publishing flow as coming soon, so the supported path today is local, personal, or repo marketplace installation.

Verify your setup

macOS/Linux:

python3 scripts/doctor.py --cwd "$PWD"

Windows PowerShell:

py -3 scripts/doctor.py --cwd (Get-Location)

The doctor reports

• whether the skill is installed into Codex
• which Claude directories were checked
• how many transcript files were found

Run the scripts directly

macOS/Linux:

python3 scripts/discover_sessions.py --cwd "$PWD" --limit 5 --picker
python3 scripts/discover_sessions.py --cwd "$PWD" --limit 5 --json --snapshot-out /tmp/claude-session-handoff-snapshot.json
python3 scripts/discover_sessions.py --snapshot-in /tmp/claude-session-handoff-snapshot.json --picker
python3 scripts/resolve_session_choice.py --snapshot /tmp/claude-session-handoff-snapshot.json --choice 1 --field file_path
python3 scripts/summarize_handoff.py --session /path/to/session.jsonl --json

Windows PowerShell:

$snapshot = Join-Path $env:TEMP "claude-session-handoff-snapshot.json"
py -3 scripts/discover_sessions.py --cwd (Get-Location) --limit 5 --picker
py -3 scripts/discover_sessions.py --cwd (Get-Location) --limit 5 --json --snapshot-out $snapshot
py -3 scripts/discover_sessions.py --snapshot-in $snapshot --picker
py -3 scripts/resolve_session_choice.py --snapshot $snapshot --choice 1 --field file_path
py -3 scripts/summarize_handoff.py --session C:\path\to\session.jsonl --json

How discovery works

Discovery checks these locations in order:

1. --claude-projects-dir
2. CLAUDE_PROJECTS_DIR
3. CLAUDE_HOME/projects
4. platform defaults in references/storage-locations.md

If your Claude data lives elsewhere, pass --claude-projects-dir.

Privacy and limits

• The normal path reads local transcript files only.
• The skill recovers a handoff, not Claude's exact internal state.
• It is best-effort and depends on Claude transcript formats staying close to the JSONL structures covered by the tests.
• Session selection still happens through normal Codex chat replies because this is a plain skill, not a custom UI.

Troubleshooting

If no sessions are found

• run scripts/doctor.py
• confirm Claude transcript files exist locally
• pass --claude-projects-dir if Claude stores data outside the default path

If the wrong session is selected

• run the discovery script directly and inspect the picker output
• invoke the skill from the repository you actually want to match

If a session file is missing or corrupted

• malformed transcripts are skipped when possible
• direct summarize_handoff.py calls return a file-specific error

Development

Run the test suite

python3 -m unittest discover -s tests -v

Verify the packaged skill bundle matches the checked-in source files:

python3 scripts/verify_packaged_skill.py

The repository includes:

• scripts/doctor.py for local diagnostics
• scripts/install_plugin.py for personal plugin installation
• .github/workflows/ci.yml for cross-platform CI
• agents/openai.yaml for packaged skill metadata
• plugins/claude-session-handoff/.codex-plugin/plugin.json for Codex plugin packaging

License

MIT