Add support for tmux control mode (#3656) by joexue · Pull Request #18928 · microsoft/terminal

Joe Xue (joexue) · 2025-05-20T00:19:08Z

Summary of the Pull Request

Let WT supports tmux control mode

References and Relevant Issues

#3656

Detailed Description of the Pull Request / Additional comments

Support:

Create/attach tmux session
Split pane vertical/horizontal
Window/panes size change
Remove pane/tab if remote pane exit or window exit

Improvements may do:

Merge the tmux menus/button with existing menu/button
Add the keyboard accelerators for tmux menus
Unicode support(the VTParser just pass part of characters in DCS mode
When attached a session, focus on the same focused tab/pane when detaching(backend is done, need to do some work frontend)
Test code

Tested by using tmux 3.4:
ssh to a machine has tmux or use wsl, then run
"tmux -CC" or "tmux -CC a"

Validation Steps Performed

PR Checklist

[x ] Closes Add support for tmux Control Mode #3656
Tests added/passed
Documentation updated
- If checked, please file a pull request on our docs repo and link it here: #xxx
Schema updated (if necessary)

Joe Xue (joexue) · 2025-05-20T00:29:08Z

@microsoft-github-policy-service agree

Dustin L. Howett (DHowett) · 2025-05-20T02:59:52Z

whoa

Darshan Prajapati (iDarshan) · 2025-05-20T23:22:17Z

This is a long-awaited feature! Thanks Joe Xue (@joexue)!

Justin (BinaryShrub) · 2025-05-20T23:58:21Z

Dustin L. Howett (DHowett) · 2025-05-23T00:03:41Z

FYI: I am working with reduced staffing at the moment, so reviews may be slow to come. I apologize for that.

Darshan Prajapati (iDarshan) · 2025-06-03T20:38:07Z

Is there a nightly build with this PR to test?

Carlos Zamora (carlos-zamora) · 2025-06-05T17:21:45Z

Is there a nightly build with this PR to test?

Your best bet is to build this locally. Once it merges, it will be available on the Canary channel though.

Darshan Prajapati (iDarshan) · 2025-06-06T02:15:22Z

Is there a nightly build with this PR to test?

Your best bet is to build this locally. Once it merges, it will be available on the Canary channel though.

I tried to find the build guide, but couldn't find one. Do you have the link handy?

Joe Xue (joexue) · 2025-06-06T13:13:42Z

Is there a nightly build with this PR to test?

Your best bet is to build this locally. Once it merges, it will be available on the Canary channel though.

I tried to find the build guide, but couldn't find one. Do you have the link handy?

README.md ->Developer Guidance Darshan Prajapati (@iDarshan)

Carlos Zamora (carlos-zamora) · 2025-06-10T22:22:01Z

Hi Joe Xue (@joexue)! Thanks for doing this! I published a build for the team to test internally and we've got a few notes we want to share with you 😊

Notes/Reactions:
- Settings menu item is gone from the dropdown
- It makes your existing window a special "tmux only" window; it disables the menu, but it doesn't disable the key bindings, so you can still split in non-tmux panes
- Scrollbars are gone? I guess scrolling is server side
Requested changes:
- [Bug] can't type in an older pane after splitting panes
- tmux tabs should not be draggable into a new window
- Add a setting to Profile > "Terminal Emulation" page that disables this (it should be disabled by default)
- Bug: Closing a tab/pane will not kill the instance on the server side
- Add a feature flag to features.xml (Guidance)
- [Architectural notes] We should see if we can't just model a tmux pane as a connection so we don't need to pump output into the terminal from the App layer

Overall, this is a really exciting feature and we're excited to see it land! Let us know if you need any guidance or additional comments on any of the thoughts above. 😊

CC Dustin L. Howett (@DHowett) Leonard Hecker (@lhecker) Mike Griese (@zadjii-msft)

Joe Xue (joexue) · 2025-06-12T02:54:13Z

Hi Joe Xue (@joexue)! Thanks for doing this! I published a build for the team to test internally and we've got a few notes we want to share with you 😊

Notes/Reactions:

Settings menu item is gone from the dropdown

It makes your existing window a special "tmux only" window; it disables the menu, but it doesn't disable the key bindings, so you can still split in non-tmux panes

Scrollbars are gone? I guess scrolling is server side

Scrollbars are gone is by design, I put the comment in the code, since we want to make local panes size match remote(tmux) panes size, but each split, tmux just lost 1 character to use it as separator, if we have side scrollbars, we cannot make two side's size match. To meet this, the padding size is changed too.

As the menu, it is because I tried to touch as less code as I can to do the job. So give the tmux a separate UI system. I described in the PR, this could be improved and should integrated into the present UI/menu system.
But, I think we can skip this ugly stage, directly change the code to make the tmux control mode work with present UI/menu system. I will address this, those +button/flyout splitting menus specifically for tmux will be gone.

Requested changes:

[Bug] can't type in an older pane after splitting panes

I did not see this bug, to help me to reproduce it here, could you describe your env? how do you connect to tmux server? what is the tmux version?

tmux tabs should not be draggable into a new window

Sure, let me fix it.

Add a setting to Profile > "Terminal Emulation" page that disables this (it should be disabled by default)

Sure, let me look it.

Bug: Closing a tab/pane will not kill the instance on the server side

This is by design, remote pane should close by quit it's app. but this is arguable, if we think close local pane should close remote pane too, it is easy and feasible.

Add a feature flag to features.xml (Guidance)

Sure. Fair enough.

[Architectural notes] We should see if we can't just model a tmux pane as a connection so we don't need to pump output into the terminal from the App layer

Please provide the idea, I can try to implement it.

Overall, this is a really exciting feature and we're excited to see it land! Let us know if you need any guidance or additional comments on any of the thoughts above. 😊

CC Dustin L. Howett (@DHowett) Leonard Hecker (@lhecker) Mike Griese (@zadjii-msft)

Thanks!

Since this PR is a bit big, another option is we split it into two or three parts to make it easy to review and integrate. Such as
part 1: infra libs(parser, TermControl, Terminal, ControlCore)
part 2: TmuxControl
part 3: integrating and UI/Menu

What do you think, split it or just keep as it is?

Joe Xue (joexue) · 2025-06-17T03:19:59Z

Carlos Zamora (@carlos-zamora) Dustin L. Howett (@DHowett) Leonard Hecker (@lhecker) Mike Griese (@zadjii-msft)
All comments are addressed, please try again.

Thanks

Darshan Prajapati (iDarshan) · 2026-01-31T02:33:49Z

I tried to test this and seems like its not working

root@fst:~# lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 24.04.3 LTS
Release:        24.04
Codename:       noble
root@fst:~# tmux ls
0: 1 windows (created Sat Jan 31 02:31:00 2026)
root@fst:~#
root@fst:~# tmux -CC attach
root@fst:~#
root@fst:~# tmux -V
tmux 3.4
root@fst:~#

Anything special need to be done to try this?

Dustin L. Howett (DHowett) · 2026-01-31T02:35:06Z

Anything special need to be done to try this?

You probably need to turn it on in Settings.

Darshan Prajapati (iDarshan) · 2026-01-31T02:42:49Z

Anything special need to be done to try this?

You probably need to turn it on in Settings.

Which settings? in Terminal or System settings? Do you have path to setting?

Dustin L. Howett (DHowett) · 2026-01-31T03:09:51Z

Which version of Terminal are you using? Did you compile it yourself? Since this pull request is still open and has not been accepted, you would need to have compiled it yourself.

Darshan Prajapati (iDarshan) · 2026-01-31T04:21:37Z

Which version of Terminal are you using? Did you compile it yourself? Since this pull request is still open and has not been accepted, you would need to have compiled it yourself.

Compiled myself. It took hell of a time to figure out compilation steps. it always fails due to vcpkg. Readme needs to include steps around vcpkg failure.

Dustin L. Howett (DHowett) · 2026-01-31T04:40:17Z

Oh dang, that's a new failure state we haven't heard of. If you remember what you had to do, would you mind sharing? It's supposed to use the vcpkg install that comes with VS, but if that's broken it will try a couple other things.

I think this PR puts the control mode toggle into Terminal's in-app settings, profile (or defaults), advanced.

Darshan Prajapati (iDarshan) · 2026-02-01T19:07:52Z

Enable this setting to allow Tmux Control mode:
Settings->Defaults->Additional Settings->Terminal Emulation->Allow Tmux Control

Darshan Prajapati (iDarshan) · 2026-02-01T19:10:37Z

I have tested this briefly and here are the basic bugs:

Cannot resize the panes
Alt + (+ button) click always splits the current pane vertically, no way to split pane horizontally.

original-cooling-space (zhangweize9-cyber)

It is recommended that the author optimize the memory safety aspect to make the overall logic more robust.

original-cooling-space (zhangweize9-cyber) · 2026-02-02T07:02:53Z

    std::shared_ptr<Pane> AttachPane(std::shared_ptr<Pane> pane,
-                                     winrt::Microsoft::Terminal::Settings::Model::SplitDirection splitType);
+                                     winrt::Microsoft::Terminal::Settings::Model::SplitDirection splitType,
+                                     const float splitSize = .5);


const float splitSize = .5

The correct way to write it is 0.5f. While using .5 might not show any obvious errors at runtime, it introduces numerous type conversions. It's also recommended to add a type specification to this variable.

- const float splitSize = .5 + const float splitSize = 0.5f

original-cooling-space (zhangweize9-cyber) · 2026-02-02T07:17:25Z

+
+namespace winrt::TerminalApp::implementation
+{
+    void TmuxConnection::Initialize(const Windows::Foundation::Collections::ValueSet&) const noexcept


Suggested change

void TmuxConnection::Initialize(const Windows::Foundation::Collections::ValueSet&) const noexcept

// WIP: `TmuxConnection::Initialize()` is working a progress......

void TmuxConnection::Initialize(const Windows::Foundation::Collections::ValueSet&) const noexcept {}

I suggest you add a comment declaring the purpose of this function. Or you can write a // WIP: comment to just to clarify, this feature is currently under development.

original-cooling-space (zhangweize9-cyber) · 2026-02-02T07:21:46Z

+            DiscoverPanes,
+        };
+
+        struct ResponseInfo


I suggest you use some more compatible functions to implement this functionality, such as std::variant.

original-cooling-space (zhangweize9-cyber) · 2026-02-02T07:27:14Z

+        void _handleDetach();
+        void _handleSessionChanged(int64_t sessionId);
+        void _handleWindowAdd(int64_t windowId);
+        void _handleWindowRenamed(int64_t windowId, winrt::hstring name);


Suggested change

void _handleWindowRenamed(int64_t windowId, winrt::hstring name);

void _handleWindowRenamed(int64_t windowId, const winrt::hstring name);

It is recommended to define this as a constant, that is, a read-only variable, for runtime safety reasons.

original-cooling-space (zhangweize9-cyber) · 2026-02-02T07:35:15Z

+            if (auto inputCallback = args->InputCallback())
+            {
+                return [inputCallback = std::move(inputCallback)](wchar_t ch) -> bool {
+                    const auto c16 = static_cast<char16_t>(ch);


Suggested change

const auto c16 = static_cast<char16_t>(ch);

const auto c16 = static_cast<char16_t>(static_cast<unsigned char>(ch));

I mentioned that this syntax might cause garbled characters in multilingual support or emojis......

original-cooling-space (zhangweize9-cyber) · 2026-02-02T07:40:17Z

        else
        {
            // Do we ever get here (= uninitialized terminal)? If so: How?
-            assert(false);


Deleting this assertion is like burying your head in the sand, it may seem like the problem is solved, but it will actually trigger a series of chain reactions.

original-cooling-space (zhangweize9-cyber) · 2026-02-02T07:42:41Z


+std::function<bool(wchar_t)> Terminal::EnterTmuxControl()
+{
+    return _pfnEnterTmuxControl ? _pfnEnterTmuxControl() : nullptr;


This line is written quite meticulously.

original-cooling-space (zhangweize9-cyber) · 2026-02-02T07:45:04Z

    // Not implemented for conhost.
 }
+
+std::function<bool(wchar_t)> ConhostInternalGetSet::EnterTmuxControl()


I suggest you add a comment to this section, indicating that the logic of this function needs further verification.

original-cooling-space (zhangweize9-cyber) · 2026-02-02T07:49:59Z

+    std::function<bool(wchar_t)> EnterTmuxControl() override
+    {
+        Log::Comment(L"EnterTmuxControl MOCK called...");
+        return nullptr;


Suggested change

return nullptr;

return 1;

If you need to return an error message, you can define the return value as 1 instead of a null pointer.

original-cooling-space (zhangweize9-cyber) · 2026-02-02T07:54:19Z

+
+ITermDispatch::StringHandler AdaptDispatch::EnterTmuxControl(const VTParameters parameters)
+{
+    if (parameters.size() != 1 || parameters.at(0).value() != 1000)


Suggested change

if (parameters.size() != 1 || parameters.at(0).value() != 1000)

const int TmuxControlModeId = 1000;

if (parameters.size() != 1 || parameters.at(0).value() != TmuxControlModeld)

To improve the maintainability of the source code, it is recommended to store 1000 as a variable.

Joe Xue (joexue) · 2026-03-20T17:35:49Z

I have tested this briefly and here are the basic bugs:

Cannot resize the panes

Alt + (+ button) click always splits the current pane vertically, no way to split pane horizontally.

It works for me to split both vertically and horizontally, at least before Leonard Hecker (@lhecker) change. It calculates automatically, try split several times. Thank you for your testing.

Joe Xue (joexue) · 2026-03-20T17:44:39Z

Hi team,
AI stuff cause the terminal and command line interface usage increases significantly, and most our job on server, each terminal give a ssh and keep it is a bit annoying. Tmux control is a very good solution for this. Many my colleagues love this functionality and they have to use my private build binary. They hope this functionality can be included in official build. Is there possibility to speed up this? Thanks.

Darshan Prajapati (iDarshan) · 2026-03-30T22:16:26Z

I have tested this briefly and here are the basic bugs:

Cannot resize the panes

Alt + (+ button) click always splits the current pane vertically, no way to split pane horizontally.

It works for me to split both vertically and horizontally, at least before Leonard Hecker (@lhecker) change. It calculates automatically, try split several times. Thank you for your testing.

Joe Xue (@joexue) How do you split horizontally? What is the step? I have attached the screenshot for splitting from + button. Also, how do you resize the pan?

Joe Xue (joexue) · 2026-03-31T12:33:22Z

I have tested this briefly and here are the basic bugs:

Cannot resize the panes

Alt + (+ button) click always splits the current pane vertically, no way to split pane horizontally.

It works for me to split both vertically and horizontally, at least before Leonard Hecker (@lhecker) change. It calculates automatically, try split several times. Thank you for your testing.

Joe Xue (@joexue) How do you split horizontally? What is the step? I have attached the screenshot for splitting from + button. Also, how do you resize the pan?

Hi Darshan Prajapati (@iDarshan)
Everything are same as windows terminal are doing for now.
1 resize, focus on the panel and use Alt+Shift+Arrow keys
2 split, focus on the panel and right click the tab title and choose the “split tab” from menu. It will split by calculating the width and height, I.e. if width > height then vertical split else horizontal split.
I use defined shortcuts to split by intensional means. In the settings->actions you will find “split pane, split right” and “ split pane, split down”. If you cannot find it , define them yourself.
Thanks for using it.

Darshan Prajapati (iDarshan) · 2026-04-16T04:51:26Z

One more thing Joe Xue (@joexue). I see that once I am in tmux control mode, Terminal is not showing space key as input. So if I type ls test it shows lstest. Then if I do back space, it will even delete prompt characters. So seems like something wrong with space character input.

Darshan Prajapati (iDarshan) · 2026-05-13T01:17:22Z

It's been a year since this PR was opened. When will this get merged?

original-cooling-space (zhangweize9-cyber) · 2026-05-15T12:25:42Z

Why is it still on indefinite hold? What stage is it stuck at, exactly?

Mike Griese (zadjii-msft) · 2026-09-04T11:21:19Z

Joe Xue (@joexue) mind merging main into this? looks like the branch went stale

Joe Xue (joexue) · 2026-09-12T19:02:50Z

Joe Xue (Joe Xue (@joexue)) mind merging main into this? looks like the branch went stale

Done, thanks

Leonard Hecker (lhecker) · 2026-09-14T15:23:33Z

/azp run

azure-pipelines · 2026-09-14T15:23:48Z

Azure Pipelines: Successfully started running 2 pipeline(s).

Leonard Hecker (lhecker) · 2026-09-14T15:25:24Z

Apologies for the delays. The PR doesn't integrate well into our existing architecture and we technically really need to rework how panes are represented. (They shouldn't own the UI content, but rather represent the layout only. This way, the tmux extension could re-layout the entire pane tree cheaply, and we only re-layout the XAML UI lazily later.)

This comment was marked as outdated.

Sign in to view

This comment has been minimized.

Sign in to view

This comment was marked as outdated.

Sign in to view

Joe Xue (joexue) mentioned this pull request May 20, 2025

Add support for tmux Control Mode #3656

Open

Carlos Zamora (carlos-zamora) added a commit that referenced this pull request Jun 10, 2025

PRE-MERGE #18928 Add support for tmux control mode (#3656)

cd25b44

Joe Xue (joexue) force-pushed the tmux_cc_pr branch from fed711a to 2bf4d08 Compare June 17, 2025 03:18

This comment has been minimized.

Sign in to view

Joe Xue (joexue) force-pushed the tmux_cc_pr branch from 2bf4d08 to b70dad2 Compare June 17, 2025 23:42

This comment has been minimized.

Sign in to view

Dustin L. Howett (DHowett) mentioned this pull request Jun 18, 2025

VT mouse mode: no reaction to touch inputs #19039

Open

Joe Xue (joexue) force-pushed the tmux_cc_pr branch 2 times, most recently from 54c2bac to 4817698 Compare June 20, 2025 01:35

Leonard Hecker (lhecker) added 3 commits January 14, 2026 19:26

Fix a crash when dragging tabs / pressing +

e9ad3f4

Fix tmux setting not being respected

00cc0c3

Merge remote-tracking branch 'origin/main' into tmux_cc_pr

fe718b6

original-cooling-space (zhangweize9-cyber) reviewed Feb 2, 2026

View reviewed changes

Carlos Zamora (carlos-zamora) removed the zBugBash-Consider label Feb 10, 2026

Carlos Zamora (carlos-zamora) added the zBugBash-Consider label Mar 24, 2026

Carlos Zamora (carlos-zamora) removed the zBugBash-Consider label May 5, 2026

Mike Griese (zadjii-msft) mentioned this pull request Sep 4, 2026

Add native tmux control mode and HTM integration #20639

Open

Merge remote-tracking branch 'origin/main' into tmux_cc_pr

9a150a7

Yuandi (DDKinger) mentioned this pull request Sep 15, 2026

Add native tmux control-mode process frontend microsoft/intelligent-terminal#966

Draft

	void TmuxConnection::Initialize(const Windows::Foundation::Collections::ValueSet&) const noexcept
	// WIP: `TmuxConnection::Initialize()` is working a progress......
	void TmuxConnection::Initialize(const Windows::Foundation::Collections::ValueSet&) const noexcept {}

	void _handleWindowRenamed(int64_t windowId, winrt::hstring name);
	void _handleWindowRenamed(int64_t windowId, const winrt::hstring name);

	const auto c16 = static_cast<char16_t>(ch);
	const auto c16 = static_cast<char16_t>(static_cast<unsigned char>(ch));

	if (parameters.size() != 1 \|\| parameters.at(0).value() != 1000)
	const int TmuxControlModeId = 1000;
	if (parameters.size() != 1 \|\| parameters.at(0).value() != TmuxControlModeld)

Uh oh!

Conversation

Joe Xue (joexue) commented May 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of the Pull Request

References and Relevant Issues

Detailed Description of the Pull Request / Additional comments

Validation Steps Performed

PR Checklist

Uh oh!

This comment was marked as outdated.

This comment has been minimized.

This comment was marked as outdated.

This comment was marked as outdated.

Joe Xue (joexue) commented May 20, 2025

Uh oh!

Dustin L. Howett (DHowett) commented May 20, 2025

Uh oh!

Darshan Prajapati (iDarshan) commented May 20, 2025

Uh oh!

Justin (BinaryShrub) commented May 20, 2025

Uh oh!

Dustin L. Howett (DHowett) commented May 23, 2025

Uh oh!

Darshan Prajapati (iDarshan) commented Jun 3, 2025

Uh oh!

Carlos Zamora (carlos-zamora) commented Jun 5, 2025

Uh oh!

Darshan Prajapati (iDarshan) commented Jun 6, 2025

Uh oh!

Joe Xue (joexue) commented Jun 6, 2025

Uh oh!

Carlos Zamora (carlos-zamora) commented Jun 10, 2025

Uh oh!

Joe Xue (joexue) commented Jun 12, 2025

Uh oh!

Joe Xue (joexue) commented Jun 17, 2025

Uh oh!

This comment has been minimized.

This comment has been minimized.

Darshan Prajapati (iDarshan) commented Jan 31, 2026

Uh oh!

Dustin L. Howett (DHowett) commented Jan 31, 2026

Uh oh!

Darshan Prajapati (iDarshan) commented Jan 31, 2026

Uh oh!

Dustin L. Howett (DHowett) commented Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Darshan Prajapati (iDarshan) commented Jan 31, 2026

Uh oh!

Dustin L. Howett (DHowett) commented Jan 31, 2026

Uh oh!

Darshan Prajapati (iDarshan) commented Feb 1, 2026

Uh oh!

Darshan Prajapati (iDarshan) commented Feb 1, 2026

Uh oh!

original-cooling-space (zhangweize9-cyber) left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Joe Xue (joexue) commented May 20, 2025 •

edited

Loading

Dustin L. Howett (DHowett) commented Jan 31, 2026 •

edited

Loading