GUI Events

Events emitted during GUI application lifecycle

GUI events are emitted by WezTerm’s graphical user interface layer during application startup and attachment to domains. These events allow you to customize the initial state of your terminal environment.

gui-startup

Since: 20220624-141144-bd1b7c5d

Emitted once when the GUI server starts up (when running wezterm start).

Timing

• Fires before any default program is started
• Fires before gui-attached event
• Does NOT fire for wezterm connect invocations
• If this event creates panes, they take precedence over default program configuration

Event Signature

wezterm.on('gui-startup', function(cmd)
  -- cmd is an optional SpawnCommand object
  -- representing any arguments passed to `wezterm start`
end)

cmd · SpawnCommand | nil

Optional spawn command from wezterm start arguments. Added in version 20220807-113146-c2fee766.

Return Value

No return value expected. This is a fire-and-forget event.

Examples

Split Window into Thirds

local wezterm = require 'wezterm'
local mux = wezterm.mux
local config = {}

wezterm.on('gui-startup', function(cmd)
  local tab, pane, window = mux.spawn_window(cmd or {})
  -- Create a split occupying the right 1/3 of the screen
  pane:split { size = 0.3 }
  -- Create another split in the remaining 2/3
  pane:split { size = 0.5 }
end)

return config

Maximize on Startup

wezterm.on('gui-startup', function(cmd)
  local tab, pane, window = mux.spawn_window(cmd or {})
  window:gui_window():maximize()
end)

Multiple Workspaces

wezterm.on('gui-startup', function(cmd)
  local args = {}
  if cmd then
    args = cmd.args
  end

  -- Coding workspace
  local project_dir = wezterm.home_dir .. '/wezterm'
  local tab, build_pane, window = mux.spawn_window {
    workspace = 'coding',
    cwd = project_dir,
    args = args,
  }
  local editor_pane = build_pane:split {
    direction = 'Top',
    size = 0.6,
    cwd = project_dir,
  }
  build_pane:send_text 'cargo build\n'

  -- Automation workspace
  local tab, pane, window = mux.spawn_window {
    workspace = 'automation',
    args = { 'ssh', 'vault' },
  }

  -- Start in coding workspace
  mux.set_active_workspace 'coding'
end)

Use Cases

• Setting up development environments with specific layouts
• Creating workspace-based configurations
• Maximizing or positioning windows on startup
• Auto-starting specific commands or shells

gui-attached

Since: 20230320-124340-559cb7b0

Emitted when the GUI attaches to a domain after startup.

Timing

• Fires AFTER gui-startup event
• Fires when using wezterm connect DOMAIN or wezterm start --domain DOMAIN
• If no domain is specified, the default domain is passed
• gui-startup does NOT fire when using wezterm connect DOMAIN or wezterm start --domain DOMAIN --attach

Event Signature

wezterm.on('gui-attached', function(domain)
  -- domain is a MuxDomain object
end)

domain · MuxDomain

The multiplexer domain that was attached. Provides information about the domain type and configuration.

Return Value

No return value expected.

Examples

Maximize All Windows on Attach

local wezterm = require 'wezterm'
local mux = wezterm.mux

wezterm.on('gui-attached', function(domain)
  -- Maximize all displayed windows on startup
  local workspace = mux.get_active_workspace()
  for _, window in ipairs(mux.all_windows()) do
    if window:get_workspace() == workspace then
      window:gui_window():maximize()
    end
  end
end)

local config = wezterm.config_builder()
return config

Domain-Specific Setup

wezterm.on('gui-attached', function(domain)
  local domain_name = domain:name()
  
  if domain_name == 'SSH:production' then
    -- Set visual indicator for production
    for _, window in ipairs(mux.all_windows()) do
      local overrides = window:get_config_overrides() or {}
      overrides.color_scheme = 'Red Alert'
      window:set_config_overrides(overrides)
    end
  end
end)

Log Domain Information

wezterm.on('gui-attached', function(domain)
  wezterm.log_info('Attached to domain: ' .. domain:name())
  wezterm.log_info('Domain state: ' .. domain:state())
end)

Use Cases

• Maximizing windows when connecting to remote domains
• Setting domain-specific visual themes or configurations
• Logging connection information
• Adjusting workspace layouts based on domain type

Comparison: gui-startup vs gui-attached

gui-startup (Local Start)

-- Fires when running: wezterm start
wezterm.on('gui-startup', function(cmd)
  -- Setup initial layout
end)

-- Followed by gui-attached
wezterm.on('gui-attached', function(domain)
  -- Additional setup after domain attachment
end)

Common Patterns

Project-Specific Layouts

local projects = {
  web = {
    dir = wezterm.home_dir .. '/projects/web',
    splits = { 'npm run dev', 'git status' }
  },
  api = {
    dir = wezterm.home_dir .. '/projects/api',
    splits = { 'docker-compose up', 'npm test -- --watch' }
  }
}

wezterm.on('gui-startup', function(cmd)
  for name, project in pairs(projects) do
    local tab, pane, window = mux.spawn_window {
      workspace = name,
      cwd = project.dir,
    }
    
    for i, command in ipairs(project.splits) do
      if i > 1 then
        pane = pane:split { size = 0.5 }
      end
      pane:send_text(command .. '\n')
    end
  end
  
  mux.set_active_workspace 'web'
end)

Conditional Window Positioning

wezterm.on('gui-startup', function(cmd)
  local tab, pane, window = mux.spawn_window(cmd or {})
  local gui_window = window:gui_window()
  
  -- Get screen dimensions
  local screens = wezterm.gui.screens()
  local active_screen = screens.active
  
  if active_screen.width > 2560 then
    -- Ultra-wide monitor: position on right half
    gui_window:set_position(active_screen.width / 2, 0)
    gui_window:set_inner_size(active_screen.width / 2, active_screen.height)
  else
    -- Normal monitor: maximize
    gui_window:maximize()
  end
end)

Related Events

• mux-startup - Fires when multiplexer starts (before GUI events)
• window-config-reloaded - Fires when configuration is reloaded

See Also

• MuxWindow object - Multiplexer window API
• MuxTab object - Multiplexer tab API