parcel

name	parcel
description	Ship the current work — repo, uncommitted changes, .env files, and the live agent session — to another machine over Tailscale SSH, where the agent resumes in tmux and keeps working. Use when the user says /parcel, "hand off to <machine>", "send this work to another machine", "keep this running after I close the laptop", or wants to move a coding session (Claude Code, Codex, pi, or Droid) to a remote box.
license	MIT

Parcel — hand off work to another machine

The parcel CLI is on PATH. Targets are machines defined in ~/.parcels/targets/<name>.conf; list them with parcel targets.

Workflow

1. Write intent into HANDOFF.md at the repo root before shipping. This is the most valuable part of the handoff — the remote agent (possibly a different one) reads it first. Include:

   • what you were working on and why
   • current state (what works, what's verified, what's mid-flight)
   • concrete next steps, in order
   • known gotchas and how to verify progress

   Preserve any existing ## Machine state (auto-generated by parcel section — parcel regenerates it on every send.

2. Ship. From inside the repo:

   parcel send <target> --agent <claude|codex|pi|droid> [--session <id>]
   

   • If you are Claude Code, your session id is the UUID in your scratchpad path (.../<uuid>/scratchpad). If unsure, omit --session — parcel picks the newest session for this cwd.
   • --prompt "..." steers what the remote agent does first (default: read HANDOFF.md and continue).
   • --idle ships without launching anything.

3. Verify it is actually running — never assume. parcel status <target> tails the remote tmux pane; you should see the agent producing output. If the launch failed, run parcel doctor <target> and report exactly what is missing.

4. Tell the user how to reach it: ssh -t <host> tmux attach -t parcel-<repo-name>.

Fixing missing auth (from parcel doctor)

• claude — user runs claude login once on the target, or mints a token on an authed machine with claude setup-token and sets CLAUDE_CODE_OAUTH_TOKEN in the target's shell profile.
• codex / pi — parcel auth <target> copies the credential files.
• droid — user runs droid once on the target to log in.

Notes

• Only git repos can be parceled (parcel send runs from inside the repo).
• The whole working tree ships — including untracked files and .envs — so warn the user before sending a repo with secrets to a shared machine.
• Re-sending the same repo overwrites the remote copy (rsync --delete) and restarts the tmux session.