> ## 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.

# 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.

<Note>
  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.
</Note>

## 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

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

```lua theme={null}
local id = pane:pane_id()
```

## Navigation Methods

### pane:tab()

Returns the [MuxTab](mux-tab) object that contains this pane.

**Returns:** `MuxTab | nil`

```lua theme={null}
local tab = pane:tab()
if tab then
  tab:set_title('My Tab')
end
```

### pane:window()

Returns the [MuxWindow](mux-window) object that contains this pane.

**Returns:** `MuxWindow | nil`

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

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

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

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

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

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

<ParamField path="nlines" type="number" optional>
  Number of lines to retrieve. If omitted, returns all viewport lines.
</ParamField>

**Returns:** `string` - Text with trailing whitespace trimmed

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

<ParamField path="nlines" type="number" optional>
  Number of lines to retrieve. If omitted, returns all viewport lines.
</ParamField>

**Returns:** `string`

```lua theme={null}
local text_with_colors = pane:get_lines_as_escapes()
```

### pane:get\_logical\_lines\_as\_text(nlines?)

Returns logical lines (respecting line wrapping) as text.

<ParamField path="nlines" type="number" optional>
  Number of lines to retrieve. If omitted, returns all viewport lines.
</ParamField>

**Returns:** `string`

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

<ParamField path="start_x" type="number" required>
  Starting column (0-based)
</ParamField>

<ParamField path="start_y" type="number" required>
  Starting row (stable row index)
</ParamField>

<ParamField path="end_x" type="number" required>
  Ending column (0-based)
</ParamField>

<ParamField path="end_y" type="number" required>
  Ending row (stable row index)
</ParamField>

**Returns:** `string`

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

<ParamField path="type" type="SemanticType" optional>
  Filter by semantic type (e.g., "Output", "Input", "Prompt")
</ParamField>

**Returns:** `SemanticZone[]`

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

<ParamField path="x" type="number" required>
  Column position
</ParamField>

<ParamField path="y" type="number" required>
  Row position (stable row index)
</ParamField>

**Returns:** `SemanticZone | nil`

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

<ParamField path="zone" type="SemanticZone" required>
  The semantic zone object
</ParamField>

**Returns:** `string`

## Position and State Methods

### pane:get\_cursor\_position()

Returns the current cursor position.

**Returns:** `{x: number, y: number, shape: string, visibility: string}`

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

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

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

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

<ParamField path="text" type="string" required>
  Text to send to the pane
</ParamField>

```lua theme={null}
pane:send_text('echo hello\n')
```

### pane:send\_paste(text)

Sends text to the pane in bracketed paste mode.

<ParamField path="text" type="string" required>
  Text to paste
</ParamField>

```lua theme={null}
pane:send_paste('multi\nline\ntext')
```

### pane:paste(text)

Alias for `send_paste()`. Exists for backwards compatibility.

<ParamField path="text" type="string" required>
  Text to paste
</ParamField>

### pane:inject\_output(text)

Injects escape sequences directly into the terminal emulator.

<ParamField path="text" type="string" required>
  Text with ANSI escape sequences
</ParamField>

```lua theme={null}
pane:inject_output('\x1b[31mRed text\x1b[0m')
```

## Manipulation Methods

### pane:split(args?)

Splits the pane and spawns a program into the new pane.

<ParamField path="args" type="table" optional>
  Configuration table for the split operation
</ParamField>

**Arguments table fields:**

<Expandable title="Split configuration options">
  <ResponseField name="direction" type="string" default="Right">
    Split direction: "Left", "Right", "Top", or "Bottom"
  </ResponseField>

  <ResponseField name="size" type="number" default="0.5">
    Size of new pane. Values \< 1.0 are percentages, >= 1.0 are cell counts.
  </ResponseField>

  <ResponseField name="top_level" type="boolean" default="false">
    If true, split the entire tab rather than just this pane
  </ResponseField>

  <ResponseField name="args" type="string[]">
    Command arguments to run in the new pane
  </ResponseField>

  <ResponseField name="cwd" type="string">
    Working directory for the new pane
  </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:** `Pane` - The newly created pane

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

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

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

<ParamField path="workspace" type="string" optional>
  Name of the workspace for the new window
</ParamField>

**Returns:** `(MuxTab, MuxWindow)` - The new tab and window

```lua theme={null}
local tab, window = pane:move_to_new_window('my-workspace')
```

## Example: Status Line with Pane Info

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

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