pi-roam

Post-hoc handoff of a live Pi session into tmux for remote continuation, with optional Tailscale account switching

Package details

← Back

extension

Install pi-roam from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:pi-roam

Package: pi-roam
Version: 0.1.0
Published: Feb 25, 2026
Downloads: 20/mo · 5/wk
Author: w-winter
License: MIT
Types: extension
Size: 23.9 KB
Dependencies: 0 dependencies · 1 peer

Pi manifest JSON

{
  "extensions": [
    "extensions/roam/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

Roam for Pi (`pi-roam`)

Post-hoc handoff of a live Pi session into tmux for remote continuation. If you forgot to start Pi inside tmux, you can conveniently run /roam mid-session and continue from another device over SSH.

Install

From npm:

pi install npm:pi-roam

From the dot314 git bundle (filtered install):

{
  "packages": [
    {
      "source": "git:github.com/w-winter/dot314",
      "extensions": ["extensions/roam/index.ts"],
      "skills": [],
      "themes": [],
      "prompts": []
    }
  ]
}

Setup

Optional per-user config:

copy config.json.example → config.json
location: ~/.pi/agent/extensions/roam/config.json

Example:

{
  "tailscale": {
    "account": "you@example.com",
    "binary": "/Applications/Tailscale.app/Contents/MacOS/Tailscale"
  }
}

Usage

/roam [window-name]

Defaults window name to the current cwd basename.

What it does

Pre-flight checks (interactive TTY, not already in tmux, tmux installed, session exists)
On macOS, optionally runs tailscale switch <account> then tailscale up (non-fatal)
Forks the current session, clears the fork header's parentSession pointer
Creates/joins dedicated tmux server -L pi, one window per roamed session
Attaches your terminal to tmux and leaves parent process as inert exit-code forwarder
Best-effort trashes original session file (for standard ~/.pi/ session paths)

Notes

Cross-platform tmux behavior; Tailscale integration is currently macOS-specific by default binary path
Uses dedicated tmux socket (-L pi) plus per-socket config for isolation
Config template is intentionally user-specific; do not commit your local config.json

Roam for Pi (pi-roam)