Pane Object

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

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

Navigation Methods

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:

Show Split configuration options

direction · string · default: "Right"

Split direction: “Left”, “Right”, “Top”, or “Bottom”

size · number · default: "0.5"

Size of new pane. Values < 1.0 are percentages, >= 1.0 are cell counts.

top_level · boolean · default: "false"

If true, split the entire tab rather than just this pane

args · string[]

Command arguments to run in the new pane

cwd · string

Working directory for the new pane

set_environment_variables · table<string, string>

Environment variables to set

domain · string | table

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

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)