# libtmux for Python > The Python library (libtmux). These pages include its guides, tested examples and API documentation. - [Python API reference](https://libtmux.org/en/py/stable/reference/): every public symbol, generated from the source. Hosted on libtmux.org. --- # Load a workspace Source: https://libtmux.org/en/py/stable/workspace/cli/load/ > Create or reuse a session from a workspace file, with explicit attachment and output choices. Load a workspace file, saved workspace name, or project directory. Multiple inputs build in order; without [`-d`](https://libtmux.org/en/py/stable/workspace/cli/load/#arguments-and-flags-d), the final session is attached or selected through the current-client flow. ## Loading and attachment Create [`workspace.yaml`](https://libtmux.org/en/py/stable/workspace/guides/installation/#create-the-input) using the [installation walkthrough](https://libtmux.org/en/py/stable/workspace/guides/installation/), then load it on that walkthrough's dedicated socket: ```console $ tmuxp load \ -L workspace-guide \ -d \ workspace.yaml ``` [`-d`](https://libtmux.org/en/py/stable/workspace/cli/load/#arguments-and-flags-d) avoids attachment. Inside an existing tmux client, the normal interactive flow can switch to the new session, append windows, or stay detached. [`--append`](https://libtmux.org/en/py/stable/workspace/cli/load/#arguments-and-flags-a-append) explicitly selects the append flow and needs a current target session. An existing session is handled through tmuxp's load policy; loading is not a declarative reconciliation operation that removes surplus windows. Put flags before the complete group of filenames. The reference accepts flags before or after that group, but a flag between two filenames can cause an argument error. [`-s`](https://libtmux.org/en/py/stable/workspace/cli/load/#arguments-and-flags-s-2) overrides the final input's session name when several files are loaded. tmuxp parses [`-2`](https://libtmux.org/en/py/stable/workspace/cli/load/#arguments-and-flags-2) and [`-8`](https://libtmux.org/en/py/stable/workspace/cli/load/#arguments-and-flags-8) as mutually exclusive flags, separate from the CLI text's `--color` setting. Legacy [`-8`](https://libtmux.org/en/py/stable/workspace/cli/load/#arguments-and-flags-8) is unsupported; [tmux removed 88-color support](https://raw.githubusercontent.com/tmux/tmux/3.2a/CHANGES). ## Progress and script output [`--progress-format`](https://libtmux.org/en/py/stable/workspace/cli/load/#arguments-and-flags-progress-format) accepts [`default`](), `minimal`, `"window"`, `"pane"`, `verbose`, or a custom format. Available tokens include `{session}`, `{window}`, `{window_index}`, `{window_total}`, `{window_progress}`, `{window_progress_rel}`, `{windows_done}`, `{windows_remaining}`, `{pane_index}`, `{pane_total}`, `{pane_progress}`, `{progress}`, `{session_pane_progress}`, `{overall_percent}`, `{bar}`, `{pane_bar}`, `{window_bar}`, and `{status_icon}`. The output panel defaults to three lines. [`--progress-lines 0`](https://libtmux.org/en/py/stable/workspace/cli/load/#arguments-and-flags-progress-lines) hides the panel and sends script output to stdout; `-1` permits all available lines up to terminal height. [`--no-progress`](https://libtmux.org/en/py/stable/workspace/cli/load/#arguments-and-flags-no-progress) disables animation. See [environment settings](https://libtmux.org/en/py/stable/workspace/configuration/environment/) for environment bindings and [command ordering](https://libtmux.org/en/py/stable/workspace/configuration/commands/) for what is executed. ## Arguments and flags | Argument or flags | Arity / default | Choices or meaning | | --- | --- | --- | | `"workspace_files"` | one or more | filepath to session or filename of session in tmuxp workspace directory | | `-L` | value; None | passthru to tmux(1) -L | | `-S` | value; None | passthru to tmux(1) -S | | `-f` | value; None | passthru to tmux(1) -f | | `-s` | value; None | start new session with new session name | | `--yes`, `-y` | flag; False | always answer yes | | `-d` | flag; False | load the session without attaching it | | `-a`, `--append` | flag; False | load workspace, appending windows to the current session | | `-2` | flag; None | force tmux to assume the terminal supports 256 colours. | | `-8` | flag; None | legacy 88-colour flag; unsupported by tmux 3.2a+ | | `--log-file` | value; None | file to log errors/output to | | `--progress-format` | value; None | Spinner line format: preset name (default, minimal, window, pane, verbose) or a format string with tokens {session}, {window}, {progress}, {window_progress}, {pane_progress}, etc. Env: TMUXP_PROGRESS_FORMAT | | `--progress-lines` | value; None | Number of script-output lines shown in the spinner panel (default: 3). 0 hides the panel entirely (script output goes to stdout). -1 shows unlimited lines (capped to terminal height). Env: TMUXP_PROGRESS_LINES | | `--no-progress` | flag; False | Disable the animated progress spinner. Env: TMUXP_PROGRESS=0 | All commands accept `-h` / `--help`. Root options precede the command; see the [CLI overview](https://libtmux.org/en/py/stable/workspace/cli/). The [output reference](https://libtmux.org/en/py/stable/workspace/reference/output/) describes the formats supported by each command. [Parser and implementation source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/load.py). [tmuxp reference source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Capture a workspace Source: https://libtmux.org/en/py/stable/workspace/cli/freeze/ > Capture a running tmux session as a starting point for a workspace file. Capture a running tmux session as a starting workspace file. A capture cannot recover original scripts, plugin intent, comments or every application state. ## Export a named session After the [installation walkthrough](https://libtmux.org/en/py/stable/workspace/guides/installation/) creates `workspace-guide`, choose a new destination: ```console $ tmuxp freeze \ -L workspace-guide \ --workspace-format yaml \ --save-to captured-workspace.yaml \ --yes \ workspace-guide ``` Without a session, format or destination, the command can ask for missing choices. `--yes` answers yes/no questions; it does not supply every choice. `--quiet` suppresses explanatory status but can still allow prompts. An explicit `--save-to` path bypasses the overwrite confirmation used by the prompted path. Select a new path deliberately. A successful export writes a file; declining a confirmation can return without saving. Inspect the captured commands and paths before following [export and reload](https://libtmux.org/en/py/stable/workspace/guides/export-session/). [Command source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/freeze.py). --- # Convert workspace files Source: https://libtmux.org/en/py/stable/workspace/cli/convert/ > Convert a complete workspace document between YAML and JSON. Convert a workspace document between YAML and JSON while retaining its mapping keys. ## Change the file format Given [`workspace.yaml`](https://libtmux.org/en/py/stable/workspace/guides/installation/#create-the-input) from the [installation walkthrough](https://libtmux.org/en/py/stable/workspace/guides/installation/): ```console $ tmuxp convert \ --yes \ workspace.yaml ``` The destination has the same stem and opposite extension. `--yes` permits replacement of an existing destination. The original input remains. YAML comments and textual formatting do not round-trip through JSON. The command resolves a file or saved workspace name. [Discovery](https://libtmux.org/en/py/stable/workspace/guides/discovery/) describes that lookup. [Command source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/convert.py). --- # Edit a workspace Source: https://libtmux.org/en/py/stable/workspace/cli/edit/ > Resolve a workspace file or saved name and open it in an editor. Resolve a saved workspace or file and open it in the configured editor. ## Open a workspace With [`workspace.yaml`](https://libtmux.org/en/py/stable/workspace/guides/installation/#create-the-input) saved and `vi` installed: ```console $ EDITOR=vi tmuxp edit workspace.yaml ``` The command passes the entire `EDITOR` value as one executable name followed by the file path. It does not split editor arguments. Use a wrapper executable when arguments are needed. The command waits for the editor but does not propagate its exit status. Inspect the edited file before loading it. [Discovery](https://libtmux.org/en/py/stable/workspace/guides/discovery/) explains saved workspace names. [Command source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/edit.py). --- # Inspect runtime diagnostics Source: https://libtmux.org/en/py/stable/workspace/cli/debug-info/ > Collect the workspace CLI runtime, configuration and tmux diagnostics.. Collect tmuxp, Python, tmux, configuration and environment diagnostics. ## Collect a report ```console $ tmuxp debug-info --json ``` The command writes one JSON object. Named path fields mask the home directory, but raw tmux output arrays are preserved. Review diagnostics before sharing them because names, commands and raw values may describe your environment. See [troubleshooting](https://libtmux.org/en/py/stable/workspace/guides/troubleshooting/) for connection and configuration failures. [Command source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/debug_info.py). --- # List saved workspaces Source: https://libtmux.org/en/py/stable/workspace/cli/ls/ > List the workspace files found in project and global configuration locations. List discovered project and saved workspace files, with optional grouping and configuration content. ## List records ```console $ tmuxp ls --json ``` JSON output is an object with `workspaces` and `global_workspace_dirs`. No workspaces produces an empty `workspaces` array. `--ndjson` emits one record per line and zero lines for an empty result; it takes precedence when both output flags are present. `--full` includes configuration content. `--tree` groups human output by directory. [Discovery](https://libtmux.org/en/py/stable/workspace/guides/discovery/) explains the locations searched. [Command source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/ls.py). --- # Search workspaces Source: https://libtmux.org/en/py/stable/workspace/cli/search/ > Search the fields of discovered workspace documents. Search discovered workspace fields with regular expressions or literal strings. Query terms combine with AND unless `--any` selects OR. ## Find a session name ```console $ tmuxp search \ --json \ --fixed-strings \ --field session \ workspace ``` Field prefixes and repeated `--field` restrictions select name, session (`s`), path ([`p`]()), window (`w`) or pane data. `--ignore-case` ignores case; `--smart-case` does so only when a pattern has no uppercase. `--word-regexp` requires whole words and `--invert-match` selects nonmatches. ## Empty and invalid queries The documented implementation emits no bytes for an empty search result, including with `--json`. With no query, machine search can print human help and return normally. An invalid regular expression can also produce no machine output. Account for these outcomes before parsing stdout as JSON. [Command source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/search.py). --- # Evaluate in a workspace Source: https://libtmux.org/en/py/stable/workspace/cli/shell/ > Use the optional Python runtime to inspect a workspace through the native command. Open a Python shell with tmux objects available, or pass `-c` to evaluate a Python expression and exit. After the [installation walkthrough](https://libtmux.org/en/py/stable/workspace/guides/installation/) creates its dedicated server: ```console $ tmuxp shell \ -L workspace-guide \ -c 'print(server.sessions)' ``` Optional session and window arguments select a narrower context. `--best` chooses an available backend; explicit backends such as `--ipython` need their packages installed in the same Python environment. `--use-pythonrc` and `--no-startup` control startup loading. The last occurrence wins. `--use-vi-mode` and `--no-vi-mode` follow the same ordering rule. [Command source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/shell.py). --- # Import a workspace Source: https://libtmux.org/en/py/stable/workspace/cli/import/ > Choose a source format and translate it into a workspace document. Use [`tmuxp import teamocil`](https://libtmux.org/en/py/stable/workspace/cli/import-teamocil/) or [`tmuxp import tmuxinator`](https://libtmux.org/en/py/stable/workspace/cli/import-tmuxinator/) to translate a saved workspace. Each child command requires a source. The parent groups the importers and accepts `--help`. - [Teamocil](https://libtmux.org/en/py/stable/workspace/cli/import-teamocil/) imports its session and window structure. - [tmuxinator](https://libtmux.org/en/py/stable/workspace/cli/import-tmuxinator/) imports its project structure. Review the converted commands and directories before loading the result. [Command source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/import_config.py). --- # Import from Teamocil Source: https://libtmux.org/en/py/stable/workspace/cli/import-teamocil/ > Translate Teamocil windows and pane commands into a workspace document. Translate a Teamocil workspace into tmuxp configuration, review the result, and select its saved representation. ## Select an existing source With [`project.yml`](https://libtmux.org/en/py/stable/workspace/guides/discovery/) already present in the Teamocil configuration directory: ```console $ tmuxp import teamocil project ``` The source lookup uses [`~/.teamocil`](https://libtmux.org/en/py/stable/workspace/cli/import-teamocil/). A source argument is effectively required: although its positional action has optional arity, it belongs to a required exclusive group, and omission exits 2. The reference previews and saves the transformed document interactively. Inspect translated commands and directories before loading the result. See [output](https://libtmux.org/en/py/stable/workspace/reference/output/) for the command's formats. An extensionless name searches the configured source directory. A filename with an extension is resolved relative to the current directory unless you provide an explicit path. ## Arguments and flags | Argument or flags | Arity / default | Choices or meaning | | --- | --- | --- | | `workspace_file` | effectively required | `nargs="?"` belongs to a required exclusive group; omission exits 2. Source lookup uses [`~/.teamocil`](https://libtmux.org/en/py/stable/workspace/cli/import-teamocil/). | All commands accept `-h` / `--help`. Root options precede the command; see the [CLI overview](https://libtmux.org/en/py/stable/workspace/cli/). The [output reference](https://libtmux.org/en/py/stable/workspace/reference/output/) describes the formats supported by each command. [Parser and implementation source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/import_config.py). [tmuxp reference source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Import from tmuxinator Source: https://libtmux.org/en/py/stable/workspace/cli/import-tmuxinator/ > Translate a tmuxinator project into a workspace document. Translate a tmuxinator workspace into tmuxp configuration, preserving an explicit boundary around dynamic Ruby configuration. ## Select an existing source With [`project.yml`](https://libtmux.org/en/py/stable/workspace/guides/discovery/) already present in the configured tmuxinator directory: ```console $ tmuxp import tmuxinator project ``` `TMUXINATOR_CONFIG` overrides the source directory and expands a leading tilde. A source argument is effectively required, and omission exits 2 despite optional-looking help. The reference previews and saves the transformed document interactively. Do not interpret successful YAML parsing as support for ERB templates or arbitrary Ruby execution. Inspect the resulting commands and directories before loading. See [environment](https://libtmux.org/en/py/stable/workspace/configuration/environment/) and [output](https://libtmux.org/en/py/stable/workspace/reference/output/). An extensionless name searches the configured source directory. A filename with an extension is resolved relative to the current directory unless you provide an explicit path. ## Arguments and flags | Argument or flags | Arity / default | Choices or meaning | | --- | --- | --- | | `workspace_file` | effectively required | `nargs="?"` belongs to a required exclusive group; omission exits 2. Source lookup honors `TMUXINATOR_CONFIG`. | All commands accept `-h` / `--help`. Root options precede the command; see the [CLI overview](https://libtmux.org/en/py/stable/workspace/cli/). The [output reference](https://libtmux.org/en/py/stable/workspace/reference/output/) describes the formats supported by each command. [Parser and implementation source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/import_config.py). [tmuxp reference source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # tmuxp CLI manual Source: https://libtmux.org/en/py/stable/workspace/cli/ > Use tmuxp to load, inspect and save workspace configurations. Use `tmuxp` to load, inspect and save workspace configurations. [Install tmuxp](https://libtmux.org/en/py/stable/workspace/guides/installation/) separately from the core [`libtmux`]() package. ## Sessions
load
Build a session from files or saved workspace names.
freeze
Export a running session to a workspace configuration.
## Workspace files
ls
List saved configurations.
search
Find configurations by name or content.
edit
Open a workspace in an editor.
convert
Change a workspace between YAML and JSON representation.
import
Translate Teamocil or tmuxinator configuration.
## Diagnostics and shell
debug-info
Report runtime and tmux information.
shell
Evaluate Python with tmux context.
## Command options Root options precede the subcommand: ```console $ tmuxp --color never ls ``` Short flags belong to their command: [`search -S`](https://libtmux.org/en/py/stable/workspace/cli/search/) selects smart-case matching, while [`load`](https://libtmux.org/en/py/stable/workspace/cli/load/)` `[`-S`](https://libtmux.org/en/py/stable/workspace/cli/load/#arguments-and-flags-s) selects a socket path. Show the installed command options before using a flag: ```console $ tmuxp load --help ``` Machine output is command-specific. Read each command reference for its supported formats and empty-result behavior. [Command source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Shell completion Source: https://libtmux.org/en/py/stable/workspace/cli/completion/ > Generate completion for the installed workspace command. tmuxp uses the optional `shtab` package to generate experimental shell completion from its argparse definitions. Install it in the same Python environment as tmuxp, then follow the [completion setup](https://tmuxp.git-pull.com/cli/completion/) for your shell. Generate the script again after upgrading tmuxp so it matches the installed parser. The parser is available through [`tmuxp.cli.create_parser`](). [Parser source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Concepts Source: https://libtmux.org/en/py/stable/concepts/ > tmux objects, command transports, queries, and workspaces. libtmux lets you create sessions, arrange windows and panes, send commands, and read output from tmux. Start with the object hierarchy, then read about the transport, query, or workspace behavior your program needs. Use the API reference for signatures, defaults, and failure conditions. - [Server, session, window, pane](https://libtmux.org/en/py/stable/concepts/server-session-window-pane/): Understand the tmux object hierarchy and attached clients. - [Control mode vs one-shot](https://libtmux.org/en/py/stable/concepts/transports/): Choose subprocess commands, persistent connections, and batching. - [Filtering and queries](https://libtmux.org/en/py/stable/concepts/queries/): Find objects and handle absent or ambiguous matches. - [Workspaces](https://libtmux.org/en/py/stable/concepts/workspaces/): Build pane layouts from code or configuration files. --- # Server, session, window, pane Source: https://libtmux.org/en/py/stable/concepts/server-session-window-pane/ > How tmux servers, sessions, windows, panes and attached clients relate to each other. libtmux models tmux's server, session, window, and pane objects: ``` Server ├── Session │ └── Window │ └── Pane └── Client (attached view) ``` A [`Server`]() contains sessions. Each [`Session`]() contains links to windows, and each [`Window`]() contains panes. Commands run inside a [`Pane`](), where you send input and capture output. A window can be linked to more than one session. ## Stable identity, not name or index tmux assigns a unique ID to each session, window, and pane at creation. The ID remains stable for that object's lifetime even if its name or index changes: | Object | ID prefix | Example | |--------|-----------|---------| | Session | `$` | `$13` | | Window | `@` | `@3243` | | Pane | `%` | `%5433` | | Server | - | identified by socket name or path instead | Use stable IDs to identify the same tmux object across reads. Names and indexes can change while a program is running. Read the hierarchy: ```python for session in server.sessions: print(session.session_name) for window in session.windows: print(" ", window.window_index, window.window_name) for pane in window.panes: print(" ", pane.pane_id, pane.pane_current_command) ``` ## Client: a view, not a child A [`Client`]() represents a terminal attached to a session. Several clients can view the same server, and each can switch sessions or windows independently. Client fields describe the view at the time of the read. A [control-mode connection](https://libtmux.org/en/py/stable/concepts/transports/) is also a client. It appears in [`list-clients`](https://libtmux.org/en/tmux/latest/manual/list-clients/), counts toward [`session_attached`](https://libtmux.org/en/tmux/latest/catalog/formats/session_attached/), and affects attachment-dependent behavior such as [`destroy-unattached`](https://libtmux.org/en/tmux/latest/catalog/options/destroy-unattached/). Closing the last attached client can therefore destroy a session configured with that option. --- # Control mode vs one-shot Source: https://libtmux.org/en/py/stable/concepts/transports/ > Choose subprocesses, command batches, or persistent connections to send commands and receive events. libtmux sends commands to tmux through subprocesses or persistent control-mode connections. tmux also accepts several commands in one invocation: 1. **One-shot subprocess.** Each command spawns a fresh `tmux` process, which sends the request to the server, prints the result, and exits. 2. **A persistent control-mode client.** [`tmux -C attach-session`](https://libtmux.org/en/tmux/latest/manual/attach-session/) starts one long-lived tmux process that stays attached and speaks a line-oriented protocol over its stdout: commands go in, replies and asynchronous notifications (`%window-add`, `%output`, ...) come out, without starting a process per call. 3. **One invocation, several commands.** tmux accepts more than one command per invocation (`;`-joined, or one `-F`-tagged `list-*` per line). Grouping operations this way reduces process starts without opening a control-mode connection. ## Available transports Each library call starts a tmux subprocess. [`ControlMode`]() in `libtmux._internal` is an internal test helper, not a public command transport. Choose based on whether you need command results, notifications, or a batch of changes. ## A control client is a real client A persistent control connection attaches a tmux client. It appears in [`list-clients`](https://libtmux.org/en/tmux/latest/manual/list-clients/), increments [`session_attached`](https://libtmux.org/en/tmux/latest/catalog/formats/session_attached/), and affects [`destroy-unattached`](https://libtmux.org/en/tmux/latest/catalog/options/destroy-unattached/), client hooks, and idle-client accounting. Each connection counts separately. Python's internal [`ControlMode`]() test helper uses this behavior for commands that require an attached client, such as [`display-popup`](https://libtmux.org/en/tmux/latest/manual/display-popup/) and [`detach-client`](https://libtmux.org/en/tmux/latest/manual/detach-client/). ## Why fold several commands into one invocation Creating an object can require a second command to read its resulting state. Batching can reduce repeated reads and process starts. ## What this costs in practice A persistent connection avoids starting a client for each command. A chain groups a known sequence into one invocation. For occasional commands, use the default subprocess transport; measure your workload before changing transports for performance. Use a notification stream when your program needs tmux events. ## Sending a command The example uses the subprocess API. See the reference for batching and control-mode setup. ```python import libtmux # One-shot: every call underneath this handle spawns a `tmux` process. server = libtmux.Server() session = server.new_session(session_name="work") session.active_window.active_pane.send_keys("echo hello") ``` To inspect tmux's control protocol, attach a control client: ```console $ tmux -C attach-session -t work ``` --- # Filtering and queries Source: https://libtmux.org/en/py/stable/concepts/queries/ > How you get from every session on the server to the one pane you mean, and what happens when zero or several match. Use a collection filter to find matching sessions, windows, or panes. Use an exactly-one lookup when your next operation requires a single target. - **Filtering returns a collection; exactly-one lookup checks the result count.** A filter returns zero or more matches. An exactly-one operation returns one object or reports a missing or ambiguous match. - **Choose where to filter.** Filter a snapshot in your program when you need several queries over the same data. A tmux format filter can reduce the rows returned by a live read. The cost depends on the data and queries you need. ## Filter collections and select one object [`server.sessions`](), [`session.windows`](), and [`window.panes`]() are [`QueryList`]() collections. Call [`.filter()`]() with field names and optional lookup suffixes: ```python >>> session.windows.filter(window_name__startswith='api') [Window(@... ...:api-server, Session($... ...))] >>> session.windows.filter(window_name__iregex=r'n?vim') ``` Lookups include `exact`, `contains`, `startswith`, `endswith`, [`regex`](), and their case-insensitive `i`-prefixed variants. Multiple keywords and chained [`.filter()`]() calls combine with AND. `.get()` requires exactly one match. Its [`default`]() argument handles an absent result; multiple matches still raise [`MultipleObjectsReturned`](). Server-wide collections ([`server.windows`](), [`server.panes`]()) enumerate window links. A window linked to two sessions appears once per session, so a lookup can be ambiguous even when the window ID is unique. Use [`Window.linked_sessions`]() to find its sessions. For a known ID, use [`Pane.from_pane_id()`]() or [`Window.from_window_id()`]() to resolve the object directly. For servers with hundreds or thousands of panes, [`.filter()`]() still builds every object before you discard the ones that don't match. [`search_sessions`](), `search_windows`, and `search_panes` push a tmux `-f` filter expression down to the server instead, so libtmux builds objects only for the matches: ```python >>> server.search_sessions(filter='#{==:#{session_name},alpha-1}') ``` Python-side lookups work with the library's supported tmux versions. The tmux filter grammar requires tmux 3.2 or newer. An unknown format token expands to an empty value, so a malformed filter can look like a valid filter with no matches. If `search_*()` unexpectedly returns no results, try [`#{m:*,#{session_name}}`](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/) to check that the session data is available. ## Result counts Use [`QueryList.filter`]() to keep matching objects and [`QueryList.get`]() when exactly one must match. An empty result raises [`ObjectDoesNotExist`]() unless you supply `default=`. Several matches raise [`MultipleObjectsReturned`](). [Filtering and querying](https://libtmux.org/en/py/stable/guides/querying-and-filtering/) shows exactly-one lookups and their error handling. Do not index the first result until the operation has established that a match exists. --- # Workspaces Source: https://libtmux.org/en/py/stable/concepts/workspaces/ > Build pane layouts with the object API or a workspace configuration file. A workspace arranges windows and panes for a task, such as editing code, running a development server, and following logs. Build it with the object API when the layout depends on program logic. Use a declarative builder when you want to store the layout in a configuration file, such as [tmuxp](https://tmuxp.git-pull.com/) YAML or JSON. ## Building one imperatively Create a window, split it into panes, apply a layout, and send each pane its command: ```python def create_dev_workspace(session, name='dev'): window = session.new_window(window_name=name, attach=False) window.resize(height=50, width=160) main_pane = window.active_pane terminal_pane = main_pane.split(size='30%') log_pane = terminal_pane.split(direction=PaneDirection.Right) return {'window': window, 'main': main_pane, 'terminal': terminal_pane, 'logs': log_pane} ``` A split creates a pane; direction and size control its placement. Applying a layout rearranges existing panes while their processes continue running. tmux provides `even-horizontal`, `even-vertical`, `main-horizontal`, `main-vertical`, and `tiled` layouts. Choose detached creation when the user's current window should retain focus. Splits and resizes issue tmux commands; [Control mode vs one-shot](https://libtmux.org/en/py/stable/concepts/transports/) covers their transport costs and batching. `attach=False` keeps a newly created window in the background. ## Building one declaratively These packages read or build workspace configurations based on tmuxp: `tmuxp` loads a workspace configuration and creates its sessions, windows, and panes. See [Workspace Manager](https://libtmux.org/en/py/stable/workspace/) for its configuration and CLI. ## Cleaning up [`Window`]() and [`Session`]() context managers kill their objects on block exit, including when the block raises: ```python with session.new_window(window_name='temp-window') as temp_win: pane = temp_win.active_pane pane.send_keys('echo "temporary workspace"') # window is gone here, even if the block raised ``` See [Context managers](https://libtmux.org/en/py/stable/topics/context-managers/) for cleanup support in each port. Use explicit kill methods when the handle does not provide scope-based cleanup. --- # Workspace configuration Source: https://libtmux.org/en/py/stable/workspace/configuration/ > Define the session, windows, panes and commands loaded by the workspace CLI. A workspace file describes one tmux session, its windows and panes, and the commands sent to them. YAML and JSON carry the same field names. Save this complete example as [`workspace.yaml`](https://libtmux.org/en/py/stable/workspace/guides/installation/#create-the-input): ```yaml session_name: workspace-example start_directory: ./ windows: - window_name: editor layout: even-horizontal panes: - echo ready - blank ``` The equivalent JSON is: ```json { "session_name": "workspace-example", "start_directory": "./", "windows": [ { "window_name": "editor", "layout": "even-horizontal", "panes": ["echo ready", "blank"] } ] } ``` With Python tmuxp installed, load this file detached on a socket reserved for the example: ```console $ tmuxp load \ -L configuration-example \ -d \ workspace.yaml ``` Inspect the resulting panes: ```console $ tmux -L configuration-example list-panes -t '=workspace-example' ``` Remove the example session when finished: ```console $ tmux -L configuration-example kill-session -t '=workspace-example' ``` ## How configuration becomes a session The tmuxp loader reads a document, expands command shorthand and shell variables, and applies inherited defaults before selecting a workspace builder. The classic builder then creates tmux objects and sends commands. Completion means construction and command delivery finished; it does not establish that a server launched in a pane is ready. [`"session_name"`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-session-name) and [`"windows"`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-windows) are needed by normal loading. A window can omit its name and let tmux choose one; an omitted [`"panes"`](https://libtmux.org/en/py/stable/workspace/configuration/windows/#window-keys-panes) list defaults to one blank pane. Supplying explicit names and pane lists makes a portable example clearer. An empty pane list is not the same input as an omitted list. The internal [`validate_schema`]() helper requires each window_name, but the current CLI/classic builder path does not call it. It is not a complete JSON Schema or an exact description of what load accepts. A YAML parser accepting a key also does not mean a builder implements it. ## Configuration reference - [Session](https://libtmux.org/en/py/stable/workspace/configuration/session/) covers identity, options, environment, and root keys. - [Windows](https://libtmux.org/en/py/stable/workspace/configuration/windows/) covers names, indexes, option timing, and focus. - [Panes](https://libtmux.org/en/py/stable/workspace/configuration/panes/) covers shorthand, blank forms, shell, and overrides. - [Commands](https://libtmux.org/en/py/stable/workspace/configuration/commands/) covers before commands, Enter, delays, and history. - [Environment](https://libtmux.org/en/py/stable/workspace/configuration/environment/) separates process settings from pane values. - [Directories](https://libtmux.org/en/py/stable/workspace/configuration/directories/) explains file discovery and path resolution. - [Layouts](https://libtmux.org/en/py/stable/workspace/configuration/layouts/) explains pane arrangement and terminal size. - [Hooks and builders](https://libtmux.org/en/py/stable/workspace/configuration/hooks/) covers scripts and Python extensions. Use the [configuration gallery](https://libtmux.org/en/py/stable/workspace/examples/gallery/) for more complete files. Configuration conversion should preserve the source mapping, including extension keys; loading that mapping requires separate support for every execution feature. ## Reference source [loader.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/loader.py); [validation.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/validation.py); [classic.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/classic.py). --- # Session configuration Source: https://libtmux.org/en/py/stable/workspace/configuration/session/ > Name a workspace and apply session options and environment. The root mapping names the session and supplies defaults inherited by its windows and panes. The file's name is independent of [`"session_name"`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-session-name): loading [`project.yaml`](https://libtmux.org/en/py/stable/workspace/guides/discovery/) can create a session named [`development`](). ```yaml session_name: development start_directory: ./ suppress_history: true shell_command_before: - echo preparing pane environment: WORKSPACE_ROLE: development options: default-shell: /bin/sh global_options: status: true windows: - window_name: main panes: - echo ready ``` [`"global_options"`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-global-options) changes the shared tmux server. Use a dedicated socket while learning these options. The example assumes `/bin/sh` exists. ## Root keys | Key | Meaning | | --- | --- | | `"session_name"` | Session identity; expanded before building | | `"windows"` | Ordered list of window mappings | | `start_directory` | Starting directory and base for inherited window directories | | `"options"` | tmux session options applied during construction | | `"global_options"` | tmux options applied with global scope on the selected server | | `"environment"` | Values placed in the tmux session environment | | `shell_command_before` | Commands prepended to commands in every pane | | `"suppress_history"` | Default history suppression inherited by windows and panes | | `"before_script"` | Process run after initial session creation, before configured windows | | `"plugins"` | List of Python plugin class references | | `workspace_builder` | Classic builder, registered builder name, or Python class reference | | `workspace_builder_paths` | Trusted directories used for Python builder imports | | `workspace_builder_options` | Builder behavior settings such as pane_readiness | Options use tmux option names and values. A workspace key such as [`start_directory`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-start-directory) is not a tmux option and does not belong in [`"options"`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-options). Some tmux settings are window options even when tmux permits them through a session target; consult tmux's option scope when choosing the catalog. ## Construction order The classic builder creates the initial session, runs its initial plugin hook and workspace before_script, then applies root options, global options, and session environment before creating configured windows. The temporary initial window is replaced. Hooks can observe those tmux operations; loading is not an invisible transaction. The same-named session is handled by the [load command](https://libtmux.org/en/py/stable/workspace/cli/load/) and its attach, switch, append, and detached choices. Changing a YAML file does not automatically reconcile an existing running session. An explicit [`load`](https://libtmux.org/en/py/stable/workspace/cli/load/)` `[`-s`](https://libtmux.org/en/py/stable/workspace/cli/load/#arguments-and-flags-s-2) value overrides the configured name for that invocation. ## Inherited defaults A window can override its start directory and history policy, and a pane can override them again. Before commands accumulate in session, window, then pane order. Session environment remains distinct from window/pane launch environments. Read [directories](https://libtmux.org/en/py/stable/workspace/configuration/directories/), [commands](https://libtmux.org/en/py/stable/workspace/configuration/commands/), and [environment](https://libtmux.org/en/py/stable/workspace/configuration/environment/) before relying on inheritance. Python scripts, plugins, and custom builder references execute code. Their exact timing and runtime requirements are in [hooks and builders](https://libtmux.org/en/py/stable/workspace/configuration/hooks/). ## Reference source [classic.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/classic.py); [loader.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/loader.py); [load.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/load.py). --- # Window configuration Source: https://libtmux.org/en/py/stable/workspace/configuration/windows/ > Set window names, indexes, layouts, options and focus. Each item in [`"windows"`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-windows) describes one window and its ordered panes. Set [`"window_name"`](https://libtmux.org/en/py/stable/workspace/configuration/windows/#window-keys-window-name) when the name matters; an omitted name lets tmux choose it. [`"window_index"`](https://libtmux.org/en/py/stable/workspace/configuration/windows/#window-keys-window-index) selects a tmux numeric index independently of the item's position in the list. ```yaml session_name: window-example start_directory: ./ windows: - window_name: tools window_index: 1 start_directory: ./ layout: even-horizontal focus: true options: automatic-rename: false options_after: synchronize-panes: true panes: - echo left - echo right ``` This configuration sends each pane its own initial command before enabling synchronized input. Later typing in one synchronized pane can affect the other pane. ## Window keys | Key | Meaning | | --- | --- | | `"window_name"` | Label used by tmux; shell variables are expanded | | `"window_index"` | Explicit numeric position, otherwise use tmux's available index | | `"panes"` | Ordered pane list; omission supplies one blank pane | | `"layout"` | Named tmux layout or explicit layout description | | `start_directory` | Directory inherited by panes unless a pane overrides it | | `"window_shell"` | Initial shell/application for panes, subject to pane shell override | | `focus` | Select the window after building | | `"options"` | Window options applied during creation | | `"options_after"` | Window options applied after panes and their initial commands | | `"environment"` | Launch environment used when a pane lacks its own map | | `shell_command_before` | Commands prepended after session before commands | | `"suppress_history"` | Window default overriding the session history policy | ## First pane and later panes A new window already has its initial pane. Tmuxp uses the first configured pane's start_directory, shell, and environment when launching that window, then creates splits for later panes. A first-pane override therefore matters during [new-window](https://libtmux.org/en/tmux/latest/manual/new-window/), not only while creating splits. A pane shell overrides window_shell. Window environment is used when the pane has no environment map; providing a pane map selects that map instead. ## Index, layout, and focus The classic builder moves the temporary initial window before creating the configured first window. This permits an explicit first index without reusing the temporary window's content. Do not assume window list position and tmux numeric index are identical. Window options precede layout application. [`"options_after"`](https://libtmux.org/en/py/stable/workspace/configuration/windows/#window-keys-options-after) exists for settings such as synchronize-panes that should take effect after individual setup commands. [Layouts](https://libtmux.org/en/py/stable/workspace/configuration/layouts/) explains named layouts, dimensions, and focus; [panes](https://libtmux.org/en/py/stable/workspace/configuration/panes/) describes the pane forms accepted inside a window. ## Reference source [classic.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/classic.py); [loader.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/loader.py); [2-pane-synchronized.yaml](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/2-pane-synchronized.yaml). --- # Pane configuration Source: https://libtmux.org/en/py/stable/workspace/configuration/panes/ > Choose pane commands, launch settings and focus. A pane can be a command string, a list of commands, or a mapping of settings. Each item in the window's [`"panes"`](https://libtmux.org/en/py/stable/workspace/configuration/windows/#window-keys-panes) list creates one pane; a command list inside that item describes several commands in that same pane. ```yaml session_name: pane-example start_directory: ./ windows: - window_name: main start_directory: ./ panes: - echo one command - [echo first command, echo second command] - shell_command: - echo configured pane start_directory: ./ focus: true - blank ``` ## Blank forms | Form inside [`"panes"`](https://libtmux.org/en/py/stable/workspace/configuration/windows/#window-keys-panes) | Reference interpretation | | --- | --- | | null, omitted YAML value, `blank`, or `"pane"` | Pane without its own commands | | Empty mapping or empty list | Expands to a pane without its own commands | | Mapping with no shell_command | Keeps the pane's other settings and uses no own commands | | `shell_command: null` or a single null command | No own commands | | Empty string `""` | Sends an empty command, normally pressing Enter | A blank pane can still receive inherited [before commands](https://libtmux.org/en/py/stable/workspace/configuration/commands/). Blank forms do not disable session/window/pane setup. An omitted window panes key is defaulted to one blank pane; an explicitly empty panes list is a different shape and should not be used as a portable way to request that default. ## Pane keys | Key | Meaning | | --- | --- | | `shell_command` | String, ordered command list, or supported command dictionaries | | `shell_command_before` | Setup prepended after session/window before commands | | `start_directory` | Pane directory override | | `"shell"` | Shell/application launched for this pane | | `focus` | Select this pane in its window | | `"environment"` | Environment map selected for this pane's launch | | `"suppress_history"` | Pane history policy override | | `"enter"` | Default for whether to submit each command | | `sleep_before`, `sleep_after` | Default delays in seconds around each command | ## Launch a shell or type commands [`"shell"`](https://libtmux.org/en/py/stable/workspace/configuration/panes/#pane-keys-shell) chooses the process tmux starts in the pane. [`shell_command`](https://libtmux.org/en/py/stable/workspace/configuration/panes/#pane-keys-shell-command) sends text into the process already running there. Launching an application through shell can work with tmux's remain-on-exit behavior, while typing that application's name into a shell has different process semantics. A pane shell overrides window_shell, including on the first pane. The first pane also supplies its directory and environment during window creation. Use an installed shell/application path rather than assuming the same executable exists on every host. A successful build confirms command delivery, not application readiness or command exit status. See [commands](https://libtmux.org/en/py/stable/workspace/configuration/commands/) for Enter, timing, and history, and [environment](https://libtmux.org/en/py/stable/workspace/configuration/environment/) for launch-map selection. ## Reference source [loader.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/loader.py); [classic.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/classic.py); [blank-panes.yaml](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/blank-panes.yaml); [pane-shell.yaml](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/pane-shell.yaml). --- # Workspace commands Source: https://libtmux.org/en/py/stable/workspace/configuration/commands/ > Order pane setup and command delivery, Enter handling and delays. Tmuxp sends workspace commands into panes in order. A command can be a string or a mapping with `"cmd"` and execution controls. [`shell_command_before`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-shell-command-before) adds shared setup without copying it into every pane. ```yaml session_name: command-example shell_command_before: - echo session setup windows: - window_name: main shell_command_before: - echo window setup panes: - shell_command_before: - echo pane setup shell_command: - cmd: echo ready sleep_after: 0.2 - cmd: echo typed but not submitted enter: false sleep_after: 0 ``` This sends the three setup commands, submits echo ready, waits 0.2 seconds, and leaves the final command at the prompt. The delay pauses construction; it does not ask the application whether it is ready. ## Forms and order [`shell_command`](https://libtmux.org/en/py/stable/workspace/configuration/panes/#pane-keys-shell-command) and [`shell_command_before`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-shell-command-before) accept a scalar command or a list. A command dictionary requires `"cmd"` for the text. The loader expands shell variables and tilde expressions in command strings before the builder sends them. Variables already known to the process running tmuxp can therefore be substituted before a pane shell sees the command. For each pane, the loader concatenates session before commands, window before commands, pane before commands, then the pane's own commands. A blank pane still receives inherited setup. Quoting affects the pane shell too; YAML quoting alone does not bypass tmuxp's expansion step. ## Enter and delays | Setting | Default and scope | | --- | --- | | `"enter"` | True; pane default, then command override | | `sleep_before` | No delay; pane default, then command override in seconds | | `sleep_after` | No delay; pane default, then command override in seconds | In the classic builder, a command's enter/delay override carries forward to subsequent commands in that pane. Set [`enter`](https://libtmux.org/en/py/stable/workspace/configuration/commands/#enter-and-delays-enter)`: true` or an explicit zero delay to restore that behavior for a later command. Absence means keep the current value; zero is an intentional delay override. Pauses run synchronously during construction. They can let a startup command settle but do not monitor its success. A failed pane command is not necessarily a failed tmux send operation, and starting a web server is not proof it is accepting connections. ## History and prompt readiness History suppression defaults to true. A session value trickles to a window, and a pane can override it. Suppression prefixes command text with a space. Bash needs HISTCONTROL containing ignorespace or ignoreboth; zsh needs HIST_IGNORE_SPACE. Without shell support, the command can still enter history. Builder pane_readiness is separate from command delays. Auto waits for the configured zsh session shell, while custom pane/window launch commands skip prompt waiting. See [hooks and builders](https://libtmux.org/en/py/stable/workspace/configuration/hooks/) for the policy and its limits. A workspace [before_script](https://libtmux.org/en/py/stable/workspace/configuration/hooks/) runs as a process outside the panes and checks its exit status. Use it for bootstrap work that must succeed before configured windows are built, rather than treating pane command delivery as a checked process result. ## Reference source [loader.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/loader.py); [classic.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/classic.py); [sleep.yaml](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/sleep.yaml); [skip-send.yaml](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/skip-send.yaml). --- # Workspace environment Source: https://libtmux.org/en/py/stable/workspace/configuration/environment/ > Configure the loader process and the variables available to pane commands. The environment of the process running tmuxp controls discovery, expansion, and presentation. A workspace's [`"environment"`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-environment) mapping controls the tmux session or the environment passed when launching a pane. These are separate settings. ```yaml session_name: environment-example environment: WORKSPACE_ROLE: shared windows: - window_name: main environment: WINDOW_ROLE: tools panes: - echo window environment - environment: PANE_ROLE: isolated shell_command: env ``` The first pane receives the window launch map. The second selects its own pane map instead of merging it with the window map. It still inherits applicable tmux session/process environment. A pane map does not mean a completely empty environment plus that map. ## Expansion before launch Tmuxp expands tilde and environment-variable expressions in session/window names, paths, before_script, command strings, environment values, and string option values. It uses the environment of the process invoking tmuxp. It does not first populate that process environment from the workspace's environment mapping. For example, a command using an already-set process variable can be substituted before pane creation. Inspect the expanded intent when a variable should instead be read dynamically by a pane shell. Unknown variables and shell-specific expressions follow the loader's expansion and the eventual shell's rules, not a general template language. ## CLI and runtime variables | Variables | Effect | | --- | --- | | `TMUXP_CONFIGDIR`, `XDG_CONFIG_HOME`, `HOME` | Global workspace directory selection and home expansion | | `TMUXINATOR_CONFIG` | Tmuxinator import source directory | | `$EDITOR` | Editor executable; reference default is vim | | `$TMUX`, `$TMUX_PANE` | Current tmux connection and shell object context | | `TMUXP_PROGRESS` | Value 0 disables animated load progress | | `TMUXP_PROGRESS_FORMAT` | Default/minimal/window/pane/verbose preset or custom tokens | | `TMUXP_PROGRESS_LINES` | Script panel lines: default 3, 0 hides, -1 caps to terminal height | | `TMUXP_DETECT_TERMINAL_SIZE` | Value 1 enables size detection; default 1 | | `TMUXP_DEFAULT_COLUMNS`, `TMUXP_DEFAULT_ROWS` | Fallback session dimensions | | `COLUMNS`, `LINES`, `ROWS` | Terminal helper overrides and fallback sizing inputs | | `NO_COLOR`, `FORCE_COLOR` | Color policy; nonempty values are significant | | [`PYTHONSTARTUP`]() | Startup file used by supported shell startup behavior | | `IPYTHON_ARGUMENTS` | Whitespace-split arguments for the IPython backend | | [`PYTHONBREAKPOINT`]() | Can affect debugger selection in tmuxp shell | | `SHELL` | Shell diagnostics and readiness fallback | | `DISABLE_AUTO_TITLE` | Oh My Zsh automatic-title warning | | `PATH` | Executable lookup and diagnostics | | `LIBTMUX_TMUX_FORMAT_SEPARATOR` | Python libtmux format collection override | Explicit progress flags take precedence over their corresponding defaults. Nonempty NO_COLOR disables color even with always; otherwise explicit never/always precede FORCE_COLOR and automatic TTY detection. Use supported machine formats when consuming output in a script. See [directories](https://libtmux.org/en/py/stable/workspace/configuration/directories/) for existing-directory precedence, [layouts](https://libtmux.org/en/py/stable/workspace/configuration/layouts/) for size resolution, and [shell](https://libtmux.org/en/py/stable/workspace/cli/shell/) for Python-specific environment effects. ## Reference source [loader.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/loader.py); [finders.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/finders.py); [classic.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/classic.py); [load.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/load.py); [shell.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/shell.py); [shell.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/shell.py); [colors.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/_internal/colors.py); [util.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/util.py). --- # Files and directories Source: https://libtmux.org/en/py/stable/workspace/configuration/directories/ > Resolve saved workspace files and the working directories used by panes. Tmuxp accepts an explicit workspace file, a saved workspace name, or a project directory. The location of the selected file determines how config-relative paths expand. Use an explicit file while debugging a discovery problem. Load a file on a dedicated server: ```console $ tmuxp load \ -L directory-example \ -d \ ./workspace.yaml ``` Load the current project's workspace: ```console $ tmuxp load . ``` These commands use Python tmuxp and assume the corresponding workspace file already exists. The first command leaves its session detached; use the session name from the file when inspecting or cleaning it up. ## Global and local discovery For the preferred global workspace directory, tmuxp tries TMUXP_CONFIGDIR, XDG_CONFIG_HOME/tmuxp (or the XDG default), then the legacy [`~/.tmuxp`](https://libtmux.org/en/py/stable/workspace/guides/discovery/) directory. It chooses the first existing directory. If none exists, it returns the legacy location. Setting TMUXP_CONFIGDIR to a nonexistent path does not automatically select that path over an existing fallback. Project discovery walks the current directory and its parents, choosing at most one workspace per directory in [`.tmuxp.yaml`](), [`.tmuxp.yml`](https://libtmux.org/en/py/stable/workspace/guides/discovery/), [`.tmuxp.json`](https://libtmux.org/en/py/stable/workspace/guides/discovery/) order. It stops at home or filesystem root. [`ls`](https://libtmux.org/en/py/stable/workspace/cli/ls/) can report global directory candidates and locally discovered workspaces; that inventory is not identical to resolving one explicit load argument. The importers use their own source roots: Teamocil uses [`~/.teamocil`](https://libtmux.org/en/py/stable/workspace/cli/import-teamocil/); tmuxinator uses TMUXINATOR_CONFIG, with tilde expansion, or [`~/.tmuxinator`](https://libtmux.org/en/py/stable/workspace/cli/import-tmuxinator/). Their source argument is effectively required, even though the parser's positional arity looks optional. ## Start directories ```yaml session_name: directory-example start_directory: ./ windows: - window_name: root panes: - pwd - window_name: child start_directory: ./src panes: - pwd - start_directory: ./ shell_command: pwd ``` This example assumes the project has a `"src"` directory. The first window inherits the session directory. The child window resolves ./src against the explicit session directory, and its second pane resolves ./ against that window directory. Both child panes start in src. The root start_directory resolves a dot-relative path from the configuration file's directory. At child levels, the pinned loader resolves dot-relative paths against the immediate parent's start_directory before inherited defaults are filled. Define that parent value explicitly when using ./ or ../ in a child. A missing parent start_directory can raise KeyError during expansion. A plain relative window directory such as src is joined to the session directory later, during trickle. A dot-relative pane under that still-relative window can resolve against the invoking process's current directory first. Use an explicit ./src window value as above, or an absolute path, to avoid that inconsistency. When a document names no [`start_directory`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-start-directory) at any level, panes start in the directory the command was run from, not the directory the workspace file lives in. Use an explicit session directory and child directories as described above when loading a file from another working directory. Absolute and expanded-home paths retain their explicit location. Quote `~` in YAML to avoid its null spelling. A pane override also applies to the first pane in the Python classic builder. Inspect resolved values and the resulting pane directory when loading a workspace from a different working directory. ## Missing directories and bootstrap A nonexistent path can make tmux start somewhere unexpected, including a home directory, rather than producing a useful configuration error. Inspect the actual pane directory when verifying a workspace. A relative before_script path is resolved from the workspace file. Its process working directory uses the session start_directory when supplied. A bootstrap process can create required project files, but it runs after the initial tmux session exists. See [hooks](https://libtmux.org/en/py/stable/workspace/configuration/hooks/) for failure handling and [environment](https://libtmux.org/en/py/stable/workspace/configuration/environment/) for variable expansion. ## Reference source [finders.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/finders.py); [loader.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/loader.py); [import_config.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/import_config.py); [classic.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/classic.py); [start-directory.yaml](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/start-directory.yaml). --- # Window layouts Source: https://libtmux.org/en/py/stable/workspace/configuration/layouts/ > Arrange panes with tmux layout names or a saved layout. A window's [`"layout"`](https://libtmux.org/en/py/stable/workspace/configuration/windows/#window-keys-layout) chooses how tmux arranges its panes. Named layouts adapt to the window size; explicit layout strings describe geometry more directly. The selected tmux version and terminal dimensions affect the final result. ```yaml session_name: layout-example windows: - window_name: main layout: main-horizontal focus: true options: main-pane-height: 60% panes: - shell_command: echo main pane focus: true - echo first lower pane - echo second lower pane ``` ## Layout names and options Common tmux layout names are even-horizontal, even-vertical, main-horizontal, main-vertical, and tiled. Layout availability belongs to the target tmux version. Options such as main-pane-height and main-pane-width shape applicable main-pane layouts. A row/column count and a percentage are different values; preserve that distinction in YAML/JSON. The classic builder applies window options before selecting a layout and applies options_after after panes and their setup commands. This lets a workspace size its main pane while delaying synchronize-panes until individual setup is complete. An explicit layout string can depend on the current number of panes and window size. A layout captured from one terminal is a starting point to inspect on another, not a portable pixel diagram. ## Terminal dimensions When TMUXP_DETECT_TERMINAL_SIZE is 1 (the default), the classic builder asks Python's terminal-size helper for initial session dimensions. COLUMNS and LINES can influence that helper. Fallback width uses TMUXP_DEFAULT_COLUMNS, then COLUMNS, then 80. Fallback height uses TMUXP_DEFAULT_ROWS, then ROWS, with nominal default 24. The helper can choose terminal dimensions instead of its fallback, so a TMUXP_DEFAULT value alone is not an unconditional size override. Detached sessions also need dimensions for reproducible layouts. Invalid numeric environment values can fail before useful construction. ## Focus and indexes Set window focus to select that window after construction, and pane focus to select the active pane within its window. Prefer one focused window and one focused pane per window; multiple true values depend on build order and are harder to reason about. A window_index selects its numeric tmux position. Pane IDs such as `%3` are runtime identities, not YAML pane list positions. Base-index and pane-base-index settings can make visible indexes differ from zero-based list positions. Inspect a running workspace's geometry and selection: ```console $ tmux -L layout-example list-windows -t '=layout-example' ``` This command assumes the sample workspace was loaded on the dedicated layout-example socket. Use [load](https://libtmux.org/en/py/stable/workspace/cli/load/) to select that socket, then inspect panes as needed. ## Reference source [classic.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/classic.py); [main-pane-height.yaml](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/main-pane-height.yaml); [main-pane-height-percentage.yaml](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/main-pane-height-percentage.yaml); [focus-window-and-panes.yaml](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/focus-window-and-panes.yaml); [window-index.yaml](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/window-index.yaml). --- # Bootstrap scripts and extensions Source: https://libtmux.org/en/py/stable/workspace/configuration/hooks/ > Run a checked bootstrap process before workspace commands. Workspace scripts, plugins, and custom builders extend how Python tmuxp creates a session. They are execution features, not passive configuration metadata. A workspace naming Python code needs that code installed or importable in tmuxp's environment. ## Bootstrap with before_script ```yaml session_name: bootstrap-example start_directory: ./ before_script: ./bootstrap.sh windows: - window_name: main panes: - echo bootstrap completed ``` This complete configuration assumes bootstrap.sh exists and is executable. Tmuxp resolves the script relative to the workspace file and uses the session start_directory as the process working directory when supplied. A zero exit status permits configured-window construction to continue; a failing script raises an error. The classic builder has already created the initial session when before_script runs. It kills that session when the bootstrap process fails. That does not undo files or other external effects created by the script. Pane shell_command is different: successful text delivery does not check the command's exit status. ## Python plugins [`"plugins"`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-plugins) is a list of Python class references, conventionally a class in a package's plugin module. Install that package into the same Python environment as tmuxp. Plugins can declare tmux, libtmux, and tmuxp version requirements. The lifecycle includes these distinct hooks: | Hook | When it applies | | --- | --- | | [`before_workspace_builder`]() | Initial session exists, before configured windows | | [`on_window_create`]() | A window has been created, before its panes finish | | [`after_window_finished`]() | That window's panes and setup have finished | | [`"before_script"`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-before-script) | Plugin callback after session construction | | [`reattach`]() | Reattachment to a session that already exists | The plugin callback named before_script is not the workspace before_script process. Their timing and execution mechanism differ. Plugin methods can change live tmux state; choose a plugin only when its behavior is intended for the workspace. ## Select a workspace builder The default is the built-in classic builder. [`workspace_builder`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-workspace-builder) can name a registered entry point in the [`tmuxp.workspace_builders`](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/registry.py) group, a `module:attribute` reference, or a dotted Python path. Custom builders receive expanded configuration and a libtmux server. [`workspace_builder_paths`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-workspace-builder-paths) lists trusted directories temporarily added to Python's import path. Tilde and environment variables expand, relative entries resolve against the workspace file, and entries must exist as directories. Tmuxp does not use site.addsitedir for these paths. Adding an import path is not permission to treat arbitrary workspace files as inert data. A builder implements the synchronous build/session interface and cooperates with plugin, progress, before-script, script-output, and build-event callbacks. The configuration alone cannot establish that an arbitrary custom builder honors those callbacks or the classic builder's behavior. ## Pane readiness ```yaml session_name: readiness-example workspace_builder: classic workspace_builder_options: pane_readiness: auto windows: - window_name: main panes: - echo ready ``` Auto, the default, waits for a prompt when the configured session shell is zsh. Always requests the wait for default-shell panes; never skips it. Accepted aliases include true/on/yes/1 for always and false/off/no/0 for never, with strings normalized for case and surrounding whitespace. Unknown values are rejected. Custom pane/window launch commands skip prompt waiting. Readiness checks concern a shell prompt, not the eventual application's health, and do not acknowledge that every later command was consumed. Use [commands](https://libtmux.org/en/py/stable/workspace/configuration/commands/) for explicit delays and Enter behavior. ## Reference source [classic.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/classic.py); [registry.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/registry.py); [protocol.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/protocol.py); [options.py](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/options.py); [plugins.md](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/docs/topics/plugins.md). --- # Examples Source: https://libtmux.org/en/py/stable/examples/ > Programs for sending input, capturing output, and building workspaces. Use these programs to send input, capture output, and build a workspace. Each example page includes its source and test coverage. Check those details before adapting an excerpt into a standalone program. ## Source and verification Port repositories use the following checks for their source examples. This site reads or copies those examples; a successful site build alone does not execute them: The test configuration includes [`README.md`]() and [`src/libtmux/`]() in its doctest collection. The `>>>` examples run against isolated tmux sessions. See [Testing with libtmux](https://libtmux.org/en/py/stable/guides/testing-with-libtmux/) for the fixture each of those test suites runs against, and each example page for the exact file a given snippet was quoted from. - [Attach and send keys](https://libtmux.org/en/py/stable/examples/attach-and-send-keys/): Find a session, send a command, and read its output. - [Capture pane output](https://libtmux.org/en/py/stable/examples/capture-pane-output/): Read a pane's screen and wait for output to appear. - [Build a workspace from a file](https://libtmux.org/en/py/stable/examples/workspace-from-file/): Create a session, windows, and panes from configuration. --- # Attach and send keys Source: https://libtmux.org/en/py/stable/examples/attach-and-send-keys/ > Get a session handle, send a command to a pane, and capture output. Get a session handle, send a command to a pane, and capture output. These examples use libtmux from your program; to attach your terminal interactively, see [Attaching to tmux](https://libtmux.org/en/py/stable/guides/attaching-to-tmux/). The examples include setup, error handling, and cleanup. [Source and verification](https://libtmux.org/en/py/stable/examples/attach-and-send-keys/#where-this-comes-from) identifies their files and checks. ```python >>> import libtmux >>> server = libtmux.Server() >>> session = server.new_session(session_name='demo') Session(...) >>> window = session.active_window >>> pane = window.split(shell='sh') >>> pane.capture_pane() ['$'] >>> pane.send_keys('echo "Hello world"', enter=True) >>> pane.capture_pane() ['$ echo "Hello world"', 'Hello world', '$'] ``` ## Finding an existing session instead For a script that runs repeatedly, look up a session before creating it. [Attaching to tmux](https://libtmux.org/en/py/stable/guides/attaching-to-tmux/#finding-a-session-instead-of-always-creating-one) shows that pattern, and [Filtering and querying, in practice](https://libtmux.org/en/py/stable/guides/querying-and-filtering/) covers absent and ambiguous matches. ## Where this comes from **Source:** [`src/libtmux/server.py`](), [`session.py`](), [`pane.py`]() docstrings **In this page:** hand-quoted, composed from three separate docstrings **Checked by:** `pytest` runs every `>>>` doctest (`testpaths` includes `src/libtmux`) against a real, isolated tmux session on every test run ### Source inclusion A `file="..."` fence reads the named source during the site build. Hand-quoted excerpts are copies; their source files and regions are listed above. --- # Capture pane output Source: https://libtmux.org/en/py/stable/examples/capture-pane-output/ > Run a complete program that captures a pane and waits for a complete output line. A pane runs asynchronously: sending a command does not mean its output is already on screen. Capture repeatedly until the expected line appears, with a deadline so a failed command cannot leave the program waiting forever. This complete program creates a private tmux server, captures its output, and cleans up. Follow the [setup and run instructions](https://libtmux.org/en/py/stable/examples/capture-pane-output/#setup-and-run) below. You need tmux and a Unix environment; no existing tmux session is required. ## Read what's on screen The program sends `printf` with a leading newline, then waits for the complete line `libtmux capture ready`. The newline keeps a late shell prompt off that line. Matching the whole line avoids mistaking the echoed command for its output. ```python title="capture.py" from pathlib import Path from tempfile import TemporaryDirectory from time import monotonic, sleep import libtmux with TemporaryDirectory(prefix="libtmux-capture-") as directory: server = libtmux.Server( socket_path=Path(directory) / "tmux.sock", config_file="/dev/null", ) try: session = server.new_session( session_name="capture", window_command="sh", environment={"ENV": "/dev/null"}, ) pane = session.active_window.active_pane pane.send_keys("printf '\\nlibtmux capture ready\\n'", literal=True) deadline = monotonic() + 5 while True: lines = pane.capture_pane() if "libtmux capture ready" in lines: print("\n".join(lines)) break if monotonic() >= deadline: raise TimeoutError("The pane did not print the expected line") sleep(0.05) finally: server.kill() ``` ## Wait for output or completion The program above checks the captured screen for up to five seconds. The short pause between checks limits polling; the observed output determines when the loop finishes. A tmux capture is a view of the screen and scrollback, so it can miss output that has already scrolled away. Use a stream or a completion signal for long-running commands when that distinction matters. [Capturing output](https://libtmux.org/en/py/stable/guides/capturing-output/) covers capture options, while [Sending keys](https://libtmux.org/en/py/stable/guides/sending-keys/#the-race-you-cant-see-from-the-call-site) explains why sending and waiting are separate operations. ## Setup and run Use an empty directory. The commands pin the library revision used to verify the program. Save the program as `capture.py`. With Python 3.10 or newer and uv installed: ```console $ uv run \ --with 'libtmux @ git+https://github.com/tmux-python/libtmux@9fdd083a8181a827889337b63cd4e6daea661a8c' \ capture.py ``` ## Where this comes from This complete program was run against the library revision pinned above. The displayed code is checked against the bytes from that run. --- # Workspace examples Source: https://libtmux.org/en/py/stable/workspace/examples/gallery/ > Start from complete configurations for pane layout, commands and environment. The examples below reproduce the pinned tmuxp YAML fixture corpus. Each record links to its source and, where present, its JSON twin. They illustrate configuration features; they are not all self-contained runnable projects. The `minimal` fixture and several other files omit window names despite the validator requiring them. Treat these as normalization and compatibility probes, not a promise that every fixture passes every load path. The [installation walkthrough](https://libtmux.org/en/py/stable/workspace/guides/installation/) supplies a complete runnable starting file. ## 2-pane-synchronized Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/2-pane-synchronized.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/2-pane-synchronized.json). ```yaml session_name: 2-pane-synchronized windows: - window_name: Two synchronized panes panes: - ssh server1 - ssh server2 options_after: synchronize-panes: on ``` ## 2-pane-vertical Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/2-pane-vertical.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/2-pane-vertical.json). ```yaml session_name: 2-pane-vertical windows: - window_name: my test window panes: - echo hello - echo hello ``` ## 3-pane Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/3-pane.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/3-pane.json). ```yaml session_name: 3-panes windows: - window_name: dev window layout: main-vertical shell_command_before: - cd ~/ panes: - shell_command: - cd /var/log - ls -al | grep \.log - echo hello - echo hello ``` ## 4-pane Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/4-pane.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/4-pane.json). ```yaml session_name: 4-pane-split windows: - window_name: dev window layout: tiled shell_command_before: - cd ~/ panes: - shell_command: - cd /var/log - ls -al | grep \.log - echo hello - echo hello - echo hello ``` ## blank-panes Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/blank-panes.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/blank-panes.json). ```yaml session_name: Blank pane test windows: # Emptiness will simply open a blank pane, if no shell_command_before. # All these are equivalent - window_name: Blank pane test panes: - - pane - blank - window_name: More blank panes panes: - null - shell_command: - shell_command: - # an empty string will be treated as a carriage return - window_name: Empty string (return) panes: - "" - shell_command: "" - shell_command: - "" # a pane can have other options but still be blank - window_name: Blank with options panes: - focus: true - start_directory: /tmp ``` ## env-variables Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/env-variables.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/env-variables.json). ```yaml start_directory: "${PWD}/test" shell_command_before: "echo ${PWD}" before_script: "${MY_ENV_VAR}/test3.sh" session_name: session - ${USER} (${MY_ENV_VAR}) windows: - window_name: editor panes: - shell_command: - tail -F /var/log/syslog start_directory: /var/log - window_name: logging for ${USER} options: automatic-rename: true panes: - shell_command: - htop - ls $PWD ``` ## focus-window-and-panes Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/focus-window-and-panes.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/focus-window-and-panes.json). ```yaml session_name: focus windows: - window_name: attached window focus: true panes: - shell_command: - echo hello - echo 'this pane should be selected on load' focus: true - shell_command: - cd /var/log - echo hello - window_name: second window shell_command_before: cd /var/log panes: - pane - shell_command: - echo 'this pane should be focused, when window switched to first time' focus: true - pane ``` ## main-pane-height-percentage Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/main-pane-height-percentage.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/main-pane-height-percentage.json). ```yaml session_name: main-pane-height start_directory: "~" windows: - layout: main-horizontal options: main-pane-height: 67% panes: - shell_command: - top start_directory: "~" - shell_command: - echo "hey" - shell_command: - echo "moo" window_name: my window name ``` ## main-pane-height Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/main-pane-height.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/main-pane-height.json). ```yaml session_name: main-pane-height start_directory: "~" windows: - layout: main-horizontal options: main-pane-height: 30 panes: - shell_command: - top start_directory: "~" - shell_command: - echo "hey" - shell_command: - echo "moo" window_name: my window name ``` ## minimal Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/minimal.yaml). ```yaml session_name: My tmux session windows: - panes: - ``` ## options Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/options.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/options.json). ```yaml session_name: test window options start_directory: "~" global_options: default-shell: /bin/sh default-command: /bin/sh options: main-pane-height: ${MAIN_PANE_HEIGHT} # works with env variables windows: - layout: main-horizontal options: automatic-rename: on panes: - shell_command: - man echo start_directory: "~" - shell_command: - echo "hey" - shell_command: - echo "moo" ``` ## pane-shell Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/pane-shell.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/pane-shell.json). ```yaml session_name: Pane shell example windows: - window_name: first window_shell: /usr/bin/python2 layout: even-vertical suppress_history: false options: remain-on-exit: true panes: - shell: /usr/bin/python3 shell_command: - print('This is python 3') - shell: /usr/bin/vim -u none shell_command: - iAll panes have the `remain-on-exit` setting on. - When you exit out of the shell or application, the panes will remain. - Use tmux command `:kill-pane` to remove the pane. - Use tmux command `:respawn-pane` to restart the shell in the pane. - Use and then `:q!` to get out of this vim window. :-) - shell_command: - print('Hello World 2') - shell: /usr/bin/top ``` ## plugin-system Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/plugin-system.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/plugin-system.json). ```yaml session_name: plugin-system plugins: - "tmuxp_plugin_extended_build.plugin.PluginExtendedBuild" windows: - window_name: editor layout: tiled shell_command_before: - cd ~/ panes: - shell_command: - cd /var/log - ls -al | grep *.log - echo "hello world" ``` ## session-environment Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/session-environment.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/session-environment.json). ```yaml session_name: Environment variables test environment: EDITOR: /usr/bin/vim DJANGO_SETTINGS_MODULE: my_app.settings.local SERVER_PORT: "8009" windows: - window_name: Django project panes: - ./manage.py runserver 0.0.0.0:${SERVER_PORT} - window_name: Another Django project environment: DJANGO_SETTINGS_MODULE: my_app.settings.local SERVER_PORT: "8010" panes: - ./manage.py runserver 0.0.0.0:${SERVER_PORT} - environment: DJANGO_SETTINGS_MODULE: my_app.settings.local-testing SERVER_PORT: "8011" shell_command: ./manage.py runserver 0.0.0.0:${SERVER_PORT} ``` ## shorthands Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/shorthands.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/shorthands.json). ```yaml session_name: shorthands windows: - window_name: long form panes: - shell_command: - echo 'did you know' - echo 'you can inline' - shell_command: echo 'single commands' - echo 'for panes' ``` ## skip-send-pane-level Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/skip-send-pane-level.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/skip-send-pane-level.json). ```yaml session_name: Skip command execution (pane-level) windows: - panes: - shell_command: echo "___$((1 + 3))___" enter: false - shell_command: - echo "___$((1 + 3))___"\; - echo "___$((1 + 3))___" enter: false ``` ## skip-send Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/skip-send.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/skip-send.json). ```yaml session_name: Skip command execution (command-level) windows: - panes: - shell_command: # You can see this - echo "___$((11 + 1))___" # This is skipped - cmd: echo "___$((1 + 3))___" enter: false ``` ## sleep-pane-level Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/sleep-pane-level.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/sleep-pane-level.json). ```yaml session_name: Pause / skip command execution (pane-level) windows: - panes: - # Wait 2 seconds before sending all commands in this pane sleep_before: 2 shell_command: - echo "___$((11 + 1))___" - cmd: echo "___$((1 + 3))___" - cmd: echo "___$((1 + 3))___" - cmd: echo "Stuff rendering here!" - cmd: echo "2 seconds later" ``` ## sleep-virtualenv Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/sleep-virtualenv.yaml). ```yaml session_name: virtualenv shell_command_before: # - cmd: source $(poetry env info --path)/bin/activate # - cmd: source `pipenv --venv`/bin/activate - cmd: source .venv/bin/activate sleep_before: 1 sleep_after: 1 windows: - panes: - shell_command: - ./manage.py runserver ``` ## sleep Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/sleep.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/sleep.json). ```yaml session_name: Pause / skip command execution (command-level) windows: - panes: - shell_command: # Executes immediately - echo "___$((11 + 1))___" # Delays before sending 2 seconds - cmd: echo "___$((1 + 3))___" sleep_before: 2 # Executes immediately - cmd: echo "___$((1 + 3))___" # Pauses 2 seconds after - cmd: echo "Stuff rendering here!" sleep_after: 2 # Executes after earlier commands (after 2 sec) - cmd: echo "2 seconds later" ``` ## start-directory Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/start-directory.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/start-directory.json). ```yaml session_name: start directory start_directory: /var/ windows: - window_name: should be /var/ panes: - shell_command: - echo "\033c - it trickles down from session-level" - echo hello - window_name: should be /var/log start_directory: log panes: - shell_command: - echo '\033c - window start_directory concatenates to session start_directory - if it is not absolute' - echo hello - window_name: should be ~ start_directory: "~" panes: - shell_command: - 'echo \\033c ~ has precedence. note: remember to quote ~ in YAML' - echo hello - window_name: should be /bin start_directory: /bin panes: - echo '\033c absolute paths also have precedence.' - echo hello - window_name: should be workspace file's dir start_directory: ./ panes: - shell_command: - echo '\033c - ./ is relative to workspace file location - ../ will be parent of workspace file - ./test will be \"test\" dir inside dir of workspace file' - shell_command: - echo '\033c - This way you can load up workspaces from projects and maintain - relative paths.' ``` ## suppress-history Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/suppress-history.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/suppress-history.json). ```yaml session_name: suppress suppress_history: false windows: - window_name: appended focus: true suppress_history: false panes: - echo "window in the history!" - window_name: suppressed suppress_history: true panes: - echo "window not in the history!" - window_name: default panes: - echo "session in the history!" - window_name: mixed suppress_history: false panes: - shell_command: - echo "command in the history!" suppress_history: false - shell_command: - echo "command not in the history!" suppress_history: true - shell_command: - echo "window in the history!" ``` ## window-index Pinned Python reference fixture. This docs run did not execute its full application environment. [YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/window-index.yaml); [JSON source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/window-index.json). ```yaml session_name: Window index example windows: - window_name: zero panes: - echo "this window's index will be zero" - window_name: five panes: - echo "this window's index will be five" window_index: 5 - window_name: one panes: - echo "this window's index will be one" ``` ## Prerequisites and portability SSH examples need the named hosts. Django and virtualenv examples need their project and environment. The plugin example needs its named Python plugin. Shell paths, log directories, top, `htop`, and editors are host-specific. The pane-shell fixture includes an obsolete Python 2 path; it is retained as upstream evidence, not recommended installation guidance. Review [configuration](https://libtmux.org/en/py/stable/workspace/configuration/), [commands](https://libtmux.org/en/py/stable/workspace/configuration/commands/), and [compatibility](https://libtmux.org/en/py/stable/workspace/reference/compatibility/) before adapting these fixtures. [tmuxp reference source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Guides Source: https://libtmux.org/en/py/stable/guides/ > Task-oriented walkthroughs that sit between the concepts and each port's own API reference. Use these guides to connect to tmux, send input, capture output, query objects, and test your program. [Concepts](https://libtmux.org/en/py/stable/concepts/) explains the object model and transport choices. [Examples](https://libtmux.org/en/py/stable/examples/) provides complete programs with setup and cleanup. - [Getting started](https://libtmux.org/en/py/stable/guides/getting-started/): Install tmux and run a complete example. - [Attaching to tmux](https://libtmux.org/en/py/stable/guides/attaching-to-tmux/): Select a socket and find or create a session. - [Sending keys](https://libtmux.org/en/py/stable/guides/sending-keys/): Send literal text, named keys, and Enter. - [Capturing output](https://libtmux.org/en/py/stable/guides/capturing-output/): Read the screen or scrollback and wait for a result. - [Filtering and querying](https://libtmux.org/en/py/stable/guides/querying-and-filtering/): Find objects and handle missing or ambiguous matches. - [Testing](https://libtmux.org/en/py/stable/guides/testing-with-libtmux/): Use isolated tmux servers and manage test cleanup. --- # Getting started Source: https://libtmux.org/en/py/stable/guides/getting-started/ > Run a complete program with this language library. Use [`libtmux`]() to create sessions, send input and read pane output from Python. The [complete capture program](https://libtmux.org/en/py/stable/examples/capture-pane-output/) includes imports, its entry point, project files, dependency setup and a run command. ## Run the smallest thing that proves it works Open that example in an empty directory and save the files using their displayed names. Its setup pins the library revision that was used to execute the program. It needs tmux on `PATH` and the native tools named on the example page. The program creates a private server, sends a command, waits for the complete line `libtmux capture ready`, then cleans up. A timeout or command failure is reported. It does not need an existing tmux session. ## What just happened [`Pane.capture_pane`]() returns a list of lines. The complete program compares whole lines, uses a monotonic deadline and closes its private server in [`finally`](). The echoed shell command cannot satisfy its output check. ## Connect to an existing server Use the [complete attach program](https://libtmux.org/en/py/stable/guides/attaching-to-tmux/) to select an existing socket and find the `work` session. That example leaves tmux running; its launcher owns setup and cleanup for trying it safely. ## Where to go next [Sending keys](https://libtmux.org/en/py/stable/guides/sending-keys/) explains input, and [Capturing output](https://libtmux.org/en/py/stable/guides/capturing-output/) explains completion. [Querying and filtering](https://libtmux.org/en/py/stable/guides/querying-and-filtering/) selects a target. --- # Attaching to tmux Source: https://libtmux.org/en/py/stable/guides/attaching-to-tmux/ > Connect to an existing tmux server and find a session with Python. Connect a [`Server`]() to an explicit socket and find the existing `work` session. The program prints its name and leaves the tmux server running. It reports an error if the connection fails or the session is absent. This controls tmux from your program. To open a session in your terminal, use [`tmux attach-session`](https://libtmux.org/en/tmux/latest/manual/attach-session/); the [shared guide](https://libtmux.org/en/tmux/guides/attaching-to-tmux/) covers interactive attachment and detaching. ## Connect to an existing server Save the complete program as `connect.py`. `LIBTMUX_SOCKET_PATH` selects the existing server. The launcher below supplies a private socket for trying the example. ```python title="connect.py" import os import libtmux server = libtmux.Server(socket_path=os.environ["LIBTMUX_SOCKET_PATH"]) session = server.sessions.get(session_name="work") print(session.session_name) ``` ## Setup and run Use an empty directory on Linux with Git and tmux 3.2a or newer installed. This example was checked with Python 3.14.6. Save the launcher as `run.sh`. It starts an isolated tmux server, runs the program, checks that the session still exists, then stops only that server. Cleanup runs after failures too. A failed shutdown keeps its socket directory and prints its location for inspection. ```sh title="run.sh" #!/bin/sh set -eu binary=$(command -v tmux) directory=$(mktemp -d "${TMPDIR:-/tmp}/libtmux-py-attach.XXXXXX") socket="$directory/tmux.sock" cleanup() { status=$? trap - 0 HUP INT TERM if [ -S "$socket" ] && ! "$binary" -S "$socket" kill-server; then printf 'Cannot stop tmux; kept %s\n' "$directory" >&2 exit 1 fi rm -rf "$directory" || exit 1 exit "$status" } trap cleanup 0 trap 'exit 1' HUP INT TERM unset TMUX TMUX_PANE export LIBTMUX_SOCKET_PATH="$socket" TMUX_BIN="$binary" "$binary" -S "$socket" -f /dev/null new-session -d -s work /bin/cat "$@" "$binary" -S "$socket" has-session -t '=work' ``` Fetch the verified library revision, build, and run: ```console $ sh run.sh uv run \ --with 'libtmux @ git+https://github.com/tmux-python/libtmux@9fdd083a8181a827889337b63cd4e6daea661a8c' \ connect.py ``` The program prints `work`. To use an existing server of your own, set `LIBTMUX_SOCKET_PATH` to its socket and run the program without the launcher. That launcher is responsible for the demonstration server's lifetime. ## Find or create a session The example only looks up a session. If your application creates a session after an unsuccessful lookup, another client may create the same name between those operations. Handle the creation error instead of assuming the lookup reserves the name. For a complete program that starts and owns its server, see [Capture pane output](https://libtmux.org/en/py/stable/examples/capture-pane-output/). Continue with [Sending keys](https://libtmux.org/en/py/stable/guides/sending-keys/) once you have a pane handle. --- # Sending keys Source: https://libtmux.org/en/py/stable/guides/sending-keys/ > Send text and named keys, then wait for the result. [`Pane.send_keys`]() accepts literal text with `literal=True`. It sends Enter by default; use `enter=False` to type without submitting, then call [`Pane.enter`](). The complete example sets literal mode explicitly. ## Run the complete program [Capture pane output](https://libtmux.org/en/py/stable/examples/capture-pane-output/) supplies the full Python program, imports, project setup and run command. It starts a private server, sends a command, checks a complete output line and cleans up. ## Literal text, key names, and whether Enter follows Choose the method and options for the input you mean to send. Literal text still goes to an application: a shell interprets its quoting, expansions and commands. Key-name handling and shell interpretation are separate concerns. ## The race you can't see from the call site A successful send means tmux accepted input. The pane's program may still be starting or processing that input. Wait for the state the next operation needs. Terminal echo alone does not prove command completion. [`Pane.capture_pane`]() returns a list of lines. The complete program compares whole lines, uses a monotonic deadline and closes its private server in [`finally`](). The echoed shell command cannot satisfy its output check. ## Where to go next [Capturing output](https://libtmux.org/en/py/stable/guides/capturing-output/) covers the output side. [Attaching to tmux](https://libtmux.org/en/py/stable/guides/attaching-to-tmux/) connects to a server you already own. --- # Capturing output Source: https://libtmux.org/en/py/stable/guides/capturing-output/ > Read pane output with an explicit completion condition. [`Pane.capture_pane`]() returns a list of lines. The complete program compares whole lines, uses a monotonic deadline and closes its private server in [`finally`](). The echoed shell command cannot satisfy its output check. ## Run the complete program [Capture pane output](https://libtmux.org/en/py/stable/examples/capture-pane-output/) includes the full Python program, all imports, project files and a run command. The program matches `libtmux capture ready` as a complete line, so the echoed command cannot satisfy the check. It creates and cleans up its own tmux server. ## Visible pane vs. scrollback A capture reads terminal state. Lines that have scrolled beyond retained history are unavailable, and repeated captures can miss intermediate output. Choose the range your task needs and use a stream or completion signal when every output event matters. ## Wait for the expected text Use a deadline and a specific output predicate. The example's short polling pause limits work between checks; it is the observed line that determines completion. [Sending keys](https://libtmux.org/en/py/stable/guides/sending-keys/) explains why returning from the input call is not a completion signal. ## Wait for a completion signal A program can also signal a dedicated tmux channel. Use the same server endpoint for the sender and waiter and a new channel name per task. [Waiting and retrying](https://libtmux.org/en/py/stable/topics/waiting-and-retry/) documents this port's waiting APIs and failure handling. --- # Querying and filtering Source: https://libtmux.org/en/py/stable/guides/querying-and-filtering/ > Choose a target and handle missing or ambiguous results. [`server.sessions.get(session_name="work")`]() selects by exact name and reports an absent result. The complete program below uses that lookup, prints the session name and leaves the existing server running. ## Require exactly one match [Attaching to tmux](https://libtmux.org/en/py/stable/guides/attaching-to-tmux/) provides the complete Python program and its setup. It searches an existing server for `work`, prints the name and reports an absent session. Its launcher checks that the server remains running. For a more general predicate, decide whether zero or several results are valid before indexing a collection. Keep lookup and command failures visible: another client can change the server between a read and the operation using its result. ## Declarative filters [Filtering and queries](https://libtmux.org/en/py/stable/concepts/queries/) describes this port's query APIs, accepted fields and result-count contracts. Use that contract when storing a query in configuration. ## Case-insensitive matching Choose case handling explicitly when your query needs it. The attach program uses exact case because the intended session is named `work`. ## Push the filter into tmux, or read once and filter locally A tmux-side filter reduces returned rows; a captured collection can answer several local queries from one read. Neither reserves the result. Check unexpectedly empty format values before assuming that an object does not exist. --- # Testing with libtmux Source: https://libtmux.org/en/py/stable/guides/testing-with-libtmux/ > Use an isolated server and check cleanup failures. The pytest plugin supplies `server` and `session` fixtures. A session fixture also creates its server. Use [`session_params`]() for fixture setup options. For a standalone program, the complete capture example uses an explicit private socket and [`finally`]() cleanup. ## Run a complete example [Capture pane output](https://libtmux.org/en/py/stable/examples/capture-pane-output/) includes a complete Python executable, imports, dependency setup and cleanup. Its output check fails when the expected line does not arrive before the deadline. Start with that program when adapting the pattern to your own test runner. ## Keep server ownership explicit Give each test a private socket and a known tmux configuration. Stop the server the test creates, including when startup or an assertion fails. Preserve the original failure and report cleanup errors so a leaked server remains visible. A connection to an existing server has a different lifetime. The [attach program](https://libtmux.org/en/py/stable/guides/attaching-to-tmux/) leaves that server running and lets its launcher own cleanup. ## Wait for the state you assert Wait for the actual output or completion condition with a deadline. [Sending keys](https://libtmux.org/en/py/stable/guides/sending-keys/) returning successfully does not establish that the application finished. [Capturing output](https://libtmux.org/en/py/stable/guides/capturing-output/) explains the difference between a screen snapshot and a stream of output. --- # Install and load a workspace Source: https://libtmux.org/en/py/stable/workspace/guides/installation/ > Build the workspace command and load a session on a private tmux socket. The runnable terminal loader is the separate Python application tmuxp. Its documented prerequisites are Python 3.10 or newer and tmux 3.2 or newer. Install it in an isolated tool environment with uv: ```console $ uv tool install tmuxp ``` The tool environment owns tmuxp's Python dependencies, including libtmux. ## Create the input Save this file as [`workspace.yaml`](https://libtmux.org/en/py/stable/workspace/guides/installation/#create-the-input) in a writable directory: ```yaml session_name: workspace-guide windows: - window_name: editor layout: even-horizontal panes: - echo ready - echo second ``` Load the session detached. Reserve the socket name for this walkthrough: ```console $ tmuxp load \ -L workspace-guide \ -d \ workspace.yaml ``` Inspect the two panes: ```console $ tmux -L workspace-guide list-panes -t '=workspace-guide:editor' ``` Attach when ready: ```console $ tmux -L workspace-guide attach-session -t '=workspace-guide' ``` Detach with your configured tmux detach binding. Before cleanup, optionally try [export and reload](https://libtmux.org/en/py/stable/workspace/guides/export-session/). Remove only this walkthrough's session when finished: ```console $ tmux -L workspace-guide kill-session -t '=workspace-guide' ``` ## Continue [Discovery](https://libtmux.org/en/py/stable/workspace/guides/discovery/) explains project files and saved names. [Configuration](https://libtmux.org/en/py/stable/workspace/configuration/) describes accepted fields, and [load](https://libtmux.org/en/py/stable/workspace/cli/load/) documents all flags. [tmuxp reference source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Find saved workspaces Source: https://libtmux.org/en/py/stable/workspace/guides/discovery/ > Resolve explicit files, project directories and saved workspace names. Use an explicit YAML or JSON file path when you need an unambiguous input. A directory resolves its project configuration, and a saved name resolves through the tmuxp configuration roots. ## Global directories An existing `TMUXP_CONFIGDIR` takes precedence, followed by the XDG configuration directory and then the legacy [`~/.tmuxp`](https://libtmux.org/en/py/stable/workspace/guides/discovery/) directory. A nonexistent explicit directory does not automatically win discovery. See [environment](https://libtmux.org/en/py/stable/workspace/configuration/environment/) for the relevant variables. ## Project files Project discovery walks from the current directory toward its ancestors, stopping at home or the filesystem root. It selects at most one candidate per directory, preferring [`.tmuxp.yaml`](), then [`.tmuxp.yml`](https://libtmux.org/en/py/stable/workspace/guides/discovery/), then [`.tmuxp.json`](https://libtmux.org/en/py/stable/workspace/guides/discovery/). Nearer directories come first. It does not recursively enumerate child projects. Load the current project's configuration: ```console $ tmuxp load . ``` The normal command can attach or prompt. Use `-d` when you want detached execution and select `-L` or `-S` for an isolated server. [ls](https://libtmux.org/en/py/stable/workspace/cli/ls/), [search](https://libtmux.org/en/py/stable/workspace/cli/search/), and [edit](https://libtmux.org/en/py/stable/workspace/cli/edit/) use the same discovery concepts with their own result and error behavior. [tmuxp reference source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Automate workspace operations Source: https://libtmux.org/en/py/stable/workspace/guides/automation/ > Run detached commands with explicit inputs and machine-readable results. Pass an explicit workspace file, dedicated socket and `-d` when running tmuxp from a script. `--yes` answers confirmations; it does not supply every missing choice. ```console $ tmuxp load -L workspace-guide -d workspace.yaml ``` Use [`ls --json`](https://libtmux.org/en/py/stable/workspace/cli/ls/) to read discovered workspace records: ```console $ tmuxp ls --json ``` The output is an object with a `workspaces` array. Search has different empty output and error behavior; read [search](https://libtmux.org/en/py/stable/workspace/cli/search/) and [exit codes](https://libtmux.org/en/py/stable/workspace/reference/exit-codes/) before building a pipeline. Use [export and reload](https://libtmux.org/en/py/stable/workspace/guides/export-session/) to capture a session. Review the resulting commands and paths rather than treating capture as a complete backup. --- # Export and reload a session Source: https://libtmux.org/en/py/stable/workspace/guides/export-session/ > Capture a running session, inspect the document and load a second copy. Use the session created by the [installation walkthrough](https://libtmux.org/en/py/stable/workspace/guides/installation/). Capture it to a new YAML destination: ```console $ tmuxp freeze \ -L workspace-guide \ --workspace-format yaml \ --save-to captured-workspace.yaml \ --yes \ workspace-guide ``` Review the output file. Capture cannot reconstruct original scripts, shell history, plugin decisions, comments, or every application's state. Compare window and pane topology, directories, layouts, environment, and options explicitly. Replay under a new name on the same dedicated server: ```console $ tmuxp load \ -L workspace-guide \ -d \ -s workspace-replay \ captured-workspace.yaml ``` Inspect the replay: ```console $ tmux -L workspace-guide list-panes -t '=workspace-replay' ``` Remove the replay when finished: ```console $ tmux -L workspace-guide kill-session -t '=workspace-replay' ``` The [freeze reference](https://libtmux.org/en/py/stable/workspace/cli/freeze/) explains prompts and overwrite behavior. [convert](https://libtmux.org/en/py/stable/workspace/cli/convert/) changes document representation without validating whether a workspace can be loaded. [tmuxp reference source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Troubleshoot a workspace Source: https://libtmux.org/en/py/stable/workspace/guides/troubleshooting/ > Find the failed stage before retrying a workspace operation. Start by identifying the failing stage. A parser error happens before a workspace is loaded. A missing file is a discovery problem. An accepted document can still fail during tmux creation, shell startup, command dispatch, or a plugin callback. ## Arguments and files Use the [command reference](https://libtmux.org/en/py/stable/workspace/cli/) for local flag meanings. Place root `--color` and `--log-level` before the command. Keep multiple load filenames together. Both importer children require a source argument. Confirm an explicit file works before investigating saved-name discovery. ## Configuration and commands Check the [configuration reference](https://libtmux.org/en/py/stable/workspace/configuration/) and the [example gallery](https://libtmux.org/en/py/stable/workspace/examples/gallery/). YAML parsing alone does not validate keys or prove builder support. A missing shell executable, directory, plugin package, SSH target, or application can prevent an otherwise valid workspace from behaving as intended. Commands are sent into panes and can require shell readiness. [`enter`](https://libtmux.org/en/py/stable/workspace/configuration/panes/#pane-keys-enter)`: false` intentionally leaves text unsubmitted. Delays are measured in seconds; explicit zero and omission differ. See [commands](https://libtmux.org/en/py/stable/workspace/configuration/commands/) and [hooks](https://libtmux.org/en/py/stable/workspace/configuration/hooks/). ## Diagnostics and remaining state ```console $ tmuxp debug-info --json ``` Inspect raw tmux values before sharing diagnostics. Use the same `-L` or `-S` endpoint when inspecting a failed load. A partial build can leave sessions, windows, and panes behind; inspect them before cleanup. Do not assume rollback or kill an unrelated default server. [tmuxp reference source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Python workspace internals Source: https://libtmux.org/en/py/stable/workspace/internals/ > How tmuxp loads configuration and builds sessions through libtmux. These pages describe tmuxp's internal implementation for contributors and extension authors. The Python interfaces have no stability guarantee and may change between releases. Use [tmuxp load](https://libtmux.org/en/py/stable/workspace/guides/) to launch a workspace from the terminal. ## Builder pipeline The CLI reads YAML or JSON, expands shorthand and variables, applies inherited defaults, and passes the result to a workspace builder. The builder uses libtmux to create the session, windows, and panes. The CLI then handles attachment or client switching. - [Topics](https://libtmux.org/en/py/stable/workspace/internals/topics/) explain the loader pipeline and builder extension points. - [Examples](https://libtmux.org/en/py/stable/workspace/internals/examples/) show expansion and building on an isolated server. - [API](https://libtmux.org/en/py/stable/workspace/reference/) links the internal loading, building, and freezing interfaces. The upstream [Internals documentation](https://tmuxp.git-pull.com/internals/) contains the full architecture and module reference. Use the [libtmux Python API](https://libtmux.org/en/py/stable/reference/) for general tmux programming. --- # Python workspace builder behavior Source: https://libtmux.org/en/py/stable/workspace/internals/topics/ > tmuxp's internal configuration pipeline, builder selection, and session handling. The CLI separates configuration processing, construction, and attachment. These Python implementation interfaces have no stability guarantee. ## Expand before building The loader reads YAML or JSON, expands command shorthand, variables, and paths, then applies inherited defaults. The builder expects the expanded configuration. The [internal example](https://libtmux.org/en/py/stable/workspace/internals/examples/) shows this sequence with an isolated libtmux server. ## Select a builder [`ClassicWorkspaceBuilder`]() is the default builder. `workspace_builder` selects an importable class or a registered entry point; `workspace_builder_paths` adds explicitly configured import directories. Plugins and custom builders run inside the Python process. Those extension imports are not portable workspace data for the other language ports. The classic builder accepts an optional existing session and an append choice. Failure handling depends on the operation and CLI path; a workspace build does not have universal transactional rollback. The CLI owns its existing-session prompts and the attachment or client-switching workflow. See the upstream [custom builder guide](https://tmuxp.git-pull.com/topics/custom-workspace-builders/) for extension configuration and the [API](https://libtmux.org/en/py/stable/workspace/reference/) for interface contracts. [Configuration loader](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/loader.py); [Classic builder](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/classic.py). --- # Python workspace builder example Source: https://libtmux.org/en/py/stable/workspace/internals/examples/ > An isolated example of tmuxp internal configuration expansion and session building. This example demonstrates tmuxp's internal builder pipeline. These Python interfaces have no stability guarantee. Load workspace files through the [CLI examples](https://libtmux.org/en/py/stable/workspace/examples/) for normal use. ## Build from Python data Run this inside an environment containing tmuxp and its compatible libtmux dependency. The example expands shorthand and inherited defaults before calling the classic builder, then removes its dedicated server. ```python from uuid import uuid4 import libtmux from tmuxp.workspace import loader from tmuxp.workspace.builder import WorkspaceBuilder config = { "session_name": "workspace-example", "windows": [ {"window_name": "editor", "panes": ["echo ready", "echo ready"]} ], } expanded = loader.trickle(loader.expand(config)) server = libtmux.Server(socket_name=f"workspace-{uuid4().hex}") try: builder = WorkspaceBuilder(session_config=expanded, server=server) builder.build() print(builder.session.name) print(len(builder.session.windows)) finally: server.kill() ``` The builder stores the resulting session on [`ClassicWorkspaceBuilder.session`](). Its `build` method does not return that session as the return value. The code uses a new socket for each run so cleanup cannot select a normal user server. ## Further reading The example combines the loader sequence used by the CLI with the classic builder's documented API. The upstream builder tests exercise its expanded configuration contract, and freezer tests cover reading live sessions back into configuration. Read the upstream [configuration examples](https://tmuxp.git-pull.com/configuration/examples/) for focus, layouts, directories, environment values, and command shorthand. Those examples depend on their commands and paths; inspect each file before loading it on your own server. [Builder examples and contract](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/classic.py); [Builder tests](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/tests/workspace/test_builder.py). --- # Python workspace internal API Source: https://libtmux.org/en/py/stable/workspace/reference/ > tmuxp APIs for expanding configuration, building sessions, and exporting layouts. tmuxp's workspace APIs are internal implementation details with no stability guarantee. They use libtmux's [`Server`](), [`Session`](), [`Window`](), and [`Pane`]() objects for tmux control. Use the [CLI guide](https://libtmux.org/en/py/stable/guides/) to load workspace files. ## Load and validate [`tmuxp.workspace.loader.expand`]() normalizes shorthand, variables, and paths. [`loader.trickle`]() applies inherited configuration after expansion. Both operate on workspace dictionaries. [`validation.validate_schema`]() checks required structure; it is not a complete machine-readable schema of every runtime behavior. Consult the upstream [loader API](https://tmuxp.git-pull.com/internals/api/workspace/loader/) and [validation API](https://tmuxp.git-pull.com/internals/api/workspace/validation/) for parameter and error details. ## Build and extend [`tmuxp.workspace.builder.WorkspaceBuilder`]() is the compatibility alias for [`ClassicWorkspaceBuilder`](). Construct it with expanded `session_config` and a libtmux server, call `build`, then read [`ClassicWorkspaceBuilder.session`](). [`WorkspaceBuilderProtocol`]() defines the interface used by the CLI, including construction callbacks, building into an optional existing session, and session discovery. The registry resolves named entry points or import paths. Use the upstream [builder API](https://tmuxp.git-pull.com/internals/api/workspace/builder/) and [custom builder guide](https://tmuxp.git-pull.com/topics/custom-workspace-builders/) when implementing an extension. ## Export and CLI [`tmuxp.workspace.freezer.freeze(session)`]() reads a live session into a configuration dictionary. [`freezer.inline`]() compacts that expanded structure for a file. The [freezer API](https://tmuxp.git-pull.com/internals/api/workspace/freezer/) documents both operations. The [CLI reference](https://tmuxp.git-pull.com/cli/) covers loading, freezing, listing, searching, editing, importing, and converting workspaces. These are application commands, separate from the language-level workspace builder. [Public builder exports](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/builder/__init__.py) ## API declarations - [tmuxp.exc.ActiveSessionMissingWorkspaceException](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-activesessionmissingworkspaceexception/) - [tmuxp.workspace.builder.available_builders](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-builder-available_builders/) - [tmuxp.exc.BeforeLoadScriptError](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-beforeloadscripterror/) - [tmuxp.exc.BeforeLoadScriptNotExists](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-beforeloadscriptnotexists/) - [tmuxp.workspace.builder.ClassicWorkspaceBuilder](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-builder-classicworkspacebuilder/) - [tmuxp.cli.cli](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-cli/) - [tmuxp.cli.CLI_DESCRIPTION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-cli_description/) - [tmuxp.cli.debug_info.CLIDebugInfoNamespace](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-debug_info-clidebuginfonamespace/) - [tmuxp.cli.freeze.CLIFreezeNamespace](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-freeze-clifreezenamespace/) - [tmuxp.cli.load.CLILoadNamespace](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-load-cliloadnamespace/) - [tmuxp.cli.ls.CLILsNamespace](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-ls-clilsnamespace/) - [tmuxp.cli.CLINamespace](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-clinamespace/) - [tmuxp.cli.search.CLISearchNamespace](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-clisearchnamespace/) - [tmuxp.cli.shell.CLIShellNamespace](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-shell-clishellnamespace/) - [tmuxp.workspace.builder.classic.COLUMNS_FALLBACK](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-builder-classic-columns_fallback/) - [tmuxp.cli.convert.command_convert](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-convert-command_convert/) - [tmuxp.cli.debug_info.command_debug_info](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-debug_info-command_debug_info/) - [tmuxp.cli.edit.command_edit](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-edit-command_edit/) - [tmuxp.cli.freeze.command_freeze](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-freeze-command_freeze/) - [tmuxp.cli.import_config.command_import](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-import_config-command_import/) - [tmuxp.cli.import_config.command_import_teamocil](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-import_config-command_import_teamocil/) - [tmuxp.cli.import_config.command_import_tmuxinator](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-import_config-command_import_tmuxinator/) - [tmuxp.cli.load.command_load](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-load-command_load/) - [tmuxp.cli.ls.command_ls](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-ls-command_ls/) - [tmuxp.cli.search.command_search](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-command_search/) - [tmuxp.cli.shell.command_shell](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-shell-command_shell/) - [tmuxp.cli.search.compile_search_patterns](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-compile_search_patterns/) - [tmuxp.plugin.Config](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-plugin-config/) - [tmuxp.cli.convert.CONVERT_DESCRIPTION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-convert-convert_description/) - [tmuxp.cli.convert.ConvertUnknownFileType](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-convert-convertunknownfiletype/) - [tmuxp.cli.convert.create_convert_subparser](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-convert-create_convert_subparser/) - [tmuxp.cli.debug_info.create_debug_info_subparser](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-debug_info-create_debug_info_subparser/) - [tmuxp.cli.edit.create_edit_subparser](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-edit-create_edit_subparser/) - [tmuxp.cli.freeze.create_freeze_subparser](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-freeze-create_freeze_subparser/) - [tmuxp.cli.import_config.create_import_subparser](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-import_config-create_import_subparser/) - [tmuxp.cli.load.create_load_subparser](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-load-create_load_subparser/) - [tmuxp.cli.ls.create_ls_subparser](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-ls-create_ls_subparser/) - [tmuxp.cli.create_parser](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-create_parser/) - [tmuxp.cli.search.create_search_subparser](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-create_search_subparser/) - [tmuxp.cli.shell.create_shell_subparser](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-shell-create_shell_subparser/) - [tmuxp.cli.debug_info.DEBUG_INFO_DESCRIPTION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-debug_info-debug_info_description/) - [tmuxp.log.debug_log_template](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-log-debug_log_template/) - [tmuxp.log.DebugLogFormatter](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-log-debuglogformatter/) - [tmuxp.plugin.DEFAULT_CONFIG](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-plugin-default_config/) - [tmuxp.cli.search.DEFAULT_FIELDS](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-default_fields/) - [tmuxp.shell.detect_best_shell](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-detect_best_shell/) - [tmuxp.cli.edit.EDIT_DESCRIPTION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-edit-edit_description/) - [tmuxp.exc.EmptyWorkspaceException](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-emptyworkspaceexception/) - [tmuxp.cli.search.evaluate_match](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-evaluate_match/) - [tmuxp.workspace.loader.expand](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-loader-expand/) - [tmuxp.workspace.loader.expand_cmd](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-loader-expand_cmd/) - [tmuxp.workspace.loader.expandshell](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-loader-expandshell/) - [tmuxp.cli.search.extract_workspace_fields](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-extract_workspace_fields/) - [tmuxp.cli.search.FIELD_ALIASES](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-field_aliases/) - [tmuxp.workspace.finders.find_local_workspace_files](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-finders-find_local_workspace_files/) - [tmuxp.cli.search.find_search_matches](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-find_search_matches/) - [tmuxp.workspace.finders.find_workspace_file](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-finders-find_workspace_file/) - [tmuxp.workspace.freezer.freeze](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-freezer-freeze/) - [tmuxp.cli.freeze.FREEZE_DESCRIPTION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-freeze-freeze_description/) - [tmuxp.shell.get_bpython](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-get_bpython/) - [tmuxp.shell.get_code](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-get_code/) - [tmuxp.util.get_current_pane](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-util-get_current_pane/) - [tmuxp.workspace.builder.get_default_columns](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-builder-get_default_columns/) - [tmuxp.workspace.builder.get_default_rows](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-builder-get_default_rows/) - [tmuxp.shell.get_ipython](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-get_ipython/) - [tmuxp.shell.get_ipython_arguments](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-get_ipython_arguments/) - [tmuxp.shell.get_launch_args](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-get_launch_args/) - [tmuxp.util.get_pane](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-util-get_pane/) - [tmuxp.shell.get_ptipython](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-get_ptipython/) - [tmuxp.shell.get_ptpython](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-get_ptpython/) - [tmuxp.util.get_session](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-util-get_session/) - [tmuxp.cli.import_config.get_teamocil_dir](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-import_config-get_teamocil_dir/) - [tmuxp.cli.import_config.get_tmuxinator_dir](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-import_config-get_tmuxinator_dir/) - [tmuxp.util.get_window](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-util-get_window/) - [tmuxp.workspace.finders.get_workspace_dir](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-finders-get_workspace_dir/) - [tmuxp.workspace.finders.get_workspace_dir_candidates](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-finders-get_workspace_dir_candidates/) - [tmuxp.shell.has_bpython](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-has_bpython/) - [tmuxp.shell.has_ipython](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-has_ipython/) - [tmuxp.shell.has_ptipython](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-has_ptipython/) - [tmuxp.shell.has_ptpython](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-has_ptpython/) - [tmuxp.cli.search.highlight_matches](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-highlight_matches/) - [tmuxp.cli.import_config.import_config](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-import_config-import_config/) - [tmuxp.cli.import_config.IMPORT_DESCRIPTION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-import_config-import_description/) - [tmuxp.workspace.importers.import_teamocil](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-importers-import_teamocil/) - [tmuxp.workspace.importers.import_tmuxinator](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-importers-import_tmuxinator/) - [tmuxp.cli.import_config.ImportConfigFn](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-import_config-importconfigfn/) - [tmuxp.workspace.finders.in_cwd](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-finders-in_cwd/) - [tmuxp.workspace.finders.in_dir](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-finders-in_dir/) - [tmuxp.workspace.freezer.inline](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-freezer-inline/) - [tmuxp.cli.search.InvalidFieldError](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-invalidfielderror/) - [tmuxp.workspace.validation.InvalidPluginsValidationError](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-validation-invalidpluginsvalidationerror/) - [tmuxp.exc.InvalidWorkspaceBuilder](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-invalidworkspacebuilder/) - [tmuxp.exc.InvalidWorkspaceBuilderOption](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-invalidworkspacebuilderoption/) - [tmuxp.workspace.finders.is_pure_name](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-finders-is_pure_name/) - [tmuxp.workspace.finders.is_workspace_file](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-finders-is_workspace_file/) - [tmuxp.shell.launch](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-shell-launch/) - [tmuxp.log.LEVEL_COLORS](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-log-level_colors/) - [tmuxp.plugin.LIBTMUX_MAX_VERSION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-plugin-libtmux_max_version/) - [tmuxp.plugin.LIBTMUX_MIN_VERSION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-plugin-libtmux_min_version/) - [tmuxp.cli.load.LOAD_DESCRIPTION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-load-load_description/) - [tmuxp.cli.load.load_plugins](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-load-load_plugins/) - [tmuxp.cli.load.load_workspace](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-load-load_workspace/) - [tmuxp.workspace.finders.LOCAL_WORKSPACE_FILES](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-finders-local_workspace_files/) - [tmuxp.log.LogFormatter](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-log-logformatter/) - [tmuxp.cli.ls.LS_DESCRIPTION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-ls-ls_description/) - [tmuxp.cli.search.normalize_fields](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-normalize_fields/) - [tmuxp.cli.ns](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-ns/) - [tmuxp.util.oh_my_zsh_auto_title](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-util-oh_my_zsh_auto_title/) - [tmuxp.exc.PaneNotFound](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-panenotfound/) - [tmuxp.workspace.options.PaneReadiness](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-options-panereadiness/) - [tmuxp.cli.search.parse_query_terms](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-parse_query_terms/) - [tmuxp.workspace.builder.prepended_sys_path](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-builder-prepended_sys_path/) - [tmuxp.cli.utils.prompt](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-utils-prompt/) - [tmuxp.cli.utils.prompt_bool](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-utils-prompt_bool/) - [tmuxp.cli.utils.prompt_choices](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-utils-prompt_choices/) - [tmuxp.cli.utils.prompt_yes_no](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-utils-prompt_yes_no/) - [tmuxp.util.PY2](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-util-py2/) - [tmuxp.workspace.builder.resolve_builder_class](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-builder-resolve_builder_class/) - [tmuxp.workspace.builder.resolve_builder_paths](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-builder-resolve_builder_paths/) - [tmuxp.workspace.options.resolve_session_shell](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-options-resolve_session_shell/) - [tmuxp.workspace.builder.classic.ROWS_FALLBACK](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-builder-classic-rows_fallback/) - [tmuxp.util.run_before_script](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-util-run_before_script/) - [tmuxp.workspace.validation.SchemaValidationError](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-validation-schemavalidationerror/) - [tmuxp.cli.search.SEARCH_DESCRIPTION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-search_description/) - [tmuxp.cli.search.SearchPattern](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-searchpattern/) - [tmuxp.cli.search.SearchToken](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-searchtoken/) - [tmuxp.exc.SessionMissingWorkspaceException](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-sessionmissingworkspaceexception/) - [tmuxp.workspace.validation.SessionNameMissingValidationError](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-validation-sessionnamemissingvalidationerror/) - [tmuxp.exc.SessionNotFound](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-sessionnotfound/) - [tmuxp.log.set_style](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-log-set_style/) - [tmuxp.log.setup_log_file](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-log-setup_log_file/) - [tmuxp.cli.setup_logger](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-setup_logger/) - [tmuxp.plugin.setup_plugin_config](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-plugin-setup_plugin_config/) - [tmuxp.cli.shell.SHELL_DESCRIPTION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-shell-shell_description/) - [tmuxp.workspace.options.shell_is_zsh](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-options-shell_is_zsh/) - [tmuxp.cli.startup](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-startup/) - [tmuxp.types.StrPath](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-types-strpath/) - [tmuxp.plugin.TMUX_MAX_VERSION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-plugin-tmux_max_version/) - [tmuxp.plugin.TMUX_MIN_VERSION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-plugin-tmux_min_version/) - [tmuxp.log.tmuxp_echo](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-log-tmuxp_echo/) - [tmuxp.plugin.TMUXP_MAX_VERSION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-plugin-tmuxp_max_version/) - [tmuxp.plugin.TMUXP_MIN_VERSION](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-plugin-tmuxp_min_version/) - [tmuxp.cli.debug_info.tmuxp_path](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-debug_info-tmuxp_path/) - [tmuxp.exc.TmuxpException](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-tmuxpexception/) - [tmuxp.log.TmuxpLoggerAdapter](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-log-tmuxploggeradapter/) - [tmuxp.plugin.TmuxpPlugin](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-plugin-tmuxpplugin/) - [tmuxp.exc.TmuxpPluginException](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-tmuxppluginexception/) - [tmuxp.workspace.loader.trickle](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-loader-trickle/) - [tmuxp.cli.search.VALID_FIELDS](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-valid_fields/) - [tmuxp.workspace.constants.VALID_WORKSPACE_DIR_FILE_EXTENSIONS](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-constants-valid_workspace_dir_file_extensions/) - [tmuxp.plugin.validate_plugin_config](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-plugin-validate_plugin_config/) - [tmuxp.workspace.validation.validate_schema](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-validation-validate_schema/) - [tmuxp.workspace.validation.WindowListMissingValidationError](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-validation-windowlistmissingvalidationerror/) - [tmuxp.workspace.validation.WindowNameMissingValidationError](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-validation-windownamemissingvalidationerror/) - [tmuxp.exc.WindowNotFound](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-windownotfound/) - [tmuxp.workspace.builder.WORKSPACE_BUILDERS_GROUP](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-builder-workspace_builders_group/) - [tmuxp.workspace.builder.WorkspaceBuilder](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-builder-workspacebuilder/) - [tmuxp.exc.WorkspaceBuilderError](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-workspacebuildererror/) - [tmuxp.exc.WorkspaceBuilderImportError](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-workspacebuilderimporterror/) - [tmuxp.exc.WorkspaceBuilderNotFound](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-workspacebuildernotfound/) - [tmuxp.workspace.options.WorkspaceBuilderOptions](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-options-workspacebuilderoptions/) - [tmuxp.exc.WorkspaceBuilderPathError](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-workspacebuilderpatherror/) - [tmuxp.workspace.builder.WorkspaceBuilderProtocol](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-workspace-builder-workspacebuilderprotocol/) - [tmuxp.exc.WorkspaceError](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-exc-workspaceerror/) - [tmuxp.cli.search.WorkspaceFields](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-workspacefields/) - [tmuxp.cli.ls.WorkspaceInfo](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-ls-workspaceinfo/) - [tmuxp.cli.search.WorkspaceSearchResult](https://libtmux.org/en/py/stable/workspace/reference/tmuxp-cli-search-workspacesearchresult/) --- # Workspace reference generation Source: https://libtmux.org/en/py/stable/workspace/internals/documentation/ > Generate command references from the parser and verify task examples against the CLI. tmuxp uses argparse definitions from [`tmuxp.cli.create_parser`]() for its command reference. The optional `shtab` integration reads that parser for completion. ## Keep syntax and behavior aligned Preserve required and mutually exclusive groups when exporting parser metadata. An optional-looking positional in help can still belong to a required group. Run examples against the corresponding tmuxp revision, including prompts, machine formats, child failures and cleanup. The CLI reference and [workspace builder API](https://libtmux.org/en/py/stable/workspace/internals/) serve different tasks. Keep their example imports, prerequisites and behavior explicit. [Parser source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Third-party notices Source: https://libtmux.org/en/py/stable/meta/third-party-notices/ > Thanks to tmux's creator and contributors, with licences and attribution for the software behind libtmux.org. ## tmux First and foremost, thank you to **[Nicholas Marriott (nicm)](https://github.com/nicm)**, the creator of tmux, and to the many [tmux contributors](https://github.com/tmux/tmux/graphs/contributors). We are grateful for the work that makes tmux possible. libtmux is a separate project. Our libraries and supporting tools control a real tmux server; tmux itself provides the terminal multiplexer. This is the libtmux website. Visit the [official tmux website](https://github.com/tmux/tmux/wiki) for the upstream project and its documentation. See tmux's [COPYING file](https://github.com/tmux/tmux/blob/master/COPYING) and the copyright and permission notices in its source files for its licensing. ### tmux artwork The tmux logomark is by Jason Long. The site uses the unmodified [upstream SVG](https://github.com/tmux/tmux/blob/8f25579c5aef8d93924a20681f394e2a582fd3ad/logo/tmux-logomark.svg) under its [copyright and permission notice](https://libtmux.org/en/brand/tmux/LICENSE.txt). ## Programming-language artwork The homepage language selector uses local copies of the following artwork to identify the selected language. Each source record includes the download URL, retrieval time, file hash, copyright information and usage terms. These marks identify their respective languages and do not imply endorsement of libtmux. The SVG files are copied unchanged except for Scala, whose empty surrounding canvas is cropped. Its paths, gradients and colors are preserved, and the original SVG is retained beside the cropped copy. Rust's supplied SVG includes its own dark-theme colors. | Language | Credit and terms | Local source record | |---|---|---| | Python | Python Software Foundation. The [PSF logo terms](https://www.python.org/psf/trademarks/) permit the unaltered mark to identify Python. | [Python provenance](https://libtmux.org/en/brand/languages/py/provenance.json) | | Ruby | Copyright © 2006, Yukihiro Matsumoto. The [Ruby logo](https://www.ruby-lang.org/en/about/logo/) is licensed under [CC BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/). | [Ruby provenance](https://libtmux.org/en/brand/languages/ruby/provenance.json) | | Lua | Copyright © 1998 Lua.org; graphic design by Alexandre Nakonechnyj. The Devicon copy carries its [MIT notice](https://libtmux.org/en/brand/languages/lua/LICENSE.txt); [Lua's logo terms](https://www.lua.org/images/) also apply. Visit [Lua.org](https://www.lua.org/). | [Lua provenance](https://libtmux.org/en/brand/languages/lua/provenance.json) | | TypeScript | Microsoft. The [official branding terms](https://www.typescriptlang.org/branding/) govern the mark; the website repository licenses exclude logo and trademark rights. | [TypeScript provenance](https://libtmux.org/en/brand/languages/ts/provenance.json) | | Rust | The Rust Foundation. [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) and the [Rust trademark policy](https://rustfoundation.org/policy/rust-trademark-policy/) apply. | [Rust provenance](https://libtmux.org/en/brand/languages/rs/provenance.json) | | Go | The [Go gopher](https://go.dev/blog/gopher) is by Renee French, licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). | [Go provenance](https://libtmux.org/en/brand/languages/go/provenance.json) | | C++ | Created by Jeremy Kratz and licensed by the Standard C++ Foundation under its [logo-use terms](https://isocpp.org/home/terms-of-use). | [C++ provenance](https://libtmux.org/en/brand/languages/cxx/provenance.json) | | Swift | Apple Inc., under the [Swift Logo Guidelines](https://developer.apple.com/swift/downloads/swift-logo.zip). Swift and the Swift logo are trademarks of Apple Inc. | [Swift provenance](https://libtmux.org/en/brand/languages/swift/provenance.json) | | Java | Devicon collection copyright (c) 2015 konpa, with its [MIT notice](https://libtmux.org/en/brand/languages/java/LICENSE.txt). This does not establish unrestricted rights to the underlying Java logo; [Oracle's logo terms](https://www.oracle.com/legal/logos/) apply. | [Java provenance](https://libtmux.org/en/brand/languages/java/provenance.json) | | Kotlin | Kotlin Foundation brand guidelines preserve JetBrains copyrights. The [icon-use terms](https://kotlinfoundation.org/guidelines/) permit identifying Kotlin alongside other programming-language icons. | [Kotlin provenance](https://libtmux.org/en/brand/languages/kotlin/provenance.json) | | Scala | Copyright EPFL. [Historical permission](https://groups.google.com/g/scala-user/c/bCC-R0FQn1w) covers noncommercial Scala promotion; the [general artwork-license question](https://github.com/scala/scala-lang/issues/1040) remains unresolved. | [Scala provenance](https://libtmux.org/en/brand/languages/scala/provenance.json) | | C# | Copyright the .NET authors. [Brand-use permission](https://github.com/dotnet/brand/issues/10#issuecomment-669465301) allows the unmodified logo to represent .NET. The repository's CC0 statement covers illustrations; no blanket CC0 claim is made for the logo. | [.NET provenance](https://libtmux.org/en/brand/languages/csharp/provenance.json) | | F# | The F# Software Foundation. Its [logo terms](https://foundation.fsharp.org/logo) require unchanged shape, colors and proportions, without implying Foundation representation. | [F# provenance](https://libtmux.org/en/brand/languages/fsharp/provenance.json) | ## Terminal artwork The tmux CLI selector displays the Windows Terminal artwork by Microsoft Corporation, licensed under [CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0/). The SVG is unmodified. See the [source and provenance](https://libtmux.org/en/brand/tools/terminal/provenance.json) and [copyright and license](https://libtmux.org/en/brand/tools/terminal/LICENSE.txt). ## Documentation toolchain libtmux and this site are built with open-source software. The following tools have their own licences and attribution requirements. | Tool | Licence | Role | |---|---|---| | [Astro](https://astro.build/) | MIT | The site shell | | [Tailwind CSS](https://tailwindcss.com/) | MIT | Styling | | [Pagefind](https://pagefind.app/) | MIT | Site-wide search | | [Expressive Code](https://expressive-code.com/) | MIT | Code blocks | | [Sphinx](https://www.sphinx-doc.org/) | BSD-2-Clause | Python and C++ reference | | [Furo](https://github.com/pradyunsg/furo) | MIT | Sphinx theme | | [Breathe](https://github.com/breathe-doc/breathe) | BSD-3-Clause | Doxygen XML into Sphinx | | [Doxygen](https://www.doxygen.nl/) | GPL-2.0-only | Parses C++ headers to XML | | [API Extractor](https://api-extractor.com/) | MIT | TypeScript API model | | [IBM Plex](https://github.com/IBM/plex) | OFL-1.1 | Typeface | ### A note on Doxygen Doxygen is licensed GPL-2.0-only. It runs as a build step that reads libtmux's own headers and emits XML; that XML is rendered by Breathe and Sphinx, and no Doxygen-generated HTML is published. Running a GPL program over your own input does not place its licence on the output, and libtmux does not distribute Doxygen or any modified version of it. ## Reference hosting The [PyPI blocks logo](https://pypi.org/trademarks/) is a trademark of the Python Software Foundation and identifies links to the Python Package Index. Other package-host icons use [Simple Icons](https://simpleicons.org/) (CC0-1.0). The docs.rs mark is its [`docsdotrs` icon](https://github.com/simple-icons/simple-icons/blob/16.35.0/icons/docsdotrs.svg), inlined unchanged. The book beside javadoc.io links is original artwork for this site: the host publishes no vector logo, and the mark does not imitate its favicon. Some ports deep-link to the canonical host their ecosystem already uses, rather than duplicating it here: - Rust: [docs.rs](https://docs.rs/libtmux), for each published crate - Go: [pkg.go.dev](https://pkg.go.dev/github.com/libtmux/libtmux-go/tmux) - Java, Kotlin and Scala: [javadoc.io](https://javadoc.io/doc/io.github.libtmux/libtmux) - Swift: the [Swift Package Index](https://swiftpackageindex.com/libtmux/libtmux-swift/documentation/libtmux) copy of the DocC reference Those sites are operated independently of this project and carry their own terms. ## libtmux itself Each port is MIT licensed. See the `LICENSE` file in that port's repository for the authoritative text. --- # API glossary Source: https://libtmux.org/en/py/stable/reference/glossary/ > Kinds, modifiers and package labels in the Python API reference. ## Symbol kinds Kinds identify declarations in the Python API reference. ### class A Python type defining attributes and behavior for its instances. References: [Python classes](https://docs.python.org/3/tutorial/classes.html). ### function A Python callable defined with def or a lambda expression. References: [Python function definitions](https://docs.python.org/3/reference/compound_stmts.html#function-definitions). ### method A Python callable obtained through a class or instance. An ordinary bound method supplies its instance as the first argument. References: [Python instance methods](https://docs.python.org/3/reference/datamodel.html#instance-methods). ### property A Python descriptor whose getter, setter or deleter runs during attribute access. A property need not correspond to a stored field, and reading it may execute code. References: [Python properties](https://docs.python.org/3/library/functions.html#property). ### attribute A named Python value accessed on an object or class, potentially through a descriptor or dynamic lookup. References: [Python attribute access](https://docs.python.org/3/reference/datamodel.html#customizing-attribute-access). ### constant A named Python API value conventionally treated as constant. Uppercase naming does not prevent reassignment at runtime. References: [Python constant naming](https://peps.python.org/pep-0008/#constants). ### exception A Python exception class whose instances can be raised and handled with except. References: [Python exceptions](https://docs.python.org/3/tutorial/errors.html#user-defined-exceptions). ## Modifiers Modifiers add information about calling, implementing, or accessing a declaration. Their precise effect follows the language and the signature. ### classmethod A Python method that receives the class as its implicit first argument, including when called through an instance. References: [Python class methods](https://docs.python.org/3/library/functions.html#classmethod). ### async A Python coroutine function declared with async def. Calling it creates a coroutine to await or schedule. References: [Python coroutine functions](https://docs.python.org/3/reference/compound_stmts.html#coroutine-function-definition). ### inherited A Python member resolved from a base class through the method resolution order. The reference names the declaring class so its original definition remains navigable. References: [Python inheritance](https://docs.python.org/3/tutorial/classes.html#inheritance). ## Package context Package labels identify where an API is supplied. ### package The Python distribution supplying this API. Its installation name can differ from the package name used in imports. References: [Python distributions and import packages](https://packaging.python.org/en/latest/discussions/distribution-package-vs-import-package/). --- # tmux MCP for Python Source: https://libtmux.org/en/py/stable/mcp/ > Expose tmux tools, resources, and prompts through Python's libtmux-mcp server. `libtmux-mcp` lets an MCP client inspect tmux, create sessions and panes, run commands, and wait for their results. The distribution and executable are `libtmux-mcp`; Python imports use [`libtmux_mcp`](). The server runs over standard input and output. It requires Python 3.10 or newer and tmux 3.2a or newer. Its default toolsets are [`inspect`](), `manage`, and `execute`; deletion tools require an explicit selection. ## Start here - [Install](https://libtmux.org/en/py/stable/mcp/#install) points an MCP client at this server. - [Tools](https://libtmux.org/en/py/stable/mcp/tools/) lists the MCP operations, arguments, and results. - [Guides](https://libtmux.org/en/py/stable/mcp/guides/) connect a client and select a tmux socket. - [Topics](https://libtmux.org/en/py/stable/mcp/topics/) explain toolsets, trust, waiting, and caller context. - [Examples](https://libtmux.org/en/py/stable/mcp/examples/) call a tool, then explore server internals. - [Language API](https://libtmux.org/en/py/stable/mcp/reference/) documents embedding and implementation types. For declarative session configuration, use the [Workspace Manager](https://libtmux.org/en/py/stable/workspace/), provided by the separate `tmuxp` project. The MCP server does not provide a tmuxp file loader. The [upstream Python documentation](https://libtmux-mcp.git-pull.com/) covers client integrations and the complete tool reference. These pages follow the [Python implementation](https://github.com/tmux-python/libtmux-mcp/tree/v0.1.0a22). --- # Python MCP topics Source: https://libtmux.org/en/py/stable/mcp/topics/ > Understand Python toolsets, socket overrides, terminal output, and command completion. Python's MCP toolsets select advertised and callable tools. They do not confine the programs running inside tmux. ## Select independent toolsets [`inspect`]() requests state or output. `manage` changes tmux structure, presentation, or coordination without supplying executable input. `execute` starts processes, sends input, or changes executable configuration. `teardown` removes objects or retained history. The default is `inspect,manage,execute`. `LIBTMUX_TOOLS` adds exact names, and `LIBTMUX_EXCLUDE_TOOLS` removes them last. Unknown names fail startup. An empty `LIBTMUX_TOOLSETS` selects no sets. These settings filter tools only. Hierarchy resources and native prompts remain available even with no tools. Resource reads contact tmux; native prompts return text without contacting it. ## Know the endpoint and caller `LIBTMUX_SOCKET` selects a default socket name. Targeted tools can accept [`socket_name`]() to override it for one call. This differs from servers that pin every call to one endpoint. Dedicated teardown tools refuse the pane containing the MCP process and its enclosing window, session, or server. The check compares socket identity as well as [`TMUX_PANE`](). It cannot turn open-ended shell input into a constrained operation. ## Choose the completion signal Use [`run_command`]() for a command the agent authors. Read [`exit_status`](), [`timed_out`](), and [`output`](); a timeout does not prove the shell stopped. Use [`wait_for_text`]() for output produced elsewhere and [`capture_since`]() for repeated observation with an opaque cursor. The default wait ceiling is 30 seconds, configurable within 1 to 120 seconds. Oversized requests are clamped. Command-history suppression defaults on for MCP calls to [`run_command`](), while direct Python calls default it off; this is best-effort shell behavior. ## Treat terminal output as data A private socket separates tmux objects. It does not restrict filesystem, network, or same-user process access. Server aliases and hooks can add effects even to a nominal inspection. Pane output can contain credentials or instructions from another program; it remains untrusted data. See the [upstream trust model](https://libtmux-mcp.git-pull.com/topics/trust/) and [configuration source](https://github.com/tmux-python/libtmux-mcp/blob/v0.1.0a22/docs/configuration.md). --- # Connect a Python MCP client Source: https://libtmux.org/en/py/stable/mcp/guides/ > Launch libtmux-mcp on a chosen socket and verify the tools your client receives. Configure the client to launch `libtmux-mcp` with a named tmux socket. Install [uv](https://docs.astral.sh/uv/) first, and make tmux 3.2a or newer available in the environment the client passes to the server. ## Launch the server This command resolves the package in its own uv environment and starts its stdio transport. It waits for an MCP client to send requests. ```console $ LIBTMUX_SOCKET=docs-agent LIBTMUX_TOOLSETS=inspect \ uvx libtmux-mcp@latest ``` For a client that accepts an `mcpServers` object, use: ```json { "mcpServers": { "tmux-python": { "command": "uvx", "args": ["libtmux-mcp@latest"], "env": { "LIBTMUX_SOCKET": "docs-agent", "LIBTMUX_TOOLSETS": "inspect" } } } } ``` Client configuration formats differ; the [upstream client guide](https://libtmux-mcp.git-pull.com/clients/) gives their individual formats. Restart the MCP process after changing startup environment variables. ## Verify the connection Ask the client to list the tools, then call [`list_sessions`](). Ask it to identify a pane before capturing content. An empty session listing can be correct for the selected socket. To allow commands and topology creation, change the toolset selection to `inspect,manage,execute`. Check the new listing after reconnecting. Removing `teardown` does not stop a shell command from deleting work. ## Diagnose a mismatch Compare the client's executable path and environment with your shell. `LIBTMUX_TMUX_BIN` selects the tmux executable. `LIBTMUX_SOCKET_PATH` selects an explicit socket path. A targeted tool's [`socket_name`]() argument can override the default endpoint. Keep this application in its own Python environment when also using [tmuxp](https://libtmux.org/en/py/stable/workspace/); the projects have independent libtmux dependency requirements. [Configuration contract](https://github.com/tmux-python/libtmux-mcp/blob/v0.1.0a22/docs/configuration.md). --- # Python MCP examples Source: https://libtmux.org/en/py/stable/mcp/examples/ > List sessions through the Python MCP server and inspect implementation examples. Connect the server using the [setup guide](https://libtmux.org/en/py/stable/mcp/guides/), then call [`list_sessions`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/) from your MCP client. ## List sessions This is the `params` object for an MCP `tools/call` request. Send it through the connected client: ```json { "name": "list_sessions", "arguments": {} } ``` Use the returned session IDs when choosing a window or pane. The [tool reference](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/) describes this port's result and optional arguments. ## Internals The following examples are for applications that embed or extend the server. Installing and connecting an MCP client does not require this code. Use a FastMCP client to inspect the same registered server that the `libtmux-mcp` executable serves. This checks the advertised contract without creating tmux sessions. ### Inspect the catalog in Python Run this in an environment containing `libtmux-mcp`. It uses the production factory and closes the in-process client when the context ends. ```python import asyncio from fastmcp import Client from libtmux_mcp.server import build_mcp_server async def main() -> None: async with Client(build_mcp_server()) as client: tools = await client.list_tools() for tool in tools: print(tool.name, tool.input_schema) asyncio.run(main()) ``` The [production factory](https://github.com/tmux-python/libtmux-mcp/blob/v0.1.0a22/src/libtmux_mcp/server.py) registers tools and applies visibility once. The [server tests](https://github.com/tmux-python/libtmux-mcp/blob/v0.1.0a22/tests/test_server.py) exercise this client/factory pattern. Set selection variables before importing the server in a fresh process. ### Run and observe through a client On a disposable session, ask the client to create a pane, run `printf 'ready\n'` with [`run_command`](), and report its typed exit status. For subsequent output, seed [`capture_since`]() and reuse the returned cursor. Use [`wait_for_text`]() when waiting for output from a process you did not launch. These are workflows for the client to carry out, not literal tool argument objects. Use the [tool reference](https://libtmux.org/en/py/stable/mcp/tools/) for each operation's schema. The [upstream quickstart](https://libtmux-mcp.git-pull.com/quickstart/) describes command completion and lower-level channel composition. --- # Python MCP API Source: https://libtmux.org/en/py/stable/mcp/reference/ > Find Python server entry points, typed models, and the separate MCP wire contract. For MCP client requests, use the [tool reference](https://libtmux.org/en/py/stable/mcp/tools/). This page covers language APIs for embedding or extending the server. The Python API and MCP protocol expose different interfaces. Python callers import functions and models; MCP clients send registered tool names and schema-validated arguments. ## MCP operations Browse the [tool reference](https://libtmux.org/en/py/stable/mcp/tools/) for the protocol catalog. `tools/list` on a running server is the effective selection after startup filtering. Registration defaults can differ from direct Python function defaults, including command-history suppression. The server also registers hierarchy resources and workflow prompts. These remain available independently of the toolset selection. ## Python entry points [`libtmux_mcp.server.build_mcp_server()`]() returns the registered production FastMCP server. [`run_server()`]() serves it over stdio. The factory uses the module's server instance; repeated calls do not create independent configuration contexts. The package separates tool functions, typed models, middleware, resource handlers, and prompt recipes. Model classes describe request/result data; their existence does not make them separate MCP tools. - [Server API](https://libtmux-mcp.git-pull.com/reference/api/server/) - [Tools API](https://libtmux-mcp.git-pull.com/reference/api/tools/) - [Models API](https://libtmux-mcp.git-pull.com/reference/api/models/) - [Registration source](https://github.com/tmux-python/libtmux-mcp/blob/v0.1.0a22/src/libtmux_mcp/server.py) Use [Examples](https://libtmux.org/en/py/stable/mcp/examples/) to inspect the protocol with an in-process client. Use the [Workspace builder API](https://libtmux.org/en/py/stable/workspace/reference/) for tmuxp configuration and builders. ## API declarations - [libtmux_mcp.middleware.AuditMiddleware](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-middleware-auditmiddleware/) - [libtmux_mcp.models.BufferContent](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-buffercontent/) - [libtmux_mcp.models.BufferRef](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-bufferref/) - [libtmux_mcp.prompts.recipes.build_dev_workspace](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-prompts-recipes-build_dev_workspace/) - [libtmux_mcp.server.build_mcp_server](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-server-build_mcp_server/) - [libtmux_mcp.tools.batch_tools.call_read_tools_batch](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-batch_tools-call_read_tools_batch/) - [libtmux_mcp.tools.pane_tools.io.CAPTURE_DEFAULT_MAX_LINES](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-io-capture_default_max_lines/) - [libtmux_mcp.tools.pane_tools.capture_pane](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-capture_pane/) - [libtmux_mcp.tools.pane_tools.capture_since](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-capture_since/) - [libtmux_mcp.tools.pane_tools.capture_since.CAPTURE_SINCE_DEFAULT_MAX_BYTES](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-capture_since-capture_since_default_max_bytes/) - [libtmux_mcp.tools.pane_tools.capture_since.CAPTURE_SINCE_DEFAULT_MAX_LINES](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-capture_since-capture_since_default_max_lines/) - [libtmux_mcp.models.CaptureSinceResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-capturesinceresult/) - [libtmux_mcp.tools.pane_tools.clear_pane](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-clear_pane/) - [libtmux_mcp.tools.server_tools.create_session](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-server_tools-create_session/) - [libtmux_mcp.tools.session_tools.create_window](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-session_tools-create_window/) - [libtmux_mcp.middleware.DEFAULT_RESPONSE_LIMIT_BYTES](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-middleware-default_response_limit_bytes/) - [libtmux_mcp.server.DEFAULT_TOOLSETS](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-server-default_toolsets/) - [libtmux_mcp.tools.buffer_tools.delete_buffer](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-buffer_tools-delete_buffer/) - [libtmux_mcp.prompts.recipes.diagnose_failing_pane](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-prompts-recipes-diagnose_failing_pane/) - [libtmux_mcp.tools.pane_tools.display_message](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-display_message/) - [libtmux_mcp.tools.pane_tools.enter_copy_mode](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-enter_copy_mode/) - [libtmux_mcp.prompts.ENV_PROMPTS_AS_TOOLS](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-prompts-env_prompts_as_tools/) - [libtmux_mcp.models.EnvironmentResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-environmentresult/) - [libtmux_mcp.models.EnvironmentSetResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-environmentsetresult/) - [libtmux_mcp.tools.pane_tools.exit_copy_mode](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-exit_copy_mode/) - [libtmux_mcp.tools.pane_tools.find_pane_by_position](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-find_pane_by_position/) - [libtmux_mcp.tools.pane_tools.get_pane_info](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-get_pane_info/) - [libtmux_mcp.tools.server_tools.get_server_info](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-server_tools-get_server_info/) - [libtmux_mcp.tools.session_tools.get_session_info](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-session_tools-get_session_info/) - [libtmux_mcp.tools.window_tools.get_window_info](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-window_tools-get_window_info/) - [libtmux_mcp.tools.pane_tools.state.HISTORY_LIMIT_FORMAT](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-state-history_limit_format/) - [libtmux_mcp.models.HookEntry](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-hookentry/) - [libtmux_mcp.models.HookListResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-hooklistresult/) - [libtmux_mcp.middleware.install_fastmcp_validation_log_filter](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-middleware-install_fastmcp_validation_log_filter/) - [libtmux_mcp.prompts.recipes.interrupt_gracefully](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-prompts-recipes-interrupt_gracefully/) - [libtmux_mcp.tools.pane_tools.kill_pane](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-kill_pane/) - [libtmux_mcp.tools.server_tools.kill_server](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-server_tools-kill_server/) - [libtmux_mcp.tools.session_tools.kill_session](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-session_tools-kill_session/) - [libtmux_mcp.tools.window_tools.kill_window](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-window_tools-kill_window/) - [libtmux_mcp.tools.window_tools.list_panes](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-window_tools-list_panes/) - [libtmux_mcp.tools.server_tools.list_servers](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-server_tools-list_servers/) - [libtmux_mcp.tools.server_tools.list_sessions](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-server_tools-list_sessions/) - [libtmux_mcp.tools.session_tools.list_windows](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-session_tools-list_windows/) - [libtmux_mcp.tools.buffer_tools.load_buffer](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-buffer_tools-load_buffer/) - [libtmux_mcp.main](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-main/) - [libtmux_mcp.tools.batch_tools.MAX_BATCH_OPERATIONS](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-batch_tools-max_batch_operations/) - [libtmux_mcp.server.mcp](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-server-mcp/) - [libtmux_mcp.tools.window_tools.move_window](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-window_tools-move_window/) - [libtmux_mcp.models.OptionResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-optionresult/) - [libtmux_mcp.models.OptionSetResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-optionsetresult/) - [libtmux_mcp.tools.pane_tools.state.PANE_STATE_FORMAT](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-state-pane_state_format/) - [libtmux_mcp.models.PaneContentMatch](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-panecontentmatch/) - [libtmux_mcp.tools.pane_tools.lifecycle.PaneCorner](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-lifecycle-panecorner/) - [libtmux_mcp.models.PaneInfo](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-paneinfo/) - [libtmux_mcp.models.PaneSnapshot](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-panesnapshot/) - [libtmux_mcp.tools.buffer_tools.paste_buffer](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-buffer_tools-paste_buffer/) - [libtmux_mcp.tools.pane_tools.paste_text](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-paste_text/) - [libtmux_mcp.tools.pane_tools.pipe_pane](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-pipe_pane/) - [libtmux_mcp.resources.hierarchy.register](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-resources-hierarchy-register/) - [libtmux_mcp.tools.batch_tools.register](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-batch_tools-register/) - [libtmux_mcp.tools.buffer_tools.register](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-buffer_tools-register/) - [libtmux_mcp.tools.env_tools.register](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-env_tools-register/) - [libtmux_mcp.tools.hook_tools.register](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-hook_tools-register/) - [libtmux_mcp.tools.option_tools.register](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-option_tools-register/) - [libtmux_mcp.tools.pane_tools.register](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-register/) - [libtmux_mcp.tools.server_tools.register](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-server_tools-register/) - [libtmux_mcp.tools.session_tools.register](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-session_tools-register/) - [libtmux_mcp.tools.wait_for_tools.register](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-wait_for_tools-register/) - [libtmux_mcp.tools.window_tools.register](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-window_tools-register/) - [libtmux_mcp.resources.hierarchy.register_completions](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-resources-hierarchy-register_completions/) - [libtmux_mcp.prompts.register_prompts](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-prompts-register_prompts/) - [libtmux_mcp.resources.register_resources](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-resources-register_resources/) - [libtmux_mcp.tools.register_tools](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-register_tools/) - [libtmux_mcp.tools.session_tools.rename_session](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-session_tools-rename_session/) - [libtmux_mcp.tools.window_tools.rename_window](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-window_tools-rename_window/) - [libtmux_mcp.tools.pane_tools.resize_pane](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-resize_pane/) - [libtmux_mcp.tools.window_tools.resize_window](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-window_tools-resize_window/) - [libtmux_mcp.tools.pane_tools.respawn_pane](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-respawn_pane/) - [libtmux_mcp.prompts.recipes.run_and_wait](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-prompts-recipes-run_and_wait/) - [libtmux_mcp.tools.pane_tools.run_command](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-run_command/) - [libtmux_mcp.server.run_server](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-server-run_server/) - [libtmux_mcp.models.RunCommandResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-runcommandresult/) - [libtmux_mcp.tools.pane_tools.search.SEARCH_DEFAULT_LIMIT](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-search-search_default_limit/) - [libtmux_mcp.tools.pane_tools.search.SEARCH_DEFAULT_MAX_LINES_PER_PANE](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-search-search_default_max_lines_per_pane/) - [libtmux_mcp.tools.pane_tools.search.SEARCH_MATCH_MAX_SECONDS](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-search-search_match_max_seconds/) - [libtmux_mcp.tools.pane_tools.search.SEARCH_MAX_PATTERN_LENGTH](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-search-search_max_pattern_length/) - [libtmux_mcp.tools.pane_tools.search_panes](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-search_panes/) - [libtmux_mcp.models.SearchPanesResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-searchpanesresult/) - [libtmux_mcp.tools.window_tools.select_layout](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-window_tools-select_layout/) - [libtmux_mcp.tools.pane_tools.select_pane](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-select_pane/) - [libtmux_mcp.tools.session_tools.select_window](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-session_tools-select_window/) - [libtmux_mcp.tools.pane_tools.send_keys](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-send_keys/) - [libtmux_mcp.tools.pane_tools.send_keys_batch](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-send_keys_batch/) - [libtmux_mcp.models.SendKeysBatchResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-sendkeysbatchresult/) - [libtmux_mcp.models.SendKeysOperation](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-sendkeysoperation/) - [libtmux_mcp.models.SendKeysOperationResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-sendkeysoperationresult/) - [libtmux_mcp.models.ServerInfo](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-serverinfo/) - [libtmux_mcp.models.SessionInfo](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-sessioninfo/) - [libtmux_mcp.tools.env_tools.set_environment](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-env_tools-set_environment/) - [libtmux_mcp.tools.option_tools.set_option](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-option_tools-set_option/) - [libtmux_mcp.tools.pane_tools.set_pane_title](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-set_pane_title/) - [libtmux_mcp.tools.buffer_tools.show_buffer](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-buffer_tools-show_buffer/) - [libtmux_mcp.tools.buffer_tools.SHOW_BUFFER_DEFAULT_MAX_LINES](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-buffer_tools-show_buffer_default_max_lines/) - [libtmux_mcp.tools.env_tools.show_environment](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-env_tools-show_environment/) - [libtmux_mcp.tools.hook_tools.show_hook](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-hook_tools-show_hook/) - [libtmux_mcp.tools.hook_tools.show_hooks](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-hook_tools-show_hooks/) - [libtmux_mcp.tools.option_tools.show_option](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-option_tools-show_option/) - [libtmux_mcp.tools.wait_for_tools.signal_channel](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-wait_for_tools-signal_channel/) - [libtmux_mcp.tools.pane_tools.snapshot_pane](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-snapshot_pane/) - [libtmux_mcp.tools.server_tools.SOCKET_NAME_EXEMPT](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-server_tools-socket_name_exempt/) - [libtmux_mcp.tools.window_tools.split_window](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-window_tools-split_window/) - [libtmux_mcp.tools.pane_tools.swap_pane](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-swap_pane/) - [libtmux_mcp.middleware.TailPreservingResponseLimitingMiddleware](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-middleware-tailpreservingresponselimitingmiddleware/) - [libtmux_mcp.models.ToolCallBatchResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-toolcallbatchresult/) - [libtmux_mcp.models.ToolCallOperation](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-toolcalloperation/) - [libtmux_mcp.models.ToolCallOperationResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-toolcalloperationresult/) - [libtmux_mcp.middleware.ToolErrorResultMiddleware](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-middleware-toolerrorresultmiddleware/) - [libtmux_mcp.middleware.ToolsetMiddleware](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-middleware-toolsetmiddleware/) - [libtmux_mcp.tools.wait_for_tools.wait_for_channel](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-wait_for_tools-wait_for_channel/) - [libtmux_mcp.tools.pane_tools.wait_for_text](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-pane_tools-wait_for_text/) - [libtmux_mcp.models.WaitForTextResult](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-waitfortextresult/) - [libtmux_mcp.models.WindowInfo](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-windowinfo/) [Protocol catalog](https://libtmux.org/en/py/stable/mcp/tools.json) --- # MCP API glossary Source: https://libtmux.org/en/py/stable/mcp/reference/glossary/ > What MCP tool annotations tell clients about a tool. ## MCP tool annotations These are server-supplied hints, not enforced guarantees. Clients must not base tool-use decisions on annotations from untrusted servers. ### readOnlyHint True indicates that the tool leaves its environment unchanged. Defaults to false when omitted. References: [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-11-25/schema#toolannotations). ### destructiveHint True indicates potentially destructive changes; false indicates additive changes only. Defaults to true. Meaningful only when readOnlyHint is false. References: [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-11-25/schema#toolannotations). ### idempotentHint True indicates that repeating a call with identical arguments adds no further effects. Defaults to false. Meaningful only when readOnlyHint is false. It does not promise identical responses. References: [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-11-25/schema#toolannotations). ### openWorldHint True indicates possible interaction with external entities; false indicates a closed interaction domain. Defaults to true. This describes the interaction domain, not whether the tool writes data. References: [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-11-25/schema#toolannotations). ### title A display title for the tool. The tool’s top-level title takes precedence, followed by annotations.title, then name. References: [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-11-25/schema#toolannotations). ## Symbol kinds Kinds identify declarations in the Python API reference. ### class A Python type defining attributes and behavior for its instances. References: [Python classes](https://docs.python.org/3/tutorial/classes.html). ### function A Python callable defined with def or a lambda expression. References: [Python function definitions](https://docs.python.org/3/reference/compound_stmts.html#function-definitions). ### method A Python callable obtained through a class or instance. An ordinary bound method supplies its instance as the first argument. References: [Python instance methods](https://docs.python.org/3/reference/datamodel.html#instance-methods). ### property A Python descriptor whose getter, setter or deleter runs during attribute access. A property need not correspond to a stored field, and reading it may execute code. References: [Python properties](https://docs.python.org/3/library/functions.html#property). ### attribute A named Python value accessed on an object or class, potentially through a descriptor or dynamic lookup. References: [Python attribute access](https://docs.python.org/3/reference/datamodel.html#customizing-attribute-access). ### constant A named Python API value conventionally treated as constant. Uppercase naming does not prevent reassignment at runtime. References: [Python constant naming](https://peps.python.org/pep-0008/#constants). ### exception A Python exception class whose instances can be raised and handled with except. References: [Python exceptions](https://docs.python.org/3/tutorial/errors.html#user-defined-exceptions). ## Modifiers Modifiers add information about calling, implementing, or accessing a declaration. Their precise effect follows the language and the signature. ### classmethod A Python method that receives the class as its implicit first argument, including when called through an instance. References: [Python class methods](https://docs.python.org/3/library/functions.html#classmethod). ### async A Python coroutine function declared with async def. Calling it creates a coroutine to await or schedule. References: [Python coroutine functions](https://docs.python.org/3/reference/compound_stmts.html#coroutine-function-definition). ### inherited A Python member resolved from a base class through the method resolution order. The reference names the declaring class so its original definition remains navigable. References: [Python inheritance](https://docs.python.org/3/tutorial/classes.html#inheritance). ## Package context Package labels identify where an API is supplied. ### package The Python distribution supplying this API. Its installation name can differ from the package name used in imports. References: [Python distributions and import packages](https://packaging.python.org/en/latest/discussions/distribution-package-vs-import-package/). --- # Python workspace manager Source: https://libtmux.org/en/py/stable/workspace/ > Describe a tmux session in a file, then load, inspect and capture it. [tmuxp](https://tmuxp.git-pull.com/) loads tmux sessions from YAML or JSON using libtmux. A file describes windows, panes and commands. [`tmuxp load`](https://libtmux.org/en/py/stable/workspace/cli/load/) builds the session and can attach to it or leave it detached. ## Start here 1. [Install tmuxp and load a workspace](https://libtmux.org/en/py/stable/workspace/guides/installation/). 2. [Configure windows and panes](https://libtmux.org/en/py/stable/workspace/configuration/). 3. [Capture and reload a session](https://libtmux.org/en/py/stable/workspace/guides/export-session/). The [CLI manual](https://libtmux.org/en/py/stable/workspace/cli/) covers discovery, search, editing, conversion and import. Use [examples](https://libtmux.org/en/py/stable/workspace/examples/gallery/) for complete files and their prerequisites. Install tmuxp separately from the core libtmux package. Its dependency resolver selects a compatible libtmux release. [Workspace internals](https://libtmux.org/en/py/stable/workspace/internals/) describe the builder and Python extension APIs. [Quickstart source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/docs/quickstart.md). - [CLI Manual](https://libtmux.org/en/py/stable/workspace/cli/): Commands, options and machine output. - [Configuration](https://libtmux.org/en/py/stable/workspace/configuration/): Workspace fields, normalization and execution. - [Install and load](https://libtmux.org/en/py/stable/workspace/guides/installation/): Load a workspace on a private socket, then capture it. - [Example gallery](https://libtmux.org/en/py/stable/workspace/examples/gallery/): Workspace files to start from, with their prerequisites. - [Runtime support](https://libtmux.org/en/py/stable/workspace/reference/compatibility/): Runtime requirements and supported behavior. - [Internals](https://libtmux.org/en/py/stable/workspace/internals/): The workspace library, for building sessions from code. --- # Python workspace topics Source: https://libtmux.org/en/py/stable/workspace/topics/ > Understand workspace configuration, existing sessions, and tmuxp freeze. Use [`tmuxp load`](https://libtmux.org/en/py/stable/workspace/cli/load/) to turn a YAML or JSON configuration into a tmux session. The configuration controls its windows, panes, directories, and commands. ## Configuration and commands A workspace names a session and contains windows with panes. Pane shorthand can name a command directly, while mappings describe command lists, working directories, focus, and other configuration. The loader expands environment variables and resolves relative paths using the workspace location. [`shell_command_before`](https://libtmux.org/en/py/stable/workspace/configuration/session/#root-keys-shell-command-before) supplies setup commands inherited by the relevant panes. Commands, scripts, plugins, and custom builders execute code in your runtime. Use workspace files whose commands and extension imports you intend to run. Successful construction does not mean a launched application has completed startup; its own readiness check is a separate task. ## Existing sessions [`tmuxp load`](https://libtmux.org/en/py/stable/workspace/cli/load/) handles attachment and switching as part of its CLI workflow. It can attach to an existing named session, and its append mode adds windows to the current session. Those choices differ from replacing a session or converging a description automatically. Read the load command's prompts and options before automating an existing-session workflow. ## Export a session [`tmuxp freeze`](https://libtmux.org/en/py/stable/workspace/cli/freeze/) writes the structure of a running session as YAML or JSON. It recovers current layouts and working directories, and uses observable current programs when forming commands. It cannot recover the original command line, process memory, or a complete application checkpoint. Review its output before relying on it as a launcher. See the upstream [workspace configuration](https://tmuxp.git-pull.com/configuration/) for supported fields. Contributor details about the loader and custom builders belong in [Internals](https://libtmux.org/en/py/stable/workspace/internals/topics/). [Expansion implementation](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/loader.py); [Freeze implementation](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/workspace/freezer.py). --- # Load a Python workspace Source: https://libtmux.org/en/py/stable/workspace/guides/ > Install tmuxp, load YAML on a dedicated socket, and inspect the session. Install tmuxp as a Python tool, with Python 3.10 or newer and tmux 3.2 or newer available on the host: ```console $ uv tool install tmuxp ``` The tool environment owns tmuxp's dependencies. Keep a separately installed MCP application in its own environment if its libtmux requirement differs. ## Describe the workspace Save this upstream example as `workspace.yaml`: ```yaml session_name: 2-pane-vertical windows: - window_name: my test window panes: - echo hello - echo hello ``` Load it detached on a dedicated socket, without changing your attached session: ```console $ tmuxp load \ -L workspace-guide \ -d \ workspace.yaml ``` The `-L` value selects the tmux server and `-d` prevents attachment. Reserve that socket name for this example. Omit `-d` when you want tmuxp to attach or offer its normal client-switching flow. Inspect the created session: ```console $ tmux -L workspace-guide list-sessions ``` When finished, remove only the example session: ```console $ tmux -L workspace-guide kill-session -t '=2-pane-vertical' ``` ## Saved workspaces and export [`tmuxp load`](https://libtmux.org/en/py/stable/workspace/cli/load/) accepts file paths and names resolved through its configuration search. Use an explicit path while learning the format so the loaded file is unambiguous. Use [`tmuxp freeze`](https://libtmux.org/en/py/stable/workspace/cli/freeze/) for a session you want to capture as a starting configuration. It offers YAML or JSON output. Inspect the generated command lists and paths before using the export later. The upstream [load reference](https://tmuxp.git-pull.com/cli/load/) covers append, session-name, socket, and attachment options. The [freeze reference](https://tmuxp.git-pull.com/cli/freeze/) covers output choices. [Workspace source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/2-pane-vertical.yaml); [CLI option definitions](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/load.py). --- # Python workspace examples Source: https://libtmux.org/en/py/stable/workspace/examples/ > Load tmux workspaces from YAML or JSON with the tmuxp CLI. Save a workspace file and pass it to [tmuxp](https://tmuxp.git-pull.com/). These examples require tmuxp and tmux; the [guide](https://libtmux.org/en/py/stable/workspace/guides/) covers installation. No Python program is needed. ## Load YAML Save this upstream two-pane example as `workspace.yaml`: ```yaml session_name: 2-pane-vertical windows: - window_name: my test window panes: - echo hello - echo hello ``` Load the workspace and attach to it: ```console $ tmuxp load workspace.yaml ``` Inside tmux, the loader offers to switch clients or append windows. Detach with your tmux prefix followed by `d` to leave the session running. ## Load JSON without attaching The same configuration fields also work in JSON. Save this separate workspace as `workspace.json`: ```json { "session_name": "json-workspace", "windows": [ { "window_name": "editor", "panes": ["echo ready", "echo ready"] } ] } ``` Load it detached on a dedicated socket: ```console $ tmuxp load \ -L workspace-json-example \ -d \ workspace.json ``` Inspect its panes: ```console $ tmux -L workspace-json-example list-panes -t '=json-workspace:editor' ``` Remove the example session when finished: ```console $ tmux -L workspace-json-example kill-session -t '=json-workspace' ``` ## More configurations The upstream [configuration examples](https://tmuxp.git-pull.com/configuration/examples/) cover layouts, focus, directories, environment values, and command shorthand. The [load reference](https://tmuxp.git-pull.com/cli/load/) documents file selection, attachment, and existing sessions. For contributors studying how a file becomes a session, see the [internal builder example](https://libtmux.org/en/py/stable/workspace/internals/examples/). [Two-pane YAML source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/examples/2-pane-vertical.yaml) --- # API glossary Source: https://libtmux.org/en/py/stable/workspace/reference/glossary/ > Kinds, modifiers and package labels in the Python API reference. ## Symbol kinds Kinds identify declarations in the Python API reference. ### class A Python type defining attributes and behavior for its instances. References: [Python classes](https://docs.python.org/3/tutorial/classes.html). ### function A Python callable defined with def or a lambda expression. References: [Python function definitions](https://docs.python.org/3/reference/compound_stmts.html#function-definitions). ### method A Python callable obtained through a class or instance. An ordinary bound method supplies its instance as the first argument. References: [Python instance methods](https://docs.python.org/3/reference/datamodel.html#instance-methods). ### property A Python descriptor whose getter, setter or deleter runs during attribute access. A property need not correspond to a stored field, and reading it may execute code. References: [Python properties](https://docs.python.org/3/library/functions.html#property). ### attribute A named Python value accessed on an object or class, potentially through a descriptor or dynamic lookup. References: [Python attribute access](https://docs.python.org/3/reference/datamodel.html#customizing-attribute-access). ### constant A named Python API value conventionally treated as constant. Uppercase naming does not prevent reassignment at runtime. References: [Python constant naming](https://peps.python.org/pep-0008/#constants). ### exception A Python exception class whose instances can be raised and handled with except. References: [Python exceptions](https://docs.python.org/3/tutorial/errors.html#user-defined-exceptions). ## Modifiers Modifiers add information about calling, implementing, or accessing a declaration. Their precise effect follows the language and the signature. ### classmethod A Python method that receives the class as its implicit first argument, including when called through an instance. References: [Python class methods](https://docs.python.org/3/library/functions.html#classmethod). ### async A Python coroutine function declared with async def. Calling it creates a coroutine to await or schedule. References: [Python coroutine functions](https://docs.python.org/3/reference/compound_stmts.html#coroutine-function-definition). ### inherited A Python member resolved from a base class through the method resolution order. The reference names the declaring class so its original definition remains navigable. References: [Python inheritance](https://docs.python.org/3/tutorial/classes.html#inheritance). ## Package context Package labels identify where an API is supplied. ### package The Python distribution supplying this API. Its installation name can differ from the package name used in imports. References: [Python distributions and import packages](https://packaging.python.org/en/latest/discussions/distribution-package-vs-import-package/). --- # Exit codes and errors Source: https://libtmux.org/en/py/stable/workspace/reference/exit-codes/ > Use process status and structured error codes to handle workspace failures. tmuxp generally uses `0` for success, `1` for operation failures and `2` for argument errors. Some commands have exceptions at this documented revision. ## Exceptions to check - [`edit`](https://libtmux.org/en/py/stable/workspace/cli/edit/) does not propagate the editor child's status. - Machine [`search`](https://libtmux.org/en/py/stable/workspace/cli/search/) can return normally with no output for an invalid pattern; a missing query can show human help. - A missing import source exits with status `2`. - A missing or unsupported tmux executable can print a diagnostic and return status `0` before argument parsing. - [`freeze`](https://libtmux.org/en/py/stable/workspace/cli/freeze/) can catch a missing-session error, print it and return normally. Read both the command's output and [reference page](https://libtmux.org/en/py/stable/workspace/cli/) before using its status as the only success check. [Command source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Output formats Source: https://libtmux.org/en/py/stable/workspace/reference/output/ > Read JSON results, NDJSON events and diagnostics from the workspace command. Choose the output supported by each tmuxp command: | Command | Machine output | | --- | --- | | [`ls`](https://libtmux.org/en/py/stable/workspace/cli/ls/) | `--json` returns an object containing `workspaces`; `--ndjson` returns records | | [`search`](https://libtmux.org/en/py/stable/workspace/cli/search/) | `--json` and `--ndjson`; read the command's empty-result caveats | | [`debug-info`](https://libtmux.org/en/py/stable/workspace/cli/debug-info/) | `--json` | | [`freeze`](https://libtmux.org/en/py/stable/workspace/cli/freeze/), [`convert`](https://libtmux.org/en/py/stable/workspace/cli/convert/), imports | YAML or JSON workspace document output, separate from a result protocol | ```console $ tmuxp ls --json ``` Do not assume every command accepts a global JSON mode. Read the [command reference](https://libtmux.org/en/py/stable/workspace/cli/) for flags, prompts and destinations, and [exit codes](https://libtmux.org/en/py/stable/workspace/reference/exit-codes/) before interpreting an empty stream as success. `--color auto|always|never`, `NO_COLOR` and `FORCE_COLOR` control human styling. Use explicit output formats when a script reads the result. [Command source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Runtime and configuration support Source: https://libtmux.org/en/py/stable/workspace/reference/compatibility/ > Runtime, configuration and extension requirements for tmuxp. These pages document tmuxp 1.74.0 at the source revision linked below. Install tmuxp in its own Python environment and let its dependency resolver select a compatible libtmux release. The walkthroughs use Python 3.10 or newer and tmux 3.2a or newer. ## Configuration and extensions Read [configuration](https://libtmux.org/en/py/stable/workspace/configuration/) for normalization, inheritance, directories, commands and hooks. Parsing YAML alone does not establish that a field changes builder behavior. Plugins and custom builders execute Python code from their installed packages or configured import paths. The [inspection shell](https://libtmux.org/en/py/stable/workspace/cli/shell/) runs in the same Python environment. Optional interactive backends need their corresponding packages installed. ## Output and errors Machine formats are command-specific. Read [output](https://libtmux.org/en/py/stable/workspace/reference/output/) and [exit codes](https://libtmux.org/en/py/stable/workspace/reference/exit-codes/) for empty output and status exceptions before using tmuxp in automation. Capture reads current tmux state; it cannot recover original scripts, application state or comments. Review captured commands and directories before reloading. Gallery examples may require their named applications or plugins. Use [builder internals](https://libtmux.org/en/py/stable/workspace/internals/) for programmatic construction and extension development. [Command source](https://github.com/tmux-python/tmuxp/blob/618b398acc05506d3c682906c36cdeb29dcfa1ff/src/tmuxp/cli/__init__.py). --- # Topics Source: https://libtmux.org/en/py/stable/topics/ > Object traversal, cleanup, pane I/O, configuration, and failure handling. Use these pages for object traversal, cleanup, pane I/O, configuration, and failure handling. [Concepts](https://libtmux.org/en/py/stable/concepts/) introduces the shared object model. The concept guides also cover [control mode vs one-shot](https://libtmux.org/en/py/stable/concepts/transports/), [filtering and queries](https://libtmux.org/en/py/stable/concepts/queries/), and [workspaces](https://libtmux.org/en/py/stable/concepts/workspaces/). Choose a topic for more detailed behavior. Use your port's API reference for signatures and defaults. Each topic explains the behavior behind those calls. - [Architecture](https://libtmux.org/en/py/stable/topics/architecture/): Locate operations and field definitions in the library source. - [Traversal](https://libtmux.org/en/py/stable/topics/traversal/): Navigate related objects, test membership, and compare identity. - [Ownership and cleanup](https://libtmux.org/en/py/stable/topics/context-managers/): Manage cleanup on block exit and identify objects that need a kill. - [Pane interaction](https://libtmux.org/en/py/stable/topics/pane-interaction/): Choose input modes, capture ranges, and completion waits. - [Options and hooks](https://libtmux.org/en/py/stable/topics/options-and-hooks/): Configure tmux and register event commands at a supported scope. - [Format-token fields](https://libtmux.org/en/py/stable/topics/format-tokens/): Read typed state and handle absent fields. - [Waiting and retrying](https://libtmux.org/en/py/stable/topics/waiting-and-retry/): Wait on a condition or a named tmux signal. - [Environment](https://libtmux.org/en/py/stable/topics/environment/): Locate objects from process variables and configure new panes. - [Socket and servers](https://libtmux.org/en/py/stable/topics/socket-and-servers/): Select a server, check liveness, and detect a replacement daemon. - [Errors and exceptions](https://libtmux.org/en/py/stable/topics/errors-and-exceptions/): Handle command failures and decide whether a mutation can be retried. --- # Architecture Source: https://libtmux.org/en/py/stable/topics/architecture/ > Locate operations, distinguish snapshots from live commands, and find their implementation. A server handle selects a tmux server. Object IDs select sessions, windows, and panes within it. For the object hierarchy and stable IDs, start with [Server, session, window, pane](https://libtmux.org/en/py/stable/concepts/server-session-window-pane/). ## Calling operations Session, window, and pane handles carry their ID and server context. Call an operation on the object you want to change. The examples below send input and kill that pane. ```python pane.send_keys("echo hi") pane.kill() ``` ## Reading tmux fields Object IDs become tmux targets (`-t`). Format variables (`#{...}`) provide the state returned by tmux. [`libtmux.constants`]() defines the format fields and their scope and tmux-version requirements. [`Obj`]() in [`libtmux.neo`]() exposes the captured values as dataclass fields. A field excluded by those requirements is [`None`](). ## Source layout [`Server`](), [`Session`](), [`Window`](), [`Pane`](), and [`Client`]() each have their own module: [`src/libtmux/server.py`](), [`src/libtmux/session.py`](), [`src/libtmux/window.py`](), [`src/libtmux/pane.py`](), and [`src/libtmux/client.py`](). [`src/libtmux/common.py`]() holds shared behavior. [`src/libtmux/neo.py`]() defines the dataclass query layer, [`src/libtmux/options.py`]() and [`src/libtmux/hooks.py`]() provide mixins, and [`src/libtmux/exc.py`]() defines the exception hierarchy. --- # Traversal Source: https://libtmux.org/en/py/stable/topics/traversal/ > Moving up and down the server/session/window/pane tree, and the two questions that come up once you have more than one object. Use relationships to move between sessions, windows, and panes. [Server, session, window, pane](https://libtmux.org/en/py/stable/concepts/server-session-window-pane/) explains the hierarchy and snapshot model. This page covers relationship calls, collection membership, and object identity. ## Down the hierarchy List children through the parent object or a captured snapshot. Whether a read issues another tmux command depends on the API, independently of whether the call is async; see [Server, session, window, pane](https://libtmux.org/en/py/stable/concepts/server-session-window-pane/). Read [`Server.sessions`](), then [`Session.windows`]() and [`Window.panes`]() to traverse from the server down to its panes. ## All panes in a session Use a session-wide pane collection when the task spans several windows, such as finding a command or capturing output from every pane. A window linked to multiple sessions still refers to the same tmux panes. Check whether the API reads live state or traverses a captured graph before reusing its result. [`libtmux.Session.panes`]() runs a session-scoped [`list-panes -s`](https://libtmux.org/en/tmux/latest/manual/list-panes/) read. Use it to list panes across the session's windows without manually listing each window. ## Up the hierarchy Parent lookups may read captured data or query tmux again. Check the method's read and failure semantics; [Server, session, window, pane](https://libtmux.org/en/py/stable/concepts/server-session-window-pane/) introduces that distinction: Read [`Pane.window`]() for a pane’s window and [`Window.session`]() for a window’s session. ## One walk, down and back up List a session's windows, then look up a parent and compare its identity with the starting object: ```python session = server.sessions[0] window = session.windows[0] pane = window.panes[0] pane.window.window_id == window.window_id window.session.session_id == session.session_id ``` ## The active child The active window and pane identify where untargeted input goes. Use their accessors or inspect the active flags in a captured snapshot: Read [`Session.active_window`]() and [`Window.active_pane`]() for the selected objects. [Format-token fields](https://libtmux.org/en/py/stable/topics/format-tokens/) describes the underlying [`window_active`](https://libtmux.org/en/tmux/latest/catalog/formats/window_active/) and [`pane_active`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_active/) fields. ## Is it in that collection? Checking membership generally goes through whatever your language uses for collection membership, since most of these calls already return an ordinary array, slice, or list: [`QueryList`]() supports [`in`](): use `window in session.windows` or `pane in window.panes`. ## Is this the same object? Compare IDs to determine whether two handles refer to the same tmux object on the same server. Check what handle equality includes before using it as an identity test: Compare [`Window.window_id`]() or [`Pane.pane_id`]() when checking whether two handles name the same object on the same server. --- # Ownership and cleanup Source: https://libtmux.org/en/py/stable/topics/context-managers/ > Scope-based cleanup for tmux objects, and when your program must kill them explicitly. A tmux session, window, or pane normally remains until you kill it. Scope-based cleanup can kill it when your code leaves a block, including after an exception. See [Workspaces](https://libtmux.org/en/py/stable/concepts/workspaces/) for a temporary layout example. ## Nested context managers Python's [`Server`](), [`Session`](), [`Window`](), and [`Pane`]() support context managers. Entry returns the existing object; exit kills it, including when the block raises: ```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"') # everything above is killed on the way out, in reverse order ``` Nested scopes exit in reverse order: pane, window, session, then server. ## Testing cleanup Use explicit cleanup for objects whose handles have no disposal hook. For an entire disposable test server, prefer your port's test fixture or server guard; see [Testing with libtmux](https://libtmux.org/en/py/stable/guides/testing-with-libtmux/). --- # Pane interaction Source: https://libtmux.org/en/py/stable/topics/pane-interaction/ > Input defaults, screen capture, and waiting for a command to finish. Send input to a pane and capture its screen to interact with a running program. [Attach and send keys](https://libtmux.org/en/py/stable/examples/attach-and-send-keys/) provides examples. [Sending keys](https://libtmux.org/en/py/stable/guides/sending-keys/) and [Capturing output](https://libtmux.org/en/py/stable/guides/capturing-output/) are task guides; this page covers input defaults, capture ranges, and completion handling. ## Typing into a pane Two questions come up every time you send something to a pane: should tmux press Enter afterward, and should tmux interpret what you sent as key names ([`Enter`](https://libtmux.org/en/tmux/latest/manual/send-keys/), `C-c`) rather than literal characters? Choose both explicitly when a command depends on them. **Type without Enter:** [`pane.send_keys(text, enter=False)`]() **Type + Enter (default):** [`pane.send_keys(text)`]() **How "literal" is chosen:** `literal=True` flag on the same method ### Examples Text and Enter can be separate tmux commands. If the second operation fails, the text may already be in the pane. Check the current state before retrying; repeating the whole request can duplicate input. Send a command line and press Enter: ```python pane.send_keys("echo hi", enter=False) # type without pressing Enter pane.send_keys("echo hi") # default: presses Enter afterward ``` ## Reading a pane back Capture reads the pane's visible screen by default. Request scrollback when you need earlier output. A capture is a snapshot of terminal contents, including any input echoed by the application. ```python pane.capture_pane() ``` ## Waiting for something to finish A send call completes when input reaches tmux. It does not wait for the shell command to finish. Wait for expected output or a completion signal. Poll capture output for a marker or use the [`wait_for`]() signal channel when you control the command. The test-support module provides `libtmux.test.retry_until(condition, ...)` for arbitrary conditions. [Capture pane output](https://libtmux.org/en/py/stable/examples/capture-pane-output/) shows capture and waiting examples. [Waiting and retrying](https://libtmux.org/en/py/stable/topics/waiting-and-retry/) explains completion conditions and timeouts.
tmux manual and source The tmux manual defines [key-name and literal input](https://github.com/tmux/tmux/blob/94796f6b1182507efac8a272fc309a79e22e58a5/tmux.1#L4457) and [screen and history capture](https://github.com/tmux/tmux/blob/94796f6b1182507efac8a272fc309a79e22e58a5/tmux.1#L2798). A send operation delivers input; it does not establish the program's exit status.
--- # Options and hooks Source: https://libtmux.org/en/py/stable/topics/options-and-hooks/ > Read and update tmux options, and register commands for tmux events. Use options to change tmux behavior, such as [`automatic-rename`](https://libtmux.org/en/tmux/latest/catalog/options/automatic-rename/) or the status-line format. Use hooks to run commands on events such as [`session-renamed`](https://libtmux.org/en/tmux/latest/catalog/hooks/session-renamed/) or [`after-split-window`](https://libtmux.org/en/tmux/latest/catalog/hooks/after-split-window/). Choose the scope supported by the option or hook. ## Reading and writing options Read, set, or unset an option at its supported scope. Distinguish a local override from the effective value inherited from a parent scope. **Read all (this scope):** [`pane.show_options()`]() **Read effective/inherited:** [`pane.show_option(name, global_=True)`]() reaches the global fallback explicitly; no separate "resolved" call **Set:** [`pane.set_option(name, value)`]() **Unset:** [`pane.unset_option(name)`]() ### Examples After a successful write completes, read the option to obtain its updated value. The following examples set, read, and unset an option: ```python pane.set_option("automatic-rename", "off") pane.show_options() pane.unset_option("automatic-rename") ``` ## Hooks **Set:** [`pane.set_hook(name, command)`]() **Unset:** [`pane.unset_hook(name)`]() **List:** [`pane.show_hook(name)`](), [`pane.show_hooks()`]() (all) **Run now, without the event:** Not listed. ### Examples tmux stores hook commands in indexed arrays, such as [`after-new-window[0]`](https://libtmux.org/en/tmux/latest/catalog/hooks/after-new-window/). Include the array index in the hook name. Set and list a session hook. The next section explains window and pane scope limitations: ```python session.set_hook("session-renamed", "display-message 'renamed'") session.show_hooks() ``` ## Supported hook scopes tmux stores hooks globally or per session. Accepted [`set-hook -w`](https://libtmux.org/en/tmux/latest/manual/set-hook/) or `-p` flags do not imply a separate window or pane hook table, and [`show-hooks`](https://libtmux.org/en/tmux/latest/manual/show-hooks/) does not provide a corresponding listing. Check the event's supported scope if a hook is accepted but never fires. Options have window and pane tables of their own. The hook-scope limitation does not apply to ordinary options. ## tmux version compatibility The compatibility notes list these tmux requirements: | Feature | Minimum tmux | |---------|-------------| | All options/hooks features | 3.2+ | | Window/pane hook *scope flags* (`-w`, `-p`) accepted | 3.2+; see the supported-scope caveat above | | [`client-active`](https://libtmux.org/en/tmux/latest/catalog/hooks/client-active/), [`window-resized`](https://libtmux.org/en/tmux/latest/catalog/hooks/window-resized/) hooks | 3.3+ | | [`pane-title-changed`](https://libtmux.org/en/tmux/latest/catalog/hooks/pane-title-changed/) hook | 3.2+ | The [`pane-title-changed`](https://libtmux.org/en/tmux/latest/catalog/hooks/pane-title-changed/) hook was [added before tmux 3.2](https://github.com/tmux/tmux/commit/d329b035cee47d968a8c93b5cbd8fde879ce6f0d). It is present in both the documented [3.2a source](https://github.com/tmux/tmux/blob/3b929f332aafa7f1080eacc31feb11ffbb1d1841/options-table.c#L1143) and the [3.7c source](https://github.com/tmux/tmux/blob/e476c1230b958df0cb12977517d24b3dc931375b/options-table.c#L1700). Check the library's supported tmux versions before using a version-specific option or hook.
tmux manual and source The tmux manual defines [option scopes and inherited reads](https://github.com/tmux/tmux/blob/94796f6b1182507efac8a272fc309a79e22e58a5/tmux.1#L4725). Unsetting a local value restores inheritance. Hook programs run in tmux when their event occurs; see the [hook implementation](https://github.com/tmux/tmux/blob/94796f6b1182507efac8a272fc309a79e22e58a5/cmd-set-option.c).
--- # Format-token fields Source: https://libtmux.org/en/py/stable/topics/format-tokens/ > The typed fields every object exposes, mirroring tmux's own format tokens, and why a field is sometimes absent. Object fields expose values from tmux's [FORMATS](https://man.openbsd.org/tmux.1#FORMATS), such as [`pane_id`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_id/), [`window_zoomed_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/window_zoomed_flag/), and [`session_name`](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/). The available fields depend on the accessor, object scope, tmux version, and data requested by the read. A token needs the right **scope** and **tmux version**. For example, a pane token needs a pane context, and a token added after your tmux release may be absent. Check the accessor's result before using a field that can be missing, as described below. ## Handling an absent field An excluded field has the value [`None`](). These examples read optional fields, including [`pane_dead_signal`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_dead_signal/) on tmux 3.3 or newer: ```python pane.pane_dead_signal # None below tmux 3.3, or on a pane that isn't dead ``` ## Field availability Field accessors retain the scope and version requirements of tmux tokens. Version gates describe tmux behavior: [`pane_dead_signal`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_dead_signal/) and [`pane_dead_time`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_dead_time/) arrived in tmux 3.3, and a cluster of pane-geometry and floating-pane tokens ([`pane_floating_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_floating_flag/), [`pane_pb_progress`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_pb_progress/), [`pane_x`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_x/), [`pane_y`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_y/), [`pane_z`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_z/), [`pane_zoomed_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_zoomed_flag/), [`bracket_paste_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/bracket_paste_flag/), [`synchronized_output_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/synchronized_output_flag/), among others) arrived together in 3.7. ## Fields promoted from the active child Python exposes fields promoted from an active child. For example, [`session.pane_id`]() identifies the active pane of the session's active window: ```python >>> session = server.new_session() >>> session.pane_id == session.active_window.active_pane.pane_id True ``` tmux's format engine includes active-child fields when listing a parent. A [`list-sessions -F`](https://libtmux.org/en/tmux/latest/manual/list-sessions/) row can include [`window_id`](https://libtmux.org/en/tmux/latest/catalog/formats/window_id/) and [`pane_id`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_id/) for the active window and pane. Check the port reference for typed access to those fields, or use the explicit relationships described in [Traversal](https://libtmux.org/en/py/stable/topics/traversal/). A pane context can include parent window and session fields. A session cannot identify one attached client when several clients may be attached, so client tokens such as [`client_name`](https://libtmux.org/en/tmux/latest/catalog/formats/client_name/) require a client context. --- # Waiting and retrying Source: https://libtmux.org/en/py/stable/topics/waiting-and-retry/ > Polling a condition instead of guessing a sleep, and tmux's own wait-for signal channel as the alternative to polling. After sending input or starting a process, wait for the state your next step requires. [Pane interaction](https://libtmux.org/en/py/stable/topics/pane-interaction/#waiting-for-something-to-finish) covers waiting for screen text. This page covers arbitrary conditions and tmux's named [`wait-for`](https://libtmux.org/en/tmux/latest/manual/wait-for/) signal channels. ## Polling a condition Polling checks a condition repeatedly until it succeeds or a deadline expires. Set a deadline and choose an interval that limits unnecessary tmux commands. **Helper:** `libtmux.test.retry_until(fn, seconds=, interval=)` **Where it lives:** [`src/libtmux/test/`]() in the main package; raises [`WaitTimeout`](). ### Examples ```python def is_window_up(pane, name): return any(w.window_name == name for w in pane.window.session.windows) libtmux.test.retry_until(lambda: is_window_up(pane, "build"), seconds=5.0) ``` ## tmux's own [wait-for](https://libtmux.org/en/tmux/latest/manual/wait-for/) channel Use [`tmux wait-for -S `](https://libtmux.org/en/tmux/latest/manual/wait-for/) to signal and [`tmux wait-for `](https://libtmux.org/en/tmux/latest/manual/wait-for/) to block until signalled. This avoids repeated screen captures when the command can announce its own completion: Signal a channel with [`Server.wait_for`]() and `set_flag=True`. Call the same method without that flag to wait for the signal. ```python server.new_session(session_name="work") server.wait_for("built", set_flag=True) # signal server.wait_for("built") # block until signalled ``` tmux remembers a signal sent before a waiter starts. The next wait on that channel returns immediately, so completion is not lost when the command finishes first. A raw [`wait-for`](https://libtmux.org/en/tmux/latest/manual/wait-for/) client can exit zero when the server dies, as well as when the channel is signalled. Verify server liveness when a lost server must be treated as a failed task. Use a channel name specific to the task. A remembered signal can otherwise satisfy an unrelated later wait.
tmux manual and source The tmux manual describes [completion channels](https://github.com/tmux/tmux/blob/94796f6b1182507efac8a272fc309a79e22e58a5/tmux.1#L8715). The [channel implementation](https://github.com/tmux/tmux/blob/94796f6b1182507efac8a272fc309a79e22e58a5/cmd-wait-for.c#L388) retains an early signal until a waiter consumes it. Use a fresh channel name for each operation.
--- # Environment Source: https://libtmux.org/en/py/stable/topics/environment/ > Locate tmux objects from process variables and manage the environment inherited by new panes. tmux exposes two environment APIs. Process variables such as [`TMUX`]() and [`TMUX_PANE`]() let code inside a pane identify its server and pane. The server also stores variables through [`set-environment`](https://libtmux.org/en/tmux/latest/manual/set-environment/) and [`show-environment`](https://libtmux.org/en/tmux/latest/manual/show-environment/) for new processes to inherit. Like the tables in [Options and hooks](https://libtmux.org/en/py/stable/topics/options-and-hooks/), this persistent store has explicit scopes. ## Locating yourself from inside a pane Inside a pane, [`TMUX`]() contains `,,`, and [`TMUX_PANE`]() contains the pane ID, such as `%1`. Use these variables to locate the current tmux objects. Select the object your operation needs: **Server:** [`Server.from_env()`]() **Session:** [`Session.from_env()`]() **Window:** [`Window.from_env()`]() **Pane:** [`Pane.from_env()`]() ### Examples ```python Pane.from_env().pane_id Window.from_env().window_id Session.from_env().session_id Server.from_env().sessions ``` Environment lookup requires valid tmux targeting variables. If your process can run outside tmux, handle that case before using the result. [`NotInsideTmux`]() reports a missing or invalid tmux environment. ## tmux's own environment variable store Like [Options and hooks](https://libtmux.org/en/py/stable/topics/options-and-hooks/), tmux's persistent environment store has global and per-session scopes. It is read with [`show-environment`](https://libtmux.org/en/tmux/latest/manual/show-environment/) and updated with [`set-environment`](https://libtmux.org/en/tmux/latest/manual/set-environment/). Newly spawned processes inherit it; existing processes retain their own environments. **Set:** [`server.set_environment(name, value)`](), [`session.set_environment(...)`]() **Read all:** [`server.show_environment()`](), [`session.show_environment()`]() **Unset:** [`server.unset_environment(name)`](). See below for `.remove_environment()`. ### Examples ```python server.set_environment("EDITOR", "vim") # global session.set_environment("EDITOR", "hx") # this session only session.show_environment() ``` [`set-environment`](https://libtmux.org/en/tmux/latest/manual/set-environment/) writes a value. Its `-u` flag removes the entry, while `-r` marks the variable for exclusion from new processes, including values tmux inherited at startup. The listing retains an excluded variable as `-NAME`. Use `unset_environment` for `-u`, or `remove_environment` for `-r`. --- # Socket and servers Source: https://libtmux.org/en/py/stable/topics/socket-and-servers/ > Select a server socket, check liveness, and detect a replacement daemon. A tmux server is selected by its Unix-domain socket. Use different sockets for independent servers, such as a development session and an isolated test server. Choose the default socket, a named socket (`-L`), or an explicit path (`-S`). ## Naming a server [`Server()`]() selects the default socket. Pass `socket_name="work"` to select a named socket, or `socket_path="/tmp/tmux-1000/work"` for an explicit path. ```python default_server = libtmux.Server() named = libtmux.Server(socket_name="work") ``` Choose either a socket name or a socket path. tmux uses `TMUX_TMPDIR` to resolve the directory for default and named sockets. [`Server(socket_name_factory=...)`]() accepts a callable that generates socket names. Use a unique name for each isolated test server. ## Is the server actually there? A server handle does not prove that the target server is running. Use a liveness check when your program needs to distinguish a live server from an unavailable socket: [`Server.is_alive`]() returns a boolean indicating whether the server responds. ```python if server.is_alive(): server.sessions ``` ## Killing a server, and telling two apart Killing a server ends all its sessions. Use this only for a server your program owns; for narrower cleanup, kill the session or pane you created. Call [`server.kill_server()`](). [`Server.__eq__`]() compares [`socket_name`]() and [`socket_path`](https://libtmux.org/en/tmux/latest/catalog/formats/socket_path/) when deciding whether two handles select the same endpoint. A restarted server can reuse a socket path while having different state. Do not treat a matching path as proof that a cached object still exists. --- # Errors and exceptions Source: https://libtmux.org/en/py/stable/topics/errors-and-exceptions/ > Handle command failures, inspect delivery status, and decide when a retry is safe. A command can fail because tmux rejects it, or because the transport stops before returning a reply. Inspect the reported error and delivery state before retrying a mutation: tmux may already have received it. For lookup failures caused by zero or multiple matches, see [Filtering and queries](https://libtmux.org/en/py/stable/concepts/queries/#the-cardinality-contract-side-by-side). ## A failed command, as a value Command failures raise [`LibTmuxException`](). It can carry a `subcommand`; its string representation includes the subcommand and stderr. ## Is it safe to retry? Retry a mutation automatically only when you know it was not dispatched, or when repeating it is safe for your operation. A timeout, cancellation, or dropped connection can occur after tmux has acted. These APIs expose delivery information: Inspect the exit status after a subprocess completes. If the call was interrupted, verify the resulting tmux state before repeating a mutation. Treat unknown delivery as potentially executed. For subprocess calls that complete normally, inspect the exit status. If a call is interrupted or times out without a delivery state, check tmux's resulting state before repeating a mutation. --- # Tools Source: https://libtmux.org/en/py/stable/mcp/tools/ > Browse the operations the server exposes to MCP clients. Use the registered name and arguments when sending a tools/call request. Browse the operations the server exposes to MCP clients. Use the registered name and arguments when sending a tools/call request. MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. The reference configuration advertises 54 tools. Your server’s available objects depend on its configuration. [Setup documentation](https://libtmux.org/en/py/stable/mcp/guides/) explains how to connect a client. ## Server5 tools[#](https://libtmux.org/en/py/stable/mcp/tools/#tools-server) [create​_session](https://libtmux.org/en/py/stable/mcp/tools/create_session/) Create a new tmux session. [get​_server​_info](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/) Get information about the tmux server. [kill​_server](https://libtmux.org/en/py/stable/mcp/tools/kill_server/) Kill the tmux server and all its sessions. [list​_servers](https://libtmux.org/en/py/stable/mcp/tools/list_servers/) Discover live tmux servers under the current user’s `$TMUX_TMPDIR`. [list​_sessions](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/) List tmux sessions (terminal workspaces) on a tmux server. ## Session5 tools[#](https://libtmux.org/en/py/stable/mcp/tools/#tools-session) [create​_window](https://libtmux.org/en/py/stable/mcp/tools/create_window/) Create a new window in a tmux session. [get​_session​_info](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/) Return metadata for a single tmux session (ID, name, window count, activity). [kill​_session](https://libtmux.org/en/py/stable/mcp/tools/kill_session/) Kill a tmux session. [list​_windows](https://libtmux.org/en/py/stable/mcp/tools/list_windows/) List tmux windows (terminal tabs) in a session, or across the server. [rename​_session](https://libtmux.org/en/py/stable/mcp/tools/rename_session/) Rename a tmux session. ## Window9 tools[#](https://libtmux.org/en/py/stable/mcp/tools/#tools-window) [get​_window​_info](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/) Return metadata for a single tmux window (ID, name, layout, dimensions). [kill​_window](https://libtmux.org/en/py/stable/mcp/tools/kill_window/) Kill (close) a tmux window. Requires exact window_id (e.g. ‘@3’). [list​_panes](https://libtmux.org/en/py/stable/mcp/tools/list_panes/) List tmux panes (terminal multiplexer splits) in a window, session, or server. [move​_window](https://libtmux.org/en/py/stable/mcp/tools/move_window/) Move a window to a different index or session. [rename​_window](https://libtmux.org/en/py/stable/mcp/tools/rename_window/) Rename a tmux window. [resize​_window](https://libtmux.org/en/py/stable/mcp/tools/resize_window/) Resize a tmux window. [select​_layout](https://libtmux.org/en/py/stable/mcp/tools/select_layout/) Set the layout of a tmux window. [select​_window](https://libtmux.org/en/py/stable/mcp/tools/select_window/) Select (focus) a tmux window by ID, index, or direction. [split​_window](https://libtmux.org/en/py/stable/mcp/tools/split_window/) Split a tmux window to create a new pane. ## Pane18 tools[#](https://libtmux.org/en/py/stable/mcp/tools/#tools-pane) [capture​_pane](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/) Capture the visible contents of a tmux pane (terminal scrollback). [capture​_since](https://libtmux.org/en/py/stable/mcp/tools/capture_since/) Capture new tmux terminal scrollback since the previous cursor. [clear​_pane](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/) Clear the contents of a tmux pane. [find​_pane​_by​_position](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/) Find the pane occupying a corner of a tmux window. [get​_pane​_info](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/) Get detailed information about a tmux pane. [kill​_pane](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/) Kill (close) a tmux pane. Requires exact pane_id (e.g. ‘%5’). [paste​_text](https://libtmux.org/en/py/stable/mcp/tools/paste_text/) Paste multi-line text into a pane using tmux paste buffers. [pipe​_pane](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/) Log a pane’s live output to a file (or stop an active log). [resize​_pane](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/) Resize a tmux pane. [respawn​_pane](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/) Restart a pane’s process in place, preserving pane_id and layout. [run​_command](https://libtmux.org/en/py/stable/mcp/tools/run_command/) Run a shell command in a pane, wait for completion, and capture output. [search​_panes](https://libtmux.org/en/py/stable/mcp/tools/search_panes/) Search visible terminal text across all tmux panes. [select​_pane](https://libtmux.org/en/py/stable/mcp/tools/select_pane/) Select (focus) a tmux pane by ID or direction. [send​_keys](https://libtmux.org/en/py/stable/mcp/tools/send_keys/) Send keys (commands or text) to a tmux pane. [send​_keys​_batch](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/) Send an ordered batch of raw key/text operations to tmux panes. [set​_pane​_title](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/) Set the title of a tmux pane. [snapshot​_pane](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/) Snapshot a tmux pane: visible terminal output, cursor, mode, scroll. [swap​_pane](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/) Swap the positions of two panes. ## Buffers4 tools[#](https://libtmux.org/en/py/stable/mcp/tools/#tools-buffers) [delete​_buffer](https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/) Delete an MCP-owned buffer. [load​_buffer](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/) Load text into a new agent-namespaced tmux paste buffer. [paste​_buffer](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/) Paste an MCP-owned buffer into a pane. [show​_buffer](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/) Read back the contents of an MCP-owned buffer. ## Hooks2 tools[#](https://libtmux.org/en/py/stable/mcp/tools/#tools-hooks) [show​_hook](https://libtmux.org/en/py/stable/mcp/tools/show_hook/) Look up a specific tmux hook by name. [show​_hooks](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/) List configured tmux hooks at the given scope. ## Options and environment4 tools[#](https://libtmux.org/en/py/stable/mcp/tools/#tools-options-and-environment) [set​_environment](https://libtmux.org/en/py/stable/mcp/tools/set_environment/) Set a tmux environment variable. [set​_option](https://libtmux.org/en/py/stable/mcp/tools/set_option/) Set a tmux option value. [show​_environment](https://libtmux.org/en/py/stable/mcp/tools/show_environment/) Show tmux environment variables. [show​_option](https://libtmux.org/en/py/stable/mcp/tools/show_option/) Show a tmux option value. ## Coordination2 tools[#](https://libtmux.org/en/py/stable/mcp/tools/#tools-coordination) [signal​_channel](https://libtmux.org/en/py/stable/mcp/tools/signal_channel/) Signal a tmux [`wait-for`](https://libtmux.org/en/tmux/latest/manual/wait-for/) channel, waking blocked waiters. [wait​_for​_channel](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/) Block until a tmux [`wait-for`](https://libtmux.org/en/tmux/latest/manual/wait-for/) channel is signalled. ## Other tools5 tools[#](https://libtmux.org/en/py/stable/mcp/tools/#tools-other-tools) [call​_read​_tools​_batch](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/) Call several `inspect` tools serially and return per-tool results. [display​_message](https://libtmux.org/en/py/stable/mcp/tools/display_message/) Read tmux variables against a target and return the substituted text. [enter​_copy​_mode](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/) Enter copy mode in a tmux pane, optionally scrolling up. [exit​_copy​_mode](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/) Exit copy mode in a tmux pane. [wait​_for​_text](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/) Wait for NEW output in a tmux pane, then return. ## [Resources](https://libtmux.org/en/py/stable/mcp/resources/) This server does not advertise resources in the reference configuration. ## [Resource templates](https://libtmux.org/en/py/stable/mcp/resources/#resources-resource-templates) 6 advertised in the reference configuration. ## [Prompts](https://libtmux.org/en/py/stable/mcp/prompts/) 4 advertised in the reference configuration. Reference configuration * `LIBTMUX_TOOLSETS` `inspect,manage,execute,teardown` Protocol version: `2025-11-25`. [Download the full protocol catalog](https://libtmux.org/en/py/stable/mcp/tools.json). Source: [`tmux-python/libtmux-mcp@4daddc0dfca9`](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). The [language API reference](https://libtmux.org/en/py/stable/mcp/reference/) documents embedding and implementation types. Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). --- # call_read_tools_batch Source: https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/ > Call several inspect tools serially and return per-tool results. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **call_read_tools_batch**( [on_error](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Fon_error)?: "stop" | "continue", [operations](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations): [Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>, ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/batch_tools.py#L277)][¶](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch) Call several `inspect` tools serially and return per-tool results. Use when one agent turn needs several observations. Each nested call still goes through FastMCP validation and this server’s middleware. Only `inspect` tools are accepted; anything that changes tmux state is refused, whatever this server has enabled. This wrapper aggregates authority under its own name: a client rule keyed on a nested tool’s name does not fire for a call made through it. Read it as authority to invoke any `inspect` tool. * MCP request method `tools/call` Send `call_read_tools_batch` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.parameters) * **[`on_error`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Fon_error)**? = `"stop"` ("stop" | "continue") * **[`operations`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations)** ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>) * **[Items](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) One nested MCP tool call for a batch wrapper. * **[`arguments`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for the nested tool call. * **[`tool`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Ftool)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Registered MCP tool name to call. No other properties are accepted. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`failed`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Ffailed)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of nested tool calls that failed. * **[`response_truncated`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresponse_truncated)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) True when nested result payloads were elided to keep the batch response under the server response cap. * **[`response_truncated_bytes`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresponse_truncated_bytes)**? = `0` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Approximate serialized bytes removed from nested result payloads. * **[`results`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults)**? ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>) Per-operation results in attempted order. * **[Items](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Per-operation result from a generic MCP tool batch. * **[`content`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fcontent)**? ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>) MCP content blocks returned by the nested tool. * **[Items](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fcontent%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`elapsed_seconds`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Felapsed_seconds)** ([number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Time spent on this operation. * **[`error`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Ferror)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Error message for this operation, if it failed. * **[`index`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Zero-based index in the submitted operation list. * **[`meta`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fmeta)**? = `null` ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Runtime metadata returned by the nested tool, if any. Matches one or more variants. * **[Variant 1](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fmeta%2FanyOf%2F0)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`structured_content`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fstructured_content)**? = `null` ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Structured content returned by the nested tool, if any. Matches one or more variants. * **[Variant 1](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fstructured_content%2FanyOf%2F0)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`success`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fsuccess)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) True when this nested tool call succeeded. * **[`tool`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Ftool)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Nested tool name that was attempted. * **[`stopped_at`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fstopped_at)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Index where processing stopped because on_error=‘stop’, or None when all operations were attempted. * **[`succeeded`](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fsucceeded)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of nested tool calls that succeeded. ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "on_error": { "default": "stop", "enum": [ "stop", "continue" ], "type": "string" }, "operations": { "items": { "additionalProperties": false, "description": "One nested MCP tool call for a batch wrapper.", "properties": { "arguments": { "additionalProperties": true, "description": "Arguments for the nested tool call.", "type": "object" }, "tool": { "description": "Registered MCP tool name to call.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, "type": "array" } }, "required": [ "operations" ], "type": "object" } ``` Output schema ```json { "description": "Structured result for a serial batch of MCP tool calls.", "properties": { "failed": { "description": "Number of nested tool calls that failed.", "type": "integer" }, "response_truncated": { "default": false, "description": "True when nested result payloads were elided to keep the batch response under the server response cap.", "type": "boolean" }, "response_truncated_bytes": { "default": 0, "description": "Approximate serialized bytes removed from nested result payloads.", "type": "integer" }, "results": { "description": "Per-operation results in attempted order.", "items": { "description": "Per-operation result from a generic MCP tool batch.", "properties": { "content": { "description": "MCP content blocks returned by the nested tool.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "elapsed_seconds": { "description": "Time spent on this operation.", "type": "number" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error message for this operation, if it failed." }, "index": { "description": "Zero-based index in the submitted operation list.", "type": "integer" }, "meta": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Runtime metadata returned by the nested tool, if any." }, "structured_content": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Structured content returned by the nested tool, if any." }, "success": { "description": "True when this nested tool call succeeded.", "type": "boolean" }, "tool": { "description": "Nested tool name that was attempted.", "type": "string" } }, "required": [ "index", "tool", "success", "elapsed_seconds" ], "type": "object" }, "type": "array" }, "stopped_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Index where processing stopped because on_error='stop', or None when all operations were attempted." }, "succeeded": { "description": "Number of nested tool calls that succeeded.", "type": "integer" } }, "required": [ "succeeded", "failed" ], "type": "object" } ``` --- # capture_pane Source: https://libtmux.org/en/py/stable/mcp/tools/capture_pane/ > Capture the visible contents of a tmux pane (terminal scrollback). tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **capture_pane**( [end](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fend)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [max_lines](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fmax_lines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [start](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fstart)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L101)][¶](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane) Capture the visible contents of a tmux pane (terminal scrollback). Use for tmux pane output — ‘capture the build log’, ‘what did the server print’ — not editor file contents. The tool for reading what is displayed in a terminal; use [search_panes](https://libtmux.org/en/py/stable/mcp/tools/search_panes/) to search across multiple panes at once. Output is tail-preserved: when the capture exceeds `max_lines` the oldest lines are dropped and the returned string is prefixed with a single `[... truncated K lines ...]` header line so the agent can tell truncation occurred and re-request with a narrower `start`/`end` window or a larger `max_lines` if needed. Pass `max_lines=None` to disable truncation entirely. * MCP request method `tools/call` Send `capture_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.parameters) * **[`end`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fend)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) End line number. * **[`max_lines`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fmax_lines)**? = `500` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Maximum number of lines to return. Defaults to `CAPTURE_DEFAULT_MAX_LINES`. Pass `None` to return the full capture with no truncation. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`start`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fstart)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Start line number. 0 is the first visible line. Negative values reach into scrollback history (e.g. -100 for last 100 lines). * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.result) This server does not advertise an output schema for this tool. Its description defines the returned content. ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/#mcp.tool.capture_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "end": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "End line number." }, "max_lines": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 500, "description": "Maximum number of lines to return. Defaults to\n``CAPTURE_DEFAULT_MAX_LINES``. Pass ``None`` to return the\nfull capture with no truncation." }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "start": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Start line number. 0 is the first visible line. Negative values\nreach into scrollback history (e.g. -100 for last 100 lines)." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "type": "object" } ``` --- # capture_since Source: https://libtmux.org/en/py/stable/mcp/tools/capture_since/ > Capture new tmux terminal scrollback since the previous cursor. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **capture_since**( [cursor](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fcursor)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [max_bytes](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fmax_bytes)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [max_lines](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fmax_lines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L106)][¶](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since) Capture new tmux terminal scrollback since the previous cursor. Use for observation-first workflows: tailing a shell, watching a long-running command, or repeatedly checking a tmux workspace pane without re-sending the same visible screen every turn. The first call with `cursor=None` returns the current visible pane and an opaque cursor. Later calls pass that cursor back and receive only rows written or rewritten after the cursor, as long as tmux still retains the required scrollback history. If tmux history was cleared or trimmed before the cursor anchor, the tool returns the current visible pane with `lines_missed=True` and a fresh cursor. Malformed cursors, cursors for a different pane, pane death, and pane respawn fail with `ExpectedToolError` so agents do not accidentally observe the wrong process. * MCP request method `tools/call` Send `capture_since` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.parameters) * **[`cursor`](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fcursor)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Opaque cursor returned by a prior `capture_since` call. When omitted, the tool captures the current visible screen and starts a new cursor. * **[`max_bytes`](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fmax_bytes)**? = `128000` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Maximum UTF-8 bytes to return across `lines`. Defaults to `CAPTURE_SINCE_DEFAULT_MAX_BYTES`. Pass `None` to disable byte truncation. * **[`max_lines`](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fmax_lines)**? = `500` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Maximum number of lines to return. Defaults to `CAPTURE_SINCE_DEFAULT_MAX_LINES`. Pass `None` to disable line truncation. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). Optional when `cursor` is supplied; the cursor carries the original pane id. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.result) This server does not advertise an output schema for this tool. Its description defines the returned content. ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/capture_since/#mcp.tool.capture_since.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque cursor returned by a prior ``capture_since`` call. When\nomitted, the tool captures the current visible screen and\nstarts a new cursor." }, "max_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 128000, "description": "Maximum UTF-8 bytes to return across ``lines``. Defaults to\n``CAPTURE_SINCE_DEFAULT_MAX_BYTES``. Pass ``None`` to\ndisable byte truncation." }, "max_lines": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 500, "description": "Maximum number of lines to return. Defaults to\n``CAPTURE_SINCE_DEFAULT_MAX_LINES``. Pass ``None`` to\ndisable line truncation." }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1'). Optional when ``cursor`` is supplied; the\ncursor carries the original pane id." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "type": "object" } ``` --- # clear_pane Source: https://libtmux.org/en/py/stable/mcp/tools/clear_pane/ > Clear the contents of a tmux pane. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **clear_pane**( [pane_id](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L141)][¶](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane) Clear the contents of a tmux pane. Use before a fresh [run_command](https://libtmux.org/en/py/stable/mcp/tools/run_command/) call or raw-input observation workflow when prior scrollback would make the result harder to inspect. * MCP request method `tools/call` Send `clear_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.parameters) * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/clear_pane/#mcp.tool.clear_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # create_session Source: https://libtmux.org/en/py/stable/mcp/tools/create_session/ > Create a new tmux session. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **create_session**( [environment](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fenvironment)?: [Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [start_directory](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fstart_directory)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [suppress_persistent_history](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fsuppress_persistent_history)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [window_name](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fwindow_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [x](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fx)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [y](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fy)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/server_tools.py#L372)][¶](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session) Create a new tmux session. Check [list_sessions](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/) first to avoid name conflicts. A new session starts with one window and one pane. Values in `environment` are stored in the tmux session environment, so future panes inherit them too. * MCP request method `tools/call` Send `create_session` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.parameters) * **[`environment`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fenvironment)**? = `null` ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Environment variables to store in the session environment. Accepts either a dict of env vars or a JSON-serialized string of the same — the latter is the cursor-composer-1 workaround described in `libtmux_mcp._utils._coerce_dict_arg`. Each item appears in the tmux client argv as one `-eKEY=VALUE` element and may be visible to host process inspection during launch. tmux retains the values in tmux session state, where [`show-environment`](https://libtmux.org/en/tmux/latest/manual/show-environment/) can reveal them. They reach the initial and future child environments unless a later spawn overrides them. MCP audit redaction does not hide these surfaces. Pass credential references, not literal credentials. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Name for the new session. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. Defaults to LIBTMUX_SOCKET env var. * **[`start_directory`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fstart_directory)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Existing directory to start in. `~` expands; a relative path resolves against the MCP server process’s directory. * **[`suppress_persistent_history`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fsuppress_persistent_history)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to suppress persistent history for the spawned shell. Defaults to False for MCP and direct Python calls. This per-call option does not inherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these controls. * **[`window_name`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fwindow_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Name for the initial window. * **[`x`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fx)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width of the initial window. * **[`y`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fy)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height of the initial window. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane id (`%N`) of the session’s active pane. Guaranteed non-None on `create_session` return (libtmux creates the session with one initial pane). May be None from [`list_sessions`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/) rows for sessions in transient teardown states where `active_pane` is unavailable. * **[`session_attached`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession_attached)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Attached client count * **[`session_created`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession_created)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Creation timestamp * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session ID (e.g. ‘$1’) * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name * **[`window_count`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fwindow_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of windows ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "environment": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "string" }, { "type": "null" } ], "default": null, "description": "Environment variables to store in the session environment. Accepts\neither a dict of env vars or a JSON-serialized string of the same —\nthe latter is the cursor-composer-1 workaround described in\n:func:`libtmux_mcp._utils._coerce_dict_arg`. Each item appears in the\ntmux client argv as one ``-eKEY=VALUE`` element and may be visible to\nhost process inspection during launch. tmux retains the values in\ntmux session state, where ``show-environment`` can reveal them. They reach\nthe initial and future child environments unless a later spawn\noverrides them. MCP audit redaction does not hide these surfaces. Pass\ncredential references, not literal credentials." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Name for the new session." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name. Defaults to LIBTMUX_SOCKET env var." }, "start_directory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Existing directory to start in. ``~`` expands; a relative path\nresolves against the MCP server process's directory." }, "suppress_persistent_history": { "default": false, "description": "Whether to suppress persistent history for the spawned shell. Defaults\nto False for MCP and direct Python calls. This per-call option does not\ninherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these\ncontrols.", "type": "boolean" }, "window_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Name for the initial window." }, "x": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Width of the initial window." }, "y": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Height of the initial window." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux session.", "properties": { "active_pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane id (``%N``) of the session's active pane. Guaranteed non-None on ``create_session`` return (libtmux creates the session with one initial pane). May be None from ``list_sessions`` rows for sessions in transient teardown states where ``active_pane`` is unavailable." }, "session_attached": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Attached client count" }, "session_created": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Creation timestamp" }, "session_id": { "description": "Session ID (e.g. '$1')", "type": "string" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name" }, "window_count": { "description": "Number of windows", "type": "integer" } }, "required": [ "session_id", "window_count" ], "type": "object" } ``` --- # create_window Source: https://libtmux.org/en/py/stable/mcp/tools/create_window/ > Create a new window in a tmux session. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **create_window**( [attach](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fattach)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [direction](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fdirection)?: "before" | "after" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [environment](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fenvironment)?: [Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [start_directory](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fstart_directory)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [suppress_persistent_history](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fsuppress_persistent_history)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [window_name](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fwindow_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/session_tools.py#L364)][¶](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window) Create a new window in a tmux session. Creates a window with one pane. Use [split_window](https://libtmux.org/en/py/stable/mcp/tools/split_window/) to add more panes afterward. * MCP request method `tools/call` Send `create_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.parameters) * **[`attach`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fattach)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to make the new window active. * **[`direction`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fdirection)**? = `null` ("before" | "after" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window placement direction. * **[`environment`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fenvironment)**? = `null` ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Per-process environment as a mapping or JSON object string. Values do not modify the tmux session environment. Each item becomes a tmux `-e` launch option. Values may be visible to host process inspection in the tmux client argv during launch and in the child environment afterward; MCP audit redaction does not hide either surface. Pass credential references, not literal credentials. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) to look up. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name to look up. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. Defaults to LIBTMUX_SOCKET env var. * **[`start_directory`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fstart_directory)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Existing directory to start in. `~` expands; a relative path resolves against the MCP server process’s directory. * **[`suppress_persistent_history`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fsuppress_persistent_history)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to suppress persistent history for the spawned shell. Defaults to False for MCP and direct Python calls. This per-call option does not inherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these controls. * **[`window_name`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fwindow_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Name for the new window. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane id (`%N`) of the window’s active pane. * **[`pane_count`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fpane_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of panes * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session name * **[`window_active`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`window_height`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Window ID (e.g. ‘@1’) * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index * **[`window_layout`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow_layout)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Layout string * **[`window_name`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window name * **[`window_width`](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/create_window/#mcp.tool.create_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "attach": { "default": false, "description": "Whether to make the new window active.", "type": "boolean" }, "direction": { "anyOf": [ { "enum": [ "before", "after" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Window placement direction." }, "environment": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "string" }, { "type": "null" } ], "default": null, "description": "Per-process environment as a mapping or JSON object string. Values do\nnot modify the tmux session environment. Each item becomes a tmux\n``-e`` launch option. Values may be visible to host process inspection\nin the tmux client argv during launch and in the child environment\nafterward; MCP audit redaction does not hide either surface. Pass\ncredential references, not literal credentials." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') to look up." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name to look up." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name. Defaults to LIBTMUX_SOCKET env var." }, "start_directory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Existing directory to start in. ``~`` expands; a relative path\nresolves against the MCP server process's directory." }, "suppress_persistent_history": { "default": false, "description": "Whether to suppress persistent history for the spawned shell. Defaults\nto False for MCP and direct Python calls. This per-call option does not\ninherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these\ncontrols.", "type": "boolean" }, "window_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Name for the new window." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux window.", "properties": { "active_pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane id (``%N``) of the window's active pane." }, "pane_count": { "description": "Number of panes", "type": "integer" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session name" }, "window_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "window_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "window_id": { "description": "Window ID (e.g. '@1')", "type": "string" }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index" }, "window_layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Layout string" }, "window_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window name" }, "window_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" } }, "required": [ "window_id", "pane_count" ], "type": "object" } ``` --- # delete_buffer Source: https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/ > Delete an MCP-owned buffer. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **delete_buffer**( [buffer_name](https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/#mcp.tool.delete_buffer.input%2Fproperties%2Fbuffer_name): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/#mcp.tool.delete_buffer.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/buffer_tools.py#L401)][¶](https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/#mcp.tool.delete_buffer) Delete an MCP-owned buffer. * MCP request method `tools/call` Send `delete_buffer` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/#mcp.tool.delete_buffer.parameters) * **[`buffer_name`](https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/#mcp.tool.delete_buffer.input%2Fproperties%2Fbuffer_name)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Must match the full MCP-namespaced form. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/#mcp.tool.delete_buffer.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/#mcp.tool.delete_buffer.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/#mcp.tool.delete_buffer.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/#mcp.tool.delete_buffer.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/#mcp.tool.delete_buffer.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "buffer_name": { "description": "Must match the full MCP-namespaced form.", "type": "string" }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." } }, "required": [ "buffer_name" ], "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # display_message Source: https://libtmux.org/en/py/stable/mcp/tools/display_message/ > Read tmux variables against a target and return the substituted text. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **display_message**( [format_string](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.input%2Fproperties%2Fformat_string): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L179)][¶](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message) Read tmux variables against a target and return the substituted text. Use this when no dedicated tool covers the field you want, e.g. ’#{[window_zoomed_flag](https://libtmux.org/en/tmux/latest/catalog/formats/window_zoomed_flag/)}’, ’#{[pane_dead](https://libtmux.org/en/tmux/latest/catalog/formats/pane_dead/)}’, ’#{[client_activity](https://libtmux.org/en/tmux/latest/catalog/formats/client_activity/)}’. Accepts literal text and ’#{variable}’ references. Format modifiers, conditionals, and jobs are refused: tmux expands ’#{E:x}’ by running x’s *value* through the expander again, and a value can arrive from a pane rather than from the caller. For raw format syntax, run ‘tmux [display-message](https://libtmux.org/en/tmux/latest/manual/display-message/) -p’ through [run_command](https://libtmux.org/en/py/stable/mcp/tools/run_command/), where the caller supplies it on a surface labelled execution. Returned values can carry text a pane chose, such as a working directory or a running command. * MCP request method `tools/call` Send `display_message` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.parameters) * **[`format_string`](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.input%2Fproperties%2Fformat_string)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Literal text and ’#{variable}’ references (e.g. ’#{[cursor_x](https://libtmux.org/en/tmux/latest/catalog/formats/cursor_x/)} #{[cursor_y](https://libtmux.org/en/tmux/latest/catalog/formats/cursor_y/)}’). * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/display_message/#mcp.tool.display_message.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "format_string": { "description": "Literal text and '#{variable}' references (e.g.\n'#{cursor_x} #{cursor_y}').", "type": "string" }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "required": [ "format_string" ], "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # enter_copy_mode Source: https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/ > Enter copy mode in a tmux pane, optionally scrolling up. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **enter_copy_mode**( [pane_id](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [scroll_up](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.input%2Fproperties%2Fscroll_up)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L184)][¶](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode) Enter copy mode in a tmux pane, optionally scrolling up. Use to navigate scrollback history. After entering copy mode, use [snapshot_pane](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/) to read the scroll_position and content. * MCP request method `tools/call` Send `enter_copy_mode` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.parameters) * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`scroll_up`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.input%2Fproperties%2Fscroll_up)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Number of lines to scroll up immediately after entering copy mode. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`is_caller`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fis_caller)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) MCP caller identity for this pane. `True` when the pane matches the caller’s `TMUX_PANE` *and* lives on the same tmux socket as the caller’s `TMUX` (verified via socket realpath); `False` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; `None` when the MCP process is not running inside tmux at all. * **[`pane_active`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`pane_at_bottom`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_at_bottom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s bottom edge. * **[`pane_at_left`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_at_left)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s left edge. * **[`pane_at_right`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_at_right)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s right edge. * **[`pane_at_top`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_at_top)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s top edge. tmux accounts for [`pane-border-status`](https://libtmux.org/en/tmux/latest/catalog/options/pane-border-status/) here, so the top row may be 1 instead of 0 when the status bar is at the top. * **[`pane_bottom`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_bottom)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Bottom edge row (inclusive), window-relative. * **[`pane_current_command`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_current_command)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Running command * **[`pane_current_path`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_current_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current working directory * **[`pane_height`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’) * **[`pane_index`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane index * **[`pane_left`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_left)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Left edge column, 0-based and window-relative. * **[`pane_pid`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_pid)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Process ID * **[`pane_right`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_right)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Right edge column (inclusive), window-relative. * **[`pane_title`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_title)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane title * **[`pane_top`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_top)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Top edge row, 0-based and window-relative. * **[`pane_tty`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_tty)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) TTY device path of the pane (e.g. ‘/dev/pts/5’). * **[`pane_width`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fpane_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.output%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent window ID ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/enter_copy_mode/#mcp.tool.enter_copy_mode.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "scroll_up": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of lines to scroll up immediately after entering copy mode." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux pane.", "properties": { "is_caller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all." }, "pane_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "pane_at_bottom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's bottom edge." }, "pane_at_left": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's left edge." }, "pane_at_right": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's right edge." }, "pane_at_top": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top." }, "pane_bottom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Bottom edge row (inclusive), window-relative." }, "pane_current_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Running command" }, "pane_current_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working directory" }, "pane_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "pane_id": { "description": "Pane ID (e.g. '%1')", "type": "string" }, "pane_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane index" }, "pane_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Left edge column, 0-based and window-relative." }, "pane_pid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Process ID" }, "pane_right": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Right edge column (inclusive), window-relative." }, "pane_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane title" }, "pane_top": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Top edge row, 0-based and window-relative." }, "pane_tty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TTY device path of the pane (e.g. '/dev/pts/5')." }, "pane_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent window ID" } }, "required": [ "pane_id" ], "type": "object" } ``` --- # exit_copy_mode Source: https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/ > Exit copy mode in a tmux pane. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **exit_copy_mode**( [pane_id](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L189)][¶](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode) Exit copy mode in a tmux pane. Returns the pane to normal mode. Use after scrolling through scrollback history. * MCP request method `tools/call` Send `exit_copy_mode` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.parameters) * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`is_caller`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fis_caller)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) MCP caller identity for this pane. `True` when the pane matches the caller’s `TMUX_PANE` *and* lives on the same tmux socket as the caller’s `TMUX` (verified via socket realpath); `False` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; `None` when the MCP process is not running inside tmux at all. * **[`pane_active`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`pane_at_bottom`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_at_bottom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s bottom edge. * **[`pane_at_left`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_at_left)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s left edge. * **[`pane_at_right`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_at_right)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s right edge. * **[`pane_at_top`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_at_top)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s top edge. tmux accounts for [`pane-border-status`](https://libtmux.org/en/tmux/latest/catalog/options/pane-border-status/) here, so the top row may be 1 instead of 0 when the status bar is at the top. * **[`pane_bottom`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_bottom)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Bottom edge row (inclusive), window-relative. * **[`pane_current_command`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_current_command)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Running command * **[`pane_current_path`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_current_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current working directory * **[`pane_height`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’) * **[`pane_index`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane index * **[`pane_left`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_left)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Left edge column, 0-based and window-relative. * **[`pane_pid`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_pid)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Process ID * **[`pane_right`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_right)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Right edge column (inclusive), window-relative. * **[`pane_title`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_title)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane title * **[`pane_top`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_top)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Top edge row, 0-based and window-relative. * **[`pane_tty`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_tty)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) TTY device path of the pane (e.g. ‘/dev/pts/5’). * **[`pane_width`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fpane_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.output%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent window ID ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/exit_copy_mode/#mcp.tool.exit_copy_mode.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux pane.", "properties": { "is_caller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all." }, "pane_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "pane_at_bottom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's bottom edge." }, "pane_at_left": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's left edge." }, "pane_at_right": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's right edge." }, "pane_at_top": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top." }, "pane_bottom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Bottom edge row (inclusive), window-relative." }, "pane_current_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Running command" }, "pane_current_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working directory" }, "pane_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "pane_id": { "description": "Pane ID (e.g. '%1')", "type": "string" }, "pane_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane index" }, "pane_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Left edge column, 0-based and window-relative." }, "pane_pid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Process ID" }, "pane_right": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Right edge column (inclusive), window-relative." }, "pane_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane title" }, "pane_top": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Top edge row, 0-based and window-relative." }, "pane_tty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TTY device path of the pane (e.g. '/dev/pts/5')." }, "pane_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent window ID" } }, "required": [ "pane_id" ], "type": "object" } ``` --- # find_pane_by_position Source: https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/ > Find the pane occupying a corner of a tmux window. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **find_pane_by_position**( [corner](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fcorner): "top-left" | "top-right" | "bottom-left" | "bottom-right", [session_id](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_index](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fwindow_index)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L136)][¶](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position) Find the pane occupying a corner of a tmux window. Composes the four `pane_at_*` predicates so callers can target a layout-relative position (e.g. “the bottom-right pane”) in one round-trip instead of listing every pane and computing the geometry. Resolves the window the same way as the other window-scoped tools. * MCP request method `tools/call` Send `find_pane_by_position` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.parameters) * **[`corner`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fcorner)** ("top-left" | "top-right" | "bottom-left" | "bottom-right") One of `'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'`. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID (e.g. ‘@1’). * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index. Requires session_name or session_id. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`is_caller`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fis_caller)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) MCP caller identity for this pane. `True` when the pane matches the caller’s `TMUX_PANE` *and* lives on the same tmux socket as the caller’s `TMUX` (verified via socket realpath); `False` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; `None` when the MCP process is not running inside tmux at all. * **[`pane_active`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`pane_at_bottom`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_at_bottom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s bottom edge. * **[`pane_at_left`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_at_left)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s left edge. * **[`pane_at_right`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_at_right)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s right edge. * **[`pane_at_top`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_at_top)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s top edge. tmux accounts for [`pane-border-status`](https://libtmux.org/en/tmux/latest/catalog/options/pane-border-status/) here, so the top row may be 1 instead of 0 when the status bar is at the top. * **[`pane_bottom`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_bottom)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Bottom edge row (inclusive), window-relative. * **[`pane_current_command`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_current_command)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Running command * **[`pane_current_path`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_current_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current working directory * **[`pane_height`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’) * **[`pane_index`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane index * **[`pane_left`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_left)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Left edge column, 0-based and window-relative. * **[`pane_pid`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_pid)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Process ID * **[`pane_right`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_right)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Right edge column (inclusive), window-relative. * **[`pane_title`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_title)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane title * **[`pane_top`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_top)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Top edge row, 0-based and window-relative. * **[`pane_tty`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_tty)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) TTY device path of the pane (e.g. ‘/dev/pts/5’). * **[`pane_width`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent window ID ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "corner": { "description": "One of ``'top-left'``, ``'top-right'``, ``'bottom-left'``,\n``'bottom-right'``.", "enum": [ "top-left", "top-right", "bottom-left", "bottom-right" ], "type": "string" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID (e.g. '@1')." }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index. Requires session_name or session_id." } }, "required": [ "corner" ], "type": "object" } ``` Output schema ```json { "description": "Serialized tmux pane.", "properties": { "is_caller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all." }, "pane_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "pane_at_bottom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's bottom edge." }, "pane_at_left": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's left edge." }, "pane_at_right": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's right edge." }, "pane_at_top": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top." }, "pane_bottom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Bottom edge row (inclusive), window-relative." }, "pane_current_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Running command" }, "pane_current_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working directory" }, "pane_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "pane_id": { "description": "Pane ID (e.g. '%1')", "type": "string" }, "pane_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane index" }, "pane_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Left edge column, 0-based and window-relative." }, "pane_pid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Process ID" }, "pane_right": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Right edge column (inclusive), window-relative." }, "pane_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane title" }, "pane_top": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Top edge row, 0-based and window-relative." }, "pane_tty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TTY device path of the pane (e.g. '/dev/pts/5')." }, "pane_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent window ID" } }, "required": [ "pane_id" ], "type": "object" } ``` --- # get_pane_info Source: https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/ > Get detailed information about a tmux pane. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **get_pane_info**( [pane_id](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L131)][¶](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info) Get detailed information about a tmux pane. Use this for metadata (PID, path, dimensions) without reading terminal content. To read what is displayed in the pane, use [capture_pane](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/) instead. * MCP request method `tools/call` Send `get_pane_info` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.parameters) * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`is_caller`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fis_caller)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) MCP caller identity for this pane. `True` when the pane matches the caller’s `TMUX_PANE` *and* lives on the same tmux socket as the caller’s `TMUX` (verified via socket realpath); `False` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; `None` when the MCP process is not running inside tmux at all. * **[`pane_active`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`pane_at_bottom`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_at_bottom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s bottom edge. * **[`pane_at_left`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_at_left)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s left edge. * **[`pane_at_right`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_at_right)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s right edge. * **[`pane_at_top`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_at_top)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s top edge. tmux accounts for [`pane-border-status`](https://libtmux.org/en/tmux/latest/catalog/options/pane-border-status/) here, so the top row may be 1 instead of 0 when the status bar is at the top. * **[`pane_bottom`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_bottom)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Bottom edge row (inclusive), window-relative. * **[`pane_current_command`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_current_command)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Running command * **[`pane_current_path`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_current_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current working directory * **[`pane_height`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’) * **[`pane_index`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane index * **[`pane_left`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_left)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Left edge column, 0-based and window-relative. * **[`pane_pid`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_pid)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Process ID * **[`pane_right`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_right)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Right edge column (inclusive), window-relative. * **[`pane_title`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_title)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane title * **[`pane_top`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_top)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Top edge row, 0-based and window-relative. * **[`pane_tty`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_tty)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) TTY device path of the pane (e.g. ‘/dev/pts/5’). * **[`pane_width`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent window ID ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux pane.", "properties": { "is_caller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all." }, "pane_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "pane_at_bottom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's bottom edge." }, "pane_at_left": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's left edge." }, "pane_at_right": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's right edge." }, "pane_at_top": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top." }, "pane_bottom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Bottom edge row (inclusive), window-relative." }, "pane_current_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Running command" }, "pane_current_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working directory" }, "pane_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "pane_id": { "description": "Pane ID (e.g. '%1')", "type": "string" }, "pane_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane index" }, "pane_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Left edge column, 0-based and window-relative." }, "pane_pid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Process ID" }, "pane_right": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Right edge column (inclusive), window-relative." }, "pane_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane title" }, "pane_top": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Top edge row, 0-based and window-relative." }, "pane_tty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TTY device path of the pane (e.g. '/dev/pts/5')." }, "pane_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent window ID" } }, "required": [ "pane_id" ], "type": "object" } ``` --- # get_server_info Source: https://libtmux.org/en/py/stable/mcp/tools/get_server_info/ > Get information about the tmux server. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **get_server_info**( [socket_name](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/#mcp.tool.get_server_info.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/server_tools.py#L382)][¶](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/#mcp.tool.get_server_info) Get information about the tmux server. Use to verify the tmux server is running before other operations. For session-level details, use [list_sessions](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/) instead. * MCP request method `tools/call` Send `get_server_info` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/#mcp.tool.get_server_info.parameters) * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/#mcp.tool.get_server_info.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. Defaults to LIBTMUX_SOCKET env var. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/#mcp.tool.get_server_info.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`is_alive`](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/#mcp.tool.get_server_info.output%2Fproperties%2Fis_alive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether the server is running * **[`session_count`](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/#mcp.tool.get_server_info.output%2Fproperties%2Fsession_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of sessions * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/#mcp.tool.get_server_info.output%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Socket name * **[`socket_path`](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/#mcp.tool.get_server_info.output%2Fproperties%2Fsocket_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Socket path * **[`version`](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/#mcp.tool.get_server_info.output%2Fproperties%2Fversion)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux version ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/#mcp.tool.get_server_info.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/get_server_info/#mcp.tool.get_server_info.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name. Defaults to LIBTMUX_SOCKET env var." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux server info.", "properties": { "is_alive": { "description": "Whether the server is running", "type": "boolean" }, "session_count": { "description": "Number of sessions", "type": "integer" }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Socket name" }, "socket_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Socket path" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux version" } }, "required": [ "is_alive", "session_count" ], "type": "object" } ``` --- # get_session_info Source: https://libtmux.org/en/py/stable/mcp/tools/get_session_info/ > Return metadata for a single tmux session (ID, name, window count, activity). tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **get_session_info**( [session_id](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/session_tools.py#L359)][¶](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info) Return metadata for a single tmux session (ID, name, window count, activity). Use this instead of [list_sessions](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/) + filter when you only need one session’s info. Resolves by session_id first; falls back to session_name. * MCP request method `tools/call` Send `get_session_info` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.parameters) * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$0’). * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane id (`%N`) of the session’s active pane. Guaranteed non-None on [`create_session`](https://libtmux.org/en/py/stable/mcp/tools/create_session/) return (libtmux creates the session with one initial pane). May be None from [`list_sessions`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/) rows for sessions in transient teardown states where `active_pane` is unavailable. * **[`session_attached`](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fsession_attached)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Attached client count * **[`session_created`](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fsession_created)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Creation timestamp * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fsession_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session ID (e.g. ‘$1’) * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name * **[`window_count`](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fwindow_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of windows ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/get_session_info/#mcp.tool.get_session_info.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$0')." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux session.", "properties": { "active_pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane id (``%N``) of the session's active pane. Guaranteed non-None on ``create_session`` return (libtmux creates the session with one initial pane). May be None from ``list_sessions`` rows for sessions in transient teardown states where ``active_pane`` is unavailable." }, "session_attached": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Attached client count" }, "session_created": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Creation timestamp" }, "session_id": { "description": "Session ID (e.g. '$1')", "type": "string" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name" }, "window_count": { "description": "Number of windows", "type": "integer" } }, "required": [ "session_id", "window_count" ], "type": "object" } ``` --- # get_window_info Source: https://libtmux.org/en/py/stable/mcp/tools/get_window_info/ > Return metadata for a single tmux window (ID, name, layout, dimensions). tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **get_window_info**( [session_id](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_index](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.input%2Fproperties%2Fwindow_index)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/window_tools.py#L507)][¶](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info) Return metadata for a single tmux window (ID, name, layout, dimensions). Use this instead of [list_windows](https://libtmux.org/en/py/stable/mcp/tools/list_windows/) + filter when you only need one window’s info. Resolves the window by window_id first; falls back to window_index within a session if window_id is not given. * MCP request method `tools/call` Send `get_window_info` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.parameters) * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID for window_index lookup. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for window_index lookup. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID (e.g. ‘@1’). * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.input%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index within the session. Requires session_name or session_id to disambiguate. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane id (`%N`) of the window’s active pane. * **[`pane_count`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fpane_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of panes * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session name * **[`window_active`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`window_height`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Window ID (e.g. ‘@1’) * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index * **[`window_layout`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow_layout)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Layout string * **[`window_name`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window name * **[`window_width`](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/get_window_info/#mcp.tool.get_window_info.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID for window_index lookup." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for window_index lookup." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID (e.g. '@1')." }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index within the session. Requires session_name or\nsession_id to disambiguate." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux window.", "properties": { "active_pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane id (``%N``) of the window's active pane." }, "pane_count": { "description": "Number of panes", "type": "integer" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session name" }, "window_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "window_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "window_id": { "description": "Window ID (e.g. '@1')", "type": "string" }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index" }, "window_layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Layout string" }, "window_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window name" }, "window_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" } }, "required": [ "window_id", "pane_count" ], "type": "object" } ``` --- # kill_pane Source: https://libtmux.org/en/py/stable/mcp/tools/kill_pane/ > Kill (close) a tmux pane. Requires exact pane_id (e.g. '%5'). tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **kill_pane**( [pane_id](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/#mcp.tool.kill_pane.input%2Fproperties%2Fpane_id): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/#mcp.tool.kill_pane.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L116)][¶](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/#mcp.tool.kill_pane) Kill (close) a tmux pane. Requires exact pane_id (e.g. ‘%5’). Use to clean up panes no longer needed. To remove an entire window and all its panes, use [kill_window](https://libtmux.org/en/py/stable/mcp/tools/kill_window/) instead. * MCP request method `tools/call` Send `kill_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/#mcp.tool.kill_pane.parameters) * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/#mcp.tool.kill_pane.input%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’). Required — no fallback resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/#mcp.tool.kill_pane.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/#mcp.tool.kill_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/#mcp.tool.kill_pane.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/#mcp.tool.kill_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/#mcp.tool.kill_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "pane_id": { "description": "Pane ID (e.g. '%1'). Required — no fallback resolution.", "type": "string" }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." } }, "required": [ "pane_id" ], "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # kill_server Source: https://libtmux.org/en/py/stable/mcp/tools/kill_server/ > Kill the tmux server and all its sessions. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **kill_server**( [socket_name](https://libtmux.org/en/py/stable/mcp/tools/kill_server/#mcp.tool.kill_server.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/server_tools.py#L377)][¶](https://libtmux.org/en/py/stable/mcp/tools/kill_server/#mcp.tool.kill_server) Kill the tmux server and all its sessions. Destroys ALL sessions, windows, and panes on this server. Use [kill_session](https://libtmux.org/en/py/stable/mcp/tools/kill_session/) to remove a single session instead. Self-kill protection prevents killing the server running this MCP process. * MCP request method `tools/call` Send `kill_server` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/kill_server/#mcp.tool.kill_server.parameters) * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/kill_server/#mcp.tool.kill_server.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. Defaults to LIBTMUX_SOCKET env var. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/kill_server/#mcp.tool.kill_server.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/kill_server/#mcp.tool.kill_server.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/kill_server/#mcp.tool.kill_server.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/kill_server/#mcp.tool.kill_server.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name. Defaults to LIBTMUX_SOCKET env var." } }, "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # kill_session Source: https://libtmux.org/en/py/stable/mcp/tools/kill_session/ > Kill a tmux session. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **kill_session**( [session_id](https://libtmux.org/en/py/stable/mcp/tools/kill_session/#mcp.tool.kill_session.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/kill_session/#mcp.tool.kill_session.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/kill_session/#mcp.tool.kill_session.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/session_tools.py#L374)][¶](https://libtmux.org/en/py/stable/mcp/tools/kill_session/#mcp.tool.kill_session) Kill a tmux session. Destroys the session and all its windows and panes. Use [kill_window](https://libtmux.org/en/py/stable/mcp/tools/kill_window/) to remove a single window instead. Self-kill protection prevents killing the session containing this MCP process. * MCP request method `tools/call` Send `kill_session` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/kill_session/#mcp.tool.kill_session.parameters) * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/kill_session/#mcp.tool.kill_session.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) to look up. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/kill_session/#mcp.tool.kill_session.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name to look up. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/kill_session/#mcp.tool.kill_session.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. Defaults to LIBTMUX_SOCKET env var. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/kill_session/#mcp.tool.kill_session.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/kill_session/#mcp.tool.kill_session.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/kill_session/#mcp.tool.kill_session.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/kill_session/#mcp.tool.kill_session.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') to look up." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name to look up." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name. Defaults to LIBTMUX_SOCKET env var." } }, "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # kill_window Source: https://libtmux.org/en/py/stable/mcp/tools/kill_window/ > Kill (close) a tmux window. Requires exact window_id (e.g. '@3'). tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **kill_window**( [socket_name](https://libtmux.org/en/py/stable/mcp/tools/kill_window/#mcp.tool.kill_window.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/kill_window/#mcp.tool.kill_window.input%2Fproperties%2Fwindow_id): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/window_tools.py#L522)][¶](https://libtmux.org/en/py/stable/mcp/tools/kill_window/#mcp.tool.kill_window) Kill (close) a tmux window. Requires exact window_id (e.g. ‘@3’). Destroys the window and all its panes. Use [kill_pane](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/) to remove a single pane instead. Self-kill protection prevents killing the window containing this MCP process. * MCP request method `tools/call` Send `kill_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/kill_window/#mcp.tool.kill_window.parameters) * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/kill_window/#mcp.tool.kill_window.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/kill_window/#mcp.tool.kill_window.input%2Fproperties%2Fwindow_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Window ID (e.g. ‘@1’). Required — no fallback resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/kill_window/#mcp.tool.kill_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/kill_window/#mcp.tool.kill_window.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/kill_window/#mcp.tool.kill_window.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/kill_window/#mcp.tool.kill_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "description": "Window ID (e.g. '@1'). Required — no fallback resolution.", "type": "string" } }, "required": [ "window_id" ], "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # list_panes Source: https://libtmux.org/en/py/stable/mcp/tools/list_panes/ > List tmux panes (terminal multiplexer splits) in a window, session, or server. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **list_panes**( [filters](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Ffilters)?: [Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_index](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fwindow_index)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/window_tools.py#L501)][¶](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes) List tmux panes (terminal multiplexer splits) in a window, session, or server. Use for terminal panes — including ‘this pane’, ‘current pane’, ‘split pane’, ‘the bottom shell’ — not editor splits or browser panes. Only searches pane metadata (current command, title, working directory); to search the actual visible terminal text, use [search_panes](https://libtmux.org/en/py/stable/mcp/tools/search_panes/). * MCP request method `tools/call` Send `list_panes` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.parameters) * **[`filters`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Ffilters)**? = `null` ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Django-style filters as a dict (e.g. `{"pane_current_command__contains": "vim"}`) or as a JSON string. Some MCP clients require the string form. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID. If given without window params, lists all panes in the session. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name. If given without window params, lists all panes in the session. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID (e.g. ‘@1’). Scopes to a single window. * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index within the session. Scopes to a single window. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult)** ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>) * **[Items](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Serialized tmux pane. * **[`is_caller`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fis_caller)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) MCP caller identity for this pane. `True` when the pane matches the caller’s `TMUX_PANE` *and* lives on the same tmux socket as the caller’s `TMUX` (verified via socket realpath); `False` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; `None` when the MCP process is not running inside tmux at all. * **[`pane_active`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`pane_at_bottom`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_at_bottom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s bottom edge. * **[`pane_at_left`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_at_left)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s left edge. * **[`pane_at_right`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_at_right)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s right edge. * **[`pane_at_top`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_at_top)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s top edge. tmux accounts for [`pane-border-status`](https://libtmux.org/en/tmux/latest/catalog/options/pane-border-status/) here, so the top row may be 1 instead of 0 when the status bar is at the top. * **[`pane_bottom`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_bottom)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Bottom edge row (inclusive), window-relative. * **[`pane_current_command`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_current_command)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Running command * **[`pane_current_path`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_current_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current working directory * **[`pane_height`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’) * **[`pane_index`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane index * **[`pane_left`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_left)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Left edge column, 0-based and window-relative. * **[`pane_pid`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_pid)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Process ID * **[`pane_right`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_right)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Right edge column (inclusive), window-relative. * **[`pane_title`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_title)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane title * **[`pane_top`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_top)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Top edge row, 0-based and window-relative. * **[`pane_tty`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_tty)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) TTY device path of the pane (e.g. ‘/dev/pts/5’). * **[`pane_width`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent window ID ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/list_panes/#mcp.tool.list_panes.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "filters": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "string" }, { "type": "null" } ], "default": null, "description": "Django-style filters as a dict\n(e.g. ``{\"pane_current_command__contains\": \"vim\"}``)\nor as a JSON string. Some MCP clients require the string form." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID. If given without window params, lists all panes\nin the session." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name. If given without window params, lists all panes\nin the session." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID (e.g. '@1'). Scopes to a single window." }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index within the session. Scopes to a single window." } }, "type": "object" } ``` Output schema ```json { "properties": { "result": { "items": { "description": "Serialized tmux pane.", "properties": { "is_caller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all." }, "pane_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "pane_at_bottom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's bottom edge." }, "pane_at_left": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's left edge." }, "pane_at_right": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's right edge." }, "pane_at_top": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top." }, "pane_bottom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Bottom edge row (inclusive), window-relative." }, "pane_current_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Running command" }, "pane_current_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working directory" }, "pane_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "pane_id": { "description": "Pane ID (e.g. '%1')", "type": "string" }, "pane_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane index" }, "pane_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Left edge column, 0-based and window-relative." }, "pane_pid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Process ID" }, "pane_right": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Right edge column (inclusive), window-relative." }, "pane_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane title" }, "pane_top": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Top edge row, 0-based and window-relative." }, "pane_tty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TTY device path of the pane (e.g. '/dev/pts/5')." }, "pane_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent window ID" } }, "required": [ "pane_id" ], "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # list_servers Source: https://libtmux.org/en/py/stable/mcp/tools/list_servers/ > Discover live tmux servers under the current user's $TMUX_TMPDIR. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **list_servers**( [extra_socket_paths](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.input%2Fproperties%2Fextra_socket_paths)?: [Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")> | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/server_tools.py#L367)][¶](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers) Discover live tmux servers under the current user’s `$TMUX_TMPDIR`. Scans `${TMUX_TMPDIR:-/tmp}/tmux-/` for socket files — the canonical location where tmux creates per-server sockets (see tmux.c’s `expand_paths` + `TMUX_SOCK` template). Only sockets with a live listener are reported; stale inodes (a common case on long-running systems where `$TMUX_TMPDIR` can carry thousands of orphans) are silently filtered. **Scope caveat**: custom `tmux -S /some/path/...` servers that live OUTSIDE `$TMUX_TMPDIR` are not returned by the scan alone — there is no canonical registry for arbitrary socket paths. Supply known paths via `extra_socket_paths` to include them in the result, or pass the path to other tools via their `socket_name` / [`socket_path`](https://libtmux.org/en/tmux/latest/catalog/formats/socket_path/) parameters once known. * MCP request method `tools/call` Send `list_servers` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.parameters) * **[`extra_socket_paths`](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.input%2Fproperties%2Fextra_socket_paths)**? = `null` ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")> | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Additional filesystem paths to probe alongside the `$TMUX_TMPDIR` scan. Each path is checked for liveness (UNIX `connect()`) and queried for server metadata. Paths that do not exist, are not sockets, or have no listener are silently skipped. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.output%2Fproperties%2Fresult)** ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>) * **[Items](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.output%2Fproperties%2Fresult%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Serialized tmux server info. * **[`is_alive`](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fis_alive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether the server is running * **[`session_count`](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fsession_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of sessions * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Socket name * **[`socket_path`](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fsocket_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Socket path * **[`version`](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fversion)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux version ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/list_servers/#mcp.tool.list_servers.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "extra_socket_paths": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Additional filesystem paths to probe alongside the\n``$TMUX_TMPDIR`` scan. Each path is checked for liveness (UNIX\n``connect()``) and queried for server metadata. Paths that do\nnot exist, are not sockets, or have no listener are silently\nskipped." } }, "type": "object" } ``` Output schema ```json { "properties": { "result": { "items": { "description": "Serialized tmux server info.", "properties": { "is_alive": { "description": "Whether the server is running", "type": "boolean" }, "session_count": { "description": "Number of sessions", "type": "integer" }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Socket name" }, "socket_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Socket path" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux version" } }, "required": [ "is_alive", "session_count" ], "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # list_sessions Source: https://libtmux.org/en/py/stable/mcp/tools/list_sessions/ > List tmux sessions (terminal workspaces) on a tmux server. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **list_sessions**( [filters](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.input%2Fproperties%2Ffilters)?: [Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/server_tools.py#L362)][¶](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions) List tmux sessions (terminal workspaces) on a tmux server. Use for tmux multiplexer sessions — ‘this session’, ‘my workspace’, ‘the dev session’ — not login sessions or HTTP sessions. The starting point for discovery — call this before targeting specific sessions, windows, or panes. * MCP request method `tools/call` Send `list_sessions` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.parameters) * **[`filters`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.input%2Fproperties%2Ffilters)**? = `null` ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Django-style filters as a dict (e.g. `{"session_name__contains": "dev"}`) or as a JSON string. Some MCP clients require the string form. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. Defaults to LIBTMUX_SOCKET env var. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fresult)** ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>) * **[Items](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fresult%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Serialized tmux session. * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane id (`%N`) of the session’s active pane. Guaranteed non-None on [`create_session`](https://libtmux.org/en/py/stable/mcp/tools/create_session/) return (libtmux creates the session with one initial pane). May be None from `list_sessions` rows for sessions in transient teardown states where `active_pane` is unavailable. * **[`session_attached`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fsession_attached)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Attached client count * **[`session_created`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fsession_created)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Creation timestamp * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fsession_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session ID (e.g. ‘$1’) * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name * **[`window_count`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fwindow_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of windows ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/#mcp.tool.list_sessions.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "filters": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "string" }, { "type": "null" } ], "default": null, "description": "Django-style filters as a dict (e.g. ``{\"session_name__contains\": \"dev\"}``)\nor as a JSON string. Some MCP clients require the string form." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name. Defaults to LIBTMUX_SOCKET env var." } }, "type": "object" } ``` Output schema ```json { "properties": { "result": { "items": { "description": "Serialized tmux session.", "properties": { "active_pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane id (``%N``) of the session's active pane. Guaranteed non-None on ``create_session`` return (libtmux creates the session with one initial pane). May be None from ``list_sessions`` rows for sessions in transient teardown states where ``active_pane`` is unavailable." }, "session_attached": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Attached client count" }, "session_created": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Creation timestamp" }, "session_id": { "description": "Session ID (e.g. '$1')", "type": "string" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name" }, "window_count": { "description": "Number of windows", "type": "integer" } }, "required": [ "session_id", "window_count" ], "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # list_windows Source: https://libtmux.org/en/py/stable/mcp/tools/list_windows/ > List tmux windows (terminal tabs) in a session, or across the server. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **list_windows**( [filters](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.input%2Fproperties%2Ffilters)?: [Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/session_tools.py#L353)][¶](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows) List tmux windows (terminal tabs) in a session, or across the server. Use for tmux windows — ‘current window’, ‘this tab’ (when terminal- contextual) — not browser tabs or desktop windows. Only searches window metadata (name, index, layout); to search the actual visible terminal text, use [search_panes](https://libtmux.org/en/py/stable/mcp/tools/search_panes/). * MCP request method `tools/call` Send `list_windows` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.parameters) * **[`filters`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.input%2Fproperties%2Ffilters)**? = `null` ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Django-style filters as a dict (e.g. `{"window_name__contains": "dev"}`) or as a JSON string. Some MCP clients require the string form. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) to look up. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name to look up. If omitted along with session_id, returns windows from all sessions. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. Defaults to LIBTMUX_SOCKET env var. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult)** ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>) * **[Items](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Serialized tmux window. * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane id (`%N`) of the window’s active pane. * **[`pane_count`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fpane_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of panes * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session name * **[`window_active`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fwindow_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`window_height`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fwindow_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fwindow_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Window ID (e.g. ‘@1’) * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index * **[`window_layout`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fwindow_layout)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Layout string * **[`window_name`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fwindow_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window name * **[`window_width`](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fresult%2Fitems%2Fproperties%2Fwindow_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/list_windows/#mcp.tool.list_windows.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "filters": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "string" }, { "type": "null" } ], "default": null, "description": "Django-style filters as a dict (e.g. ``{\"window_name__contains\": \"dev\"}``)\nor as a JSON string. Some MCP clients require the string form." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') to look up." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name to look up. If omitted along with session_id,\nreturns windows from all sessions." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name. Defaults to LIBTMUX_SOCKET env var." } }, "type": "object" } ``` Output schema ```json { "properties": { "result": { "items": { "description": "Serialized tmux window.", "properties": { "active_pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane id (``%N``) of the window's active pane." }, "pane_count": { "description": "Number of panes", "type": "integer" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session name" }, "window_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "window_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "window_id": { "description": "Window ID (e.g. '@1')", "type": "string" }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index" }, "window_layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Layout string" }, "window_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window name" }, "window_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" } }, "required": [ "window_id", "pane_count" ], "type": "object" }, "type": "array" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # load_buffer Source: https://libtmux.org/en/py/stable/mcp/tools/load_buffer/ > Load text into a new agent-namespaced tmux paste buffer. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **load_buffer**( [content](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer.input%2Fproperties%2Fcontent): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [logical_name](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer.input%2Fproperties%2Flogical_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/buffer_tools.py#L386)][¶](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer) Load text into a new agent-namespaced tmux paste buffer. Each call allocates a fresh buffer name — two concurrent calls will land in distinct buffers even if they pass the same `logical_name`. Agents MUST use the returned [`buffer_name`](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-bufferref-buffer_name/) on subsequent paste/show/delete calls. **When to use this vs. [paste_text](https://libtmux.org/en/py/stable/mcp/tools/paste_text/):** `load_buffer` is the stage-then-fire path — you get a handle back and can inspect via [`show_buffer`](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/), paste into multiple panes via [`paste_buffer`](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/), or hold the content for later. Use [`paste_text`](https://libtmux.org/en/py/stable/mcp/tools/paste_text/) for a simple one-shot paste with no follow-up. * MCP request method `tools/call` Send `load_buffer` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer.parameters) * **[`content`](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer.input%2Fproperties%2Fcontent)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The text to stage. Can be multi-line. Redacted in audit logs. * **[`logical_name`](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer.input%2Fproperties%2Flogical_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Short label for the buffer. Limited to `[A-Za-z0-9_.-]{1,64}` so the final name stays safe on the tmux command line. Empty or `None` uses `"buf"`. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`buffer_name`](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer.output%2Fproperties%2Fbuffer_name)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The actual tmux buffer name (with prefix and UUID nonce). Pass this back to [paste_buffer](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/)/[show_buffer](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/)/[delete_buffer](https://libtmux.org/en/py/stable/mcp/tools/delete_buffer/). * **[`logical_name`](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer.output%2Fproperties%2Flogical_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Optional logical name supplied by the caller, if any. ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/#mcp.tool.load_buffer.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "content": { "description": "The text to stage. Can be multi-line. Redacted in audit logs.", "type": "string" }, "logical_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Short label for the buffer. Limited to\n``[A-Za-z0-9_.-]{1,64}`` so the final name stays safe on the\ntmux command line. Empty or ``None`` uses ``\"buf\"``." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." } }, "required": [ "content" ], "type": "object" } ``` Output schema ```json { "description": "Handle returned by :func:`~libtmux_mcp.tools.buffer_tools.load_buffer`.\n\nAgent-created tmux paste buffers are namespaced with a per-call UUID\nto avoid collisions on the server-global buffer namespace when\nconcurrent agents (or parallel tool calls from a single agent) are\nstaging content. Callers must use the ``buffer_name`` this model\ncarries on subsequent\n:func:`~libtmux_mcp.tools.buffer_tools.paste_buffer`,\n:func:`~libtmux_mcp.tools.buffer_tools.show_buffer`, and\n:func:`~libtmux_mcp.tools.buffer_tools.delete_buffer` calls.", "properties": { "buffer_name": { "description": "The actual tmux buffer name (with prefix and UUID nonce). Pass this back to paste_buffer/show_buffer/delete_buffer.", "type": "string" }, "logical_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional logical name supplied by the caller, if any." } }, "required": [ "buffer_name" ], "type": "object" } ``` --- # move_window Source: https://libtmux.org/en/py/stable/mcp/tools/move_window/ > Move a window to a different index or session. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **move_window**( [destination_index](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fdestination_index)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [destination_session](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fdestination_session)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_index](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fwindow_index)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/window_tools.py#L537)][¶](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window) Move a window to a different index or session. Reorder windows within a session or move a window to another session. * MCP request method `tools/call` Send `move_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.parameters) * **[`destination_index`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fdestination_index)**? = `""` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Target window index. Default empty string (next available). * **[`destination_session`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fdestination_session)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Target session name or ID. Default is current session. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Source session ID. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Source session name. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID (e.g. ‘@1’). * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index within the session. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane id (`%N`) of the window’s active pane. * **[`pane_count`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fpane_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of panes * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session name * **[`window_active`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`window_height`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Window ID (e.g. ‘@1’) * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index * **[`window_layout`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow_layout)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Layout string * **[`window_name`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window name * **[`window_width`](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/move_window/#mcp.tool.move_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "destination_index": { "default": "", "description": "Target window index. Default empty string (next available).", "type": "string" }, "destination_session": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Target session name or ID. Default is current session." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Source session ID." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Source session name." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID (e.g. '@1')." }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index within the session." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux window.", "properties": { "active_pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane id (``%N``) of the window's active pane." }, "pane_count": { "description": "Number of panes", "type": "integer" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session name" }, "window_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "window_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "window_id": { "description": "Window ID (e.g. '@1')", "type": "string" }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index" }, "window_layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Layout string" }, "window_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window name" }, "window_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" } }, "required": [ "window_id", "pane_count" ], "type": "object" } ``` --- # paste_buffer Source: https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/ > Paste an MCP-owned buffer into a pane. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **paste_buffer**( [bracket](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fbracket)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [buffer_name](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fbuffer_name): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/buffer_tools.py#L391)][¶](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer) Paste an MCP-owned buffer into a pane. * MCP request method `tools/call` Send `paste_buffer` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.parameters) * **[`bracket`](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fbracket)**? = `true` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Use tmux bracketed paste mode. Default True. * **[`buffer_name`](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fbuffer_name)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Must match the full MCP-namespaced form returned by [`load_buffer`](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/). Non-MCP buffers are rejected so the tool cannot be turned into an arbitrary-buffer reader. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Target pane ID. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane resolution fallbacks. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane resolution fallbacks. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane resolution fallbacks. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/#mcp.tool.paste_buffer.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "bracket": { "default": true, "description": "Use tmux bracketed paste mode. Default True.", "type": "boolean" }, "buffer_name": { "description": "Must match the full MCP-namespaced form returned by\n:func:`~libtmux_mcp.tools.buffer_tools.load_buffer`.\nNon-MCP buffers are rejected so the tool cannot be turned into\nan arbitrary-buffer reader.", "type": "string" }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Target pane ID." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane resolution fallbacks." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane resolution fallbacks." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane resolution fallbacks." } }, "required": [ "buffer_name" ], "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # paste_text Source: https://libtmux.org/en/py/stable/mcp/tools/paste_text/ > Paste multi-line text into a pane using tmux paste buffers. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **paste_text**( [bracket](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fbracket)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [text](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Ftext): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L194)][¶](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text) Paste multi-line text into a pane using tmux paste buffers. Uses tmux’s [load-buffer](https://libtmux.org/en/tmux/latest/manual/load-buffer/) and [paste-buffer](https://libtmux.org/en/tmux/latest/manual/paste-buffer/) for clean multi-line input, avoiding the issues of sending text line-by-line via [send_keys](https://libtmux.org/en/py/stable/mcp/tools/send_keys/). Supports bracketed paste mode for terminals that handle it. **When to use this vs. [load_buffer](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/) + [paste_buffer](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/):** `paste_text` is the fire-and-forget path — the buffer is created, pasted, and deleted in one call. Use [`load_buffer`](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/) + [`paste_buffer`](https://libtmux.org/en/py/stable/mcp/tools/paste_buffer/) when you need to stage content first, paste it into multiple panes, or inspect it with [`show_buffer`](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/) before pasting. * MCP request method `tools/call` Send `paste_text` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.parameters) * **[`bracket`](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fbracket)**? = `true` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to use bracketed paste mode. Default True. Bracketed paste wraps the text in escape sequences that tell the terminal “this is pasted text, not typed input”. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`text`](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Ftext)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The text to paste. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/paste_text/#mcp.tool.paste_text.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "bracket": { "default": true, "description": "Whether to use bracketed paste mode. Default True.\nBracketed paste wraps the text in escape sequences that tell\nthe terminal \"this is pasted text, not typed input\".", "type": "boolean" }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "text": { "description": "The text to paste.", "type": "string" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "required": [ "text" ], "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # pipe_pane Source: https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/ > Log a pane's live output to a file (or stop an active log). tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **pipe_pane**( [append](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Fappend)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [output_path](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Foutput_path)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L174)][¶](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane) Log a pane’s live output to a file (or stop an active log). Streams everything written to the pane (stdout plus terminal control sequences) into a file on disk — the common use is `output_path="/tmp/pane.log"` to capture scrollback continuously while the agent watches for errors. When `output_path` is given, starts logging; when `output_path` is None, stops any active pipe for the pane. Warning This tool writes to arbitrary filesystem paths chosen by the MCP client. There is no allow-list; the server will create files anywhere the server process has write access. Treat this as elevated-risk: it is the broadest-reach tool in `execute`. If you run libtmux-mcp on untrusted input, consider `LIBTMUX_TOOLSETS=inspect` or run the server under a user with a scoped home directory. See [topics/trust](https://libtmux-mcp.git-pull.com/topics/trust/) for the full footgun list. * MCP request method `tools/call` Send `pipe_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.parameters) * **[`append`](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Fappend)**? = `true` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to append to the file. Default True. If False, overwrites. * **[`output_path`](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Foutput_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) File path to write output to. None stops piping. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/pipe_pane/#mcp.tool.pipe_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "append": { "default": true, "description": "Whether to append to the file. Default True. If False, overwrites.", "type": "boolean" }, "output_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "File path to write output to. None stops piping." }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # rename_session Source: https://libtmux.org/en/py/stable/mcp/tools/rename_session/ > Rename a tmux session. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **rename_session**( [new_name](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.input%2Fproperties%2Fnew_name): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/session_tools.py#L369)][¶](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session) Rename a tmux session. Use when a session’s purpose has changed. Existing pane_id references remain valid after renaming. * MCP request method `tools/call` Send `rename_session` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.parameters) * **[`new_name`](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.input%2Fproperties%2Fnew_name)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) New name for the session. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) to look up. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current session name to look up. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. Defaults to LIBTMUX_SOCKET env var. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane id (`%N`) of the session’s active pane. Guaranteed non-None on [`create_session`](https://libtmux.org/en/py/stable/mcp/tools/create_session/) return (libtmux creates the session with one initial pane). May be None from [`list_sessions`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/) rows for sessions in transient teardown states where `active_pane` is unavailable. * **[`session_attached`](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fsession_attached)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Attached client count * **[`session_created`](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fsession_created)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Creation timestamp * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fsession_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session ID (e.g. ‘$1’) * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name * **[`window_count`](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fwindow_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of windows ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/rename_session/#mcp.tool.rename_session.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "new_name": { "description": "New name for the session.", "type": "string" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') to look up." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current session name to look up." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name. Defaults to LIBTMUX_SOCKET env var." } }, "required": [ "new_name" ], "type": "object" } ``` Output schema ```json { "description": "Serialized tmux session.", "properties": { "active_pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane id (``%N``) of the session's active pane. Guaranteed non-None on ``create_session`` return (libtmux creates the session with one initial pane). May be None from ``list_sessions`` rows for sessions in transient teardown states where ``active_pane`` is unavailable." }, "session_attached": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Attached client count" }, "session_created": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Creation timestamp" }, "session_id": { "description": "Session ID (e.g. '$1')", "type": "string" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name" }, "window_count": { "description": "Number of windows", "type": "integer" } }, "required": [ "session_id", "window_count" ], "type": "object" } ``` --- # rename_window Source: https://libtmux.org/en/py/stable/mcp/tools/rename_window/ > Rename a tmux window. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **rename_window**( [new_name](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fnew_name): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_index](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fwindow_index)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/window_tools.py#L517)][¶](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window) Rename a tmux window. Use when a window’s purpose has changed. Existing window_id references remain valid after renaming. * MCP request method `tools/call` Send `rename_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.parameters) * **[`new_name`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fnew_name)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The new name for the window. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID (e.g. ‘@1’). * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index within the session. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane id (`%N`) of the window’s active pane. * **[`pane_count`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fpane_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of panes * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session name * **[`window_active`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`window_height`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Window ID (e.g. ‘@1’) * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index * **[`window_layout`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow_layout)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Layout string * **[`window_name`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window name * **[`window_width`](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/rename_window/#mcp.tool.rename_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "new_name": { "description": "The new name for the window.", "type": "string" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID (e.g. '@1')." }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index within the session." } }, "required": [ "new_name" ], "type": "object" } ``` Output schema ```json { "description": "Serialized tmux window.", "properties": { "active_pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane id (``%N``) of the window's active pane." }, "pane_count": { "description": "Number of panes", "type": "integer" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session name" }, "window_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "window_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "window_id": { "description": "Window ID (e.g. '@1')", "type": "string" }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index" }, "window_layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Layout string" }, "window_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window name" }, "window_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" } }, "required": [ "window_id", "pane_count" ], "type": "object" } ``` --- # resize_pane Source: https://libtmux.org/en/py/stable/mcp/tools/resize_pane/ > Resize a tmux pane. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **resize_pane**( [height](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fheight)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [width](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fwidth)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [zoom](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fzoom)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L111)][¶](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane) Resize a tmux pane. Use when adjusting layout for better readability or to fit content. * MCP request method `tools/call` Send `resize_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.parameters) * **[`height`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fheight)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) New height in lines. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`width`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fwidth)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) New width in columns. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. * **[`zoom`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fzoom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Toggle pane zoom. If True, zoom the pane. If False, unzoom. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`is_caller`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fis_caller)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) MCP caller identity for this pane. `True` when the pane matches the caller’s `TMUX_PANE` *and* lives on the same tmux socket as the caller’s `TMUX` (verified via socket realpath); `False` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; `None` when the MCP process is not running inside tmux at all. * **[`pane_active`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`pane_at_bottom`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_at_bottom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s bottom edge. * **[`pane_at_left`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_at_left)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s left edge. * **[`pane_at_right`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_at_right)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s right edge. * **[`pane_at_top`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_at_top)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s top edge. tmux accounts for [`pane-border-status`](https://libtmux.org/en/tmux/latest/catalog/options/pane-border-status/) here, so the top row may be 1 instead of 0 when the status bar is at the top. * **[`pane_bottom`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_bottom)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Bottom edge row (inclusive), window-relative. * **[`pane_current_command`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_current_command)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Running command * **[`pane_current_path`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_current_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current working directory * **[`pane_height`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’) * **[`pane_index`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane index * **[`pane_left`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_left)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Left edge column, 0-based and window-relative. * **[`pane_pid`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_pid)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Process ID * **[`pane_right`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_right)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Right edge column (inclusive), window-relative. * **[`pane_title`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_title)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane title * **[`pane_top`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_top)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Top edge row, 0-based and window-relative. * **[`pane_tty`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_tty)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) TTY device path of the pane (e.g. ‘/dev/pts/5’). * **[`pane_width`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent window ID ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/resize_pane/#mcp.tool.resize_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "New height in lines." }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "New width in columns." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." }, "zoom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Toggle pane zoom. If True, zoom the pane. If False, unzoom." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux pane.", "properties": { "is_caller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all." }, "pane_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "pane_at_bottom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's bottom edge." }, "pane_at_left": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's left edge." }, "pane_at_right": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's right edge." }, "pane_at_top": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top." }, "pane_bottom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Bottom edge row (inclusive), window-relative." }, "pane_current_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Running command" }, "pane_current_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working directory" }, "pane_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "pane_id": { "description": "Pane ID (e.g. '%1')", "type": "string" }, "pane_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane index" }, "pane_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Left edge column, 0-based and window-relative." }, "pane_pid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Process ID" }, "pane_right": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Right edge column (inclusive), window-relative." }, "pane_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane title" }, "pane_top": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Top edge row, 0-based and window-relative." }, "pane_tty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TTY device path of the pane (e.g. '/dev/pts/5')." }, "pane_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent window ID" } }, "required": [ "pane_id" ], "type": "object" } ``` --- # resize_window Source: https://libtmux.org/en/py/stable/mcp/tools/resize_window/ > Resize a tmux window. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **resize_window**( [height](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fheight)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [width](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fwidth)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_index](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fwindow_index)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/window_tools.py#L532)][¶](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window) Resize a tmux window. Use to adjust the window dimensions. This affects all panes within the window. * MCP request method `tools/call` Send `resize_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.parameters) * **[`height`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fheight)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) New height in lines. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`width`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fwidth)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) New width in columns. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID (e.g. ‘@1’). * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index within the session. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane id (`%N`) of the window’s active pane. * **[`pane_count`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fpane_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of panes * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session name * **[`window_active`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`window_height`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Window ID (e.g. ‘@1’) * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index * **[`window_layout`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow_layout)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Layout string * **[`window_name`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window name * **[`window_width`](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/resize_window/#mcp.tool.resize_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "New height in lines." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "New width in columns." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID (e.g. '@1')." }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index within the session." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux window.", "properties": { "active_pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane id (``%N``) of the window's active pane." }, "pane_count": { "description": "Number of panes", "type": "integer" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session name" }, "window_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "window_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "window_id": { "description": "Window ID (e.g. '@1')", "type": "string" }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index" }, "window_layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Layout string" }, "window_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window name" }, "window_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" } }, "required": [ "window_id", "pane_count" ], "type": "object" } ``` --- # respawn_pane Source: https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/ > Restart a pane's process in place, preserving pane_id and layout. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **respawn_pane**( [environment](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fenvironment)?: [Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [kill](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fkill)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fpane_id): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [shell](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fshell)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [start_directory](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fstart_directory)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [suppress_persistent_history](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fsuppress_persistent_history)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L121)][¶](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane) Restart a pane’s process in place, preserving pane_id and layout. Use when a shell wedges (hung REPL, runaway process, bad terminal mode). The alternative — [kill_pane](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/) + [split_window](https://libtmux.org/en/py/stable/mcp/tools/split_window/) — destroys pane_id references the agent may still be holding, and rearranges the layout. [respawn-pane](https://libtmux.org/en/tmux/latest/manual/respawn-pane/) preserves both. With `kill=True` (the default), tmux kills the existing process before respawning. Optional `shell` replaces the command tmux relaunches; `start_directory` sets the working directory for the new process; `environment` sets per-process environment variables for the relaunched command (one `-e KEY=VALUE` flag per entry). [`pane_id`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_id/) is required — sibling pane tools accept a hierarchical fallback ([`session_name`](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/) / [`window_id`](https://libtmux.org/en/tmux/latest/catalog/formats/window_id/) / [`pane_index`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_index/)) that resolves to “first pane in session/window”, but combined with default `kill=True` that fallback could silently kill an unrelated process. The signature deliberately omits the resolver fields so the FastMCP schema rejects them at the framework boundary. Resolve via [`list_panes`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/) first. Tip: call [`get_pane_info`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/) first if you need to capture [`pane_current_command`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_current_command/) before respawn — the new process loses its argv. Omitting `shell` makes tmux replay the original argv (good default for shells; may differ for processes spawned via custom shell at split time). * MCP request method `tools/call` Send `respawn_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.parameters) * **[`environment`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fenvironment)**? = `null` ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Environment variables to set for the relaunched process. Each item becomes one `-e KEY=VALUE` flag (tmux’s `cmd-respawn-pane.c` supports the flag repeatedly). Values supplied in a mapping are redacted in the audit log on a per-key basis — keys like `DATABASE_URL` remain visible but their values are replaced by `{len, sha256_prefix}` digests. A JSON object string is redacted as one scalar digest, so its keys are not retained in the audit record. Values may still appear briefly in the OS process table while tmux spawns the new process; do not pass long-lived secrets here when a host-resident agent or other tenant could observe `ps`. * **[`kill`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fkill)**? = `true` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) When True (default), pass `-k` to tmux so the current process is killed before respawning. When False, respawn fails if the pane already has a running process. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’). Required. * **[`shell`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fshell)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Replacement command for tmux to launch. When omitted, tmux replays the original argv (good default for shells; may differ for processes spawned via custom shell at split time). Matches the `shell` parameter on [`split_window`](https://libtmux.org/en/py/stable/mcp/tools/split_window/) and the eventual upstream `Pane.respawn(shell=)` API. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`start_directory`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fstart_directory)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Existing directory to start in. `~` expands; a relative path resolves against the MCP server process’s directory. * **[`suppress_persistent_history`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fsuppress_persistent_history)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to suppress persistent history for the spawned shell. Defaults to False for MCP and direct Python calls. This per-call option does not inherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these controls. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`is_caller`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fis_caller)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) MCP caller identity for this pane. `True` when the pane matches the caller’s `TMUX_PANE` *and* lives on the same tmux socket as the caller’s `TMUX` (verified via socket realpath); `False` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; `None` when the MCP process is not running inside tmux at all. * **[`pane_active`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`pane_at_bottom`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_at_bottom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s bottom edge. * **[`pane_at_left`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_at_left)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s left edge. * **[`pane_at_right`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_at_right)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s right edge. * **[`pane_at_top`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_at_top)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s top edge. tmux accounts for [`pane-border-status`](https://libtmux.org/en/tmux/latest/catalog/options/pane-border-status/) here, so the top row may be 1 instead of 0 when the status bar is at the top. * **[`pane_bottom`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_bottom)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Bottom edge row (inclusive), window-relative. * **[`pane_current_command`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_current_command)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Running command * **[`pane_current_path`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_current_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current working directory * **[`pane_height`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’) * **[`pane_index`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane index * **[`pane_left`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_left)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Left edge column, 0-based and window-relative. * **[`pane_pid`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_pid)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Process ID * **[`pane_right`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_right)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Right edge column (inclusive), window-relative. * **[`pane_title`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_title)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane title * **[`pane_top`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_top)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Top edge row, 0-based and window-relative. * **[`pane_tty`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_tty)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) TTY device path of the pane (e.g. ‘/dev/pts/5’). * **[`pane_width`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent window ID ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "environment": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "string" }, { "type": "null" } ], "default": null, "description": "Environment variables to set for the relaunched process. Each\nitem becomes one ``-e KEY=VALUE`` flag (tmux's\n``cmd-respawn-pane.c`` supports the flag repeatedly). Values\nsupplied in a mapping are redacted in the audit log on a\nper-key basis — keys like ``DATABASE_URL`` remain visible but\ntheir values are replaced by ``{len, sha256_prefix}`` digests.\nA JSON object string is redacted as one scalar digest, so its\nkeys are not retained in the audit record. Values may still\nappear briefly in the OS process table while tmux spawns the\nnew process; do not pass long-lived secrets here when a\nhost-resident agent or other tenant could observe ``ps``." }, "kill": { "default": true, "description": "When True (default), pass ``-k`` to tmux so the current\nprocess is killed before respawning. When False, respawn\nfails if the pane already has a running process.", "type": "boolean" }, "pane_id": { "description": "Pane ID (e.g. '%1'). Required.", "type": "string" }, "shell": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Replacement command for tmux to launch. When omitted, tmux\nreplays the original argv (good default for shells; may differ\nfor processes spawned via custom shell at split time). Matches\nthe ``shell`` parameter on :func:`split_window` and the\neventual upstream ``Pane.respawn(shell=)`` API." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "start_directory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Existing directory to start in. ``~`` expands; a relative path\nresolves against the MCP server process's directory." }, "suppress_persistent_history": { "default": false, "description": "Whether to suppress persistent history for the spawned shell. Defaults\nto False for MCP and direct Python calls. This per-call option does not\ninherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these\ncontrols.", "type": "boolean" } }, "required": [ "pane_id" ], "type": "object" } ``` Output schema ```json { "description": "Serialized tmux pane.", "properties": { "is_caller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all." }, "pane_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "pane_at_bottom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's bottom edge." }, "pane_at_left": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's left edge." }, "pane_at_right": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's right edge." }, "pane_at_top": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top." }, "pane_bottom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Bottom edge row (inclusive), window-relative." }, "pane_current_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Running command" }, "pane_current_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working directory" }, "pane_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "pane_id": { "description": "Pane ID (e.g. '%1')", "type": "string" }, "pane_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane index" }, "pane_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Left edge column, 0-based and window-relative." }, "pane_pid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Process ID" }, "pane_right": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Right edge column (inclusive), window-relative." }, "pane_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane title" }, "pane_top": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Top edge row, 0-based and window-relative." }, "pane_tty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TTY device path of the pane (e.g. '/dev/pts/5')." }, "pane_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent window ID" } }, "required": [ "pane_id" ], "type": "object" } ``` --- # run_command Source: https://libtmux.org/en/py/stable/mcp/tools/run_command/ > Run a shell command in a pane, wait for completion, and capture output. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **run_command**( [command](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fcommand): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [max_lines](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fmax_lines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [suppress_history](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fsuppress_history)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [timeout](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Ftimeout)?: [number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L96)][¶](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command) Run a shell command in a pane, wait for completion, and capture output. Use for the common terminal workflow: run this command, wait until it completes, then report whether it succeeded. The command is sent to the pane’s interactive shell, followed by a private [`tmux wait-for`](https://libtmux.org/en/tmux/latest/manual/wait-for/) signal and a private pane option carrying the shell exit status. This is the AUTHORED-output path — the command you pass is what the wait synchronizes on. Reserve [`wait_for_text`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/) for output you did not author: another process, a human, or a background job. The command runs in a subshell, so `cd`, `export` and other shell state changes do not persist to later calls. * MCP request method `tools/call` Send `run_command` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.parameters) * **[`command`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Shell command to run in the target pane. * **[`max_lines`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fmax_lines)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Maximum pane output lines to return. Defaults to all captured visible output; pass a small value for a tail-only summary. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`suppress_history`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fsuppress_history)**? = `true` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) For MCP calls, omission uses the server’s LIBTMUX_SUPPRESS_HISTORY default; an explicit value overrides it. Direct Python calls default to False. Best effort: the shell must honor space-prefixed history suppression. Suppression requires a single-line command; multiline commands remain available when suppression is false. * **[`timeout`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Ftimeout)**? = `30` ([number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Maximum seconds to wait for command completion. Capped by the same server wait ceiling as [`wait_for_text`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/); an over-large value is not an error — the wait returns at the ceiling and the timeout actually enforced is reported on `RunCommandResult.effective_timeout`. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`effective_timeout`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.output%2Fproperties%2Feffective_timeout)** ([number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Seconds actually enforced for command completion. Server policy caps the requested `timeout`; compare against what you passed to see a clamp. * **[`elapsed_seconds`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.output%2Fproperties%2Felapsed_seconds)** ([number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Time spent waiting in seconds * **[`exit_status`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.output%2Fproperties%2Fexit_status)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Shell exit status, or None when the command timed out * **[`output`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.output%2Fproperties%2Foutput)**? ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")>) Tail-preserved pane output after the wait completes * **[`output_truncated`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.output%2Fproperties%2Foutput_truncated)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) True when output was tail-preserved to stay within max_lines * **[`output_truncated_lines`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.output%2Fproperties%2Foutput_truncated_lines)**? = `0` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of pane lines dropped from the head when truncating * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID that received the command * **[`timed_out`](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.output%2Fproperties%2Ftimed_out)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) True when the wait timed out ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/run_command/#mcp.tool.run_command.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "command": { "description": "Shell command to run in the target pane.", "type": "string" }, "max_lines": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Maximum pane output lines to return. Defaults to all captured\nvisible output; pass a small value for a tail-only summary." }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "suppress_history": { "default": true, "description": "For MCP calls, omission uses the server's LIBTMUX_SUPPRESS_HISTORY\ndefault; an explicit value overrides it. Direct Python calls default\nto False. Best effort: the shell must honor space-prefixed history\nsuppression. Suppression requires a single-line command; multiline\ncommands remain available when suppression is false.", "type": "boolean" }, "timeout": { "default": 30, "description": "Maximum seconds to wait for command completion. Capped by the\nsame server wait ceiling as ``wait_for_text``; an over-large\nvalue is not an error — the wait returns at the ceiling and\nthe timeout actually enforced is reported on\n``RunCommandResult.effective_timeout``.", "type": "number" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "required": [ "command" ], "type": "object" } ``` Output schema ```json { "description": "Result of running a shell command in a pane.", "properties": { "effective_timeout": { "description": "Seconds actually enforced for command completion. Server policy caps the requested ``timeout``; compare against what you passed to see a clamp.", "type": "number" }, "elapsed_seconds": { "description": "Time spent waiting in seconds", "type": "number" }, "exit_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Shell exit status, or None when the command timed out" }, "output": { "description": "Tail-preserved pane output after the wait completes", "items": { "type": "string" }, "type": "array" }, "output_truncated": { "default": false, "description": "True when output was tail-preserved to stay within max_lines", "type": "boolean" }, "output_truncated_lines": { "default": 0, "description": "Number of pane lines dropped from the head when truncating", "type": "integer" }, "pane_id": { "description": "Pane ID that received the command", "type": "string" }, "timed_out": { "description": "True when the wait timed out", "type": "boolean" } }, "required": [ "pane_id", "timed_out", "elapsed_seconds", "effective_timeout" ], "type": "object" } ``` --- # search_panes Source: https://libtmux.org/en/py/stable/mcp/tools/search_panes/ > Search visible terminal text across all tmux panes. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **search_panes**( [content_end](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fcontent_end)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [content_start](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fcontent_start)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [limit](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Flimit)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [match_case](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fmatch_case)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [max_matched_lines_per_pane](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fmax_matched_lines_per_pane)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [offset](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Foffset)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [pattern](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fpattern): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [regex](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fregex)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L146)][¶](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes) Search visible terminal text across all tmux panes. Use when the user asks what panes ‘contain’, ‘mention’, or ‘show’ — e.g. ‘find the pane with the pytest failure’. Searches each pane’s visible terminal scrollback content (not editor or browser text) and returns panes where the pattern is found, with matching lines. * MCP request method `tools/call` Send `search_panes` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.parameters) * **[`content_end`](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fcontent_end)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) End line for capture. * **[`content_start`](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fcontent_start)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Start line for capture. Negative values reach into scrollback. * **[`limit`](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Flimit)**? = `500` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Maximum matching panes returned on this call. Defaults to `SEARCH_DEFAULT_LIMIT`. Pass `None` to disable the cap. * **[`match_case`](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fmatch_case)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to match case. Default False (case-insensitive). * **[`max_matched_lines_per_pane`](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fmax_matched_lines_per_pane)**? = `50` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Per-pane cap on `matched_lines`. Defaults to `SEARCH_DEFAULT_MAX_LINES_PER_PANE`. * **[`offset`](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Foffset)**? = `0` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Skip this many matching panes from the start. Use with `limit` for pagination. * **[`pattern`](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fpattern)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Text to search for in pane contents. Treated as literal text by default. Set `regex=True` to interpret as a regular expression. * **[`regex`](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fregex)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to interpret pattern as a regular expression. Default False (literal text matching). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Limit search to panes in this session (by ID). * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Limit search to panes in this session. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.result) This server does not advertise an output schema for this tool. Its description defines the returned content. ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/search_panes/#mcp.tool.search_panes.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "content_end": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "End line for capture." }, "content_start": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Start line for capture. Negative values reach into scrollback." }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 500, "description": "Maximum matching panes returned on this call. Defaults to\n``SEARCH_DEFAULT_LIMIT``. Pass ``None`` to disable the cap." }, "match_case": { "default": false, "description": "Whether to match case. Default False (case-insensitive).", "type": "boolean" }, "max_matched_lines_per_pane": { "default": 50, "description": "Per-pane cap on ``matched_lines``. Defaults to\n``SEARCH_DEFAULT_MAX_LINES_PER_PANE``.", "type": "integer" }, "offset": { "default": 0, "description": "Skip this many matching panes from the start. Use with\n``limit`` for pagination.", "type": "integer" }, "pattern": { "description": "Text to search for in pane contents. Treated as literal text by\ndefault. Set ``regex=True`` to interpret as a regular expression.", "type": "string" }, "regex": { "default": false, "description": "Whether to interpret pattern as a regular expression. Default False\n(literal text matching).", "type": "boolean" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Limit search to panes in this session (by ID)." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Limit search to panes in this session." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." } }, "required": [ "pattern" ], "type": "object" } ``` --- # select_layout Source: https://libtmux.org/en/py/stable/mcp/tools/select_layout/ > Set the layout of a tmux window. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **select_layout**( [layout](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Flayout): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_index](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Fwindow_index)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/window_tools.py#L527)][¶](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout) Set the layout of a tmux window. Choose from: even-horizontal, even-vertical, main-horizontal, main-vertical, or tiled. Rearranges all panes in the window. * MCP request method `tools/call` Send `select_layout` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.parameters) * **[`layout`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Flayout)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Layout name or custom layout string. Built-in layouts: ‘even-horizontal’, ‘even-vertical’, ‘main-horizontal’, ‘main-horizontal-mirrored’, ‘main-vertical’, ‘main-vertical-mirrored’, ‘tiled’. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID (e.g. ‘@1’). * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index within the session. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane id (`%N`) of the window’s active pane. * **[`pane_count`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fpane_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of panes * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session name * **[`window_active`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`window_height`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Window ID (e.g. ‘@1’) * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index * **[`window_layout`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow_layout)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Layout string * **[`window_name`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window name * **[`window_width`](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/select_layout/#mcp.tool.select_layout.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "layout": { "description": "Layout name or custom layout string. Built-in layouts:\n'even-horizontal', 'even-vertical', 'main-horizontal',\n'main-horizontal-mirrored', 'main-vertical',\n'main-vertical-mirrored', 'tiled'.", "type": "string" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID (e.g. '@1')." }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index within the session." } }, "required": [ "layout" ], "type": "object" } ``` Output schema ```json { "description": "Serialized tmux window.", "properties": { "active_pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane id (``%N``) of the window's active pane." }, "pane_count": { "description": "Number of panes", "type": "integer" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session name" }, "window_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "window_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "window_id": { "description": "Window ID (e.g. '@1')", "type": "string" }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index" }, "window_layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Layout string" }, "window_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window name" }, "window_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" } }, "required": [ "window_id", "pane_count" ], "type": "object" } ``` --- # select_pane Source: https://libtmux.org/en/py/stable/mcp/tools/select_pane/ > Select (focus) a tmux pane by ID or direction. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **select_pane**( [direction](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fdirection)?: "up" | "down" | "left" | "right" | "last" | "next" | "previous" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_index](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fwindow_index)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L164)][¶](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane) Select (focus) a tmux pane by ID or direction. Use this to navigate between panes. Provide either pane_id for direct selection, or direction for relative navigation within a window. * MCP request method `tools/call` Send `select_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.parameters) * **[`direction`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fdirection)**? = `null` ("up" | "down" | "left" | "right" | "last" | "next" | "previous" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Relative direction: ‘up’, ‘down’, ‘left’, ‘right’, ‘last’ (previously active), ‘next’, or ‘previous’. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’) for direct selection. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID for resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for directional navigation scope. * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index for directional navigation scope. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`is_caller`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fis_caller)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) MCP caller identity for this pane. `True` when the pane matches the caller’s `TMUX_PANE` *and* lives on the same tmux socket as the caller’s `TMUX` (verified via socket realpath); `False` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; `None` when the MCP process is not running inside tmux at all. * **[`pane_active`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`pane_at_bottom`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_at_bottom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s bottom edge. * **[`pane_at_left`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_at_left)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s left edge. * **[`pane_at_right`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_at_right)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s right edge. * **[`pane_at_top`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_at_top)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s top edge. tmux accounts for [`pane-border-status`](https://libtmux.org/en/tmux/latest/catalog/options/pane-border-status/) here, so the top row may be 1 instead of 0 when the status bar is at the top. * **[`pane_bottom`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_bottom)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Bottom edge row (inclusive), window-relative. * **[`pane_current_command`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_current_command)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Running command * **[`pane_current_path`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_current_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current working directory * **[`pane_height`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’) * **[`pane_index`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane index * **[`pane_left`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_left)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Left edge column, 0-based and window-relative. * **[`pane_pid`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_pid)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Process ID * **[`pane_right`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_right)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Right edge column (inclusive), window-relative. * **[`pane_title`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_title)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane title * **[`pane_top`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_top)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Top edge row, 0-based and window-relative. * **[`pane_tty`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_tty)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) TTY device path of the pane (e.g. ‘/dev/pts/5’). * **[`pane_width`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent window ID ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/select_pane/#mcp.tool.select_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "direction": { "anyOf": [ { "enum": [ "up", "down", "left", "right", "last", "next", "previous" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Relative direction: 'up', 'down', 'left', 'right', 'last'\n(previously active), 'next', or 'previous'." }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1') for direct selection." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID for resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for directional navigation scope." }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index for directional navigation scope." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux pane.", "properties": { "is_caller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all." }, "pane_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "pane_at_bottom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's bottom edge." }, "pane_at_left": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's left edge." }, "pane_at_right": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's right edge." }, "pane_at_top": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top." }, "pane_bottom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Bottom edge row (inclusive), window-relative." }, "pane_current_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Running command" }, "pane_current_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working directory" }, "pane_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "pane_id": { "description": "Pane ID (e.g. '%1')", "type": "string" }, "pane_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane index" }, "pane_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Left edge column, 0-based and window-relative." }, "pane_pid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Process ID" }, "pane_right": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Right edge column (inclusive), window-relative." }, "pane_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane title" }, "pane_top": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Top edge row, 0-based and window-relative." }, "pane_tty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TTY device path of the pane (e.g. '/dev/pts/5')." }, "pane_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent window ID" } }, "required": [ "pane_id" ], "type": "object" } ``` --- # select_window Source: https://libtmux.org/en/py/stable/mcp/tools/select_window/ > Select (focus) a tmux window by ID, index, or direction. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **select_window**( [direction](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2Fdirection)?: "next" | "previous" | "last" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_index](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2Fwindow_index)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/session_tools.py#L379)][¶](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window) Select (focus) a tmux window by ID, index, or direction. Use to navigate between windows. Provide window_id or window_index for direct selection, or direction for relative navigation. * MCP request method `tools/call` Send `select_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.parameters) * **[`direction`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2Fdirection)**? = `null` ("next" | "previous" | "last" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Relative direction: ‘next’, ‘previous’, or ‘last’. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID for resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID (e.g. ‘@1’) for direct selection. * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index for direct selection. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane id (`%N`) of the window’s active pane. * **[`pane_count`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fpane_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of panes * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session name * **[`window_active`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`window_height`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Window ID (e.g. ‘@1’) * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index * **[`window_layout`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow_layout)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Layout string * **[`window_name`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window name * **[`window_width`](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/select_window/#mcp.tool.select_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "direction": { "anyOf": [ { "enum": [ "next", "previous", "last" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Relative direction: 'next', 'previous', or 'last'." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID for resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID (e.g. '@1') for direct selection." }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index for direct selection." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux window.", "properties": { "active_pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane id (``%N``) of the window's active pane." }, "pane_count": { "description": "Number of panes", "type": "integer" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session name" }, "window_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "window_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "window_id": { "description": "Window ID (e.g. '@1')", "type": "string" }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index" }, "window_layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Layout string" }, "window_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window name" }, "window_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" } }, "required": [ "window_id", "pane_count" ], "type": "object" } ``` --- # send_keys Source: https://libtmux.org/en/py/stable/mcp/tools/send_keys/ > Send keys (commands or text) to a tmux pane. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **send_keys**( [enter](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fenter)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [keys](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fkeys): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [literal](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fliteral)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [suppress_history](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fsuppress_history)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L82)][¶](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys) Send keys (commands or text) to a tmux pane. Use this for raw interactive input: TUI keys, control sequences, partial shell input, or persistent shell state. Use [`send_keys_batch`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/) when you need several ordered raw-input operations. For authored shell commands that need completion, exit status, or captured output, use [`run_command`](https://libtmux.org/en/py/stable/mcp/tools/run_command/) instead. For custom completion outside that shape, compose [`tmux wait-for -S `](https://libtmux.org/en/tmux/latest/manual/wait-for/) into the shell command and call [`wait_for_channel`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/). For repeated observation after input, prefer [`capture_since`](https://libtmux.org/en/py/stable/mcp/tools/capture_since/); reserve [`wait_for_text`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/) for output the agent does not author. Do NOT call [`capture_pane`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/) immediately — both the read and the pattern-match paths race the pane’s PTY draw. * MCP request method `tools/call` Send `send_keys` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.parameters) * **[`enter`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fenter)**? = `true` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to press Enter after sending keys. Default True. * **[`keys`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fkeys)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The keys or text to send. * **[`literal`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fliteral)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to send keys literally (no tmux interpretation). Default False. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`suppress_history`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fsuppress_history)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Suppress shell history by prepending a space; only effective where the shell ignores space-prefixed commands. Default False. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/send_keys/#mcp.tool.send_keys.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "enter": { "default": true, "description": "Whether to press Enter after sending keys. Default True.", "type": "boolean" }, "keys": { "description": "The keys or text to send.", "type": "string" }, "literal": { "default": false, "description": "Whether to send keys literally (no tmux interpretation). Default False.", "type": "boolean" }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "suppress_history": { "default": false, "description": "Suppress shell history by prepending a space; only effective where\nthe shell ignores space-prefixed commands. Default False.", "type": "boolean" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "required": [ "keys" ], "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # send_keys_batch Source: https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/ > Send an ordered batch of raw key/text operations to tmux panes. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **send_keys_batch**( [on_error](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Fon_error)?: "stop" | "continue", [operations](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations): [Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>, [socket_name](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [timeout](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Ftimeout)?: [number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L87)][¶](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch) Send an ordered batch of raw key/text operations to tmux panes. Use this for bulk TUI or persistent-shell input where each item is the same kind of low-level terminal interaction as [`send_keys`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/). For authored shell commands that need exit status and captured output, use [`run_command`](https://libtmux.org/en/py/stable/mcp/tools/run_command/) instead. For repeated observation after sending input, use [`capture_since`](https://libtmux.org/en/py/stable/mcp/tools/capture_since/) with its returned cursor. This tool intentionally does not compose heterogeneous operations such as send → wait → capture. Keeping the batch homogeneous preserves clear per-operation error attribution and avoids embedding a workflow DSL in the MCP tool surface. * MCP request method `tools/call` Send `send_keys_batch` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.parameters) * **[`on_error`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Fon_error)**? = `"stop"` ("stop" | "continue") Whether to stop at the first failed operation or keep attempting later operations. Default “stop”. * **[`operations`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations)** ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>) Ordered raw-input operations to send. * **[Items](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) One raw-input operation for batch sending. Used by `send_keys_batch`. * **[`enter`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Fenter)**? = `true` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to press Enter after sending keys. * **[`keys`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Fkeys)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Keys or text to send. * **[`literal`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Fliteral)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to send keys literally with no tmux key interpretation. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`suppress_history`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Fsuppress_history)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Suppress shell history by prepending a space where the shell ignores space-prefixed commands. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other properties are accepted. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`timeout`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Ftimeout)**? = `null` ([number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Maximum time in seconds to allow the batch to run before aborting. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`failed`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Ffailed)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of operations that failed. * **[`results`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Fresults)**? ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>) Per-operation results in attempted order. * **[Items](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Fresults%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Per-operation result from batch sending. Returned by `send_keys_batch`. * **[`elapsed_seconds`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Felapsed_seconds)** ([number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Time spent on this operation. * **[`error`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Ferror)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Error message for this operation, if it failed. * **[`index`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Zero-based index in the submitted operation list. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Resolved pane ID, or None if target resolution failed. * **[`success`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fsuccess)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) True when this operation sent successfully. * **[`stopped_at`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Fstopped_at)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Index where processing stopped because on_error=‘stop’, or None when all operations were attempted. * **[`succeeded`](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Fsucceeded)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of operations sent successfully. ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "on_error": { "default": "stop", "description": "Whether to stop at the first failed operation or keep attempting\nlater operations. Default \"stop\".", "enum": [ "stop", "continue" ], "type": "string" }, "operations": { "description": "Ordered raw-input operations to send.", "items": { "additionalProperties": false, "description": "One raw-input operation for batch sending.\n\nUsed by :func:`~libtmux_mcp.tools.pane_tools.send_keys_batch`.", "properties": { "enter": { "default": true, "description": "Whether to press Enter after sending keys.", "type": "boolean" }, "keys": { "description": "Keys or text to send.", "type": "string" }, "literal": { "default": false, "description": "Whether to send keys literally with no tmux key interpretation.", "type": "boolean" }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "suppress_history": { "default": false, "description": "Suppress shell history by prepending a space where the shell ignores space-prefixed commands.", "type": "boolean" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "required": [ "keys" ], "type": "object" }, "type": "array" }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "timeout": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Maximum time in seconds to allow the batch to run before aborting." } }, "required": [ "operations" ], "type": "object" } ``` Output schema ```json { "description": "Structured result for a batch of raw-input send operations.", "properties": { "failed": { "description": "Number of operations that failed.", "type": "integer" }, "results": { "description": "Per-operation results in attempted order.", "items": { "description": "Per-operation result from batch sending.\n\nReturned by :func:`~libtmux_mcp.tools.pane_tools.send_keys_batch`.", "properties": { "elapsed_seconds": { "description": "Time spent on this operation.", "type": "number" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Error message for this operation, if it failed." }, "index": { "description": "Zero-based index in the submitted operation list.", "type": "integer" }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Resolved pane ID, or None if target resolution failed." }, "success": { "description": "True when this operation sent successfully.", "type": "boolean" } }, "required": [ "index", "success", "elapsed_seconds" ], "type": "object" }, "type": "array" }, "stopped_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Index where processing stopped because on_error='stop', or None when all operations were attempted." }, "succeeded": { "description": "Number of operations sent successfully.", "type": "integer" } }, "required": [ "succeeded", "failed" ], "type": "object" } ``` --- # set_environment Source: https://libtmux.org/en/py/stable/mcp/tools/set_environment/ > Set a tmux environment variable. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **set_environment**( [name](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.input%2Fproperties%2Fname): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [value](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.input%2Fproperties%2Fvalue): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/env_tools.py#L130)][¶](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment) Set a tmux environment variable. Use to set variables that will be inherited by new panes and windows. Changes do not affect already-running processes. Some variables control later shell execution. Bash sources the file named by `BASH_ENV`, POSIX shells may source the file named by `ENV`, and Bash evaluates `PROMPT_COMMAND` before displaying a prompt. Warning Values set here propagate into **every** shell tmux later spawns in the targeted scope — including panes the user opens manually, not just panes the agent drives. A caller that writes `PATH`, `LD_PRELOAD`, or `AWS_*` variables can influence future commands the human user types directly. Treat this as elevated-risk within `execute`. The audit log redacts the `value` argument, but the side effects persist on disk/memory until tmux is restarted. Prefer `env VAR=value command` via [`send_keys`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/) when you only need the override for a single command. See [topics/trust](https://libtmux-mcp.git-pull.com/topics/trust/). * MCP request method `tools/call` Send `set_environment` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.parameters) * **[`name`](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.input%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Environment variable name. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID to set environment for. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name to set environment for. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`value`](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.input%2Fproperties%2Fvalue)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Environment variable value. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`name`](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.output%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Variable name * **[`status`](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.output%2Fproperties%2Fstatus)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Operation status * **[`value`](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.output%2Fproperties%2Fvalue)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Value that was set ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/set_environment/#mcp.tool.set_environment.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "name": { "description": "Environment variable name.", "type": "string" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID to set environment for." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name to set environment for." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "value": { "description": "Environment variable value.", "type": "string" } }, "required": [ "name", "value" ], "type": "object" } ``` Output schema ```json { "description": "Result of a set_environment call.", "properties": { "name": { "description": "Variable name", "type": "string" }, "status": { "description": "Operation status", "type": "string" }, "value": { "description": "Value that was set", "type": "string" } }, "required": [ "name", "value", "status" ], "type": "object" } ``` --- # set_option Source: https://libtmux.org/en/py/stable/mcp/tools/set_option/ > Set a tmux option value. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **set_option**( [global\_](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.input%2Fproperties%2Fglobal_)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [option](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.input%2Fproperties%2Foption): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [scope](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.input%2Fproperties%2Fscope)?: "server" | "session" | "window" | "pane" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [target](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.input%2Fproperties%2Ftarget)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [value](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.input%2Fproperties%2Fvalue): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/option_tools.py#L158)][¶](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option) Set a tmux option value. Some option values are executable. tmux runs a `#(...)` job inside the status formats when it draws them, and repeats it on the status interval; [`default-command`](https://libtmux.org/en/tmux/latest/catalog/options/default-command/) and [`default-shell`](https://libtmux.org/en/tmux/latest/catalog/options/default-shell/) decide what every future pane runs, and [`command-alias`](https://libtmux.org/en/tmux/latest/catalog/options/command-alias/) rewrites later commands. The value is stored verbatim, so an option that interprets it later runs what is stored, not what this call did. Use to change tmux behavior at runtime. Common uses: adjusting history-limit, enabling mouse support, changing status bar format. * MCP request method `tools/call` Send `set_option` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.parameters) * **[`global_`](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.input%2Fproperties%2Fglobal_)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to set the global option. * **[`option`](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.input%2Fproperties%2Foption)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The tmux option name to set. * **[`scope`](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.input%2Fproperties%2Fscope)**? = `null` ("server" | "session" | "window" | "pane" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Option scope. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`target`](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.input%2Fproperties%2Ftarget)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Target identifier. For session scope: session name (e.g. ‘mysession’). For window scope: window ID (e.g. ‘@1’). For pane scope: pane ID (e.g. ‘%1’). Requires scope. * **[`value`](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.input%2Fproperties%2Fvalue)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The value to set. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`option`](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.output%2Fproperties%2Foption)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Option name * **[`status`](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.output%2Fproperties%2Fstatus)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Operation status * **[`value`](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.output%2Fproperties%2Fvalue)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Value that was set ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/set_option/#mcp.tool.set_option.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "global_": { "default": false, "description": "Whether to set the global option.", "type": "boolean" }, "option": { "description": "The tmux option name to set.", "type": "string" }, "scope": { "anyOf": [ { "enum": [ "server", "session", "window", "pane" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Option scope." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "target": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Target identifier. For session scope: session name\n(e.g. 'mysession'). For window scope: window ID (e.g. '@1').\nFor pane scope: pane ID (e.g. '%1'). Requires scope." }, "value": { "description": "The value to set.", "type": "string" } }, "required": [ "option", "value" ], "type": "object" } ``` Output schema ```json { "description": "Result of a set_option call.", "properties": { "option": { "description": "Option name", "type": "string" }, "status": { "description": "Operation status", "type": "string" }, "value": { "description": "Value that was set", "type": "string" } }, "required": [ "option", "value", "status" ], "type": "object" } ``` --- # set_pane_title Source: https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/ > Set the title of a tmux pane. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **set_pane_title**( [pane_id](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [title](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2Ftitle): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L126)][¶](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title) Set the title of a tmux pane. Use titles to label panes for later identification via [list_panes](https://libtmux.org/en/py/stable/mcp/tools/list_panes/) or [get_pane_info](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/). * MCP request method `tools/call` Send `set_pane_title` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.parameters) * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`title`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2Ftitle)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The new pane title. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`is_caller`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fis_caller)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) MCP caller identity for this pane. `True` when the pane matches the caller’s `TMUX_PANE` *and* lives on the same tmux socket as the caller’s `TMUX` (verified via socket realpath); `False` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; `None` when the MCP process is not running inside tmux at all. * **[`pane_active`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`pane_at_bottom`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_at_bottom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s bottom edge. * **[`pane_at_left`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_at_left)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s left edge. * **[`pane_at_right`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_at_right)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s right edge. * **[`pane_at_top`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_at_top)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s top edge. tmux accounts for [`pane-border-status`](https://libtmux.org/en/tmux/latest/catalog/options/pane-border-status/) here, so the top row may be 1 instead of 0 when the status bar is at the top. * **[`pane_bottom`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_bottom)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Bottom edge row (inclusive), window-relative. * **[`pane_current_command`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_current_command)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Running command * **[`pane_current_path`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_current_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current working directory * **[`pane_height`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’) * **[`pane_index`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane index * **[`pane_left`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_left)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Left edge column, 0-based and window-relative. * **[`pane_pid`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_pid)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Process ID * **[`pane_right`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_right)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Right edge column (inclusive), window-relative. * **[`pane_title`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_title)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane title * **[`pane_top`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_top)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Top edge row, 0-based and window-relative. * **[`pane_tty`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_tty)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) TTY device path of the pane (e.g. ‘/dev/pts/5’). * **[`pane_width`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent window ID ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "title": { "description": "The new pane title.", "type": "string" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "required": [ "title" ], "type": "object" } ``` Output schema ```json { "description": "Serialized tmux pane.", "properties": { "is_caller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all." }, "pane_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "pane_at_bottom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's bottom edge." }, "pane_at_left": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's left edge." }, "pane_at_right": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's right edge." }, "pane_at_top": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top." }, "pane_bottom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Bottom edge row (inclusive), window-relative." }, "pane_current_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Running command" }, "pane_current_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working directory" }, "pane_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "pane_id": { "description": "Pane ID (e.g. '%1')", "type": "string" }, "pane_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane index" }, "pane_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Left edge column, 0-based and window-relative." }, "pane_pid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Process ID" }, "pane_right": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Right edge column (inclusive), window-relative." }, "pane_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane title" }, "pane_top": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Top edge row, 0-based and window-relative." }, "pane_tty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TTY device path of the pane (e.g. '/dev/pts/5')." }, "pane_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent window ID" } }, "required": [ "pane_id" ], "type": "object" } ``` --- # show_buffer Source: https://libtmux.org/en/py/stable/mcp/tools/show_buffer/ > Read back the contents of an MCP-owned buffer. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **show_buffer**( [buffer_name](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/#mcp.tool.show_buffer.input%2Fproperties%2Fbuffer_name): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [max_lines](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/#mcp.tool.show_buffer.input%2Fproperties%2Fmax_lines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/#mcp.tool.show_buffer.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/buffer_tools.py#L396)][¶](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/#mcp.tool.show_buffer) Read back the contents of an MCP-owned buffer. Output is tail-preserved: when the buffer exceeds `max_lines` the oldest lines are dropped and [`content_truncated`](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-buffercontent-content_truncated/) is set so the caller can tell truncation happened and opt in to a full read via `max_lines=None`. This mirrors [`capture_pane`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/) — one consistent bounded-output contract across read-heavy tools so a pathological [`load_buffer`](https://libtmux.org/en/py/stable/mcp/tools/load_buffer/) staging cannot blow the agent’s context window on a single `show_buffer` call. * MCP request method `tools/call` Send `show_buffer` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/#mcp.tool.show_buffer.parameters) * **[`buffer_name`](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/#mcp.tool.show_buffer.input%2Fproperties%2Fbuffer_name)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Must match the full MCP-namespaced form. * **[`max_lines`](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/#mcp.tool.show_buffer.input%2Fproperties%2Fmax_lines)**? = `500` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Maximum number of lines to return. Defaults to [`SHOW_BUFFER_DEFAULT_MAX_LINES`](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-buffer_tools-show_buffer_default_max_lines/). Pass `None` for no truncation. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/#mcp.tool.show_buffer.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/#mcp.tool.show_buffer.result) This server does not advertise an output schema for this tool. Its description defines the returned content. ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/#mcp.tool.show_buffer.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/show_buffer/#mcp.tool.show_buffer.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "buffer_name": { "description": "Must match the full MCP-namespaced form.", "type": "string" }, "max_lines": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 500, "description": "Maximum number of lines to return. Defaults to\n:data:`SHOW_BUFFER_DEFAULT_MAX_LINES`. Pass ``None`` for no\ntruncation." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." } }, "required": [ "buffer_name" ], "type": "object" } ``` --- # show_environment Source: https://libtmux.org/en/py/stable/mcp/tools/show_environment/ > Show tmux environment variables. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **show_environment**( [session_id](https://libtmux.org/en/py/stable/mcp/tools/show_environment/#mcp.tool.show_environment.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/show_environment/#mcp.tool.show_environment.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/show_environment/#mcp.tool.show_environment.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/env_tools.py#L125)][¶](https://libtmux.org/en/py/stable/mcp/tools/show_environment/#mcp.tool.show_environment) Show tmux environment variables. Use to inspect tmux environment variables that affect child processes. * MCP request method `tools/call` Send `show_environment` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/show_environment/#mcp.tool.show_environment.parameters) * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/show_environment/#mcp.tool.show_environment.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID to query environment for. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/show_environment/#mcp.tool.show_environment.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name to query environment for. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/show_environment/#mcp.tool.show_environment.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/show_environment/#mcp.tool.show_environment.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`variables`](https://libtmux.org/en/py/stable/mcp/tools/show_environment/#mcp.tool.show_environment.output%2Fproperties%2Fvariables)** ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\) Environment variable mapping ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/show_environment/#mcp.tool.show_environment.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/show_environment/#mcp.tool.show_environment.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID to query environment for." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name to query environment for." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." } }, "type": "object" } ``` Output schema ```json { "description": "Result of a show_environment call.", "properties": { "variables": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] }, "description": "Environment variable mapping", "type": "object" } }, "required": [ "variables" ], "type": "object" } ``` --- # show_hook Source: https://libtmux.org/en/py/stable/mcp/tools/show_hook/ > Look up a specific tmux hook by name. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **show_hook**( [global\_](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.input%2Fproperties%2Fglobal_)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [hook_name](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.input%2Fproperties%2Fhook_name): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [scope](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.input%2Fproperties%2Fscope)?: "server" | "session" | "window" | "pane" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [target](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.input%2Fproperties%2Ftarget)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/hook_tools.py#L248)][¶](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook) Look up a specific tmux hook by name. Returns a [`HookListResult`](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-hooklistresult/) with zero or more [`HookEntry`](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-hookentry/) rows — zero if the hook is unset, one if it is a scalar hook, and multiple if it is an array hook with sparse indices. * MCP request method `tools/call` Send `show_hook` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.parameters) * **[`global_`](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.input%2Fproperties%2Fglobal_)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) [`show_hooks`](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/). * **[`hook_name`](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.input%2Fproperties%2Fhook_name)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Hook to look up (e.g. [`"pane-exited"`](https://libtmux.org/en/tmux/latest/catalog/hooks/pane-exited/)). * **[`scope`](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.input%2Fproperties%2Fscope)**? = `null` ("server" | "session" | "window" | "pane" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) [`show_hooks`](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/). * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) [`show_hooks`](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/). * **[`target`](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.input%2Fproperties%2Ftarget)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) [`show_hooks`](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/). No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`entries`](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.output%2Fproperties%2Fentries)**? ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>) * **[Items](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.output%2Fproperties%2Fentries%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) One entry in a tmux hook array. Hooks like [`session-renamed`](https://libtmux.org/en/tmux/latest/catalog/hooks/session-renamed/) are arrays — they can have multiple commands registered at sparse indices. [`HookEntry`](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-hookentry/) flattens one index+command pair into a serialisable row. * **[`command`](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.output%2Fproperties%2Fentries%2Fitems%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) tmux command string registered at that index. * **[`hook_name`](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.output%2Fproperties%2Fentries%2Fitems%2Fproperties%2Fhook_name)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Hook name (e.g. ‘pane-exited’). * **[`index`](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.output%2Fproperties%2Fentries%2Fitems%2Fproperties%2Findex)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Array index for array-style hooks (e.g. session-renamed\[3]). `None` for scalar hooks. ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/show_hook/#mcp.tool.show_hook.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "global_": { "default": false, "description": ":func:`~libtmux_mcp.tools.hook_tools.show_hooks`.", "type": "boolean" }, "hook_name": { "description": "Hook to look up (e.g. ``\"pane-exited\"``).", "type": "string" }, "scope": { "anyOf": [ { "enum": [ "server", "session", "window", "pane" ], "type": "string" }, { "type": "null" } ], "default": null, "description": ":func:`~libtmux_mcp.tools.hook_tools.show_hooks`." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": ":func:`~libtmux_mcp.tools.hook_tools.show_hooks`." }, "target": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": ":func:`~libtmux_mcp.tools.hook_tools.show_hooks`." } }, "required": [ "hook_name" ], "type": "object" } ``` Output schema ```json { "description": "Structured result for hook introspection.\n\nReturned by :func:`~libtmux_mcp.tools.hook_tools.show_hooks` and\n:func:`~libtmux_mcp.tools.hook_tools.show_hook`.\nFlat list of :class:`~libtmux_mcp.models.HookEntry` instances so\nMCP clients can iterate without caring whether the underlying tmux\nhook is scalar or array-shaped.", "properties": { "entries": { "items": { "description": "One entry in a tmux hook array.\n\nHooks like ``session-renamed`` are arrays — they can have multiple\ncommands registered at sparse indices.\n:class:`~libtmux_mcp.models.HookEntry` flattens one index+command\npair into a serialisable row.", "properties": { "command": { "description": "tmux command string registered at that index.", "type": "string" }, "hook_name": { "description": "Hook name (e.g. 'pane-exited').", "type": "string" }, "index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Array index for array-style hooks (e.g. session-renamed[3]). ``None`` for scalar hooks." } }, "required": [ "hook_name", "command" ], "type": "object" }, "type": "array" } }, "type": "object" } ``` --- # show_hooks Source: https://libtmux.org/en/py/stable/mcp/tools/show_hooks/ > List configured tmux hooks at the given scope. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **show_hooks**( [global\_](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.input%2Fproperties%2Fglobal_)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [scope](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.input%2Fproperties%2Fscope)?: "server" | "session" | "window" | "pane" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [target](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.input%2Fproperties%2Ftarget)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/hook_tools.py#L243)][¶](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks) List configured tmux hooks at the given scope. `scope="server"` enumerates hooks installed via [`tmux set-hook -g ...`](https://libtmux.org/en/tmux/latest/manual/set-hook/). tmux splits those globals across two options trees by hook category: session-level hooks ([`session-closed`](https://libtmux.org/en/tmux/latest/catalog/hooks/session-closed/), `client-*`, etc.) live in the global-session tree enumerated by [`show-hooks -g`](https://libtmux.org/en/tmux/latest/manual/show-hooks/), while pane/window-level hooks ([`pane-focus-in`](https://libtmux.org/en/tmux/latest/catalog/hooks/pane-focus-in/), [`window-resized`](https://libtmux.org/en/tmux/latest/catalog/hooks/window-resized/), etc.) live in the global-window tree enumerated by [`show-hooks -gw`](https://libtmux.org/en/tmux/latest/manual/show-hooks/ "tmux command"). This tool consults both trees and merges the results so the enumeration matches what a name-targeted [`show_hook`](https://libtmux.org/en/py/stable/mcp/tools/show_hook/) call would return. * MCP request method `tools/call` Send `show_hooks` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.parameters) * **[`global_`](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.input%2Fproperties%2Fglobal_)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Pass `-g` to query global hooks. Default False. * **[`scope`](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.input%2Fproperties%2Fscope)**? = `null` ("server" | "session" | "window" | "pane" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Hook scope (server/session/window/pane). Defaults to the calling object’s scope when a `target` is given. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`target`](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.input%2Fproperties%2Ftarget)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Target identifier. For session scope: session name. For window scope: window ID. For pane scope: pane ID. Requires `scope`. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`entries`](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.output%2Fproperties%2Fentries)**? ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>) * **[Items](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.output%2Fproperties%2Fentries%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) One entry in a tmux hook array. Hooks like [`session-renamed`](https://libtmux.org/en/tmux/latest/catalog/hooks/session-renamed/) are arrays — they can have multiple commands registered at sparse indices. [`HookEntry`](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-hookentry/) flattens one index+command pair into a serialisable row. * **[`command`](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.output%2Fproperties%2Fentries%2Fitems%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) tmux command string registered at that index. * **[`hook_name`](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.output%2Fproperties%2Fentries%2Fitems%2Fproperties%2Fhook_name)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Hook name (e.g. ‘pane-exited’). * **[`index`](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.output%2Fproperties%2Fentries%2Fitems%2Fproperties%2Findex)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Array index for array-style hooks (e.g. session-renamed\[3]). `None` for scalar hooks. ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/show_hooks/#mcp.tool.show_hooks.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "global_": { "default": false, "description": "Pass ``-g`` to query global hooks. Default False.", "type": "boolean" }, "scope": { "anyOf": [ { "enum": [ "server", "session", "window", "pane" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Hook scope (server/session/window/pane). Defaults to the\ncalling object's scope when a ``target`` is given." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "target": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Target identifier. For session scope: session name. For window\nscope: window ID. For pane scope: pane ID. Requires ``scope``." } }, "type": "object" } ``` Output schema ```json { "description": "Structured result for hook introspection.\n\nReturned by :func:`~libtmux_mcp.tools.hook_tools.show_hooks` and\n:func:`~libtmux_mcp.tools.hook_tools.show_hook`.\nFlat list of :class:`~libtmux_mcp.models.HookEntry` instances so\nMCP clients can iterate without caring whether the underlying tmux\nhook is scalar or array-shaped.", "properties": { "entries": { "items": { "description": "One entry in a tmux hook array.\n\nHooks like ``session-renamed`` are arrays — they can have multiple\ncommands registered at sparse indices.\n:class:`~libtmux_mcp.models.HookEntry` flattens one index+command\npair into a serialisable row.", "properties": { "command": { "description": "tmux command string registered at that index.", "type": "string" }, "hook_name": { "description": "Hook name (e.g. 'pane-exited').", "type": "string" }, "index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Array index for array-style hooks (e.g. session-renamed[3]). ``None`` for scalar hooks." } }, "required": [ "hook_name", "command" ], "type": "object" }, "type": "array" } }, "type": "object" } ``` --- # show_option Source: https://libtmux.org/en/py/stable/mcp/tools/show_option/ > Show a tmux option value. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **show_option**( [global\_](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Fglobal_)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [option](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Foption): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [scope](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Fscope)?: "server" | "session" | "window" | "pane" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [target](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Ftarget)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/option_tools.py#L153)][¶](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option) Show a tmux option value. Use to check tmux configuration values such as history-limit, mouse support, or status bar settings. * MCP request method `tools/call` Send `show_option` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.parameters) * **[`global_`](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Fglobal_)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to query the global option. * **[`option`](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Foption)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The tmux option name to query. * **[`scope`](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Fscope)**? = `null` ("server" | "session" | "window" | "pane" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Option scope. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`target`](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Ftarget)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Target identifier. For session scope: session name (e.g. ‘mysession’). For window scope: window ID (e.g. ‘@1’). For pane scope: pane ID (e.g. ‘%1’). Requires scope. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`option`](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.output%2Fproperties%2Foption)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Option name * **[`value`](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.output%2Fproperties%2Fvalue)** (any value) Option value ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/show_option/#mcp.tool.show_option.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "global_": { "default": false, "description": "Whether to query the global option.", "type": "boolean" }, "option": { "description": "The tmux option name to query.", "type": "string" }, "scope": { "anyOf": [ { "enum": [ "server", "session", "window", "pane" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Option scope." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "target": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Target identifier. For session scope: session name\n(e.g. 'mysession'). For window scope: window ID (e.g. '@1').\nFor pane scope: pane ID (e.g. '%1'). Requires scope." } }, "required": [ "option" ], "type": "object" } ``` Output schema ```json { "description": "Result of a show_option call.", "properties": { "option": { "description": "Option name", "type": "string" }, "value": { "description": "Option value" } }, "required": [ "option", "value" ], "type": "object" } ``` --- # signal_channel Source: https://libtmux.org/en/py/stable/mcp/tools/signal_channel/ > Signal a tmux wait-for channel, waking blocked waiters. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **signal_channel**( [channel](https://libtmux.org/en/py/stable/mcp/tools/signal_channel/#mcp.tool.signal_channel.input%2Fproperties%2Fchannel): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/signal_channel/#mcp.tool.signal_channel.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/wait_for_tools.py#L327)][¶](https://libtmux.org/en/py/stable/mcp/tools/signal_channel/#mcp.tool.signal_channel) Signal a tmux [`wait-for`](https://libtmux.org/en/tmux/latest/manual/wait-for/) channel, waking blocked waiters. With no current waiter, tmux records one pending signal for the next waiter to consume. Signalling that channel again clears it. A woken waiter continues whatever work follows its wait. * MCP request method `tools/call` Send `signal_channel` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/signal_channel/#mcp.tool.signal_channel.parameters) * **[`channel`](https://libtmux.org/en/py/stable/mcp/tools/signal_channel/#mcp.tool.signal_channel.input%2Fproperties%2Fchannel)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Channel name. Must match `^[A-Za-z0-9_.:-]{1,128}$`. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/signal_channel/#mcp.tool.signal_channel.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/signal_channel/#mcp.tool.signal_channel.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/signal_channel/#mcp.tool.signal_channel.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/signal_channel/#mcp.tool.signal_channel.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/signal_channel/#mcp.tool.signal_channel.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "channel": { "description": "Channel name. Must match ``^[A-Za-z0-9_.:-]{1,128}$``.", "type": "string" }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." } }, "required": [ "channel" ], "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # snapshot_pane Source: https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/ > Snapshot a tmux pane: visible terminal output, cursor, mode, scroll. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **snapshot_pane**( [max_lines](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2Fmax_lines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L158)][¶](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane) Snapshot a tmux pane: visible terminal output, cursor, mode, scroll. Use for terminal-contents inspection — ‘what’s in my pane’, ‘the current shell output’ — not editor panes or browser viewports. Returns everything [`capture_pane`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/) and [`get_pane_info`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/) return, plus cursor position, [copy-mode](https://libtmux.org/en/tmux/latest/manual/copy-mode/) state, and scroll position — in a single call. Prefer this over separate [capture_pane](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/) + [get_pane_info](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/) calls when you need to reason about cursor location or pane mode. The `content` field is tail-preserved: when the captured pane exceeds `max_lines`, the oldest lines are dropped and the result is reported via `content_truncated` / `content_truncated_lines` fields on the returned [`PaneSnapshot`](https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-models-panesnapshot/). Pass `max_lines=None` to opt out of truncation entirely. * MCP request method `tools/call` Send `snapshot_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.parameters) * **[`max_lines`](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2Fmax_lines)**? = `500` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Maximum number of content lines to return. Defaults to `CAPTURE_DEFAULT_MAX_LINES`. Pass `None` to return the full capture untrimmed. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.result) This server does not advertise an output schema for this tool. Its description defines the returned content. ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "max_lines": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": 500, "description": "Maximum number of content lines to return. Defaults to\n``CAPTURE_DEFAULT_MAX_LINES``.\nPass ``None`` to return the full capture untrimmed." }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "type": "object" } ``` --- # split_window Source: https://libtmux.org/en/py/stable/mcp/tools/split_window/ > Split a tmux window to create a new pane. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **split_window**( [direction](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fdirection)?: "above" | "below" | "left" | "right" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [environment](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fenvironment)?: [Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [shell](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fshell)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [size](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fsize)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [start_directory](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fstart_directory)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [suppress_persistent_history](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fsuppress_persistent_history)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [window_index](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fwindow_index)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/window_tools.py#L512)][¶](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window) Split a tmux window to create a new pane. Creates a new pane by splitting an existing one. Use direction to choose above/below/left/right. Returns the new pane’s info including its pane_id. * MCP request method `tools/call` Send `split_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.parameters) * **[`direction`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fdirection)**? = `null` ("above" | "below" | "left" | "right" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Split direction. * **[`environment`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fenvironment)**? = `null` ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Per-process environment as a mapping or JSON object string. Values do not modify the tmux session environment. Each item becomes a tmux `-e` launch option. Values may be visible to host process inspection in the tmux client argv during launch and in the child environment afterward; MCP audit redaction does not hide either surface. Pass credential references, not literal credentials. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID to split from. If given, splits adjacent to this pane. * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’). * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name. * **[`shell`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fshell)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Shell command to run in the new pane. * **[`size`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fsize)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Size of the new pane. Use a string with ’%%’ suffix for percentage (e.g. ‘50%%’) or an integer for lines/columns. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`start_directory`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fstart_directory)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Existing directory to start in. `~` expands; a relative path resolves against the MCP server process’s directory. * **[`suppress_persistent_history`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fsuppress_persistent_history)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to suppress persistent history for the spawned shell. Defaults to False for MCP and direct Python calls. This per-call option does not inherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these controls. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID (e.g. ‘@1’). * **[`window_index`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fwindow_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window index within the session. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`is_caller`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fis_caller)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) MCP caller identity for this pane. `True` when the pane matches the caller’s `TMUX_PANE` *and* lives on the same tmux socket as the caller’s `TMUX` (verified via socket realpath); `False` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; `None` when the MCP process is not running inside tmux at all. * **[`pane_active`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`pane_at_bottom`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_at_bottom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s bottom edge. * **[`pane_at_left`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_at_left)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s left edge. * **[`pane_at_right`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_at_right)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s right edge. * **[`pane_at_top`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_at_top)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s top edge. tmux accounts for [`pane-border-status`](https://libtmux.org/en/tmux/latest/catalog/options/pane-border-status/) here, so the top row may be 1 instead of 0 when the status bar is at the top. * **[`pane_bottom`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_bottom)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Bottom edge row (inclusive), window-relative. * **[`pane_current_command`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_current_command)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Running command * **[`pane_current_path`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_current_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current working directory * **[`pane_height`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’) * **[`pane_index`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane index * **[`pane_left`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_left)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Left edge column, 0-based and window-relative. * **[`pane_pid`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_pid)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Process ID * **[`pane_right`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_right)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Right edge column (inclusive), window-relative. * **[`pane_title`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_title)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane title * **[`pane_top`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_top)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Top edge row, 0-based and window-relative. * **[`pane_tty`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_tty)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) TTY device path of the pane (e.g. ‘/dev/pts/5’). * **[`pane_width`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent window ID ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/split_window/#mcp.tool.split_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "direction": { "anyOf": [ { "enum": [ "above", "below", "left", "right" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Split direction." }, "environment": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "string" }, { "type": "null" } ], "default": null, "description": "Per-process environment as a mapping or JSON object string. Values do\nnot modify the tmux session environment. Each item becomes a tmux\n``-e`` launch option. Values may be visible to host process inspection\nin the tmux client argv during launch and in the child environment\nafterward; MCP audit redaction does not hide either surface. Pass\ncredential references, not literal credentials." }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID to split from. If given, splits adjacent to this pane." }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1')." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name." }, "shell": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Shell command to run in the new pane." }, "size": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Size of the new pane. Use a string with '%%' suffix for\npercentage (e.g. '50%%') or an integer for lines/columns." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "start_directory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Existing directory to start in. ``~`` expands; a relative path\nresolves against the MCP server process's directory." }, "suppress_persistent_history": { "default": false, "description": "Whether to suppress persistent history for the spawned shell. Defaults\nto False for MCP and direct Python calls. This per-call option does not\ninherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these\ncontrols.", "type": "boolean" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID (e.g. '@1')." }, "window_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window index within the session." } }, "type": "object" } ``` Output schema ```json { "description": "Serialized tmux pane.", "properties": { "is_caller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all." }, "pane_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "pane_at_bottom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's bottom edge." }, "pane_at_left": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's left edge." }, "pane_at_right": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's right edge." }, "pane_at_top": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top." }, "pane_bottom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Bottom edge row (inclusive), window-relative." }, "pane_current_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Running command" }, "pane_current_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working directory" }, "pane_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "pane_id": { "description": "Pane ID (e.g. '%1')", "type": "string" }, "pane_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane index" }, "pane_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Left edge column, 0-based and window-relative." }, "pane_pid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Process ID" }, "pane_right": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Right edge column (inclusive), window-relative." }, "pane_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane title" }, "pane_top": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Top edge row, 0-based and window-relative." }, "pane_tty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TTY device path of the pane (e.g. '/dev/pts/5')." }, "pane_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent window ID" } }, "required": [ "pane_id" ], "type": "object" } ``` --- # swap_pane Source: https://libtmux.org/en/py/stable/mcp/tools/swap_pane/ > Swap the positions of two panes. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **swap_pane**( [socket_name](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [source_pane_id](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.input%2Fproperties%2Fsource_pane_id): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [target_pane_id](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.input%2Fproperties%2Ftarget_pane_id): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L169)][¶](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane) Swap the positions of two panes. Exchanges the visual positions of two panes. Both panes must exist. Use this to rearrange pane layout without changing content. * MCP request method `tools/call` Send `swap_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.parameters) * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`source_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.input%2Fproperties%2Fsource_pane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID of the first pane (e.g. ‘%1’). * **[`target_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.input%2Fproperties%2Ftarget_pane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID of the second pane (e.g. ‘%2’). No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`is_caller`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fis_caller)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) MCP caller identity for this pane. `True` when the pane matches the caller’s `TMUX_PANE` *and* lives on the same tmux socket as the caller’s `TMUX` (verified via socket realpath); `False` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; `None` when the MCP process is not running inside tmux at all. * **[`pane_active`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`pane_at_bottom`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_at_bottom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s bottom edge. * **[`pane_at_left`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_at_left)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s left edge. * **[`pane_at_right`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_at_right)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s right edge. * **[`pane_at_top`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_at_top)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s top edge. tmux accounts for [`pane-border-status`](https://libtmux.org/en/tmux/latest/catalog/options/pane-border-status/) here, so the top row may be 1 instead of 0 when the status bar is at the top. * **[`pane_bottom`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_bottom)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Bottom edge row (inclusive), window-relative. * **[`pane_current_command`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_current_command)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Running command * **[`pane_current_path`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_current_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current working directory * **[`pane_height`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’) * **[`pane_index`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane index * **[`pane_left`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_left)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Left edge column, 0-based and window-relative. * **[`pane_pid`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_pid)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Process ID * **[`pane_right`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_right)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Right edge column (inclusive), window-relative. * **[`pane_title`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_title)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane title * **[`pane_top`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_top)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Top edge row, 0-based and window-relative. * **[`pane_tty`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_tty)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) TTY device path of the pane (e.g. ‘/dev/pts/5’). * **[`pane_width`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpane_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent window ID ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/swap_pane/#mcp.tool.swap_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "source_pane_id": { "description": "Pane ID of the first pane (e.g. '%1').", "type": "string" }, "target_pane_id": { "description": "Pane ID of the second pane (e.g. '%2').", "type": "string" } }, "required": [ "source_pane_id", "target_pane_id" ], "type": "object" } ``` Output schema ```json { "description": "Serialized tmux pane.", "properties": { "is_caller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all." }, "pane_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "pane_at_bottom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's bottom edge." }, "pane_at_left": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's left edge." }, "pane_at_right": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's right edge." }, "pane_at_top": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top." }, "pane_bottom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Bottom edge row (inclusive), window-relative." }, "pane_current_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Running command" }, "pane_current_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working directory" }, "pane_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "pane_id": { "description": "Pane ID (e.g. '%1')", "type": "string" }, "pane_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane index" }, "pane_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Left edge column, 0-based and window-relative." }, "pane_pid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Process ID" }, "pane_right": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Right edge column (inclusive), window-relative." }, "pane_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane title" }, "pane_top": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Top edge row, 0-based and window-relative." }, "pane_tty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TTY device path of the pane (e.g. '/dev/pts/5')." }, "pane_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent window ID" } }, "required": [ "pane_id" ], "type": "object" } ``` --- # wait_for_channel Source: https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/ > Block until a tmux wait-for channel is signalled. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **wait_for_channel**( [channel](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.input%2Fproperties%2Fchannel): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [timeout](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.input%2Fproperties%2Ftimeout)?: [number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/wait_for_tools.py#L322)][¶](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel) Block until a tmux [`wait-for`](https://libtmux.org/en/tmux/latest/manual/wait-for/) channel is signalled. This is the AUTHORED-output synchronisation primitive: the channel only fires because your own composed shell command signals it. Reserve [`wait_for_text`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/) for output you did not author. Agents can compose this with [`send_keys`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/) to turn shell-side milestones into explicit synchronisation points:: ```plaintext send_keys( "pytest; tmux wait-for -S tests_done", pane_id=..., ) wait_for_channel("tests_done", timeout=60) ``` Shell `;` semantics fire [`wait-for -S`](https://libtmux.org/en/tmux/latest/manual/wait-for/ "tmux command") whether the command succeeded or failed, so the edge-triggered signal never deadlocks on a crash. Do NOT chain `exit $status` after the signal — in an interactive shell that exits the shell itself, which destroys single-pane sessions. Exit-status preservation in interactive shells is out-of-scope; inspect the captured output for command-specific success markers. * MCP request method `tools/call` Send `wait_for_channel` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.parameters) * **[`channel`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.input%2Fproperties%2Fchannel)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Channel name. Must match `^[A-Za-z0-9_.:-]{1,128}$`. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`timeout`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.input%2Fproperties%2Ftimeout)**? = `30` ([number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Maximum seconds to wait. The underlying [`tmux wait-for`](https://libtmux.org/en/tmux/latest/manual/wait-for/) has no built-in timeout — this wrapper enforces it by killing the tmux child, which also happens if the call is cancelled. Defaults to 30 seconds. Capped by the same server wait ceiling as [`wait_for_text`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/); an over-large value is not an error, the wait returns at the ceiling and the confirmation message names the timeout that was actually enforced. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`result`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.output%2Fproperties%2Fresult)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "channel": { "description": "Channel name. Must match ``^[A-Za-z0-9_.:-]{1,128}$``.", "type": "string" }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "timeout": { "default": 30, "description": "Maximum seconds to wait. The underlying ``tmux wait-for`` has\nno built-in timeout — this wrapper enforces it by killing the\ntmux child, which also happens if the call is cancelled.\nDefaults to 30 seconds. Capped by the same server wait ceiling\nas ``wait_for_text``; an over-large value is not an error, the\nwait returns at the ceiling and the confirmation message names\nthe timeout that was actually enforced.", "type": "number" } }, "required": [ "channel" ], "type": "object" } ``` Output schema ```json { "properties": { "result": { "type": "string" } }, "required": [ "result" ], "type": "object", "x-fastmcp-wrap-result": true } ``` --- # wait_for_text Source: https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/ > Wait for NEW output in a tmux pane, then return. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **wait_for_text**( [interval](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Finterval)?: [number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [match_case](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fmatch_case)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fpane_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [patterns](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fpatterns)?: [Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")> | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [regex](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fregex)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [session_id](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fsession_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [stop](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fstop)?: [Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")> | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [timeout](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Ftimeout)?: [number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [window_id](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fwindow_id)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L153)][¶](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text) Wait for NEW output in a tmux pane, then return. Polls until one of `patterns` appears on a line written *after* this call starts, one of `stop` appears (immediate failure exit), or the timeout expires. Pass `patterns=null` to wait for any new output at all. Use this instead of polling [`capture_pane`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/) in a loop. Pre-existing scrollback is never matched, and neither is paint left below the cursor at entry — only rows written after the call began count. If a pattern was already on screen the result says so via `matched_at_entry`. **Last resort: reserve for output you did not author.** Commands you send are AUTHORED — use [`run_command`](https://libtmux.org/en/py/stable/mcp/tools/run_command/) (returns exit status) or compose [`; tmux wait-for -S `](https://libtmux.org/en/tmux/latest/manual/wait-for/) with [`wait_for_channel`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/) instead, both cheaper and exact. For unattributable recurring prompts or background log lines, bracket your own command with a unique sentinel (`cmd; echo __WAIT_$RANDOM__`) and wait for that. `stop` is the cheap way to avoid burning the whole budget: pass the failure markers you already know (`"error:"`, `"FAILED"`, `"Traceback"`) and a failed run returns in milliseconds instead of at the ceiling. The server caps `timeout`. An over-large value is not an error — the wait returns at the ceiling and reports `effective_timeout`. * MCP request method `tools/call` Send `wait_for_text` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.parameters) * **[`interval`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Finterval)**? = `0.05` ([number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Seconds between polls. Default 0.05 (50ms). Minimum 0.01. * **[`match_case`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fmatch_case)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether to match case. Default False (case-insensitive). * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fpane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane ID (e.g. ‘%1’). * **[`patterns`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fpatterns)**? = `null` ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")> | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Success patterns; the first one to match ends the wait. Literal text unless `regex=True`. Omit or pass `null` to wait for any new output. * **[`regex`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fregex)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Interpret `patterns` and `stop` as regular expressions. Default False (literal text). * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session ID (e.g. ‘$1’) for pane resolution. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name for pane resolution. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`stop`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fstop)**? = `null` ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")> | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Failure patterns. A hit ends the wait immediately with `outcome="stopped"` and `found=false`; `matched_index` says which entry fired. * **[`timeout`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Ftimeout)**? = `8` ([number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Requested seconds to wait. Default 8.0. Clamped by server policy; see `effective_timeout` in the result. * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Window ID for pane resolution. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`alternate_screen`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Falternate_screen)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) True when the pane was on the terminal’s alternate screen at any point during the wait. * **[`effective_timeout`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Feffective_timeout)** ([number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Seconds actually enforced. Server policy caps the requested `timeout`; compare against what you passed to see a clamp. * **[`elapsed_seconds`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Felapsed_seconds)** ([number](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Time spent waiting in seconds * **[`found`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Ffound)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) True when a `patterns` entry matched new output, or, with `patterns=null`, when any new output appeared. * **[`matched_at_entry`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Fmatched_at_entry)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) True when `patterns` already matched on-screen text before the wait began and nothing new matched after. The wait holds out for a FRESH occurrence, so re-running a command whose output looks identical still works. Read it as: the text is there, but it predates your call. * **[`matched_index`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Fmatched_index)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Zero-based index into `patterns`, or into `stop` when `outcome` is `stopped`. Null otherwise. * **[`matched_lines`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Fmatched_lines)**? ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")>) Newly-written lines that matched (empty on timeout). * **[`outcome`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Foutcome)** ("matched" | "any_output" | "stopped" | "alternate_screen" | "timeout") How the wait ended. `matched`: a `patterns` entry hit. `any_output`: `patterns` was omitted and something — possibly just a prompt repaint — was written; read it as ‘the pane moved’, never as ‘the command finished’. `stopped`: a `stop` failure marker hit. `alternate_screen`: the pane was under a pager, editor, or full-screen TUI, which repaints the whole grid, so matching was suppressed — read the screen with [snapshot_pane](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/) instead of retrying. `timeout`: nothing matched in the budget. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID that was polled * **[`saw_new_output`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Fsaw_new_output)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) True when content was written on or below the entry cursor row. Read it with `found=false`: true means output arrived and did not match — read `tail` and fix the pattern; false means the pane was quiet — suspect the command never ran, or check `alternate_screen`. * **[`tail`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Ftail)**? ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")>) Rows from the entry cursor row down at the final poll, tail-limited by lines and bytes. Includes stale rows excluded from matching, so it shows what the pane looks like, not what matched. On a timeout this usually already contains the answer — read it before retrying with a different pattern. ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "interval": { "default": 0.05, "description": "Seconds between polls. Default 0.05 (50ms). Minimum 0.01.", "type": "number" }, "match_case": { "default": false, "description": "Whether to match case. Default False (case-insensitive).", "type": "boolean" }, "pane_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane ID (e.g. '%1')." }, "patterns": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Success patterns; the first one to match ends the wait.\nLiteral text unless ``regex=True``. Omit or pass ``null`` to\nwait for any new output." }, "regex": { "default": false, "description": "Interpret ``patterns`` and ``stop`` as regular expressions.\nDefault False (literal text).", "type": "boolean" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session ID (e.g. '$1') for pane resolution." }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Session name for pane resolution." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "stop": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Failure patterns. A hit ends the wait immediately with\n``outcome=\"stopped\"`` and ``found=false``; ``matched_index``\nsays which entry fired." }, "timeout": { "default": 8, "description": "Requested seconds to wait. Default 8.0. Clamped by server\npolicy; see ``effective_timeout`` in the result.", "type": "number" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Window ID for pane resolution." } }, "type": "object" } ``` Output schema ```json { "description": "Result of a bounded wait for new pane output.\n\nDeliberately free of inference. Every field is something the tool\nobserved directly — a match, a clock reading, a tmux flag. There is\nno \"likely cause\", no \"next action\", no quiescence verdict: a\nconfidently-wrong diagnosis costs the agent more than an honest\n\"nothing appeared, here is what the pane shows\".\n\nField count is load-bearing. ``outputSchema`` is re-sent on every\nrequest of every session, so a field that no agent branches on is a\npermanent tax. ``outcome`` carries what three separate booleans\ncarried before it.", "properties": { "alternate_screen": { "default": false, "description": "True when the pane was on the terminal's alternate screen at any point during the wait.", "type": "boolean" }, "effective_timeout": { "description": "Seconds actually enforced. Server policy caps the requested ``timeout``; compare against what you passed to see a clamp.", "type": "number" }, "elapsed_seconds": { "description": "Time spent waiting in seconds", "type": "number" }, "found": { "description": "True when a ``patterns`` entry matched new output, or, with ``patterns=null``, when any new output appeared.", "type": "boolean" }, "matched_at_entry": { "default": false, "description": "True when ``patterns`` already matched on-screen text before the wait began and nothing new matched after. The wait holds out for a FRESH occurrence, so re-running a command whose output looks identical still works. Read it as: the text is there, but it predates your call.", "type": "boolean" }, "matched_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Zero-based index into ``patterns``, or into ``stop`` when ``outcome`` is ``stopped``. Null otherwise." }, "matched_lines": { "description": "Newly-written lines that matched (empty on timeout).", "items": { "type": "string" }, "type": "array" }, "outcome": { "description": "How the wait ended. ``matched``: a ``patterns`` entry hit. ``any_output``: ``patterns`` was omitted and something — possibly just a prompt repaint — was written; read it as 'the pane moved', never as 'the command finished'. ``stopped``: a ``stop`` failure marker hit. ``alternate_screen``: the pane was under a pager, editor, or full-screen TUI, which repaints the whole grid, so matching was suppressed — read the screen with snapshot_pane instead of retrying. ``timeout``: nothing matched in the budget.", "enum": [ "matched", "any_output", "stopped", "alternate_screen", "timeout" ], "type": "string" }, "pane_id": { "description": "Pane ID that was polled", "type": "string" }, "saw_new_output": { "default": false, "description": "True when content was written on or below the entry cursor row. Read it with ``found=false``: true means output arrived and did not match — read ``tail`` and fix the pattern; false means the pane was quiet — suspect the command never ran, or check ``alternate_screen``.", "type": "boolean" }, "tail": { "description": "Rows from the entry cursor row down at the final poll, tail-limited by lines and bytes. Includes stale rows excluded from matching, so it shows what the pane looks like, not what matched. On a timeout this usually already contains the answer — read it before retrying with a different pattern.", "items": { "type": "string" }, "type": "array" } }, "required": [ "found", "outcome", "pane_id", "elapsed_seconds", "effective_timeout" ], "type": "object" } ``` --- # Prompts Source: https://libtmux.org/en/py/stable/mcp/prompts/ > Browse the reusable workflows the server provides through prompts/get. Each prompt documents its arguments and the messages it returns. Browse the reusable workflows the server provides through prompts/get. Each prompt documents its arguments and the messages it returns. MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. The reference configuration advertises 4 prompts. Your server’s available objects depend on its configuration. [Setup documentation](https://libtmux.org/en/py/stable/mcp/guides/) explains how to connect a client. ## Workflows4 prompts[#](https://libtmux.org/en/py/stable/mcp/prompts/#prompts-workflows) [build​_dev​_workspace](https://libtmux.org/en/py/stable/mcp/prompts/build_dev_workspace/) Construct a simple 3-pane development session. [diagnose​_failing​_pane](https://libtmux.org/en/py/stable/mcp/prompts/diagnose_failing_pane/) Gather pane context and propose a root-cause hypothesis. [interrupt​_gracefully](https://libtmux.org/en/py/stable/mcp/prompts/interrupt_gracefully/) Interrupt a running command and verify the prompt returned. [run​_and​_wait](https://libtmux.org/en/py/stable/mcp/prompts/run_and_wait/) Run a shell command in a tmux pane and wait for completion. Reference configuration * `LIBTMUX_TOOLSETS` `inspect,manage,execute,teardown` Protocol version: `2025-11-25`. [Download the full protocol catalog](https://libtmux.org/en/py/stable/mcp/tools.json). Source: [`tmux-python/libtmux-mcp@4daddc0dfca9`](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). The [language API reference](https://libtmux.org/en/py/stable/mcp/reference/) documents embedding and implementation types. Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). --- # build_dev_workspace Source: https://libtmux.org/en/py/stable/mcp/prompts/build_dev_workspace/ > Construct a simple 3-pane development session. prompt MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **build_dev_workspace**( [session_name](https://libtmux.org/en/py/stable/mcp/prompts/build_dev_workspace/#mcp.prompt.build_dev_workspace.parameter.session_name), [log_command](https://libtmux.org/en/py/stable/mcp/prompts/build_dev_workspace/#mcp.prompt.build_dev_workspace.parameter.log_command)?, ) prompt [¶](https://libtmux.org/en/py/stable/mcp/prompts/build_dev_workspace/#mcp.prompt.build_dev_workspace) Construct a simple 3-pane development session. Produces editor (top), terminal (bottom-left), logs (bottom-right) layout — the most common shape for a working session. * MCP request method `prompts/get` Send `build_dev_workspace` as the prompt name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/prompts/build_dev_workspace/#mcp.prompt.build_dev_workspace.parameters) * **[`session_name`](https://libtmux.org/en/py/stable/mcp/prompts/build_dev_workspace/#mcp.prompt.build_dev_workspace.parameter.session_name)** Name for the new session. Provide a value matching the following JSON schema: {“type”:“string”}. Encode non-string values as JSON. * Binding Prompt argument * **[`log_command`](https://libtmux.org/en/py/stable/mcp/prompts/build_dev_workspace/#mcp.prompt.build_dev_workspace.parameter.log_command)**? Command to run in the logs pane. Defaults to an OS-neutral `watch -n 1 date` so the recipe does not assume Linux log paths. Pass e.g. `"tail -f /var/log/syslog"` on Linux or `"log stream --level info"` on macOS. Provide a value matching the following JSON schema: {“type”:“string”}. Encode non-string values as JSON. * Binding Prompt argument ## Result[#](https://libtmux.org/en/py/stable/mcp/prompts/build_dev_workspace/#mcp.prompt.build_dev_workspace.result) Returns the prompt’s messages. The client supplies the advertised arguments as strings. ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/prompts/build_dev_workspace/#mcp.prompt.build_dev_workspace.schemas) Use the complete advertised contract for validation and client integration. Registration ```json { "_meta": { "fastmcp": { "tags": [] } }, "arguments": [ { "description": "Name for the new session.\n\nProvide a value matching the following JSON schema: {\"type\":\"string\"}. Encode non-string values as JSON.", "name": "session_name", "required": true }, { "description": "Command to run in the logs pane. Defaults to an OS-neutral\n``watch -n 1 date`` so the recipe does not assume Linux log\npaths. Pass e.g. ``\"tail -f /var/log/syslog\"`` on Linux or\n``\"log stream --level info\"`` on macOS.\n\nProvide a value matching the following JSON schema: {\"type\":\"string\"}. Encode non-string values as JSON.", "name": "log_command", "required": false } ], "description": "Construct a simple 3-pane development session.\n\nProduces editor (top), terminal (bottom-left), logs (bottom-right)\nlayout — the most common shape for a working session.", "name": "build_dev_workspace" } ``` Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). --- # diagnose_failing_pane Source: https://libtmux.org/en/py/stable/mcp/prompts/diagnose_failing_pane/ > Gather pane context and propose a root-cause hypothesis. prompt MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **diagnose_failing_pane**( [pane_id](https://libtmux.org/en/py/stable/mcp/prompts/diagnose_failing_pane/#mcp.prompt.diagnose_failing_pane.parameter.pane_id), ) prompt [¶](https://libtmux.org/en/py/stable/mcp/prompts/diagnose_failing_pane/#mcp.prompt.diagnose_failing_pane) Gather pane context and propose a root-cause hypothesis. Uses [`snapshot_pane`](https://libtmux.org/en/py/stable/mcp/tools/snapshot_pane/) (content + cursor + mode + scroll state in one call) instead of [`capture_pane`](https://libtmux.org/en/py/stable/mcp/tools/capture_pane/) + [`get_pane_info`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/) so the agent sees everything in a single protocol call. When the diagnosis needs another read after waiting or observing, the rendered recipe points agents at [`capture_since`](https://libtmux.org/en/py/stable/mcp/tools/capture_since/) instead of a repeated full capture. * MCP request method `prompts/get` Send `diagnose_failing_pane` as the prompt name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/prompts/diagnose_failing_pane/#mcp.prompt.diagnose_failing_pane.parameters) * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/prompts/diagnose_failing_pane/#mcp.prompt.diagnose_failing_pane.parameter.pane_id)** The pane to diagnose. Provide a value matching the following JSON schema: {“type”:“string”}. Encode non-string values as JSON. * Binding Prompt argument ## Result[#](https://libtmux.org/en/py/stable/mcp/prompts/diagnose_failing_pane/#mcp.prompt.diagnose_failing_pane.result) Returns the prompt’s messages. The client supplies the advertised arguments as strings. ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/prompts/diagnose_failing_pane/#mcp.prompt.diagnose_failing_pane.schemas) Use the complete advertised contract for validation and client integration. Registration ```json { "_meta": { "fastmcp": { "tags": [] } }, "arguments": [ { "description": "The pane to diagnose.\n\nProvide a value matching the following JSON schema: {\"type\":\"string\"}. Encode non-string values as JSON.", "name": "pane_id", "required": true } ], "description": "Gather pane context and propose a root-cause hypothesis.\n\nUses ``snapshot_pane`` (content + cursor + mode + scroll state\nin one call) instead of ``capture_pane`` + ``get_pane_info`` so\nthe agent sees everything in a single protocol call. When the\ndiagnosis needs another read after waiting or observing, the\nrendered recipe points agents at ``capture_since`` instead of a\nrepeated full capture.", "name": "diagnose_failing_pane" } ``` Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). --- # interrupt_gracefully Source: https://libtmux.org/en/py/stable/mcp/prompts/interrupt_gracefully/ > Interrupt a running command and verify the prompt returned. prompt MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **interrupt_gracefully**( [pane_id](https://libtmux.org/en/py/stable/mcp/prompts/interrupt_gracefully/#mcp.prompt.interrupt_gracefully.parameter.pane_id), ) prompt [¶](https://libtmux.org/en/py/stable/mcp/prompts/interrupt_gracefully/#mcp.prompt.interrupt_gracefully) Interrupt a running command and verify the prompt returned. Sends `C-c` through `send_keys(literal=True)`, then waits on shell-prompt patterns via [`wait_for_text`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_text/). Fails loudly if the process ignores SIGINT — the right escalation point is the caller, not an automatic `C-\` follow-up (SIGQUIT can core-dump). * MCP request method `prompts/get` Send `interrupt_gracefully` as the prompt name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/prompts/interrupt_gracefully/#mcp.prompt.interrupt_gracefully.parameters) * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/prompts/interrupt_gracefully/#mcp.prompt.interrupt_gracefully.parameter.pane_id)** Target pane. Provide a value matching the following JSON schema: {“type”:“string”}. Encode non-string values as JSON. * Binding Prompt argument ## Result[#](https://libtmux.org/en/py/stable/mcp/prompts/interrupt_gracefully/#mcp.prompt.interrupt_gracefully.result) Returns the prompt’s messages. The client supplies the advertised arguments as strings. ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/prompts/interrupt_gracefully/#mcp.prompt.interrupt_gracefully.schemas) Use the complete advertised contract for validation and client integration. Registration ```json { "_meta": { "fastmcp": { "tags": [] } }, "arguments": [ { "description": "Target pane.\n\nProvide a value matching the following JSON schema: {\"type\":\"string\"}. Encode non-string values as JSON.", "name": "pane_id", "required": true } ], "description": "Interrupt a running command and verify the prompt returned.\n\nSends ``C-c`` through ``send_keys(literal=True)``, then waits on\nshell-prompt patterns via ``wait_for_text``. Fails loudly if the\nprocess ignores SIGINT — the right escalation point is the caller,\nnot an automatic ``C-\\`` follow-up (SIGQUIT can core-dump).", "name": "interrupt_gracefully" } ``` Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). --- # run_and_wait Source: https://libtmux.org/en/py/stable/mcp/prompts/run_and_wait/ > Run a shell command in a tmux pane and wait for completion. prompt MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **run_and_wait**( [command](https://libtmux.org/en/py/stable/mcp/prompts/run_and_wait/#mcp.prompt.run_and_wait.parameter.command), [pane_id](https://libtmux.org/en/py/stable/mcp/prompts/run_and_wait/#mcp.prompt.run_and_wait.parameter.pane_id), [timeout](https://libtmux.org/en/py/stable/mcp/prompts/run_and_wait/#mcp.prompt.run_and_wait.parameter.timeout)?, ) prompt [¶](https://libtmux.org/en/py/stable/mcp/prompts/run_and_wait/#mcp.prompt.run_and_wait) Run a shell command in a tmux pane and wait for completion. The returned template teaches the high-level authored-command primitive: [`run_command`](https://libtmux.org/en/py/stable/mcp/tools/run_command/) sends the command, waits through a private tmux signal, captures output, and reports exit status in one typed result. Use lower-level [`send_keys`](https://libtmux.org/en/py/stable/mcp/tools/send_keys/) + [`wait_for_channel`](https://libtmux.org/en/py/stable/mcp/tools/wait_for_channel/) only when the caller needs custom shell composition outside this common command-completion shape. * MCP request method `prompts/get` Send `run_and_wait` as the prompt name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/prompts/run_and_wait/#mcp.prompt.run_and_wait.parameters) * **[`command`](https://libtmux.org/en/py/stable/mcp/prompts/run_and_wait/#mcp.prompt.run_and_wait.parameter.command)** The shell command to run. Provide a value matching the following JSON schema: {“type”:“string”}. Encode non-string values as JSON. * Binding Prompt argument * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/prompts/run_and_wait/#mcp.prompt.run_and_wait.parameter.pane_id)** Target pane (e.g. `%1`). Provide a value matching the following JSON schema: {“type”:“string”}. Encode non-string values as JSON. * Binding Prompt argument * **[`timeout`](https://libtmux.org/en/py/stable/mcp/prompts/run_and_wait/#mcp.prompt.run_and_wait.parameter.timeout)**? Maximum seconds to wait for command completion. Default 60. Provide a value matching the following JSON schema: {“type”:“number”}. Encode non-string values as JSON. * Binding Prompt argument ## Result[#](https://libtmux.org/en/py/stable/mcp/prompts/run_and_wait/#mcp.prompt.run_and_wait.result) Returns the prompt’s messages. The client supplies the advertised arguments as strings. ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/prompts/run_and_wait/#mcp.prompt.run_and_wait.schemas) Use the complete advertised contract for validation and client integration. Registration ```json { "_meta": { "fastmcp": { "tags": [] } }, "arguments": [ { "description": "The shell command to run.\n\nProvide a value matching the following JSON schema: {\"type\":\"string\"}. Encode non-string values as JSON.", "name": "command", "required": true }, { "description": "Target pane (e.g. ``%1``).\n\nProvide a value matching the following JSON schema: {\"type\":\"string\"}. Encode non-string values as JSON.", "name": "pane_id", "required": true }, { "description": "Maximum seconds to wait for command completion. Default 60.\n\nProvide a value matching the following JSON schema: {\"type\":\"number\"}. Encode non-string values as JSON.", "name": "timeout", "required": false } ], "description": "Run a shell command in a tmux pane and wait for completion.\n\nThe returned template teaches the high-level authored-command\nprimitive: ``run_command`` sends the command, waits through a\nprivate tmux signal, captures output, and reports exit status in\none typed result. Use lower-level ``send_keys`` +\n``wait_for_channel`` only when the caller needs custom shell\ncomposition outside this common command-completion shape.", "name": "run_and_wait" } ``` Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). --- # Resources Source: https://libtmux.org/en/py/stable/mcp/resources/ > Browse the data the server exposes through resources/read. Resource templates describe URI patterns and the variables used to select a resource. Browse the data the server exposes through resources/read. Resource templates describe URI patterns and the variables used to select a resource. MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. The reference configuration advertises 6 resources and resource templates. Your server’s available objects depend on its configuration. [Setup documentation](https://libtmux.org/en/py/stable/mcp/guides/) explains how to connect a client. ## Resource templates6 objects[#](https://libtmux.org/en/py/stable/mcp/resources/#resources-resource-templates) [get​_pane](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane/) Get details of a specific pane. [get​_pane​_content](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane_content/) Capture and return the content of a pane. [get​_session](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session/) Get details of a specific tmux session. [get​_session​_windows](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session_windows/) List all windows in a tmux session. [get​_sessions](https://libtmux.org/en/py/stable/mcp/resources/templates/get_sessions/) List all tmux sessions. [get​_window](https://libtmux.org/en/py/stable/mcp/resources/templates/get_window/) Get details of a specific window in a session. Reference configuration * `LIBTMUX_TOOLSETS` `inspect,manage,execute,teardown` Protocol version: `2025-11-25`. [Download the full protocol catalog](https://libtmux.org/en/py/stable/mcp/tools.json). Source: [`tmux-python/libtmux-mcp@4daddc0dfca9`](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). The [language API reference](https://libtmux.org/en/py/stable/mcp/reference/) documents embedding and implementation types. Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). --- # get_pane Source: https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane/ > Get details of a specific pane. resource template MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * `tmux://panes/{pane_id}{?socket_name}` resource template [¶](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane/#mcp.resource-template.tmux%3A%2F%2Fpanes%2F%7Bpane_id%7D%7B%3Fsocket_name%7D) Get details of a specific pane. * MCP request method `resources/read` Send the resource URI shown above. * MIME type `application/json` ## URI parameters[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane/#mcp.resource-template.tmux%3A%2F%2Fpanes%2F%7Bpane_id%7D%7B%3Fsocket_name%7D.parameters) * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane/#mcp.resource-template.tmux%3A%2F%2Fpanes%2F%7Bpane_id%7D%7B%3Fsocket_name%7D.parameter.pane_id)** The pane ID (e.g. ‘%1’). * Binding URI variable * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane/#mcp.resource-template.tmux%3A%2F%2Fpanes%2F%7Bpane_id%7D%7B%3Fsocket_name%7D.parameter.socket_name)** tmux socket name. Defaults to LIBTMUX_SOCKET env var. * Binding Query variable ## Result[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane/#mcp.resource-template.tmux%3A%2F%2Fpanes%2F%7Bpane_id%7D%7B%3Fsocket_name%7D.result) Returns resource contents for the requested URI with MIME type `application/json`. str JSON object of pane details (MIME: `application/json`). ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane/#mcp.resource-template.tmux%3A%2F%2Fpanes%2F%7Bpane_id%7D%7B%3Fsocket_name%7D.schemas) Use the complete advertised contract for validation and client integration. Registration ```json { "_meta": { "fastmcp": { "tags": [] } }, "description": "Get details of a specific pane.\n\nParameters\n----------\npane_id : str\n The pane ID (e.g. '%1').\nsocket_name : str, optional\n tmux socket name. Defaults to LIBTMUX_SOCKET env var.\n\nReturns\n-------\nstr\n JSON object of pane details (MIME: ``application/json``).", "mimeType": "application/json", "name": "get_pane", "title": "Pane Detail", "uriTemplate": "tmux://panes/{pane_id}{?socket_name}" } ``` Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). --- # get_pane_content Source: https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane_content/ > Capture and return the content of a pane. resource template MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * `tmux://panes/{pane_id}/content{?socket_name}` resource template [¶](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane_content/#mcp.resource-template.tmux%3A%2F%2Fpanes%2F%7Bpane_id%7D%2Fcontent%7B%3Fsocket_name%7D) Capture and return the content of a pane. * MCP request method `resources/read` Send the resource URI shown above. * MIME type `text/plain` ## URI parameters[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane_content/#mcp.resource-template.tmux%3A%2F%2Fpanes%2F%7Bpane_id%7D%2Fcontent%7B%3Fsocket_name%7D.parameters) * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane_content/#mcp.resource-template.tmux%3A%2F%2Fpanes%2F%7Bpane_id%7D%2Fcontent%7B%3Fsocket_name%7D.parameter.pane_id)** The pane ID (e.g. ‘%1’). * Binding URI variable * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane_content/#mcp.resource-template.tmux%3A%2F%2Fpanes%2F%7Bpane_id%7D%2Fcontent%7B%3Fsocket_name%7D.parameter.socket_name)** tmux socket name. Defaults to LIBTMUX_SOCKET env var. * Binding Query variable ## Result[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane_content/#mcp.resource-template.tmux%3A%2F%2Fpanes%2F%7Bpane_id%7D%2Fcontent%7B%3Fsocket_name%7D.result) Returns resource contents for the requested URI with MIME type `text/plain`. str Plain text captured pane content (MIME: `text/plain`). ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_pane_content/#mcp.resource-template.tmux%3A%2F%2Fpanes%2F%7Bpane_id%7D%2Fcontent%7B%3Fsocket_name%7D.schemas) Use the complete advertised contract for validation and client integration. Registration ```json { "_meta": { "fastmcp": { "tags": [] } }, "description": "Capture and return the content of a pane.\n\nParameters\n----------\npane_id : str\n The pane ID (e.g. '%1').\nsocket_name : str, optional\n tmux socket name. Defaults to LIBTMUX_SOCKET env var.\n\nReturns\n-------\nstr\n Plain text captured pane content (MIME: ``text/plain``).", "mimeType": "text/plain", "name": "get_pane_content", "title": "Pane Content", "uriTemplate": "tmux://panes/{pane_id}/content{?socket_name}" } ``` Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). --- # get_session Source: https://libtmux.org/en/py/stable/mcp/resources/templates/get_session/ > Get details of a specific tmux session. resource template MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * `tmux://sessions/{session_name}{?socket_name}` resource template [¶](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%7B%3Fsocket_name%7D) Get details of a specific tmux session. * MCP request method `resources/read` Send the resource URI shown above. * MIME type `application/json` ## URI parameters[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%7B%3Fsocket_name%7D.parameters) * **[`session_name`](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%7B%3Fsocket_name%7D.parameter.session_name)** The session name. * Binding URI variable * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%7B%3Fsocket_name%7D.parameter.socket_name)** tmux socket name. Defaults to LIBTMUX_SOCKET env var. * Binding Query variable ## Result[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%7B%3Fsocket_name%7D.result) Returns resource contents for the requested URI with MIME type `application/json`. str JSON object with session info and its windows (MIME: `application/json`). ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%7B%3Fsocket_name%7D.schemas) Use the complete advertised contract for validation and client integration. Registration ```json { "_meta": { "fastmcp": { "tags": [] } }, "description": "Get details of a specific tmux session.\n\nParameters\n----------\nsession_name : str\n The session name.\nsocket_name : str, optional\n tmux socket name. Defaults to LIBTMUX_SOCKET env var.\n\nReturns\n-------\nstr\n JSON object with session info and its windows\n (MIME: ``application/json``).", "mimeType": "application/json", "name": "get_session", "title": "Session Detail", "uriTemplate": "tmux://sessions/{session_name}{?socket_name}" } ``` Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). --- # get_session_windows Source: https://libtmux.org/en/py/stable/mcp/resources/templates/get_session_windows/ > List all windows in a tmux session. resource template MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * `tmux://sessions/{session_name}/windows{?socket_name}` resource template [¶](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session_windows/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%7B%3Fsocket_name%7D) List all windows in a tmux session. * MCP request method `resources/read` Send the resource URI shown above. * MIME type `application/json` ## URI parameters[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session_windows/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%7B%3Fsocket_name%7D.parameters) * **[`session_name`](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session_windows/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%7B%3Fsocket_name%7D.parameter.session_name)** The session name. * Binding URI variable * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session_windows/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%7B%3Fsocket_name%7D.parameter.socket_name)** tmux socket name. Defaults to LIBTMUX_SOCKET env var. * Binding Query variable ## Result[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session_windows/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%7B%3Fsocket_name%7D.result) Returns resource contents for the requested URI with MIME type `application/json`. str JSON array of window objects (MIME: `application/json`). ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_session_windows/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%7B%3Fsocket_name%7D.schemas) Use the complete advertised contract for validation and client integration. Registration ```json { "_meta": { "fastmcp": { "tags": [] } }, "description": "List all windows in a tmux session.\n\nParameters\n----------\nsession_name : str\n The session name.\nsocket_name : str, optional\n tmux socket name. Defaults to LIBTMUX_SOCKET env var.\n\nReturns\n-------\nstr\n JSON array of window objects (MIME: ``application/json``).", "mimeType": "application/json", "name": "get_session_windows", "title": "Session Windows", "uriTemplate": "tmux://sessions/{session_name}/windows{?socket_name}" } ``` Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). --- # get_sessions Source: https://libtmux.org/en/py/stable/mcp/resources/templates/get_sessions/ > List all tmux sessions. resource template MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * `tmux://sessions{?socket_name}` resource template [¶](https://libtmux.org/en/py/stable/mcp/resources/templates/get_sessions/#mcp.resource-template.tmux%3A%2F%2Fsessions%7B%3Fsocket_name%7D) List all tmux sessions. * MCP request method `resources/read` Send the resource URI shown above. * MIME type `application/json` ## URI parameters[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_sessions/#mcp.resource-template.tmux%3A%2F%2Fsessions%7B%3Fsocket_name%7D.parameters) * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/resources/templates/get_sessions/#mcp.resource-template.tmux%3A%2F%2Fsessions%7B%3Fsocket_name%7D.parameter.socket_name)** tmux socket name. Defaults to LIBTMUX_SOCKET env var. * Binding Query variable ## Result[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_sessions/#mcp.resource-template.tmux%3A%2F%2Fsessions%7B%3Fsocket_name%7D.result) Returns resource contents for the requested URI with MIME type `application/json`. str JSON array of session objects (MIME: `application/json`). ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_sessions/#mcp.resource-template.tmux%3A%2F%2Fsessions%7B%3Fsocket_name%7D.schemas) Use the complete advertised contract for validation and client integration. Registration ```json { "_meta": { "fastmcp": { "tags": [] } }, "description": "List all tmux sessions.\n\nParameters\n----------\nsocket_name : str, optional\n tmux socket name. Defaults to LIBTMUX_SOCKET env var.\n\nReturns\n-------\nstr\n JSON array of session objects (MIME: ``application/json``).", "mimeType": "application/json", "name": "get_sessions", "title": "All Sessions", "uriTemplate": "tmux://sessions{?socket_name}" } ``` Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760). --- # get_window Source: https://libtmux.org/en/py/stable/mcp/resources/templates/get_window/ > Get details of a specific window in a session. resource template MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * `tmux://sessions/{session_name}/windows/{window_index}{?socket_name}` resource template [¶](https://libtmux.org/en/py/stable/mcp/resources/templates/get_window/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%2F%7Bwindow_index%7D%7B%3Fsocket_name%7D) Get details of a specific window in a session. * MCP request method `resources/read` Send the resource URI shown above. * MIME type `application/json` ## URI parameters[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_window/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%2F%7Bwindow_index%7D%7B%3Fsocket_name%7D.parameters) * **[`session_name`](https://libtmux.org/en/py/stable/mcp/resources/templates/get_window/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%2F%7Bwindow_index%7D%7B%3Fsocket_name%7D.parameter.session_name)** The session name. * Binding URI variable * **[`window_index`](https://libtmux.org/en/py/stable/mcp/resources/templates/get_window/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%2F%7Bwindow_index%7D%7B%3Fsocket_name%7D.parameter.window_index)** The window index within the session. * Binding URI variable * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/resources/templates/get_window/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%2F%7Bwindow_index%7D%7B%3Fsocket_name%7D.parameter.socket_name)** tmux socket name. Defaults to LIBTMUX_SOCKET env var. * Binding Query variable ## Result[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_window/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%2F%7Bwindow_index%7D%7B%3Fsocket_name%7D.result) Returns resource contents for the requested URI with MIME type `application/json`. str JSON object with window info and its panes (MIME: `application/json`). ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/resources/templates/get_window/#mcp.resource-template.tmux%3A%2F%2Fsessions%2F%7Bsession_name%7D%2Fwindows%2F%7Bwindow_index%7D%7B%3Fsocket_name%7D.schemas) Use the complete advertised contract for validation and client integration. Registration ```json { "_meta": { "fastmcp": { "tags": [] } }, "description": "Get details of a specific window in a session.\n\nParameters\n----------\nsession_name : str\n The session name.\nwindow_index : str\n The window index within the session.\nsocket_name : str, optional\n tmux socket name. Defaults to LIBTMUX_SOCKET env var.\n\nReturns\n-------\nstr\n JSON object with window info and its panes\n (MIME: ``application/json``).", "mimeType": "application/json", "name": "get_window", "title": "Window Detail", "uriTemplate": "tmux://sessions/{session_name}/windows/{window_index}{?socket_name}" } ``` Source revision: [tmux-python/libtmux-mcp@4daddc0dfca96c43bf521d818bf91564e1434760](https://github.com/tmux-python/libtmux-mcp/tree/4daddc0dfca96c43bf521d818bf91564e1434760).