# 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.