feat: tmux control mode with layout sync, capture, and pane management

doc/terminator.1

@@ -1,7 +1,7 @@
 '\" t
 .\"     Title: terminator
 .\"    Author: [see the "AUTHOR(S)" section]
-.\" Generator: Asciidoctor 2.0.18
+.\" Generator: Asciidoctor 2.0.23
 .\"      Date: 2023-04-01
 .\"    Manual: Manual for Terminator
 .\"    Source: Terminator
@@ -68,7 +68,7 @@ Start with a fullscreen window.
 .sp
 \fB\-b\fP, \fB\-\-borderless\fP
 .RS 4
-Instruct the window manager not to render borders/decorations on the
+Instruct the window manager not to render borders/decoration on the
 Terminator window (this works well with \-\-maximise).
 .RE
 .sp
@@ -166,6 +166,20 @@ addition to \-\-debug\-classes, only the intersection of the two lists will
 be displayed.
 .RE
 .sp
+\fB\-\-tmux\-attach\fP[=\fISESSION\fP]
+.RS 4
+Attach to an existing tmux session in control mode. If SESSION is not
+specified, attaches to the most recently used session. Terminator will
+mirror the tmux session layout, with splits displayed as panes and
+tmux windows as tabs.
+.RE
+.sp
+\fB\-\-tmux\-new\fP=\fISESSION\fP
+.RS 4
+Create a new tmux session with the given name and attach to it in
+control mode.
+.RE
+.sp
 \fB\-\-new\-tab\fP
 .RS 4
 If this is specified and Terminator is already running, DBus will be
@@ -178,6 +192,54 @@ If this is specified and Terminator is already running, DBus will be
 used to toggle Terminator window visibility. Usable under Wayland to
 replace hide keyboad shortcut.
 .RE
+.SH "TMUX CONTROL MODE"
+.sp
+Terminator can act as a native GUI frontend for tmux sessions using
+tmux\(cqs control mode (\fB\-C\fP flag). There are two ways to use this:
+.SS "Command line attach"
+.sp
+Launch Terminator with \fB\-\-tmux\-attach\fP or \fB\-\-tmux\-new\fP to connect to a
+tmux session. The tmux layout (panes, splits, tabs) is mirrored in the
+Terminator window. Input, resize, and focus changes are synchronized
+with tmux.
+.SS "In\-terminal detection"
+.sp
+Type \fBtmux \-CC\fP or \fBtmux \-CC attach\fP inside any Terminator terminal.
+Terminator detects the control mode output, takes over the PTY, and
+opens a new window with the tmux layout. The original terminal shows a
+control mode screen with a \fBCtrl+C to detach\fP prompt.
+.SS "Detaching and exiting"
+.sp
+There are three ways to end a tmux control mode session:
+.sp
+\fBExit\fP
+.RS 4
+When the last shell in the tmux session exits, the tmux
+window closes and the original terminal is restored.
+.RE
+.sp
+\fBClose window\fP
+.RS 4
+Closing the tmux window (via the window manager or
+\fBCtrl+Shift+Q\fP) sends a detach command to tmux, preserving the
+session for later reattach.
+.RE
+.sp
+\fBCtrl+C\fP
+.RS 4
+From the control mode screen in the original terminal,
+pressing \fBCtrl+C\fP detaches from tmux and closes the tmux window.
+.RE
+.SS "Features"
+.sp
+Pane splits, tabs, and resize are synchronized bidirectionally with
+tmux. Terminal titles are updated from tmux pane information, and
+applications that set custom titles (via OSC escape sequences) are
+displayed. The window title shows the tmux user, host, and session
+name.
+.sp
+When in tmux mode, overlay titlebars and overlay scrollbars are
+automatically enabled regardless of profile settings.
 .SH "KEYBINDINGS"
 .sp
 The following default keybindings can be used to control Terminator.
@@ -482,4 +544,4 @@ Terminator was written by Chris Jones <cmsj@tenshu.net> and others.
 This manual page was written by Chris Jones <cmsj@tenshu.net> and others.
 .SH "SEE ALSO"
 .sp
-\fBterminator_config\fP(5)
+\fBterminator_config\fP(5)

doc/terminator.adoc

@@ -104,6 +104,16 @@ only be printed from the specified functions. If this is specified in
 addition to --debug-classes, only the intersection of the two lists will
 be displayed.
 
+**--tmux-attach**[=__SESSION__]::
+Attach to an existing tmux session in control mode. If SESSION is not
+specified, attaches to the most recently used session. Terminator will
+mirror the tmux session layout, with splits displayed as panes and
+tmux windows as tabs.
+
+**--tmux-new**=__SESSION__::
+Create a new tmux session with the given name and attach to it in
+control mode.
+
 *--new-tab*::
 If this is specified and Terminator is already running, DBus will be
 used to spawn a new tab in the first Terminator window.
@@ -113,6 +123,46 @@ If this is specified and Terminator is already running, DBus will be
 used to toggle Terminator window visibility. Usable under Wayland to
 replace hide keyboad shortcut.
 
+== TMUX CONTROL MODE
+
+Terminator can act as a native GUI frontend for tmux sessions using
+tmux's control mode (*-C* flag). There are two ways to use this:
+
+=== Command line attach
+Launch Terminator with *--tmux-attach* or *--tmux-new* to connect to a
+tmux session. The tmux layout (panes, splits, tabs) is mirrored in the
+Terminator window. Input, resize, and focus changes are synchronized
+with tmux.
+
+=== In-terminal detection
+Type *tmux -CC* or *tmux -CC attach* inside any Terminator terminal.
+Terminator detects the control mode output, takes over the PTY, and
+opens a new window with the tmux layout. The original terminal shows a
+control mode screen with a *Ctrl+C to detach* prompt.
+
+=== Detaching and exiting
+There are three ways to end a tmux control mode session:
+
+*Exit*:: When the last shell in the tmux session exits, the tmux
+window closes and the original terminal is restored.
+
+*Close window*:: Closing the tmux window (via the window manager or
+*Ctrl+Shift+Q*) sends a detach command to tmux, preserving the
+session for later reattach.
+
+*Ctrl+C*:: From the control mode screen in the original terminal,
+pressing *Ctrl+C* detaches from tmux and closes the tmux window.
+
+=== Features
+Pane splits, tabs, and resize are synchronized bidirectionally with
+tmux. Terminal titles are updated from tmux pane information, and
+applications that set custom titles (via OSC escape sequences) are
+displayed. The window title shows the tmux user, host, and session
+name.
+
+When in tmux mode, overlay titlebars and overlay scrollbars are
+automatically enabled regardless of profile settings.
+
 == KEYBINDINGS
 The following default keybindings can be used to control Terminator.
 Most of these keybindings can be changed in the Preferences.

doc/terminator_config.5

@@ -1,7 +1,7 @@
 '\" t
 .\"     Title: terminator_config
 .\"    Author: [see the "AUTHOR(S)" section]
-.\" Generator: Asciidoctor 2.0.16
+.\" Generator: Asciidoctor 2.0.23
 .\"      Date: 2023-10-10
 .\"    Manual: Manual for Terminator
 .\"    Source: Terminator
@@ -123,6 +123,15 @@ If set to True, the window will be hidden from the taskbar.
 Default value: \fBFalse\fP
 .RE
 .sp
+\fBhide_tmux_origin\fP = \fIboolean\fP
+.RS 4
+If set to True, the terminal window where \fBtmux \-CC\fP was typed will be
+automatically minimized when tmux control mode activates. The window is
+restored when the tmux session is detached or exited.
+.br
+Default value: \fBFalse\fP
+.RE
+.sp
 \fBgeometry_hinting\fP = \fIboolean\fP
 .RS 4
 If set to True, the window will resize in step with font sizes.
@@ -1165,11 +1174,21 @@ Default value: \fBmiddle\fP
 \fBscrollbar_position\fP = \fIstring\fP
 .RS 4
 Specify where the terminal scrollbar is put.
-Can be any of: \*(Aqleft\*(Aq, \*(Aqright\*(Aq, \*(Aqhidden\*(Aq.
+Can be any of: \*(Aqleft\*(Aq, \*(Aqright\*(Aq, \*(Aqdisabled\*(Aq.
 .br
 Default value: \fBright\fP
 .RE
 .sp
+\fBoverlay_scrollbar\fP = \fIboolean\fP
+.RS 4
+If set to True, the scrollbar overlays the terminal content and is
+transparent when scrolled to the bottom. It fades in when scrolled up
+in history. Works with the left/right position setting. Always enabled
+in tmux control mode regardless of this setting.
+.br
+Default value: \fBFalse\fP
+.RE
+.sp
 \fBscroll_on_output\fP = \fIboolean\fP
 .RS 4
 If set to True, the terminall will scroll to the bottom when an
@@ -1241,6 +1260,15 @@ title of that terminal.
 Default value: \fBTrue\fP
 .RE
 .sp
+\fBoverlay_titlebar\fP = \fIboolean\fP
+.RS 4
+If set to True, the titlebar floats over the terminal content and is
+fully transparent until the mouse hovers over it. This saves vertical
+space. Always enabled in tmux control mode regardless of this setting.
+.br
+Default value: \fBFalse\fP
+.RE
+.sp
 \fBtitle_hide_sizetext\fP = \fIboolean\fP
 .RS 4
 If set to True, the size of the terminal will not be written on its

doc/terminator_config.adoc

@@ -86,6 +86,12 @@ Default value: *False*
 If set to True, the window will be hidden from the taskbar. +
 Default value: *False*
 
+*hide_tmux_origin* = _boolean_::
+If set to True, the terminal window where *tmux -CC* was typed will be
+automatically minimized when tmux control mode activates. The window is
+restored when the tmux session is detached or exited. +
+Default value: *False*
+
 *geometry_hinting* = _boolean_::
 If set to True, the window will resize in step with font sizes. +
 Default value: *False*
@@ -784,9 +790,16 @@ Default value: *middle*
 
 *scrollbar_position* = _string_::
 Specify where the terminal scrollbar is put.
-Can be any of: 'left', 'right', 'hidden'. +
+Can be any of: 'left', 'right', 'disabled'. +
 Default value: *right*
 
+*overlay_scrollbar* = _boolean_::
+If set to True, the scrollbar overlays the terminal content and is
+transparent when scrolled to the bottom. It fades in when scrolled up
+in history. Works with the left/right position setting. Always enabled
+in tmux control mode regardless of this setting. +
+Default value: *False*
+
 *scroll_on_output* = _boolean_::
 If set to True, the terminall will scroll to the bottom when an
 application writes text to it. +
@@ -839,6 +852,12 @@ If set to True, the terminal will have a titlebar showing the current
 title of that terminal. +
 Default value: *True*
 
+*overlay_titlebar* = _boolean_::
+If set to True, the titlebar floats over the terminal content and is
+fully transparent until the mouse hovers over it. This saves vertical
+space. Always enabled in tmux control mode regardless of this setting. +
+Default value: *False*
+
 *title_hide_sizetext* = _boolean_::
 If set to True, the size of the terminal will not be written on its
 titlebar. +

terminator

@@ -128,14 +128,85 @@ if __name__ == '__main__':
         TERMINATOR.set_dbus_data(dbus_service)
         TERMINATOR.reconfigure()
 
-        try:
-            dbg('Creating a terminal with layout: %s' % OPTIONS.layout)
-            TERMINATOR.create_layout(OPTIONS.layout)
-        except (KeyError,ValueError) as ex:
-            err('layout creation failed, creating a window ("%s")' % ex)
-            TERMINATOR.new_window()
+        tmux_attach = getattr(OPTIONS, 'tmux_attach', None)
+        tmux_new = getattr(OPTIONS, 'tmux_new', None)
+        tmux_session = tmux_attach if tmux_attach is not None else tmux_new
+        if tmux_session is not None:
+            from terminatorlib.tmux.controller import TmuxController
+            new_session = bool(tmux_new)
+            # Empty session name means "most recent" (like bare tmux attach)
+            if tmux_session == '' and not new_session:
+                import subprocess as _sp
+                try:
+                    result = _sp.run(['tmux', 'list-sessions', '-F', '#{session_name}'],
+                                     capture_output=True, text=True, timeout=2)
+                    if result.returncode == 0 and result.stdout.strip():
+                        tmux_session = result.stdout.strip().split('\n')[0]
+                        dbg('Auto-selected tmux session: %s' % tmux_session)
+                    else:
+                        err('No tmux sessions available')
+                        tmux_session = None
+                except Exception as ex:
+                    err('Failed to list tmux sessions: %s' % ex)
+                    tmux_session = None
+            if tmux_session is None:
+                TERMINATOR.new_window()
+            else:
+                tmux_ctrl = TmuxController()
+                tmux_ctrl.start(tmux_session, new_session=new_session)
+                tmux_layout = tmux_ctrl.get_initial_layout()
+                if tmux_layout:
+                    dbg('Using tmux layout: %s' % tmux_layout)
+                    # Extract original tmux size before create
+                    # may cap it to fit the screen.
+                    _orig_tmux_size = None
+                    for _k, _v in tmux_layout.items():
+                        if _v.get('type') == 'Window' and \
+                                'tmux_size' in _v:
+                            _s = _v['tmux_size']
+                            _orig_tmux_size = (
+                                int(_s[0]), int(_s[1]))
+                            break
+                    TERMINATOR.create_layout_from_flat(tmux_layout)
+                    # If tmux_size was capped to fit the screen,
+                    # tell tmux so it re-lays-out within our limits.
+                    if _orig_tmux_size and tmux_ctrl.active:
+                        for w in TERMINATOR.windows:
+                            capped = getattr(
+                                w, '_tmux_capped_size', None)
+                            if (capped and
+                                    capped != _orig_tmux_size):
+                                dbg('tmux size capped %dx%d -> '
+                                    '%dx%d, sending refresh-client'
+                                    % (_orig_tmux_size[0],
+                                       _orig_tmux_size[1],
+                                       capped[0], capped[1]))
+                                tmux_ctrl.protocol.send_command(
+                                    'refresh-client -C %d,%d'
+                                    % (capped[0], capped[1]))
+                                tmux_ctrl.state.last_client_size \
+                                    = capped
+                            break
+                else:
+                    err('tmux layout not available, falling back to default')
+                    TERMINATOR.new_window()
+        else:
+            try:
+                dbg('Creating a terminal with layout: %s' % OPTIONS.layout)
+                TERMINATOR.create_layout(OPTIONS.layout)
+            except (KeyError,ValueError) as ex:
+                err('layout creation failed, creating a window ("%s")' % ex)
+                TERMINATOR.new_window()
+
         TERMINATOR.layout_done()
 
+        # After layout_done, terminals are registered - capture initial content
+        try:
+            if tmux_session and tmux_ctrl.active:
+                tmux_ctrl.handlers.capture_initial_content()
+        except NameError:
+            pass
+
     if OPTIONS.debug and OPTIONS.debug >= 2:
         import terminatorlib.debugserver as debugserver
         # pylint: disable-msg=W0611

terminatorlib/config.py

@@ -97,6 +97,7 @@
             'hide_from_taskbar'     : False,
             'always_on_top'         : False,
             'hide_on_lose_focus'    : False,
+            'hide_tmux_origin'      : False,
             'sticky'                : False,
             'use_custom_url_handler': False,
             'custom_url_handler'    : '',
@@ -233,7 +234,9 @@
                 'font'                  : 'Mono 10',
                 'foreground_color'      : '#aaaaaa',
                 'show_titlebar'         : True,
+                'overlay_titlebar'      : False,
                 'scrollbar_position'    : "right",
+                'overlay_scrollbar'     : False,
                 'scroll_on_keystroke'   : True,
                 'scroll_on_output'      : False,
                 'scrollback_lines'      : 500,