---
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, Droid, or Grok Build) 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|grok> [--session <id>]
   ```

   - If you are Claude Code, your session id is the UUID in your scratchpad
     path (`.../<uuid>/scratchpad`). If you are Grok Build, it is the session
     directory name under `~/.grok/sessions/<encoded-cwd>/<uuid>/`. If unsure,
     omit `--session` — parcel picks the newest session for this cwd.
   - `--agent grok` (alias: `grok-build`) transplants a Grok Build session.
   - `--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 / grok** — `parcel auth <target>` copies the credential files.
  Grok alternative: set `XAI_API_KEY` on the target, or run `grok login`.
- **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 `.env`s — 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.