MuxWindow Object

API reference for the MuxWindow object in WezTerm’s Lua configuration

Available since version 20220624-141144-bd1b7c5d.

A MuxWindow object represents a window that is managed by the WezTerm multiplexer. It contains tabs and provides methods to manage them and the window’s state.

MuxWindow objects represent the logical window in the multiplexer layer, as opposed to the GUI Window object which represents the physical GUI window.

How to Access

MuxWindow objects are commonly accessed through:

• The window:mux_window() method from a GUI Window
• The pane:window() method
• The tab:window() method
• The wezterm.mux module functions

local wezterm = require 'wezterm'

wezterm.on('update-status', function(window, pane)
  local mux_win = window:mux_window()
  if mux_win then
    local tabs = mux_win:tabs()
  end
end)

Identification

mux_window:window_id()

Returns the unique multiplexer window identifier.

Returns: number - The mux window ID

local id = mux_win:window_id()

GUI Window Access

mux_window:gui_window()

Returns the GUI Window object for this multiplexer window, if one exists.

This is an async method because the GUI window may not exist yet (e.g., in a headless multiplexer scenario).

Returns: Window | nil

wezterm.action_callback(function(window, pane)
  local mux_win = window:mux_window()
  if mux_win then
    -- This is async, so use in async context
    local gui_win = mux_win:gui_window()
  end
end)

Workspace Methods

mux_window:get_workspace()

Returns the name of the workspace this window belongs to.

Returns: string

local workspace = mux_win:get_workspace()
wezterm.log_info('Window workspace: ', workspace)

mux_window:set_workspace(name)

Moves this window to a different workspace.

name · string · required

The name of the workspace to switch to

mux_win:set_workspace('development')

Title Methods

mux_window:get_title()

Returns the title of the window.

Returns: string

local title = mux_win:get_title()

mux_window:set_title(title)

Sets the title of the window.

title · string · required

The new title for the window

mux_win:set_title('My Project Window')

Tab Management

mux_window:tabs()

Returns an array of all tabs in this window.

Returns: MuxTab[]

local tabs = mux_win:tabs()
wezterm.log_info('Window has ', #tabs, ' tabs')

for i, tab in ipairs(tabs) do
  wezterm.log_info('Tab ', i, ': ', tab:get_title())
end

mux_window:tabs_with_info()

Returns an array of tabs with additional information.

Returns: Array of tables, each containing:

index · number

The position of the tab within the window (0-based)

is_active · boolean

Whether this is the active tab

tab · MuxTab

The MuxTab object

local tabs_info = mux_win:tabs_with_info()

for _, info in ipairs(tabs_info) do
  local marker = info.is_active and '*' or ' '
  wezterm.log_info(
    marker,
    ' Tab ', info.index,
    ': ', info.tab:get_title()
  )
end

mux_window:active_tab()

Returns the currently active tab in this window.

Returns: MuxTab | nil

local tab = mux_win:active_tab()
if tab then
  tab:set_title('Active Tab')
end

mux_window:active_pane()

Returns the active pane in the active tab.

Returns: Pane | nil

local pane = mux_win:active_pane()
if pane then
  pane:send_text('echo hello\n')
end

mux_window:spawn_tab(args)

Spawns a new tab in this window.

args · table · required

Configuration table for the new tab

Arguments table fields:

Show Spawn tab configuration options

args · string[]

Command arguments to run in the new tab. If omitted, uses the default program.

cwd · string

Working directory for the new tab

set_environment_variables · table<string, string>

Environment variables to set

domain · string | table

Domain to spawn in (e.g., “CurrentPaneDomain”, “DefaultDomain”, or )

Returns: MuxTab - The newly created tab

-- Spawn with default program
local new_tab = mux_win:spawn_tab{}

-- Spawn with specific command
local htop_tab = mux_win:spawn_tab{
  args = {'htop'},
  cwd = '/tmp',
}

-- Spawn in a specific domain
local remote_tab = mux_win:spawn_tab{
  args = {'bash'},
  domain = {DomainName = 'my-ssh-domain'},
}

Example: Window Information Display

local wezterm = require 'wezterm'

wezterm.on('update-status', function(window, pane)
  local mux_win = window:mux_window()
  if not mux_win then return end
  
  local workspace = mux_win:get_workspace()
  local tabs = mux_win:tabs()
  
  local status = string.format(
    'WS:%s | Tabs:%d',
    workspace,
    #tabs
  )
  
  window:set_left_status(status)
end)

Example: Spawn Tab with Keybinding

local wezterm = require 'wezterm'

return {
  keys = {
    {
      key = 't',
      mods = 'CTRL|SHIFT',
      action = wezterm.action_callback(function(window, pane)
        local mux_win = window:mux_window()
        if mux_win then
          -- Get CWD from current pane
          local cwd_uri = pane:get_current_working_dir()
          local cwd = cwd_uri and cwd_uri.file_path or nil
          
          -- Spawn new tab in same directory
          local new_tab = mux_win:spawn_tab{
            cwd = cwd,
          }
          
          new_tab:set_title('New Tab')
        end
      end),
    },
  },
}

Example: Workspace Switcher

local wezterm = require 'wezterm'
local act = wezterm.action

return {
  keys = {
    {
      key = 'w',
      mods = 'CTRL|SHIFT',
      action = wezterm.action_callback(function(window, pane)
        local mux_win = window:mux_window()
        if not mux_win then return end
        
        local workspaces = {'default', 'development', 'testing', 'production'}
        local current_ws = mux_win:get_workspace()
        
        -- Find next workspace
        local current_idx = 1
        for i, ws in ipairs(workspaces) do
          if ws == current_ws then
            current_idx = i
            break
          end
        end
        
        local next_idx = (current_idx % #workspaces) + 1
        local next_ws = workspaces[next_idx]
        
        mux_win:set_workspace(next_ws)
        
        window:toast_notification(
          'Workspace',
          'Switched to: ' .. next_ws,
          nil,
          2000
        )
      end),
    },
  },
}

Example: Tab Manager

local wezterm = require 'wezterm'

wezterm.on('user-var-changed', function(window, pane, name, value)
  if name == 'LIST_TABS' then
    local mux_win = window:mux_window()
    if not mux_win then return end
    
    local tabs_info = mux_win:tabs_with_info()
    
    wezterm.log_info('=== Window Tabs ===')
    wezterm.log_info('Title: ', mux_win:get_title())
    wezterm.log_info('Workspace: ', mux_win:get_workspace())
    wezterm.log_info('Tab count: ', #tabs_info)
    wezterm.log_info('')
    
    for _, info in ipairs(tabs_info) do
      local marker = info.is_active and '→' or ' '
      local tab = info.tab
      local panes = tab:panes()
      
      wezterm.log_info(
        string.format(
          '%s [%d] %s (%d panes)',
          marker,
          info.index,
          tab:get_title(),
          #panes
        )
      )
    end
  end
end)

Relationship to GUI Window

The MuxWindow is the logical window in the multiplexer, while the GUI Window is the physical window you see on screen:

• MuxWindow: Exists in the multiplexer layer, can exist without a GUI (e.g., in wezterm cli contexts)
• GUI Window: The actual rendered window with GUI-specific methods like set_right_status(), get_appearance(), etc.

In most GUI scenarios, you’ll have both:

wezterm.on('update-status', function(window, pane)
  -- window is the GUI Window
  local mux_win = window:mux_window()  -- Get the MuxWindow
  
  -- GUI-specific operations
  window:set_right_status('Status')
  local appearance = window:get_appearance()
  
  -- Mux-specific operations
  local tabs = mux_win:tabs()
  local workspace = mux_win:get_workspace()
end)