> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# MuxWindow Object

> API reference for the MuxWindow object in WezTerm's Lua configuration

<Note>
  Available since version `20220624-141144-bd1b7c5d`.
</Note>

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](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

```lua theme={null}
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

```lua theme={null}
local id = mux_win:window_id()
```

## GUI Window Access

### mux\_window:gui\_window()

Returns the GUI [Window](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`

```lua theme={null}
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`

```lua theme={null}
local workspace = mux_win:get_workspace()
wezterm.log_info('Window workspace: ', workspace)
```

### mux\_window:set\_workspace(name)

Moves this window to a different workspace.

<ParamField path="name" type="string" required>
  The name of the workspace to switch to
</ParamField>

```lua theme={null}
mux_win:set_workspace('development')
```

## Title Methods

### mux\_window:get\_title()

Returns the title of the window.

**Returns:** `string`

```lua theme={null}
local title = mux_win:get_title()
```

### mux\_window:set\_title(title)

Sets the title of the window.

<ParamField path="title" type="string" required>
  The new title for the window
</ParamField>

```lua theme={null}
mux_win:set_title('My Project Window')
```

## Tab Management

### mux\_window:tabs()

Returns an array of all tabs in this window.

**Returns:** `MuxTab[]`

```lua theme={null}
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:

<ResponseField name="index" type="number">
  The position of the tab within the window (0-based)
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether this is the active tab
</ResponseField>

<ResponseField name="tab" type="MuxTab">
  The MuxTab object
</ResponseField>

```lua theme={null}
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`

```lua theme={null}
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`

```lua theme={null}
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.

<ParamField path="args" type="table" required>
  Configuration table for the new tab
</ParamField>

**Arguments table fields:**

<Expandable title="Spawn tab configuration options">
  <ResponseField name="args" type="string[]">
    Command arguments to run in the new tab. If omitted, uses the default program.
  </ResponseField>

  <ResponseField name="cwd" type="string">
    Working directory for the new tab
  </ResponseField>

  <ResponseField name="set_environment_variables" type="table<string, string>">
    Environment variables to set
  </ResponseField>

  <ResponseField name="domain" type="string | table">
    Domain to spawn in (e.g., "CurrentPaneDomain", "DefaultDomain", or {DomainName = "name"})
  </ResponseField>
</Expandable>

**Returns:** `MuxTab` - The newly created tab

```lua theme={null}
-- 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

```lua theme={null}
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

```lua theme={null}
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

```lua theme={null}
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

```lua theme={null}
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](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:

```lua theme={null}
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)
```