parcel

# 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.