2.6 KiB

Raw Blame History

Phase 0 Spike — Quick Start

This branch contains the Phase 0 Proof of Concept for streaming tmux output via WebSocket.

What This Does

Spawns a tmux session running pi
Streams the terminal output via pipe-pane to a FIFO
Broadcasts the stream over WebSocket to multiple clients
Demonstrates that pi runs cleanly in tmux and streaming is viable

How to Run

1. Start the Spike Server

npm run spike

Output:

=== Phase 0 Spike: tmux Stream PoC ===

[spike] Creating tmux session: pi-spike
[spike] Created FIFO: /tmp/pi-spike.fifo
[spike] Attached pipe-pane to session pi-spike
[spike] WebSocket server listening on ws://127.0.0.1:7799/spike

=== Spike Server Running ===

To attach to the tmux session (in another terminal):
  tmux attach -t pi-spike

WebSocket endpoint:
  ws://127.0.0.1:7799/spike

To test with the HTML client:
  open /path/to/spike-client.html

To stop: Ctrl+C in this terminal

2. Attach to the tmux Session

In a separate terminal:

tmux attach -t pi-spike

Now you can interact with pi normally. Any output will be streamed to connected WebSocket clients.

To detach: Ctrl+B, then D

3. Connect a Client

Option A: HTML Client (recommended)

open extensions/remote-control/spike-client.html

This opens a browser with xterm.js that renders the stream in real-time.

Option B: Raw WebSocket (for testing)

node -e "
const WebSocket = require('ws');
const ws = new WebSocket('ws://127.0.0.1:7799/spike');
ws.on('message', (data) => process.stdout.write(data));
"

4. Stop

Press Ctrl+C in the terminal running the spike server
Or: pkill -f "tsx.*spike.ts"
Cleanup: tmux kill-session -t pi-spike

Files

extensions/remote-control/spike.ts — Main spike implementation
extensions/remote-control/spike-client.html — Test client with xterm.js
run-spike.sh — Wrapper script
docs/reference/PHASE-0-report.md — Full report with findings

Key Findings

✅ Works: Pi runs cleanly in tmux, ANSI streaming works, latency is excellent (< 50ms localhost)

⚠️ Issue: tmux's pipe-pane can disconnect after certain operations (e.g., alternate screen buffer usage). Not a blocker for PoC, but Phase 1 should use node-pty instead.

See the full report: docs/reference/PHASE-0-report.md

Next Steps

This branch is kept for reference. The PoC validated the approach.

Phase 1 will rebuild from scratch with:

node-pty instead of pipe-pane
Ringbuffer for replay/snapshot
WebSocket compression (permessage-deflate)
Proper error handling and reconnection

See docs/SYNC.md for current status.

2.6 KiB Raw Blame History