GitHunt
PI

pipoprods/pair-ls

Editor-agnostic remote pair programming

pair-ls

Pair-ls is a lightweight, editor-agnostic tool for remote pair-programming. It
allows you to easily share the files you are working on in a read-only manner.
Pair-ls is not a collaborative editor. If you're wondering why you would use
pair-ls, read the comparison section.

pair.mp4

Installation

You can download a binary from the releases
page

If you want to build from source, git clone this repo and run yarn build
(you will need to install
yarn and go build tools)

Setup

If the option is available, it is recommended to use a plugin for your editor.
If your editor is not yet supported, you can still use pair-ls with minimal
configuration (also file an issue to ask for support). Using pair-ls without an
editor plugin will mean some degradation in the cursor tracking.

Editor plugins:

See the link for installation instructions

Generic Setup - any editor

pair-ls supports any editor with a LSP
client.

Configure your LSP client to run this command as a server: pair-ls lsp -port 8080.
Now you can visit http://localhost:8080 to see a mirror of your code. For more
info on how to share this page, see Sharing.

Sharing

Running pair-ls lsp -port 8080 is an easy way to get started, but how can you
share this across the internet?

The quickest way with no setup required is to use WebRTC
connections.

You can use ngrok or a server you control to forward your
web port.

If you'd prefer the server act as a full intermediary, you can set up a relay
server.

For completeness, you can also set up a signal server, but
that has all the drawbacks of both WebRTC and relay server, so it's not
recommended.

Password protection

If your pair-ls webpage is visible on the public internet, you should make sure
to enable password protection to prevent anyone on the internet from seeing your
code. Simply provide a password, either via the config file or
with the environment variable PAIR_WEB_PASS. The webserver will now require
this password before allowing access. You should also make sure your site it
hosted over https so the password can't be trivially sniffed (see
encryption).

Configuration

The configuration file can be found at $XDG_CONFIG_HOME/pair-ls.toml. Most
values can be specified on the command line instead, if you prefer (run
pair-ls for detailed help).

# Default log file is $XDG_CACHE_HOME/pair-ls.log
logFile = "/path/to/file.log"

# For the relay server. When false (the default) all files are cleared from the
# server when the last editor connection is closed.
relayPersist = false

# The static site hosting the WebRTC connection code
staticRTCSite = "https://code.stevearc.com/"

# The one-time WebRTC connection token generated from the static WebRTC site
# Editor plugins provide a better way to pass this in, so only use the option if
# your editor doesn't have a plugin.
callToken = ""

[server]
# If provided, will require password auth from web client
webPassword = "passw0rd"
# If provided, will require connecting pair-ls LSP to provide this password in
# the [client] section (only used for relay & signal servers)
lspPassword = "secur3"
# If provided, will secure all connections with TLS
certFile = "/path/to/cert.pem"
# If the private key is not in the certFile PEM, you can pass it in separately here
keyFile = "/path/to/cert.key.pem"
# If true, will require pair-ls LSP to provide a matching client cert.
# This is the certFile under the [client] section.
requireClientCert = false
# PEM file with one or more certs that pair-ls LSP can match
# (when requireClientCert = true; only used for relay & signal servers)
clientCAs = "/path/to/pool.pem"

[client]
# Provide this certificate to the relay/signal server when connecting
certFile = "/path/to/cert.pem"
# If the private key is not in the certFile PEM, you can pass it in separately here
keyFile = "/path/to/cert.key.pem"
# If the relay/signal server requires a password, supply it here
password = "secur3"

Comparison

Pairing tools fall into roughly 3 categories: screen sharing, web
editors, and editor plugins.

Screen sharing: Easiest to use, with the worst functionality

  • Pros:
    • Very easy, they're built into the tools you're already using to call your partners
    • You see exactly what the sharer is doing, across all windows and applications
  • Cons:
    • Video artifacts can make text hard to read
    • Text is often too small unless the sharer increases the size dramatically
    • Viewer has no control over what they're looking at
    • Read-only sharing

Web editor: Easy to share, but only if you buy into their ecosystem

  • Pros:
    • No installation required
    • Often have collaborative editing functionality
  • Cons:
    • You have to use their editor
    • You have to use their entire editing ecosystem, since it's not simply working with files on your own computer

Editor plugin: Best experience as long as everyone's preferred editor is supported

  • Pros:
    • You can use your own editor
    • Often have collaborative editing functionality
  • Cons:
    • Requires installation
    • Your editor has to have a plugin available
    • Everyone has to be using the same editor
    • Only shares editor state, nothing in other windows

Pair-ls: Sacrifices features of editor plugins for broader support

  • Pros:
    • You can use your own editor
  • Cons:
    • Requires installation
    • Read-only sharing
    • Only shares files. You can't see open terminals or anything else the sharer is doing in the editor

Alternatives

Most of these are paid apps/services, though many of those have a free tier.

Technical Overview

pair-ls is implemented as a Language
Server, so it receives
file open and edit information from any LSP client. It is a simple matter to
then expose that information to a web client, or to replicate it to a relay server.

Editor plugins add extensions on top of LSP to allow for enhanced features (see
differences in Setup) that aren't possible with the current state of
LSP (e.g. tracking cursor movement).

Contributors

ST
MIT License
Created December 9, 2022
Updated December 9, 2022