Session Handoff Skill

session-handoff is a Codex / Claude skill for recovering and transferring local AI coding-agent sessions when a conversation is interrupted by rate limits, account switching, window switching, or tool switching.

It uses continues to read local session files and export a structured handoff Markdown file. The receiving agent can then continue from the exported file instead of starting from scratch.

What It Solves

Common situation:

1. You are working in one Codex or Claude account.
2. The conversation hits a rate limit or runs out of quota.
3. You switch to another account, another window, or another tool.
4. The new session cannot see the previous chat context.

This skill turns the previous local session into a portable handoff file with:

• session overview
• current state
• recent conversation
• tool activity
• modified files, when available
• original session path
• a ready-to-paste continuation prompt

Repository Layout

.
├── README.md
├── CHANGELOG.md
├── VERSION
├── install.sh
├── scripts/
│   └── verify.sh
└── skill/
    └── session-handoff/
        ├── SKILL.md
        ├── agents/openai.yaml
        ├── references/continues-usage.md
        └── scripts/handoff.py

The runtime skill is only the skill/session-handoff/ folder. Documentation and release files stay outside the skill folder so the installed skill remains small.

Prerequisites

Install continues first:

npm install -g continues
continues --version

continues requires Node.js >=22.5.0. If your default Node is older, install a newer Node or create a wrapper that runs continues with a compatible Node binary.

You also need local session files from at least one supported tool, such as:

• Codex: ~/.codex/sessions/
• Claude Code: ~/.claude/projects/

Install

Clone the repository:

git clone https://github.com/SUNRNEHUI/session-handoff-skill.git
cd session-handoff-skill

Install for Codex:

./install.sh --codex

Install for both Codex and Claude:

./install.sh --all

The installer creates symlinks:

~/.codex/skills/session-handoff -> <repo>/skill/session-handoff
~/.claude/skills/session-handoff -> <repo>/skill/session-handoff

Using symlinks avoids drift between the Git checkout and installed skill.

Quick Start

Ask Codex or Claude:

帮我找另一个账号的最后一个 Codex 线程，生成交接文档

Or:

帮我找“修复某个 App 启动失败”那个线程，生成交接文档

The skill will search local sessions and export a Markdown file to:

~/Documents/Codex-Handoffs/

The output includes a continuation prompt like:

请先读取 <handoff.md>，按里面的 Current State、Recent Conversation、Tool Activity、Files Modified（如果有）、Session Origin 继续任务。不要从头开始。

Paste that prompt into the new account, window, or tool.

Manual Commands

List recent Codex sessions:

continues list --source codex -n 10

List recent Claude sessions:

continues list --source claude -n 10

Export the best matching Codex session by query:

python3 skill/session-handoff/scripts/handoff.py \
  --source codex \
  --query "app launch failure" \
  --preset standard

Export a known session by id:

python3 skill/session-handoff/scripts/handoff.py \
  --id <session-id> \
  --preset standard

Show matching candidates without writing a file:

python3 skill/session-handoff/scripts/handoff.py \
  --source codex \
  --query "app launch failure" \
  --show-candidates

Use a custom output directory:

python3 skill/session-handoff/scripts/handoff.py \
  --source claude \
  --query "my project" \
  --out-dir ~/Desktop

Presets

The skill passes these presets through to continues inspect:

Preset	Use case
minimal	urgent, low-token recovery
standard	default handoff
verbose	complex debugging or multi-file work
full	high-risk long task where context loss is costly

Validation

Each exported handoff is validated before the script reports success.

Required checks:

• file exists
• file is non-empty
• session id is present
• Session Overview exists
• Current State exists
• Recent Conversation exists
• Session Origin exists

At least one detail section must also exist:

• Tool Activity
• Files Modified

The command prints JSON with validation.ok: true when the handoff is structurally usable.

Test Example

This repository was tested with real local Codex sessions before release. The public repository intentionally does not include raw session files, generated handoff files, or real local session ids.

Verification method:

1. Export with the skill script.
2. Export the same session with raw continues inspect.
3. Compare the two files with cmp.

Expected result:

cmp_exit=0

This proves the skill wrapper preserves the original continues output.

Privacy and Safety

The skill reads local session files. It does not upload session content by itself.

Be careful before publishing or pasting generated handoff files. They may contain:

• local file paths
• recent prompts
• shell commands
• excerpts of tool output
• sensitive project context

Prefer sharing the handoff file path with a local agent instead of pasting the full file into chat.

Troubleshooting

continues not found

npm install -g continues

continues complains about Node version

Install Node.js >=22.5.0, or create a wrapper that runs continues with a newer Node binary.

No matching session found

Try a broader query:

python3 skill/session-handoff/scripts/handoff.py --source codex --query app

Or list candidates:

python3 skill/session-handoff/scripts/handoff.py --source codex --show-candidates

The handoff differs from an older exported file

That usually means the source session kept receiving new turns. A handoff file is a snapshot of the source session at export time.

Development

Run verification:

./scripts/verify.sh

The verification checks:

• skill metadata validity
• Python syntax
• candidate search
• real handoff export against local sessions when available

License

MIT