diff --git a/SPIKE-README.md b/SPIKE-README.md new file mode 100644 index 0000000..6b317d1 --- /dev/null +++ b/SPIKE-README.md @@ -0,0 +1,106 @@ +# 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 + +```bash +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: + +```bash +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) + +```bash +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) + +```bash +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.