0
# Pane Management
1

2
Pane management in libtmux provides direct interaction with individual terminal instances within tmux windows. Panes represent the actual shell processes where commands are executed and output is captured.
3

4
## Capabilities
5

6
### Pane Initialization and Context
7

8
Create and manage pane instances with proper resource management and context support.
9

10
```python { .api }
11
@dataclasses.dataclass()
12
class Pane(Obj):
13
    """
14
    tmux Pane object.
15
    
16
    Pane instances can send commands directly to a pane, or traverse
17
    between linked tmux objects.
18
    """
19
    
20
    server: Server
21

22
    def __enter__(self) -> Self:
23
        """Enter the context, returning self."""
24
        
25
    def __exit__(
26
        self,
27
        exc_type: type[BaseException] | None,
28
        exc_value: BaseException | None,
29
        exc_tb: types.TracebackType | None
30
    ) -> None:
31
        """Exit the context, killing the pane if it exists."""
32

33
    @classmethod
34
    def from_pane_id(cls, server: Server, pane_id: str) -> Pane:
35
        """Create Pane from existing pane_id."""
36
```
37

38
### Pane Information and Refresh
39

40
Access and update pane state, properties, and position information from tmux.
41

42
```python { .api }
43
def refresh(self) -> None:
44
    """Refresh pane attributes from tmux."""
45

46
@property
47
def id(self) -> str | None:
48
    """Alias of Pane.pane_id."""
49

50
@property
51
def index(self) -> str | None:
52
    """Alias of Pane.pane_index."""
53

54
@property
55
def height(self) -> str | None:
56
    """Alias of Pane.pane_height."""
57

58
@property
59
def width(self) -> str | None:
60
    """Alias of Pane.pane_width."""
61

62
@property
63
def window(self) -> Window:
64
    """Parent window of pane."""
65

66
@property
67
def session(self) -> Session:
68
    """Parent session of pane."""
69
```
70

71
### Pane Position Properties
72

73
Determine pane position within window layout.
74

75
```python { .api }
76
@property
77
def at_top(self) -> bool:
78
    """True if pane is at top edge of window."""
79

80
@property
81
def at_bottom(self) -> bool:
82
    """True if pane is at bottom edge of window."""
83

84
@property
85
def at_left(self) -> bool:
86
    """True if pane is at left edge of window."""
87

88
@property
89
def at_right(self) -> bool:
90
    """True if pane is at right edge of window."""
91
```
92

93
### Command Execution
94

95
Execute tmux commands within the pane context.
96

97
```python { .api }
98
def cmd(
99
    self,
100
    cmd: str,
101
    *args: t.Any,
102
    target: str | int | None = None
103
) -> tmux_cmd:
104
    """
105
    Execute tmux subcommand within pane context.
106
    
107
    Automatically binds target by adding -t for object's pane ID to the command.
108
    Pass target to keyword arguments to override.
109
    
110
    Parameters:
111
    - cmd: The tmux command to execute
112
    - *args: Additional command arguments
113
    - target: Optional custom target override (defaults to pane ID)
114
    
115
    Returns:
116
    tmux_cmd object with stdout, stderr, and return code
117
    """
118
```
119

120
### Input and Output Operations
121

122
Send commands and capture output from the pane's terminal session.
123

124
```python { .api }
125
def send_keys(
126
    self,
127
    cmd: str,
128
    enter: bool | None = True,
129
    suppress_history: bool | None = False,
130
    literal: bool | None = False
131
) -> None:
132
    """
133
    Send keys/text to pane via tmux send-keys.
134
    
135
    A leading space character is added to cmd to avoid polluting the
136
    user's history.
137
    
138
    Parameters:
139
    - cmd: Text or input to send into pane
140
    - enter: Send enter after sending the input (default True)
141
    - suppress_history: Prepend space to command to suppress shell history (default False)
142
    - literal: Send keys literally (default False)
143
    """
144

145
def enter(self) -> Pane:
146
    """
147
    Send carriage return to pane.
148
    
149
    Returns:
150
    Pane instance for method chaining
151
    """
152

153
def capture_pane(
154
    self,
155
    start: t.Literal["-"] | int | None = None,
156
    end: t.Literal["-"] | int | None = None
157
) -> str | list[str]:
158
    """
159
    Capture text from pane.
160
    
161
    Parameters:
162
    - start: Starting line number (0=first visible line, negative=history, "-"=start of history)
163
    - end: Ending line number (0=first visible line, negative=history, "-"=end of visible pane)
164
    
165
    Returns:
166
    List of strings containing pane content
167
    """
168

169
def display_message(
170
    self,
171
    cmd: str,
172
    get_text: bool = False
173
) -> str | list[str] | None:
174
    """
175
    Display message to pane.
176
    
177
    Displays a message in target-client status line.
178
    
179
    Parameters:
180
    - cmd: Special parameters to request from pane
181
    - get_text: Returns only text without displaying message in status line
182
    
183
    Returns:
184
    Message text if get_text=True, None otherwise
185
    """
186
```
187

188
### Pane Control and Navigation
189

190
Control pane state, selection, and focus within window.
191

192
```python { .api }
193
def select(self) -> Pane:
194
    """
195
    Select pane.
196
    
197
    Returns:
198
    Pane instance for method chaining
199
    """
200

201
def clear(self) -> Pane:
202
    """
203
    Clear pane.
204
    
205
    Returns:
206
    Pane instance for method chaining
207
    """
208

209
def reset(self) -> Pane:
210
    """
211
    Reset and clear pane history.
212
    
213
    Returns:
214
    Pane instance for method chaining
215
    """
216
```
217

218
### Pane Splitting
219

220
Create new panes by splitting the current pane.
221

222
```python { .api }
223
def split(
224
    self,
225
    /,
226
    target: int | str | None = None,
227
    start_directory: StrPath | None = None,
228
    attach: bool = False,
229
    direction: PaneDirection | None = None,
230
    full_window_split: bool | None = None,
231
    zoom: bool | None = None,
232
    shell: str | None = None,
233
    size: str | int | None = None,
234
    environment: dict[str, str] | None = None
235
) -> Pane:
236
    """
237
    Split window and return Pane, by default beneath current pane.
238
    
239
    Parameters:
240
    - target: Optional custom target-pane, used by Window.split
241
    - start_directory: Working directory for new window (str or PathLike)
242
    - attach: Make new window the current window after creating (default False)
243
    - direction: Split direction (PaneDirection enum). If none specified, assume down
244
    - full_window_split: Split across full window width/height rather than active pane
245
    - zoom: Expand pane
246
    - shell: Execute command on splitting the window
247
    - size: Cell/row or percentage to occupy with respect to current window
248
    - environment: Environmental variables for new pane (tmux 3.0+)
249
    
250
    Returns:
251
    Pane object for the created pane
252
    """
253
```
254

255
### Pane Resizing
256

257
Resize individual panes within window layout.
258

259
```python { .api }
260
def resize(
261
    self,
262
    /,
263
    # Adjustments
264
    adjustment_direction: ResizeAdjustmentDirection | None = None,
265
    adjustment: int | None = None,
266
    # Manual
267
    height: str | int | None = None,
268
    width: str | int | None = None,
269
    # Zoom
270
    zoom: bool | None = None,
271
    # Mouse
272
    mouse: bool | None = None,
273
    # Optional flags
274
    trim_below: bool | None = None
275
) -> Pane:
276
    """
277
    Resize tmux pane.
278
    
279
    Parameters:
280
    - adjustment_direction: Direction to adjust (Up, Down, Left, Right)
281
    - adjustment: Amount to adjust by
282
    - height: resize-pane -y dimensions
283
    - width: resize-pane -x dimensions
284
    - zoom: Expand pane
285
    - mouse: Resize via mouse
286
    - trim_below: Trim below cursor
287
    
288
    Returns:
289
    Pane instance for method chaining
290
    
291
    Raises:
292
    LibTmuxException, PaneAdjustmentDirectionRequiresAdjustment, RequiresDigitOrPercentage
293
    """
294

295
def set_width(self, width: int) -> Pane:
296
    """
297
    Set pane width.
298
    
299
    Parameters:
300
    - width: Pane width, in cells
301
    
302
    Returns:
303
    Pane instance for method chaining
304
    """
305

306
def set_height(self, height: int) -> Pane:
307
    """
308
    Set pane height.
309
    
310
    Parameters:
311
    - height: Height of pane, in cells
312
    
313
    Returns:
314
    Pane instance for method chaining
315
    """
316
```
317

318
### Pane Lifecycle
319

320
Control pane termination and cleanup.
321

322
```python { .api }
323
def kill(
324
    self,
325
    all_except: bool | None = None
326
) -> None:
327
    """
328
    Kill Pane.
329
    
330
    $ tmux kill-pane.
331
    
332
    Parameters:
333
    - all_except: Kill all panes except this one
334
    """
335
```
336

337
## Usage Examples
338

339
### Basic Pane Operations
340

341
```python
342
import libtmux
343

344
server = libtmux.Server()
345
session = server.new_session('work')
346
window = session.new_window('main')
347
pane = window.active_pane
348

349
# Get pane information
350
print(f"Pane ID: {pane.id}")
351
print(f"Pane Size: {pane.width}x{pane.height}")
352
print(f"Position: top={pane.at_top}, left={pane.at_left}")
353

354
# Refresh pane state
355
pane.refresh()
356
```
357

358
### Context Manager Usage
359

360
```python
361
import libtmux
362

363
server = libtmux.Server()
364
session = server.new_session('temp')
365
window = session.new_window('work')
366

367
with window.split_window() as pane:
368
    # Work with pane
369
    pane.send_keys('echo "Hello World"')
370
    # Pane automatically cleaned up on exit
371
```
372

373
### Command Execution and Output Capture
374

375
```python
376
import libtmux
377

378
server = libtmux.Server()
379
session = server.new_session('commands')
380
window = session.new_window('terminal')
381
pane = window.active_pane
382

383
# Send commands
384
pane.send_keys('ls -la')
385
pane.send_keys('echo "Processing..."')
386
pane.send_keys('date', enter=True)
387

388
# Capture output
389
import time
390
time.sleep(1)  # Wait for commands to complete
391
output = pane.capture_pane()
392
print('\n'.join(output))
393

394
# Clear pane for next commands
395
pane.clear()
396
```
397

398
### Interactive Command Execution
399

400
```python
401
import libtmux
402

403
server = libtmux.Server()  
404
session = server.new_session('interactive')
405
window = session.new_window('python')
406
pane = window.active_pane
407

408
# Start Python interpreter
409
pane.send_keys('python3')
410
time.sleep(1)
411

412
# Send Python commands
413
pane.send_keys('import os')
414
pane.send_keys('print(os.getcwd())')
415
pane.send_keys('x = 2 + 2') 
416
pane.send_keys('print(f"Result: {x}")')
417

418
# Capture Python output
419
output = pane.capture_pane()
420
python_output = [line for line in output if line.strip()]
421
print(python_output)
422

423
# Exit Python
424
pane.send_keys('exit()')
425
```
426

427
### Pane Layout and Splitting
428

429
```python
430
import libtmux
431

432
server = libtmux.Server()
433
session = server.new_session('layout')
434
window = session.new_window('multi_pane')
435

436
# Start with active pane
437
main_pane = window.active_pane
438

439
# Split vertically (right side)
440
right_pane = main_pane.split_window(vertical=True)
441

442
# Split main pane horizontally (bottom)
443
bottom_pane = main_pane.split_window(vertical=False)
444

445
# Split right pane horizontally
446
bottom_right = right_pane.split_window(vertical=False)
447

448
# Resize panes
449
main_pane.set_width(80)
450
right_pane.resize('left', 5)
451

452
# Send different commands to each pane
453
main_pane.send_keys('htop')
454
right_pane.send_keys('tail -f /var/log/syslog')
455
bottom_pane.send_keys('cd /tmp && ls -la')
456
bottom_right.send_keys('python3')
457
```
458

459
### File Operations and Monitoring
460

461
```python
462
import libtmux
463

464
server = libtmux.Server()
465
session = server.new_session('monitoring')
466
window = session.new_window('files')
467

468
# Create panes for different monitoring tasks
469
log_pane = window.active_pane
470
cpu_pane = log_pane.split_window(vertical=True)
471
disk_pane = log_pane.split_window(vertical=False)
472

473
# Set up monitoring in each pane
474
log_pane.send_keys('tail -f /var/log/system.log')
475
cpu_pane.send_keys('top -o cpu')
476
disk_pane.send_keys('watch df -h')
477

478
# Capture initial state
479
time.sleep(2)
480
for i, pane in enumerate([log_pane, cpu_pane, disk_pane]):
481
    content = pane.capture_pane(start=-10)  # Last 10 lines
482
    print(f"Pane {i} content:")
483
    print('\n'.join(content[-5:]))  # Show last 5 lines
484
    print("---")
485
```