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:

     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?


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?

  • 1
    tmux does support copy and paste, see capture-pane and save-buffer and related commands
    – thrig
    Jul 4, 2018 at 13:44
  • @thrig Sorry what I read was wrong; tmux does support it but does not the mouse-based copy & paste. It seems feasible via third-party plugins like tmux-yank, though I have not tried it yet.
    – Blaszard
    Jul 4, 2018 at 13:54
  • Do you already have a tmux session running when you try tmux -C or tmux -CC?
    – JigglyNaga
    Jul 4, 2018 at 17:07
  • @JigglyNaga I tried both situations but the result was consistent.
    – Blaszard
    Jul 4, 2018 at 17:31
  • @Blaszard if you enable mouse support, you can enable copy by highlighting with your mouse.
    – rovr138
    Jul 4, 2018 at 18:08

5 Answers 5


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.

  • 7
    tmux - Control mode says "It was designed and written by George Nachman and allows his iTerm2 terminal to interface with tmux and show tmux panes using the iTerm2 UI"
    – Tun
    Oct 10, 2020 at 7:03

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.

  • 1
    This is silly but I want to thank you for explaining it in a different way from everyone else. In doing so, you gave me a pretty cool idea. I sometimes tinker on little programs I make that implement terminal UIs (little reinventions of curses pretty much). So, what I'd been doing with this was assembling little libraries used for unit tests that basically spawn panes inside tmux, because it is a nice PTY sandbox and is capable of displaying test outputs in parallel on one screen, and nothing revs my engine like tests running in parallel. Now I know to use this mode to command the tmux!
    – Steven Lu
    Aug 22, 2022 at 7:57

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.


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

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.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .