tmux-python · tony · Nov 9, 2025 · Nov 9, 2025 · Nov 9, 2025 · Nov 9, 2025
diff --git a/README.md b/README.md
diff --git a/conftest.py b/conftest.py
@@ -10,14 +10,17 @@
 
 from __future__ import annotations
 
+import asyncio
 import functools
 import shutil
 import typing as t
 
 import pytest
+import pytest_asyncio
 from _pytest.doctest import DoctestItem
 
 from libtmux._internal.control_mode import ControlMode
+from libtmux.common_async import get_version, tmux_cmd_async
 from libtmux.pane import Pane
 from libtmux.pytest_plugin import USING_ZSH
 from libtmux.server import Server
@@ -57,6 +60,11 @@ def add_doctest_fixtures(
         )
         doctest_namespace["monkeypatch"] = request.getfixturevalue("monkeypatch")
 
+        # Add async support for async doctests
+        doctest_namespace["asyncio"] = asyncio
+        doctest_namespace["tmux_cmd_async"] = tmux_cmd_async
+        doctest_namespace["get_version"] = get_version
+
 
 @pytest.fixture(autouse=True)
 def set_home(
@@ -82,3 +90,51 @@ def setup_session(
     """Session-level test configuration for pytest."""
     if USING_ZSH:
         request.getfixturevalue("zshrc")
+
+
+# Async test fixtures
+# These require pytest-asyncio to be installed
+
+
+@pytest_asyncio.fixture
+async def async_server(server: Server):
+    """Async wrapper for sync server fixture.
+
+    Provides async context while using proven sync server isolation.
+    Server has unique socket name from libtmux_test{random}.
+
+    The sync server fixture creates a Server with:
+    - Unique socket name: libtmux_test{8-random-chars}
+    - Automatic cleanup via request.addfinalizer
+    - Complete isolation from developer's tmux sessions
+
+    This wrapper just ensures we're in an async context.
+    All cleanup is handled by the parent sync fixture.
+    """
+    await asyncio.sleep(0)  # Ensure in async context
+    yield server
+    # Cleanup handled by sync fixture's finalizer
+
+
+@pytest_asyncio.fixture
+async def async_test_server(TestServer: t.Callable[..., Server]):
+    """Async wrapper for TestServer factory fixture.
+
+    Returns factory that creates servers with unique sockets.
+    Each call to factory() creates new isolated server.
+
+    The sync TestServer fixture creates a factory that:
+    - Generates unique socket names per call
+    - Tracks all created servers
+    - Cleans up all servers via request.addfinalizer
+
+    Usage in async tests:
+        server1 = async_test_server()  # Creates server with unique socket
+        server2 = async_test_server()  # Creates another with different socket
+
+    This wrapper just ensures we're in an async context.
+    All cleanup is handled by the parent sync fixture.
+    """
+    await asyncio.sleep(0)  # Ensure in async context
+    yield TestServer
+    # Cleanup handled by TestServer's finalizer
diff --git a/docs/index.md b/docs/index.md
@@ -1,110 +1,37 @@
-(index)=
-
-# libtmux
-
-Typed Python API for [tmux](https://github.com/tmux/tmux). Control
-servers, sessions, windows, and panes as Python objects.
-
-::::{grid} 1 1 3 3
-:gutter: 2 2 3 3
-
-:::{grid-item-card} Quickstart
-:link: quickstart
-:link-type: doc
-Install and make your first API call in 5 minutes.
-:::
-
-:::{grid-item-card} Topics
-:link: topics/index
-:link-type: doc
-Architecture, traversal, filtering, and automation patterns.
-:::
-
-:::{grid-item-card} API Reference
-:link: api/index
-:link-type: doc
-Every public class, function, and exception.
-:::
-
-:::{grid-item-card} Testing
-:link: api/testing/index
-:link-type: doc
-pytest plugin and test helpers for isolated tmux environments.
-:::
-
-:::{grid-item-card} Contributing
-:link: project/index
-:link-type: doc
-Development setup, code style, release process.
-:::
-
-::::
-
-## Install
-
-```console
-$ pip install libtmux
-```
-
-```console
-$ uv add libtmux
-```
+---
+hide-toc: true
+---
 
-Tip: libtmux is pre-1.0. Pin to a range: `libtmux>=0.55,<0.56`
-
-See [Quickstart](quickstart.md) for all methods and first steps.
-
-## At a glance
-
-```python
-import libtmux
+(index)=
 
-server = libtmux.Server()
-session = server.sessions.get(session_name="my-project")
-window = session.active_window
-pane = window.split()
-pane.send_keys("echo hello")
-```
+```{include} ../README.md
 
-```
-Server  →  Session  →  Window  →  Pane
 ```
 
-Every level of the [tmux hierarchy](topics/architecture.md) is a typed
-Python object with traversal, filtering, and command execution.
+## Table of Contents
 
-| Object | What it wraps |
-|--------|---------------|
-| {class}`~libtmux.server.Server` | tmux server / socket |
-| {class}`~libtmux.session.Session` | tmux session |
-| {class}`~libtmux.window.Window` | tmux window |
-| {class}`~libtmux.pane.Pane` | tmux pane |
-
-## Testing
+:hidden:
 
-libtmux ships a [pytest plugin](api/testing/pytest-plugin/index.md) with
-isolated tmux fixtures:
+```{toctree}
+:maxdepth: 2
 
-```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"
+quickstart
+quickstart_async
+about
+topics/index
+api/index
+pytest-plugin/index
+test-helpers/index
 ```
 
 ```{toctree}
+:caption: Project
 :hidden:
 
-quickstart
-topics/index
-api/index
-api/testing/index
+developing
 internals/index
-project/index
 history
 migration
 glossary
-MCP <https://libtmux-mcp.git-pull.com>
 GitHub <https://github.com/tmux-python/libtmux>
 ```
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -12,7 +12,7 @@ from inside a live tmux session.
 
 ## Requirements
 
-- [tmux] 3.2a or newer
+- [tmux]
 - [pip] - for this handbook's examples
 
 [tmux]: https://tmux.github.io/
@@ -44,15 +44,10 @@ the 4th beta release of `1.10.0` before general availability.
 - [pipx]\:
 
   ```console
-  $ pipx install \
-      --suffix=@next \
-      --pip-args '\--pre' \
-      --force \
-      'libtmux'
+  $ pipx install --suffix=@next 'libtmux' --pip-args '\--pre' --force
+  // Usage: libtmux@next [command]
   ```
 
-  Usage: `libtmux@next [command]`
-
 - [uv tool install][uv-tools]\:
 
   ```console
@@ -82,10 +77,7 @@ via trunk (can break easily):
 - [pipx]\:
 
   ```console
-  $ pipx install \
-      --suffix=@master \
-      --force \
-      'libtmux @ git+https://github.com/tmux-python/libtmux.git@master'
+  $ pipx install --suffix=@master 'libtmux @ git+https://github.com/tmux-python/libtmux.git@master' --force
   ```
 
 - [uv]\:
@@ -137,7 +129,7 @@ $ ptpython
 ```
 
 ```{module} libtmux
-:no-index:
+
 ```
 
 First, we can grab a {class}`Server`.
@@ -449,37 +441,23 @@ automatically sent, the leading space character prevents adding it to the user's
 shell history. Omitting `enter=false` means the default behavior (sending the
 command) is done, without needing to use `pane.enter()` after.
 
-## Working with options
+## Examples
 
-libtmux provides a unified API for managing tmux options across Server, Session,
-Window, and Pane objects.
+Want to see more? Check out our example scripts:
 
-### Getting options
+- **[examples/async_demo.py]** - Async command execution with performance benchmarks
+- **[examples/hybrid_async_demo.py]** - Both sync and async patterns working together
+- **[More examples]** - Full examples directory on GitHub
 
-```python
->>> server.show_option('buffer-limit')
-50
+For async-specific guides, see:
 
->>> window.show_options()  # doctest: +ELLIPSIS
-{...}
-```
-
-### Setting options
-
-```python
->>> window.set_option('automatic-rename', False)  # doctest: +ELLIPSIS
-Window(@... ...)
+- {doc}`/quickstart_async` - Async quickstart tutorial
+- {doc}`/topics/async_programming` - Comprehensive async guide
+- {doc}`/api/common_async` - Async API reference
 
->>> window.show_option('automatic-rename')
-False
-
->>> window.unset_option('automatic-rename')  # doctest: +ELLIPSIS
-Window(@... ...)
-```
-
-:::{seealso}
-See {ref}`options-and-hooks` for more details on options and hooks.
-:::
+[examples/async_demo.py]: https://github.com/tmux-python/libtmux/blob/master/examples/async_demo.py
+[examples/hybrid_async_demo.py]: https://github.com/tmux-python/libtmux/blob/master/examples/hybrid_async_demo.py
+[More examples]: https://github.com/tmux-python/libtmux/tree/master/examples
 
 ## Final notes
 
@@ -499,3 +477,4 @@ and our [test suite] (see {ref}`development`.)
 
 [workspacebuilder.py]: https://github.com/tmux-python/libtmux/blob/master/libtmux/workspacebuilder.py
 [test suite]: https://github.com/tmux-python/libtmux/tree/master/tests
+[ptpython]: https://github.com/prompt-toolkit/ptpython
diff --git a/docs/topics/index.md b/docs/topics/index.md
@@ -1,72 +1,14 @@
-# Topics
-
-Explore libtmux's core functionalities and underlying principles at a high level, while providing essential context and detailed explanations to help you understand its design and usage.
-
-::::{grid} 1 1 2 2
-:gutter: 2 2 3 3
-
-:::{grid-item-card} Architecture
-:link: architecture
-:link-type: doc
-Module hierarchy, data flow, and internal identifiers.
-:::
-
-:::{grid-item-card} Traversal
-:link: traversal
-:link-type: doc
-Navigate the Server, Session, Window, Pane hierarchy.
-:::
-
-:::{grid-item-card} Filtering
-:link: filtering
-:link-type: doc
-Query and filter collections by attributes.
-:::
-
-:::{grid-item-card} Pane Interaction
-:link: pane_interaction
-:link-type: doc
-Send keys, capture output, and interact with panes.
-:::
+---
+orphan: true
+---
 
-:::{grid-item-card} Workspace Setup
-:link: workspace_setup
-:link-type: doc
-Create sessions, windows, and panes programmatically.
-:::
-
-:::{grid-item-card} Automation Patterns
-:link: automation_patterns
-:link-type: doc
-Common patterns for scripting and automation.
-:::
-
-:::{grid-item-card} Context Managers
-:link: context_managers
-:link-type: doc
-Automatic cleanup with temporary sessions and windows.
-:::
-
-:::{grid-item-card} Options & Hooks
-:link: options_and_hooks
-:link-type: doc
-Get and set tmux options and hooks.
-:::
+# Topics
 
-::::
+Explore libtmux’s core functionalities and underlying principles at a high level, while providing essential context and detailed explanations to help you understand its design and usage.
 
 ```{toctree}
-:hidden:
 
-architecture
-configuration
-design-decisions
-public-vs-internal
-traversal
-filtering
-pane_interaction
-workspace_setup
-automation_patterns
+async_programming
 context_managers
-options_and_hooks
+traversal
 ```