What is the "control mode" in tmux?

Question

According to man tmux to check the launch option:

-C: Start in control mode (see the CONTROL MODE section). Given twice (-CC) disables echo.

Then in the control mode section of the man tmux, there is the following description:

CONTROL MODE
     tmux offers a textual interface called control mode.  This allows
     applications to communicate with tmux using a simple text-only protocol.

     In control mode, a client sends tmux commands or command sequences
     terminated by newlines on standard input.  Each command will produce one
     block of output on standard output.  An output block consists of a %begin
     line followed by the output (which may be empty).  The output block ends
     with a %end or %error.  %begin and matching %end or %error have two
     arguments: an integer time (as seconds from epoch) and command number.
     For example:

           %begin 1363006971 2
           0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
           %end 1363006971 2

     The refresh-client -C command may be used to set the size of a client in
     control mode.

     In control mode, tmux outputs notifications.  A notification will never
     occur inside an output block.

I'm not sure what it means, but at least as far as I try a few commands and try to see the looks and feels of it via (tmux -CC), it looks like the same as when I launch via tmux new-session.

So what is the "control mode" and what makes it different from the normal mode?

---

EDIT

I found that the session and the window that was launched via the control mode (-CC) does not react to the keyboard shortcut of the tmux commands, such as window split. So what is the point of using the control mode in the first place?

Answer 1

I'm on a Mac and I use iTerm2. As far as I know it's the only terminal emulator that has tmux integration. You start by doing tmux -CC and iTerm will control your tmux session. This means you can use iTerm2 normally as you usually do (CMD-D to split a window vertically, CMD-SHIFT-D split it horizontally). You can use your mouse to reposition the panes instead of using C-b {. You don't need to use the prefix at all. You don't have any problems with copy and paste either when you're dealing with panes.

tl;dr Using tmux -CC allows you to use tmux "natively" on terminals that support it. So far I haven't seen any linux terminals that support it, only iTerm2 on a Mac.

Answer 2

The interesting aspect of control mode is that you can write a background process that listens to a real tmux process. It gets notifications of things happening in the real tmux, and it can then send commands. If you use 2 terminals and run a normal session in one

tmux new -s mysession

and in the other

tmux -C attach -t mysession

then when you split windows, add new ones, or close them in the normal tmux you will get lines like

%layout-change @2 91a8,80x23,0,0[80x11,0,0,5,80x11,0,12,7]
%window-add @3
%window-close @1

in the control tmux, to which you can react by writing a program. To help there is a python library to exploit this mechanism. See the examples there.

Answer 3

tmux control mode is not intended to be used directly. It changes tmux's behavior from being interactive to being more like a "proxy". The way it's intended to be used is by being invoked in a terminal emulator that supports this feature, such as iTerm2. Unfortunately, there are no Linux terminals that currently support control mode. (Though Terminator seems to be making progress.)

This is a killer feature.

As an example of how it's used, consider a workflow that involves sshing to a remote server. While you're working on that server if you want to start another session you must create a new ssh connection (not difficult, but a hassle, and a minor context switch).

Enter tmux.

tmux can create multiple remote sessions over your single connection (hence the "multiplexer" in the name), and display them in multiple tabs and split panes. This certainly works, but I find the key combinations required to navigate tmux to be just cumbersome enough to make me wish for something better. If only there were a way for tabs and split panes on the remote to be just as fluid and natural as in a native, local terminal emulator...

Enter tmux -CC.

tmux control mode allows a terminal emulator that supports it to control the tmux session by issuing commands directly to it (see meuh's answer). For instance, you could open a new pane/tab in your remote session, but using the same key strokes/commands as you would for opening a local pane/tab, and it would be a local pane/tab, but connected to your remote session.

Answer 4

You are seeing similar results from tmux -CC as you would from tmux new-session because you didn't specify a command, so tmux uses the default, which is new-session:

command [flags]

This specifies one of a set of commands used to control tmux, as described in the following sections. If no commands are specified, the new-session command is assumed.

Adding -CC doesn't appear to change that. To control the existing session, you should attach to it in control mode:

tmux -C attach

Answer 5

To my understanding, control mode is like normal client. The difference is in control mode. tmux client read command from stdin and send to tmux server. In the reverse direction, client in control mode receives message from server, and print to stdout instead of draw the terminal as normal client does.