I'm used to iTerm2 (or Terminal.app for this case) on OS X. But I want to move to use tmux (or screen, but the problem is similar to both apps).

So my idea is to have a single iTerm tab with a tmux session opened with multiple tabs. To do the transition I have a basic feature I need to configure on tmux: switch the the tab 'n' by using cmd + n (like Firefox, Chrome, iTerm2 itself, etc)

However I can't find a way of mapping the cmd key on the mac keyboard. I first tried to implement cmd as a prefix key, with no success. I've tried setting

set-option -g prefix M-a (hoping for Meta-a)

set-option -g prefix ^a (hoping for ^ to work)

but nothing works. Is this possible? I don't really need to bind the prefix to cmd, but I want to be able to change tmux tabs with cmd+n.

Thank you


You want to invoke a sequence of keystrokes (first Ctrl-b, then n ranging from 0 to 9).

Your best bet is to use a keyboard shortcut utility such as Butler or Keyboard Maestro to do this for you.

Using Butler:

Select + » Smart Item » Keystrokes, configure the hotkey Cmd-1. Press Ctrl-B, then 1 for the Keystrokes. Configure it to be only valid in Terminal (or iTerm). It will warn you that other applications might not like it, but you know that already.

Using Keyboard Maestro:

Create a new group on the left that is only available in Terminal (or iTerm).

Add a new item, triggered by Hot Key Trigger (Cmd-1) and add two Keystrokes to its actions: Ctrl-B and 1.

You might also want to take a look at this topic -- doesn't use Command though, and didn't work for me using Terminal.

From the tmux documentation:

Bind key key to command. Keys may be specified prefixed with ‘C-’ or ‘ˆ’ for ctrl keys, or ‘M-’ for alt (meta) keys. The −r flag indicates this key may repeat, see the repeat-time option.

They don't support a third modifier key.

  • omg what an awesome hack! it works too! used Keyboard Maestro because Butler seems overkill. Thank you! – rubenfonseca Mar 19 '11 at 16:42
  • Keyboard Maestro works wonderfully for this – Sam Selikoff Jul 23 '14 at 14:45

In iTerm2, you can map shortcuts to hex codes that get sent into the terminal. Goto iTerm2 Preferences -> Keys. In Global Shortcut Keys, click the + and add type your desired shortcut like the cmd+1, which will be captured. Then select "Send Hex Code". In the box that appears, type the hex codes that you want sent to tmux separated by spaces. Ctrl-B is 0x02, so for "Ctrl-B 1", type "0x02 0x31". See here for more hex codes: http://www.nthelp.com/ascii.htm

I mapped Cmd with h,j,k,l for moving around between tmux panes, and Cmd with % and " for creating the splits. I'll probably do something similar to move between vim splits with one control key.

  • This is definitely the best answer for those using iTerm2. Thanks! – newUserNameHere Dec 22 '14 at 17:26
  • 1
    For some reason, this isn't working on my iTerm2 build 3.0.2 – jasonszhao Jun 23 '16 at 4:51
  • If this is not working it may be because iTerm2 binds the cmd key to switch-tab by default. Your modifier may be clashing. I had to change the swith tab key to option to get this to work on CMD+n – Surfrdan Jul 29 at 18:10

Special shortcuts can be made with Terminal.app. I just found out the other day, but this may have been possible prior to lion.

Go into Preferences > Settings and click on the "Keyboard" tab. Now you need to add a new keyboard shortcut by clicking on the plus icon below the box. Now you want to set a key combo that "Sends string to shell."

Example: Let's say I want to set M-LeftArrow to be mapped to prefix-p (previous window).

Key: Left Arrow 
Modifier: Option 
Action: send string to shell

Now just type in prefix-p into the input box where prefix is whatever you have set for tmux (I use cntrl-a so the box displays \001p). Note that if you make a mistake, delete characters will be inserted instead of actually deleting characters, so hit the "Delete one character" button to move backwards, in case you mess up.

Special characters I have set to make life easier:

M-Left  > Previous Window
M-Right > Next Window
M-Up    > Enter scrolling mode
M-Down  > Next Pane

You can also modify cntrl-anything and shift-anything, but do remember that these could interfere with your $EDITOR or other programs, so be careful about what special functions might be rendered useless.

Also, note that I could not figure out how to duplicate this functionality in iTerm2.


You may also want to consider the native (but very experimental) integration that iTerm2 offers with tmux: http://code.google.com/p/iterm2/wiki/TmuxIntegration

That way, when you press Cmd-D to split the screen iTerm2 will split the tab for you. This is great, because the split is native, so you can drag the edge in the middle to re-adjust widths, or you can select a pane by clicking. Ditto for new tabs/windows (but the shortcuts are slightly different -- otherwise you'd have no way to add non-tmux tabs).

And like tmux, if you detach and re-attach, everything will be saved for you.

There are two caveats though: * this is a very experimental feature and very flaky for me. * you will have to build tmux yourself (using the archive somewhere on the link above).


  • I know it's been two years, but any idea if this is still working? I followed the instructions at your link, but cmd+D splits iTerm2's panes, not tmux's. – Sam Selikoff Jul 23 '14 at 14:36
  • 1
    @SamSelikoff You have to start it with tmux -CC. – jasonszhao Jun 23 '16 at 4:43

You might also look at this blog post that has very detailed explanations about tmux/iterm integration: http://tangledhelix.com/blog/2012/04/28/iterm2-keymaps-for-tmux/

  • 2
    Web pages disappear and get moved all the time. Please at least summarize the contents of the blog post and give details of its title and author so that your answer doesn't become complelely worthless if the link breaks. – David Richerby Jan 2 '15 at 10:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.