Pairroom Relay

---
name: pairroom-relay
description: Collaborate across native sessions through PairRoom.
---

# PairRoom relay

Use this session's agent tools. Before first bind or on setup failure, run read-only pairroom relay preflight; follow next_steps until ready. Bindings follow sessions across cwd/worktrees: --repo is for initial selection/ambiguity, not rebinding on cwd changes. Reuse the Room; follow its collaboration rules. Gemini: approve BeforeTool/AfterAgent; run standalone run_shell_command. No Service wake.

**Create** (/pairroom-relay [peer] <topic>): leading claude|cc|codex|grok|gemini sets --peer-runtime; otherwise infer only one clearly named non-self peer, or omit. pairroom relay bind --create --name "<topic>". Default slot 1; --slot only on request. Retry creation once with the intended peer only if preflight explicitly says no Room was created and no peer runtime was passed; otherwise recover, never repeat --create. Share peer_join_local (same workspace) or peer_join unchanged.

**Join/resume**: pairroom relay bind; select only on ambiguity. Slots: 1|2, not runtimes. Bind is usable immediately; no nonce, turn/status check or provider setup. On a new join to a bound peer, announce once via relay send; no wait/final peer handle. Skip on resume or binding first.

**Discuss**: receive: pairroom relay wait; exchange: pairroom relay exchange --id <stable-id> --text "<message>". Reuse an ID only for identical publication content. Confirmed send plus timeout: receive-only wait, never resend. Finish with send; omit a final peer handle unless intentionally publishing twice. Use status/reconcile only for uncertainty/failure, not after each success. Read a harness's full-output file if only a preview is shown; stdout/handed_off is not model acceptance.

**Files/evidence**: send existing text with --text-file <path> or stdin with --text-file -; do not read and retype it. Prefer inline small replies and send deltas. send/exchange --ref <path> shares path/size/SHA-256, not uploaded content: retain the file, verify its hash, read needed sections with authorized access; changed evidence needs a new ID. wait/exchange --output-file <new-path> saves the full envelope; read it before acting. Parent must exist and be writable; no overwrite, retry with a fresh path. Paths use the tool cwd; these flags need the current CLI. For requested reviews use --review and verify with review --id <published-id>; pass --review-repo <task-checkout> on each for a different checkout. An observation is neither an atomic snapshot nor approval. Inspect independently; report unresolved disagreements. Pin base/head SHAs and dirty hash; recheck before closure. Findings need location, evidence and impact; label hypotheses. Verify fixes at the new revision with a retest. Report tests/not run. See Getting started.

**Reachability**: keep exactly one collector. If tracked background completion wakes this harness without idle model turns, keep one long relay wait while bound (--timeout 0 until cancelled); resolve its result before another collector, and rehang after expiry unless unbound or the human stops it. A quiet Room alone is not a stop request. In a poll-only harness, do not keep a background wait or poll merely to stay reachable: unseen stdout can consume input and suppress Service wake. End the turn: bounded Stop park or Service wake in a wake-enabled Room may deliver queued input next turn. During active work, an imminent reply warrants one foreground wait/exchange within the harness tool limit; after an empty timeout, end the turn. The CLI's one-hour default is a transport budget, not a harness lifetime guarantee. Stop park is bounded. Wake is rate-limited/fail-closed: only unattempted cooldown work is rechecked; reserved effects are never auto-retried. Failed wake leaves input queued for collection or a human nudge. Never execute printed vendor wake commands.

**Grok**: approve /hooks, reload with r; folder trust belongs to the human. No Service wake and at most seven Stop continuations: long unattended runs need supported tracked completion: keep one background wait in Grok and send long results explicitly, or input stays queued. Reuse a compatible project hook; do not add a duplicate. Readiness means run wait for full input. Publish clipped replies in full via explicit send/exchange, never a truncated prefix or already-confirmed resend. Grok shell mode (!) lacks GROK_SESSION_ID and skips Stop: run relay through the agent's terminal tool. If the human used !, rerun the command yourself; never ask for a session ID.

**Recovery**: on Service failure run pairroom daemon status; ask the human to start it, and install the daemon only with confirmation. Use doctor for wake/capability issues; history --id or paged history --pending for read-only evidence. Inspection never requeues work or proves model acceptance. Recover through the CLI, not private state; never bypass approvals. Session changes require explicit bind --replace.