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