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/docs/api/async.md b/docs/api/async.md
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -4,166 +4,15 @@
 
 # API Reference
 
-libtmux's public API mirrors tmux's object hierarchy:
-`Server` → `Session` → `Window` → `Pane`
-
-## What do you want to do?
-
-::::{grid} 1 2 2 2
-:gutter: 2
-
-:::{grid-item-card} Find a session, window, or pane?
-:link: libtmux.server
-:link-type: doc
-Use `server.sessions.get()`, `session.windows.get()`.
-:::
-
-:::{grid-item-card} Send commands or keys to a terminal?
-:link: libtmux.pane
-:link-type: doc
-Use `pane.send_keys()` and `pane.enter()`.
-:::
-
-:::{grid-item-card} Capture output from a pane?
-:link: libtmux.pane
-:link-type: doc
-Use `pane.capture_pane()`.
-:::
-
-:::{grid-item-card} Write tests against tmux?
-:link: testing/index
-:link-type: doc
-Use the pytest plugin and test helpers.
-:::
-
-::::
-
-## Core Objects
-
-::::{grid} 1 1 2 2
-:gutter: 2 2 3 3
-
-:::{grid-item-card} Server
-:link: libtmux.server
-:link-type: doc
-Entry point. Manages sessions and executes raw tmux commands.
-:::
-
-:::{grid-item-card} Session
-:link: libtmux.session
-:link-type: doc
-Manages windows within a tmux session.
-:::
-
-:::{grid-item-card} Window
-:link: libtmux.window
-:link-type: doc
-Manages panes, layouts, and window operations.
-:::
-
-:::{grid-item-card} Pane
-:link: libtmux.pane
-:link-type: doc
-Terminal instance. Send keys and capture output.
-:::
-
-::::
-
-## Supporting Modules
-
-::::{grid} 1 2 3 3
-:gutter: 2 2 3 3
-
-:::{grid-item-card} Common
-:link: libtmux.common
-:link-type: doc
-Base classes and command execution.
-:::
-
-:::{grid-item-card} Neo
-:link: libtmux.neo
-:link-type: doc
-Dataclass-based query interface.
-:::
-
-:::{grid-item-card} Options
-:link: libtmux.options
-:link-type: doc
-tmux option get/set.
-:::
-
-:::{grid-item-card} Hooks
-:link: libtmux.hooks
-:link-type: doc
-tmux hook management.
-:::
-
-:::{grid-item-card} Constants
-:link: libtmux.constants
-:link-type: doc
-Format strings and constants.
-:::
-
-:::{grid-item-card} Exceptions
-:link: libtmux.exc
-:link-type: doc
-Exception hierarchy.
-:::
-
-::::
-
-## Testing
-
-::::{grid} 1 1 1 1
-:gutter: 2
-
-:::{grid-item-card} Testing Utilities
-:link: testing/index
-:link-type: doc
-pytest plugin, fixtures, and test helpers for testing code that uses libtmux.
-:::
-
-::::
-
-## API Policy and Guarantees
-
-These documents define the project's promises about the public API.
-
-::::{grid} 1 2 3 3
-:gutter: 2
-
-:::{grid-item-card} Public API
-:link: ../project/public-api
-:link-type: doc
-What is and is not considered stable public API.
-:::
-
-:::{grid-item-card} Compatibility
-:link: ../project/compatibility
-:link-type: doc
-Supported versions of Python and tmux.
-:::
-
-:::{grid-item-card} Deprecations
-:link: ../project/deprecations
-:link-type: doc
-Active deprecations and migration guidance.
-:::
-
-::::
-
 ```{toctree}
-:hidden:
-:maxdepth: 1
 
-Server <libtmux.server>
-Session <libtmux.session>
-Window <libtmux.window>
-Pane <libtmux.pane>
-Common <libtmux.common>
-Neo <libtmux.neo>
-Options <libtmux.options>
-Hooks <libtmux.hooks>
-Constants <libtmux.constants>
-Exceptions <libtmux.exc>
+properties
+servers
+sessions
+windows
+panes
+async
+constants
+common
+exceptions
 ```
diff --git a/docs/api/libtmux.server.md b/docs/api/libtmux.server.md
@@ -9,6 +9,17 @@
 
 tmux initializes a server automatically on first running (e.g. executing `tmux`)
 
+## Async Methods
+
+Server provides async versions of key methods for use in async applications:
+
+- {meth}`~Server.ahas_session` - Check if session exists asynchronously
+- {meth}`~Server.anew_session` - Create new session asynchronously
+
+See {ref}`async` for comprehensive async documentation.
+
+## API Reference
+
 ```{eval-rst}
 .. autoclass:: libtmux.Server
     :members:

diff --git a/docs/api/libtmux.session.md b/docs/api/libtmux.session.md
@@ -6,6 +6,17 @@
 - Contain {ref}`Windows` (which contain {ref}`Panes`)
 - Identified by `$`, e.g. `$313`
 
+## Async Methods
+
+Session provides async versions of key methods for use in async applications:
+
+- {meth}`~Session.anew_window` - Create new window asynchronously
+- {meth}`~Session.arename_session` - Rename session asynchronously
+
+See {ref}`async` for comprehensive async documentation.
+
+## API Reference
+
 ```{eval-rst}
 .. autoclass:: libtmux.Session
     :members:

diff --git a/docs/api/libtmux.window.md b/docs/api/libtmux.window.md
@@ -6,6 +6,16 @@
 - Contain {ref}`Panes`
 - Identified by `@`, e.g. `@313`
 
+## Async Methods
+
+Window provides async versions of key methods for use in async applications:
+
+- {meth}`~Window.akill` - Kill window asynchronously
+
+See {ref}`async` for comprehensive async documentation.
+
+## API Reference
+
 ```{module} libtmux
 :no-index:
 ```

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,85 @@ 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
+## Async Support
 
-libtmux provides a unified API for managing tmux options across Server, Session,
-Window, and Pane objects.
+For async applications, libtmux provides async versions of key methods using the 'a' prefix naming convention.
 
-### Getting options
+### Basic Async Usage
 
 ```python
->>> server.show_option('buffer-limit')
-50
+import asyncio
+from libtmux import Server
 
->>> window.show_options()  # doctest: +ELLIPSIS
-{...}
-```
+async def main():
+    server = Server()
 
-### Setting options
+    # Create session asynchronously
+    session = await server.anew_session(session_name="async_demo")
 
-```python
->>> window.set_option('automatic-rename', False)  # doctest: +ELLIPSIS
-Window(@... ...)
+    # Create window asynchronously
+    window = await session.anew_window(window_name="async_window")
 
->>> window.show_option('automatic-rename')
-False
+    # Check session exists
+    exists = await server.ahas_session("async_demo")
+    print(f"Session exists: {exists}")  # True
 
->>> window.unset_option('automatic-rename')  # doctest: +ELLIPSIS
-Window(@... ...)
+asyncio.run(main())
 ```
 
-:::{seealso}
-See {ref}`options-and-hooks` for more details on options and hooks.
-:::
+### Concurrent Operations
+
+One of the key benefits of async methods is concurrent execution:
+
+```python
+import asyncio
+
+async def setup_workspace():
+    server = Server()
+
+    # Create multiple sessions concurrently
+    frontend, backend, database = await asyncio.gather(
+        server.anew_session(
+            session_name="frontend",
+            start_directory="~/project/frontend"
+        ),
+        server.anew_session(
+            session_name="backend",
+            start_directory="~/project/backend"
+        ),
+        server.anew_session(
+            session_name="database",
+            start_directory="~/project/database"
+        ),
+    )
+
+    # Set up windows in each session concurrently
+    await asyncio.gather(
+        frontend.anew_window(window_name="editor"),
+        frontend.anew_window(window_name="server"),
+        backend.anew_window(window_name="api"),
+        backend.anew_window(window_name="tests"),
+    )
+
+    return frontend, backend, database
+```
+
+### Available Async Methods
+
+- {meth}`Server.ahas_session` - Check if session exists
+- {meth}`Server.anew_session` - Create new session
+- {meth}`Session.anew_window` - Create new window
+- {meth}`Session.arename_session` - Rename session
+- {meth}`Window.akill` - Kill window
+
+### When to Use Async
+
+Use async methods when:
+- Your application uses asyncio
+- You need to perform multiple tmux operations concurrently
+- You're integrating with async frameworks (FastAPI, aiohttp, etc.)
+
+For more details, see {ref}`async`.
 
 ## Final notes
 
@@ -499,3 +539,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