How We Use tmux for Remote Pair Programming

Tuesday, July 17, 2012

Update 07/18/2012: We have added tmux-vim autosaving support as a Vim plugin. It’s available here: https://github.com/pivotal/tmux-config

Update 07/20/2012: There is a lively discussion on Hacker News about this post in addition to the comments below.

tmux is the cool kid on the block for remote pair programming, as long as you are using a terminal based editor such as Vim or Emacs.

There is no shortage of tutorials and guides regarding how to use tmux, thus my only introduction to tmux will be this: tmux is a terminal multiplexer and supports shared terminal usage.

Our large software project used tmux regularly for remote pair programming and settled on a configuration that has worked well for our team. Read on to learn about tmux’s advantages and disadvantages vs. desktop screen sharing, why and how we used it, and how we addressed the many challenges of remote pairing using tmux.

Advantages vs. Desktop Screen Sharing

Fast! tmux has the least latency of any collaborative code editing we have used
Addictive usage model: tmux’s multiple terminal pane usage model is very handy in general. Some of us now use tmux even when we are not remote pairing
No extra heavyweight software: if you have tmux and ssh access you’re good to go

Disadvantages vs. Desktop Screen Sharing

Requires ssh access and thus possibly a VPN
Extra overhead of learning and using tmux commands
Lack of desktop friendly UX, such as mouse support, function keys, ⌘ key
Only for terminal based editors, such as Vim and Emacs
Might still need desktop screen sharing for GUI-based tools and tasks: shared web browser for web development, etc.

Why We Used It for Remote Pairing

Due to network latency GUI-based desktop screen sharing was intolerably slow for coding. tmux made network latency a non issue. My personal experience was that tmux + Vim was so fast when working remotely that it was usually indistinguishable from coding locally.

Monitor Setup

We use two monitors: the iMac’s main 27″ monitor and a large (usually at least 24″) LCD rotated vertically.

We usually had iTerm running a shared tmux session on the large 27″ display and a desktop screen sharing session on the vertical display. The vertical display usually had the shared web browser visible since we were usually doing web development.

Challenges and How We Addressed Them

Most of our in-office developers only used tmux when remote pairing: the majority of their development was in-person pair programming using MacVim and “normal” tabbed iTerm. The occasional switch to terminal-based Vim within tmux and a bunch of tmux terminal panes was the most challenging aspect of using tmux as part of our development stack. The major difference were:

Automatic saving within MacVim was lost
No mouse support
Scrolling onerous in tmux
Copy-paste actions onerous in tmux
MacVim keymapping not fully supported in terminal Vim
Learning tmux specific commands

Read on to see how (or if) we addressed the above challenges.

Automatic Saving

Once you have automatic saving it’s tough to give it up. Our buffers automatically saved whenever MacVim lost focus. After quite a bit of work we were able to add automatic Vim saving support within tmux. It’s not as good as MacVim’s autosave, but it’s pretty close. Please see this Github pull request for how to set up automatic saving. (Note, I’ll update this post as the pull request progresses.)

Update 07/18/2012: Our tmux-vim automatic saving Vim plugin is available here: https://github.com/pivotal/tmux-config. We’ve also integrated it into our vim-config configuration here: https://github.com/pivotal/vim-config.

Mouse Support

By default tmux has very little mouse support. We enabled significant mouse support within iTerm by customizing our .tmux.conf:

Selecting tmux panes
Resizing tmux panes
Scrolling

See this .tmux.conf template for more, but here’s the interesting section:

 # ~/.tmux.conf
 # Enable mouse support (works in iTerm)
 set-window-option -g mode-mouse on
 set-option -g mouse-select-pane on
 set-option -g mouse-resize-pane on
 set-option -g mouse-select-window on

Note that iTerm supports this configuration. We cannot vouch for Mac’s Terminal application’s level of mouse support.

OS-Level Copy-Paste

Highlighting with the mouse triggers tmux’s text selection, which is not OS X’s highlighting, and thus ⌘+c will not copy the highlighted text. Though we never fully solved this issue there is a workaround: hold down the ⌥ key (ALT/Option) while highlighting to trigger OS X’s selection — ⌘+c will now copy the text.

tmux selection — OS X will not copy this

Holding ⌥ — OS X will copy this!

Unfortunately this technique does not respect tmux’s panes and will select across the entire screen, but it’s better than nothing.

MacVim vs. Terminal Vim Keybindings

Why did MacVim and Vim have different keybindings if both use the ~/.vimrc file? The answer is the ⌘ key. To ease the transition from RubyMine and TextMate to MacVim we mapped many common ⌘-based keybinding which were unavailable in terminal-based Vim. My personal advice is to stay away from the ⌘ key if your team uses both MacVim and terminal Vim, but if that’s not possible at least make an extra <leader> KEY mapping for everything that uses ⌘.

Take a look at our sophisticated ~/.vimrc setup, including the keybindings file, where ⌘ bindings are paired with non- ⌘ keybindings.

Learning tmux-Specific Commands

There’s no way around this one. Though mouse support means one can avoid the tmux-pane selection and scrolling commands I highly recommend learning tmux well if you are using it consistently.

In practice we only use a handful of tmux commands often:

CTL+b % – new vertical split
CTL+b " – new horizontal split
CTL+b o – switch to other pane. Repeat to cycle through.
CTL+b c – create new tmux tab/window
CTL+b n/p/l – switch to next, previous, or last tmux tab/windows
CTL+b [ – Enter scroll/copy mode

Here are a couple of fun ones:

CTL+b SPACE – change arrangement of panes. Repeat to cycle through various arrangements.
CTL+b w – list tmux tabs/windows
CTL+b , – rename tmux tab/window

Once your team gets the hang of it they might even prefer the multiple tmux-pane workflow to a multi-app, multi-tab setup.

It’s a Fast Paced World

With such a plethora of remote pairing software and configurations it’s impossible to keep up. We would love to hear about your own experiences remote pairing with tmux and how you might improve upon our own techniques and configurations. Please post comments and let us know what you think.

Integrating Remote Developers: Intuitive, Flexible Video Conferencing

Joe Moore

Friday, July 13, 2012

I recently blogged about about integrating remote developers with large development teams. An important but finicky part of bridging the gap between remote developers and the rest of the team is video conferencing.

How hard can this be? It’s Skype, right? While most techies know how to use Skype to make video calls, the difficulty is managing headsets, external microphones, external speakers, and switching between all of these frequently throughout the day. Despite what Apple might tell you, it does not “just work”, especially Skype, which has a particularly baffling user interface.

Early in our large project’s history the following scene played out frequently:

Office developer sits down at a workstation and Skype’s a remote developer.
They can’t hear each other!
Office developer finds headset is unplugged, plugs it in to Skype laptop.
Still can’t hear!
Office dev opens the Mac sound preferences, clicks around a bit.
Still can’t hear!
Office dev dives into Skype sound preferences… Ah-ha! Select headset.
Still can’t hear!
Remote developer starts messing with his own preferences, settings, cords…
Bingo! Finally, they can hear each other, but suddenly…
Someone in the office needs to talk to both developers.
Office dev starts changing audio settings again, plugging/unplugging stuff…
After several minutes a group conversation can be held.
Group conversation is over. Go to Step 1.

The Need: Intuitive, Flexible Video Conferencing

Actually, it’s mostly about the audio: the video usually works fine. We needed a means to easily switch between pairing-mode and group-conversation-mode — that is, between headphones + mic and external speakers + external mic. Above all else we wanted to avoid constantly changing software preferences. We needed something as easy as pressing a button or plugging/unplugging a single jack.

So far we have found two solutions that work well:

Solution 1: External Speakers with Headphone Input: An external microphone, external speakers with a headphone jack, and regular “music” headphones.
Solution 2: Seamless USB Audio Input Switching for Skype: An external microphone, external speakers, a USB headset, and a bit of special Mac and Skype configuration.

Read on for more details.

Solution 1: External Speakers with Headphone Input

This solution relies upon a high quality external USB mic for both pairing and group conversations. Personally this worked fine for me — the background noise in the office was actually useful, not overwhelming, and I enjoyed hearing bits of the conversations going on in the office. Others might find the background noise annoying.

Connect a high quality external mic (such as a Blue Snowball) and external speakers to the Skype machine. The speakers must have an external headphone jack.
Configure the Mac and Skype to use the Snowball mic
When pair programming: plug your headphones of choice into headphone jack on speakers
For group conversations: unplug headphones. Voilà! Speakers will be live.

That’s it! Toggling between pairing and group conversations is as easy as unplugging the headphones.

Pros

Simple setup
Intuitive to use
Uses external mic rather than headset mic – remote can hear background conversations

Cons

Uses external mic rather than headset mic – background noise possibly an issue.
Sharing in-ear headphones/earbuds is icky. People should probably use personal headphones.

Solution 2: Seamless USB Audio Input Switching for Skype

For a normal remote pairing scenario the computer’s audio priorities should be as follows:

Headset microphone, headset headphones: remote pair programming.
External microphone, external speakers: group conversations including remote developer.
Internal microphone, internal speakers: default, no extra hardware.

Managing this audio setup would be as easy as plugging and unplugging your USB headset. When pairing with a remote developer, plug in the headset for a quiet, private pairing experience. When a group of people arrives at your desk and need to speak with both you and the remote developer, simply unplug the headset to activate the external hardware. When the group conversation is over, plug the headset back in.

Simple. Intuitive. Low-overhead.

Unfortunately, your computer doesn’t know about these priorities. Also, Skype has its own audio input/output settings independent from the computer’s OS-controlled settings.

Luckily both the Mac OS and Skype are “trainable” and will respect the above priorities if you know how to teach them. Note that Skype takes a “hint” from your Mac on how to switch inputs and outputs. Thus, we must train them both at the same time. Here’s how:

Open both the Mac Sound System Preferences and Skype’s Audio/Video preferences. No external Audio devices should be detected.
(Click for a larger image)
Plug in the external mic. Once it is detected by both the Mac and Skype select the mic in both Mac and Skype preferences.
(Click for a larger image)
Before continuing, Close, then reopen the Skype Audio/Video preferences. You know, just to make sure it sticks.
Plug in your USB headset. Once it is detected by both the Mac and Skype select the headset in both Mac and Skype preferences.
(Click for a larger image)
Close, then reopen the Skype Audio/Video preferences. Is this needed? I don’t know… maybe. It’s Skype.
Test the configuration: Unplug your USB Headset. Skype and your Mac should automatically switch to using the external mic. Plug the USB headset in again. Skype and your Mac should automatically switch to using the USB headset again.
(Click for a larger image)
If it didn’t work, unplug everything, quit System Preferences and Skype, and start over.

Overall this is my preferred audio setup, though it takes a couple of minutes to set up and can be confusing the first time. But, once it’s set up, the configuration is usually solid and you rarely have to touch it again. Also, unlike the headphones-jacked-into-speakers technique, the headset mic is fully utilized for the best audio quality. You can also plug external speakers into the computer’s headphone jack without confusing the computer or Skype.

Pros:

Intuitive to use
Highest audio quality for both developers
No configuration changes after the first time

Cons

Confusing “training” process
New audio hardware might require re-training of Mac and Skype

What Do You Use?

Do you use a cool A/V setup? Tell us about it! We love to try new things. We’re still on a quest to find the best iPad-based A/V configuration. With any luck we’ll report back on that soon.

Integrating Remote Developers into Large Teams

Joe Moore

Thursday, July 12, 2012

I’m obsessed with remote pair programming and remote collaboration. I’ve even given tech talks about remote pair programming. Most teams with which I’ve worked remotely are small — usually around four to six team members total — but for the past 10 months I have remote paired on a project of up to 30 developers. While the majority of the team was co-located in our NYC office, five of us were remote. Over that time we have tried many different remote collaboration and pairing setups and feel we’ve settled on a configuration that supports daily pair rotation with minimum overhead.

Daily Standup Meetings

We set up a team Skype account and paid for Skype group video. Each morning the team would gather for standup in a large conference room and call us from the group video account.

It can be difficult for the remote members to hear everyone in such a large room. We used a Blue Snowball mic to aid with this, and it worked well so long as nobody unplugged it.

We had a team whiteboard where we would list technical tips, tricks, and cries for help. Every day someone would send the group a photo of the board. I’m sure we could have come up with a more technical solution but this has worked well for us, though it does take some extra effort.

If remote team members had items for the standup board they would simply speak up towards the end of the meeting; a scribe was taking notes and emailed them to everyone afterwards.

Dedicated Workstations

We settled on having dedicated remote pairing workstations in the NYC office, one for each remote developer. This is a departure from the norm. At Pivotal we swich pairing stations frequently and nobody (or everybody) “owns” a particular machine. For practical reasons the remote person really needed to own a single station to make remote pairing as efficient as possible.

Minimizing Setup Overhead

Remote pair programming often requires a bit of setup: configuring Screen Sharing, setting up tmux, launching and logging in to Skype, etc. With dedicated remote pairing stations this setup can be done once early in the project and (usually) left alone. Time spent on this overhead is minimized, and pairing could start immediately.

Virtual Presence

At Pivotal Labs, our offices have an open floor plan. To find someone you need only stand up and look around for them. But what about when you need to talk to Joe-in-Atlanta? Who’s he pairing with today?

A dedicated workstation for each remote developer becomes their virtual presence in the office. Everyone on the team knows where to find Joe-in-Atlanta. This is important not only for other developers, but also for product manager, project managers, designers — the entire team. My station was called “Little Atlanta” and we referenced it often in conversations: “Joe, I need to talk to you after standup today. I’ll meet you at Little Atlanta in a few minutes.”

Extreme Remote Pairing!

Occasionally two remote developers would remote pair for the day. What did we do then? We usually chose one of our dedicated NYC office stations and paired through that machine rather than our local (that is, home) machines. Why? Just as if we were physically in the office we wanted other developers to be able to see what we were doing and help us if needed.

We made ourselves available by setting up a group Skype call between ourselves and the workstation “Skype laptop” and letting everyone know where we could be found. This worked very well. Using this video conference we could ask for help and team members could seek us out as well.

Resources

Group Video Chat from Skype
tmux — terminal sharing for terminal-based pair programming
Snowball USB Microphone
Training Skype to Automatically Switch Between Audio/Video Inputs
Antoher “Skype Laptop” setup

Syncing IntelliJ Android .apk Files Using Dropbox

Joe Moore

Thursday, June 16, 2011

During a typical day of Android development we compile Android applications (.apk files) dozens of times, deploying to emulators and devices simply by pressing the Run button in IntelliJ. This is great for our in-office developers, but it’s more difficult for our remote-pairing developers to install those same .apks on their own emulators and phones. As a remote developer, I wanted seamless, instant access to all .apks we build during development. Using Dropbox and some IntelliJ configuration changes I now have all .apks we build available for me to install on my local emulators and phones just seconds after we build them on our development machines, 2500 miles away.

Dropbox

Many developers already know about Dropbox, the fast, super-secure file sharing service. I installed Dropbox on all of our machines and created Dropbox directories for each machine our team uses. They happened to be named after streets in San Francisco, Boulder, and Atlanta.

Dropbox dir

Symlinks

Next, on each machine, create an apk symlink to the appropriate Dropbox directory within IntellJ’s ide_bulid directory.

~/workspace/PivotalAndroid$ ln -s ~/Dropbox/PivotalAndroid/grafton_apks ide_build/production/PivotalAndroid/apk

Next, tell IntelliJ to output .apks to that directory. We have to be careful here, especially if you check your .iml file and .idea directory into source control. You can select Project Structure => Facets => (Your Android Module) => Compiler => APK Path:, but this will follow the symlink you created and change your project’s .iml file to include the machine-specific Dropbox directory, and thus a merge conflict on each machine.

Instead, you can manually edit the appropriate value in your .iml:

<!-- old value: -->
<option name="APK_PATH" value="" />

<!-- new value, where '/apk/' is the symlink to Dropbox: -->
<option name="APK_PATH" value="/ide_build/production/PivotalAndroid/apk/PivoalAndroid.apk" />

Note: IntelliJ will sometimes reset APK_PATH back to either the default or to the Dropbox dir. Watch for this and fix the path again when needed. We run into this once per week or so.

Result: Updates Galore!

Now I have .apk files streaming in from three different development machines; as a bonus, each development machine is synced with each other, so we all have access to all .apks. Whenever I want to install the latest .apk from another pair (or my own) onto my local test phone I simply pass the machine name into a script:

#!/usr/bin/env ruby
system "adb -d install -r ~/Dropbox/PivotalAndroid/#{ARGV[0]}-apks/PivotalAndroid.apk"

Thus, scripts/apk cedar installs the latest .apk file created on our machine named “cedar”.

Best Remote Pairing Settings 2008

Chad Woolley

Thursday, December 18, 2008

About a year and a half ago, I made two posts on the “Best Remote Pairing Settings”.

A Remote Pair

The world has moved on, and so has the state of the art in remote pairing. I work remote 75% of the time, so this is an important topic for me. The setup we have now is working pretty good, so I wanted to describe it for the benefit of other remoties. Also, I’m only going to describe one specific setup – the one that is currently working best for me. So, here it is:

Computer and OS

Macintoshes running OS X 10.5 (Leopard) and maxed out on ram (at least 2 gig+), with a second monitor, ideally a 24″.

Pivotal uses 24″ iMacs exclusively. This lets you have your remote pair’s screen up on the second monitor, while still having the primary iMac screen available for local work (configuration, looking stuff up, temporary soloing, etc). You must be very disciplined and up-front – you should be explicit about when you are paying attention to your pair and when you are not, but that’s a whole other topic.

Also, at my home office, I have an iMac which I use for screen sharing, but I usually run the Skype audio/video on my MacBook. This takes the CPU load off of the iMac, which is important, because Skype is a CPU hog (more on that later).

Screen Sharing Software

Apple Screen Sharing which comes with Leopard.

Apple has done a nice job making the screen sharing app perform well, and the most important feature for any remote pairing screen sharing tool is performance. In my opinion, it performs better than any other VNC client on any platform, assuming you have a good connection (possibly excluding some windows native-video-hook solutions like UltraVNC or Remote Desktop, but there’s no way I would ever use Windows for development). All VNC clients which use the standard RFB Protocol can only be tweaked so much, and will only give you mediocre performance. However, there are several annoying bugs and gotchas with Apple Screen Sharing:

It is hard to find. Look under /System/Library/CoreServices/Screen Sharing.app. It is easiest to use Spotlight/Quicksilver or drag it to your dock. Supposedly you can start it with iChat but this never worked for me, I had to run the app directly.
Most of the useful features are disabled by default with no way to access them via menu or toolbar buttons. This is an amazingly annoying decision by Apple, but it is fairly easy to hack the toolbar buttons back into existence. Here is a Macworld tutorial showing two options.

In general, it seems that the best remote-control tools are those with some sort of native/low-level GUI integration: Leopard Screen Sharing, NoMachine NX, UltraVNC, Windows Remote Desktop, etc. Higher-level platform agnostic tools (like standard VNC/RFB protocol) just don’t perform as well – no matter how much you tweak the available color/depth/etc settings.

Audio/Video Hardware

Plantronics GamePro USB Headset

This is a great headset, and you need a really good headset if you are going to wear it all day, every day. Cloth earpieces, mic cover, very long cord, and I believe it also has some echo cancellation built in (there’s a huge box inline in the cord that does something). Unfortunately, I don’t see the exact model on the Plantronics website anymore. It may be replaced by the “GameCom” model, but I haven’t tried this.

Built-in iMac Microphone/Speaker

The built-in microphone and speaker on iMacs is really good. If you want to talk to a group of people remotely (for example, project standup), this is the way to do it. However, if the ambient noise gets too much, you can switch back to the headset.

You can even combine the two. For example, if you want to hear the surrounding conversations, but your pair is having trouble hearing you over the noise, then can wear the headset, but still keep the input set to the built-in iMac mic.

Sometimes you will need to adjust the input/output levels to reduce echo, and the remote pair should handle this themselves – they know what it sounds like.

Built-in iMac camera

Just like the built-in iMac mic and speaker, the iSight is a great camera. A detached iSight is just as good, if you want to be able to move it around or aim it without moving the computer.

Audio/Video Software

Skype

Skype is the best I’ve found. It does have drawbacks: it crashes rather frequently, it sucks a lot of CPU, it can do bad things to your network if you become a supernode, and it doesn’t support video in conferences.

However, it has great echo cancellation, it is free, and easy to use. The echo cancellation is really the most important thing – all other audio conferencing tools I’ve tried seem to have much more issues with echoes – even when you are using echo-cancelling hardware devices or speakerphones.

Some people seem to like iChat, but I have not had good luck with it. It takes longer than Skype to connect, the echo cancellation is not as good (sometimes it is, sometimes not), and most annoyingly, it doesn’t always close. I often end up having to force quit it – which is even more annoying when it is stuck on a freeze-frame of me making a stupid face or scratching my nose. Skype never does this – video always goes away when you shut your video or kill the call.

iChat has video conferencing, though, which is a benefit. You can sort of work around this by putting up the video preview in iChat, and having multiple remote people connect to view it via screen sharing, if you only want to see video for one of the participants (e.g. a couple of remote people calling in to a company meeting).

Network, Network, Network

This is the last but most important component to usable remote pairing. A fast, low-latency network connection is critical. I don’t have any numbers, but I believe that low latency is at least as important as high bandwidth. I also (without proof) believe that ping is not necessarily a good indicator of latency – I bet it is possible to have a good ping (ICMP) but still have issues with TCP/UDP latency. Who knows what’s going on in the tubes between you and your pair? Any data, tools, or insight on this would be very welcome.

As empirical evidence, for the first year or two at Pivotal I had DSL, which was pretty fast with low ping, but had continual problems with performance. Then, I switched to corporate-grade cable with a significantly higher bandwidth limit. My experience improved dramatically and my problems decreased greatly. This was about the same time I switched to Leopard screen sharing, so I think that had something to do with it, but the better connection definitely made a huge difference. Again, sorry I don’t have more concrete numbers, but I will guarantee that the better your connection, the better your experience will be.

Also, if you are in a corporate network, this may cause you problems. Even if there is a big pipe to your location, there may be saturation on your local LANs or intranet. Again, no hard data, but this is backed up by experiences of having consistently better performance when connecting to another remote at-home pair with a good connection as opposed to connecting to the Pivotal office which has a much larger pipe.

Remote Pairing Presentation at RailsConf 2008

At RailsConf 2008, Michael Buffington and Joe O’Brien did a good presentation on Remote Pairing. This is a very good presentation which covered many important aspects of remote pairing, as well as presenting some innovative ideas. Unfortunately, I don’t see a link to the preso, please post one in the comments if you have it.

Summary

This isn’t meant to be the be-all, end-all set of recommendations, it’s just what is working pretty well for me now. By “pretty well”, I mean that I can be an efficient pair, even when I’m driving the remote machine.

However, I’ve learned to cope with a lot, and adapted my work habits. It has forced me to become much better at communication, and describing what, why, and how I am programming. In general, though, I believe that remote pairing is physically, emotionally, and intellectually taxing. Regardless, I personally deal with it because Pivotal is such an awesome place to work and Pivots are such incredible developers. Most importantly, I come out in person for a week every month, attend retrospectives and brownbags, have some beers, and generally stay “entangled” with the rest of the team in person. If I was 100% remote, I don’t think I could handle it long-term.

So, I hope this helps out all the other remoties out there. Please let me know what you think, your experiences, and what works well for you.