$ cat ~/map/pi-relay.md

pi-relay

Slash-command handoffs: the agent writes a sealed handoff, a successor session verifies it on the model you pick.

extensions✓ Sep 17

Install a tagged release with pi install git:github.com/jpowersdev/pi-relay@v0.1.0 and restart pi; move to a newer tag by installing it explicitly, or try the current checkout without installing it permanently with pi -e git:github.com/jpowersdev/pi-relay

## TL;DR

A pi extension that adds a /relay command for durable session handoffs: the current agent writes a structured, sealed handoff of the work state, a fresh parent-linked session starts on a model selected from an interactive picker, and the destination agent verifies repository state in a read-only first turn before continuing.

## Key points

• $Handoff flow: /relay asks the current agent to inspect the workspace and write a structured handoff, validates and seals it, creates a fresh session linked to the source session, restores the selected model and current thinking level, and asks the destination agent to verify repository state in a read-only first turn — the destination waits for your response before implementation resumes.
• $Model selection: pi presents an interactive selector of the models currently available to the local installation; command text after /relay is treated only as additional focus for the handoff and is never parsed as a model name.
• $Storage: handoffs live outside project repositories under ~/.pi/agent/handoffs/ with the directory at mode 0700 and sealed files at 0600 where Unix permissions apply; files are limited to 128 KiB and remain on disk until you remove them.
• $Privacy shape: a handoff can contain repository status, file paths, implementation summaries, decisions, and a path to the source session — treat it as private development data; the full source transcript is not copied into the handoff and remains available locally as a recovery path.
• $No extra network calls: the extension itself adds no network requests; the normal pi model turns used to write and verify a handoff still send context through the configured model provider.
• $Failure behavior: the source session remains intact; if handoff creation or validation fails, relay stops without replacing the current session, and a validated handoff is retained if a later session switch is cancelled.
• $Requirements: pi 0.82.1 or newer, Node.js 22.19.0 or newer, interactive TUI mode, an active write or bash tool for creating the handoff and an active read or bash tool for verifying it; the initial release is tested with pi 0.82.1, and pinning a release tag is recommended because pi extension APIs can evolve.

## FAQ

## References

• README ↗

Last updated: Sep 17, 2026