Rename PyPI distribution to handoff-agent; add (c) copy on resume hint

The short name "handoff" is already taken on PyPI, so the distribution is
published as handoff-agent while the CLI command, Python package, and entry
point stay as "handoff". Also prompts the user to press (c) to copy the
resume command after a transfer, and falls back gracefully when no
clipboard tool is available.

Author: HacksonClark

.github/workflows/release.yml

@@ -7,7 +7,7 @@ on:
 
 # Use PyPI trusted publishing — no long-lived token required.
 # Configure at https://pypi.org/manage/account/publishing/
-# Project: handoff, Owner: <your-org>, Repo: handoff, Workflow: release.yml, Environment: pypi
+# Project: handoff-agent, Owner: HacksonClark, Repo: handoff, Workflow: release.yml, Environment: pypi
 permissions:
   contents: read
 
@@ -41,7 +41,7 @@ jobs:
     runs-on: ubuntu-latest
     environment:
       name: pypi
-      url: https://pypi.org/p/handoff
+      url: https://pypi.org/p/handoff-agent
     permissions:
       id-token: write  # trusted publishing
     steps:

README.md

@@ -17,12 +17,15 @@ When you switch between AI coding agents mid-project — rate limits, a second o
 
 ## Install
 
+The CLI is named `handoff`; the PyPI distribution is `handoff-agent` (the
+short name was already taken):
+
 ```bash
 # uv (recommended)
-uv tool install handoff
+uv tool install handoff-agent
 
 # pip
-pip install handoff
+pip install handoff-agent
 ```
 
 ## Usage

packaging/README.md

@@ -6,10 +6,20 @@ Releases publish automatically when you push a `v*` tag. Trusted publishing
 is configured via GitHub Actions (`.github/workflows/release.yml`). Set up
 the project on PyPI first:
 
-1. Create the project on https://pypi.org by uploading a manual release once.
-2. Add a trusted publisher: repo `HacksonClark/handoff`, workflow
-   `release.yml`, environment `pypi`.
-3. Tag a release: `git tag v0.1.0 && git push --tags`.
+1. In PyPI, add a trusted publisher for project `handoff-agent`. The name
+   `handoff` was already taken, so the distribution is published as
+   `handoff-agent` while the CLI command stays `handoff`.
+2. Use repo `HacksonClark/handoff`, workflow `release.yml`, environment `pypi`.
+3. If the project does not exist on PyPI yet, configure it as a pending
+   publisher so the first publish creates the project.
+4. Tag a release: `git tag v0.1.0 && git push origin v0.1.0`.
+
+Once the workflow publishes `handoff-agent` to PyPI, users can install it
+with:
+
+```bash
+uv tool install handoff-agent
+```
 
 ## Homebrew
 
@@ -25,7 +35,8 @@ Ship via a personal tap first; if there's uptake, submit to `homebrew-core`.
 
 ## uv tool
 
-Nothing to do — `uv tool install handoff` works once the package is on PyPI.
+Nothing separate to do. `uv tool install handoff-agent` installs from PyPI
+by default, so publishing to PyPI is what makes uv installs work.
 
 ## Shell completion
 

packaging/handoff.rb

@@ -12,7 +12,7 @@ class Handoff < Formula
 
   desc "Seamlessly switch between AI coding agents without losing context"
   homepage "https://github.com/HacksonClark/handoff"
-  url "https://files.pythonhosted.org/packages/source/h/handoff/handoff-0.1.0.tar.gz"
+  url "https://files.pythonhosted.org/packages/source/h/handoff-agent/handoff_agent-0.1.0.tar.gz"
   sha256 "REPLACE_WITH_SHA256_OF_SDIST"
   license "MIT"
 

pyproject.toml

@@ -1,5 +1,5 @@
 [project]
-name = "handoff"
+name = "handoff-agent"
 version = "0.1.0"
 description = "Seamlessly switch between AI coding agents without losing context."
 readme = "README.md"

src/handoff/agents/codex.py

@@ -342,7 +342,11 @@ def inject(self, transcript: CanonicalTranscript) -> Path:
         ts_iso = ts.isoformat().replace("+00:00", "Z")
         lines: list[dict[str, Any]] = []
         first_user_message = next(
-            (msg.content for msg in transcript.transcript if msg.author == "user" and msg.content.strip()),
+            (
+                msg.content
+                for msg in transcript.transcript
+                if msg.author == "user" and msg.content.strip()
+            ),
             "",
         )
         title = first_user_message or f"Handoff from {transcript.metadata.source_agent}"
@@ -387,8 +391,6 @@ def inject(self, transcript: CanonicalTranscript) -> Path:
         for msg in transcript.transcript:
             lines.extend(self._message_to_records(msg, ts_iso))
 
-        import os
-
         fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
         with os.fdopen(fd, "w", encoding="utf-8") as f:
             for rec in lines:
@@ -412,7 +414,9 @@ def inject(self, transcript: CanonicalTranscript) -> Path:
                     reasoning_effort=None,
                 )
             except Exception as exc:
-                log.warning("handoff: Codex SQLite mirror failed (falling back to JSONL-only): %s", exc)
+                log.warning(
+                    "handoff: Codex SQLite mirror failed (falling back to JSONL-only): %s", exc
+                )
         return path
 
     @staticmethod

src/handoff/cli.py

@@ -3,7 +3,11 @@
 from __future__ import annotations
 
 import json
+import os
+import shutil
+import subprocess
 import sys
+from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -217,7 +221,10 @@ def transfer_cmd(
     _success(f"Created {to_a.title()} session: {new_path.stem}")
     _info(f"  {new_path}")
     _info("")
-    _info(_resume_help(to_a, new_path))
+    hint = _resume_hint(to_a, new_path)
+    _info(hint.text)
+    if hint.command:
+        _prompt_copy(hint.command)
 
 
 def _emit(transcript: CanonicalTranscript, fmt: str) -> None:
@@ -230,33 +237,109 @@ def _emit(transcript: CanonicalTranscript, fmt: str) -> None:
         click.echo(to_markdown(transcript))
 
 
-def _resume_help(agent: str, path: Path) -> str:
-    """Agent-specific instructions for opening the injected session."""
+@dataclass(frozen=True)
+class ResumeHint:
+    """Instructions for resuming an injected session, plus a copyable command.
+
+    ``command`` is ``None`` when there is no single command to copy (e.g. the
+    target agent only exposes a session picker UI).
+    """
+
+    text: str
+    command: str | None = None
+
+
+def _resume_hint(agent: str, path: Path) -> ResumeHint:
     session_id = path.stem
     if agent == "claude":
-        return (
-            "To continue in Claude Code:\n"
-            f"    claude --resume {session_id}"
-        )
+        command = f"claude --resume {session_id}"
+        return ResumeHint(text=f"To continue in Claude Code:\n    {command}", command=command)
     if agent == "codex":
         try:
             first = path.read_text(encoding="utf-8").splitlines()[0]
             record = json.loads(first)
             session_id = record.get("payload", {}).get("id") or session_id
         except (OSError, json.JSONDecodeError, IndexError, AttributeError):
             pass
-        return (
-            "To continue in Codex:\n"
-            f"    codex resume {session_id}\n"
-            "(or just run `codex` in this directory — the most recent rollout is picked up)"
+        command = f"codex resume {session_id}"
+        return ResumeHint(
+            text=(
+                "To continue in Codex:\n"
+                f"    {command}\n"
+                "(or just run `codex` in this directory — the most recent rollout is picked up)"
+            ),
+            command=command,
         )
     if agent == "opencode":
-        return (
-            "To continue in OpenCode:\n"
-            "    opencode       # then open the 'Handoff from <agent>' session from the session list\n"
-            f"(session id: {session_id})"
+        # OpenCode has no single-command resume — user picks from a session list.
+        return ResumeHint(
+            text=(
+                "To continue in OpenCode:\n"
+                "    opencode       # then open the 'Handoff from <agent>' session from the session list\n"
+                f"(session id: {session_id})"
+            ),
+            command=None,
+        )
+    return ResumeHint(text="Ready to continue!", command=None)
+
+
+def _copy_to_clipboard(text: str) -> bool:
+    """Copy ``text`` to the system clipboard. Returns True on success."""
+    candidates: list[list[str]] = []
+    if sys.platform == "darwin":
+        candidates = [["pbcopy"]]
+    elif sys.platform == "win32":
+        candidates = [["clip"]]
+    else:
+        if os.environ.get("WAYLAND_DISPLAY"):
+            candidates.append(["wl-copy"])
+        candidates.extend(
+            [["xclip", "-selection", "clipboard"], ["xsel", "--clipboard", "--input"]]
         )
-    return "Ready to continue!"
+
+    for cmd in candidates:
+        if not shutil.which(cmd[0]):
+            continue
+        try:
+            subprocess.run(cmd, input=text, text=True, check=True, timeout=2)
+            return True
+        except (subprocess.SubprocessError, OSError):
+            continue
+    return False
+
+
+def _prompt_copy(command: str) -> None:
+    """Offer to copy ``command`` to the clipboard on keypress.
+
+    Only runs in interactive terminals; a no-op when stdout/stdin aren't TTYs
+    (e.g. piped output, CI, test harnesses).
+    """
+    if not (sys.stdin.isatty() and sys.stdout.isatty()):
+        return
+
+    click.echo("")
+    prompt = click.style(
+        "Press (c) to copy command, any other key to continue...", fg="cyan", dim=True
+    )
+    click.echo(prompt, nl=False)
+    try:
+        ch = click.getchar(echo=False)
+    except (KeyboardInterrupt, EOFError):
+        click.echo("")
+        return
+
+    # Wipe the prompt line so the final output doesn't include the prompt text.
+    click.echo("\r\033[2K", nl=False)
+    if ch and ch.lower() == "c":
+        if _copy_to_clipboard(command):
+            click.echo(click.style("✓ Copied to clipboard.", fg="green"))
+        else:
+            click.echo(
+                click.style(
+                    "✗ Could not copy (no clipboard tool found — install pbcopy/xclip/wl-copy).",
+                    fg="yellow",
+                )
+            )
 
 
 # ---------------------------------------------------------------------------

tests/test_cli.py

@@ -4,7 +4,7 @@
 
 from click.testing import CliRunner
 
-from handoff.cli import _resume_help, main
+from handoff.cli import _resume_hint, main
 
 
 def test_help() -> None:
@@ -41,12 +41,27 @@ def test_unknown_agent_errors(tmp_path: Path, monkeypatch) -> None:
     assert result.exit_code != 0
 
 
-def test_resume_help_uses_codex_session_uuid(tmp_path: Path) -> None:
+def test_resume_hint_uses_codex_session_uuid(tmp_path: Path) -> None:
     rollout = tmp_path / "rollout-2026-04-21T20-37-58-abc.jsonl"
     rollout.write_text(
         '{"timestamp":"2026-04-21T20:37:58Z","type":"session_meta","payload":{"id":"392bdabb-6109-4343-81e5-6b7ca056b09d"}}\n',
         encoding="utf-8",
     )
 
-    help_text = _resume_help("codex", rollout)
-    assert "codex resume 392bdabb-6109-4343-81e5-6b7ca056b09d" in help_text
+    hint = _resume_hint("codex", rollout)
+    assert hint.command == "codex resume 392bdabb-6109-4343-81e5-6b7ca056b09d"
+    assert "codex resume 392bdabb-6109-4343-81e5-6b7ca056b09d" in hint.text
+
+
+def test_resume_hint_claude_has_copyable_command(tmp_path: Path) -> None:
+    session = tmp_path / "4c9b7967-90d7-4fab-8e1d-6a95f1b3c8e2.jsonl"
+    session.write_text("", encoding="utf-8")
+    hint = _resume_hint("claude", session)
+    assert hint.command == "claude --resume 4c9b7967-90d7-4fab-8e1d-6a95f1b3c8e2"
+
+
+def test_resume_hint_opencode_has_no_copyable_command(tmp_path: Path) -> None:
+    session = tmp_path / "abc.json"
+    session.write_text("", encoding="utf-8")
+    hint = _resume_hint("opencode", session)
+    assert hint.command is None