diff --git a/Resources/shell-integration/cmux-bash-integration.bash b/Resources/shell-integration/cmux-bash-integration.bash
index 4a22e3a171c3..4cf8735716c2 100644
--- a/Resources/shell-integration/cmux-bash-integration.bash
+++ b/Resources/shell-integration/cmux-bash-integration.bash
@@ -509,4 +509,41 @@ _cmux_fix_path() {
 _cmux_fix_path
 unset -f _cmux_fix_path
 
+# tmux auto-CC: when the user runs `tmux attach` or `tmux new-session`
+# in an interactive cmux terminal, automatically add -CC so native pane
+# rendering activates. Use `command tmux ...` to bypass, or set
+# CMUX_TMUX_AUTO_CC=0 to disable globally.
+tmux() {
+    # Opt-out
+    [[ "${CMUX_TMUX_AUTO_CC:-1}" == "0" ]] && { command tmux "$@"; return $?; }
+    # Inside cmux, $TMUX may be inherited from the launcher env but
+    # this terminal is NOT really inside tmux — ignore it.
+    # Outside cmux (no CMUX_SOCKET_PATH), respect $TMUX as usual.
+    [[ -z "$CMUX_SOCKET_PATH" && -n "$TMUX" ]] && { command tmux "$@"; return $?; }
+    [[ "$-" == *i* ]] || { command tmux "$@"; return $?; }
+    [[ -t 1 ]] || { command tmux "$@"; return $?; }
+    # Already has -CC or -C
+    local arg; for arg in "$@"; do
+        [[ "$arg" == "-CC" || "$arg" == "-C" ]] && { command tmux "$@"; return $?; }
+        [[ "$arg" == "--" ]] && break
+    done
+    # Determine the tmux subcommand (skip global flags that take a value)
+    local subcmd="" skip_next=0
+    for arg in "$@"; do
+        if (( skip_next )); then skip_next=0; continue; fi
+        case "$arg" in
+            -L|-S|-f|-c) skip_next=1; continue ;;  # these flags consume the next arg
+            -*) continue ;;
+            *) subcmd="$arg"; break ;;
+        esac
+    done
+    # Only auto-add -CC for commands that start a tmux client
+    case "$subcmd" in
+        attach|attach-session|a|new|new-session|"")
+            command tmux -CC "$@" ;;
+        *)
+            command tmux "$@" ;;
+    esac
+}
+
 _cmux_install_prompt_command
diff --git a/Resources/shell-integration/cmux-zsh-integration.zsh b/Resources/shell-integration/cmux-zsh-integration.zsh
index e9bbf235f6dc..f29b52786746 100644
--- a/Resources/shell-integration/cmux-zsh-integration.zsh
+++ b/Resources/shell-integration/cmux-zsh-integration.zsh
@@ -567,8 +567,46 @@ _cmux_zshexit() {
     _cmux_stop_pr_poll_loop
 }
 
+# tmux auto-CC: installed on first prompt (after .zshrc) so user plugins
+# cannot shadow it. Use `command tmux ...` to bypass, or set
+# CMUX_TMUX_AUTO_CC=0 to disable globally.
+_cmux_install_tmux_wrapper() {
+    # Define/redefine the tmux function, overriding any plugin definition
+    tmux() {
+        [[ "${CMUX_TMUX_AUTO_CC:-1}" == "0" ]] && { command tmux "$@"; return $?; }
+        # Inside cmux, $TMUX may be inherited from the launcher env but
+        # this terminal is NOT really inside tmux — ignore it.
+        # Outside cmux (no CMUX_SOCKET_PATH), respect $TMUX as usual.
+        [[ -z "$CMUX_SOCKET_PATH" && -n "$TMUX" ]] && { command tmux "$@"; return $?; }
+        [[ -o interactive ]] || { command tmux "$@"; return $?; }
+        [[ -t 1 ]] || { command tmux "$@"; return $?; }
+        local arg; for arg in "$@"; do
+            [[ "$arg" == "-CC" || "$arg" == "-C" ]] && { command tmux "$@"; return $?; }
+            [[ "$arg" == "--" ]] && break
+        done
+        local subcmd="" skip_next=0
+        for arg in "$@"; do
+            if (( skip_next )); then skip_next=0; continue; fi
+            case "$arg" in
+                -L|-S|-f|-c) skip_next=1; continue ;;
+                -*) continue ;;
+                *) subcmd="$arg"; break ;;
+            esac
+        done
+        case "$subcmd" in
+            attach|attach-session|a|new|new-session|"")
+                command tmux -CC "$@" ;;
+            *)
+                command tmux "$@" ;;
+        esac
+    }
+    # Only need to install once
+    add-zsh-hook -d precmd _cmux_install_tmux_wrapper
+}
+
 autoload -Uz add-zsh-hook
 add-zsh-hook preexec _cmux_preexec
 add-zsh-hook precmd _cmux_precmd
 add-zsh-hook precmd _cmux_fix_path
+add-zsh-hook precmd _cmux_install_tmux_wrapper
 add-zsh-hook zshexit _cmux_zshexit
diff --git a/Sources/GhosttyTerminalView.swift b/Sources/GhosttyTerminalView.swift
index 013e387f1af6..5371ab6a4732 100644
--- a/Sources/GhosttyTerminalView.swift
+++ b/Sources/GhosttyTerminalView.swift
@@ -361,10 +361,11 @@ func cmuxPasteboardImagePathForTesting(_ pasteboard: NSPasteboard) -> String? {
 enum TerminalOpenURLTarget: Equatable {
     case embeddedBrowser(URL)
     case external(URL)
+    case internalFile(URL)
 
     var url: URL {
         switch self {
-        case let .embeddedBrowser(url), let .external(url):
+        case let .embeddedBrowser(url), let .external(url), let .internalFile(url):
             return url
         }
     }
@@ -457,13 +458,26 @@ func resolveTerminalOpenURLTarget(_ rawValue: String) -> TerminalOpenURLTarget?
 
     if NSString(string: trimmed).isAbsolutePath {
         #if DEBUG
-        dlog("link.resolve result=external(absolutePath) url=\(trimmed)")
+        dlog("link.resolve result=internalFile(absolutePath) path=\(trimmed)")
         #endif
-        return .external(URL(fileURLWithPath: trimmed))
+        return .internalFile(URL(fileURLWithPath: trimmed))
     }
 
     if let parsed = URL(string: trimmed),
        let scheme = parsed.scheme?.lowercased() {
+        if scheme == "file" {
+            let host = parsed.host?.lowercased()
+            if host == nil || host == "" || host == "localhost" {
+                #if DEBUG
+                dlog("link.resolve result=internalFile(fileURL) path=\(parsed.path)")
+                #endif
+                return .internalFile(parsed)
+            }
+            #if DEBUG
+            dlog("link.resolve result=external(remoteFileURL) url=\(parsed)")
+            #endif
+            return .external(parsed)
+        }
         if scheme == "http" || scheme == "https" {
             guard BrowserInsecureHTTPSettings.normalizeHost(parsed.host ?? "") != nil else {
                 #if DEBUG
@@ -2001,6 +2015,17 @@ class GhosttyApp {
         let callbackTabId = callbackContext?.tabId
         let callbackSurfaceId = callbackContext?.surfaceId
 
+        #if DEBUG
+        // Trace tmux-related actions to debug control mode activation
+        if action.tag == GHOSTTY_ACTION_TMUX_STATE ||
+           action.tag == GHOSTTY_ACTION_TMUX_WINDOWS_CHANGED ||
+           action.tag == GHOSTTY_ACTION_TMUX_PANE_UNREGISTERED {
+            let ctxOk = callbackContext != nil
+            let svOk = callbackContext?.surfaceView != nil
+            dlog("tmux.action tag=\(action.tag.rawValue) ctxOk=\(ctxOk) svOk=\(svOk) tabId=\(callbackTabId?.uuidString.prefix(5) ?? "nil")")
+        }
+        #endif
+
         if action.tag == GHOSTTY_ACTION_SHOW_CHILD_EXITED {
             // The child (shell) exited. Ghostty will fall back to printing
             // "Process exited. Press any key..." into the terminal unless the host
@@ -2291,6 +2316,17 @@ class GhosttyApp {
                 surfaceView.updateKeyTable(action.action.key_table)
                 return true
             }
+        case GHOSTTY_ACTION_MOUSE_OVER_LINK:
+            #if DEBUG
+            let mol = action.action.mouse_over_link
+            if let ptr = mol.url, mol.len > 0 {
+                let linkStr = String(data: Data(bytes: ptr, count: Int(mol.len)), encoding: .utf8) ?? ""
+                dlog("link.mouseOverLink url=\(linkStr)")
+            } else {
+                dlog("link.mouseOverLink url=nil (cleared)")
+            }
+            #endif
+            return true
         case GHOSTTY_ACTION_OPEN_URL:
             let openUrl = action.action.open_url
             guard let cstr = openUrl.url else { return false }
@@ -2307,7 +2343,9 @@ class GhosttyApp {
                 #endif
                 return false
             }
-            if !BrowserLinkOpenSettings.openTerminalLinksInCmuxBrowser() {
+            if case .internalFile = target {
+                // Local file routing should not depend on the browser-link setting.
+            } else if !BrowserLinkOpenSettings.openTerminalLinksInCmuxBrowser() {
                 #if DEBUG
                 dlog("link.openURL cmuxBrowser=disabled, opening externally url=\(target.url)")
                 #endif
@@ -2316,6 +2354,50 @@ class GhosttyApp {
                 }
             }
             switch target {
+            case let .internalFile(fileURL):
+                let path = fileURL.path
+                #if DEBUG
+                dlog("link.openURL target=internalFile, opening in markdown panel path=\(path)")
+                #endif
+                // Validate the path is a readable file (not a directory or missing).
+                // Fall back to system handler if validation fails.
+                var isDir: ObjCBool = false
+                let fileExists = FileManager.default.fileExists(atPath: path, isDirectory: &isDir)
+                guard fileExists, !isDir.boolValue else {
+                    #if DEBUG
+                    dlog("link.openURL internalFile not a readable file, falling back to external path=\(path)")
+                    #endif
+                    return performOnMain {
+                        NSWorkspace.shared.open(fileURL)
+                    }
+                }
+                let sourceWorkspaceId = callbackTabId ?? surfaceView.tabId
+                let sourcePanelId = callbackSurfaceId ?? surfaceView.terminalSurface?.id
+                guard let sourceWorkspaceId, let sourcePanelId else {
+                    return performOnMain {
+                        NSWorkspace.shared.open(fileURL)
+                    }
+                }
+                return performOnMain {
+                    guard let app = AppDelegate.shared,
+                          let resolved = app.workspaceContainingPanel(
+                            panelId: sourcePanelId,
+                            preferredWorkspaceId: sourceWorkspaceId
+                          ) else {
+                        NSWorkspace.shared.open(fileURL)
+                        return true
+                    }
+                    if resolved.workspace.newMarkdownSplit(
+                        from: sourcePanelId,
+                        orientation: .horizontal,
+                        filePath: path
+                    ) != nil {
+                        return true
+                    }
+                    // Split creation failed — fall back to system handler
+                    NSWorkspace.shared.open(fileURL)
+                    return true
+                }
             case let .external(url):
                 #if DEBUG
                 dlog("link.openURL target=external, opening externally url=\(url)")
@@ -2401,6 +2483,33 @@ class GhosttyApp {
                     }
                 }
             }
+        case GHOSTTY_ACTION_TMUX_STATE:
+            let entered = action.action.tmux_state == GHOSTTY_TMUX_STATE_ENTER
+            #if DEBUG
+            dlog("tmux.state entered=\(entered)")
+            #endif
+            return performOnMain {
+                surfaceView.tmuxControlMode = entered
+                if entered {
+                    surfaceView.tmuxLoadPrefixConfig()
+                } else {
+                    surfaceView.tmuxResetPrefixState()
+                    surfaceView.tmuxCleanupAllPanes()
+                }
+                return true
+            }
+        case GHOSTTY_ACTION_TMUX_WINDOWS_CHANGED:
+            return performOnMain {
+                surfaceView.handleTmuxWindowsChanged()
+                return true
+            }
+        case GHOSTTY_ACTION_TMUX_PANE_UNREGISTERED:
+            let paneId = action.action.tmux_pane_unregistered.pane_id
+            let regId = action.action.tmux_pane_unregistered.reg_id
+            return performOnMain {
+                surfaceView.handleTmuxPaneUnregistered(paneId: paneId, regId: regId)
+                return true
+            }
         default:
             return false
         }
@@ -3537,6 +3646,56 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
     var desiredFocus: Bool = false
     var suppressingReparentFocus: Bool = false
     var tabId: UUID?
+    /// True when this surface is in tmux control mode.
+    var tmuxControlMode: Bool = false
+
+    /// Tmux pane surface management (Phase 2).
+    struct TmuxPaneState {
+        let surface: ghostty_surface_t
+        let view: NSView
+        let regId: UInt32
+        let writeContext: UnsafeMutablePointer<TmuxPaneWriteContext>
+    }
+
+    /// Context passed through the C io_write_cb for a tmux pane surface.
+    class TmuxPaneWriteContext {
+        let hostSurface: ghostty_surface_t
+        let paneId: UInt
+
+        init(hostSurface: ghostty_surface_t, paneId: UInt) {
+            self.hostSurface = hostSurface
+            self.paneId = paneId
+        }
+    }
+
+    var tmuxPaneSurfaces: [UInt: TmuxPaneState] = [:]
+    var tmuxRegIdCounter: UInt32 = 0
+    var tmuxPaneContainer: NSView?
+    var tmuxStatusBar: NSTextField?
+    var tmuxStatusBarTimer: Timer?
+    /// Pane IDs awaiting unregister ack before surface can be freed.
+    var tmuxPendingUnregister: [UInt: UInt32] = [:]
+    /// Last tmux client size we requested via refresh-client -C.
+    var tmuxRequestedClientSize: (cols: Int, rows: Int)?
+
+    // MARK: - Tmux Prefix Layer
+
+    /// Configuration loaded from tmux: prefix keys and key bindings.
+    struct TmuxPrefixConfig {
+        /// Keys that activate prefix mode, e.g. ["C-b", "C-Space"]
+        var prefixKeys: Set<String> = []
+        /// Bindings: tmux key name → tmux command, e.g. "d" → "detach-client"
+        var bindings: [String: String] = [:]
+        var loaded: Bool = false
+    }
+
+    enum TmuxPrefixState {
+        case idle
+        case pending
+    }
+
+    private var tmuxPrefixConfig = TmuxPrefixConfig()
+    private var tmuxPrefixState: TmuxPrefixState = .idle
     var onFocus: (() -> Void)?
     var onTriggerFlash: (() -> Void)?
     var backgroundColor: NSColor?
@@ -4066,6 +4225,29 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
         terminalSurface?.surface
     }
 
+    /// The pane ID that was last clicked or focused. Updated on mouseDown.
+    private var tmuxActivePaneId: UInt?
+
+    /// Returns the active tmux pane state, or nil if not in tmux mode.
+    /// Returns the last-clicked pane, falling back to the first pane.
+    private var activeTmuxPane: TmuxPaneState? {
+        guard tmuxControlMode else { return nil }
+        if let id = tmuxActivePaneId, let state = tmuxPaneSurfaces[id] {
+            return state
+        }
+        // Fallback: first pane (single-pane case)
+        return tmuxPaneSurfaces.values.first
+    }
+
+    /// Returns the surface that should receive keyboard/IME input.
+    /// In tmux control mode, returns the active pane surface; otherwise the host surface.
+    private var inputSurface: ghostty_surface_t? {
+        if let pane = activeTmuxPane {
+            return pane.surface
+        }
+        return surface
+    }
+
     private func applySurfaceColorScheme(force: Bool = false) {
         guard let surface else { return }
         let bestMatch = effectiveAppearance.bestMatch(from: [.darkAqua, .aqua])
@@ -4104,9 +4286,11 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
     }
 
     func performBindingAction(_ action: String) -> Bool {
-        guard let surface = surface else { return false }
+        // In tmux mode, route binding actions (paste, copy, etc.) to the
+        // pane surface so they operate on the pane's terminal content.
+        guard let target = inputSurface ?? surface else { return false }
         return action.withCString { cString in
-            ghostty_surface_binding_action(surface, cString, UInt(strlen(cString)))
+            ghostty_surface_binding_action(target, cString, UInt(strlen(cString)))
         }
     }
 
@@ -4325,6 +4509,38 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
     // MARK: - Clipboard paste
 
     @IBAction func paste(_ sender: Any?) {
+        // In tmux mode, Ghostty's async clipboard flow would send the result
+        // back to the host surface (shared userdata). Instead, read the
+        // clipboard directly and route through the pane's send-keys path.
+        if let paneState = activeTmuxPane {
+            guard let str = NSPasteboard.general.string(forType: .string),
+                  !str.isEmpty else { return }
+            let hostSurface = paneState.writeContext.pointee.hostSurface
+            let paneId = paneState.writeContext.pointee.paneId
+            // Split by newlines to avoid raw newlines breaking the tmux
+            // command stream. Each line is sent as literal text, with
+            // explicit Enter key events between lines.
+            let lines = str.components(separatedBy: .newlines)
+            for (i, line) in lines.enumerated() {
+                if !line.isEmpty, let data = line.data(using: .utf8) {
+                    data.withUnsafeBytes { rawBuf in
+                        let ptr = rawBuf.baseAddress!.assumingMemoryBound(to: UInt8.self)
+                        ghostty_surface_tmux_send_keys(hostSurface, paneId, ptr, data.count, 0)
+                    }
+                }
+                // Send Enter between lines (not after the last line)
+                if i < lines.count - 1 {
+                    "Enter".withCString { cstr in
+                        ghostty_surface_tmux_send_keys(
+                            hostSurface, paneId,
+                            UnsafePointer<UInt8>(OpaquePointer(cstr)),
+                            strlen(cstr), 1  // key_type=1 (key name)
+                        )
+                    }
+                }
+            }
+            return
+        }
         _ = performBindingAction("paste_from_clipboard")
     }
 
@@ -4528,6 +4744,8 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
         let result = super.resignFirstResponder()
         if result {
             desiredFocus = false
+            // Cancel tmux prefix mode on focus loss
+            if tmuxPrefixState == .pending { tmuxPrefixState = .idle }
         }
         if result, let surface = surface {
             let now = CACurrentMediaTime()
@@ -4541,6 +4759,8 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
     // For NSTextInputClient - accumulates text during key events
     private var keyTextAccumulator: [String]? = nil
     private var markedText = NSMutableAttributedString()
+    /// Cursor position within the IME preedit text (from setMarkedText selectedRange).
+    private var markedTextCursorOffset: Int = 0
     private var lastPerformKeyEvent: TimeInterval?
     private struct SelectionSnapshot {
         let range: NSRange
@@ -4755,13 +4975,62 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
         }
         let ensureSurfaceStart = ProcessInfo.processInfo.systemUptime
 #endif
-        guard let surface = ensureSurfaceReadyForInput() else {
+        guard var surface = ensureSurfaceReadyForInput() else {
 #if DEBUG
             ensureSurfaceMs = (ProcessInfo.processInfo.systemUptime - ensureSurfaceStart) * 1000.0
 #endif
             super.keyDown(with: event)
             return
         }
+        // In tmux control mode, redirect keyboard input to the pane surface.
+        // This preserves the full keyDown flow (IME, interpretKeyEvents, etc.)
+        // while routing the encoded key bytes to the pane's Manual I/O backend.
+        // If tmux mode is active but pane surfaces aren't ready yet, drop the
+        // key event to avoid sending it to the host surface (which would eat it).
+        if tmuxControlMode && tmuxPaneSurfaces.isEmpty {
+            return
+        }
+
+        // Tmux prefix key state machine: intercept prefix keys before
+        // they reach Ghostty's key handler or the pane surface.
+        // Only active when not composing IME text (markedText).
+        if tmuxControlMode && tmuxPrefixConfig.loaded && !hasMarkedText() {
+            if let key = tmuxKeyName(for: event) {
+                switch tmuxPrefixState {
+                case .idle:
+                    if tmuxPrefixConfig.prefixKeys.contains(key) {
+                        tmuxPrefixState = .pending
+                        #if DEBUG
+                        dlog("tmux.prefix PENDING key=\(key)")
+                        #endif
+                        return
+                    }
+                case .pending:
+                    tmuxPrefixState = .idle
+                    if let command = tmuxPrefixConfig.bindings[key] {
+                        #if DEBUG
+                        dlog("tmux.prefix EXEC key=\(key) cmd=\(command)")
+                        #endif
+                        tmuxSendCommand(command)
+                    } else {
+                        #if DEBUG
+                        dlog("tmux.prefix UNKNOWN key=\(key), beep")
+                        #endif
+                        NSSound.beep()
+                    }
+                    return
+                }
+            } else if tmuxPrefixState == .pending {
+                // Unmappable key while in prefix mode → cancel
+                tmuxPrefixState = .idle
+                NSSound.beep()
+                return
+            }
+        }
+
+        if let paneState = activeTmuxPane {
+            surface = paneState.surface
+        }
 #if DEBUG
         ensureSurfaceMs = (ProcessInfo.processInfo.systemUptime - ensureSurfaceStart) * 1000.0
 #endif
@@ -4931,12 +5200,9 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
 
         // Capture the keyboard layout ID before interpretation so we can
         // detect if an IME changed it (e.g. toggling input methods).
-        // We only check when not already in a preedit state.
-        let keyboardIdBefore: String? = if (!markedTextBefore) {
-            KeyboardLayout.id
-        } else {
-            nil
-        }
+        // We capture in both composing and non-composing states so that
+        // switching input methods during composition can commit the preedit.
+        let keyboardIdBefore: String? = KeyboardLayout.id
 
         // Let the input system handle the event (for IME, dead keys, etc.)
 #if DEBUG
@@ -4954,16 +5220,28 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
 #endif
 
         // If the keyboard layout changed, an input method grabbed the event.
-        // Sync preedit and return without sending the key to Ghostty.
-        if !markedTextBefore, let kbBefore = keyboardIdBefore, kbBefore != KeyboardLayout.id {
+        if let kbBefore = keyboardIdBefore, kbBefore != KeyboardLayout.id {
+            if markedTextBefore && markedText.length > 0 {
+                // Switching input methods mid-composition: commit the current
+                // preedit text as literal input so the user's typing isn't lost.
+                let commitText = markedText.string
+                markedText.mutableString.setString("")
+                syncPreedit(clearIfNeeded: true)
+                if !commitText.isEmpty {
+                    keyTextAccumulator?.append(commitText)
+                }
+                // Fall through to send the accumulated text via ghostty_surface_key
+            } else {
+                // No composition was active — sync preedit and return.
 #if DEBUG
-            let syncPreeditStart = ProcessInfo.processInfo.systemUptime
+                let syncPreeditStart = ProcessInfo.processInfo.systemUptime
 #endif
-            syncPreedit(clearIfNeeded: markedTextBefore)
+                syncPreedit(clearIfNeeded: markedTextBefore)
 #if DEBUG
-            syncPreeditMs = (ProcessInfo.processInfo.systemUptime - syncPreeditStart) * 1000.0
+                syncPreeditMs = (ProcessInfo.processInfo.systemUptime - syncPreeditStart) * 1000.0
 #endif
-            return
+                return
+            }
         }
 
         // Sync the preedit state with Ghostty so it can render the IME
@@ -5394,16 +5672,974 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
             )
         }
         guard let surface = surface else { return }
+
+        // In tmux mode, route mouse events to the pane surface so Ghostty's
+        // native link detection works on the pane's real Terminal content.
+        #if DEBUG
+        dlog("tmux.mouseDown check tmuxControlMode=\(tmuxControlMode) paneCount=\(tmuxPaneSurfaces.count)")
+        #endif
+        if let paneState = activeTmuxPane {
+            let paneSurface = paneState.surface
+            let point = paneState.view.convert(event.locationInWindow, from: nil)
+            let y = paneState.view.bounds.height - point.y
+            #if DEBUG
+            dlog("tmux.mouseDown routed to pane regId=\(paneState.regId) point=(\(String(format: "%.0f", point.x)),\(String(format: "%.0f", y))) cmd=\(event.modifierFlags.contains(.command))")
+            #endif
+            // Track and sync active pane with tmux so prefix commands target the right pane
+            let paneId = paneState.writeContext.pointee.paneId
+            tmuxActivePaneId = paneId
+            tmuxSendCommand("select-pane -t %\(paneId)")
+            // Cancel prefix mode on click
+            if tmuxPrefixState == .pending { tmuxPrefixState = .idle }
+            ghostty_surface_mouse_pos(paneSurface, point.x, y, modsFromEvent(event))
+            _ = ghostty_surface_mouse_button(paneSurface, GHOSTTY_MOUSE_PRESS, GHOSTTY_MOUSE_LEFT, modsFromEvent(event))
+            return
+        }
+
         let point = convert(event.locationInWindow, from: nil)
         ghostty_surface_mouse_pos(surface, point.x, bounds.height - point.y, modsFromEvent(event))
         _ = ghostty_surface_mouse_button(surface, GHOSTTY_MOUSE_PRESS, GHOSTTY_MOUSE_LEFT, modsFromEvent(event))
     }
 
+    /// Handle cmd+click in tmux control mode by querying pane text
+    /// and finding file paths at the clicked row.
+    private func handleTmuxCmdClick(surface: ghostty_surface_t, event: NSEvent) -> Bool {
+        let point = convert(event.locationInWindow, from: nil)
+        // Convert pixel position to terminal row (0-indexed, top=0)
+        guard cellSize.height > 0 else { return false }
+        let row = Int((bounds.height - point.y) / cellSize.height)
+        let col = Int(point.x / cellSize.width)
+
+        #if DEBUG
+        dlog("tmux.cmdClick row=\(row) col=\(col)")
+        #endif
+
+        // Query tmux pane text
+        var textResult = ghostty_text_s()
+        guard ghostty_surface_tmux_pane_text(surface, UInt.max, &textResult),
+              let ptr = textResult.text else {
+            #if DEBUG
+            dlog("tmux.cmdClick pane text query failed")
+            #endif
+            return false
+        }
+        defer { var mutable = textResult; ghostty_surface_free_text(surface, &mutable) }
+
+        let fullText = String(cString: ptr)
+        let lines = fullText.components(separatedBy: "\n")
+
+        guard row >= 0 && row < lines.count else {
+            #if DEBUG
+            dlog("tmux.cmdClick row \(row) out of range (lines=\(lines.count))")
+            #endif
+            return false
+        }
+
+        let line = lines[row]
+        #if DEBUG
+        dlog("tmux.cmdClick line[\(row)]=\(line.prefix(120))")
+        #endif
+
+        // Find file paths in the clicked line using a simple regex:
+        // absolute paths (/...) or ~/ paths
+        guard let regex = try? NSRegularExpression(
+            pattern: "(?:/[\\w.@~+-]+)+(?::\\d+)?|~/[\\w.@/+-]+(?::\\d+)?",
+            options: []
+        ) else { return false }
+
+        let nsLine = line as NSString
+        let matches = regex.matches(in: line, range: NSRange(location: 0, length: nsLine.length))
+
+        // Find the match that contains the click column
+        for match in matches {
+            let range = match.range
+            if col >= range.location && col < range.location + range.length {
+                let path = nsLine.substring(with: range)
+                #if DEBUG
+                dlog("tmux.cmdClick matched path=\(path) at col \(range.location)-\(range.location + range.length)")
+                #endif
+                return openTmuxClickedPath(path)
+            }
+        }
+
+        // No match at click position — try the nearest match on the line
+        if let nearest = matches.first {
+            let path = nsLine.substring(with: nearest.range)
+            #if DEBUG
+            dlog("tmux.cmdClick nearest path=\(path) (click col \(col) not inside match)")
+            #endif
+        }
+
+        return false
+    }
+
+    /// Open a file path found via tmux cmd+click.
+    private func openTmuxClickedPath(_ rawPath: String) -> Bool {
+        // Strip optional :line_number suffix
+        let path: String
+        if let colonIdx = rawPath.lastIndex(of: ":"),
+           colonIdx > rawPath.startIndex,
+           rawPath[rawPath.index(after: colonIdx)...].allSatisfy(\.isNumber) {
+            path = String(rawPath[..<colonIdx])
+        } else {
+            path = rawPath
+        }
+
+        // Expand ~ to home directory
+        let expanded = (path as NSString).expandingTildeInPath
+
+        guard let target = resolveTerminalOpenURLTarget(expanded) else {
+            #if DEBUG
+            dlog("tmux.cmdClick resolve failed for path=\(expanded)")
+            #endif
+            return false
+        }
+
+        if case let .internalFile(fileURL) = target {
+            let filePath = fileURL.path
+            var isDir: ObjCBool = false
+            guard FileManager.default.fileExists(atPath: filePath, isDirectory: &isDir),
+                  !isDir.boolValue else {
+                #if DEBUG
+                dlog("tmux.cmdClick file not found or is directory path=\(filePath)")
+                #endif
+                return false
+            }
+
+            guard let tabId = tabId,
+                  let surfaceId = terminalSurface?.id,
+                  let app = AppDelegate.shared,
+                  let resolved = app.workspaceContainingPanel(
+                    panelId: surfaceId,
+                    preferredWorkspaceId: tabId
+                  ) else {
+                NSWorkspace.shared.open(fileURL)
+                return true
+            }
+
+            if resolved.workspace.newMarkdownSplit(
+                from: surfaceId,
+                orientation: .horizontal,
+                filePath: filePath
+            ) != nil {
+                #if DEBUG
+                dlog("tmux.cmdClick opened markdown panel path=\(filePath)")
+                #endif
+                return true
+            }
+            NSWorkspace.shared.open(fileURL)
+            return true
+        }
+
+        return false
+    }
+
+    // MARK: - Tmux Phase 2: Pane Surface Management
+
+    /// Handle tmux windows/pane topology change. Creates or destroys
+    /// native Ghostty surfaces for each tmux pane.
+    func handleTmuxWindowsChanged() {
+        guard let hostSurface = terminalSurface?.surface else { return }
+        guard let app = ghostty_surface_app(hostSurface) else { return }
+
+        // Query current pane topology
+        let count = ghostty_surface_tmux_panes(hostSurface, nil, 0)
+        guard count > 0 else {
+            #if DEBUG
+            dlog("tmux.windowsChanged: no panes")
+            #endif
+            return
+        }
+
+        var panes = [ghostty_tmux_pane_info_s](repeating: ghostty_tmux_pane_info_s(), count: Int(count))
+        let written = ghostty_surface_tmux_panes(hostSurface, &panes, count)
+
+        #if DEBUG
+        dlog("tmux.windowsChanged paneCount=\(written)")
+        #endif
+
+        // Determine which panes are new vs existing vs removed
+        let currentPaneIds = Set(panes[0..<Int(written)].map { $0.pane_id })
+        let existingPaneIds = Set(tmuxPaneSurfaces.keys)
+        let toAdd = currentPaneIds.subtracting(existingPaneIds)
+        let toRemove = existingPaneIds.subtracting(currentPaneIds)
+
+        // Remove stale panes (two-phase: unregister first, destroy on ack)
+        for paneId in toRemove {
+            guard let state = tmuxPaneSurfaces[paneId] else { continue }
+            tmuxPendingUnregister[paneId] = state.regId
+            ghostty_surface_tmux_unregister_pane(hostSurface, paneId, state.regId)
+            state.view.removeFromSuperview()
+            tmuxPaneSurfaces.removeValue(forKey: paneId)
+            #if DEBUG
+            dlog("tmux.pane remove pane=\(paneId) regId=\(state.regId)")
+            #endif
+        }
+
+        // Ensure container exists — add above the scroll view so it's
+        // not hidden behind the host terminal's Metal rendering layer.
+        if tmuxPaneContainer == nil {
+            let container = NSView(frame: bounds)
+            container.autoresizingMask = [.width, .height]
+            // Hide host terminal rendering but keep the view in the event
+            // chain for mouse handling. alphaValue=0 makes the Metal layer
+            // invisible without setting isHidden (which breaks hit-testing).
+            self.alphaValue = 0
+            // Walk up: GhosttyNSView → documentView → clipView → scrollView → GhosttySurfaceScrollView
+            if let parentView = enclosingScrollView?.superview {
+                parentView.addSubview(container, positioned: .above, relativeTo: nil)
+                container.frame = parentView.bounds
+                #if DEBUG
+                dlog("tmux.container added to parentView=\(type(of: parentView)) frame=\(parentView.bounds)")
+                #endif
+            } else {
+                if let contentView = window?.contentView {
+                    contentView.addSubview(container, positioned: .above, relativeTo: nil)
+                    container.frame = contentView.bounds
+                    #if DEBUG
+                    dlog("tmux.container fallback to window.contentView frame=\(contentView.bounds)")
+                    #endif
+                } else {
+                    addSubview(container)
+                    #if DEBUG
+                    dlog("tmux.container fallback to self (nothing else available)")
+                    #endif
+                }
+            }
+            tmuxPaneContainer = container
+
+            // Create tmux status bar at the bottom of the container.
+            // Matches tmux's default green status bar appearance.
+            let barHeight: CGFloat = max(cellSize.height, 18)
+            let barView = NSView(frame: NSRect(
+                x: 0, y: 0,
+                width: container.bounds.width,
+                height: barHeight
+            ))
+            barView.wantsLayer = true
+            barView.layer?.backgroundColor = NSColor(red: 0.0, green: 0.67, blue: 0.0, alpha: 1.0).cgColor
+            barView.autoresizingMask = [.width, .maxYMargin]
+
+            // Left-aligned label: [session] window:name
+            let leftLabel = NSTextField(frame: NSRect(
+                x: 0, y: 0,
+                width: container.bounds.width * 0.5,
+                height: barHeight
+            ))
+            leftLabel.isEditable = false
+            leftLabel.isSelectable = false
+            leftLabel.isBordered = false
+            leftLabel.drawsBackground = false
+            leftLabel.textColor = NSColor.black
+            leftLabel.font = NSFont.monospacedSystemFont(ofSize: min(cellSize.height * 0.65, 13), weight: .regular)
+            leftLabel.lineBreakMode = .byTruncatingTail
+            leftLabel.autoresizingMask = [.width, .maxYMargin]
+            leftLabel.tag = 1
+            barView.addSubview(leftLabel)
+
+            // Right-aligned label: time/date
+            let rightLabel = NSTextField(frame: NSRect(
+                x: container.bounds.width * 0.5, y: 0,
+                width: container.bounds.width * 0.5,
+                height: barHeight
+            ))
+            rightLabel.isEditable = false
+            rightLabel.isSelectable = false
+            rightLabel.isBordered = false
+            rightLabel.drawsBackground = false
+            rightLabel.textColor = NSColor.black
+            rightLabel.font = leftLabel.font
+            rightLabel.alignment = .right
+            rightLabel.lineBreakMode = .byTruncatingHead
+            rightLabel.autoresizingMask = [.width, .maxYMargin, .minXMargin]
+            rightLabel.tag = 2
+            barView.addSubview(rightLabel)
+
+            container.addSubview(barView)
+            tmuxStatusBar = leftLabel  // keep ref for updates
+
+            // Query tmux for session info using the first pane's ID
+            let firstPaneId = panes[0].pane_id
+            tmuxUpdateStatusBar(barView: barView, paneId: firstPaneId)
+
+            // Refresh status bar every 15 seconds
+            tmuxStartStatusBarTimer(barView: barView, paneId: firstPaneId)
+        }
+
+        let paneSlice = panes[0..<Int(written)]
+        let desiredClientSize = tmuxDesiredClientSize()
+        let currentClientSize = tmuxCurrentClientSize(paneSlice)
+
+        // Tell tmux the correct client size based on the pane container
+        // dimensions. Initial sync must wait until tmux reports geometry
+        // that matches the pane surface rows/cols; otherwise capture-pane
+        // will return a different number of rows and replay will scroll.
+        if let desired = desiredClientSize,
+           !(currentClientSize.map { $0.cols == desired.cols && $0.rows == desired.rows } ?? false) {
+            #if DEBUG
+            dlog("tmux.refreshClient desired=\(desired.cols)x\(desired.rows) current=\(currentClientSize?.cols ?? -1)x\(currentClientSize?.rows ?? -1)")
+            #endif
+            if tmuxRequestedClientSize?.cols != desired.cols || tmuxRequestedClientSize?.rows != desired.rows {
+                tmuxRequestedClientSize = desired
+                tmuxSendCommand("refresh-client -C \(desired.cols)x\(desired.rows)")
+            }
+        } else if let desired = desiredClientSize {
+            tmuxRequestedClientSize = desired
+        }
+
+        // Create surfaces for new panes
+        for i in 0..<Int(written) {
+            let paneInfo = panes[i]
+            guard toAdd.contains(paneInfo.pane_id) else { continue }
+
+            tmuxRegIdCounter += 1
+            let regId = tmuxRegIdCounter
+
+            // Create a host NSView for the pane surface.
+            // Do NOT set wantsLayer here — Ghostty's Metal renderer sets
+            // the view's layer property first, then enables wantsLayer
+            // (layer-hosting mode). Pre-setting wantsLayer creates a
+            // layer-backed view which breaks Metal rendering.
+            let paneView = NSView(frame: tmuxPaneFrame(paneInfo))
+            #if DEBUG
+            dlog("tmux.paneView frame=\(paneView.frame) container=\(tmuxPaneContainer?.frame ?? .zero)")
+            #endif
+            tmuxPaneContainer?.addSubview(paneView)
+
+            // Create Ghostty surface in Manual I/O mode
+            var config = ghostty_surface_config_new()
+            config.platform_tag = GHOSTTY_PLATFORM_MACOS
+            config.platform = ghostty_platform_u(macos: ghostty_platform_macos_s(
+                nsview: Unmanaged.passUnretained(paneView).toOpaque()
+            ))
+            if let window = window {
+                config.scale_factor = Double(window.backingScaleFactor)
+            }
+            config.io_mode = GHOSTTY_IO_MODE_MANUAL
+
+            // Share the host surface's callback context so actions dispatched
+            // from the pane surface (e.g. OPEN_URL on cmd+click) are routed
+            // to the host's GhosttyNSView action handler.
+            config.userdata = ghostty_surface_userdata(hostSurface)
+
+            // Set up write callback context (C function + opaque pointer)
+            let writeCtx = UnsafeMutablePointer<TmuxPaneWriteContext>.allocate(capacity: 1)
+            writeCtx.initialize(to: TmuxPaneWriteContext(hostSurface: hostSurface, paneId: paneInfo.pane_id))
+            config.io_write_cb = { (userdata: UnsafeMutableRawPointer?, data: UnsafePointer<UInt8>?, len: Int) in
+                guard let userdata = userdata, let data = data, len > 0 else { return }
+                let ctx = userdata.assumingMemoryBound(to: TmuxPaneWriteContext.self).pointee
+                // Classify: printable UTF-8 → literal, control/escape → key name
+                let bytes = UnsafeBufferPointer(start: data, count: len)
+                let first = bytes[0]
+
+                #if DEBUG
+                let hexStr = bytes.map { String(format: "%02x", $0) }.joined(separator: " ")
+                dlog("tmux.input write_cb len=\(len) first=0x\(String(format: "%02x", first)) hex=[\(hexStr)]")
+                #endif
+
+                // Space via send-keys key name to avoid quoting issues
+                // in tmux control mode command parsing
+                if first == 0x20 && len == 1 {
+                    "Space".withCString { cstr in
+                        ghostty_surface_tmux_send_keys(
+                            ctx.hostSurface, ctx.paneId,
+                            UnsafePointer<UInt8>(OpaquePointer(cstr)),
+                            strlen(cstr), 1  // key_type=1 (key name)
+                        )
+                    }
+                    return
+                }
+                if first == 0x1B && len > 1 {
+                    // Escape sequence → map to tmux key name
+                    if let keyName = GhosttyNSView.tmuxMapEscapeSequence(bytes) {
+                        keyName.withCString { cstr in
+                            ghostty_surface_tmux_send_keys(
+                                ctx.hostSurface, ctx.paneId,
+                                UnsafePointer<UInt8>(OpaquePointer(cstr)),
+                                strlen(cstr), 1  // key_type=1 (key name)
+                            )
+                        }
+                    }
+                } else if first < 0x20 || first == 0x7F {
+                    // Control character → map to tmux key name
+                    if let keyName = GhosttyNSView.tmuxMapControlChar(first) {
+                        keyName.withCString { cstr in
+                            ghostty_surface_tmux_send_keys(
+                                ctx.hostSurface, ctx.paneId,
+                                UnsafePointer<UInt8>(OpaquePointer(cstr)),
+                                strlen(cstr), 1
+                            )
+                        }
+                    }
+                } else {
+                    // Printable text → literal
+                    ghostty_surface_tmux_send_keys(
+                        ctx.hostSurface, ctx.paneId,
+                        data, len, 0  // key_type=0 (literal)
+                    )
+                }
+            }
+            config.io_write_userdata = UnsafeMutableRawPointer(writeCtx)
+
+            guard let paneSurface = ghostty_surface_new(app, &config) else {
+                #if DEBUG
+                dlog("tmux.pane create FAILED pane=\(paneInfo.pane_id)")
+                #endif
+                writeCtx.deinitialize(count: 1)
+                writeCtx.deallocate()
+                paneView.removeFromSuperview()
+                continue
+            }
+
+            // Register with host for %output routing + initial sync
+            ghostty_surface_tmux_register_pane(hostSurface, paneInfo.pane_id, regId, paneSurface)
+
+            tmuxPaneSurfaces[paneInfo.pane_id] = TmuxPaneState(
+                surface: paneSurface,
+                view: paneView,
+                regId: regId,
+                writeContext: writeCtx
+            )
+
+            // Complete surface initialization (same as normal surface flow):
+            // set display ID, content scale, and pixel size so renderer starts.
+            if let screen = window?.screen,
+               let displayID = screen.displayID,
+               displayID != 0 {
+                ghostty_surface_set_display_id(paneSurface, displayID)
+            }
+            let scaleFactor = window?.backingScaleFactor ?? 2.0
+            ghostty_surface_set_content_scale(paneSurface, scaleFactor, scaleFactor)
+            let backingSize = paneView.convertToBacking(NSRect(origin: .zero, size: paneView.bounds.size)).size
+            let wpx = UInt32(max(backingSize.width, 1))
+            let hpx = UInt32(max(backingSize.height, 1))
+            ghostty_surface_set_size(paneSurface, wpx, hpx)
+
+            // Focus the pane surface so it starts accepting input
+            ghostty_surface_set_focus(paneSurface, true)
+
+            #if DEBUG
+            dlog("tmux.pane create pane=\(paneInfo.pane_id) regId=\(regId) viewFrame=\(paneView.frame) wpx=\(wpx) hpx=\(hpx) scale=\(scaleFactor)")
+            #endif
+
+            // Initial sync: capture tmux pane content and replay.
+            // On re-attach, tmux may still be on the default 80x24 geometry,
+            // so we wait briefly for pane_height to converge before replaying.
+            tmuxInitialSync(paneId: paneInfo.pane_id, regId: regId)
+        }
+
+        // Update layout for existing panes
+        for i in 0..<Int(written) {
+            let paneInfo = panes[i]
+            if let state = tmuxPaneSurfaces[paneInfo.pane_id], !toAdd.contains(paneInfo.pane_id) {
+                state.view.frame = tmuxPaneFrame(paneInfo)
+            }
+        }
+
+    }
+
+    /// Convert tmux pane cell coordinates to NSView frame.
+    /// Uses the container bounds to scale: each cell maps to
+    /// (container_width / window_cols) × (container_height / window_rows).
+    private func tmuxPaneFrame(_ pane: ghostty_tmux_pane_info_s) -> NSRect {
+        guard let container = tmuxPaneContainer else { return .zero }
+        let containerBounds = container.bounds
+
+        // For a single-pane window, the pane IS the window — fill container.
+        // For multi-pane, we need the window dimensions to compute cell size.
+        // tmux pane x/y/width/height are in cells. The pane at (0,0) with
+        // full window width/height should fill the entire container.
+        // We use the host surface's cell size for pixel mapping.
+        let cw = max(cellSize.width, 1)
+        let ch = max(cellSize.height, 1)
+
+        let x = CGFloat(pane.x) * cw
+        let y = CGFloat(pane.y) * ch
+        let w = CGFloat(pane.width) * cw
+        let h = CGFloat(pane.height) * ch
+
+        // Reserve space for the status bar at the bottom (AppKit y=0).
+        // tmuxStatusBar points to the left label inside the barView.
+        let barHeight = tmuxStatusBar?.superview?.frame.height ?? 0
+        let availH = containerBounds.height - barHeight
+
+        // Clamp to available area (above status bar)
+        return NSRect(
+            x: min(x, containerBounds.width),
+            y: min(y + barHeight, containerBounds.height),
+            width: min(w, containerBounds.width - min(x, containerBounds.width)),
+            height: min(h, availH - min(y, availH))
+        )
+    }
+
+    private func tmuxDesiredClientSize() -> (cols: Int, rows: Int)? {
+        let cw = max(cellSize.width, 1)
+        let ch = max(cellSize.height, 1)
+        let containerH = tmuxPaneContainer?.bounds.height ?? bounds.height
+        let containerW = tmuxPaneContainer?.bounds.width ?? bounds.width
+        let barH = tmuxStatusBar?.superview?.frame.height ?? 0
+        let cols = Int(containerW / cw)
+        let rows = Int((containerH - barH) / ch)
+        guard cols > 0, rows > 0 else { return nil }
+        return (cols, rows)
+    }
+
+    private func tmuxCurrentClientSize(_ panes: ArraySlice<ghostty_tmux_pane_info_s>) -> (cols: Int, rows: Int)? {
+        guard !panes.isEmpty else { return nil }
+        var cols = 0
+        var rows = 0
+        for pane in panes {
+            cols = max(cols, Int(pane.x + pane.width))
+            rows = max(rows, Int(pane.y + pane.height))
+        }
+        guard cols > 0, rows > 0 else { return nil }
+        return (cols, rows)
+    }
+
+    /// Handle ack from I/O thread that a pane surface is unregistered.
+    /// Now safe to destroy the surface.
+    func handleTmuxPaneUnregistered(paneId: UInt, regId: UInt32) {
+        #if DEBUG
+        dlog("tmux.pane unregistered ack pane=\(paneId) regId=\(regId)")
+        #endif
+
+        // Verify this ack matches our pending unregister
+        if let pendingRegId = tmuxPendingUnregister[paneId], pendingRegId == regId {
+            tmuxPendingUnregister.removeValue(forKey: paneId)
+        }
+
+        // If the pane is still in our surfaces map with a DIFFERENT regId,
+        // it's been re-registered — don't destroy.
+        if let current = tmuxPaneSurfaces[paneId], current.regId == regId {
+            current.view.removeFromSuperview()
+            ghostty_surface_free(current.surface)
+            current.writeContext.deinitialize(count: 1)
+            current.writeContext.deallocate()
+            tmuxPaneSurfaces.removeValue(forKey: paneId)
+        }
+    }
+
+    /// Clean up all tmux pane surfaces (called on tmux exit).
+    func tmuxCleanupAllPanes() {
+        guard let hostSurface = terminalSurface?.surface else { return }
+        for (paneId, state) in tmuxPaneSurfaces {
+            ghostty_surface_tmux_unregister_pane(hostSurface, paneId, state.regId)
+            state.view.removeFromSuperview()
+            ghostty_surface_free(state.surface)
+            state.writeContext.deinitialize(count: 1)
+            state.writeContext.deallocate()
+        }
+        tmuxPaneSurfaces.removeAll()
+        tmuxPendingUnregister.removeAll()
+        tmuxStatusBarTimer?.invalidate()
+        tmuxStatusBarTimer = nil
+        tmuxStatusBar?.superview?.removeFromSuperview()  // remove barView
+        tmuxStatusBar = nil
+        // Restore host terminal rendering
+        self.alphaValue = 1
+        tmuxPaneContainer?.removeFromSuperview()
+        tmuxPaneContainer = nil
+        tmuxRequestedClientSize = nil
+    }
+
+    /// Query tmux for session/window info and update the status bar.
+    /// Uses tmux's actual status-left and status-right format strings,
+    /// targeting the specific pane so we get the correct session context.
+    private func tmuxUpdateStatusBar(barView: NSView, paneId: UInt) {
+        DispatchQueue.global(qos: .userInitiated).async { [weak barView] in
+            let target = "%\(paneId)"
+            // Use tmux's own status format evaluation
+            let leftText = Self.tmuxQuery(
+                "display-message", "-t", target, "-p",
+                "#{T:status-left}#{W:#{E:window-status-current-format} ,#{E:window-status-format} }"
+            )
+            let rightText = Self.tmuxQuery(
+                "display-message", "-t", target, "-p", "#{T:status-right}"
+            )
+
+            DispatchQueue.main.async {
+                guard let barView = barView else { return }
+                if let left = barView.viewWithTag(1) as? NSTextField {
+                    left.stringValue = leftText.isEmpty ? "" : leftText
+                }
+                if let right = barView.viewWithTag(2) as? NSTextField {
+                    right.stringValue = rightText.isEmpty ? "" : rightText
+                }
+            }
+        }
+    }
+
+    /// Run a tmux command and return trimmed stdout.
+    private func tmuxStartStatusBarTimer(barView: NSView, paneId: UInt) {
+        tmuxStatusBarTimer?.invalidate()
+        tmuxStatusBarTimer = Timer.scheduledTimer(withTimeInterval: 15, repeats: true) { [weak self, weak barView] _ in
+            guard let barView = barView else {
+                self?.tmuxStatusBarTimer?.invalidate()
+                return
+            }
+            self?.tmuxUpdateStatusBar(barView: barView, paneId: paneId)
+        }
+    }
+
+    private static func tmuxQuery(_ args: String...) -> String {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+        process.arguments = ["tmux"] + args
+        let pipe = Pipe()
+        process.standardOutput = pipe
+        process.standardError = FileHandle.nullDevice
+        do {
+            try process.run()
+            process.waitUntilExit()
+            let data = pipe.fileHandleForReading.readDataToEndOfFile()
+            return String(data: data, encoding: .utf8)?
+                .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        } catch {
+            return ""
+        }
+    }
+
+    // MARK: - Tmux Prefix Layer Methods
+
+    /// Reset prefix state (called on tmux exit).
+    func tmuxResetPrefixState() {
+        tmuxPrefixState = .idle
+        tmuxPrefixConfig = TmuxPrefixConfig()
+        tmuxActivePaneId = nil
+    }
+
+    /// Capture the tmux pane's visible content and feed it to the pane surface.
+    /// Uses `tmux capture-pane -p -e` to get ANSI-escaped content. On re-attach
+    /// tmux may briefly report the default 80x24 geometry, so we retry until
+    /// pane_height matches the pane surface rows (or fall back after a few tries).
+    private func tmuxInitialSync(paneId: UInt, regId: UInt32, attempt: Int = 0) {
+        let maxAttempts = 12
+        let retryDelay: TimeInterval = 0.05
+        DispatchQueue.global(qos: .userInitiated).async { [weak self] in
+            let paneInfo = Self.tmuxQueryArray([
+                "display-message", "-t", "%\(paneId)", "-p", "#{pane_height};#{cursor_y};#{cursor_x}"
+            ])
+            let output = Self.tmuxQueryRaw(["capture-pane", "-p", "-e", "-t", "%\(paneId)"])
+
+            DispatchQueue.main.async {
+                guard let self = self,
+                      let state = self.tmuxPaneSurfaces[paneId],
+                      state.regId == regId else { return }
+
+                let surfaceRows = max(Int(ghostty_surface_size(state.surface).rows), 1)
+
+                let paneParts = paneInfo.components(separatedBy: ";")
+                let tmuxRows = paneParts.count >= 1 ? Int(paneParts[0]) : nil
+                let rawCursorRow = paneParts.count >= 2 ? Int(paneParts[1]) : nil
+                let rawCursorCol = paneParts.count >= 3 ? Int(paneParts[2]) : nil
+
+                if attempt < maxAttempts {
+                    if tmuxRows != surfaceRows || output.isEmpty {
+                        if let desired = self.tmuxDesiredClientSize() {
+                            self.tmuxRequestedClientSize = desired
+                            self.tmuxSendCommand("refresh-client -C \(desired.cols)x\(desired.rows)")
+                        }
+                        DispatchQueue.main.asyncAfter(deadline: .now() + retryDelay) { [weak self] in
+                            self?.tmuxInitialSync(paneId: paneId, regId: regId, attempt: attempt + 1)
+                        }
+                        return
+                    }
+                } else if output.isEmpty {
+                    return
+                }
+
+                var captureLines = output.components(separatedBy: "\n")
+                if captureLines.last == "" {
+                    captureLines.removeLast()
+                }
+
+                var adjustedCursorRow = rawCursorRow ?? 0
+                let adjustedCursorCol = rawCursorCol ?? 0
+
+                if captureLines.count > surfaceRows {
+                    // More lines than surface can display: keep bottom rows
+                    let overflow = captureLines.count - surfaceRows
+                    captureLines = Array(captureLines.suffix(surfaceRows))
+                    adjustedCursorRow -= overflow
+                } else if captureLines.count < surfaceRows {
+                    // Fewer lines: use cursor position to calculate minimal
+                    // top padding so content aligns with where tmux has the
+                    // cursor, instead of blindly padding to fill the screen.
+                    let neededTopPad = max(0, adjustedCursorRow - (captureLines.count - 1))
+                    if neededTopPad > 0 {
+                        captureLines = Array(repeating: "", count: neededTopPad) + captureLines
+                        adjustedCursorRow = adjustedCursorRow  // unchanged — pad pushes content down to match
+                    }
+                }
+
+                adjustedCursorRow = max(0, min(adjustedCursorRow, max(captureLines.count - 1, 0)))
+
+                var fullOutput = "\u{1B}[H"
+                for (i, line) in captureLines.enumerated() {
+                    if i > 0 { fullOutput += "\r\n" }
+                    fullOutput += line
+                }
+                fullOutput += "\u{1B}[\(adjustedCursorRow + 1);\(adjustedCursorCol + 1)H"
+
+                guard let bytes = fullOutput.data(using: .utf8) else { return }
+                bytes.withUnsafeBytes { rawBuf in
+                    let ptr = rawBuf.baseAddress!.assumingMemoryBound(to: UInt8.self)
+                    ghostty_surface_process_output(state.surface, ptr, bytes.count)
+                }
+            }
+        }
+    }
+
+    /// Run a tmux command and return raw stdout bytes (no trimming).
+    private static func tmuxQueryRaw(_ args: [String]) -> String {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+        process.arguments = ["tmux"] + args
+        let pipe = Pipe()
+        process.standardOutput = pipe
+        process.standardError = FileHandle.nullDevice
+        do {
+            try process.run()
+            process.waitUntilExit()
+            let data = pipe.fileHandleForReading.readDataToEndOfFile()
+            return String(data: data, encoding: .utf8) ?? ""
+        } catch {
+            return ""
+        }
+    }
+
+    /// Send a raw tmux command through the control mode channel.
+    private func tmuxSendCommand(_ command: String) {
+        guard let hostSurface = terminalSurface?.surface else { return }
+        command.withCString { cstr in
+            ghostty_surface_tmux_command(hostSurface, UnsafePointer<UInt8>(OpaquePointer(cstr)), strlen(cstr))
+        }
+    }
+
+    /// Normalize an NSEvent into a tmux key name (e.g. "C-b", "d", "Left", "Enter").
+    /// Returns nil if the event can't be mapped to a tmux key.
+    private func tmuxKeyName(for event: NSEvent) -> String? {
+        let flags = event.modifierFlags.intersection(.deviceIndependentFlagsMask)
+        let hasCtrl = flags.contains(.control)
+        let hasMeta = flags.contains(.option)  // tmux calls Option "Meta"
+        let hasShift = flags.contains(.shift)
+
+        // Special keys by keyCode
+        let specialKey: String? = switch event.keyCode {
+        case 126: "Up"
+        case 125: "Down"
+        case 123: "Left"
+        case 124: "Right"
+        case 115: "Home"
+        case 119: "End"
+        case 116: "PPage"     // tmux uses PPage/NPage in list-keys -T prefix
+        case 121: "NPage"
+        case 117: "DC"        // Forward Delete
+        case 122: "F1"
+        case 120: "F2"
+        case 99:  "F3"
+        case 118: "F4"
+        case 96:  "F5"
+        case 97:  "F6"
+        case 98:  "F7"
+        case 100: "F8"
+        case 101: "F9"
+        case 109: "F10"
+        case 103: "F11"
+        case 111: "F12"
+        case 36:  "Enter"
+        case 48:  "Tab"
+        case 53:  "Escape"
+        case 49:  "Space"
+        case 51:  "BSpace"    // Backspace
+        default:  nil
+        }
+
+        var name: String
+        if let specialKey {
+            name = specialKey
+        } else if hasCtrl, let chars = event.charactersIgnoringModifiers?.lowercased(),
+                  let ch = chars.first, ch.isASCII, let av = ch.asciiValue, av >= 0x61, av <= 0x7A {
+            // Ctrl+letter: tmux uses "C-<letter>"
+            return "C-\(ch)"
+        } else if let chars = event.characters, !chars.isEmpty {
+            // Use .characters (not .charactersIgnoringModifiers) to get the
+            // actual typed character. This means Shift+5 → "%" not "S-5",
+            // matching how tmux names keys in list-keys output.
+            let ch = chars.first!
+            if ch == " " { name = "Space" }
+            else { name = String(ch) }
+        } else {
+            return nil
+        }
+
+        // For special keys (arrows, F-keys, etc.), add modifier prefixes.
+        // For printable characters, the character itself already encodes
+        // the shift state (e.g. "%" instead of "S-5"), so only add C-/M-.
+        var prefix = ""
+        if hasCtrl { prefix += "C-" }
+        if let _ = specialKey, hasShift { prefix += "S-" }
+        if hasMeta { prefix += "M-" }
+
+        if prefix.isEmpty {
+            return name
+        }
+        return "\(prefix)\(name)"
+    }
+
+    /// Load prefix configuration from tmux: prefix keys and key bindings.
+    /// Called asynchronously after entering tmux control mode.
+    func tmuxLoadPrefixConfig() {
+        guard let hostSurface = terminalSurface?.surface else { return }
+        // Capture pane ID for target
+        let paneId: UInt? = tmuxPaneSurfaces.values.first?.writeContext.pointee.paneId
+        DispatchQueue.global(qos: .userInitiated).async { [weak self] in
+            var config = TmuxPrefixConfig()
+
+            // Load prefix keys
+            let targetArgs: [String] = paneId.map { ["-t", "%\($0)"] } ?? []
+            let prefix1 = Self.tmuxQueryArray(["show", "-gv", "prefix"] + targetArgs)
+            let prefix2 = Self.tmuxQueryArray(["show", "-gv", "prefix2"] + targetArgs)
+            if !prefix1.isEmpty { config.prefixKeys.insert(prefix1) }
+            if !prefix2.isEmpty { config.prefixKeys.insert(prefix2) }
+
+            // Load bindings from prefix key table
+            let listKeysOutput = Self.tmuxQueryArray(["list-keys", "-T", "prefix"] + targetArgs)
+            // Parse lines like: bind-key    -T prefix d detach-client
+            // tmux escapes some key tokens with backslash: \%, \", \#, \$
+            for line in listKeysOutput.components(separatedBy: "\n") {
+                let parts = line.trimmingCharacters(in: .whitespaces)
+                    .components(separatedBy: .whitespaces)
+                    .filter { !$0.isEmpty }
+                // Format: bind-key [-r] -T prefix <key> <command...>
+                guard parts.count >= 5,
+                      parts[0] == "bind-key" else { continue }
+                // Find the key and command after "-T prefix"
+                if let tIdx = parts.firstIndex(of: "-T"),
+                   tIdx + 2 < parts.count,
+                   parts[tIdx + 1] == "prefix" {
+                    let keyIdx = tIdx + 2
+                    // Unescape tmux key token: \% → %, \" → ", etc.
+                    var key = parts[keyIdx]
+                    if key.hasPrefix("\\") && key.count == 2 {
+                        key = String(key.dropFirst())
+                    }
+                    let command = parts[(keyIdx + 1)...].joined(separator: " ")
+                    if !command.isEmpty {
+                        config.bindings[key] = command
+                    }
+                }
+            }
+
+            config.loaded = true
+
+            #if DEBUG
+            dlog("tmux.prefix loaded: keys=\(config.prefixKeys) bindings=\(config.bindings.count) entries")
+            #endif
+
+            DispatchQueue.main.async {
+                self?.tmuxPrefixConfig = config
+            }
+        }
+    }
+
+    /// Helper: run tmux command and return full stdout.
+    private static func tmuxQueryArray(_ args: [String]) -> String {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+        process.arguments = ["tmux"] + args
+        let pipe = Pipe()
+        process.standardOutput = pipe
+        process.standardError = FileHandle.nullDevice
+        do {
+            try process.run()
+            process.waitUntilExit()
+            let data = pipe.fileHandleForReading.readDataToEndOfFile()
+            return String(data: data, encoding: .utf8)?
+                .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        } catch {
+            return ""
+        }
+    }
+
+    /// Map escape sequences to tmux key names.
+    static func tmuxMapEscapeSequence(_ bytes: UnsafeBufferPointer<UInt8>) -> String? {
+        // Handle both CSI (ESC [) and SS3/application mode (ESC O) arrow keys
+        if bytes.count == 3 && (bytes[1] == 0x5B || bytes[1] == 0x4F) { // ESC[ or ESCO
+            switch bytes[2] {
+            case 0x41: return "Up"
+            case 0x42: return "Down"
+            case 0x43: return "Right"
+            case 0x44: return "Left"
+            case 0x48: return "Home"
+            case 0x46: return "End"
+            default: break
+            }
+        }
+        if bytes.count == 4 && bytes[1] == 0x5B { // ESC[x~
+            if bytes[3] == 0x7E { // ~
+                switch bytes[2] {
+                case 0x32: return "IC"     // Insert
+                case 0x33: return "DC"     // Delete
+                case 0x35: return "PPage"  // Page Up
+                case 0x36: return "NPage"  // Page Down
+                default: break
+                }
+            }
+        }
+        if bytes.count == 1 {
+            return "Escape"
+        }
+        // Unknown escape sequence — log and skip
+        #if DEBUG
+        let hex = bytes.map { String(format: "%02x", $0) }.joined(separator: " ")
+        dlog("tmux.input unmapped escape: \(hex)")
+        #endif
+        return nil
+    }
+
+    /// Map control characters to tmux key names.
+    static func tmuxMapControlChar(_ byte: UInt8) -> String? {
+        switch byte {
+        case 0x0D: return "Enter"
+        case 0x09: return "Tab"
+        case 0x1B: return "Escape"
+        case 0x7F: return "BSpace"
+        case 0x08: return "BSpace"
+        case 0x01: return "C-a"
+        case 0x02: return "C-b"
+        case 0x03: return "C-c"
+        case 0x04: return "C-d"
+        case 0x05: return "C-e"
+        case 0x06: return "C-f"
+        case 0x0B: return "C-k"
+        case 0x0C: return "C-l"
+        case 0x0E: return "C-n"
+        case 0x10: return "C-p"
+        case 0x12: return "C-r"
+        case 0x15: return "C-u"
+        case 0x17: return "C-w"
+        case 0x19: return "C-y"
+        case 0x1A: return "C-z"
+        default:
+            if byte < 0x20 {
+                // Generic C-x mapping
+                let ch = Character(UnicodeScalar(byte + 0x60))
+                return "C-\(ch)"
+            }
+            return nil
+        }
+    }
+
     override func mouseUp(with event: NSEvent) {
         #if DEBUG
         dlog("terminal.mouseUp surface=\(terminalSurface?.id.uuidString.prefix(5) ?? "nil") mods=[\(debugModifierString(event.modifierFlags))]")
         #endif
         guard let surface = surface else { return }
+        if let paneState = activeTmuxPane {
+            _ = ghostty_surface_mouse_button(paneState.surface, GHOSTTY_MOUSE_RELEASE, GHOSTTY_MOUSE_LEFT, modsFromEvent(event))
+            return
+        }
         _ = ghostty_surface_mouse_button(surface, GHOSTTY_MOUSE_RELEASE, GHOSTTY_MOUSE_LEFT, modsFromEvent(event))
     }
 
@@ -5541,6 +6777,13 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
     override func mouseMoved(with event: NSEvent) {
         maybeRequestFirstResponderForMouseFocus()
         guard let surface = surface else { return }
+        // Route to pane surface in tmux mode for link hover detection
+        if let paneState = activeTmuxPane {
+            let paneSurface = paneState.surface
+            let point = paneState.view.convert(event.locationInWindow, from: nil)
+            ghostty_surface_mouse_pos(paneSurface, point.x, paneState.view.bounds.height - point.y, modsFromEvent(event))
+            return
+        }
         let point = convert(event.locationInWindow, from: nil)
         ghostty_surface_mouse_pos(surface, point.x, bounds.height - point.y, modsFromEvent(event))
     }
@@ -5580,6 +6823,11 @@ class GhosttyNSView: NSView, NSUserInterfaceValidations {
 
     override func mouseDragged(with event: NSEvent) {
         guard let surface = surface else { return }
+        if let paneState = activeTmuxPane {
+            let point = paneState.view.convert(event.locationInWindow, from: nil)
+            ghostty_surface_mouse_pos(paneState.surface, point.x, paneState.view.bounds.height - point.y, modsFromEvent(event))
+            return
+        }
         let point = convert(event.locationInWindow, from: nil)
         ghostty_surface_mouse_pos(surface, point.x, bounds.height - point.y, modsFromEvent(event))
     }
@@ -8133,6 +9381,9 @@ extension GhosttyNSView: NSTextInputClient {
         default:
             break
         }
+        // selectedRange.location is the cursor position between characters.
+        // The renderer draws a bar cursor at the LEFT edge of this codepoint index.
+        markedTextCursorOffset = selectedRange.location
 
         // If we're not in a keyDown event, sync preedit immediately.
         // This can happen due to external events like changing keyboard layouts
@@ -8176,21 +9427,28 @@ extension GhosttyNSView: NSTextInputClient {
             )
         }
 #endif
-        guard let surface = surface else { return }
+        // Use inputSurface so IME preedit renders on the pane surface
+        // when in tmux control mode.
+        guard let target = inputSurface else { return }
 
         if markedText.length > 0 {
             let str = markedText.string
             let len = str.utf8CString.count
             if len > 0 {
                 str.withCString { ptr in
-                    // Subtract 1 for the null terminator
-                    ghostty_surface_preedit(surface, ptr, UInt(len - 1))
+                    // Subtract 1 for the null terminator.
+                    // Pass cursor offset so the renderer draws a double
+                    // underline at the IME cursor position.
+                    ghostty_surface_preedit_with_cursor(
+                        target, ptr, UInt(len - 1),
+                        UInt(markedTextCursorOffset)
+                    )
                 }
             }
         } else if clearIfNeeded {
             // If we had marked text before but don't now, we're no longer
             // in a preedit state so we can clear it.
-            ghostty_surface_preedit(surface, nil, 0)
+            ghostty_surface_preedit(target, nil, 0)
         }
     }
 
@@ -8230,8 +9488,8 @@ extension GhosttyNSView: NSTextInputClient {
             y = override.y
             w = override.width
             h = override.height
-        } else if let surface = surface {
-            ghostty_surface_ime_point(surface, &x, &y, &w, &h)
+        } else if let target = inputSurface {
+            ghostty_surface_ime_point(target, &x, &y, &w, &h)
         }
 #else
         if range.length > 0,
@@ -8239,8 +9497,8 @@ extension GhosttyNSView: NSTextInputClient {
            let snapshot = readSelectionSnapshot() {
             x = snapshot.topLeft.x - 2
             y = snapshot.topLeft.y + 2
-        } else if let surface = surface {
-            ghostty_surface_ime_point(surface, &x, &y, &w, &h)
+        } else if let target = inputSurface {
+            ghostty_surface_ime_point(target, &x, &y, &w, &h)
         }
 #endif
 
@@ -8250,13 +9508,21 @@ extension GhosttyNSView: NSTextInputClient {
         }
 
         // Ghostty coordinates are top-left origin; AppKit expects bottom-left.
+        // When in tmux mode, the coordinates are relative to the pane view,
+        // so we must convert through the pane view's coordinate space.
+        let sourceView: NSView
+        if let paneState = activeTmuxPane {
+            sourceView = paneState.view
+        } else {
+            sourceView = self
+        }
         let viewRect = NSRect(
             x: x,
-            y: frame.size.height - y,
+            y: sourceView.frame.size.height - y,
             width: w,
             height: max(h, cellSize.height)
         )
-        let winRect = convert(viewRect, to: nil)
+        let winRect = sourceView.convert(viewRect, to: nil)
         return window.convertToScreen(winRect)
     }
 
diff --git a/docs/phase2-review.md b/docs/phase2-review.md
new file mode 100644
index 000000000000..fbc1cf69b788
--- /dev/null
+++ b/docs/phase2-review.md
@@ -0,0 +1,270 @@
+# Phase 2 tmux Integration Review
+
+Date: 2026-03-18
+Reviewer: Codex
+
+Reviewed inputs:
+- `docs/tmux-integration-plan.md`
+- `.claude/plans/snoopy-moseying-tide.md`
+- `ghostty/src/termio/Termio.zig`
+- `ghostty/src/termio/Exec.zig`
+- `ghostty/src/termio/Manual.zig`
+- `ghostty/src/termio/message.zig`
+- `ghostty/src/termio/stream_handler.zig`
+- `ghostty/src/terminal/tmux/viewer.zig`
+
+## Executive Summary
+
+Phase 2's overall direction is good:
+- use Ghostty's existing tmux viewer as the protocol/state layer
+- surface tmux layout changes to Swift
+- give each tmux pane its own native Ghostty surface
+- route tmux `%output` into pane surfaces
+
+The biggest problems are not in the output path. They are:
+- input routing via `send-keys -H`
+- pane surface lifetime when the host I/O thread stores raw `*Termio`
+- missing initial sync contract
+
+My recommendation:
+- keep the overall architecture
+- do not implement `send-keys -H <hexblob>` as designed
+- add a real lifetime/teardown handshake for registered pane surfaces
+- define initial sync explicitly before coding Step 3/5
+
+## 1. processOutput Cross-Thread Safety
+
+## Verdict
+
+Lock-wise, this is mostly fine.
+
+`Termio.processOutput()` already takes `renderer_state.mutex` and is explicitly used from a separate read thread in exec mode. So the narrow question "can a non-main thread call `processOutput()`?" is answered by existing code: yes.
+
+Relevant code:
+- `Termio.processOutput()` locks `renderer_state.mutex` before touching terminal state.
+- `Exec` read thread already calls `Termio.processOutput()` directly.
+
+## What is actually risky
+
+The real risk is not the mutex. The real risk is lifetime.
+
+Your design stores raw `*Termio` pointers in `stream_handler.tmux_pane_surfaces`, then plans to:
+- register them via an async termio message
+- unregister them via another async termio message
+- destroy pane surfaces on tmux exit or layout change
+
+That leaves a use-after-free window:
+- main thread queues unregister
+- main thread destroys pane surface
+- host I/O thread has not processed unregister yet
+- tmux `%output` arrives
+- host I/O thread dereferences stale `*Termio`
+
+So the statement "single producer, single consumer = no race" is too optimistic. It avoids concurrent map mutation, but it does not solve pointer lifetime.
+
+## Recommendation
+
+Do one of these before implementing Step 3:
+
+1. Two-phase teardown
+- `unregister` is sent to host I/O thread
+- host I/O thread removes mapping
+- host I/O thread acks back
+- only after ack does Swift destroy pane surface
+
+2. Host-thread-owned registration tokens
+- do not store naked `*Termio`
+- store a registration record with explicit validity/liveness
+- destruction flips validity first, then frees after host thread confirms no more routing
+
+3. Retained object lifetime
+- if Ghostty/cmux already has a safe retain/release story for surfaces, use that
+- do not rely on raw pointer discipline alone
+
+## Bottom line
+
+`processOutput()` itself is thread-safe enough for this design.
+The architecture is not lifetime-safe yet.
+
+That is a blocking issue for Step 3/Step 6.
+
+## 2. send-keys -H Hex Encoding
+
+## Verdict
+
+As currently designed, this is not correct.
+
+The local tmux 3.6a man page says:
+- `send-keys -H` expects each key to be a hexadecimal number for an ASCII character
+- `send-keys -l` sends literal UTF-8 characters
+- `send-keys -K` sends to the target client so keys are looked up in the client's key table
+
+Your current design is:
+- Ghostty encodes terminal input to bytes
+- hex-encode the entire byte stream
+- send one command like `send-keys -t %pane -H <hex>`
+
+There are three problems with that:
+
+1. `-H` is not a "raw byte stream" API
+- it expects key arguments, not one concatenated blob
+- even if you split per byte, the man page frames it as ASCII characters
+
+2. Ghostty key encoding is terminal-byte-oriented, not tmux-key-oriented
+- tmux as a GUI client needs key semantics, not just post-encoding bytes
+- prefix handling, copy mode, tmux key tables, and tmux-native bindings all sit above "bytes written to a pane"
+
+3. It risks bypassing tmux's own key interpretation
+- you may get text insertion working
+- but special keys, prefix, tmux bindings, and mode-specific behavior will be wrong or incomplete
+
+## Recommendation
+
+Do not make `send-keys -H <hexblob>` the Phase 2 input path.
+
+Better options:
+
+1. Proper tmux key-event mapping
+- convert Ghostty input events into tmux key names where possible
+- use `send-keys` with key names / literals intentionally
+
+2. Split text input from special-key input
+- plain text: `send-keys -l`
+- special keys: named tmux keys
+- this is still imperfect, but much less wrong than `-H <hexblob>`
+
+3. If you want tmux-client semantics, investigate `-K`
+- this may be closer to what a real GUI client wants
+- but it changes the routing model and needs a deliberate design pass
+
+## Bottom line
+
+This is a blocking issue for Step 4.
+
+The current input design is not ready to implement as written.
+
+## 3. Initial Sync
+
+## Verdict
+
+This is currently under-specified, and that gap matters.
+
+Your plan correctly notes:
+- viewer already has a `Terminal` per tmux pane
+- pane surfaces will have their own `Terminal`
+- `%output` will keep them in sync after startup
+
+But there is no precise startup rule for how a newly created pane surface catches up with the current viewer state.
+
+If you skip this, new pane surfaces will start blank and only become correct after future `%output`.
+
+If you try to do this with plain text only, it will not be faithful enough.
+
+Plain text alone loses:
+- attributes/colors
+- cursor position
+- scrollback structure
+- modes
+- hyperlinks
+- any non-text terminal state
+
+## Recommendation
+
+You need one explicit bootstrap contract before Step 5:
+
+1. Preferred: clone/snapshot terminal state in Zig
+- host already has viewer pane `Terminal`
+- create a host-side API that copies or serializes enough of that state into the new pane surface
+- this is the cleanest architectural direction
+
+2. Acceptable MVP fallback: text-only bootstrap, but call it what it is
+- render current viewport text only
+- accept that fidelity is partial
+- do not describe this as a true initial sync
+
+3. Better than text scrape: host-side "apply current pane snapshot"
+- even if not a full deep clone, do it inside Zig against real terminal structures
+- avoid Swift reconstructing terminal state from strings
+
+## Bottom line
+
+Initial sync is a design gap, not a small implementation detail.
+
+I would not start Step 5 before choosing one of:
+- real terminal snapshot/clone
+- clearly degraded MVP bootstrap with known limitations
+
+## 4. Overall Architecture
+
+## Verdict
+
+The overall architecture is reasonable.
+
+What I like:
+- using viewer as protocol/state authority
+- surfacing `.windows` to Swift and querying pane topology
+- keeping pane rendering in real Ghostty surfaces
+- routing `%output` before/alongside `viewer.next()` so viewer and pane surface each maintain their own state
+
+The "double Terminal" tradeoff is also fine for MVP. It is not elegant, but it is understandable and cheap enough to start with.
+
+## What needs to change before implementation
+
+Three things:
+
+1. Fix input design
+- replace `send-keys -H <hexblob>`
+
+2. Add pane lifetime ownership protocol
+- unregister must be acknowledged before destruction
+- raw `*Termio` alone is not enough
+
+3. Define initial sync
+- decide whether this is true terminal-state bootstrap or limited viewport bootstrap
+
+## Non-blocking notes
+
+### `%output` routed to both viewer and pane surface
+
+This is okay.
+
+It is redundant, but intentional redundancy is fine here:
+- viewer stays protocol-authoritative
+- pane surface stays render/input-authoritative
+
+### `termio.Message` 40-byte limit
+
+This looks manageable.
+
+Current code has an explicit size guard test on `termio.Message == 40 bytes`.
+If `tmux_register_pane` is kept to a compact payload such as:
+- `pane_id`
+- pointer/handle
+
+then it should fit.
+
+Still, this is not something to assume. The existing size test should be updated and treated as the source of truth.
+
+## Final Recommendation
+
+Ready to proceed:
+- Step 1 (`.windows` action)
+- Step 2 (`tmux_panes()` query API)
+
+Do not proceed as currently written:
+- Step 4 (`send-keys -H <hexblob>`)
+
+Do not proceed without an explicit design update:
+- Step 3 / Step 6 lifetime handling
+- Step 5 initial sync semantics
+
+## Commit Readiness
+
+Phase 2 is not ready to implement exactly as currently written.
+
+It is ready for one more design pass with these concrete changes:
+- replace input routing design
+- add unregister/destroy handshake
+- define pane bootstrap strategy
+
+After that, the architecture is solid enough to build.
diff --git a/docs/phase2-step1-4-review.md b/docs/phase2-step1-4-review.md
new file mode 100644
index 000000000000..76c6f175960e
--- /dev/null
+++ b/docs/phase2-step1-4-review.md
@@ -0,0 +1,278 @@
+# Phase 2 Step 1-4 Review
+
+Date: 2026-03-18
+Reviewer: Codex
+
+Scope reviewed:
+- `ghostty/src/apprt/action.zig`
+- `ghostty/src/apprt/surface.zig`
+- `ghostty/src/Surface.zig`
+- `ghostty/src/termio/stream_handler.zig`
+- `ghostty/src/termio/message.zig`
+- `ghostty/src/termio/Thread.zig`
+- `ghostty/src/apprt/embedded.zig`
+- `ghostty.h`
+- `Sources/GhosttyTerminalView.swift`
+
+## Executive Summary
+
+Step 1-4 has a good core shape:
+- new tmux actions/messages are mostly clean
+- `.windows` wiring is in the right place
+- `%output` routing before `viewer.next()` is the right default
+- the `termio.Message` size guard is still in place
+
+The main problems are:
+- initial sync uses `dumpString` and then feeds plain text into `processOutput()`
+- unregister ack is keyed only by `pane_id`, but pane IDs can be reused
+- `send-keys` improved compared to the old `-H` idea, but the current literal/key-name split is still not robust enough for a real tmux GUI client
+
+## Findings
+
+### 1. High: initial sync via `dumpString` -> `processOutput()` is semantically wrong
+
+Current implementation:
+- `tmuxRegisterPane()` looks up the viewer pane terminal
+- calls `screen.dumpString(...)`
+- feeds the resulting plain text into `pane_termio.processOutput(dump)`
+
+Relevant code:
+- `stream_handler.zig` `tmuxRegisterPane()` initial sync path
+- `Screen.dumpString()` emits plain formatted screen text, not a replayable terminal state stream
+
+Why this is a problem:
+- `dumpString` is a rendered text dump
+- `processOutput()` expects terminal output bytes
+- feeding plain text back into a terminal does not reconstruct:
+  - attributes/colors
+  - cursor position
+  - modes
+  - hyperlinks
+  - scrollback structure
+  - alternate-screen state
+  - wrapped-line semantics beyond visible text
+
+So this is not just "lower fidelity". It is the wrong data model.
+
+What will happen in practice:
+- panes may look roughly right for simple shell prompts
+- but anything richer than plain text will drift immediately
+- initial cursor/mode state will be wrong
+
+Recommendation:
+- do not merge this initial sync as the long-term path
+- replace it with one of:
+  1. a true host-side terminal snapshot/clone into the pane surface
+  2. a clearly-degraded MVP bootstrap that is explicitly documented as text-only and temporary
+
+Blocking status:
+- blocking for the "native Ghostty surface per pane" goal
+
+### 2. High: unregister ack keyed only by `pane_id` is not safe
+
+Current implementation:
+- unregister removes `pane_id` from `tmux_pane_surfaces`
+- then sends `tmux_pane_unregistered(pane_id)` as the destroy ack
+
+Relevant code:
+- `stream_handler.zig` `tmuxUnregisterPane()`
+- `action.zig` / `surface.zig` / `Surface.zig` action/message plumbing
+
+Why this is a problem:
+- `pane_id` is not guaranteed to be a globally unique lifetime token
+- Ghostty's own tmux viewer tests explicitly mention reused pane IDs:
+  - "Uses same pane IDs 0,1 - they should be re-created since old panes were cleared"
+
+That means this race is possible:
+1. old pane `1` unregisters
+2. tmux session/layout changes
+3. new pane `1` appears and gets registered
+4. delayed ack for old pane `1` arrives
+5. Swift destroys the new pane `1` by mistake
+
+Recommendation:
+- ack must carry more than `pane_id`
+- use at least one of:
+  1. generation / registration token
+  2. surface identity
+  3. host-assigned opaque registration ID
+
+Blocking status:
+- blocking for two-phase teardown correctness
+
+### 3. Medium: `send-keys` split is better than `-H`, but still not robust enough
+
+Current implementation:
+- `key_type == 0` => `send-keys -l -t %pane "<text>"`
+- `key_type != 0` => `send-keys -t %pane <key_name>`
+
+What is better now:
+- this is better than the earlier `-H <hexblob>` design
+- it acknowledges tmux has separate notions of literal text vs key names
+
+What is still wrong or incomplete:
+
+#### Literal path
+
+The current quoting only escapes:
+- `"`
+- `\`
+
+That is not a general serialization for arbitrary user input.
+
+Examples that are still problematic:
+- embedded newline
+- carriage return
+- control bytes
+- strings that should not be routed as `-l` text at all
+
+If the pane surface ever sends anything beyond plain text, this path becomes fragile.
+
+#### Key-name path
+
+This path is only correct if the caller is already producing valid tmux key names.
+
+That means:
+- no terminal-encoded escape sequences here
+- no "already-encoded by Ghostty terminal" bytes
+- actual tmux key names only
+
+So the architecture still needs a real input-mapping layer.
+
+The remaining design question is:
+- where do we convert Ghostty input events into tmux key names vs literal text?
+
+Right now that layer is not defined in this patch.
+
+Recommendation:
+- keep the `literal vs key name` split
+- but do not treat this Step 4 implementation as finished
+- add an explicit mapping contract in Swift/Zig before wiring real input
+
+Blocking status:
+- medium for Step 4 itself
+- becomes high once real interactive typing is wired
+
+## Point-by-Point Review
+
+## 1. ABI: action / message / surface message additions
+
+Overall this looks okay.
+
+What looks good:
+- new action tags are append-only
+- `action.zig` still uses enum/header sync checks
+- `tmux_pane_unregistered` payload is a simple extern struct
+- `tmux_windows_changed` is void, so no extra union payload complexity
+- `termio.Message` still has an explicit `@sizeOf(Message) == 40` test
+
+No major ABI concern from Step 1 itself.
+
+The real issue is not ABI shape, it is the teardown token (`pane_id`) being too weak semantically.
+
+## 2. `%output` routing position
+
+This is in the right place.
+
+Current position:
+- intercept `%output`
+- route to registered pane surface
+- then pass the same notification into `viewer.next()`
+
+I agree with that ordering.
+
+Why it is right:
+- pane surface sees the raw pane output immediately
+- viewer still maintains its own protocol/state model
+- the duplication is intentional and understandable in this MVP
+
+I do not see a reason to move `%output` routing after `viewer.next()`.
+
+## 3. Initial sync (`dumpString`)
+
+This is the weakest part of the current implementation.
+
+`dumpString` is fine for:
+- debug output
+- text extraction
+- screen inspection
+
+It is not fine for:
+- reconstructing a live terminal surface
+
+So if this merges, it should be merged as a temporary bootstrap hack, not as the architecture we plan to keep.
+
+## 4. send-keys literal vs key name split
+
+Directionally correct, not complete.
+
+The split itself is good:
+- plain text and special keys should not be encoded the same way
+
+But the actual boundary is still missing:
+- who decides literal vs key name?
+- what input types are allowed on each path?
+- what happens to Enter, arrows, modifiers, paste, bracketed paste, IME commit text?
+
+That needs to be specified before Step 4 can be called done.
+
+## 5. Two-phase teardown ack flow
+
+The existence of an ack is good.
+
+That was the right architectural move.
+
+But the ack payload is not strong enough.
+
+Two-phase teardown should identify:
+- which registration is being removed
+- not just which pane ID happened to be involved
+
+So the flow is now structurally correct, but still logically unsafe.
+
+## Non-blocking Notes
+
+### `tmux_windows_changed` as a void action
+
+This is fine for now.
+
+Querying pane topology through `ghostty_surface_tmux_panes()` is a reasonable design.
+
+### `termio.Message` payload size
+
+This looks fine.
+
+`tmux_register_pane` is compact:
+- `usize pane_id`
+- `*Termio pane_termio`
+
+That should fit comfortably under the existing 40-byte union cap, and the size test remains present.
+
+### Swift debug handler
+
+No issue.
+
+The current `TMUX_WINDOWS_CHANGED` debug handler is minimal and appropriate for this step.
+
+## Final Recommendation
+
+Step 1 is basically fine.
+Step 2 is basically fine.
+Step 3 is not safe to ship until:
+- initial sync is redesigned
+- unregister ack is strengthened
+
+Step 4 is improved, but not complete:
+- keep the split
+- redesign the real input mapping before calling it done
+
+## Commit Readiness
+
+Not ready to commit as-is.
+
+I would block on:
+- initial sync using `dumpString` as replay input
+- `tmux_pane_unregistered(pane_id)` as the only teardown ack identity
+
+I would mark as follow-up but not immediate blocker:
+- input mapping contract behind `ghostty_surface_tmux_send_keys()`
diff --git a/docs/tmux-integration-plan.md b/docs/tmux-integration-plan.md
new file mode 100644
index 000000000000..47dcec74b724
--- /dev/null
+++ b/docs/tmux-integration-plan.md
@@ -0,0 +1,111 @@
+# cmux tmux Control Mode Integration Plan
+
+## Background
+
+cmux 在 tmux 下所有依賴「讀 Ghostty viewport 文字」的功能都失效：
+- cmd+click link detection
+- 左側 tree notification
+- CJK IME cursor 定位
+
+**根因**：tmux 用自己的 screen buffer 渲染到 host terminal。Ghostty 的 `render_state.string()` 在 tmux 下回傳幾乎全是 null bytes，看不到 pane 內容。
+
+## 關鍵發現
+
+Ghostty 已有完整的 tmux control mode 實作（build flag `tmux_control_mode`，預設開啟）：
+
+| 檔案 | 行數 | 功能 |
+|------|------|------|
+| `src/terminal/tmux/control.zig` | 725 | tmux control mode protocol parser |
+| `src/terminal/tmux/viewer.zig` | 2292 | tmux pane viewer + state machine |
+| `src/terminal/tmux/layout.zig` | 638 | layout parser |
+| `src/terminal/tmux/output.zig` | 590 | output handler |
+
+- 作者是 Mitchell Hashimoto（Ghostty 原作者），2025-12 寫的上游原生功能
+- 每個 tmux Pane 裡已有一個 `Terminal` 實例，維護完整的 terminal state
+- `Viewer.Action` 有三種：`exit`、`command`、`windows`
+
+## 缺失的接線
+
+`src/termio/stream_handler.zig` L427-449：
+
+```zig
+for (viewer.next(.{ .tmux = tmux })) |action| {
+    switch (action) {
+        .exit => { /* ignored, handled by DCS end */ },
+        .command => |cmd| { /* sends command to tmux */ },
+        .windows => { /* TODO */ },  // ← 這裡是空的
+    }
+}
+```
+
+- `exit` 和 `command` 已有 handler
+- `windows`（pane topology 變更）是 **TODO**
+- **沒有** tmux actions 暴露到 `ghostty.h` C API
+- cmux Swift 層完全看不到 tmux 狀態
+
+## Phase 1：最小 tmux bridge（read-only）
+
+**目標**：讓 cmux 拿到 tmux pane 的文字內容，證明 link detection 可以在結構化資料上運作。
+
+### Ghostty Zig 層
+
+1. 在 action system 新增 tmux events：
+   - `tmux_enter` / `tmux_exit`：lifecycle
+   - `tmux_windows_changed`：topology 變更，帶 window/pane list
+   - `tmux_pane_output`：某 pane 有新輸出（by pane_id）
+
+2. 在 `ghostty.h` 暴露：
+   - `ghostty_action_tmux_*` structs
+   - `ghostty_surface_tmux_pane_text(surface, pane_id, text*)` 查詢 API
+
+3. 在 `stream_handler.zig` 的 `.windows` TODO 裡 fire action
+
+### cmux Swift 層
+
+1. 接收 `GHOSTTY_ACTION_TMUX_*` events
+2. 在 debug log 裡證明：tmux pane 裡的檔案路徑可以被穩定讀出
+3. 用 pane text 做 link detection（取代 render state scraping）
+
+### 不做（留給 Phase 2）
+
+- pane-to-surface 映射
+- input routing
+- active pane focus sync
+- resize propagation
+- mouse forwarding
+
+### Demo 標準
+
+在 cmux 的 tmux session 裡：
+1. `echo /Users/timfeng/GitHub/genesis/GENESIS.md`
+2. cmd+click → 右側開 markdown panel
+
+## Phase 2：完整 tmux integration
+
+**目標**：cmux 成為 tmux 的 first-class GUI（like iTerm2 `tmux -CC`）。
+
+- 每個 tmux pane 對應一個 native Ghostty surface
+- 用戶輸入反向送回 tmux
+- Layout 雙向同步
+- 左側 tree 顯示 tmux sessions/windows/panes
+- Notification ring 對每個 pane 獨立運作
+
+### 參考
+
+- [iTerm2 tmux integration architecture](https://deepwiki.com/gnachman/iTerm2/5.2-tmux-integration)：TmuxGateway + TmuxController + TmuxWindowOpener，~4000-6000 行
+- [tmux Control Mode protocol](https://github.com/tmux/tmux/wiki/Control-Mode)
+- cmux issue [#560](https://github.com/manaflow-ai/cmux/issues/560)
+
+## 相關 Issues / PRs
+
+- PR [#1517](https://github.com/manaflow-ai/cmux/pull/1517)：cmd+click 開檔案（非 tmux 下可用）
+- Issue [#1521](https://github.com/manaflow-ai/cmux/issues/1521)：CJK IME cursor 不可見
+- Issue [#458](https://github.com/manaflow-ai/cmux/issues/458)：tmux 下 notification 不 work
+- Issue [#833](https://github.com/manaflow-ai/cmux/issues/833)：SSH+tmux notification
+
+## 檔案位置
+
+- Ghostty tmux module：`ghostty/src/terminal/tmux/`
+- Stream handler（接線點）：`ghostty/src/termio/stream_handler.zig` L385-450
+- Ghostty C API：`ghostty/include/ghostty.h`
+- cmux action handler：`Sources/GhosttyTerminalView.swift` L1922+
diff --git a/ghostty b/ghostty
index bc9be90a2199..cb310c774cc5 160000
--- a/ghostty
+++ b/ghostty
@@ -1 +1 @@
-Subproject commit bc9be90a21997a4e5f06bf15ae2ec0f937c2dc42
+Subproject commit cb310c774cc5e008f4f2b900bdffb58e30a6637a
diff --git a/ghostty.h b/ghostty.h
index 585564d7c7f5..ed4a1191dea9 100644
--- a/ghostty.h
+++ b/ghostty.h
@@ -437,6 +437,13 @@ typedef enum {
   GHOSTTY_SURFACE_CONTEXT_SPLIT = 2,
 } ghostty_surface_context_e;
 
+typedef enum {
+  GHOSTTY_IO_MODE_EXEC = 0,
+  GHOSTTY_IO_MODE_MANUAL = 1,
+} ghostty_io_mode_e;
+
+typedef void (*ghostty_io_write_cb)(void* userdata, const uint8_t* data, size_t len);
+
 typedef struct {
   ghostty_platform_e platform_tag;
   ghostty_platform_u platform;
@@ -450,6 +457,9 @@ typedef struct {
   const char* initial_input;
   bool wait_after_command;
   ghostty_surface_context_e context;
+  ghostty_io_mode_e io_mode;
+  ghostty_io_write_cb io_write_cb;
+  void* io_write_userdata;
 } ghostty_surface_config_s;
 
 typedef struct {
@@ -621,6 +631,18 @@ typedef enum {
   GHOSTTY_READONLY_ON,
 } ghostty_action_readonly_e;
 
+// apprt.action.TmuxState
+typedef enum {
+  GHOSTTY_TMUX_STATE_ENTER,
+  GHOSTTY_TMUX_STATE_EXIT,
+} ghostty_action_tmux_state_e;
+
+// apprt.action.TmuxPaneUnregistered
+typedef struct {
+  uintptr_t pane_id;
+  uint32_t reg_id;
+} ghostty_action_tmux_pane_unregistered_s;
+
 // apprt.action.DesktopNotification.C
 typedef struct {
   const char* title;
@@ -910,6 +932,10 @@ typedef enum {
   GHOSTTY_ACTION_SEARCH_TOTAL,
   GHOSTTY_ACTION_SEARCH_SELECTED,
   GHOSTTY_ACTION_READONLY,
+  GHOSTTY_ACTION_COPY_TITLE_TO_CLIPBOARD,
+  GHOSTTY_ACTION_TMUX_STATE,
+  GHOSTTY_ACTION_TMUX_WINDOWS_CHANGED,
+  GHOSTTY_ACTION_TMUX_PANE_UNREGISTERED,
 } ghostty_action_tag_e;
 
 typedef union {
@@ -950,6 +976,8 @@ typedef union {
   ghostty_action_search_total_s search_total;
   ghostty_action_search_selected_s search_selected;
   ghostty_action_readonly_e readonly;
+  ghostty_action_tmux_state_e tmux_state;
+  ghostty_action_tmux_pane_unregistered_s tmux_pane_unregistered;
 } ghostty_action_u;
 
 typedef struct {
@@ -1085,6 +1113,7 @@ bool ghostty_surface_key_is_binding(ghostty_surface_t,
                                     ghostty_binding_flags_e*);
 void ghostty_surface_text(ghostty_surface_t, const char*, uintptr_t);
 void ghostty_surface_preedit(ghostty_surface_t, const char*, uintptr_t);
+void ghostty_surface_preedit_with_cursor(ghostty_surface_t, const char*, uintptr_t, uintptr_t);
 bool ghostty_surface_mouse_captured(ghostty_surface_t);
 bool ghostty_surface_mouse_button(ghostty_surface_t,
                                   ghostty_input_mouse_state_e,
@@ -1122,6 +1151,38 @@ bool ghostty_surface_read_text(ghostty_surface_t,
                                ghostty_text_s*);
 void ghostty_surface_free_text(ghostty_surface_t, ghostty_text_s*);
 
+// Pass as pane_id to ghostty_surface_tmux_pane_text to read the first
+// available pane (convenience when the active pane ID is not yet known).
+#define GHOSTTY_TMUX_PANE_ID_ANY ((uintptr_t)-1)
+bool ghostty_surface_tmux_pane_text(ghostty_surface_t, uintptr_t pane_id, ghostty_text_s*);
+
+// Tmux pane info: leaf pane position/size in cells, relative to window.
+typedef struct {
+  uintptr_t window_id;
+  uintptr_t pane_id;
+  uint32_t x, y, width, height;
+} ghostty_tmux_pane_info_s;
+
+// Query tmux pane topology. Returns number of panes. If out is NULL,
+// returns total count without writing. Otherwise writes up to max_count.
+size_t ghostty_surface_tmux_panes(ghostty_surface_t, ghostty_tmux_pane_info_s* out, size_t max_count);
+
+// Register/unregister pane surfaces for tmux %output routing.
+void ghostty_surface_tmux_register_pane(ghostty_surface_t host, uintptr_t pane_id, uint32_t reg_id, ghostty_surface_t pane_surface);
+void ghostty_surface_tmux_unregister_pane(ghostty_surface_t host, uintptr_t pane_id, uint32_t reg_id);
+
+// Send keys to a tmux pane. key_type: 0=literal text (-l), 1=key name.
+void ghostty_surface_tmux_send_keys(ghostty_surface_t host, uintptr_t pane_id,
+                                     const uint8_t* data, size_t len, int key_type);
+
+// Send a raw tmux command through the control mode channel.
+// The command string should NOT include a trailing newline.
+void ghostty_surface_tmux_command(ghostty_surface_t host,
+                                   const uint8_t* cmd, size_t len);
+
+// Feed raw terminal output to a surface (used for Manual I/O mode).
+void ghostty_surface_process_output(ghostty_surface_t, const uint8_t* data, size_t len);
+
 #ifdef __APPLE__
 void ghostty_surface_set_display_id(ghostty_surface_t, uint32_t);
 void* ghostty_surface_quicklook_font(ghostty_surface_t);
diff --git a/scripts/reload.sh b/scripts/reload.sh
index 12c57e81bf50..ebfbbeeab810 100755
--- a/scripts/reload.sh
+++ b/scripts/reload.sh
@@ -351,6 +351,9 @@ OPEN_CLEAN_ENV=(
   -u CMUX_DEBUG_LOG
   -u CMUX_BUNDLE_ID
   -u CMUX_SHELL_INTEGRATION
+  # Don't leak tmux env into cmux — the app's terminals are not inside tmux.
+  -u TMUX
+  -u TMUX_PANE
   -u GHOSTTY_BIN_DIR
   -u GHOSTTY_RESOURCES_DIR
   -u GHOSTTY_SHELL_FEATURES