Add support for tmux control mode (#3656) #18928

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)

joexue · 2025-05-20T00:29:08Z

@microsoft-github-policy-service agree

DHowett · 2025-05-20T02:59:52Z

whoa

iDarshan · 2025-05-20T23:22:17Z

This is a long-awaited feature! Thanks @joexue!

BinaryShrub · 2025-05-20T23:58:21Z

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.

iDarshan · 2025-06-03T20:38:07Z

Is there a nightly build with this PR to test?

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.

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?

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 @iDarshan

carlos-zamora · 2025-06-10T22:22:01Z

Hi @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 @DHowett @lhecker @zadjii-msft

joexue · 2025-06-12T02:54:13Z

Hi @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 @DHowett @lhecker @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?

joexue · 2025-06-17T03:19:59Z

@carlos-zamora @DHowett @lhecker @zadjii-msft
All comments are addressed, please try again.

Thanks

joexue · 2025-07-23T15:40:49Z

Anything we can do on this?

DHowett · 2025-07-29T22:04:51Z

Anything we can do on this?

We're just about to release v1.24, and then we can really start to go crazy with new features 🙂

joexue · 2025-08-01T20:39:53Z

Anything we can do on this?

We're just about to release v1.24, and then we can really start to go crazy with new features 🙂

Understood, take your time.👌

iDarshan · 2025-10-02T17:35:34Z

Anything we can do on this?

We're just about to release v1.24, and then we can really start to go crazy with new features 🙂

Any updates on getting this merged?

bilfinger-fellner-h · 2025-11-12T08:04:01Z

What's holding this up at the moment? I've anxiously been sitting on needles waiting for tmux control mode support in Windows Terminal for quite a while now.

lhecker · 2025-12-05T20:58:11Z

I began working on this PR late last week. It has a few issues that require fundamental changes to the PR. For instance, we use the ITerminalApi interface to raise notifications through our stack. We also shouldn't do any IO on the UI thread (which this PR relies on). But the good news (well, hopefully good news 😅) is that I'm taking care of all that. 🙂

joexue · 2025-12-07T05:34:06Z

I began working on this PR late last week. It has a few issues that require fundamental changes to the PR. For instance, we use the ITerminalApi interface to raise notifications through our stack. We also shouldn't do any IO on the UI thread (which this PR relies on). But the good news (well, hopefully good news 😅) is that I'm taking care of all that. 🙂

Definitely good news, thanks for taking care of that

lhecker · 2025-12-10T16:13:16Z

src/cascadia/TerminalApp/TerminalPage.cpp

+ control.SetTmuxControlHandlerProducer([this, control](auto print) {
+ return _tmuxControl->TmuxControlHandlerProducer(control, print);
+ });


I'm going to leave some comments on your PR now for things that I found and already corrected in my branch. The problem is that some of the required changes essentially break your PR fundamentally, and I found it difficult to piece it back together. That's why I haven't committed it yet. 😅

In any case, this first one is pretty gnarly. Because your lambda here takes a copy of control and then you store the lambda on control itself, you're leaking the control instance. It'll never be freed.

(It's not possible to fix this by passing control as a weak pointer because this breaks the Close events. I'm still working to fix this.)

lhecker · 2025-12-10T16:14:12Z

src/cascadia/TerminalApp/TmuxControl.cpp

+ const std::wregex TmuxControl::REG_WINDOW_ADD{ L"^%window-add @(\\d+)$" };
+ const std::wregex TmuxControl::REG_WINDOW_CLOSE{ L"^%window-close @(\\d+)$" };
+ const std::wregex TmuxControl::REG_WINDOW_PANE_CHANGED{ L"^%window-pane-changed @(\\d+) %(\\d+)$" };
+ const std::wregex TmuxControl::REG_WINDOW_RENAMED{ L"^%window-renamed @(\\d+) (\\S+)$" };


While regexes are fine for some things, I'm personally not happy with the reliance on them in this PR. I believe we should write proper, classic parsers for the tmux protocol.

lhecker · 2025-12-10T16:17:11Z

src/cascadia/TerminalApp/TmuxControl.cpp

+ // Tmux control has its own profile, we duplicate it from the control panel
+ void TmuxControl::_SetupProfile()
+ {
+ const auto settings{ CascadiaSettings::LoadDefaults() };


FWIW, creating an entire settings object for cloning the profile is a bit ugly. I have not changed this however, as we indeed lack the facilities to do it differently.

lhecker · 2025-12-10T16:18:50Z

src/cascadia/TerminalApp/TmuxControl.cpp

+ out.push_back(c);
+ ++it;


For ideal performance this should do a chunk-wise translation of the output payload.

lhecker · 2025-12-10T16:19:34Z

src/cascadia/TerminalApp/TmuxControl.cpp

+ // The pane is not ready it, put int backlog for now
+ if (search == _attachedPanes.end())
+ {
+ _outputBacklog.insert_or_assign(paneId, text);


If we create an _attachedPanes item in advance here, we can store the output backlog in the AttachedPane struct. I think this also makes some other code a bit neater.

lhecker · 2025-12-11T15:58:02Z

src/cascadia/TerminalConnection/DummyConnection.cpp

+ void DummyConnection::WriteInput(const winrt::array_view<const char16_t> buffer)
+ {
+ const auto data = winrt_array_to_wstring_view(buffer);
+ std::wstringstream prettyPrint;
+ for (const auto& wch : data)
+ {
+ prettyPrint << wch;
+ }
+ TerminalInput.raise(prettyPrint.str());
+ }


This isn't quite ideal. To fix this we can simply change TerminalInput to also send Char[] instead of String around. Then this can simple pass the buffer through unmodified.

lhecker · 2025-12-11T15:59:04Z

src/cascadia/TerminalConnection/DummyConnection.cpp

+
+namespace winrt::Microsoft::Terminal::TerminalConnection::implementation
+{
+ DummyConnection::DummyConnection() noexcept = default;


Instead of making this a dummy connection, this should ideally be a genuine TmuxConnection which raises proper output events. All we need to do for that is save the connection instance in TmuxControl and use it to raise the output events.

lhecker · 2025-12-11T15:59:41Z

src/cascadia/TerminalControl/ControlCore.cpp

+ void ControlCore::SendOutput(const std::wstring_view wstr)
+ {
+ if (wstr.empty())
+ {
+ return;
+ }
+
+ auto lock = _terminal->LockForWriting();
+ _terminal->Write(wstr);
+ }


Having a TmuxConnection then makes this unnecessary.

lhecker · 2025-12-11T16:01:46Z

src/terminal/adapter/adaptDispatch.cpp

+ PrintString(s);
+ _DoLineFeed(page, true, true);


While the PrintHandler is a very clever solution, I don't think that we should do this. It taints the VT parser with even more Windows-Terminal-specific code. It moves us further into a "big ball of mud" direction instead of the opposite of turning our VT parser into a purer, proper parser. I've broken this functionality in my local branch, and I hope we can restore this functionality at some point later.

lhecker · 2025-12-11T16:04:13Z

src/terminal/adapter/adaptDispatch.cpp

+void AdaptDispatch::SetTmuxControlHandlerProducer(StringHandlerProducer producer)
+{
+ _tmuxControlHandlerProducer = producer;
+}


We use the ITerminalApi interface to raise notifications to the hosting terminal (a typical push parser design). If we now have callback functions on top of that, this would make it worse. The correct approach is to add a ITerminalApi function which returns a StringHandler handler.

lhecker · 2025-12-11T16:08:24Z

src/cascadia/TerminalApp/TmuxControl.cpp

+ }
+
+ // From tmux to controller through the dcs. parse it per line.
+ bool TmuxControl::_Advance(wchar_t ch)


I've written #19640 to improve the performance of this PR. I've already modified this function in my branch to process entire std::wstring_views at a time.

This comment was marked as outdated.

Sign in to view