feat: auto-attach tmux sessions and switch them from remote block context menu

frontend/app/block/blockframe-header.tsx

@@ -31,7 +31,7 @@ import * as React from "react";
 import { BlockEnv } from "./blockenv";
 import { BlockFrameProps } from "./blocktypes";
 
-function handleHeaderContextMenu(
+async function handleHeaderContextMenu(
     e: React.MouseEvent<HTMLDivElement>,
     blockId: string,
     viewModel: ViewModel,
@@ -56,7 +56,7 @@ function handleHeaderContextMenu(
             },
         },
     ];
-    const extraItems = viewModel?.getSettingsMenuItems?.();
+    const extraItems = await viewModel?.getSettingsMenuItems?.();
     if (extraItems && extraItems.length > 0) menu.push({ type: "separator" }, ...extraItems);
     menu.push(
         { type: "separator" },

frontend/app/store/wshclientapi.ts

@@ -618,6 +618,12 @@ export class RpcApiType {
         return client.wshRpcCall("listalleditableapps", null, opts);
     }
 
+    // command "listtmuxsessions" [call]
+    ListTmuxSessionsCommand(client: WshClient, data: string, opts?: RpcOpts): Promise<string[]> {
+        if (this.mockClient) return this.mockClient.mockWshRpcCall(client, "listtmuxsessions", data, opts);
+        return client.wshRpcCall("listtmuxsessions", data, opts);
+    }
+
     // command "macosversion" [call]
     MacOSVersionCommand(client: WshClient, opts?: RpcOpts): Promise<string> {
         if (this.mockClient) return this.mockClient.mockWshRpcCall(client, "macosversion", null, opts);

frontend/app/view/term/term-model.ts

@@ -42,6 +42,7 @@ import * as React from "react";
 import { getBlockingCommand } from "./shellblocking";
 import { computeTheme, DefaultTermTheme, isLikelyOnSameHost, trimTerminalSelection } from "./termutil";
 import { TermWrap, WebGLSupported } from "./termwrap";
+import { applyTmuxSessionChange, toggleTmuxSession } from "./tmux-session";
 
 export class TermViewModel implements ViewModel {
     viewType: string;
@@ -822,7 +823,7 @@ export class TermViewModel implements ViewModel {
         });
     }
 
-    getContextMenuItems(): ContextMenuItem[] {
+    async getContextMenuItems(): Promise<ContextMenuItem[]> {
         const menu: ContextMenuItem[] = [];
         const hasSelection = this.termRef.current?.terminal?.hasSelection();
         const selection = hasSelection ? this.termRef.current?.terminal.getSelection() : null;
@@ -908,13 +909,69 @@ export class TermViewModel implements ViewModel {
 
         menu.push({ type: "separator" });
 
-        const settingsItems = this.getSettingsMenuItems();
+        const settingsItems = await this.getSettingsMenuItems();
         menu.push(...settingsItems);
 
         return menu;
     }
 
-    getSettingsMenuItems(): ContextMenuItem[] {
+    // Returns the Tmux Sessions submenu for remote blocks, or null when it does not apply.
+    // Fetches a fresh session snapshot when the settings menu opens and marks the active session as checked.
+    async getTmuxSessionMenuItems(): Promise<ContextMenuItem | null> {
+        const blockData = globalStore.get(this.blockAtom);
+        const connName = blockData?.meta?.connection ?? "";
+        if (connName == "" || connName == "local" || connName.startsWith("local:")) {
+            return null;
+        }
+        const curSession = (globalStore.get(getBlockMetaKeyAtom(this.blockId, "term:tmux:session")) ?? "") as string;
+        let sessions: string[] = [];
+        try {
+            // Normalize a null result (RPC connection down) to an empty list so `.includes` below never throws.
+            sessions = (await RpcApi.ListTmuxSessionsCommand(TabRpcClient, connName)) ?? [];
+        } catch (e) {
+            // Keep the settings menu usable when the connection is down, tmux is unavailable, or listing fails.
+            sessions = [];
+        }
+        const submenu: ContextMenuItem[] = [];
+        // Keep a missing active session visible so the user can still clear the association.
+        if (curSession != "" && !sessions.includes(curSession)) {
+            sessions = [curSession, ...sessions];
+        }
+        if (sessions.length == 0) {
+            submenu.push({ label: "(No tmux sessions)", enabled: false });
+        } else {
+            for (const name of sessions) {
+                submenu.push({
+                    label: name,
+                    type: "checkbox",
+                    checked: name == curSession,
+                    click: () => {
+                        fireAndForget(() => this.applyTmuxSession(toggleTmuxSession(curSession, name)));
+                    },
+                });
+            }
+        }
+        return { label: "Tmux Sessions", type: "submenu", submenu };
+    }
+
+    // Persists or clears term:tmux:session, then restarts this block controller so the change takes effect immediately.
+    // An empty session clears the association; a non-empty session associates or switches without stopping remote tmux.
+    async applyTmuxSession(session: string): Promise<void> {
+        const oldSession = (globalStore.get(getBlockMetaKeyAtom(this.blockId, "term:tmux:session")) ?? "") as string;
+        await applyTmuxSessionChange(
+            oldSession,
+            session,
+            async (nextSession) => {
+                await RpcApi.SetMetaCommand(TabRpcClient, {
+                    oref: WOS.makeORef("block", this.blockId),
+                    meta: { "term:tmux:session": nextSession || null },
+                });
+            },
+            () => this.forceRestartController()
+        );
+    }
+
+    async getSettingsMenuItems(): Promise<ContextMenuItem[]> {
         const fullConfig = globalStore.get(atoms.fullConfigAtom);
         const termThemes = fullConfig?.termthemes ?? {};
         const termThemeKeys = Object.keys(termThemes);
@@ -936,6 +993,10 @@ export class TermViewModel implements ViewModel {
         };
 
         const fullMenu: ContextMenuItem[] = [];
+        const tmuxSubmenu = await this.getTmuxSessionMenuItems();
+        if (tmuxSubmenu != null) {
+            fullMenu.push(tmuxSubmenu, { type: "separator" });
+        }
         fullMenu.push({
             label: "Split Horizontally",
             click: () => {

frontend/app/view/term/term.tsx

@@ -378,8 +378,10 @@ const TerminalView = ({ blockId, model }: ViewComponentProps<TermViewModel>) =>
         (e: React.MouseEvent<HTMLDivElement>) => {
             e.preventDefault();
             e.stopPropagation();
-            const menuItems = model.getContextMenuItems();
-            ContextMenuModel.getInstance().showContextMenu(menuItems, e);
+            fireAndForget(async () => {
+                const menuItems = await model.getContextMenuItems();
+                ContextMenuModel.getInstance().showContextMenu(menuItems, e);
+            });
         },
         [model]
     );

frontend/app/view/term/tmux-session.test.ts

@@ -0,0 +1,61 @@
+// Copyright 2026, Command Line Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it, vi } from "vitest";
+
+import { applyTmuxSessionChange, toggleTmuxSession } from "./tmux-session";
+
+describe("toggleTmuxSession", () => {
+    it("associates an unchecked session", () => {
+        expect(toggleTmuxSession("", "mactop-3")).toBe("mactop-3");
+        expect(toggleTmuxSession("workspace-8", "mactop-3")).toBe("mactop-3");
+    });
+
+    it("cancels the association when the checked session is selected again", () => {
+        expect(toggleTmuxSession("mactop-3", "mactop-3")).toBe("");
+    });
+});
+
+describe("applyTmuxSessionChange", () => {
+    it("does nothing when the selected session is already active", async () => {
+        const persistSession = vi.fn(async () => {});
+        const restartController = vi.fn(async () => {});
+
+        const changed = await applyTmuxSessionChange("mactop-3", "mactop-3", persistSession, restartController);
+
+        expect(changed).toBe(false);
+        expect(persistSession).not.toHaveBeenCalled();
+        expect(restartController).not.toHaveBeenCalled();
+    });
+
+    it.each([
+        ["cancel", "mactop-3", ""],
+        ["switch", "mactop-3", "workspace-8"],
+        ["associate", "", "mactop-3"],
+    ])("persists and restarts when attempting to %s", async (_operation, currentSession, nextSession) => {
+        const calls: string[] = [];
+        const persistSession = vi.fn(async (session: string) => {
+            calls.push(`persist:${session}`);
+        });
+        const restartController = vi.fn(async () => {
+            calls.push("restart");
+        });
+
+        const changed = await applyTmuxSessionChange(currentSession, nextSession, persistSession, restartController);
+
+        expect(changed).toBe(true);
+        expect(calls).toEqual([`persist:${nextSession}`, "restart"]);
+    });
+
+    it("does not restart when persisting the session fails", async () => {
+        const persistSession = vi.fn(async () => {
+            throw new Error("set meta failed");
+        });
+        const restartController = vi.fn(async () => {});
+
+        await expect(applyTmuxSessionChange("mactop-3", "", persistSession, restartController)).rejects.toThrow(
+            "set meta failed"
+        );
+        expect(restartController).not.toHaveBeenCalled();
+    });
+});

frontend/app/view/term/tmux-session.ts

@@ -0,0 +1,20 @@
+// Copyright 2026, Command Line Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export async function applyTmuxSessionChange(
+    currentSession: string,
+    nextSession: string,
+    persistSession: (session: string) => Promise<void>,
+    restartController: () => Promise<void>
+): Promise<boolean> {
+    if (currentSession === nextSession) {
+        return false;
+    }
+    await persistSession(nextSession);
+    await restartController();
+    return true;
+}
+
+export function toggleTmuxSession(currentSession: string, selectedSession: string): string {
+    return currentSession === selectedSession ? "" : selectedSession;
+}

frontend/types/custom.d.ts

@@ -353,7 +353,7 @@ declare global {
         isBasicTerm?: (getFn: jotai.Getter) => boolean;
 
         // Returns menu items for the settings dropdown.
-        getSettingsMenuItems?: () => ContextMenuItem[];
+        getSettingsMenuItems?: () => ContextMenuItem[] | Promise<ContextMenuItem[]>;
 
         // Attempts to give focus to the block, returning true if successful.
         giveFocus?: () => boolean;

frontend/types/gotypes.d.ts

@@ -1190,6 +1190,7 @@ declare global {
         "term:bellindicator"?: boolean;
         "term:osc52"?: string;
         "term:durable"?: boolean;
+        "term:tmux:session"?: string;
         "web:zoom"?: number;
         "web:hidenav"?: boolean;
         "web:partition"?: string;

pkg/blockcontroller/blockcontroller.go

@@ -490,5 +490,30 @@ func makeSwapToken(ctx context.Context, logCtx context.Context, blockId string,
 		token.Env[k] = v
 	}
 	token.ScriptText = getCustomInitScript(logCtx, blockMeta, remoteName, shellType)
+	token.ScriptText += buildTmuxAttachScript(blockMeta, remoteName, shellType)
 	return token
 }
+
+// buildTmuxAttachScript returns an inline script fragment that auto-attaches to a tmux
+// session (or an empty string when it does not apply). It is injected only when the block
+// carries a term:tmux:session meta key, the connection is a remote SSH block, and the shell
+// is a POSIX-compatible shell (bash/zsh). fish and pwsh use a different syntax, so the
+// fragment is skipped for them rather than emitting syntax they cannot parse.
+func buildTmuxAttachScript(blockMeta waveobj.MetaMapType, remoteName string, shellType string) string {
+	tmuxSession := blockMeta.GetString(waveobj.MetaKey_TermTmuxSession, "")
+	if tmuxSession == "" {
+		return ""
+	}
+	if conncontroller.IsLocalConnName(remoteName) {
+		return ""
+	}
+	if shellType != shellutil.ShellType_bash && shellType != shellutil.ShellType_zsh {
+		return ""
+	}
+	// Wrap the session name in shell single quotes, escaping any inner single quote as '\''
+	// so session names cannot break out of the command (injection-safe).
+	quoted := "'" + strings.ReplaceAll(tmuxSession, "'", "'\\''") + "'"
+	// Skip when already inside tmux to avoid nesting; fall back gracefully when tmux is not
+	// installed on the remote; exec replaces the shell so no empty shell lingers behind.
+	return fmt.Sprintf("\n[ -n \"$TMUX\" ] || ! command -v tmux >/dev/null 2>&1 || exec tmux new -A -t %s\n", quoted)
+}

pkg/blockcontroller/blockcontroller_test.go

@@ -0,0 +1,90 @@
+// Copyright 2026, Command Line Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package blockcontroller
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/wavetermdev/waveterm/pkg/util/shellutil"
+	"github.com/wavetermdev/waveterm/pkg/waveobj"
+)
+
+// Requirement: auto-associate remote sessions with tmux.
+// Acceptance criteria coverage:
+// 1. Remote block with term:tmux:session → tmux attach is injected (bash/zsh)
+// 2. Local block / block without the meta key → no injection
+// 3. Session names are quote-escaped to prevent injection
+// 4. Unsupported shells (fish/pwsh) → no injection (syntax would not parse)
+
+func TestBuildTmuxAttachScript_RemoteConn(t *testing.T) {
+	meta := waveobj.MetaMapType{
+		waveobj.MetaKey_TermTmuxSession: "omlx-11335",
+	}
+	for _, shellType := range []string{shellutil.ShellType_bash, shellutil.ShellType_zsh} {
+		script := buildTmuxAttachScript(meta, "aws:co-gpu", shellType)
+		if script == "" {
+			t.Fatalf("expected tmux attach script for remote conn with shell %q", shellType)
+		}
+		if !strings.Contains(script, `exec tmux new -A -t 'omlx-11335'`) {
+			t.Fatalf("unexpected attach command: %q", script)
+		}
+		if !strings.Contains(script, `[ -n "$TMUX" ]`) {
+			t.Fatalf("missing nested tmux guard: %q", script)
+		}
+		if !strings.Contains(script, `command -v tmux`) {
+			t.Fatalf("missing tmux presence guard: %q", script)
+		}
+	}
+}
+
+func TestBuildTmuxAttachScript_UnsupportedShell(t *testing.T) {
+	meta := waveobj.MetaMapType{
+		waveobj.MetaKey_TermTmuxSession: "omlx-11335",
+	}
+	for _, shellType := range []string{shellutil.ShellType_fish, shellutil.ShellType_pwsh, shellutil.ShellType_unknown} {
+		if script := buildTmuxAttachScript(meta, "aws:co-gpu", shellType); script != "" {
+			t.Fatalf("expected no script for shell %q, got %q", shellType, script)
+		}
+	}
+}
+
+func TestBuildTmuxAttachScript_LocalConn(t *testing.T) {
+	meta := waveobj.MetaMapType{
+		waveobj.MetaKey_TermTmuxSession: "omlx-11335",
+	}
+	for _, connName := range []string{"local", "local:whatever", ""} {
+		if script := buildTmuxAttachScript(meta, connName, shellutil.ShellType_bash); script != "" {
+			t.Fatalf("expected no script for local conn %q, got %q", connName, script)
+		}
+	}
+}
+
+func TestBuildTmuxAttachScript_NoMetaKey(t *testing.T) {
+	if script := buildTmuxAttachScript(waveobj.MetaMapType{}, "aws:co-gpu", shellutil.ShellType_bash); script != "" {
+		t.Fatalf("expected no script when meta key absent, got %q", script)
+	}
+	if script := buildTmuxAttachScript(waveobj.MetaMapType{waveobj.MetaKey_TermTmuxSession: ""}, "aws:co-gpu", shellutil.ShellType_bash); script != "" {
+		t.Fatalf("expected no script when session name empty, got %q", script)
+	}
+}
+
+func TestBuildTmuxAttachScript_EscapesSessionName(t *testing.T) {
+	meta := waveobj.MetaMapType{
+		waveobj.MetaKey_TermTmuxSession: `evil"; rm -rf /; echo "`,
+	}
+	script := buildTmuxAttachScript(meta, "aws:co-gpu", shellutil.ShellType_bash)
+	// Session names must be single-quoted so inner double quotes / semicolons cannot break shell structure.
+	if !strings.Contains(script, `-t 'evil"; rm -rf /; echo "'`) {
+		t.Fatalf("expected single-quoted session name, got: %q", script)
+	}
+	// Session names containing single quotes are also safe: inner single quotes escape to '\''.
+	meta2 := waveobj.MetaMapType{
+		waveobj.MetaKey_TermTmuxSession: `a'b`,
+	}
+	script2 := buildTmuxAttachScript(meta2, "aws:co-gpu", shellutil.ShellType_bash)
+	if !strings.Contains(script2, `-t 'a'\''b'`) {
+		t.Fatalf("expected escaped inner single quote, got: %q", script2)
+	}
+}

pkg/waveobj/metaconsts.go

@@ -129,6 +129,7 @@ const (
 	MetaKey_TermBellIndicator                = "term:bellindicator"
 	MetaKey_TermOsc52                        = "term:osc52"
 	MetaKey_TermDurable                      = "term:durable"
+	MetaKey_TermTmuxSession                  = "term:tmux:session"
 
 	MetaKey_WebZoom                          = "web:zoom"
 	MetaKey_WebHideNav                       = "web:hidenav"

pkg/waveobj/wtypemeta.go

@@ -133,6 +133,7 @@ type MetaTSType struct {
 	TermBellIndicator       *bool    `json:"term:bellindicator,omitempty"`
 	TermOsc52               string   `json:"term:osc52,omitempty"`
 	TermDurable             *bool    `json:"term:durable,omitempty"`
+	TermTmuxSession         string   `json:"term:tmux:session,omitempty"`
 
 	WebZoom          float64 `json:"web:zoom,omitempty"`
 	WebHideNav       *bool   `json:"web:hidenav,omitempty"`

pkg/wshrpc/wshclient/wshclient.go

@@ -616,6 +616,12 @@ func ListAllEditableAppsCommand(w *wshutil.WshRpc, opts *wshrpc.RpcOpts) ([]wshr
 	return resp, err
 }
 
+// command "listtmuxsessions", wshserver.ListTmuxSessionsCommand
+func ListTmuxSessionsCommand(w *wshutil.WshRpc, data string, opts *wshrpc.RpcOpts) ([]string, error) {
+	resp, err := sendRpcRequestCallHelper[[]string](w, "listtmuxsessions", data, opts)
+	return resp, err
+}
+
 // command "macosversion", wshserver.MacOSVersionCommand
 func MacOSVersionCommand(w *wshutil.WshRpc, opts *wshrpc.RpcOpts) (string, error) {
 	resp, err := sendRpcRequestCallHelper[string](w, "macosversion", nil, opts)