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

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.

  • Brian Kelly says:

    How do you get the graphica characters (arrow dividers) in your status-left?

  • Brian Kelly says:

    How do you get the special characters (angled blocks) in your status-left?

  • Brian Kelly says:

    Also, your comment form provides no feedback as to if my comment was received, being moderated, etc. So I may have posted the same question twice.

  • Matt Furden says:

    Hi Brian, creator of wemux here.

    The session on the left in the example screen shot uses a patched font from the vim-powerline project.

    I’ve included the relevant settings from my tmux.conf file in a gist.

  • Brian Kelly says:

    Thanks, Matt. I’ll check out the powerline project.

  • […] we’d like to do is install and configure tmux and Matt Furden’s wemux script for managing shared tmux […]

  • Comments are closed.