starred/terminal
1
0
Fork 0
mirror of https://github.com/microsoft/terminal.git synced 2026-02-04 05:35:20 +00:00
Code Issues 19.0k Packages Projects Releases 20 Wiki Activity

Implement tmux control mode (-CC) #7753

New Issue
Open
opened 2026-01-31 01:11:56 +00:00 by claunia · 0 comments
claunia commented 2026-01-31 01:11:56 +00:00
Owner
Copy Link

Originally created by @browell on GitHub (Apr 28, 2020).

Description

Tmux/Screen has long been considered an essential tool when working in terminals on Linux, and a huge portion of all WSL users are likely using tmux.

With the introduction of panes in the latest release, it is now reasonable to consider integrating with tmux's control mode (tmux -CC). This is a textual interface provided by tmux specifically for the purpose of integrating with terminal emulators. The most prominent example of such integration is iTerm2.

This would build on the existing pane implementation to allow terminal windows displaying a tmux session to essentially function as a renderer of tmux's state in the following ways:

  • Panes created/destroyed in tmux would create/destroy corresponding panes in windows terminal, and vice versa.

  • Changes in size to panes in either tmux or windows terminal would be mirrored respectively.

  • Text selections within windows terminal would therefore be limited by the presence of native panes, and prevented from spanning multiple panes.

  • Window names would be updated based on the name for the active pane within a tmux session.

  • It may or may not be helpful to pass through raw keystrokes to tmux to allow them to be interpreted, and the output reinterpreted by the terminal emulator so that users can make use of existing tmux key bindings.

Doing this would allow for native-feeling experiences even for terminals over SSH; reduce configuration for tmux users; and gloss over some of the awkwardness of overlapping functionality. For example, a terminal emulator can't provide tmux's persistence functionality and therefore will never replace it, but the presence of panes within panes within panes (vim within tmux within a terminal emulator that has panes...) can get quite awkward and difficult to manage. It also reduces the experience of latency when working with tmux.

Implementation details

To spy on an tmux session's control codes, open a tmux session in one terminal window, and in another, attach to the same session with tmux -CC attach. You will now see the outputted control codes for every action within tmux in the original window, including the raw text output for each pane.

From the man pages:
`
CONTROL MODE

 tmux offers a textual interface called control mode.  This allows
 applications to communicate with tmux using a simple text-only proto‐
 col.

 In control mode, a client sends tmux commands or command sequences ter‐
 minated 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.

 The following notifications are defined:

 %client-session-changed client session-id name
         The client is now attached to the session with ID session-id,
         which is named name.

 %exit [reason]
         The tmux client is exiting immediately, either because it is
         not attached to any session or an error occurred.  If present,
         reason describes why the client exited.

 %layout-change window-id window-layout window-visible-layout
         window-flags
         The layout of a window with ID window-id changed.  The new lay‐
         out is window-layout.  The window's visible layout is
         window-visible-layout and the window flags are window-flags.

 %output pane-id value
         A window pane produced output.  value escapes non-printable
         characters and backslash as octal \xxx.

 %pane-mode-changed pane-id
         The pane with ID pane-id has changed mode.

 %session-changed session-id name
         The client is now attached to the session with ID session-id,
         which is named name.

 %session-renamed name
         The current session was renamed to name.

 %session-window-changed session-id window-id
         The session with ID session-id changed its active window to the
         window with ID window-id.

 %sessions-changed
         A session was created or destroyed.

 %unlinked-window-add window-id
         The window with ID window-id was created but is not linked to
         the current session.

 %window-add window-id
         The window with ID window-id was linked to the current session.

 %window-close window-id
         The window with ID window-id closed.

 %window-pane-changed window-id pane-id
         The active pane in the window with ID window-id changed to the
         pane with ID pane-id.

 %window-renamed window-id name
         The window with ID window-id was renamed to name.

`

In Summary

Windows Terminal should detect when tmux is launched in control mode (tmux -CC), and should start rendering the parsed output described above using native GUI panes. It would be reasonable to prevent non-tmux panes from being created in this mode, or otherwise create placeholder panes within the tmux session displaying some simple but useful representation of what is in the pane.

When the window is closed, session is detached. Tmux is left running. This would also facilitate persistent layouts without the need to implement it natively.

The ability to create profiles which automatically attach to a tmux session would enhance the usefulness of this feature.

Originally created by @browell on GitHub (Apr 28, 2020). **Description** Tmux/Screen has long been considered an essential tool when working in terminals on Linux, and a huge portion of all WSL users are likely using tmux. With the introduction of panes in the latest release, it is now reasonable to consider integrating with tmux's control mode (tmux -CC). This is a textual interface provided by tmux specifically for the purpose of integrating with terminal emulators. The most prominent example of such integration is iTerm2. This would build on the existing pane implementation to allow terminal windows displaying a tmux session to essentially function as a renderer of tmux's state in the following ways: - Panes created/destroyed in tmux would create/destroy corresponding panes in windows terminal, and vice versa. - Changes in size to panes in either tmux or windows terminal would be mirrored respectively. - Text selections within windows terminal would therefore be limited by the presence of native panes, and prevented from spanning multiple panes. - Window names would be updated based on the name for the active pane within a tmux session. - It may or may not be helpful to pass through raw keystrokes to tmux to allow them to be interpreted, and the output reinterpreted by the terminal emulator so that users can make use of existing tmux key bindings. Doing this would allow for native-feeling experiences even for terminals over SSH; reduce configuration for tmux users; and gloss over some of the awkwardness of overlapping functionality. For example, a terminal emulator can't provide tmux's persistence functionality and therefore will never replace it, but the presence of panes within panes within panes (vim within tmux within a terminal emulator that has panes...) can get quite awkward and difficult to manage. It also reduces the experience of latency when working with tmux. **Implementation details** To spy on an tmux session's control codes, open a tmux session in one terminal window, and in another, attach to the same session with `tmux -CC attach`. You will now see the outputted control codes for every action within tmux in the original window, including the raw text output for each pane. From the man pages: ` CONTROL MODE tmux offers a textual interface called control mode. This allows applications to communicate with tmux using a simple text-only proto‐ col. In control mode, a client sends tmux commands or command sequences ter‐ minated 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. The following notifications are defined: %client-session-changed client session-id name The client is now attached to the session with ID session-id, which is named name. %exit [reason] The tmux client is exiting immediately, either because it is not attached to any session or an error occurred. If present, reason describes why the client exited. %layout-change window-id window-layout window-visible-layout window-flags The layout of a window with ID window-id changed. The new lay‐ out is window-layout. The window's visible layout is window-visible-layout and the window flags are window-flags. %output pane-id value A window pane produced output. value escapes non-printable characters and backslash as octal \xxx. %pane-mode-changed pane-id The pane with ID pane-id has changed mode. %session-changed session-id name The client is now attached to the session with ID session-id, which is named name. %session-renamed name The current session was renamed to name. %session-window-changed session-id window-id The session with ID session-id changed its active window to the window with ID window-id. %sessions-changed A session was created or destroyed. %unlinked-window-add window-id The window with ID window-id was created but is not linked to the current session. %window-add window-id The window with ID window-id was linked to the current session. %window-close window-id The window with ID window-id closed. %window-pane-changed window-id pane-id The active pane in the window with ID window-id changed to the pane with ID pane-id. %window-renamed window-id name The window with ID window-id was renamed to name. ` **In Summary** Windows Terminal should detect when tmux is launched in control mode (`tmux -CC`), and should start rendering the parsed output described above using native GUI panes. It would be reasonable to prevent non-tmux panes from being created in this mode, or otherwise create placeholder panes within the tmux session displaying some simple but useful representation of what is in the pane. When the window is closed, session is detached. Tmux is left running. This would also facilitate persistent layouts without the need to implement it natively. The ability to create profiles which automatically attach to a tmux session would enhance the usefulness of this feature.
claunia added the Issue-FeatureResolution-Duplicate labels 2026-01-31 01:11:56 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
⛺ Reserved
A11yCO
A11yMAS
A11ySev1
A11ySev2
A11ySev3
A11yTTValidated
A11yUsable
A11yVoiceAccess
A11yWCAG
Area-Accessibility
Area-AtlasEngine
Area-AzureShell
Area-Build
Area-Build
Area-Chat
Area-CmdPal
Area-CodeHealth
Area-Commandline
Area-CookedRead
Area-DefApp
Area-Extensibility
Area-Fonts
Area-GroupPolicy
Area-i18n
Area-Input
Area-Interaction
Area-Interop
Area-Localization
Area-Output
Area-Performance
Area-Portable
Area-Quality
Area-Remoting
Area-Rendering
Area-Schema
Area-Server
Area-Settings
Area-SettingsUI
Area-ShellExtension
Area-ShellExtension
Area-ShellExtension
Area-Suggestions
Area-Suggestions
Area-TerminalConnection
Area-TerminalControl
Area-Theming
Area-UserInterface
Area-VT
Area-Windowing
Area-WPFControl
AutoMerge
Blocking-Ingestion
Culprit-Centennial
Culprit-WinUI
Disability-All
Disability-Blind
Disability-LowVision
Disability-Mobility
External-Blocked-WinUI3
Fixed
Gathering-Data
good first issue
HCL-E+D
HCL-WindowsTerminal
Help Wanted
Impact-Compatibility
Impact-Compliance
Impact-Correctness
Impact-Visual
In-PR
InclusionBacklog
InclusionBacklog-Windows TerminalWin32
InclusionCommitted-202206
Issue-Bug
Issue-Docs
Issue-Feature
Issue-Feature
Issue-Question
Issue-Samples
Issue-Scenario
Issue-Task
Needs-Attention
Needs-Author-Feedback
Needs-Bisect
Needs-Discussion
Needs-Repro
Needs-Tag-Fix
Needs-Tag-Fix
Needs-Triage
No-Recent-Activity
Priority-0
Priority-1
Priority-2
Priority-3
Product-Cmd.exe
Product-Colortool
Product-Colortool
Product-Colortool
Product-Conhost
Product-Conpty
Product-Meta
Product-Powershell
Product-Terminal
Product-WSL
pull-request
Mirrored from GitHub Pull Request
 Resolution-Answered
Resolution-By-Design
Resolution-Duplicate
Resolution-External
Resolution-Fix-Available
Resolution-Fix-Committed
Resolution-No-Repro
Resolution-Won't-Fix
Severity-Blocking
Severity-Crash
Severity-DataLoss
spam
this-will-be-a-breaking-change
Tracking-External
WindowsTerminal_Win32
Work-Item
zAskModeBug
zInbox-Bug
No Label Issue-Feature Resolution-Duplicate
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
claunia
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/terminal#7753
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?