0
# libtmux
1
2
libtmux is a typed Python library that provides an ORM wrapper for tmux, a terminal multiplexer. It offers a pythonic interface to manage tmux servers, sessions, windows, and panes programmatically, enabling developers to automate terminal workflows and build tmux-powered applications.
3
4
## Package Information
5
6
- **Package Name**: libtmux
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install libtmux`
10
11
## Core Imports
12
13
```python
14
import libtmux
15
from libtmux import Server, Session, Window, Pane
16
```
17
18
## Basic Usage
19
20
```python
21
import libtmux
22
23
# Connect to tmux server
24
server = libtmux.Server()
25
26
# Create a new session
27
session = server.new_session(session_name="my_session", window_name="main")
28
29
# Create a new window
30
window = session.new_window(window_name="work")
31
32
# Split window into panes
33
pane = window.split()
34
35
# Send commands to pane
36
pane.send_keys("echo 'Hello World'")
37
pane.send_keys("Enter")
38
39
# Get output from pane
40
output = pane.capture_pane()
41
print(output)
42
43
# Clean up
44
session.kill()
45
```
46
47
## Architecture
48
49
libtmux follows tmux's hierarchical structure with context manager support for automatic cleanup:
50
51
- **Server**: Top-level tmux server instance managing socket connections and global operations
52
- **Session**: Collection of windows within a server, handling session-level configuration and environment
53
- **Window**: Collection of panes within a session, managing layout and window-specific options
54
- **Pane**: Individual terminal instance within a window, providing direct interaction with shell processes
55
56
All objects support both direct manipulation and context manager protocols for proper resource management.
57
58
## Capabilities
59
60
### Server Management
61
62
Server connection, lifecycle management, and global tmux operations. Handles socket connections, server status, and cross-session operations.
63
64
```python { .api }
65
class Server:
66
def __init__(
67
self,
68
socket_name: str | None = None,
69
socket_path: str | pathlib.Path | None = None,
70
config_file: str | None = None,
71
colors: int | None = None,
72
on_init: t.Callable[[Server], None] | None = None,
73
socket_name_factory: t.Callable[[], str] | None = None,
74
**kwargs: t.Any
75
) -> None: ...
76
def is_alive(self) -> bool: ...
77
def cmd(self, cmd: str, *args: t.Any, target: str | int | None = None) -> tmux_cmd: ...
78
def new_session(
79
self,
80
session_name: str | None = None,
81
kill_session: bool = False,
82
attach: bool = False,
83
start_directory: StrPath | None = None,
84
window_name: str | None = None,
85
window_command: str | None = None,
86
x: int | DashLiteral | None = None,
87
y: int | DashLiteral | None = None,
88
environment: dict[str, str] | None = None,
89
*args: t.Any,
90
**kwargs: t.Any
91
) -> Session: ...
92
def has_session(self, target_session: str, exact: bool = True) -> bool: ...
93
def kill_session(self, target_session: str | int) -> Server: ...
94
```
95
96
[Server Management](./server.md)
97
98
### Session Management
99
100
Session creation, configuration, and lifecycle operations. Manages session-level environment variables, options, and window collections.
101
102
```python { .api }
103
class Session:
104
server: Server
105
def cmd(self, cmd: str, *args: t.Any, target: str | int | None = None) -> tmux_cmd: ...
106
def new_window(
107
self,
108
window_name: str | None = None,
109
*,
110
start_directory: StrPath | None = None,
111
attach: bool = False,
112
window_index: str = "",
113
window_shell: str | None = None,
114
environment: dict[str, str] | None = None,
115
direction: WindowDirection | None = None,
116
target_window: str | None = None
117
) -> Window: ...
118
def kill(self, all_except: bool | None = None, clear: bool | None = None) -> None: ...
119
def set_environment(self, name: str, value: str) -> Session: ...
120
def show_environment(self, global_: bool = False) -> dict[str, str]: ...
121
```
122
123
[Session Management](./session.md)
124
125
### Window Management
126
127
Window operations, layout management, and pane organization. Handles window-specific options, layouts, and pane splitting operations.
128
129
```python { .api }
130
class Window:
131
server: Server
132
def cmd(self, cmd: str, *args: t.Any, target: str | int | None = None) -> tmux_cmd: ...
133
def split(
134
self,
135
/,
136
target: int | str | None = None,
137
start_directory: StrPath | None = None,
138
attach: bool = False,
139
direction: PaneDirection | None = None,
140
full_window_split: bool | None = None,
141
zoom: bool | None = None,
142
shell: str | None = None,
143
size: str | int | None = None,
144
environment: dict[str, str] | None = None
145
) -> Pane: ...
146
def select_layout(self, layout: str | None = None) -> Window: ...
147
def rename_window(self, new_name: str) -> Window: ...
148
def kill(self, all_except: bool | None = None) -> None: ...
149
```
150
151
[Window Management](./window.md)
152
153
### Pane Management
154
155
Direct pane interaction, content capture, and command execution. Provides the primary interface for sending commands and retrieving output from terminal sessions.
156
157
```python { .api }
158
class Pane:
159
server: Server
160
def cmd(self, cmd: str, *args: t.Any, target: str | int | None = None) -> tmux_cmd: ...
161
def send_keys(
162
self,
163
cmd: str,
164
enter: bool | None = True,
165
suppress_history: bool | None = False,
166
literal: bool | None = False
167
) -> None: ...
168
def capture_pane(
169
self,
170
start: t.Literal["-"] | int | None = None,
171
end: t.Literal["-"] | int | None = None
172
) -> str | list[str]: ...
173
def split(
174
self,
175
/,
176
target: int | str | None = None,
177
start_directory: StrPath | None = None,
178
attach: bool = False,
179
direction: PaneDirection | None = None,
180
full_window_split: bool | None = None,
181
zoom: bool | None = None,
182
shell: str | None = None,
183
size: str | int | None = None,
184
environment: dict[str, str] | None = None
185
) -> Pane: ...
186
def kill(self, all_except: bool | None = None) -> None: ...
187
```
188
189
[Pane Management](./pane.md)
190
191
### Exception Handling
192
193
Comprehensive exception hierarchy for error handling and tmux-specific error conditions.
194
195
```python { .api }
196
class LibTmuxException(Exception): ...
197
class TmuxSessionExists(LibTmuxException): ...
198
class TmuxCommandNotFound(LibTmuxException): ...
199
class TmuxObjectDoesNotExist(LibTmuxException): ...
200
class VersionTooLow(LibTmuxException): ...
201
```
202
203
[Exception Handling](./exceptions.md)
204
205
### Utility Functions
206
207
Version checking, tmux compatibility, and helper functions for tmux operations.
208
209
```python { .api }
210
def get_version() -> LooseVersion: ...
211
def has_minimum_version(raises: bool = True) -> bool: ...
212
def session_check_name(session_name: str | None) -> None: ...
213
```
214
215
[Utilities](./utilities.md)
216
217
## Types
218
219
### Core Types
220
221
```python { .api }
222
from typing import Dict, List, Optional, Union, Any
223
from pathlib import Path
224
225
StrPath = Union[str, Path]
226
227
class QueryList(list):
228
"""List-like interface with filtering capabilities."""
229
def get(self, **kwargs): ...
230
def filter(self, **kwargs): ...
231
```
232
233
### Direction Enums
234
235
```python { .api }
236
from enum import Enum
237
238
class PaneDirection(Enum):
239
Above = "ABOVE"
240
Below = "BELOW"
241
Left = "LEFT"
242
Right = "RIGHT"
243
244
class WindowDirection(Enum):
245
Before = "BEFORE"
246
After = "AFTER"
247
248
class ResizeAdjustmentDirection(Enum):
249
Up = "UP"
250
Down = "DOWN"
251
Left = "LEFT"
252
Right = "RIGHT"
253
```