pi-team-sync

Share Pi CLI sessions in real-time with your team. Watch pair programming sessions, debug together, or onboard new team members.

Features

• Real-time streaming — See Pi CLI output as it happens
• Session history — Late viewers catch up on what happened
• Simple setup — No auth, no database, just WebSocket relay
• Multi-viewer — Unlimited team members can watch one session
• Minimal dependencies — Only ws required

Installation

# Clone the repo
git clone https://github.com/ky2renzz/pi-team-sync.git
cd pi-team-sync

# Install dependencies
npm install

Setup

Add to ~/.pi/agent/settings.json:

{
  "tools": {
    "pi-sync": { "command": ["node", "/absolute/path/to/pi-sync.js"] }
  }
}

Replace /absolute/path/to/pi-sync.js with the actual path to the file.

Quick Start

# Terminal 1: Start relay server
node relay-server.js

# Terminal 2: In Pi CLI, create a session
pi-sync start --user "Your Name" --project "my-project"

# Terminal 3: Share your Pi session
pi | node pi-sync-host.js <session-id>

# Terminal 4 (teammate): View the session
node pi-sync-view.js <session-id>

Commands

pi-sync start

Create a new sharing session.

pi-sync start [--user <name>] [--project <name>]

• --user — Your name (optional)
• --project — Project name (optional)

Outputs a session ID that others can use to join.

pi-sync join <id>

Show connection info for an existing session.

pi-sync join <session-id>

pi-sync help

Show help message.

Environment Variables

• PI_SYNC_RELAY — HTTP URL for session creation (default: http://localhost:7123)
• PI_SYNC_RELAY_HOST — WebSocket host (default: localhost)
• PI_SYNC_PORT — Port for relay server (default: 7123)

Architecture

┌─────────────┐     WebSocket     ┌─────────────┐
│   Pi CLI    │ ─────────────────▶│   Relay     │
│  (host)     │◀─────────────────│   Server    │
└─────────────┘     WebSocket     └─────────────┘
                                            │
                                            │ WebSocket
                                            ▼
                                    ┌─────────────┐
                                    │   Viewer 1  │
                                    └─────────────┘
                                    ┌─────────────┐
                                    │   Viewer 2  │
                                    └─────────────┘
                                    ┌─────────────┐
                                    │   Viewer N  │
                                    └─────────────┘

• Relay Server (relay-server.js) — WebSocket + HTTP server that routes messages
• Host (pi-sync-host.js) — Pipes Pi CLI output to relay
• Viewer (pi-sync-view.js) — Connects to relay and displays output
• Session — Contains host connection, viewer connections, and message history

Use Cases

• Pair programming — Watch senior devs work in Pi
• Onboarding — New team members learn by watching
• Debugging — Get help by sharing your session
• Demos — Live coding sessions
• Code reviews — Watch the thought process

Development

# Install dependencies
npm install

# Run relay server
node relay-server.js

# Test session creation
node pi-sync.js start --user test --project test

# Test hosting
echo "test output" | node pi-sync-host.js <id>

# Test viewing (another terminal)
node pi-sync-view.js <id>

Limitations

• No authentication (trust-based, suitable for local teams)
• No persistence (relay restart clears all sessions)
• No encryption (use VPN for remote teams)
• Single relay instance (no clustering)

License

MIT

Contributing

See CONTRIBUTING.md