Web Companion

A browser-based mirror of your agent terminals. Live PTY streaming via xterm.js and WebSocket.

What It Is

The web companion is a single-page app served by the initech process. Open it in any browser and you see live terminal output from your agent panes, rendered by xterm.js. The same raw PTY bytes that drive the TUI are streamed over WebSocket to the browser.

It's read-only. You can observe agents from the browser but not type into them. Use initech send or the TUI for input.

Enabling

The web companion is disabled by default. Enable it with the --web-port flag:

$ initech --web-port 9100

The TUI banner shows the URL on startup:

Web: http://localhost:9100

You can also set web_port in initech.yaml to enable it permanently:

web_port: 9100   # 0 = disabled (default)

Accessing

Open the URL in any browser. The web companion binds to 0.0.0.0, so it's accessible from other devices on your network:

• Same machine: http://localhost:9100
• LAN device: http://<your-ip>:9100 (phone, tablet, second laptop)
• Tailscale: http://<tailscale-ip>:9100

Features

Live terminal streaming

Each agent pane streams its PTY output over WebSocket. The browser renders it with xterm.js, the same terminal emulator used by VS Code, Jupyter, and GitHub Codespaces. You see full ANSI colors, cursor positioning, and Claude Code's interface rendered correctly.

Multi-pane grid

The browser renders all agent panes in a CSS grid, similar to the TUI layout. Click a pane to zoom it full-screen. Click again to return to the grid.

Agent overlay

A floating overlay shows agent names and activity state (running, idle, stopped). Pane labels appear above each terminal.

Auto-reconnect

If the WebSocket connection drops (network interruption, laptop sleep), the browser reconnects automatically. Terminal content reappears as the agent produces new output.

Use Cases

• Monitor from a phone or tablet. Open the URL on your phone while away from your desk. See which agents are active without switching back to the terminal.
• Second-screen dashboard. Put the web companion on a second monitor. Keep the TUI for interaction, use the browser for observation.
• Share with a teammate. Send the LAN URL to a colleague. They can watch your agent session in their browser without terminal access.
• Persistent view during meetings. Open the companion on a tablet during standups. Glance at agent progress without context-switching.

API Endpoints

The web companion exposes a simple API that advanced users can build on:

• GET / serves the SPA (embedded in the binary via go:embed)
• GET /api/panes returns a JSON array of pane info: [{"name":"eng1","activity":"running","alive":true}]
• WS /ws/pane/<name> opens a WebSocket that streams raw PTY bytes for the named pane

The pane list endpoint lets you build custom dashboards or monitoring integrations on top of the web companion.

Architecture

The web server is embedded in the initech process, not a separate binary. It has direct access to pane PTY file descriptors. When the TUI's readLoop() reads bytes from a PTY, it writes to the terminal emulator (for TUI rendering) and broadcasts the same bytes to all WebSocket subscribers.

initech
  |
  +-- TUI (tcell, renders to terminal)
  +-- IPC socket (.initech/initech.sock)
  +-- HTTP :9100 (web companion)
       +-- GET /              SPA (xterm.js)
       +-- GET /api/panes     JSON pane list
       +-- WS  /ws/pane/eng1  raw PTY bytes

Static assets (HTML, JS, CSS, vendored xterm.js) are embedded in the binary via go:embed. No npm, no build step, no external files.

Security

The web companion has no authentication in the current version. Anyone who can reach the port can view your agent terminals. On a trusted LAN or VPN this is acceptable. For sensitive environments:

• Use SSH tunneling: ssh -L 9100:localhost:9100 <host>
• Restrict access via firewall rules
• Keep the web companion disabled (web_port: 0) when not needed

Authentication is planned for a future version.

Last updated: April 2026