Simple Remote Pairing with wemux

I have been looking at ways to simplify remote pairing. I was happy to find out about a new project called wemux.

wemux is a script that simplifies the management of shared tmux sessions.


wemux Basics

wemux seeks to facilitate two main usage patterns for shared tmux sessions:

  • Direct user to user connections
  • Multiple users connecting to shared central server (This scenario is likely to be less common, but wemux does include advanced configuration options to enable multi-host capabilities.)

In each case, wemux has a concept of one user being the “host” and others being “clients.” Each wemux “server” is created on its own socket. Common usage patterns are captured by wemux’s three main modes:

1. Mirror Mode

Client is connected in read-only, non-interactive mode. This may be good for live demos, or some forms of remote pairing. NB: You should not rely on this being ‘secure’ — you are still giving another user access to your session.

2. Pair Mode

Client is connected interactively but shares a cursor/window focus with the host. This is probably best for most forms of pairing where users may take turns driving, but always view the same screen.

3. Rogue Mode

This allows clients to connect to a shared session but interact with different windows than the host.


Unfortunately, Wemux isn’t in Homebrew yet, but it there is an open pull request. In the meantime, you can use the formula like this:
brew install https://github.com/downloads/zolrath/wemux/wemux.rb

For those who are not using Homebrew, there are instructions for manual installation.


The Homebrew formula automatically adds the current user to the list of users allowed to “host” sessions. If you’d like to have additional users as “hosts” (or make other configuration changes), running wemux conf will open the configuration file with your $EDITOR. More information on configuration can be found in the wemux wiki.

Adding #(wemux status_users) to your status-right or status-left in ~/.tmux.conf will let you see who is currently connected to the wemux server. This is one of my favorite features. Names with an [m] are connected in mirror (read-only) mode.

Using wemux

Here are some of the basic commands to get started.


  • Host a session: wemux start
  • See who’s connected: wemux users


  • Attach in ‘mirror’ mode: wemux mirror
  • Attach in ‘pair’ mode: wemux pair
  • Attach in ‘rogue’ mode: wemux rogue


If you tend to pair with the same person on a regular basis, you can streamline the process by creating a user for them on your local machine, adding their public SSH key to authorized_keys, and putting wemux pair; exit in their ~/.bash_profile. Then, whenever they connect to your machine, they automatically join your wemux server in pair mode.