iTerm 2 not honoring key bindings declared in .tmux.conf

Question

I am using the latest stable version of iTerm2 (2.0) with the latest Homebrew build of tmux (1.9a). Unfortunately, my keybindings as declared in .tmux.conf do not work with the iTerm2/tmux combo in "integrated mode" (i.e. when iTerm2 takes over the management of tmux windows and panes). I tried different prefixes (C-b, M-a) as well as different key mappings in iTerm, but to no avail.

Is this indeed an iTerm bug? Or is my expectation that the .tmux.conf keybindings would be carried over to iTerm a false one? Even my tmux command prefix (M-a) does not work!

You may view my tmux configuration file at https://gist.github.com/453ab63c42df976bc2be.

Answer 1

Someone reported a similar bug at iTerm2 Tmux Integration Default Keybindings not working in 2015. The response from the developer George Nachman suggests that keybindings are not supported:

One of the main goals of the tmux integration is that you use iTerm2's keystrokes, not tmux's. If there's a specific workflow that you can't accomplish natively, let me know--there is a lot of power in the ability to remap keys in iTerm2.

Answer 2

As of this change in iTerm2, you can now set a Leader key / prefix in the iTerm2 config which will forward to tmux. You still can't bring up the tmux command prompt, but you can create new windows, panes, etc, and my custom keybinds appear to be in working order.

You can configure the shortcut in Prefs > Keys > Key Bindings > Leader... Once you define a leader, the tmux key combos will become available. I recommend cmd-B as the leader for muscle memory and because cmd-B isn't otherwise in use.

This is what it should look like, note my prefix is the ` key but you should set this to whatever your tmux prefix binding is.

As of this writing the feature is only in the nightly build of iTerm2, so you'll be running alpha code, but assuming nothing goes wrong it should be included in the next stable release (or 3.5beta6).