handoff

---
name: handoff
description: Use when a user wants the canonical coSlash handoff or context for a specific session.
---

# coSlash handoff

If the user means the current session, resolve it from the host:

| Host | Selector |
| --- | --- |
| Claude Code | `claude:$CLAUDE_CODE_SESSION_ID` when that variable is set. If it is unset, list sessions for Claude. |
| Codex | `codex:$CODEX_SESSION_ID` when that variable is set. If it is unset, list sessions for Codex. |
| OpenCode | `coslash sessions --agent opencode --recent 20 --json` |
| Cursor CLI | `coslash sessions --agent cursor --recent 20 --json` |
| Pi | `coslash sessions --agent pi --recent 20 --json` |
| Grok | `coslash sessions --agent grok --recent 20 --json` |

Use a returned `selector` only when it uniquely identifies the intended session; if multiple sessions could match, ask the user to choose. Do not assume the newest session is current. For a named session, use the `selector` returned by `coslash sessions [query] --json`. Then run `coslash handoff <agent>:<session>`.

Use the `coslash` executable found on `PATH` and preserve the inherited `COSLASH_HOME`. Do not substitute a repository-relative binary or `go run` unless the user explicitly asks to test a source build.

If a command reports `Error: usage:`, compare the usage it prints with the command you ran. If that usage does not list a subcommand or flag that you used, the installed coSlash is older than this skill. Run `coslash --version`, tell the user to update coSlash the same way they installed it, for example `brew upgrade coslash`, and stop. Otherwise, the arguments are not valid: return stderr and the exit status. Do not retry with other flags.

In Codex, if the command reports `coSlash app is not running`, `coSlash app is not reachable`, or `operation not permitted` for coSlash storage, request escalated execution and retry the exact command outside the sandbox. Use the same elevated execution for any startup and retries below. If permission is denied, stop and report that coSlash needs access to its local files and loopback address.

If the command reports `coSlash app is not running` after the Codex retry, when applicable, resolve the `coslash` executable from `PATH`, launch that executable directly as `coslash --no-open --port 0` in the background with output redirected to temporary logs created with `mktemp -t coslash.XXXXXX` on macOS/Linux or `New-TemporaryFile` on Windows PowerShell, and retain its PID. On Windows PowerShell, use `Start-Process` with `-WindowStyle Hidden`, `-PassThru`, and separate stdout/stderr redirection; retain the returned process object and include both logs in startup failures. Do not launch for other errors. Every two seconds, retry the exact original command while it reports `coSlash app is not running`, until three minutes pass. The command reports that error before it contacts the app, so a retry has no side effect. If the retained process exits because another coSlash app is already running, keep retrying for that app; for any other early exit, return the startup logs.

When the command reports anything else, stop retrying and use that result. Keep the temporary logs while the retained process runs, and arrange their removal after that process exits; if it already exited as a startup contender, remove the logs when the retries end. On startup failure or timeout, stop the retained process if it is still running (SIGTERM on macOS/Linux, or `Stop-Process -InputObject $process` followed by `$process.WaitForExit()` on Windows PowerShell, using the object returned by `Start-Process`), return the startup logs, then remove the logs. Otherwise leave the instance running by default. If the user asks to close it after the command, arrange cleanup before launching so interruption also stops that same process object using the same platform command, then wait for it to exit and remove the logs. Report cleanup failures on stderr without changing command stdout. Never stop an instance that was already running or a process found by name, port, or a PID file.

On success, make the entire final response the exact command stdout, starting with its `# Handoff` heading. Do not add a preface, summarize, or reformat it. If the command fails, return stderr and the exit status, then suggest `coslash doctor --json`.