ttv (terminal tv)

🚧⚠️🚧 Experimental Project 🚧⚠️🚧
This project is a fun, experimental proof-of-concept and is not intended for production use. It may be incomplete or contain bugs, and currently does not include security features.

ttv is a Go CLI for streaming and viewing live terminal sessions - built on Temporal.

Streaming (left) and viewing (right) live terminal sessions with ttv.

Prerequisites

• Go
• Temporal CLI (for running a local dev server)
• tmux (optional, only needed for the tmux demo)

Installation

$ go install ./cmd/ttv

# alternatively
$ make install

Usage

After installation, use the ttv CLI to stream and view terminal sessions. Common commands include:

• ttv list - List all active terminal streaming sessions
• ttv stream <session-name> - Start streaming your current terminal session. The <session-name> is the unique identifier for your session; viewers must use the exact same name to join.
• ttv view <session-name> <viewer-name> - Join and view an active session identified by the given session name, and provide your viewer name.

For help, run:

ttv <command> --help

Usage:
  ttv <command> [arguments]

Commands:
  stream <session-name>                Start streaming your current terminal session.
                                       <session-name> is the unique identifier for your session.

  view   <session-name> <viewer-name>  Join and view a running terminal stream as <viewer-name>.

  list                                 List available streams for viewing.

Flags:
  -h, --help                           Show this help message

Known Issues

WebSocket connection fails if reusing a session name.

If you reuse the same streaming session name (workflow ID) to create a new session, you will not be able to connect to the websocket server for that session.

To fix: Restart the worker or use a new, unique session name for each stream.

Demo Instructions

Note: If you'd prefer not to install ttv via go install, you can use go run ./cmd/ttv/main.go instead of the ttv command in the steps below.

Run each of the following steps in a new terminal window:

1. Start the Temporal Dev Server

$ temporal server start-dev

2. Start the ttv Worker

$ go run ./cmd/worker

3. Start a Streaming Session

$ ttv stream demo

# general syntax
$ ttv stream <your-session-name>

4. View Available Streaming Sessions

$ ttv list

# example output
$ ttv list
stream                          viewers   
------------------------------  ----------
demo                            0         

$ ttv list
no live streams.

$ ttv list
stream                          viewers   
------------------------------  ----------
lonely-stream                   0         
my-terminal                     2         
demo                            1        

5. View a Streaming Session

$ ttv view demo alice

# general syntax
$ ttv view <your-session-name> <your-viewer-name>

tmux Demo

Run the tmux-based demo script to launch a streaming session with three viewers. The script creates a 2x2 grid of panes: the top left is the streamer, and the other panes are viewers. You’ll be attached to the streamer’s pane, so any commands you enter will be broadcast live to all viewers in real time.

$ ./scripts/tmux_demo.sh

# exit terminals when done, alternatively run the following to close tmux:
$ make kill-tmux

# alternatively
$ make tmux-demo

Features & Temporal Capabilities

ttv uses a number of Temporal components and features to stream and view terminal sessions. The following table shows how some of Temporal's capabilities enable the list, view, and stream commands:

Command	Temporal Capabilities & Components
list	Uses ListOpenWorkflow to show available sessions, and the GetActiveViewers workflow query to display active viewer counts.
view	Uses the AddViewer signal and GetWebsocketURL workflow query; connects to the WebSocket server in a long-running activity to receive terminal output for viewing.
stream	Uses Workflow.Execute to start a session workflow, the GetWebsocketURL workflow query, connects to the WebSocket server in a long-running activity to send terminal output, and sends the EndStream signal to end the session.

AI Usage Note

AI was used to scaffold CLI commands/subcommands, format output, set up PTY for stream/view commands, implement the WebSocket server in the StartWebsocketServerActivity activity, and help create this README. Most Temporal-related logic - including workflow code, queries, signals, activity logic, and the CLI logic for list, create, and view commands - was written by a human (with occasional help fixing a bug).