Session Handoff

note: this project was prototyped rapidly (in about 15 minutes) by gpt-5.6-sol. use at your own discretion.

Continue a coding task in another coding agent by pointing it to the previous agent's session file.

Supported agents:

• Claude Code
• Codex CLI
• Cursor
• Pi

Session Handoff does not summarize the conversations. It only searches for the file path of latest coding session transcript belonging to the current working directory.

Install

uv tool install session-handoff
# or
pipx install session-handoff

From a local checkout:

uv tool install .

Use

Run handoff inside the project you want to continue:

# Launch Codex with the latest Claude Code session.
handoff claude codex

# Print the prompt instead of launching the destination.
handoff claude codex --prompt

# All directions are supported.
handoff codex pi
handoff pi claude
handoff cursor codex
handoff claude cursor

The generated prompt is:

Read the previous coding session at <path>, understand the task, inspect the current working directory, and continue from where the previous agent stopped.
Ask clarifying questions if required.

Session selection

Handoff matches the current working directory against metadata in each agent's local history and chooses the matching file with the newest modification time.

It fails when no session matches the current directory.

Native location overrides are supported:

• CLAUDE_CONFIG_DIR
• CODEX_HOME
• CURSOR_DATA_DIR
• PI_CODING_AGENT_SESSION_DIR
• PI_CODING_AGENT_DIR

Development

Run the tests:

PYTHONPATH=src python -m unittest discover -s tests -v