Skip to main content
A Pane object represents a live instance of a pane in the WezTerm multiplexer. It tracks the pseudo terminal (or real serial terminal), associated processes, and the parsed screen and scrollback buffer. Pane objects are typically passed to your code via event callbacks. You can use a Pane object to send input to associated processes and introspect the terminal emulation state.
Since version 20221119-145034-49b9839f, there is only the underlying mux pane (previously there were separate MuxPane and Pane objects). These docs refer to it as Pane for simplicity.

​
How to Access

Pane objects are commonly accessed through:
  • Event callbacks (e.g., update-status, format-tab-title)
  • Window and Tab methods like window:active_pane() or tab:active_pane()
  • The wezterm.mux module methods
local wezterm = require 'wezterm'

wezterm.on('update-status', function(window, pane)
  -- pane is a Pane object
  local title = pane:get_title()
end)

​
Properties

​
pane:pane_id()

Returns the unique pane identifier. Returns: number - The pane ID 
local id = pane:pane_id()

​
pane:tab()

Returns the MuxTab object that contains this pane. Returns: MuxTab | nil 
local tab = pane:tab()
if tab then
  tab:set_title('My Tab')
end

​
pane:window()

Returns the MuxWindow object that contains this pane. Returns: MuxWindow | nil 
local window = pane:window()
if window then
  window:set_title('My Window')
end

​
pane:mux_pane()

Returns the pane itself. This method exists for backwards compatibility when there were separate GUI and Mux pane objects. Returns: Pane

​
Content Retrieval Methods

​
pane:get_title()

Returns the title of the pane. This is typically wezterm by default but can be modified by applications using OSC 1 (Icon/Tab title) and/or OSC 2 (Window title) escape sequences. Returns: string 
local title = pane:get_title()

​
pane:get_current_working_dir()

Returns the current working directory of the pane, if available. Returns: Url | nil - A URL object representing the working directory 
local cwd = pane:get_current_working_dir()
if cwd then
  local path = cwd.file_path
end

​
pane:get_foreground_process_name()

Returns the executable path of the foreground process. Returns: string | nil 
local process = pane:get_foreground_process_name()

​
pane:get_foreground_process_info()

Returns detailed information about the foreground process. Returns: LocalProcessInfo | nil

​
pane:get_user_vars()

Returns user variables that have been set in the pane environment. Returns: table<string, string> 
local vars = pane:get_user_vars()
local my_var = vars.MY_VARIABLE

​
pane:get_metadata()

Returns metadata associated with the pane. Returns: dynamic - Dynamic metadata value

​
pane:get_domain_name()

Returns the name of the domain this pane belongs to. Returns: string 
local domain = pane:get_domain_name()

​
pane:get_tty_name()

Returns the TTY device name associated with this pane. Returns: string | nil

​
Screen Content Methods

​
pane:get_lines_as_text(nlines?)

Returns lines from the viewport as plain text (no escape sequences).
​
nlines
number
Number of lines to retrieve. If omitted, returns all viewport lines.
Returns: string - Text with trailing whitespace trimmed 
-- Get all viewport lines
local text = pane:get_lines_as_text()

-- Get last 10 lines
local last_10 = pane:get_lines_as_text(10)

​
pane:get_lines_as_escapes(nlines?)

Returns lines with ANSI escape sequences preserved.
​
nlines
number
Number of lines to retrieve. If omitted, returns all viewport lines.
Returns: string 
local text_with_colors = pane:get_lines_as_escapes()

​
pane:get_logical_lines_as_text(nlines?)

Returns logical lines (respecting line wrapping) as text.
​
nlines
number
Number of lines to retrieve. If omitted, returns all viewport lines.
Returns: string 
local logical_text = pane:get_logical_lines_as_text()

​
pane:get_text_from_region(start_x, start_y, end_x, end_y)

Extracts text from a specific region of the terminal.
​
start_x
number
required
Starting column (0-based)
​
start_y
number
required
Starting row (stable row index)
​
end_x
number
required
Ending column (0-based)
​
end_y
number
required
Ending row (stable row index)
Returns: string 
local text = pane:get_text_from_region(0, 0, 10, 5)

​
Semantic Zone Methods

​
pane:get_semantic_zones(type?)

Returns semantic zones in the pane (prompts, commands, output regions).
​
type
SemanticType
Filter by semantic type (e.g., “Output”, “Input”, “Prompt”)
Returns: SemanticZone[] 
local zones = pane:get_semantic_zones()
for _, zone in ipairs(zones) do
  wezterm.log_info('Zone: ', zone)
end

​
pane:get_semantic_zone_at(x, y)

Returns the semantic zone at the specified coordinates.
​
x
number
required
Column position
​
y
number
required
Row position (stable row index)
Returns: SemanticZone | nil 
local zone = pane:get_semantic_zone_at(10, 5)
if zone then
  local text = pane:get_text_from_semantic_zone(zone)
end

​
pane:get_text_from_semantic_zone(zone)

Extracts text from a semantic zone.
​
zone
SemanticZone
required
The semantic zone object
Returns: string

​
Position and State Methods

​
pane:get_cursor_position()

Returns the current cursor position. Returns: {x: number, y: number, shape: string, visibility: string} 
local cursor = pane:get_cursor_position()
wezterm.log_info('Cursor at: ', cursor.x, cursor.y)

​
pane:get_dimensions()

Returns dimensional information about the pane. Returns: Table with fields:
  • cols - number of columns
  • rows - number of rows
  • viewport_rows - number of visible rows
  • physical_top - top of physical scrollback
  • scrollback_rows - number of scrollback rows
local dims = pane:get_dimensions()
wezterm.log_info('Pane size: ', dims.cols, 'x', dims.rows)

​
pane:get_progress()

Returns the progress indicator state, if any. Returns: number | nil - Progress value between 0 and 1

​
pane:has_unseen_output()

Returns whether the pane has received output since last being focused. Returns: boolean 
if pane:has_unseen_output() then
  -- Highlight tab or window
end

​
pane:is_alt_screen_active()

Returns whether the alternate screen buffer is active. Returns: boolean 
if pane:is_alt_screen_active() then
  -- Running a full-screen app like vim or less
end

​
Input Methods

​
pane:send_text(text)

Sends text directly to the pane as if typed.
​
text
string
required
Text to send to the pane
pane:send_text('echo hello\n')

​
pane:send_paste(text)

Sends text to the pane in bracketed paste mode.
​
text
string
required
Text to paste
pane:send_paste('multi\nline\ntext')

​
pane:paste(text)

Alias for send_paste(). Exists for backwards compatibility.
​
text
string
required
Text to paste

​
pane:inject_output(text)

Injects escape sequences directly into the terminal emulator.
​
text
string
required
Text with ANSI escape sequences
pane:inject_output('\x1b[31mRed text\x1b[0m')

​
Manipulation Methods

​
pane:split(args?)

Splits the pane and spawns a program into the new pane.
​
args
table
Configuration table for the split operation
Arguments table fields: Returns: Pane - The newly created pane 
-- Split right with default program
local new_pane = pane:split{}

-- Split vertically at top, running 'top'
local top_pane = pane:split{
  direction = 'Top',
  size = 0.3,
  args = {'top'}
}

​
pane:activate()

Activates this pane (makes it the focused pane in its tab and window). 
pane:activate()

​
pane:move_to_new_tab()

Moves this pane to a new tab in the same window. Returns: (MuxTab, MuxWindow) - The new tab and its containing window 
local new_tab, window = pane:move_to_new_tab()

​
pane:move_to_new_window(workspace?)

Moves this pane to a new window, optionally in a specific workspace.
​
workspace
string
Name of the workspace for the new window
Returns: (MuxTab, MuxWindow) - The new tab and window 
local tab, window = pane:move_to_new_window('my-workspace')

​
Example: Status Line with Pane Info

local wezterm = require 'wezterm'

wezterm.on('update-status', function(window, pane)
  local cwd = pane:get_current_working_dir()
  local process = pane:get_foreground_process_name()
  
  local status = 'CWD: ' .. (cwd and cwd.file_path or 'unknown')
  if process then
    status = status .. ' | Process: ' .. process
  end
  
  if pane:has_unseen_output() then
    status = status .. ' [NEW OUTPUT]'
  end
  
  window:set_right_status(status)
end)

​
Example: Working with Semantic Zones

local wezterm = require 'wezterm'

wezterm.on('user-var-changed', function(window, pane, name, value)
  if name == 'GET_LAST_OUTPUT' then
    local zones = pane:get_semantic_zones('Output')
    if #zones > 0 then
      local last_output = pane:get_text_from_semantic_zone(zones[#zones])
      wezterm.log_info('Last output: ', last_output)
    end
  end
end)