### Install libtmux

Source: https://github.com/tmux-python/libtmux/blob/master/docs/api/testing/pytest-plugin/usage.md

Install the package using pip.

```console
$ pip install libtmux
```

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

### Format Code with Ruff

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/code-style.md

Use this command to format all code files according to the project's style guide. Ensure ruff is installed via uv.

```console
$ uv run ruff format .
```

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

### Regex filtering for window names

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md

Demonstrates using `__regex` for pattern matching on window names. This example finds windows matching a semantic version pattern. Includes setup and cleanup.

```python
>>> # Create versioned windows
>>> w1 = session.new_window(window_name="release-v1.0")
>>> w2 = session.new_window(window_name="release-v2.0")
>>> w3 = session.new_window(window_name="dev")

>>> # Match semantic version pattern
>>> session.windows.filter(window_name__regex=r'v\d+\.\d+')  # doctest: +ELLIPSIS
[Window(@... ...:release-v1.0, Session($... ...)), Window(@... ...:release-v2.0, Session($... ...))]

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

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

### Install development packages with uv

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Install all development dependencies, including extras, using the uv package manager.

```console
uv sync --all-extras --dev
```

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

### Start tmux and Python

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/automation_patterns.md

Basic commands to initialize a tmux session and start a Python interpreter.

```console
$ tmux
```

```console
$ python
```

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

### Install libtmux

Source: https://github.com/tmux-python/libtmux/blob/master/docs/index.md

Installation commands for common Python package managers.

```console
$ pip install libtmux
```

```console
$ uv add libtmux
```

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

### Install libtmux from main branch

Source: https://github.com/tmux-python/libtmux/blob/master/README.md

Install the bleeding-edge version of libtmux directly from its GitHub repository.

```console
pip install 'git+https://github.com/tmux-python/libtmux.git'
```

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

### Serve documentation with make

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Start an HTTP server to serve the project's documentation using the Makefile.

```console
make serve_docs
```

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

### Manually serve documentation

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Start an HTTP server to view the manually built documentation.

```console
make serve
```

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

### Start Python

Source: https://github.com/tmux-python/libtmux/blob/master/docs/api/libtmux.neo.md

Command to launch the Python interpreter.

```console
$ python
```

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

### Install libtmux dependencies

Source: https://github.com/tmux-python/libtmux/blob/master/AGENTS.md

Commands to install project dependencies using uv.

```bash
# Install dependencies
uv pip install --editable .
uv pip sync

# Install with development dependencies
uv pip install --editable . -G dev
```

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

### Set and Manage tmux Hooks with libtmux

Source: https://context7.com/tmux-python/libtmux/llms.txt

This example demonstrates how to set, get, and remove tmux hooks using libtmux. It covers setting single hooks, indexed hooks for multiple commands, and setting multiple hooks at once.

```python
import libtmux

server = libtmux.Server()
session = server.sessions[0]

# Set a hook
session.set_hook('session-renamed', 'display-message "Session was renamed!"')

# Get a single hook
hook_value = session.show_hook('session-renamed')
print(f"Hook value: {hook_value}")

# Get all hooks
all_hooks = session.show_hooks()
print(all_hooks)

# Remove a hook
session.unset_hook('session-renamed')

# Set indexed hooks (multiple commands for same event)
session.set_hook('after-split-window[0]', 'display-message "Split happened"')
session.set_hook('after-split-window[1]', 'run-shell "echo split >> /tmp/log"')

# Set multiple hooks at once
session.set_hooks('window-linked', {
    0: 'display-message "Window linked 0"',
    1: 'display-message "Window linked 1"',
})

# Clean up hooks
session.unset_hook('after-split-window[0]')
session.unset_hook('after-split-window[1]')

```

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

### Installing libtmux with pipx

Source: https://github.com/tmux-python/libtmux/blob/master/AGENTS.md

Install the libtmux package using pipx, with options for specifying a suffix, pip arguments, and forcing the installation.

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

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

### Start documentation preview server

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Build and serve the documentation locally using sphinx-autobuild. Run from the project's home directory.

```console
make start_docs
```

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

### Start documentation server from docs directory

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Build and serve the documentation locally using sphinx-autobuild. Run from the docs/ directory.

```console
make start
```

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

### Case-insensitive window name filtering

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md

Shows how to perform case-insensitive filtering using the `__istartswith` lookup suffix. This example finds windows starting with 'myapp', regardless of case. Includes setup and cleanup.

```python
>>> # Create windows with mixed case
>>> w1 = session.new_window(window_name="MyApp")
>>> w2 = session.new_window(window_name="myapp-worker")

>>> # Case-insensitive search
>>> session.windows.filter(window_name__istartswith='myapp')  # doctest: +ELLIPSIS
[Window(@... ...:MyApp, Session($... ...)), Window(@... ...:myapp-worker, Session($... ...))]

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

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

### Get all sessions

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/filtering.md

Retrieve all sessions on the server. This is a basic example of accessing a collection.

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

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

### Install Developmental libtmux Release

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Install pre-release versions of libtmux using pip for testing new features. Use --upgrade to ensure you get the latest pre-release.

```console
pip install --user --upgrade --pre libtmux
```

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

### Install Developmental libtmux Release with uvx

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Install pre-release versions of libtmux using uvx. The --prerelease allow flag allows the installation of pre-release versions.

```console
uvx --from 'libtmux' --prerelease allow python
```

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

### Install libtmux using pipx

Source: https://github.com/tmux-python/libtmux/blob/master/README.md

Install libtmux using pipx for isolated environments.

```console
pipx install libtmux
```

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

### Filter windows by name starting with a prefix

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md

Demonstrates using the `__startswith` lookup suffix with `filter()` to find windows whose names begin with a specified string. Includes setup and cleanup.

```python
>>> # Create windows to demonstrate filtering
>>> w1 = session.new_window(window_name="app-frontend")
>>> w2 = session.new_window(window_name="app-backend")
>>> w3 = session.new_window(window_name="logs")

>>> # Find windows starting with 'app-'
>>> session.windows.filter(window_name__startswith='app-')  # doctest: +ELLIPSIS
[Window(@... ...:app-frontend, Session($... ...)), Window(@... ...:app-backend, Session($... ...))]

>>> # Find windows containing 'end'
>>> session.windows.filter(window_name__contains='end')  # doctest: +ELLIPSIS
[Window(@... ...:app-frontend, Session($... ...)), Window(@... ...:app-backend, Session($... ...))]

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

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

### Install Developmental libtmux Release with uv tool

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Install pre-release versions of libtmux using the uv tool. The --prerelease=allow flag enables the installation of pre-release versions.

```console
uv tool install --prerelease=allow libtmux
```

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

### Install libtmux from Git Repository with uv tool

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Install libtmux from its Git repository using the uv tool. This command fetches the latest code from the master branch.

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

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

### Install libtmux from Git Repository Master with pipx

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Install the master branch of libtmux using pipx. The --suffix=@master and --force flags are used to specify the branch and overwrite existing installations.

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

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

### Start long-running processes

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/automation_patterns.md

Demonstrates creating a new window and sending commands to a pane to execute background tasks.

```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()
```

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

### Start tmux

Source: https://github.com/tmux-python/libtmux/blob/master/docs/api/libtmux.neo.md

Command to initiate a tmux session in a terminal.

```console
$ tmux
```

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

### Install libtmux from Git Repository (Editable)

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Install libtmux in editable mode directly from its Git repository using pip. This is useful for development.

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

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

### Get All Window Options

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Display all tmux options for a given window. This can be used to inspect the current settings of a window.

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

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

### Documentation Command Execution

Source: https://github.com/tmux-python/libtmux/blob/master/CLAUDE.md

Use the console language tag and prefix commands with $ for interactive examples. Keep each code block limited to a single logical command.

```console
$ uv run pytest
```

```console
$ uv run pytest --cov
```

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

### Install Developmental libtmux Release with pipx

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Install pre-release versions of libtmux using pipx. The --suffix=@next and --pip-args '\--pre' flags are used to specify pre-release versions.

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

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

### Window Context Manager Example

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md

Employ the Window context manager for temporary windows that are automatically killed upon exiting the 'with' statement. Useful for managing temporary window states.

```python
>>> server = Server()
>>> session = server.new_session()
>>> with session.new_window() as window:
...     print(window in session.windows)
...     pane = window.split()
True
>>> print(window in session.windows)  # Window is killed after exiting context
False
```

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

### Testing with server and session fixtures

Source: https://github.com/tmux-python/libtmux/blob/master/docs/api/testing/pytest-plugin/fixtures.md

Examples of using the server and session fixtures to interact with tmux objects.

```python
def test_server_sessions(server: Server) -> None:
    session = server.new_session(session_name="work")
    assert session.session_name == "work"
```

```python
def test_session_windows(session: Session) -> None:
    window = session.new_window(window_name="editor")
    assert window.window_name == "editor"
```

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

### Filter windows by name starting with 'web'

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/filtering.md

Find windows whose names start with the prefix 'web'. This uses the `startswith` lookup.

```python
>>> # 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()
```

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

### Start a tmux session

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Starts a new tmux session named 'foo' with a window named 'bar'. The '-n' flag sets the window name, and '-s' sets the session name.

```console
tmux new-session -n bar -s foo
```

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

### Running Tests with uv

Source: https://github.com/tmux-python/libtmux/blob/master/AGENTS.md

Use the `uv run` command to execute tests. This example shows how to run pytest.

```console
$ uv run pytest
```

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

### Get a non-existent window with a default value

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/filtering.md

Attempt to retrieve a window that does not exist, providing a default value to prevent exceptions. The `get()` method returns the default value if no match is found.

```python
>>> session.windows.get(window_name="nonexistent", default=None) is None
True
```

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

### Get all windows across all sessions

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md

Retrieve a list of all windows from all active sessions using `server.windows`.

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

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

### Manage tmux Options with libtmux

Source: https://context7.com/tmux-python/libtmux/llms.txt

This snippet shows how to get and set tmux options across Server, Session, Window, and Pane objects using libtmux. It covers getting all options, single options, global options, setting, unsetting, and retrieving options from different scopes.

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

server = libtmux.Server()
session = server.sessions[0]
window = session.active_window

# Get all options
all_options = session.show_options()
print(all_options)

# Get a single option
buffer_limit = server.show_option('buffer-limit')
print(f"Buffer limit: {buffer_limit}")

# Get global options
global_status = server.show_option('status', global_=True)

# Set options
window.set_option('automatic-rename', False)
session.set_option('status-interval', 5)

# Unset option (revert to default)
window.unset_option('automatic-rename')

# Get options from different scopes
window_opts = session.show_options(scope=OptionScope.Window)
pane_opts = session.show_options(scope=OptionScope.Pane)

# Verify option was set
auto_rename = window.show_option('automatic-rename')
print(f"automatic-rename: {auto_rename}")
```

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

### Add libtmux with Prerelease Support using uv

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Add libtmux to your project with support for pre-release versions using the uv command. The --prerelease allow flag enables pre-release installations.

```console
uv add libtmux --prerelease allow
```

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

### Filter windows by multiple conditions (AND)

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/filtering.md

Filter windows that simultaneously start with 'feature' and end with 'signup'. This demonstrates combining conditions within a single `filter()` call.

```python
>>> # Create windows for this example
>>> w1 = session.new_window(window_name="feature-login")
>>> w2 = session.new_window(window_name="feature-signup")
>>> w3 = session.new_window(window_name="bugfix-typo")

>>> # Multiple conditions in one filter (AND)
>>> session.windows.filter(
...     window_name__startswith='feature',
...     window_name__endswith='signup'
... )  # doctest: +ELLIPSIS
[Window(@... ...:feature-signup, Session($... ...))]
```

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

### NumPy Docstring Style Example

Source: https://github.com/tmux-python/libtmux/blob/master/AGENTS.md

Illustrates the required NumPy docstring format for functions and methods, including parameters and return values.

```python
"""Short description of the function or class.

Detailed description using reStructuredText format.

Parameters
----------
param1 : type
    Description of param1
param2 : type
    Description of param2

Returns
-------
type
    Description of return value
"""
```

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

### Example Git Commit Message

Source: https://github.com/tmux-python/libtmux/blob/master/AGENTS.md

Follow this format for commit messages, including scope, type, a concise description, and detailed explanations for 'why' and 'what'.

```git
Pane(feat[send_keys]): Add support for literal flag

why: Enable sending literal characters without tmux interpretation
what:
- Add literal parameter to send_keys method
- Update send_keys to pass -l flag when literal=True
- Add tests for literal key sending
```

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

### Check Code with Ruff

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/code-style.md

Run this command to lint the codebase and automatically fix any style violations. Ensure ruff is installed via uv.

```console
$ uv run ruff check . --fix --show-fixes
```

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

### Get pane ID

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/pane_interaction.md

Fetches the unique identifier for the pane. The ID is returned as the first element in a list and starts with '%'.

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

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

### Build and serve documentation

Source: https://github.com/tmux-python/libtmux/blob/master/AGENTS.md

Commands for managing project documentation.

```bash
# Build documentation
just build-docs

# Start documentation server with auto-reload
just start-docs

# Update documentation CSS/JS
just design-docs
```

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

### Pane Context Manager Example

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md

Use the Pane context manager to create temporary panes that are automatically killed when the 'with' block finishes. Ideal for isolated pane operations.

```python
>>> server = Server()
>>> session = server.new_session()
>>> window = session.new_window()
>>> with window.split() as pane:
...     print(pane in window.panes)
...     pane.send_keys('echo "Hello"')
True
>>> print(pane in window.panes)  # Pane is killed after exiting context
False
```

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

### Build documentation with make

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Build the project's documentation using the Makefile.

```console
make build_docs
```

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

### Server Context Manager Example

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md

Use the Server context manager to create a temporary tmux server that is automatically killed upon exiting the 'with' block. This is useful for isolated testing.

```python
>>> with Server() as server:
...     session = server.new_session()
...     print(server.is_alive())
True
>>> print(server.is_alive())  # Server is killed after exiting context
False
```

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

### Develop documentation and run server

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Rebuild documentation and run the server automatically on file changes. Requires entr(1) and GNU Make with -J support.

```console
make dev_docs
```

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

### Session Context Manager Example

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md

Utilize the Session context manager to create a temporary tmux session that is automatically killed when the 'with' block is exited. Ensures session cleanup.

```python
>>> server = Server()
>>> with server.new_session() as session:
...     print(session in server.sessions)
...     window = session.new_window()
True
>>> print(session in server.sessions)  # Session is killed after exiting context
False
```

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

### Manually build HTML documentation

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Build the HTML documentation from the docs/ directory.

```console
cd docs/ && make html
```

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

### Type Checking with Mypy

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/code-style.md

Execute this command to perform strict type checking on the project's source and test files using mypy. Ensure mypy is installed via uv.

```console
$ uv run mypy
```

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

### Initialize Server

Source: https://github.com/tmux-python/libtmux/blob/master/docs/api/libtmux.neo.md

Create a Server object to interact with the tmux instance.

```python
>>> import libtmux
>>> t = libtmux.Server()
>>> t
```

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

### Create Development Workspace Layout

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/workspace_setup.md

A recipe for setting up a common development environment with a main editing pane, a terminal pane, and a logs pane. Requires libtmux.constants.PaneDirection.

```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()
```

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

### Lint and check code with ruff (manual)

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Run ruff for linting, formatting, and import sorting if not using uv.

```console
ruff check .
```

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

### Get windows in a session

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md

Access the `session.windows` attribute to get a list of all windows within a specific session.

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

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

### Get all panes across all windows

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md

Access `server.panes` to get a list of all panes from all windows across all sessions.

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

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

### Get active pane in a window

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md

Access the `window.active_pane` attribute to get the currently active pane within a window.

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

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

### Get a specific pane by ID

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md

Use the `get()` method on a collection of panes to retrieve a single pane that matches the provided `pane_id`.

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

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

### Test Window Renaming with Fixture

Source: https://github.com/tmux-python/libtmux/blob/master/AGENTS.md

Demonstrates how to use the 'window' fixture to test window renaming functionality. The fixture provides a pre-configured Window instance.

```python
def test_window_rename(window):
    """Test renaming a window."""
    # window is already a Window instance with a live tmux window
    window.rename_window('new_name')
    assert window.window_name == 'new_name'
```

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

### Lint and check code with ruff (uv)

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Run ruff for linting, formatting, and import sorting using uv.

```console
uv run ruff
```

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

### Split Pane with Environment Variables

Source: https://context7.com/tmux-python/libtmux/llms.txt

Demonstrates creating a new pane with specific environment variables defined.

```python
pane = window.split(environment={'DEBUG': '1', 'ENV': 'development'})

print(f"Created pane: {pane.pane_id}")
print(f"Pane position: at_left={pane.at_left}, at_right={pane.at_right}")
```

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

### Get a single window by ID

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/filtering.md

Retrieve a single window using its unique ID. This uses the `get()` method, which raises an exception if zero or multiple matches are found.

```python
>>> window = session.windows.get(window_id=session.active_window.window_id)
>>> window  # doctest: +ELLIPSIS
Window(@... ..., Session($... ...))
```

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

### Connect to a tmux server

Source: https://github.com/tmux-python/libtmux/blob/master/README.md

Import the Server class from libtmux and instantiate it to connect to the default tmux server.

```python
import libtmux
svr = libtmux.Server()
svr
```

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

### Navigate to the libtmux directory

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Change the current directory to the cloned libtmux repository.

```console
cd libtmux
```

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

### Automatic Resource Cleanup with Context Managers

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/automation_patterns.md

Shows how to use context managers with libtmux to ensure automatic cleanup of resources like windows, even if exceptions occur during the work block.

```python
# Context managers ensure cleanup even on exceptions
with session.new_window(window_name='safe-work') as safe_window:
    pane = safe_window.active_pane
    # Work happens here
    pass  # Even if exception occurs, window is cleaned up
```

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

### Get the first session

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md

Retrieve the first session from the `server.sessions` list.

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

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

### Overriding session parameters

Source: https://github.com/tmux-python/libtmux/blob/master/docs/api/testing/pytest-plugin/fixtures.md

Example of overriding the session_params fixture in a conftest.py file.

```python
# conftest.py
@pytest.fixture
def session_params() -> dict:
    return {"x": 800, "y": 600}
```

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

### Tag a Release

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/releasing.md

Use this command to create a git tag for a new release.

```console
git tag v<version>
```

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

### Format code with make

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Format code using ruff format via the Makefile.

```console
make ruff_format
```

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

### Retrieve and Rename tmux Sessions

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Demonstrates how to rename a session and retrieve 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)
```

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

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

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

### Get panes in a window

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md

Retrieve a list of all panes within a specific window using the `window.panes` attribute.

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

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

### Test with pytest

Source: https://github.com/tmux-python/libtmux/blob/master/docs/index.md

Example of using the libtmux pytest plugin to manage isolated tmux sessions during testing.

```python
def test_my_tool(session):
    window = session.new_window(window_name="test")
    pane = window.active_pane
    pane.send_keys("echo hello")
    assert window.window_name == "test"
```

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

### Run tests with make

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

A convenience command to run tests using the Makefile.

```console
make test
```

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

### Nested Context Managers for Resource Management

Source: https://context7.com/tmux-python/libtmux/llms.txt

Demonstrates nested context managers for managing Server, Session, Window, and Pane resources. All resources are cleaned up automatically in reverse order of creation.

```python
with Server(socket_name='isolated') as server:
    with server.new_session() as session:
        with session.new_window() as window:
            with window.split() as pane:
                pane.send_keys('echo "Hello"')
                # All resources cleaned up in reverse order
```

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

### Get Tmux Option

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Retrieve the value of a specific tmux option for the server. This is useful for checking current configurations.

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

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

### Import libtmux

Source: https://github.com/tmux-python/libtmux/blob/master/docs/api/libtmux.neo.md

Initial import statement for the libtmux library.

```python
>>> import libtmux
```

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

### Get pane current working directory

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/pane_interaction.md

Retrieves the current working directory of the pane. The result is returned as a list.

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

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

### List all tmux sessions

Source: https://github.com/tmux-python/libtmux/blob/master/README.md

Access the 'sessions' attribute of a Server object to get a list of all active Session objects.

```python
server.sessions
```

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

### Case-insensitive startswith filtering

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/filtering.md

Find windows whose names start with 'myapp', ignoring case. This uses the `istartswith` lookup.

```python
>>> # Case-insensitive startswith
>>> session.windows.filter(window_name__istartswith='myapp')  # doctest: +ELLIPSIS
[Window(@... ...:MyApp-Server, Session($... ...)), Window(@... ...:myapp-worker, Session($... ...))]

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

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

### Basic libtmux fixture usage

Source: https://github.com/tmux-python/libtmux/blob/master/docs/api/testing/pytest-plugin/fixtures.md

Demonstrates injecting server and session fixtures into test functions.

```python
def test_basic(server: Server) -> None:
    session = server.new_session(session_name="my-session")
    assert session is not None


def test_with_session(session: Session) -> None:
    window = session.new_window(window_name="test")
    assert window is not None
```

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

### Lint and check code with make

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/contributing.md

Run ruff linting and checks using the Makefile.

```console
make ruff
```

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

### Kill a specific pane

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/pane_interaction.md

Destroys a given pane. This is a destructive operation. Example shows creating a temporary pane and then killing it.

```python
# Create a temporary pane
temp_pane = pane.split()
temp_pane in window.panes

# Kill it
temp_pane.kill()
temp_pane not in window.panes
```

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

### Create new windows

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/workspace_setup.md

Methods for creating windows within a session, including background creation and custom shell execution.

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

```python
>>> background_window = session.new_window(
...     window_name='background-task',
...     attach=False,
... )
>>> background_window  # doctest: +ELLIPSIS
Window(@... ...:background-task, Session($... ...))

>>> # Clean up
>>> background_window.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()
```

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

### Using tmux Format Strings

Source: https://github.com/tmux-python/libtmux/blob/master/AGENTS.md

Demonstrates the syntax for tmux format strings, which are used to query object state like session_id, window_id, and pane_id.

```text
# Format: "#{format_name}" (e.g., "#{session_id}", "#{window_name}")
```

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

### Get active window and pane in a session

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/traversal.md

Retrieve the currently active window and pane within a session using `session.active_window` and `session.active_pane`.

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

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

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

### Get the first tmux session

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Accesses the first session from the list of active tmux sessions. Note that the order might not be guaranteed.

```python
server.sessions[0]
```

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

### Nested Context Managers for Hierarchical Cleanup

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/context_managers.md

Demonstrates nesting context managers for Server, Session, Window, and Pane to ensure automatic, hierarchical cleanup in reverse order of creation. This guarantees all resources are properly released.

```python
>>> with Server() as server:
...     with server.new_session() as session:
...         with session.new_window() as window:
...             with window.split() as pane:
...                 pane.send_keys('echo "Hello"')
...                 # Do work with the pane
...                 # Everything is cleaned up automatically when exiting contexts
```

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

### Arrange panes with window layouts

Source: https://context7.com/tmux-python/libtmux/llms.txt

Apply predefined tmux layouts and resize panes or windows programmatically.

```python
import libtmux

server = libtmux.Server()
session = server.sessions[0]
window = session.new_window(window_name='layout-demo')

# Create multiple panes
pane1 = window.active_pane
pane2 = window.split()
pane3 = window.split()
pane4 = window.split()

# Apply layout
window.select_layout('tiled')           # Even grid
window.select_layout('even-horizontal') # Side by side
window.select_layout('even-vertical')   # Stacked
window.select_layout('main-horizontal') # Large top, small bottom row
window.select_layout('main-vertical')   # Large left, small right column

# Resize window
window.resize(height=50, width=200)

# Resize pane
pane1.resize(height=20)
pane1.resize(width=80)
pane1.resize(height='50%')  # Percentage

# Directional resize
from libtmux.constants import ResizeAdjustmentDirection
pane1.resize(
    adjustment_direction=ResizeAdjustmentDirection.Up,
    adjustment=5
)

# Zoom pane (toggle fullscreen)
pane1.resize(zoom=True)

# Helper methods
pane1.set_width(100)
pane1.set_height(30)
```

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

### Initialize libtmux Server

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Initializes a Server object to interact with the tmux server. This is the entry point for controlling tmux via libtmux.

```python
import libtmux
server = libtmux.Server()
server
```

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

### Get pane height

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/pane_interaction.md

Queries the current height of a pane using tmux format variables. Returns a list containing the height as a string.

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

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

### Import Core Library Modules

Source: https://github.com/tmux-python/libtmux/blob/master/docs/project/public-api.md

Standard import paths for accessing core libtmux components.

```python
from libtmux.server import Server
```

```python
from libtmux.session import Session
```

```python
from libtmux.window import Window
```

```python
from libtmux.pane import Pane
```

```python
from libtmux.common import ...
```

```python
from libtmux.neo import ...
```

```python
from libtmux.options import ...
```

```python
from libtmux.hooks import ...
```

```python
from libtmux.constants import ...
```

```python
from libtmux.exc import ...
```

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

### Get pane width

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/pane_interaction.md

Queries the current width of a pane using tmux format variables. Returns a list containing the width as a string.

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

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

### Get a specific tmux session by ID

Source: https://github.com/tmux-python/libtmux/blob/master/README.md

Use the .get() method on the sessions list to retrieve a specific Session object using its session_id.

```python
server.sessions.get(session_id=session.session_id)
```

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

### Retrieve tmux options

Source: https://github.com/tmux-python/libtmux/blob/master/docs/topics/options_and_hooks.md

Use show_options to retrieve all options or show_option for a specific key.

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

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

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

### Get a specific tmux window by name

Source: https://github.com/tmux-python/libtmux/blob/master/README.md

Use the .get() method on the windows list to retrieve a specific Window object based on a name pattern.

```python
session.windows.get(window_name__startswith="bg")
```

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

### Execute Raw tmux Commands with libtmux

Source: https://context7.com/tmux-python/libtmux/llms.txt

This snippet illustrates how to execute any raw tmux command using the `.cmd()` method available on libtmux objects. It shows server-level, session-level, window-level, and pane-level commands, including creating new sessions/windows/panes and converting raw output to libtmux objects.

```python
import libtmux
from libtmux import Window, Pane

server = libtmux.Server()
session = server.sessions[0]
window = session.active_window
pane = window.active_pane

# Server-level command
result = server.cmd('display-message', 'Hello from server')
print(f"Return code: {result.returncode}")
print(f"Stdout: {result.stdout}")
print(f"Stderr: {result.stderr}")

# Create session with raw command
result = server.cmd('new-session', '-d', '-P', '-F#{session_id}')
new_session_id = result.stdout[0]
print(f"Created session: {new_session_id}")

# Session-level command (automatically targets session)
result = session.cmd('new-window', '-P', '-F#{window_id}')
new_window_id = result.stdout[0]

# Window-level command (automatically targets window)
result = window.cmd('split-window', '-P', '-F#{pane_id}')
new_pane_id = result.stdout[0]

# Convert raw output to objects
new_window = Window.from_window_id(server=server, window_id=new_window_id)
new_pane = Pane.from_pane_id(server=server, pane_id=new_pane_id)

# Pane-level command with custom target
pane.cmd('select-pane', target=f'{session.session_id}:{window.window_index}.0')
```

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

### Filter tmux windows by name

Source: https://github.com/tmux-python/libtmux/blob/master/README.md

Access the 'windows' attribute of a Session object and use .filter() to find windows whose names start with a specific prefix.

```python
session.windows.filter(window_name__startswith="bg")
```

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

### Get tmux session by ID

Source: https://github.com/tmux-python/libtmux/blob/master/docs/quickstart.md

Retrieves a specific tmux session object using its unique ID. This is a convenient way to access a session when its ID is known.

```python
server.get_by_id('$<yourId>')
```