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
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)
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
- Neovim: pair-ls.nvim
- VS Code: pair-ls-vscode
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.
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.
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).
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"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
Most of these are paid apps/services, though many of those have a free tier.
- Screen sharing
- Web editor
- Replit (paid)
- Codeanywhere (paid)
- CodeSandbox (paid)
- Cloud9 (only AWS usage fees)
- Red Hat CodeReady
- Editor plugin
- Microsoft Live Share (VSCode, Visual Studio)
- Floobits (IntelliJ, Sublime, Atom, Neovim, Emacs) (paid)
- Duckly (VSCode, IntelliJ) (paid)
- CodeTogether (VSCode, IntelliJ, Eclipse) (paid)
- Teletype (Atom)
- instant.nvim (Neovim)
- crdt.el (Emacs)
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).