libtmux

https://libtmux.git-pull.com/
Admin
libtmux is a typed Python library that provides an API to control and automate tmux servers,...
Tokens:75,524
Snippets:1,114
Trust Score:7.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start tmux in a terminal

Source: https://libtmux.git-pull.com/topics/context_managers.md

Open a terminal and start tmux to follow along with the context manager examples.

```console
$ tmux
```

--------------------------------

### Install libtmux via uv

Source: https://libtmux.git-pull.com/index.md

Install the library using the uv package manager.

```console
$ uv add libtmux
```

--------------------------------

### Start Python interpreter

Source: https://libtmux.git-pull.com/topics/context_managers.md

Open a second terminal and start Python (or ptpython) to run the libtmux examples.

```console
$ python
```

--------------------------------

### Server.start_server()

Source: https://libtmux.git-pull.com/docs.json

Starts the tmux server.

```APIDOC
## Server.start_server()

### Description
Starts the tmux server.

### Method
start_server()

### Parameters
None

### Returns
None.
```

--------------------------------

### Install libtmux via pip

Source: https://libtmux.git-pull.com/quickstart.html

Standard installation command for libtmux using pip.

```bash
$ pip install --user libtmux
```

--------------------------------

### Quick Start: Using fixtures in doctests

Source: https://libtmux.git-pull.com/api/testing/pytest-plugin/fixtures.md

Shows how to use libtmux fixtures in doctests. The fixtures are injected via doctest_namespace. The example creates a session and a window, checks they are not None, and kills them.

```python
>>> created_session = server.new_session(session_name="my-session")
>>> created_session is not None
True
>>> created_session.kill()

>>> created_window = session.new_window(window_name="test")
>>> created_window is not None
True
>>> created_window.kill()
```

--------------------------------

### Execute basic command

Source: https://libtmux.git-pull.com/topics/pane_interaction.md

Example of splitting a window and sending a command to the new pane.

```python
>>> pane = window.split(shell='sh')

>>> pane.send_keys('echo "Hello from libtmux"')

>>> import time; time.sleep(0.1)  # Allow command to execute

>>> output = pane.capture_pane()
>>> 'Hello from libtmux' in '\\n'.join(output)
True
```

--------------------------------

### Create a window with a specific shell (window_shell)

Source: https://libtmux.git-pull.com/topics/workspace_setup.md

Creates a window that runs a custom shell command instead of the default shell. The example uses window_shell='sh -c "echo Hello; exec sh"' to boot into a shell that echoes Hello and then starts an interactive shell. The window is created in the background and cleaned up with kill().

```python
>>> shell_window = session.new_window(
...     window_name='shell-test',
...     attach=False,
...     window_shell='sh -c "echo Hello; exec sh"',
... )
>>> shell_window  # doctest: +ELLIPSIS
Window(@... ...:shell-test, Session($... ...))

>>> # Clean up
>>> shell_window.kill()
```

--------------------------------

### Install libtmux via pip

Source: https://libtmux.git-pull.com/index.md

Install the library using the pip package manager.

```console
$ pip install libtmux
```

--------------------------------

### Start tmux and python

Source: https://libtmux.git-pull.com/topics/self_location.md

Commands to initiate a tmux session and start a python interpreter inside a pane.

```console
$ tmux
```

```console
$ python
```

--------------------------------

### Start a background process with send_keys

Source: https://libtmux.git-pull.com/topics/automation_patterns.md

Demonstrates how to initiate a command in a libtmux pane that runs in the background, allowing the script to continue execution immediately.

```python
>>> import time

>>> proc_window = session.new_window(window_name='process', attach=False)
>>> proc_pane = proc_window.active_pane

>>> # Start a background process
>>> proc_pane.send_keys('sleep 2 && echo "Process complete"')

>>> # Process is running
>>> time.sleep(0.1)
>>> proc_window.window_name
'process'

>>> # Clean up
>>> proc_window.kill()
```

--------------------------------

### Install libtmux from trunk via uv tool

Source: https://libtmux.git-pull.com/quickstart.html

Command to install the latest development version of libtmux from the git repository using uv tool.

```bash
$ uv tool install libtmux --from git+https://github.com/tmux-python/libtmux.git
```

--------------------------------

### Install ptpython for commandline completion

Source: https://libtmux.git-pull.com/quickstart.html

Installs ptpython, which provides commandline completion for the Python shell.

```bash
$ pip install --user ptpython

```

--------------------------------

### Ask where you are using environment variables

Source: https://libtmux.git-pull.com/topics/self_location.md

Demonstrates using from_env methods to identify the current pane, window, and session. The example manually sets environment variables to simulate running inside a tmux pane.

```python
>>> socket_path = server.cmd(
...     "display-message", "-p", "-t", session.session_id, "#{socket_path}"
... ).stdout[0]
>>> monkeypatch.setenv("TMUX", f"{socket_path},1,{session.session_id}")
>>> monkeypatch.setenv("TMUX_PANE", pane.pane_id)

>>> Pane.from_env().pane_id == pane.pane_id
True
>>> Window.from_env().window_id == window.window_id
True
>>> Session.from_env().session_id == session.session_id
True
```

--------------------------------

### Show a single option with show_option

Source: https://libtmux.git-pull.com/topics/options_and_hooks.md

Use server.show_option('buffer-limit') to get a single option value. The example shows the default value of 50.

```python
>>> server.show_option('buffer-limit')
50
```

--------------------------------

### Find and get windows by prefix

Source: https://libtmux.git-pull.com/topics/filtering.md

Demonstrates filtering windows by a common prefix using window_name__startswith and retrieving a specific window by name using .get().

```python
>>> # Create windows following a naming convention
>>> w1 = session.new_window(window_name="project-frontend")
>>> w2 = session.new_window(window_name="project-backend")
>>> w3 = session.new_window(window_name="logs")

>>> # Find all project windows
>>> project_windows = session.windows.filter(window_name__startswith='project-')
>>> len(project_windows) >= 2
True

>>> # Get specific project window
>>> backend = session.windows.get(window_name='project-backend')
>>> backend.window_name
'project-backend'

>>> # Clean up
>>> w1.kill()
>>> w2.kill()
>>> w3.kill()
```

--------------------------------

### Install libtmux developmental release via uv tool

Source: https://libtmux.git-pull.com/quickstart.html

Command to install pre-release versions of libtmux using uv tool.

```bash
$ uv tool install --prerelease=allow libtmux
```

--------------------------------

### Start a tmux session with session and window names

Source: https://libtmux.git-pull.com/quickstart.html

Opens a new tmux session named 'foo' with a window named 'bar'. The session and window names are used throughout the tutorial.

```bash
$ tmux new-session -n bar -s foo

```

--------------------------------

### Install libtmux from trunk via pip

Source: https://libtmux.git-pull.com/quickstart.html

Command to install the latest development version of libtmux directly from the git repository using pip.

```bash
$ pip install --user -e git+https://github.com/tmux-python/libtmux.git#egg=libtmux
```

--------------------------------

### Install libtmux from trunk via pipx

Source: https://libtmux.git-pull.com/quickstart.html

Command to install the latest development version of libtmux from the master branch using pipx.

```bash
$ pipx install \
    --suffix=@master \
    --force \
    'libtmux @ git+https://github.com/tmux-python/libtmux.git@master'
```

--------------------------------

### Test with libtmux fixtures

Source: https://libtmux.git-pull.com/index.md

Example of using libtmux within a testing context to create windows and verify their properties.

```python
>>> test_window = session.new_window(window_name="test")
>>> test_pane = test_window.active_pane
>>> test_pane.send_keys("echo hello")
>>> test_window.window_name
'test'
>>> test_window.kill()
```

--------------------------------

### Install libtmux developmental release via pip

Source: https://libtmux.git-pull.com/quickstart.html

Command to install pre-release versions of libtmux using pip.

```bash
$ pip install --user --upgrade --pre libtmux
```

--------------------------------

### Getting tmux options

Source: https://libtmux.git-pull.com/quickstart.html

Demonstrates retrieving a specific option value using show_option and listing all options for a window using show_options.

```python
>>> server.show_option('buffer-limit')
50

>>> window.show_options()
{...}
```

--------------------------------

### Create a development workspace with libtmux

Source: https://libtmux.git-pull.com/topics/workspace_setup.md

Defines a helper function that creates a window with a main editing pane, a terminal pane below it, and a log pane to the right. Returns a dictionary keyed by role so the caller can drive each pane by name. The example also shows creating a workspace, checking the pane count, and cleaning up by killing the window.

```python
>>> import time
>>> from libtmux.constants import PaneDirection

>>> def create_dev_workspace(session, name='dev'):
...     """Create a typical development workspace layout."""
...     window = session.new_window(window_name=name, attach=False)
...     window.resize(height=50, width=160)
...
...     # Main editing pane (large, left side)
...     main_pane = window.active_pane
...
...     # Terminal pane (bottom)
...     terminal_pane = main_pane.split(size='30%')
...
...     # Logs pane (right side of terminal)
...     log_pane = terminal_pane.split(direction=PaneDirection.Right)
...
...     return {
...         'window': window,
...         'main': main_pane,
...         'terminal': terminal_pane,
...         'logs': log_pane,
...     }

>>> workspace = create_dev_workspace(session, 'my-project')
>>> len(workspace['window'].panes)
3

>>> # Clean up
>>> workspace['window'].kill()
```

--------------------------------

### Install libtmux developmental release via pipx

Source: https://libtmux.git-pull.com/quickstart.html

Command to install pre-release versions of libtmux using pipx with a suffix.

```bash
$ pipx install \
    --suffix=@next \
    --pip-args '\--pre' \
    --force \
    'libtmux'
```

--------------------------------

### Filter windows by contains and startswith

Source: https://libtmux.git-pull.com/topics/filtering.md

Creates windows with names like 'api-server' and 'web-frontend', then filters them using __contains and __startswith. The example includes cleanup with kill().

```python
>>> # Create windows for this example
>>> w1 = session.new_window(window_name="api-server")
>>> w2 = session.new_window(window_name="api-worker")
>>> w3 = session.new_window(window_name="web-frontend")

>>> # Windows containing 'api'
>>> api_windows = session.windows.filter(window_name__contains='api')
>>> len(api_windows) >= 2
True

>>> # Windows starting with 'web'
>>> web_windows = session.windows.filter(window_name__startswith='web')
>>> len(web_windows) >= 1
True

>>> # Clean up
>>> w1.kill()
>>> w2.kill()
>>> w3.kill()
```

--------------------------------

### Enter Python interactive shell

Source: https://libtmux.git-pull.com/quickstart.html

Starts a Python interactive shell to run libtmux commands.

```bash
$ python

```

--------------------------------

### Apply tmux layouts with libtmux select_layout

Source: https://libtmux.git-pull.com/topics/workspace_setup.md

Creates a window with multiple panes, applies the tiled, even-horizontal, and main-vertical layouts using select_layout, then kills the window. The example uses doctest ellipsis markers for expected output.

```python
>>> # Create window with multiple panes
>>> layout_window = session.new_window(window_name='layout-demo', attach=False)
>>> layout_window.resize(height=60, width=120)  # doctest: +ELLIPSIS
Window(@... ...)

>>> pane1 = layout_window.active_pane
>>> pane2 = layout_window.split()
>>> pane3 = layout_window.split()
>>> pane4 = layout_window.split()

>>> # Apply tiled layout
>>> layout_window.select_layout('tiled')  # doctest: +ELLIPSIS
Window(@... ...)

>>> # Apply even-horizontal layout
>>> layout_window.select_layout('even-horizontal')  # doctest: +ELLIPSIS
Window(@... ...)

>>> # Apply main-vertical layout
>>> layout_window.select_layout('main-vertical')  # doctest: +ELLIPSIS
Window(@... ...)

>>> # Clean up
>>> layout_window.kill()
```

--------------------------------

### Create a window with session.new_window

Source: https://libtmux.git-pull.com/topics/workspace_setup.md

Creates a new window in the session with the given name. The window is created in the background by default (attach=False) and is added to the session's window list. The example shows the returned Window object and verifies it is part of the session.

```python
>>> new_window = session.new_window(window_name='workspace')
>>> new_window  # doctest: +ELLIPSIS
Window(@... ...:workspace, Session($... ...))

>>> # Window is part of the session
>>> new_window in session.windows
True
```

--------------------------------

### Run commands in multiple panes with libtmux

Source: https://libtmux.git-pull.com/topics/workspace_setup.md

Defines a helper that sends different commands to each pane using send_keys. Because send_keys returns immediately and commands run asynchronously, the example sleeps briefly before capturing pane output with capture_pane to verify the commands ran. It also shows creating a window with three panes and cleaning up.

```python
>>> import time

>>> def run_in_panes(panes, commands):
...     """Run different commands in each pane."""
...     for pane, cmd in zip(panes, commands):
...         pane.send_keys(cmd)

>>> multi_window = session.new_window(window_name='multi-cmd', attach=False)
>>> multi_window.resize(height=40, width=120)  # doctest: +ELLIPSIS
Window(@... ...)

>>> pane_a = multi_window.active_pane
>>> pane_b = multi_window.split()
>>> pane_c = multi_window.split()

>>> run_in_panes(
...     [pane_a, pane_b, pane_c],
...     ['echo "Task A"', 'echo "Task B"', 'echo "Task C"'],
... )

>>> # Give commands time to execute
>>> time.sleep(0.2)

>>> # Verify all commands ran
>>> 'Task A' in '\n'.join(pane_a.capture_pane())
True

>>> # Clean up
>>> multi_window.kill()
```

--------------------------------

### Create a grid of panes with libtmux

Source: https://libtmux.git-pull.com/topics/workspace_setup.md

Defines a function that creates an NxM grid of panes by splitting a row across and repeating down, then applies the 'tiled' layout for even distribution. The example shows creating a 2x2 grid, verifying the pane count, and cleaning up by killing the window.

```python
>>> from libtmux.constants import PaneDirection

>>> def create_pane_grid(session, rows=2, cols=2, name='grid'):
...     """Create an NxM grid of panes."""
...     window = session.new_window(window_name=name, attach=False)
...     window.resize(height=50, width=160)
...
...     panes = []
...     base_pane = window.active_pane
...     panes.append(base_pane)
...
...     # Create first row of panes
...     current = base_pane
...     for _ in range(cols - 1):
...         new_pane = current.split(direction=PaneDirection.Right)
...         panes.append(new_pane)
...         current = new_pane
...
...     # Create additional rows
...     for _ in range(rows - 1):
...         row_start = panes[-cols]
...         current = row_start
...         for col in range(cols):
...             new_pane = panes[-cols + col].split(direction=PaneDirection.Below)
...             panes.append(new_pane)
...
...     # Apply tiled layout for even distribution
...     window.select_layout('tiled')
...     return window, panes

>>> grid_window, grid_panes = create_pane_grid(session, rows=2, cols=2, name='test-grid')
>>> len(grid_panes) >= 4
True

>>> # Clean up
>>> grid_window.kill()
```

--------------------------------

### Create temporary servers with custom configuration

Source: https://libtmux.git-pull.com/api/testing/pytest-plugin/usage.md

Shows how to initialize a Server with a custom configuration file path.

```python
>>> config_path = request.getfixturevalue("tmp_path") / "tmux.conf"
>>> _ = config_path.write_text("set -g status off")
>>> configured_server = Server(config_file=str(config_path))
>>> _ = configured_server.new_session()
>>> configured_server.is_alive()
True
>>> configured_server.kill()
```

--------------------------------

### Create and auto-kill a temporary window with session.new_window

Source: https://libtmux.git-pull.com/topics/workspace_setup.md

Use `with session.new_window(...) as temp_win` to create a window that is automatically killed when the block exits. The example sends a command to the active pane and verifies the window exists inside the block, then confirms it is removed after the block.

```python
>>> with session.new_window(window_name='temp-window') as temp_win:
...     pane = temp_win.active_pane
...     pane.send_keys('echo "temporary workspace"')
...     temp_win in session.windows
True

>>> # Window is automatically killed after exiting context
>>> temp_win not in session.windows
True
```

--------------------------------

### Get a global option with global_=True

Source: https://libtmux.git-pull.com/topics/options_and_hooks.md

Use global_=True to retrieve the server-wide default for an option, ignoring any session or window overrides. This example gets the global buffer-limit.

```python
>>> server.show_option('buffer-limit', global_=True)
50
```

--------------------------------

### Server.__init__()

Source: https://libtmux.git-pull.com/docs.json

Initializes a new Server instance. This constructor is part of the Server class and sets up the server connection.

```APIDOC
## Server.__init__()

### Description
Initializes a new Server instance. This constructor is part of the Server class and sets up the server connection.

### Method
__init__()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Get options with a specific scope

Source: https://libtmux.git-pull.com/topics/options_and_hooks.md

Pass the scope parameter to show_options to retrieve options from a different level than the object in hand. This example gets window-scoped options from a session.

```python
>>> from libtmux.constants import OptionScope

>>> # Get window-scoped options from a session
>>> session.show_options(scope=OptionScope.Window)  # doctest: +ELLIPSIS
{...}
```

--------------------------------

### Get active window with Session.active_window

Source: https://libtmux.git-pull.com/quickstart.html

Use Session.active_window to retrieve the current window object. This is the starting point for manipulating windows and panes.

```python
>>> window = session.active_window

```

--------------------------------

### Window.__init__()

Source: https://libtmux.git-pull.com/docs.json

Initializes a new Window object.

```APIDOC
## Window.__init__()

### Description
Initializes a new Window object.

### Method
__init__()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Access session and its windows

Source: https://libtmux.git-pull.com/topics/traversal.md

Demonstrates accessing the first session and listing its windows.

```python
>>> session = server.sessions[0]
>>> session  # doctest: +ELLIPSIS
Session($... ...)
```

```python
>>> session.windows  # doctest: +ELLIPSIS
[Window(@... ..., Session($... ...))]
```

--------------------------------

### show_options()

Source: https://libtmux.git-pull.com/docs.json

Displays all window options. This method retrieves the full list of window settings.

```APIDOC
## show_options()

### Description
Displays all window options.

### Method
show_options()
```

--------------------------------

### Window._show_options_dict()

Source: https://libtmux.git-pull.com/docs.json

Shows all window options as a dictionary.

```APIDOC
## Window._show_options_dict()

### Description
Shows all window options as a dictionary.

### Method
_show_options_dict()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Window._show_options()

Source: https://libtmux.git-pull.com/docs.json

Shows all window options.

```APIDOC
## Window._show_options()

### Description
Shows all window options.

### Method
_show_options()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Create a new window with raw command

Source: https://libtmux.git-pull.com/quickstart.html

Uses session.cmd('new-window', ...) to create a new window and prints its window ID. The output is 'libtmux...:2.0'.

```python
>>> session.cmd('new-window', '-P').stdout[0]
'libtmux...:2.0'

```

--------------------------------

### Get with default

Source: https://libtmux.git-pull.com/topics/traversal.md

Provide a default value to the get method to avoid raising an exception when no object matches the criteria.

```python
>>> # Returns None instead of raising ObjectDoesNotExist
>>> session.windows.get(window_name="nonexistent", default=None) is None
True
```

--------------------------------

### Show all options with show_options

Source: https://libtmux.git-pull.com/topics/options_and_hooks.md

Use session.show_options() to retrieve all options for a session. The output is a dictionary, as indicated by the ellipsis in the doctest.

```python
>>> session.show_options()  # doctest: +ELLIPSIS
{...}
```

--------------------------------

### Window.show_window_options()

Source: https://libtmux.git-pull.com/docs.json

Shows all window options for the window.

```APIDOC
## Window.show_window_options()

### Description
Shows all window options for the window.

### Method
show_window_options()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Get attached session with client.attached_session

Source: https://libtmux.git-pull.com/topics/clients.md

Use client.attached_session to get the live Session object the client is attached to. This performs a refresh and returns the current session, not a snapshot.

```python
>>> with control_mode() as ctl:
...     client = server.clients.get(client_name=ctl.client_name)
...     attached = client.attached_session
>>> attached is not None
True
```

--------------------------------

### Get a specific pane by ID

Source: https://libtmux.git-pull.com/topics/traversal.md

Use the get method to retrieve a single pane object by its ID. This method raises an exception if zero or more than one object is found.

```python
>>> window.panes.get(pane_id=pane.pane_id)  # doctest: +ELLIPSIS
Pane(%... Window(@... ..., Session($... ...)))
```

--------------------------------

### libtmux.Pane.__init__()

Source: https://libtmux.git-pull.com/docs.json

Initializes a new Pane instance. This method is part of the libtmux Pane class.

```APIDOC
## libtmux.Pane.__init__()

### Description
Initializes a new Pane instance.

### Method
__init__()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Get attached pane with client.attached_pane

Source: https://libtmux.git-pull.com/topics/clients.md

Use client.attached_pane to get the live Pane object the client is viewing. This chains through the attached session and active window, performing one refresh.

```python
>>> with control_mode() as ctl:
...     client = server.clients.get(client_name=ctl.client_name)
...     pane = client.attached_pane
>>> pane is None or pane.pane_id.startswith('%')
True
```

--------------------------------

### Window._show_options_raw()

Source: https://libtmux.git-pull.com/docs.json

Shows all window options in raw format.

```APIDOC
## Window._show_options_raw()

### Description
Shows all window options in raw format.

### Method
_show_options_raw()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Window.get_by_id()

Source: https://libtmux.git-pull.com/docs.json

Gets a window by its ID.

```APIDOC
## Window.get_by_id()

### Description
Gets a window by its ID.

### Method
get_by_id()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Session.get_by_id()

Source: https://libtmux.git-pull.com/docs.json

Gets a session by its ID.

```APIDOC
## Session.get_by_id()

### Description
Gets a session by its ID.

### Method
get_by_id()

### Parameters
- **session_id** (str) - Required - Session ID

### Returns
Session object
```

--------------------------------

### Window.get()

Source: https://libtmux.git-pull.com/docs.json

Gets a window attribute by key.

```APIDOC
## Window.get()

### Description
Gets a window attribute by key.

### Method
get()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Session.get()

Source: https://libtmux.git-pull.com/docs.json

Gets a session attribute by name.

```APIDOC
## Session.get()

### Description
Gets a session attribute by name.

### Method
get()

### Parameters
- **key** (str) - Required - Attribute name

### Returns
Attribute value
```

--------------------------------

### Get all sessions in the server

Source: https://libtmux.git-pull.com/topics/traversal.md

Retrieves a list of all sessions currently managed by the server.

```python
>>> server.sessions  # doctest: +ELLIPSIS
[Session($... ...)]
```

--------------------------------

### Get panes in a window

Source: https://libtmux.git-pull.com/topics/traversal.md

Retrieves a list of all panes contained within a specific window.

```python
>>> window.panes  # doctest: +ELLIPSIS
[Pane(%... Window(@... ..., Session($... ...)))]
```

--------------------------------

### OptionsMixin.show_options()

Source: https://libtmux.git-pull.com/docs.json

Shows all tmux options. This method is part of the OptionsMixin class in libtmux.options.

```APIDOC
## OptionsMixin.show_options()

### Description
Shows all tmux options. This method is part of the OptionsMixin class in libtmux.options.

### Method
show_options()

### Returns
A dictionary of option names and their values.
```

--------------------------------

### Launch ptpython shell

Source: https://libtmux.git-pull.com/quickstart.html

Starts the ptpython interactive shell, which offers enhanced commandline completion.

```bash
$ ptpython

```

--------------------------------

### Create a pane with raw command

Source: https://libtmux.git-pull.com/quickstart.html

Uses window.cmd('split-window', ...) to create a new pane and prints its pane ID. The output is '%2'.

```python
>>> window.cmd('split-window', '-P', '-F#{pane_id}').stdout[0]
'%2'

```

--------------------------------

### libtmux.Pane._show_options()

Source: https://libtmux.git-pull.com/docs.json

Shows all options for the pane. This method is part of the libtmux Pane class.

```APIDOC
## libtmux.Pane._show_options()

### Description
Shows all options for the pane.

### Method
_show_options()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Get active pane in a window

Source: https://libtmux.git-pull.com/topics/traversal.md

Retrieves the currently active pane within a specific window.

```python
>>> window.active_pane  # doctest: +ELLIPSIS
Pane(%... Window(@... ..., Session($... ...)))
```

--------------------------------

### Manage tmux objects

Source: https://libtmux.git-pull.com/index.md

Demonstrates creating a window, accessing its active pane, sending commands, and killing the window.

```python
>>> demo_window = session.new_window(window_name="my-project")
>>> demo_pane = demo_window.active_pane
>>> demo_pane.send_keys("echo hello")
>>> demo_window.kill()
```

--------------------------------

### Get all panes across all windows

Source: https://libtmux.git-pull.com/topics/traversal.md

Retrieves a list of all panes across every window in the server.

```python
>>> server.panes  # doctest: +ELLIPSIS
[Pane(%... Window(@... ..., Session($... ...)))]
```

--------------------------------

### Server.from_env()

Source: https://libtmux.git-pull.com/docs.json

Creates a Server instance from environment variables. This method is part of the Server class and allows constructing a server from the environment.

```APIDOC
## Server.from_env()

### Description
Creates a Server instance from environment variables. This method is part of the Server class and allows constructing a server from the environment.

### Method
from_env()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Get all windows across all sessions

Source: https://libtmux.git-pull.com/topics/traversal.md

Retrieves a list of all windows across every session in the server.

```python
>>> server.windows  # doctest: +ELLIPSIS
[Window(@... ..., Session($... ...))]
```

--------------------------------

### Window.buffer_sample

Source: https://libtmux.git-pull.com/docs.json

Property that returns the buffer sample.

```APIDOC
## Window.buffer_sample

### Description
Returns the buffer sample.

### Type
Property

### Returns
String.
```

--------------------------------

### Get pane information

Source: https://libtmux.git-pull.com/topics/pane_interaction.md

Retrieves pane-specific metadata such as the current working directory and the unique pane ID.

```python
>>> # Current working directory
>>> cwd = pane.display_message('#{pane_current_path}', get_text=True)
>>> isinstance(cwd, list)
True

>>> # Pane ID
>>> pane_id = pane.display_message('#{pane_id}', get_text=True)
>>> pane_id[0].startswith('%')
True
```

--------------------------------

### libtmux.Pane._show_options_dict()

Source: https://libtmux.git-pull.com/docs.json

Shows all options for the pane as a dictionary. This method is part of the libtmux Pane class.

```APIDOC
## libtmux.Pane._show_options_dict()

### Description
Shows all options for the pane as a dictionary.

### Method
_show_options_dict()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Get pane dimensions

Source: https://libtmux.git-pull.com/topics/pane_interaction.md

Retrieves the current width and height of a pane using display_message with the get_text=True parameter.

```python
>>> width = pane.display_message('#{pane_width}', get_text=True)
>>> isinstance(width, list) and len(width) > 0
True

>>> height = pane.display_message('#{pane_height}', get_text=True)
>>> isinstance(height, list) and len(height) > 0
True
```

--------------------------------

### Create temporary servers with TestServer

Source: https://libtmux.git-pull.com/api/testing/pytest-plugin/usage.md

Demonstrates using the Server class to create independent tmux servers that are automatically cleaned up.

```python
>>> temp_server = Server()
>>> temp_session = temp_server.new_session()
>>> temp_server.is_alive()
True
>>> temp_server.kill()
```

--------------------------------

### Rename and filter sessions by name

Source: https://libtmux.git-pull.com/quickstart.html

Demonstrates renaming a session and retrieving it using filter or get methods.

```python
>>> server.sessions[0].rename_session('foo')
Session($1 foo)

>>> server.sessions.filter(session_name="foo")[0]
Session($1 foo)

>>> server.sessions.get(session_name="foo")
Session($1 foo)
```

--------------------------------

### Override session_params fixture

Source: https://libtmux.git-pull.com/api/testing/pytest-plugin/usage.md

Example of overriding the session_params fixture to pass custom keyword arguments to Server.new_session().

```python
>>> import pytest
>>> @pytest.fixture
... def session_params() -> dict[str, int]:
...     return {"x": 800, "y": 600}
```

--------------------------------

### Server.command_prompt()

Source: https://libtmux.git-pull.com/docs.json

Opens a command prompt in the tmux server.

```APIDOC
## Server.command_prompt()

### Description
Opens a command prompt in the tmux server.

### Method
command_prompt()

### Parameters
None

### Returns
None.
```

--------------------------------

### Capture with line ranges

Source: https://libtmux.git-pull.com/topics/pane_interaction.md

Uses start and end parameters to define the range of lines to capture, including history.

```python
>>> # Capture last 5 lines of visible pane
>>> recent = pane.capture_pane(start=-5, end='-')
>>> isinstance(recent, list)
True

>>> # Capture from start of history to current
>>> full_history = pane.capture_pane(start='-', end='-')
>>> len(full_history) >= 0
True
```

--------------------------------

### Server.list_keys()

Source: https://libtmux.git-pull.com/docs.json

Lists all key bindings on the server. This method is part of the Server class and returns a list of key bindings.

```APIDOC
## Server.list_keys()

### Description
Lists all key bindings on the server. This method is part of the Server class and returns a list of key bindings.

### Method
list_keys()

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Server.list_keys()

Source: https://libtmux.git-pull.com/docs.json

Lists all key bindings in the tmux server.

```APIDOC
## Server.list_keys()

### Description
Lists all key bindings in the tmux server.

### Method
list_keys()

### Parameters
None

### Returns
List of key binding strings.
```

--------------------------------

### Get active window and pane in a session

Source: https://libtmux.git-pull.com/topics/traversal.md

Retrieves the currently active window and pane within a specific session.

```python
>>> session.active_window  # doctest: +ELLIPSIS
Window(@... ..., Session($... ...))

>>> session.active_pane  # doctest: +ELLIPSIS
Pane(%... Window(@... ..., Session($... ...)))
```

--------------------------------

### Pane.choose_client()

Source: https://libtmux.git-pull.com/docs.json

Chooses a client. This method opens a client selection prompt.

```APIDOC
## Pane.choose_client()

### Description
Chooses a client.

### Method
choose_client()

### Parameters
None

### Returns
None
```

--------------------------------

### Session.show_options()

Source: https://libtmux.git-pull.com/docs.json

Shows all session options. This method is part of the libtmux Session API.

```APIDOC
## Session.show_options()

### Description
Shows all session options for the tmux session.

### Method
show_options()

### Parameters
None

### Returns
- **options** (dict) - A dictionary of option names to values.
```

--------------------------------

### Iterate server.clients to find attached clients

Source: https://libtmux.git-pull.com/topics/clients.md

Iterate over server.clients to filter or find clients. This example collects clients matching a specific client_name.

```python
>>> with control_mode() as ctl:
...     attached = [
...         c
...         for c in server.clients
...         if c.client_name == ctl.client_name
...     ]
>>> bool(attached)
True
```

--------------------------------

### Create and kill a window by name

Source: https://libtmux.git-pull.com/quickstart.html

Creates a window and then kills it by referencing its name.

```python
>>> session.new_window(attach=False, window_name="ha in the bg")
Window(@2 ...:ha in the bg, Session($1 ...))

>>> session.kill_window('ha in the bg')
```
Tokens:
Raw