agent-handoff

# Agent handoff Moves a coding agent that is running in a herdr pane on this machine to another machine, so the user can carry on there (typically: laptop → always-on box on the tailnet, and back). One handoff does all of this: 1. Finds the agent in herdr and its session: herdr's agent integration records the id. Without it, the script uses the newest transcript for that folder written since the agent started. 2. Checks the target over ssh: tools present, herdr server up, and **a checkout of the same repo** — matched by git remote, so it may live at a different path. 3. Quits the agent cleanly (`/exit`), so nothing else writes to the transcript. 4. Pushes `HEAD` plus a snapshot of uncommitted changes **straight to the target over ssh** (`refs/handoff/*`, removed afterwards). Nothing is pushed to GitHub, and no branch on either side is rewritten. 5. On the target: fast-forwards the branch where it is already checked out, or else makes a worktree next to the repo (`<repo>.worktrees/<branch>`), then applies the uncommitted changes. 6. Copies the transcript into the target agent's session store (honouring `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `PI_CODING_AGENT_DIR` and `GROK_HOME` on either side), replacing the old repo path, home directory and config folder with the new ones inside it. 7. Installs the herdr integration for that agent on the target if it's missing (so the next handoff back knows the session id), opens a herdr workspace there and resumes the agent. If the agent asks whether to trust the folder, the script answers yes: the user was already working in this repo on the source. Pass `--no-trust` to leave that question for the user. 8. Stashes the uncommitted changes in the source checkout (`git stash list` shows them), so a later handoff back applies cleanly. If anything fails after step 3, including the agent exiting straight after it starts on the target, the script restarts the agent where it was and reports why. ## How to run it The script is `scripts/agent_handoff.py` in the folder that contains this SKILL.md (your agent may call it the skill's base directory). It needs only `python3`. Run it with a shell that has network access and may run `ssh` and write to other agents' session folders (`~/.claude`, `~/.codex`, ...). If your agent runs commands in a sandbox that blocks these, ask the user to approve running the script outside it; don't work around the sandbox. ```bash S="<skill_dir>/scripts/agent_handoff.py" python3 "$S" list # agents here, their status and session ids python3 "$S" doctor <ssh-target> # prerequisites here and on the target python3 "$S" send <agent> <ssh-target> --dry-run python3 "$S" send <agent> <ssh-target> python3 "$S" send <agent> <ssh-target> --self # move yourself after this turn ends python3 "$S" list --from <host> # agents on another machine python3 "$S" send <agent> --from <host> # bring an agent on <host> back to this machine python3 "$S" send <agent> --here --new-worktree # same machine: into a new worktree of the repo python3 "$S" send <agent> --here --dir <checkout> # same machine: into another checkout ``` - `<agent>`: a herdr agent name, pane id (e.g. `w1Y:p7`), or session id prefix, taken from `list`. - `<ssh-target>`: whatever `ssh` accepts non-interactively (e.g. `vega@vega`, a tailnet name, or an SSH config alias). Every command prints JSON. `send` ends with `"ok": true` and an `attach` command, or `"ok": false` and an `error`. A self-handoff returns `"ok": true, "deferred": true` with the helper's `pane` and `workspace`; this means it was scheduled, not that the move has finished. ## Procedure The handoff always runs on the machine where the agent is. To bring a session *back* from another machine (for example "bring the hark session on vega back here"), use `list --from <that machine>`, then `send <agent> --from <that machine>` with **no target**. The script fills in this machine's ssh name (`$AGENT_HANDOFF_SELF`, else `user@hostname`). Only pass a target with `--from` if the user names a third machine. Never pass the `--from` host as the target. To move a session **on this machine**, use `--here` (no ssh). Use `--here --new-worktree` when the user wants the session in its own worktree (it gets a `handoff/<id>` branch), and `--here --dir <path>` for a checkout they name. Plain `--here` uses another checkout of the repo on this machine if there is one, else a new worktree; the dry run shows which (`target_repo`). If this is the first handoff to a machine, run `doctor <ssh-target>` first. Report anything missing (herdr not running, the agent CLI not installed, ssh failing), with the fix. 1. Run `list`. Pick the agent the user means: match on name, repo (`cwd`) or what it is working on. If more than one fits, ask. A row with `"this_pane": true` is you: pick it when the user asks you to move yourself, and pass `--self` when sending. 2. If the user didn't name the target machine, ask for it. Don't guess. Users often say a nickname ("the mini", "my laptop"). If it doesn't match a name the user has given before, ask which ssh host it means. 3. Run `send … --dry-run` and check the plan: - `target_repo` is the checkout you expected. If `other_target_checkouts` lists others and it's not obvious, ask, then pass `--dir <path>`. - `source_argv` shows how the agent was started. If it had flags the user will want kept (model, permission mode), pass them after `--`, e.g. `send hark vega@vega -- --model opus`. 4. If another agent is `working`, tell the user, and only pass `--wait` if they want to wait for it to finish its turn. Dry runs check the plan immediately, even while an agent is working. 5. Run `send`. Report the target worktree, branch, whether uncommitted changes moved, and the `attach` line (`herdr --remote <target>`). For yourself, use `send … --self`: it checks the plan and starts a helper pane, then returns immediately. When `deferred` is true, finish your reply with "Moving to <target> once this turn ends" and the `attach` line, then end the turn. The helper waits for idle, quits you, and completes the move. Uncommitted changes and the transcript are captured after you quit, including edits and your final reply from this turn. The helper closes on success; on failure it stays open showing the error, and restarts you in place if you had already quit. 6. If `target_waiting_for_user` is not empty, the agent on the target is showing a screen the user must answer, and the script never answers these. Tell the user what it is, and don't send the agent prompts until they've dealt with it (a prompt's Enter would land on that screen): - `hook_review`: Codex wants approval for a new or changed hook, usually the herdr hook the handoff just installed. Approving it lets herdr track Codex's state on that machine. Escape skips it, and hooks then don't run. - `first_run_setup` / `login`: the agent has never been set up, or isn't logged in, on the target. The session is copied over and will resume once the user attaches, finishes setup and logs in. - `unrecognized_prompt`: the agent stopped on a screen this tool doesn't know (often after an agent update reworded one). The user should attach and look. 7. If `send` fails, quote its `error`. It ends with what to do (`--new-branch`, `--dir`, install something, wait for the agent). ## Never fix access or setup yourself If a step fails because of ssh (permission denied, host key verification, unknown host), a missing tool, herdr not running, or a logged-out agent, **stop and tell the user**. Give them the error and the fix, and let them do it. Do not: - add, copy or generate SSH keys, or edit any SSH file (the authorized-keys and known-hosts files, or the client config), on any machine; - try other usernames or hostnames until something connects. Use the names the user gave, or ask; - install software, or log agents in, on either machine; - change git config, discard changes, or delete stashes or worktrees. Running `doctor` to diagnose is fine. Retrying with a corrected name the user gave you is fine. ## Options | Flag | Use | |---|---| | `--dir PATH` | Use this checkout on the target (skips discovery). | | `--new-branch` | Put the work on `handoff/<id>` on the target. Use when the target's copy of the branch is dirty or has diverged; the error message says when. | | `--keep-source-changes` | Don't stash the source checkout afterwards. | | `--name NAME` | Agent name on the target (defaults to the source name, or `<repo>-<kind>`). | | `--session ID_OR_PATH` | Session to move, if herdr didn't record one (integration installed after the agent started). | | `--no-focus` | Don't focus the new workspace on the target. | | `--wait` | Wait for a `working` agent to go idle first. | | `--self` | Move the agent running this command after its turn ends, using a separate helper pane. Required for self-handoffs. | | `--wait-timeout SECONDS` | Maximum wait for idle with `--wait` or `--self` (default: 1800 seconds). Continues as soon as the agent is idle. On timeout the source agent keeps running and the helper stays open with the error. | | `--no-trust` | Don't answer the agent's "trust this folder?" screen on the target; leave it for the user. | | `--here` | Hand off on this machine, no ssh. Add `--new-worktree` or `--dir`. | | `--new-worktree` | With `--here`: move the session into a new worktree of the same repo. | | `--from HOST` | Run on HOST, where the agent is, over ssh. Works with `list`, `doctor` and `send`. | ## Repo discovery on the target Checkouts are matched by any git remote (`git@github.com:o/r.git` and `https://github.com/o/r` are the same). The search covers `~/github.com`, `~/src`, `~/code`, `~/dev`, `~/Developer`, `~/projects`, `~/repos`, `~/work`, `~/git`, `~/workspace` and the top of `~`. Results are cached in `~/.config/agent-handoff/repos.json`. To change the search roots, set `AGENT_HANDOFF_ROOTS=dir1:dir2` or write `{"roots": [...]}` to `~/.config/agent-handoff/config.json`. ## Limits - Supported agents: `claude`, `codex`, `omp`, `pi`, `grok`. Others (including `hermes`) fail with a clear error. Adding one means adding an adapter class to the script. - The repo must have at least one git remote, so it can be matched on the target. - The agent must be at rest (idle or done) before it quits. `--wait` and `--self` wait for that state; they do not answer approvals. - herdr's Codex integration doesn't record a session id. The script picks the newest Codex transcript for the agent's folder written since the agent started. If two Codex agents share a folder it stops and asks for `--session`. - Uncommitted changes leave the source checkout (they're stashed). Don't hand off an agent in a repo where you are editing files by hand at the same time. - Needs herdr 0.8.0 or newer on both machines, and ssh between them that works without prompts (`ssh -o BatchMode=yes <host> true`). - The source pane is left at a shell prompt. Worktrees the handoff creates are left in place; remove them with `git worktree remove` when you're done.