session-handoff 0.1.0__tar.gz

session_handoff-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include tests/fixtures *.jsonl

session_handoff-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: session-handoff
+Version: 0.1.0
+Summary: Continue a coding-agent session in Claude Code, Codex, 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
+- 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
+```
+
+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` |
+| Pi | `~/.pi/agent/sessions/**/*.jsonl` |
+
+It fails when no session matches the current directory.
+
+Native location overrides are supported:
+
+- `CLAUDE_CONFIG_DIR`
+- `CODEX_HOME`
+- `PI_CODING_AGENT_SESSION_DIR`
+- `PI_CODING_AGENT_DIR`
+
+## Development
+
+Run the tests:
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -v
+```
+

session_handoff-0.1.0/README.md

@@ -0,0 +1,78 @@
+# 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
+- 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
+```
+
+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` |
+| Pi | `~/.pi/agent/sessions/**/*.jsonl` |
+
+It fails when no session matches the current directory.
+
+Native location overrides are supported:
+
+- `CLAUDE_CONFIG_DIR`
+- `CODEX_HOME`
+- `PI_CODING_AGENT_SESSION_DIR`
+- `PI_CODING_AGENT_DIR`
+
+## Development
+
+Run the tests:
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -v
+```
+

session_handoff-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "session-handoff"
+version = "0.1.0"
+description = "Continue a coding-agent session in Claude Code, Codex, or Pi"
+readme = "README.md"
+requires-python = ">=3.10"
+
+[project.scripts]
+handoff = "handoff_cli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

session_handoff-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

session_handoff-0.1.0/src/handoff_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Handoff coding-agent sessions by passing their local path."""
+
+__version__ = "0.1.0"

session_handoff-0.1.0/src/handoff_cli/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

session_handoff-0.1.0/src/handoff_cli/agents.py

@@ -0,0 +1,22 @@
+"""Agent names and destination launch metadata."""
+
+from __future__ import annotations
+
+from .models import Agent, AgentId
+
+AGENTS: dict[AgentId, Agent] = {
+    "claude": Agent(id="claude", display_name="Claude Code", executable="claude"),
+    "codex": Agent(id="codex", display_name="Codex", executable="codex"),
+    "pi": Agent(id="pi", display_name="Pi", executable="pi"),
+}
+
+
+def get_agent(agent_id: str) -> Agent:
+    """Return an agent or raise a user-facing ValueError."""
+    try:
+        return AGENTS[agent_id]  # type: ignore[index]
+    except KeyError as error:
+        supported = ", ".join(AGENTS)
+        raise ValueError(
+            f"Unknown agent {agent_id!r}. Supported agents: {supported}."
+        ) from error

session_handoff-0.1.0/src/handoff_cli/cli.py

@@ -0,0 +1,110 @@
+"""Command-line entry point for Handoff."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import TextIO
+
+from .agents import AGENTS
+from .launcher import DestinationNotFoundError, launch_destination
+from .models import AgentId
+from .paths import canonical_path
+from .prompt import render_prompt
+from .sources import make_locator
+
+
+def package_version() -> str:
+    try:
+        return version("session-handoff")
+    except PackageNotFoundError:
+        return "0.1.0"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="handoff",
+        description=(
+            "Continue the latest project session from Claude Code, Codex, or Pi "
+            "in another agent."
+        ),
+        epilog=(
+            "Examples:\n"
+            "  handoff claude codex\n"
+            "  handoff pi claude --prompt\n"
+            "  handoff codex pi --prompt | pbcopy"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("source", choices=tuple(AGENTS), help="agent to hand off from")
+    parser.add_argument(
+        "destination", choices=tuple(AGENTS), help="agent to hand off to"
+    )
+    parser.add_argument(
+        "--prompt",
+        action="store_true",
+        dest="print_prompt",
+        help="print the handoff prompt instead of launching the destination",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {package_version()}"
+    )
+    return parser
+
+
+def run(
+    argv: Sequence[str] | None = None,
+    *,
+    cwd: Path | None = None,
+    environ: Mapping[str, str] | None = None,
+    stdout: TextIO | None = None,
+    stderr: TextIO | None = None,
+    launch: Callable[[AgentId, str, Path], int] = launch_destination,
+) -> int:
+    args = build_parser().parse_args(argv)
+    output = sys.stdout if stdout is None else stdout
+    errors = sys.stderr if stderr is None else stderr
+    environment = os.environ if environ is None else environ
+
+    try:
+        working_directory = canonical_path(Path.cwd() if cwd is None else cwd)
+        source: AgentId = args.source
+        destination: AgentId = args.destination
+        locator = make_locator(source, environ=environment)
+        artifact = locator.find_latest_for_cwd(working_directory)
+        if artifact is None:
+            display_name = AGENTS[source].display_name
+            raise RuntimeError(
+                f"No {display_name} session was found for:\n"
+                f"{working_directory}\n\n"
+                "Handoff will not use a session from another working directory."
+            )
+
+        # Opening the file catches stale paths and unreadable stores before the
+        # destination starts. Reading one byte does not load the transcript.
+        try:
+            with artifact.path.open("rb") as stream:
+                stream.read(1)
+        except OSError as error:
+            raise RuntimeError(
+                f"The session file is not readable: {artifact.path}\n{error}"
+            ) from error
+
+        prompt = render_prompt(artifact)
+        if args.print_prompt:
+            output.write(prompt)
+            output.write("\n")
+            return 0
+
+        return launch(destination, prompt, working_directory)
+    except (DestinationNotFoundError, RuntimeError, ValueError) as error:
+        errors.write(f"handoff: error: {error}\n")
+        return 1
+
+
+def main() -> None:
+    raise SystemExit(run())

session_handoff-0.1.0/src/handoff_cli/launcher.py

@@ -0,0 +1,41 @@
+"""Shell-free destination process launching."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from .agents import AGENTS
+from .models import AgentId
+
+
+class DestinationNotFoundError(RuntimeError):
+    pass
+
+
+def launch_destination(destination: AgentId, prompt: str, cwd: Path) -> int:
+    """Launch a destination with inherited terminal streams and return its code."""
+    agent = AGENTS[destination]
+    executable = shutil.which(agent.executable)
+    if executable is None:
+        raise DestinationNotFoundError(
+            f"Cannot launch {agent.display_name}: {agent.executable!r} was not found "
+            "on PATH. Install it or use --prompt."
+        )
+
+    try:
+        completed = subprocess.run(
+            [executable, prompt],
+            cwd=cwd,
+            check=False,
+        )
+    except KeyboardInterrupt:
+        return 130
+    except OSError as error:
+        raise RuntimeError(f"Could not launch {agent.display_name}: {error}") from error
+
+    # Shell convention for a child terminated by a signal.
+    if completed.returncode < 0:
+        return 128 + abs(completed.returncode)
+    return completed.returncode

session_handoff-0.1.0/src/handoff_cli/models.py

@@ -0,0 +1,25 @@
+"""Small shared data types for Handoff."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+AgentId = Literal["claude", "codex", "pi"]
+
+
+@dataclass(frozen=True)
+class Agent:
+    id: AgentId
+    display_name: str
+    executable: str
+
+
+@dataclass(frozen=True)
+class SessionArtifact:
+    agent: AgentId
+    path: Path
+    cwd: Path
+    session_id: str | None
+    modified_at: float

session_handoff-0.1.0/src/handoff_cli/paths.py

@@ -0,0 +1,20 @@
+"""Filesystem path helpers."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def canonical_path(path: str | os.PathLike[str]) -> Path:
+    """Return a normalized absolute path, resolving existing symlinks.
+
+    ``strict=False`` keeps this useful for metadata referring to a path that has
+    since moved, while ``normcase`` makes comparisons correct on Windows.
+    """
+    expanded = Path(path).expanduser().resolve(strict=False)
+    return Path(os.path.normcase(str(expanded)))
+
+
+def same_path(left: str | os.PathLike[str], right: str | os.PathLike[str]) -> bool:
+    return canonical_path(left) == canonical_path(right)

session_handoff-0.1.0/src/handoff_cli/prompt.py

@@ -0,0 +1,13 @@
+"""Render the prompt passed to the destination agent."""
+
+from __future__ import annotations
+
+from .models import SessionArtifact
+
+
+def render_prompt(artifact: SessionArtifact) -> str:
+    return (
+        f"Read the previous coding session at {artifact.path}, understand the task, "
+        "inspect the current working directory, and continue from where the previous "
+        "agent stopped.\nAsk clarifying questions if required."
+    )

session_handoff-0.1.0/src/handoff_cli/sources/__init__.py

@@ -0,0 +1,35 @@
+"""Read-only locators for supported agent session stores."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+
+from ..models import AgentId
+from .base import SourceLocator
+from .claude import ClaudeLocator
+from .codex import CodexLocator
+from .pi import PiLocator
+
+
+def make_locator(
+    agent: AgentId,
+    *,
+    environ: Mapping[str, str] | None = None,
+    home: Path | None = None,
+) -> SourceLocator:
+    locators = {
+        "claude": ClaudeLocator,
+        "codex": CodexLocator,
+        "pi": PiLocator,
+    }
+    return locators[agent](environ=environ, home=home)
+
+
+__all__ = [
+    "ClaudeLocator",
+    "CodexLocator",
+    "PiLocator",
+    "SourceLocator",
+    "make_locator",
+]

session_handoff-0.1.0/src/handoff_cli/sources/base.py

@@ -0,0 +1,63 @@
+"""Shared source-locator helpers."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterable, Iterator, Mapping
+from pathlib import Path
+from typing import Any
+
+from ..models import SessionArtifact
+
+# Metadata appears near the beginning of all supported formats. The limits keep
+# one malformed or unexpected file from making discovery expensive.
+MAX_METADATA_LINES = 512
+MAX_METADATA_BYTES = 64 * 1024 * 1024
+
+
+class SourceLocator:
+    """Base class for a read-only session locator."""
+
+    def find_latest_for_cwd(self, cwd: Path) -> SessionArtifact | None:
+        raise NotImplementedError
+
+
+def environment_path(environ: Mapping[str, str], name: str, default: Path) -> Path:
+    value = environ.get(name)
+    return Path(value).expanduser() if value else default
+
+
+def json_records(
+    path: Path,
+    *,
+    max_lines: int = MAX_METADATA_LINES,
+    max_bytes: int = MAX_METADATA_BYTES,
+) -> Iterator[dict[str, Any]]:
+    """Yield bounded JSON-object records, skipping malformed lines."""
+    consumed = 0
+    try:
+        with path.open("rb") as stream:
+            for index, raw_line in enumerate(stream):
+                if index >= max_lines:
+                    return
+                consumed += len(raw_line)
+                if consumed > max_bytes:
+                    return
+                try:
+                    value = json.loads(raw_line)
+                except (json.JSONDecodeError, UnicodeDecodeError):
+                    continue
+                if isinstance(value, dict):
+                    yield value
+    except (OSError, ValueError):
+        return
+
+
+def newest(candidates: Iterable[SessionArtifact]) -> SessionArtifact | None:
+    """Choose deterministically by mtime, then path."""
+    return max(
+        candidates,
+        key=lambda item: (item.modified_at, os.fspath(item.path)),
+        default=None,
+    )

session_handoff-0.1.0/src/handoff_cli/sources/claude.py

@@ -0,0 +1,91 @@
+"""Locate Claude Code project sessions."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator, Mapping
+from pathlib import Path
+from typing import Any
+
+from ..models import SessionArtifact
+from ..paths import canonical_path, same_path
+from .base import SourceLocator, json_records, newest
+
+
+class ClaudeLocator(SourceLocator):
+    def __init__(
+        self,
+        *,
+        root: Path | None = None,
+        environ: Mapping[str, str] | None = None,
+        home: Path | None = None,
+    ) -> None:
+        self.environ = os.environ if environ is None else environ
+        user_home = Path.home() if home is None else home
+        if root is not None:
+            self.root = root
+        elif config_dir := self.environ.get("CLAUDE_CONFIG_DIR"):
+            self.root = Path(config_dir).expanduser() / "projects"
+        else:
+            self.root = user_home / ".claude" / "projects"
+
+    def find_latest_for_cwd(self, cwd: Path) -> SessionArtifact | None:
+        expected_cwd = canonical_path(cwd)
+        candidates: list[SessionArtifact] = []
+        for path in self._session_files(expected_cwd):
+            metadata = self._metadata(path)
+            if metadata is None or not same_path(metadata["cwd"], expected_cwd):
+                continue
+            try:
+                modified_at = path.stat().st_mtime
+            except OSError:
+                continue
+            candidates.append(
+                SessionArtifact(
+                    agent="claude",
+                    path=path.resolve(strict=False),
+                    cwd=expected_cwd,
+                    session_id=metadata.get("session_id") or path.stem,
+                    modified_at=modified_at,
+                )
+            )
+        return newest(candidates)
+
+    def _session_files(self, cwd: Path) -> Iterator[Path]:
+        if not self.root.is_dir():
+            return
+
+        # Claude currently encodes a project path by replacing separators with
+        # hyphens. Check that directory first for speed, but validate the cwd
+        # stored inside every file and scan other directories as a fallback.
+        encoded = str(cwd).replace("\\", "-").replace("/", "-")
+        preferred = self.root / encoded
+        directories: list[Path] = []
+        if preferred.is_dir():
+            directories.append(preferred)
+        try:
+            directories.extend(
+                child
+                for child in self.root.iterdir()
+                if child.is_dir() and child != preferred
+            )
+        except OSError:
+            pass
+
+        for directory in directories:
+            try:
+                yield from directory.glob("*.jsonl")
+            except OSError:
+                continue
+
+    @staticmethod
+    def _metadata(path: Path) -> dict[str, Any] | None:
+        session_id: str | None = None
+        for record in json_records(path):
+            value = record.get("sessionId") or record.get("session_id")
+            if isinstance(value, str) and value:
+                session_id = value
+            recorded_cwd = record.get("cwd")
+            if isinstance(recorded_cwd, str) and recorded_cwd:
+                return {"cwd": recorded_cwd, "session_id": session_id}
+        return None

session_handoff-0.1.0/src/handoff_cli/sources/codex.py

@@ -0,0 +1,76 @@
+"""Locate Codex rollout sessions."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator, Mapping
+from pathlib import Path
+from typing import Any
+
+from ..models import SessionArtifact
+from ..paths import canonical_path, same_path
+from .base import SourceLocator, json_records, newest
+
+
+class CodexLocator(SourceLocator):
+    def __init__(
+        self,
+        *,
+        root: Path | None = None,
+        environ: Mapping[str, str] | None = None,
+        home: Path | None = None,
+    ) -> None:
+        self.environ = os.environ if environ is None else environ
+        user_home = Path.home() if home is None else home
+        if root is not None:
+            self.root = root
+        elif codex_home := self.environ.get("CODEX_HOME"):
+            self.root = Path(codex_home).expanduser() / "sessions"
+        else:
+            self.root = user_home / ".codex" / "sessions"
+
+    def find_latest_for_cwd(self, cwd: Path) -> SessionArtifact | None:
+        expected_cwd = canonical_path(cwd)
+        candidates: list[SessionArtifact] = []
+        for path in self._session_files():
+            metadata = self._metadata(path)
+            if metadata is None or not same_path(metadata["cwd"], expected_cwd):
+                continue
+            try:
+                modified_at = path.stat().st_mtime
+            except OSError:
+                continue
+            candidates.append(
+                SessionArtifact(
+                    agent="codex",
+                    path=path.resolve(strict=False),
+                    cwd=expected_cwd,
+                    session_id=metadata.get("session_id"),
+                    modified_at=modified_at,
+                )
+            )
+        return newest(candidates)
+
+    def _session_files(self) -> Iterator[Path]:
+        if not self.root.is_dir():
+            return
+        for directory, _, filenames in os.walk(self.root):
+            for filename in filenames:
+                if filename.startswith("rollout-") and filename.endswith(".jsonl"):
+                    yield Path(directory) / filename
+
+    @staticmethod
+    def _metadata(path: Path) -> dict[str, Any] | None:
+        for record in json_records(path):
+            if record.get("type") != "session_meta":
+                continue
+            payload = record.get("payload")
+            if not isinstance(payload, dict):
+                continue
+            recorded_cwd = payload.get("cwd")
+            if not isinstance(recorded_cwd, str) or not recorded_cwd:
+                return None
+            value = payload.get("id") or payload.get("session_id")
+            session_id = value if isinstance(value, str) and value else None
+            return {"cwd": recorded_cwd, "session_id": session_id}
+        return None

session_handoff-0.1.0/src/handoff_cli/sources/pi.py

@@ -0,0 +1,74 @@
+"""Locate Pi JSONL sessions."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator, Mapping
+from pathlib import Path
+from typing import Any
+
+from ..models import SessionArtifact
+from ..paths import canonical_path, same_path
+from .base import SourceLocator, json_records, newest
+
+
+class PiLocator(SourceLocator):
+    def __init__(
+        self,
+        *,
+        root: Path | None = None,
+        environ: Mapping[str, str] | None = None,
+        home: Path | None = None,
+    ) -> None:
+        self.environ = os.environ if environ is None else environ
+        user_home = Path.home() if home is None else home
+        if root is not None:
+            self.root = root
+        elif session_dir := self.environ.get("PI_CODING_AGENT_SESSION_DIR"):
+            self.root = Path(session_dir).expanduser()
+        elif agent_dir := self.environ.get("PI_CODING_AGENT_DIR"):
+            self.root = Path(agent_dir).expanduser() / "sessions"
+        else:
+            self.root = user_home / ".pi" / "agent" / "sessions"
+
+    def find_latest_for_cwd(self, cwd: Path) -> SessionArtifact | None:
+        expected_cwd = canonical_path(cwd)
+        candidates: list[SessionArtifact] = []
+        for path in self._session_files():
+            metadata = self._metadata(path)
+            if metadata is None or not same_path(metadata["cwd"], expected_cwd):
+                continue
+            try:
+                modified_at = path.stat().st_mtime
+            except OSError:
+                continue
+            candidates.append(
+                SessionArtifact(
+                    agent="pi",
+                    path=path.resolve(strict=False),
+                    cwd=expected_cwd,
+                    session_id=metadata.get("session_id"),
+                    modified_at=modified_at,
+                )
+            )
+        return newest(candidates)
+
+    def _session_files(self) -> Iterator[Path]:
+        if not self.root.is_dir():
+            return
+        for directory, _, filenames in os.walk(self.root):
+            for filename in filenames:
+                if filename.endswith(".jsonl"):
+                    yield Path(directory) / filename
+
+    @staticmethod
+    def _metadata(path: Path) -> dict[str, Any] | None:
+        record = next(json_records(path, max_lines=1), None)
+        if record is None or record.get("type") != "session":
+            return None
+        recorded_cwd = record.get("cwd")
+        if not isinstance(recorded_cwd, str) or not recorded_cwd:
+            return None
+        value = record.get("id")
+        session_id = value if isinstance(value, str) and value else None
+        return {"cwd": recorded_cwd, "session_id": session_id}

session_handoff-0.1.0/src/session_handoff.egg-info/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: session-handoff
+Version: 0.1.0
+Summary: Continue a coding-agent session in Claude Code, Codex, 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
+- 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
+```
+
+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` |
+| Pi | `~/.pi/agent/sessions/**/*.jsonl` |
+
+It fails when no session matches the current directory.
+
+Native location overrides are supported:
+
+- `CLAUDE_CONFIG_DIR`
+- `CODEX_HOME`
+- `PI_CODING_AGENT_SESSION_DIR`
+- `PI_CODING_AGENT_DIR`
+
+## Development
+
+Run the tests:
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -v
+```
+

session_handoff-0.1.0/src/session_handoff.egg-info/SOURCES.txt

@@ -0,0 +1,26 @@
+MANIFEST.in
+README.md
+pyproject.toml
+src/handoff_cli/__init__.py
+src/handoff_cli/__main__.py
+src/handoff_cli/agents.py
+src/handoff_cli/cli.py
+src/handoff_cli/launcher.py
+src/handoff_cli/models.py
+src/handoff_cli/paths.py
+src/handoff_cli/prompt.py
+src/handoff_cli/sources/__init__.py
+src/handoff_cli/sources/base.py
+src/handoff_cli/sources/claude.py
+src/handoff_cli/sources/codex.py
+src/handoff_cli/sources/pi.py
+src/session_handoff.egg-info/PKG-INFO
+src/session_handoff.egg-info/SOURCES.txt
+src/session_handoff.egg-info/dependency_links.txt
+src/session_handoff.egg-info/entry_points.txt
+src/session_handoff.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_sources.py
+tests/fixtures/claude/session.jsonl
+tests/fixtures/codex/session.jsonl
+tests/fixtures/pi/session.jsonl

session_handoff-0.1.0/src/session_handoff.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

session_handoff-0.1.0/src/session_handoff.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+handoff = handoff_cli.cli:main

session_handoff-0.1.0/src/session_handoff.egg-info/top_level.txt

@@ -0,0 +1 @@
+handoff_cli

session_handoff-0.1.0/tests/fixtures/claude/session.jsonl

@@ -0,0 +1,3 @@
+{"type":"mode","sessionId":"claude-session"}
+{"type":"user","sessionId":"claude-session","cwd":"__CWD__","uuid":"user-1","parentUuid":null,"message":{"role":"user","content":"Sanitized fixture task"}}
+{"type":"assistant","sessionId":"claude-session","cwd":"__CWD__","uuid":"assistant-1","parentUuid":"user-1","message":{"role":"assistant","content":[{"type":"text","text":"Sanitized fixture response"}]}}

session_handoff-0.1.0/tests/fixtures/codex/session.jsonl

@@ -0,0 +1,2 @@
+{"timestamp":"2026-01-01T00:00:00Z","type":"session_meta","payload":{"id":"codex-session","cwd":"__CWD__","cli_version":"0.0.0-fixture","source":"cli"}}
+{"timestamp":"2026-01-01T00:00:01Z","type":"event_msg","payload":{"type":"user_message","message":"Sanitized fixture task"}}

session_handoff-0.1.0/tests/fixtures/pi/session.jsonl

@@ -0,0 +1,2 @@
+{"type":"session","version":3,"id":"pi-session","timestamp":"2026-01-01T00:00:00Z","cwd":"__CWD__"}
+{"type":"message","id":"abcd1234","parentId":null,"timestamp":"2026-01-01T00:00:01Z","message":{"role":"user","content":"Sanitized fixture task","timestamp":1767225601000}}

session_handoff-0.1.0/tests/test_cli.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import io
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from handoff_cli.cli import run
+from handoff_cli.launcher import DestinationNotFoundError, launch_destination
+from handoff_cli.models import SessionArtifact
+from handoff_cli.prompt import render_prompt
+
+from test_sources import fixture, write
+
+
+class CliTests(unittest.TestCase):
+    def make_environment(self, root: Path, cwd: Path) -> dict[str, str]:
+        claude_config = root / "claude"
+        codex_home = root / "codex"
+        pi_sessions = root / "pi"
+        write(
+            claude_config / "projects" / "project" / "claude.jsonl",
+            fixture("claude", cwd),
+            mtime=10,
+        )
+        write(
+            codex_home / "sessions" / "2026" / "01" / "rollout-codex.jsonl",
+            fixture("codex", cwd),
+            mtime=10,
+        )
+        write(pi_sessions / "project" / "pi.jsonl", fixture("pi", cwd), mtime=10)
+        return {
+            "CLAUDE_CONFIG_DIR": str(claude_config),
+            "CODEX_HOME": str(codex_home),
+            "PI_CODING_AGENT_SESSION_DIR": str(pi_sessions),
+        }
+
+    def test_prompt_mode_prints_only_prompt_and_does_not_launch(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            cwd = root / "project with spaces"
+            cwd.mkdir()
+            environment = self.make_environment(root, cwd)
+            stdout = io.StringIO()
+            stderr = io.StringIO()
+
+            def should_not_launch(*_args: object) -> int:
+                self.fail("prompt mode launched a destination")
+
+            result = run(
+                ["claude", "codex", "--prompt"],
+                cwd=cwd,
+                environ=environment,
+                stdout=stdout,
+                stderr=stderr,
+                launch=should_not_launch,
+            )
+
+            self.assertEqual(result, 0)
+            self.assertEqual(stderr.getvalue(), "")
+            self.assertTrue(stdout.getvalue().endswith("\n"))
+            self.assertIn("Read the previous coding session at", stdout.getvalue())
+            self.assertIn("claude.jsonl", stdout.getvalue())
+            self.assertIn("Ask clarifying questions if required.", stdout.getvalue())
+            self.assertNotIn("Sanitized fixture task", stdout.getvalue())
+
+    def test_all_nine_routes_use_one_prompt_argument_and_same_cwd(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            cwd = root / "project"
+            cwd.mkdir()
+            environment = self.make_environment(root, cwd)
+
+            for source in ("claude", "codex", "pi"):
+                for destination in ("claude", "codex", "pi"):
+                    with self.subTest(source=source, destination=destination):
+                        calls: list[tuple[str, str, Path]] = []
+
+                        def fake_launch(
+                            agent: str, prompt: str, launch_cwd: Path
+                        ) -> int:
+                            calls.append((agent, prompt, launch_cwd))
+                            return 23
+
+                        result = run(
+                            [source, destination],
+                            cwd=cwd,
+                            environ=environment,
+                            stdout=io.StringIO(),
+                            stderr=io.StringIO(),
+                            launch=fake_launch,  # type: ignore[arg-type]
+                        )
+
+                        self.assertEqual(result, 23)
+                        self.assertEqual(len(calls), 1)
+                        self.assertEqual(calls[0][0], destination)
+                        self.assertEqual(calls[0][2], cwd.resolve())
+                        self.assertIn("Read the previous coding session", calls[0][1])
+
+    def test_missing_project_session_fails_without_launching(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            cwd = root / "project"
+            cwd.mkdir()
+            errors = io.StringIO()
+
+            result = run(
+                ["claude", "codex"],
+                cwd=cwd,
+                environ={"CLAUDE_CONFIG_DIR": str(root / "missing")},
+                stdout=io.StringIO(),
+                stderr=errors,
+                launch=lambda *_: self.fail("destination launched"),
+            )
+
+            self.assertEqual(result, 1)
+            self.assertIn("No Claude Code session was found", errors.getvalue())
+            self.assertIn("will not use a session from another", errors.getvalue())
+
+    def test_destination_error_is_distinct(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            cwd = root / "project"
+            cwd.mkdir()
+            environment = self.make_environment(root, cwd)
+            errors = io.StringIO()
+
+            def missing_destination(*_args: object) -> int:
+                raise DestinationNotFoundError("codex was not found on PATH")
+
+            result = run(
+                ["pi", "codex"],
+                cwd=cwd,
+                environ=environment,
+                stdout=io.StringIO(),
+                stderr=errors,
+                launch=missing_destination,
+            )
+
+            self.assertEqual(result, 1)
+            self.assertIn("codex was not found on PATH", errors.getvalue())
+            self.assertNotIn("No Pi session", errors.getvalue())
+
+
+class PromptTests(unittest.TestCase):
+    def test_prompt_contains_path_not_transcript_and_handles_quotes(self) -> None:
+        cwd = Path('/tmp/a project with "quotes"')
+        session = cwd / "session's file.jsonl"
+        artifact = SessionArtifact(
+            agent="pi",
+            path=session,
+            cwd=cwd,
+            session_id="fixture",
+            modified_at=1,
+        )
+
+        prompt = render_prompt(artifact)
+
+        self.assertEqual(
+            prompt,
+            f"Read the previous coding session at {session}, understand the task, "
+            "inspect the current working directory, and continue from where the "
+            "previous agent stopped.\nAsk clarifying questions if required.",
+        )
+
+
+class LauncherTests(unittest.TestCase):
+    @patch("handoff_cli.launcher.subprocess.run")
+    @patch("handoff_cli.launcher.shutil.which", return_value="/tools/codex")
+    def test_launcher_uses_argv_without_a_shell(
+        self, _which: object, run_process: object
+    ) -> None:
+        mocked = run_process
+        mocked.return_value = subprocess.CompletedProcess([], 17)  # type: ignore[attr-defined]
+        cwd = Path('/tmp/project with "quotes"')
+        prompt = "one argument with spaces, 'quotes', and $shell syntax"
+
+        result = launch_destination("codex", prompt, cwd)
+
+        self.assertEqual(result, 17)
+        mocked.assert_called_once_with(  # type: ignore[attr-defined]
+            ["/tools/codex", prompt], cwd=cwd, check=False
+        )
+
+    @patch("handoff_cli.launcher.shutil.which", return_value=None)
+    def test_missing_executable_suggests_prompt_mode(self, _which: object) -> None:
+        with self.assertRaisesRegex(DestinationNotFoundError, "--prompt"):
+            launch_destination("codex", "prompt", Path("/tmp"))
+
+
+if __name__ == "__main__":
+    unittest.main()

session_handoff-0.1.0/tests/test_sources.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import os
+import tempfile
+import unittest
+from pathlib import Path
+
+from handoff_cli.sources.claude import ClaudeLocator
+from handoff_cli.sources.codex import CodexLocator
+from handoff_cli.sources.pi import PiLocator
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def fixture(agent: str, cwd: Path) -> str:
+    text = (FIXTURES / agent / "session.jsonl").read_text(encoding="utf-8")
+    return text.replace("__CWD__", str(cwd).replace("\\", "\\\\"))
+
+
+def write(path: Path, content: str, *, mtime: float) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    os.utime(path, (mtime, mtime))
+    return path
+
+
+class ClaudeLocatorTests(unittest.TestCase):
+    def test_selects_newest_root_session_and_ignores_newer_subagent(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            cwd = root / "project"
+            cwd.mkdir()
+            project = root / "claude" / str(cwd).replace("/", "-")
+            older = write(project / "older.jsonl", fixture("claude", cwd), mtime=10)
+            latest = write(project / "latest.jsonl", fixture("claude", cwd), mtime=20)
+            write(
+                project / "latest" / "subagents" / "agent-newer.jsonl",
+                fixture("claude", cwd),
+                mtime=30,
+            )
+
+            found = ClaudeLocator(root=root / "claude").find_latest_for_cwd(cwd)
+
+            self.assertIsNotNone(found)
+            assert found is not None
+            self.assertEqual(found.path, latest.resolve())
+            self.assertNotEqual(found.path, older.resolve())
+            self.assertEqual(found.session_id, "claude-session")
+
+    def test_rejects_globally_newer_session_from_another_cwd(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            cwd = root / "project"
+            other = root / "other"
+            cwd.mkdir()
+            other.mkdir()
+            write(
+                root / "claude" / "other-project" / "newest.jsonl",
+                fixture("claude", other),
+                mtime=100,
+            )
+
+            found = ClaudeLocator(root=root / "claude").find_latest_for_cwd(cwd)
+
+            self.assertIsNone(found)
+
+    def test_skips_malformed_file(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            cwd = root / "project"
+            cwd.mkdir()
+            project = root / "claude" / str(cwd).replace("/", "-")
+            write(project / "broken.jsonl", "not-json\n", mtime=20)
+            valid = write(project / "valid.jsonl", fixture("claude", cwd), mtime=10)
+
+            found = ClaudeLocator(root=root / "claude").find_latest_for_cwd(cwd)
+
+            self.assertIsNotNone(found)
+            assert found is not None
+            self.assertEqual(found.path, valid.resolve())
+
+
+class CodexLocatorTests(unittest.TestCase):
+    def test_reads_session_meta_and_selects_newest_matching_rollout(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            cwd = root / "project"
+            cwd.mkdir()
+            sessions = root / "codex"
+            write(
+                sessions / "2026" / "01" / "01" / "rollout-old.jsonl",
+                fixture("codex", cwd),
+                mtime=10,
+            )
+            latest = write(
+                sessions / "2026" / "01" / "02" / "rollout-latest.jsonl",
+                fixture("codex", cwd),
+                mtime=20,
+            )
+            write(
+                sessions / "2026" / "01" / "03" / "notes.jsonl",
+                fixture("codex", cwd),
+                mtime=30,
+            )
+
+            found = CodexLocator(root=sessions).find_latest_for_cwd(cwd)
+
+            self.assertIsNotNone(found)
+            assert found is not None
+            self.assertEqual(found.path, latest.resolve())
+            self.assertEqual(found.session_id, "codex-session")
+
+    def test_rejects_different_cwd(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            cwd = root / "project"
+            other = root / "other"
+            cwd.mkdir()
+            other.mkdir()
+            write(
+                root / "codex" / "2026" / "rollout-other.jsonl",
+                fixture("codex", other),
+                mtime=10,
+            )
+
+            self.assertIsNone(
+                CodexLocator(root=root / "codex").find_latest_for_cwd(cwd)
+            )
+
+
+class PiLocatorTests(unittest.TestCase):
+    def test_reads_header_and_selects_newest_matching_session(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            cwd = root / "project"
+            cwd.mkdir()
+            sessions = root / "pi"
+            write(sessions / "project" / "old.jsonl", fixture("pi", cwd), mtime=10)
+            latest = write(
+                sessions / "project" / "latest.jsonl", fixture("pi", cwd), mtime=20
+            )
+
+            found = PiLocator(root=sessions).find_latest_for_cwd(cwd)
+
+            self.assertIsNotNone(found)
+            assert found is not None
+            self.assertEqual(found.path, latest.resolve())
+            self.assertEqual(found.session_id, "pi-session")
+
+    def test_rejects_different_cwd(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            cwd = root / "project"
+            other = root / "other"
+            cwd.mkdir()
+            other.mkdir()
+            write(root / "pi" / "other.jsonl", fixture("pi", other), mtime=10)
+
+            self.assertIsNone(PiLocator(root=root / "pi").find_latest_for_cwd(cwd))
+
+    @unittest.skipIf(os.name == "nt", "symlink creation needs privileges on Windows")
+    def test_matches_symlinked_working_directory(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            real_cwd = root / "real-project"
+            link_cwd = root / "linked-project"
+            real_cwd.mkdir()
+            link_cwd.symlink_to(real_cwd, target_is_directory=True)
+            write(root / "pi" / "session.jsonl", fixture("pi", real_cwd), mtime=10)
+
+            found = PiLocator(root=root / "pi").find_latest_for_cwd(link_cwd)
+
+            self.assertIsNotNone(found)
+            assert found is not None
+            self.assertEqual(found.cwd, real_cwd.resolve())
+
+
+if __name__ == "__main__":
+    unittest.main()