0
# Window Management
1

2
Window management in libtmux handles tmux window operations, pane organization, layout management, and window-specific configuration. Windows contain collections of panes and provide the primary workspace organization within sessions.
3

4
## Capabilities
5

6
### Window Initialization and Context
7

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

10
```python { .api }
11
@dataclasses.dataclass()
12
class Window(Obj):
13
    """
14
    tmux Window object.
15
    
16
    Holds Pane objects and inherits from Obj.
17
    """
18
    
19
    server: Server
20

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

32
    @classmethod
33
    def from_window_id(cls, server: Server, window_id: str) -> Window:
34
        """Create Window from existing window_id."""
35
```
36

37
### Window Information and Refresh
38

39
Access and update window state, properties, and attributes from tmux.
40

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

45
@property
46
def id(self) -> str | None:
47
    """Alias of Window.window_id."""
48

49
@property
50
def name(self) -> str | None:
51
    """Alias of Window.window_name."""
52

53
@property
54
def index(self) -> str | None:
55
    """Alias of Window.window_index."""
56

57
@property
58
def height(self) -> str | None:
59
    """Alias of Window.window_height."""
60

61
@property  
62
def width(self) -> str | None:
63
    """Alias of Window.window_width."""
64

65
@property
66
def session(self) -> Session:
67
    """Parent session of window."""
68

69
@property
70
def active_pane(self) -> Pane | None:
71
    """Return attached Pane."""
72
```
73

74
### Command Execution
75

76
Execute tmux commands within the window context.
77

78
```python { .api }
79
def cmd(
80
    self,
81
    cmd: str,
82
    *args: t.Any,
83
    target: str | int | None = None
84
) -> tmux_cmd:
85
    """
86
    Execute tmux subcommand within window context.
87
    
88
    Automatically binds target by adding -t for object's window ID to the command.
89
    Pass target to keyword arguments to override.
90
    
91
    Parameters:
92
    - cmd: The tmux command to execute
93
    - *args: Additional command arguments
94
    - target: Optional custom target override (defaults to window ID)
95
    
96
    Returns:
97
    tmux_cmd object with stdout, stderr, and return code
98
    """
99
```
100

101
### Pane Operations
102

103
Create, manage, and query panes within the window.
104

105
```python { .api }
106
def split(
107
    self,
108
    /,
109
    target: int | str | None = None,
110
    start_directory: StrPath | None = None,
111
    attach: bool = False,
112
    direction: PaneDirection | None = None,
113
    full_window_split: bool | None = None,
114
    zoom: bool | None = None,
115
    shell: str | None = None,
116
    size: str | int | None = None,
117
    environment: dict[str, str] | None = None
118
) -> Pane:
119
    """
120
    Split window on active pane and return the created Pane.
121
    
122
    Parameters:
123
    - target: Target pane to split
124
    - start_directory: Working directory for new pane (str or PathLike)
125
    - attach: Make new window the current window after creating (default False)
126
    - direction: Split direction (PaneDirection enum)
127
    - full_window_split: Split across full window width/height rather than active pane
128
    - zoom: Expand pane
129
    - shell: Execute command on splitting the window
130
    - size: Cell/row or percentage to occupy with respect to current window
131
    - environment: Environmental variables for new pane (tmux 3.0+)
132
    
133
    Returns:
134
    Pane object for the created pane
135
    """
136

137
def select_pane(self, target_pane: str | int) -> Pane | None:
138
    """
139
    Select pane and return selected Pane.
140
    
141
    Parameters:
142
    - target_pane: Target pane ('-U', '-D', '-L', '-R', '-l', or pane ID)
143
    
144
    Returns:
145
    Selected Pane object
146
    """
147

148
def last_pane(self) -> Pane | None:
149
    """Return last pane."""
150
```
151

152
### Window Layout Management
153

154
Control window layout, pane arrangement, and display organization.
155

156
```python { .api }
157
def select_layout(self, layout: str | None = None) -> Window:
158
    """
159
    Select layout for window.
160
    
161
    Wrapper for $ tmux select-layout <layout>.
162
    
163
    Parameters:
164
    - layout: Layout name ('even-horizontal', 'even-vertical', 'main-horizontal', 
165
              'main-vertical', 'tiled', 'custom') or None for most recent layout
166
    
167
    Returns:
168
    Window instance for method chaining
169
    """
170

171
def resize(
172
    self,
173
    /,
174
    # Adjustments
175
    adjustment_direction: ResizeAdjustmentDirection | None = None,
176
    adjustment: int | None = None,
177
    # Manual
178
    height: int | None = None,
179
    width: int | None = None,
180
    # Expand / Shrink
181
    expand: bool | None = None,
182
    shrink: bool | None = None
183
) -> Window:
184
    """
185
    Resize tmux window.
186
    
187
    Parameters:
188
    - adjustment_direction: Direction to adjust (Up, Down, Left, Right)
189
    - adjustment: Amount to adjust by
190
    - height: resize-window -y dimensions
191
    - width: resize-window -x dimensions
192
    - expand: Expand window
193
    - shrink: Shrink window
194
    
195
    Returns:
196
    Window instance for method chaining
197
    
198
    Raises:
199
    LibTmuxException, WindowAdjustmentDirectionRequiresAdjustment
200
    """
201
```
202

203
### Window Control and Navigation
204

205
Control window state, selection, and navigation within session.
206

207
```python { .api }
208
def select(self) -> Window:
209
    """
210
    Select window.
211
    
212
    To select a window object asynchronously. If a window object exists
213
    and is no longer the current window, w.select() will make w the current window.
214
    
215
    Returns:
216
    Window instance for method chaining
217
    """
218

219
def move_window(
220
    self,
221
    destination: str = "",
222
    session: str | None = None
223
) -> Window:
224
    """
225
    Move current Window object $ tmux move-window.
226
    
227
    Parameters:
228
    - destination: Target window or index to move the window to (default: empty string)
229
    - session: Target session or index to move the window to (default: current session)
230
    
231
    Returns:
232
    Window instance for method chaining
233
    """
234

235
def new_window(
236
    self,
237
    window_name: str | None = None,
238
    *,
239
    start_directory: None = None,
240
    attach: bool = False,
241
    window_index: str = "",
242
    window_shell: str | None = None,
243
    environment: dict[str, str] | None = None,
244
    direction: WindowDirection | None = None
245
) -> Window:
246
    """
247
    Create new window respective of current window's position.
248
    
249
    Parameters:
250
    - window_name: Name for the new window
251
    - start_directory: Working directory for new window
252
    - attach: Make new window active after creation
253
    - window_index: Index position for new window
254
    - window_shell: Shell command to run in new window
255
    - environment: Environment variables for window (tmux 3.0+)
256
    - direction: Direction to insert window (tmux 3.2+)
257
    
258
    Returns:
259
    Window object for the created window
260
    """
261
```
262

263
### Window Lifecycle
264

265
Control window renaming, termination, and lifecycle operations.
266

267
```python { .api }
268
def rename_window(self, new_name: str) -> Window:
269
    """
270
    Rename window.
271
    
272
    Parameters:
273
    - new_name: New name for the window
274
    
275
    Returns:
276
    Window instance for method chaining
277
    """
278

279
def kill(
280
    self,
281
    all_except: bool | None = None
282
) -> None:
283
    """
284
    Kill Window.
285
    
286
    $ tmux kill-window.
287
    
288
    Parameters:
289
    - all_except: Kill all windows except this one
290
    """
291
```
292

293
### Window Options
294

295
Configure window-level tmux options and settings.
296

297
```python { .api }
298
def set_window_option(self, option: str, value: int | str) -> Window:
299
    """
300
    Set option for tmux window.
301
    
302
    Wraps $ tmux set-window-option <option> <value>.
303
    
304
    Parameters:
305
    - option: Option to set (e.g., 'aggressive-resize')
306
    - value: Window option value (True/False becomes 'on'/'off')
307
    
308
    Returns:
309
    Window instance for method chaining
310
    
311
    Raises:
312
    OptionError, UnknownOption, InvalidOption, AmbiguousOption
313
    """
314

315
def show_window_options(self, g: bool | None = False) -> WindowOptionDict:
316
    """
317
    Return dict of options for window.
318
    
319
    Parameters:
320
    - g: Pass -g flag for global variable (default False)
321
    
322
    Returns:
323
    Dictionary of window option names and values
324
    """
325

326
def show_window_option(
327
    self,
328
    option: str,
329
    g: bool = False
330
) -> str | int | None:
331
    """
332
    Return option value for the target window.
333
    
334
    Parameters:
335
    - option: Option name
336
    - g: Pass -g flag, global (default False)
337
    
338
    Returns:
339
    Option value (str, int, or None if not found)
340
    
341
    Raises:
342
    OptionError, UnknownOption, InvalidOption, AmbiguousOption
343
    """
344
```
345

346
### Collection Properties
347

348
Access collections of panes and active pane within the window.
349

350
```python { .api }
351
@property
352
def panes(self) -> QueryList[Pane]:
353
    """
354
    Panes contained by window.
355
    
356
    Can be accessed via .panes.get() and .panes.filter()
357
    """
358
```
359

360
## Usage Examples
361

362
### Basic Window Operations
363

364
```python
365
import libtmux
366

367
server = libtmux.Server()
368
session = server.new_session('work')
369
window = session.new_window('main')
370

371
# Get window information
372
print(f"Window ID: {window.id}")
373
print(f"Window Name: {window.name}")
374
print(f"Window Size: {window.width}x{window.height}")
375

376
# Refresh window state
377
window.refresh()
378
```
379

380
### Context Manager Usage
381

382
```python
383
import libtmux
384

385
server = libtmux.Server()
386
session = server.new_session('temp')
387

388
with session.new_window('work') as window:
389
    # Work with window
390
    pane = window.split_window()
391
    # Window automatically cleaned up on exit
392
```
393

394
### Pane Management
395

396
```python
397
import libtmux
398

399
server = libtmux.Server()
400
session = server.new_session('dev')
401
window = session.new_window('editor')
402

403
# Split window into panes
404
right_pane = window.split_window(vertical=True)
405
bottom_pane = window.split_window(vertical=False, target_pane=window.active_pane.id)
406

407
# Query panes
408
for pane in window.panes:
409
    print(f"Pane: {pane.id}")
410

411
# Select specific pane
412
window.select_pane(right_pane.id)
413
```
414

415
### Layout Management
416

417
```python
418
import libtmux
419

420
server = libtmux.Server()
421
session = server.new_session('layout_test')
422
window = session.new_window('main')
423

424
# Create multiple panes
425
window.split_window(vertical=True)
426
window.split_window(vertical=False)
427
window.split_window(vertical=True)
428

429
# Apply different layouts
430
window.select_layout('tiled')
431
window.select_layout('main-vertical')
432
window.select_layout('even-horizontal')
433

434
# Manual resize
435
window.resize('right', 10)
436
```
437

438
### Window Options
439

440
```python
441
import libtmux
442

443
server = libtmux.Server()
444
session = server.new_session('configured')
445
window = session.new_window('main')
446

447
# Set window options
448
window.set_window_option('automatic-rename', 'off')
449
window.set_window_option('monitor-activity', 'on')
450

451
# Get options
452
auto_rename = window.show_window_option('automatic-rename')
453
all_options = window.show_window_options()
454

455
# Rename window
456
window.rename_window('editor')
457
```