Metadata-Version: 2.4
Name: session-handoff
Version: 0.1.1
Summary: Continue a coding-agent session in Claude Code, Codex, Cursor, or Pi
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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

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

From a local checkout:

```bash
uv tool install .
```

## Use

Run `handoff` inside the project you want to continue:

```bash
# 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:

```text
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.

| Agent | Default history location |
| --- | --- |
| Claude Code | `~/.claude/projects/*/*.jsonl` |
| Codex | `~/.codex/sessions/**/rollout-*.jsonl` |
| Cursor | `~/.cursor/projects/*/agent-transcripts/*/*.jsonl` |
| Pi | `~/.pi/agent/sessions/**/*.jsonl` |

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:

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

