107 lines
2.6 KiB
Markdown
107 lines
2.6 KiB
Markdown
# 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.
|