# libtmux for TypeScript > The TypeScript library (libtmux). These pages include its guides, tested examples and API documentation. - [TypeScript API reference](https://libtmux.org/en/ts/latest/reference/): every public symbol, generated from the source. Hosted on libtmux.org. --- # Load a workspace Source: https://libtmux.org/en/ts/latest/workspace/cli/load/ > Create or reuse a session from a workspace file, with explicit attachment and output choices. **Workspace Manager concept example** A working example of the core library. It can change without notice. Load a saved configuration into tmux. Use `-d` for scripts so the command returns after construction without attaching a terminal. Command delivery does not mean the programs running in those panes have finished or become ready. ## Load without attaching Continue the [installation walkthrough](https://libtmux.org/en/ts/latest/workspace/guides/installation/) with its [`workspace.yaml`](https://libtmux.org/en/ts/latest/workspace/guides/installation/#create-the-input) and private socket: ```console $ tmux-workspace load \ -S "$WORKSPACE_TMP/tmux.sock" \ -f /dev/null \ -d \ --json \ workspace.yaml ``` `-S` selects the socket path; `-L` selects a socket name. `-f` supplies tmux's configuration when starting a server. Keep the same endpoint for later capture, inspection and cleanup. Pass `-s another-name` to override the final input's session name. ## Existing sessions and append A session with the requested name is reused. Loading is not a reconciliation operation that removes extra windows. Inspect a failed result before retrying: earlier inputs and changes to a borrowed session can remain. Inside tmux, `--append` adds windows to the invoking pane's session. It needs valid `TMUX` and `TMUX_PANE` values for the selected daemon. Use `-d` when loading onto a different server. Multiple inputs are processed in their supplied order. ## Attachment and output Human loading can attach a terminal or switch a tmux client. For automation, choose `-d` or an authenticated append explicitly; machine output does not answer interactive questions. `--yes` accepts supported confirmations. `--json` returns a result; `--ndjson` emits records as work proceeds. Read [output](https://libtmux.org/en/ts/latest/workspace/reference/output/) and [errors](https://libtmux.org/en/ts/latest/workspace/reference/exit-codes/) before consuming those records. `--no-progress` disables the terminal display; it does not disable errors. `-2` requests 256-color handling from tmux. Use [configuration](https://libtmux.org/en/ts/latest/workspace/configuration/) for fields and [hooks](https://libtmux.org/en/ts/latest/workspace/configuration/hooks/) for bootstrap scripts and extensions. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Capture a workspace Source: https://libtmux.org/en/ts/latest/workspace/cli/freeze/ > Capture a running tmux session as a starting point for a workspace file. **Workspace Manager concept example** A working example of the core library. It can change without notice. Capture a running tmux session as a starting point for a workspace file. Capture reads live state. It cannot recover original command arguments, command history, script definitions or plugin intent. ## Inspect a session After the [installation walkthrough](https://libtmux.org/en/ts/latest/workspace/guides/installation/) creates `workspace-guide`, request a machine result from its private socket: ```console $ tmux-workspace freeze \ -S "$WORKSPACE_TMP/tmux.sock" \ --json \ workspace-guide ``` ## Save the captured document Name the destination and format explicitly: ```console $ tmux-workspace freeze \ -S "$WORKSPACE_TMP/tmux.sock" \ --json \ --workspace-format yaml \ --save-to captured-workspace.yaml \ workspace-guide ``` Use a new destination, or pass `--force` to authorize replacement. Review captured commands and directories before loading the file on another machine. The saved document encoding is separate from the CLI result format selected by `--json` or `--ndjson`. See [export and reload](https://libtmux.org/en/ts/latest/workspace/guides/export-session/) for the complete workflow. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Convert workspace files Source: https://libtmux.org/en/ts/latest/workspace/cli/convert/ > Convert a complete workspace document between YAML and JSON. **Workspace Manager concept example** A working example of the core library. It can change without notice. Convert a complete workspace document between YAML and JSON. Conversion preserves mapping fields; it does not establish that every field can be loaded. ## Inspect the result Start with [`workspace.yaml`](https://libtmux.org/en/ts/latest/workspace/guides/installation/#create-the-input) from the [installation walkthrough](https://libtmux.org/en/ts/latest/workspace/guides/installation/): ```console $ tmux-workspace convert --json workspace.yaml ``` Without a destination, machine mode returns the converted document in its result. YAML comments and textual formatting do not survive conversion to JSON. ## Save a file Choose an explicit destination and encoding: ```console $ tmux-workspace convert \ --json \ --workspace-format json \ --save-to workspace.json \ workspace.yaml ``` Replacing an existing destination requires `--force`. Keep that choice separate from `--yes`, which answers prompts. Review the result before [loading it](https://libtmux.org/en/ts/latest/workspace/cli/load/). [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Edit a workspace Source: https://libtmux.org/en/ts/latest/workspace/cli/edit/ > Resolve a workspace file or saved name and open it in an editor. **Workspace Manager concept example** A working example of the core library. It can change without notice. Resolve a workspace file or saved name and open it in an editor. Use an explicit path when editing a particular file. ## Open the file With `vi` installed and [`workspace.yaml`](https://libtmux.org/en/ts/latest/workspace/guides/installation/#create-the-input) saved: ```console $ EDITOR=vi tmux-workspace edit workspace.yaml ``` The CLI waits for the editor and reports a failed child through its exit status. Editor values can contain quoted arguments. They are parsed as an argument list; shell pipelines and redirection require an explicit shell or wrapper. [Discovery](https://libtmux.org/en/ts/latest/workspace/guides/discovery/) explains saved workspace names. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Inspect runtime diagnostics Source: https://libtmux.org/en/ts/latest/workspace/cli/debug-info/ > Collect the workspace CLI runtime, configuration and tmux diagnostics.. **Workspace Manager concept example** A working example of the core library. It can change without notice. Collect the workspace CLI runtime, configuration and tmux diagnostics. ## Collect a report ```console $ tmux-workspace debug-info --json ``` Review the report before sharing it. Paths, session names and raw tmux values can describe your environment even when home-directory prefixes are redacted. Use the failed command exit status and stderr to diagnose its actual failure. See [troubleshooting](https://libtmux.org/en/ts/latest/workspace/guides/troubleshooting/) and the [machine output reference](https://libtmux.org/en/ts/latest/workspace/reference/output/). [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # List saved workspaces Source: https://libtmux.org/en/ts/latest/workspace/cli/ls/ > List the workspace files found in project and global configuration locations. **Workspace Manager concept example** A working example of the core library. It can change without notice. List the workspace files found in project and global configuration locations. Listing does not load sessions or run pane commands. ## List records ```console $ tmux-workspace ls --json ``` Include each document configuration: ```console $ tmux-workspace ls --full --json ``` For a human display grouped by directory, use `--tree`: ```console $ tmux-workspace ls --tree ``` Machine output preserves record values and has its own structure; do not parse the human tree. See [discovery](https://libtmux.org/en/ts/latest/workspace/guides/discovery/) for the locations searched and [output](https://libtmux.org/en/ts/latest/workspace/reference/output/) for the result format. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Search workspaces Source: https://libtmux.org/en/ts/latest/workspace/cli/search/ > Search the fields of discovered workspace documents. **Workspace Manager concept example** A working example of the core library. It can change without notice. Search the fields of discovered workspace documents. Use literal matching when the input should be treated as text rather than a regular expression. ## Find a session name ```console $ tmux-workspace search \ --json \ --fixed-strings \ --field session \ workspace ``` Repeat `--field` to restrict additional fields. Query terms combine with AND; `--any` selects OR. `--ignore-case`, `--smart-case`, `--word-regexp`, and `--invert-match` control matching. Inspect the installed `search --help` for supported field names and aliases. Check both the exit status and [machine result](https://libtmux.org/en/ts/latest/workspace/reference/output/). An empty successful search and a failed pattern are different outcomes. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Evaluate in a workspace Source: https://libtmux.org/en/ts/latest/workspace/cli/shell/ > Use the optional Python runtime to inspect a workspace through the native command. **Workspace Manager concept example** A working example of the core library. It can change without notice. `tmux-workspace shell` opens the optional Python inspection environment for a loaded session. Code passed to `-c` executes in that environment, with tmux objects such as [`server`](), [`session`](), [`window`]() and [`pane`]() available. ## Runtime requirement Install tmuxp 1.74.0 in a separate Python environment and set `TMUX_WORKSPACE_PYTHON` to that environment's Python executable. The native CLI checks the runtime before evaluating code. Ordinary workspace loading does not require this inspection runtime. ## Evaluate with a selected server Continue the [installation walkthrough](https://libtmux.org/en/ts/latest/workspace/guides/installation/) through its detached load. Select its socket, session and window: ```console $ tmux-workspace shell \ -S "$WORKSPACE_TMP/tmux.sock" \ -c 'print(pane.pane_id)' \ --json \ workspace-guide editor ``` The result includes captured output and child status. Check the command's exit status before consuming it. An interactive shell needs a terminal; use `-c` when stdout belongs to automation. `shell --help` lists backend and startup choices. Optional shell backends must be installed in the selected Python environment. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Import a workspace Source: https://libtmux.org/en/ts/latest/workspace/cli/import/ > Choose a source format and translate it into a workspace document. **Workspace Manager concept example** A working example of the core library. It can change without notice. Translate a saved Teamocil or tmuxinator configuration into a native workspace document. Import reads and translates the file without creating tmux sessions or running its pane commands. - [Teamocil](https://libtmux.org/en/ts/latest/workspace/cli/import-teamocil/) translates a session with named windows and panes. - [tmuxinator](https://libtmux.org/en/ts/latest/workspace/cli/import-tmuxinator/) translates a project with ordered windows. ```console $ tmux-workspace import --help ``` Select a child command and an explicit source path. Preview with `--json` before choosing `--save-to`. An existing destination requires `--force`. Review commands, directories and layout in the translated document before loading it. Source features the importer cannot preserve fail visibly. Use [convert](https://libtmux.org/en/ts/latest/workspace/cli/convert/) to change YAML/JSON encoding without translating fields. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Import from Teamocil Source: https://libtmux.org/en/ts/latest/workspace/cli/import-teamocil/ > Translate Teamocil windows and pane commands into a workspace document. **Workspace Manager concept example** A working example of the core library. It can change without notice. Import a Teamocil file without starting tmux. Save this source as `teamocil.yaml`: ```yaml title="teamocil.yaml" session: name: imported-team windows: - name: editor layout: even-horizontal panes: - commands: [printf ready] - commands: [printf second] ``` ## Preview the translation ```console $ tmux-workspace import teamocil --json ./teamocil.yaml ``` The translated document preserves window and pane order. Several commands in one Teamocil [`commands`]() list become one semicolon-separated shell input in that pane. Review the absolute working directories selected by the import. ## Save the workspace ```console $ tmux-workspace import teamocil \ --json \ --workspace-format yaml \ --save-to imported-teamocil.yaml \ ./teamocil.yaml ``` Use `--force` only to replace an existing destination deliberately. Unsupported fields, such as pane widths and filters, fail before saving. Conversion does not prove that a command or directory will be available when you [load](https://libtmux.org/en/ts/latest/workspace/cli/load/) the result. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Import from tmuxinator Source: https://libtmux.org/en/ts/latest/workspace/cli/import-tmuxinator/ > Translate a tmuxinator project into a workspace document. **Workspace Manager concept example** A working example of the core library. It can change without notice. Import a saved tmuxinator project without starting tmux. Save this source as `tmuxinator.yaml`: ```yaml title="tmuxinator.yaml" name: imported-project windows: - editor: - printf ready - printf second ``` ## Preview the translation ```console $ tmux-workspace import tmuxinator --json ./tmuxinator.yaml ``` The window's command list remains sequential commands in one pane. Use an explicit source `panes` list when the project needs separate panes. ## Save the workspace ```console $ tmux-workspace import tmuxinator \ --json \ --workspace-format yaml \ --save-to imported-tmuxinator.yaml \ ./tmuxinator.yaml ``` Existing destinations require `--force`. The importer rejects unexpanded ERB templates and unsupported lifecycle or runtime fields before writing. It does not evaluate Ruby. Review the translated commands and absolute directories before [loading](https://libtmux.org/en/ts/latest/workspace/cli/load/) the file. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # tmux-workspace CLI manual Source: https://libtmux.org/en/ts/latest/workspace/cli/ > Use `tmux-workspace` to load, inspect and save workspace files. **Workspace Manager concept example** A working example of the core library. It can change without notice. Use `tmux-workspace` to load, inspect and save workspace files. Complete [installation](https://libtmux.org/en/ts/latest/workspace/guides/installation/) and put the executable on `PATH` before using these commands. ## Sessions
load
Create a session from a workspace file.
freeze
Capture a running session into a workspace document.
## Workspace files
ls
List saved configurations.
search
Find saved configurations.
edit
Open a configuration in your editor.
convert
Change a document between YAML and JSON.
import
Translate Teamocil or tmuxinator configuration.
## Diagnostics and completion
debug-info
Report runtime and tmux information.
completion
Generate completion for your shell.
## Command options Show the options accepted by the installed command: ```console $ tmux-workspace load --help ``` ## Machine output `--json` requests one JSON result. `--ndjson` requests a stream of records and takes precedence when both are present. Select detached loading with `-d` when automating session creation. Check the exit status as well as the result; a failed load can leave completed tmux operations in place. The [output reference](https://libtmux.org/en/ts/latest/workspace/reference/output/) describes the result records, and [automation](https://libtmux.org/en/ts/latest/workspace/guides/automation/) covers scripts. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Shell completion Source: https://libtmux.org/en/ts/latest/workspace/cli/completion/ > Generate completion for the installed workspace command. **Workspace Manager concept example** A working example of the core library. It can change without notice. Generate completion using the installed `tmux-workspace` command. The script matches that executable's command definitions. ## Enable Bash completion ```console $ tmux-workspace completion bash > tmux-workspace.bash ``` Check the generated script before loading it in your current Bash session: ```console $ bash -n tmux-workspace.bash ``` ```bash source ./tmux-workspace.bash ``` Keep the script in your shell's completion directory to load it in later sessions. Regenerate it after upgrading the CLI. ## Other shells `completion zsh` and `completion fish` generate the other supported shells. Follow the selected shell's completion setup before sourcing its script. Generating a script does not start tmux or load workspace files. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Concepts Source: https://libtmux.org/en/ts/latest/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/ts/latest/concepts/server-session-window-pane/): Understand the tmux object hierarchy and attached clients. - [Control mode vs one-shot](https://libtmux.org/en/ts/latest/concepts/transports/): Choose subprocess commands, persistent connections, and batching. - [Filtering and queries](https://libtmux.org/en/ts/latest/concepts/queries/): Find objects and handle absent or ambiguous matches. - [Workspaces](https://libtmux.org/en/ts/latest/concepts/workspaces/): Build pane layouts from code or configuration files. --- # Server, session, window, pane Source: https://libtmux.org/en/ts/latest/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: ```typescript for (const session of await server.sessions()) { console.log(session.name); for (const window of session.windows) { console.log(" ", window.index, window.name); for (const pane of window.panes) { console.log(" ", pane.id, pane.currentCommand); } } } ``` ## 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/ts/latest/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/ts/latest/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 Commands use a subprocess by default. [`pipeline()`]() and [`batch()`]() group operations. [`connect()`]() and [`watch()`]() keep a connection for notifications; ordinary commands still use separate processes. Choose based on whether you need command results, notifications, or a batch of changes. ## Notifications and commands are separable TypeScript's [`connect()`]() adds an event observer while commands such as [`session.newWindow(...)`]() and [`pane.sendKeys(...)`]() continue to run as separate tmux processes. A dedicated process provides a completion boundary for output from alias-expanded or waiting commands. ## 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. ## 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. [`batch()`]() resolves planned mutations from one final snapshot. ## 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. ```typescript import { Server } from "libtmux"; // Each awaited command uses a tmux subprocess. const server = new Server(); const session = await server.newSession({ name: "work" }); const editor = await session.newWindow({ name: "editor" }); await editor.panes.at(0)?.sendKeys("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/ts/latest/concepts/queries/ > Match names, handle missing and ambiguous results, traverse linked windows, refresh snapshots, and validate saved TypeScript queries. Read a snapshot once, then query its sessions, windows, panes, and clients in TypeScript. [`Selection.where()`](https://libtmux.org/en/ts/latest/reference/selection-selection-where/) filters that captured state without another tmux command. Use [`one()`](https://libtmux.org/en/ts/latest/reference/selection-selection-one/) when the next operation requires exactly one target. ## Setup and run These are independent programs with imports, assertions, and cleanup. Each creates a private tmux server, runs `cat` in its panes to keep them alive, and stops its server before exiting. They require Bun 1.4.2 or newer, tmux 3.3a or newer, and a Unix environment. You do not need an existing tmux session. In an empty directory, save this file as `package.json`: ```json title="package.json" {"type":"module","dependencies":{"libtmux":"file:./libtmux/packages/libtmux"}} ``` Install the library revision used to run the examples: ```console $ git clone https://github.com/libtmux/libtmux-ts libtmux && git -C libtmux checkout 3fe1ca654b81b8cbf4a13b777a001a3298c87a6f && bun install ``` Save any program below in that directory and run its command. Each program includes its own setup; none depends on another example's variables or server. A failed assertion or cleanup exits with an error. If cleanup fails, the error names the retained directory so the private server remains reachable. ## Match names and combine conditions A bare value means equality. Matching is case sensitive unless that field's criterion has `mode: "insensitive"`. Fields in one object and successive [`.where()`]() calls combine with AND; `AND`, `OR`, and `NOT` compose whole criteria. [`.filter()`]() accepts a JavaScript predicate when a condition needs application code, such as membership in an existing [`Set`](). | Task | Criterion for `name` | | --- | --- | | Equal | `"app-api"` or `{ equals: "app-api" }` | | Contain text | `{ contains: "api" }` | | Start or end with text | `{ startsWith: "app-" }`, `{ endsWith: "worker" }` | | Ignore case | `{ contains: "MYAPP", mode: "insensitive" }` | | Be in a list | `{ in: ["app-api", "app-worker"] }` | | Be outside a list | `{ notIn: ["shell"] }` | | Match a pattern | `{ regex: { pattern: "^app-v[0-9]+-0$", flags: "" } }` | Save as `matching.ts`. It selects exact names, composes conditions, and compares structured criteria with a local predicate. ```typescript title="matching.ts" import assert from "node:assert/strict"; import { mkdtemp, readdir, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { Server } from "libtmux"; const directory = await mkdtemp(join(tmpdir(), "libtmux-query-")); const server = new Server({ socketPath: join(directory, "tmux.sock"), configFile: "/dev/null", timeoutMs: 5_000, }); const failures: unknown[] = []; try { const session = await server.newSession({ name: "work", windowName: "shell", shellCommand: "cat", }); for (const name of ["app-api", "app-worker", "MyApp-logs", "app-v1-0", "app-beta"]) { await session.newWindow({ name, shellCommand: "cat" }); } const { windows } = await server.snapshot(); const exact = windows.where({ name: "app-api" }); assert.equal(exact.one().name, "app-api"); console.log("exact:", exact.one().name); const worker = windows.where({ name: { startsWith: "app-" } }) .where({ name: { endsWith: "worker" } }); assert.equal(worker.one().name, "app-worker"); console.log("prefix AND suffix:", worker.one().name); const apiOrLogs = windows.where({ OR: [{ name: "app-api" }, { name: { contains: "logs" } }], NOT: [{ name: "shell" }], }).map((window) => window.name).sort(); assert.deepEqual(apiOrLogs, ["MyApp-logs", "app-api"]); console.log("OR and NOT:", apiOrLogs.join(", ")); const insensitive = windows.where({ name: { contains: "MYAPP", mode: "insensitive" }, }); assert.equal(insensitive.one().name, "MyApp-logs"); console.log("case insensitive:", insensitive.one().name); const versioned = windows.where({ name: { regex: { pattern: "^app-v[0-9]+-0$", flags: "" } }, }); assert.equal(versioned.one().name, "app-v1-0"); console.log("regex:", versioned.one().name); const selected = windows.where({ name: { in: ["app-api", "app-worker"] } }); assert.equal(selected.count(), 2); assert.equal(selected.where({ name: { notIn: ["app-worker"] } }).one().name, "app-api"); console.log("membership:", selected.map((window) => window.name).sort().join(", ")); const namesFromConfig = new Set(["shell", "app-beta"]); const local = windows.filter((window) => namesFromConfig.has(window.name)); assert.equal(local.count(), 2); console.log("predicate:", local.map((window) => window.name).sort().join(", ")); } catch (error) { failures.push(error); } finally { try { if ((await readdir(directory)).includes("tmux.sock")) await server.kill(); await rm(directory, { recursive: true }); } catch (error) { failures.push(new Error(`Cleanup failed; inspect ${directory}`, { cause: error })); } } if (failures.length > 0) throw new AggregateError(failures, "Query example failed"); ``` ```console $ bun run matching.ts ``` The output identifies `app-api`, `app-worker`, and `"MyApp-logs"`; the version pattern selects `app-v1-0`. Membership selects two application windows, while the predicate selects `app-beta` and `shell`. ### Regular expression limits Structured regex criteria use a restricted grammar. This revision accepts at most 512 UTF-16 code units and one repetition operator. A repeated pattern must start with `^`, cannot repeat a group, and cannot combine repetition with alternation or multiline mode. It rejects lookarounds, backreferences, and escapes such as `\d`; use `[0-9]` for digits. Accepted flags are `""`, `"m"`, `"s"`, and `"ms"`; use the field's `mode: "insensitive"` for case folding. A syntactically valid JavaScript pattern can therefore raise [`QueryValidationError`](https://libtmux.org/en/ts/latest/reference/errors-queryvalidationerror/) here. The saved-query example below checks that rejection. For a trusted pattern that needs the full JavaScript grammar, use a predicate with a [`RegExp`](); that predicate is local code and cannot be encoded as a query document. ## Handle zero, one, and several matches Choose the result contract before using a target: | Operation | Zero matches | One match | Several matches | | --- | --- | --- | --- | | [`.where()`]() | Empty selection | Selection | Selection | | [`.one()`]() | [`NoMatchError`]() | Object | [`MultipleMatchesError`]() | | [`.oneOrUndefined()`]() | [`undefined`]() | Object | [`MultipleMatchesError`]() | | [`.first()`]() | [`undefined`]() | Object | First object in tmux order | | [`.exists()`]() | `false` | `true` | `true` | | `.count()` | `0` | `1` | Match count | Use [`.first()`]() when any first result is acceptable. It does not establish that there is only one target. [`.oneOrUndefined()`]() relaxes only the missing case; it still reports ambiguity. Save as `single-result.ts`. This handles missing and ambiguous results separately and rethrows unexpected failures. ```typescript title="single-result.ts" import assert from "node:assert/strict"; import { mkdtemp, readdir, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { Server, MultipleMatchesError, NoMatchError } from "libtmux"; const directory = await mkdtemp(join(tmpdir(), "libtmux-query-")); const server = new Server({ socketPath: join(directory, "tmux.sock"), configFile: "/dev/null", timeoutMs: 5_000, }); const failures: unknown[] = []; try { const session = await server.newSession({ name: "work", windowName: "editor", shellCommand: "cat", }); await session.newWindow({ name: "logs", shellCommand: "cat" }); const { windows } = await server.snapshot(); assert.equal(windows.one({ name: "logs" }).name, "logs"); assert.equal(windows.oneOrUndefined({ name: "missing" }), undefined); assert.equal(windows.exists({ name: "missing" }), false); console.log("optional missing:", windows.oneOrUndefined({ name: "missing" })); try { windows.one({ name: "missing" }); throw new Error("Expected the missing lookup to fail"); } catch (error) { if (!(error instanceof NoMatchError)) throw error; console.log("missing:", error.code); } for (const lookup of [() => windows.one(), () => windows.oneOrUndefined()]) { try { lookup(); throw new Error("Expected the ambiguous lookup to fail"); } catch (error) { if (!(error instanceof MultipleMatchesError)) throw error; assert.equal(error.count, 2); console.log("ambiguous:", error.code, error.count); } } assert.equal(windows.first()?.name, "editor"); console.log("first:", windows.first()?.name); } catch (error) { failures.push(error); } finally { try { if ((await readdir(directory)).includes("tmux.sock")) await server.kill(); await rm(directory, { recursive: true }); } catch (error) { failures.push(new Error(`Cleanup failed; inspect ${directory}`, { cause: error })); } } if (failures.length > 0) throw new AggregateError(failures, "Query example failed"); ``` ```console $ bun run single-result.ts ``` The program prints [`undefined`]() for an optional missing window, [`NoMatchError`]() for a required missing window, and `MultipleMatchesError 2` for both ambiguous lookups. [`first()`]() returns `editor` because it occupies the first window index. ## Query relations and linked windows A server-wide window selection contains placements: a window linked into two sessions appears twice with the same window ID. A pane reached through those placements also has session context. Add a [`session`]() criterion when the action needs a particular placement. Use [`linkedSessions`](https://libtmux.org/en/ts/latest/reference/window-window-linkedsessions/) to inspect the sessions holding the window. Collection relations accept `some`, `every`, and `none`. `every` and `none` are true for an empty collection; combine `some: {}` with `every` when you require at least one related object. Single-object relations use `is` and `isNot`; `is: null` matches an absent relation. Save as `relations.ts`. It links one logs window into a second session, selects its home placement, and queries sessions and panes through their relations. ```typescript title="relations.ts" import assert from "node:assert/strict"; import { mkdtemp, readdir, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { Server, MultipleMatchesError } from "libtmux"; const directory = await mkdtemp(join(tmpdir(), "libtmux-query-")); const server = new Server({ socketPath: join(directory, "tmux.sock"), configFile: "/dev/null", timeoutMs: 5_000, }); const failures: unknown[] = []; try { const home = await server.newSession({ name: "home", windowName: "logs", shellCommand: "cat", }); const guest = await server.newSession({ name: "guest", windowName: "shell", shellCommand: "cat", }); const shared = home.windows.one({ name: "logs" }); await shared.link({ session: guest }); const snapshot = await server.snapshot(); const placements = snapshot.windows.where({ id: shared.id }); assert.equal(placements.count(), 2); console.log("placements:", placements.count()); try { placements.one(); throw new Error("Expected two placements to be ambiguous"); } catch (error) { if (!(error instanceof MultipleMatchesError)) throw error; console.log("same ID:", error.code); } const atHome = placements.one({ session: { is: { name: "home" } } }); assert.equal(atHome.session?.name, "home"); const owners = atHome.linkedSessions.map((session) => session.name).sort(); assert.deepEqual(owners, ["guest", "home"]); console.log("linked sessions:", owners.join(", ")); const hasLogs = snapshot.sessions.where({ windows: { some: { name: "logs" } } }); assert.equal(hasLogs.count(), 2); const onlyLogs = snapshot.sessions.where({ windows: { some: {}, every: { name: "logs" } }, }); assert.equal(onlyLogs.one().name, "home"); const noShell = snapshot.sessions.where({ windows: { none: { name: "shell" } } }); assert.equal(noShell.one().name, "home"); console.log("some logs:", hasLogs.map((session) => session.name).sort().join(", ")); console.log("every window is logs:", onlyLogs.one().name); console.log("no shell:", noShell.one().name); const guestPanes = snapshot.panes.where({ session: { is: { name: "guest" } } }); assert.equal(guestPanes.count(), 2); console.log("panes reached through guest:", guestPanes.count()); } catch (error) { failures.push(error); } finally { try { if ((await readdir(directory)).includes("tmux.sock")) await server.kill(); await rm(directory, { recursive: true }); } catch (error) { failures.push(new Error(`Cleanup failed; inspect ${directory}`, { cause: error })); } } if (failures.length > 0) throw new AggregateError(failures, "Query example failed"); ``` ```console $ bun run relations.ts ``` The logs window has two placements and two linked sessions. Both sessions have some logs window. Only `home` has every window named `logs` and no window named `shell`. The guest session contains two panes through its two windows. These relations come from the same snapshot. Traversing them does not refresh the server. A scalar window mutation such as `rename()` affects that window in every session that links it; selecting a placement does not create a copy. ## Refresh after a mutation [`Server.snapshot()`](https://libtmux.org/en/ts/latest/reference/server-server-snapshot/) acquires the state. Filtering and reading relations use it locally. A handle can issue a mutation, but its captured fields and earlier selections keep their old values. Acquire another snapshot to observe the result. Save as `refresh.ts`. It creates a window after a snapshot, then renames it and compares old and fresh reads. ```typescript title="refresh.ts" import assert from "node:assert/strict"; import { mkdtemp, readdir, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { Server } from "libtmux"; const directory = await mkdtemp(join(tmpdir(), "libtmux-query-")); const server = new Server({ socketPath: join(directory, "tmux.sock"), configFile: "/dev/null", timeoutMs: 5_000, }); const failures: unknown[] = []; try { const session = await server.newSession({ name: "work", windowName: "editor", shellCommand: "cat", }); const before = await server.snapshot(); await session.newWindow({ name: "logs", shellCommand: "cat" }); assert.equal(before.windows.exists({ name: "logs" }), false); console.log("old snapshot sees logs:", before.windows.exists({ name: "logs" })); const after = await server.snapshot(); assert.equal(after.windows.exists({ name: "logs" }), true); console.log("fresh snapshot sees logs:", after.windows.exists({ name: "logs" })); const logs = after.windows.one({ name: "logs" }); await logs.rename("archive"); assert.equal(logs.name, "logs"); assert.equal(after.windows.one({ id: logs.id }).name, "logs"); console.log("captured name after rename:", logs.name); const renamed = await server.snapshot(); assert.equal(renamed.windows.one({ id: logs.id }).name, "archive"); console.log("refreshed name:", renamed.windows.one({ id: logs.id }).name); } catch (error) { failures.push(error); } finally { try { if ((await readdir(directory)).includes("tmux.sock")) await server.kill(); await rm(directory, { recursive: true }); } catch (error) { failures.push(new Error(`Cleanup failed; inspect ${directory}`, { cause: error })); } } if (failures.length > 0) throw new AggregateError(failures, "Query example failed"); ``` ```console $ bun run refresh.ts ``` The old snapshot reports no logs window. The fresh one finds it. After the rename, the existing handle still reports `logs`; another snapshot reports `archive` for the same ID. Prefer one snapshot when several queries should describe the same captured state. Calling [`server.sessions()`](), [`server.windows()`](), and [`server.panes()`]() separately takes a separate snapshot for each call. A snapshot also cannot prevent another process from removing a target before a later mutation; handle that command's error at the mutation boundary. ## Save and validate criteria [`encodeWhereDocument()`](https://libtmux.org/en/ts/latest/reference/selection-encodewheredocument/) serializes a versioned query. Parse its JSON and pass the value to [`decodeWhereDocument()`](https://libtmux.org/en/ts/latest/reference/selection-decodewheredocument/) before applying it. Check the document's model so session criteria go to the session selection. Use the encoder and decoder to preserve the wire format; do not cast unvalidated JSON to a criteria type. Save as `query-document.ts`. It round-trips a session query, rejects an unknown field, and catches a regex outside the supported grammar. ```typescript title="query-document.ts" import assert from "node:assert/strict"; import { mkdtemp, readdir, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { Server, decodeWhereDocument, encodeWhereDocument, QueryValidationError, } from "libtmux"; const directory = await mkdtemp(join(tmpdir(), "libtmux-query-")); const server = new Server({ socketPath: join(directory, "tmux.sock"), configFile: "/dev/null", timeoutMs: 5_000, }); const failures: unknown[] = []; try { await server.newSession({ name: "prod-api", shellCommand: "cat" }); await server.newSession({ name: "dev-api", shellCommand: "cat" }); const encoded = encodeWhereDocument({ version: 1, model: "session", where: { name: { startsWith: "prod-" } }, }); const document = decodeWhereDocument(JSON.parse(encoded)); assert.equal(document.model, "session"); if (document.model !== "session") throw new Error("Expected session criteria"); const snapshot = await server.snapshot(); const selected = snapshot.sessions.where(document.where); assert.equal(selected.one().name, "prod-api"); console.log("decoded query:", selected.one().name); console.log("wire JSON:", encoded); try { decodeWhereDocument({ version: 1, model: "session", where: { session_naem: "prod-api" } }); throw new Error("Expected an unknown field to fail validation"); } catch (error) { if (!(error instanceof QueryValidationError)) throw error; assert.equal(error.reason, "invalid-query"); console.log("invalid document:", error.code, error.reason); } try { snapshot.sessions.where({ name: { regex: { pattern: "^prod-[a-z]+-[0-9]+$", flags: "" } }, }); throw new Error("Expected multiple repetitions to fail validation"); } catch (error) { if (!(error instanceof QueryValidationError)) throw error; console.log("unsupported regex:", error.code); } } catch (error) { failures.push(error); } finally { try { if ((await readdir(directory)).includes("tmux.sock")) await server.kill(); await rm(directory, { recursive: true }); } catch (error) { failures.push(new Error(`Cleanup failed; inspect ${directory}`, { cause: error })); } } if (failures.length > 0) throw new AggregateError(failures, "Query example failed"); ``` ```console $ bun run query-document.ts ``` The decoded query selects `prod-api`. Both invalid inputs raise [`QueryValidationError`](). Its `reason` distinguishes invalid IDs from invalid criteria; `path` identifies the failing field or nested condition. A valid criterion can still name a field introduced after the running tmux version. That raises [`VersionTooLowError`](https://libtmux.org/en/ts/latest/reference/errors-versiontoolowerror/), which carries [`criteriaName`](), [`serverVersion`](), and [`since`](). Treat a version error as an unsupported query, not as evidence that no objects match. ## Filter a live tmux listing Use snapshot selections when you need typed handles, relations, several local queries, or JavaScript predicates. To request only matching rows from tmux, call [`Server.cmd()`]() with a list command's `-f` option. This returns output lines; it does not return a [`Selection`]() or apply the TypeScript criteria grammar. Save as `tmux-filter.ts`. It lists production sessions with a tmux glob, then shows why an unknown format token can look like a valid empty result. ```typescript title="tmux-filter.ts" import assert from "node:assert/strict"; import { mkdtemp, readdir, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { Server } from "libtmux"; const directory = await mkdtemp(join(tmpdir(), "libtmux-query-")); const server = new Server({ socketPath: join(directory, "tmux.sock"), configFile: "/dev/null", timeoutMs: 5_000, }); const failures: unknown[] = []; try { await server.newSession({ name: "prod-api", shellCommand: "cat" }); await server.newSession({ name: "dev-api", shellCommand: "cat" }); const expression = "#{m:prod-*,#{session_name}}"; const names = await server.cmd("list-sessions", [ "-f", expression, "-F", "#{session_name}", ]); assert.deepEqual(names, ["prod-api"]); console.log("tmux matches:", names.join(", ")); const unknown = "#{session_naem}"; const empty = await server.cmd("list-sessions", [ "-f", unknown, "-F", "#{session_name}", ]); assert.deepEqual(empty, []); console.log("unknown token matches:", empty.length); const expansion = await server.cmd("display-message", [ "-p", "-t", "=prod-api:", expression, ]); assert.deepEqual(expansion, ["1"]); const badExpansion = await server.cmd("display-message", [ "-p", "-t", "=prod-api:", `value=<${unknown}>`, ]); assert.deepEqual(badExpansion, ["value=<>"]); console.log("valid expression:", expansion[0]); console.log("unknown token:", badExpansion[0]); } catch (error) { failures.push(error); } finally { try { if ((await readdir(directory)).includes("tmux.sock")) await server.kill(); await rm(directory, { recursive: true }); } catch (error) { failures.push(new Error(`Cleanup failed; inspect ${directory}`, { cause: error })); } } if (failures.length > 0) throw new AggregateError(failures, "Query example failed"); ``` ```console $ bun run tmux-filter.ts ``` The glob returns `prod-api`. The misspelled `session_naem` returns zero rows without a command error. Expanding the valid expression prints `1`; expanding the unknown token between delimiters prints `value=<>`. When a live filter unexpectedly returns nothing, first run the same listing without `-f` to confirm the objects exist. Expand the expression with [`display-message -p`](https://libtmux.org/en/tmux/latest/manual/display-message/) against a known target, and check its token names against the running tmux version's manual. Keep each command argument separate as above; these strings go to tmux without shell interpolation. ## API and related tasks - [`Selection`](https://libtmux.org/en/ts/latest/reference/selection-selection/) defines iteration, criteria, predicates, counts, and exactly-one lookup. - [`Server`](https://libtmux.org/en/ts/latest/reference/server-server/) owns snapshot acquisition and command execution. - [Traversal](https://libtmux.org/en/ts/latest/topics/traversal/) explains object relationships and identity. - [Sending keys](https://libtmux.org/en/ts/latest/guides/sending-keys/) uses a selected pane as an input target. - [Capturing output](https://libtmux.org/en/ts/latest/guides/capturing-output/) reads a selected pane's screen. --- # Workspaces Source: https://libtmux.org/en/ts/latest/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: 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/ts/latest/concepts/transports/) covers their transport costs and batching. ## Building one declaratively These packages read or build workspace configurations based on tmuxp: `@libtmux/workspace` applies a workspace configuration through [`applyWorkspace`](). Pass the server and a configuration containing [`session_name`](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/) and `windows`. TypeScript's [`applyWorkspace`]() applies a desired configuration. Applying the same configuration again reuses its existing objects: ```ts await applyWorkspace(server, { session_name: "api", windows: [ { window_name: "editor", panes: ["vim", "git status"] }, { window_name: "server", panes: [{ shell_command: "bun dev", focus: true }] }, ], }); ``` ## Cleaning up See [Context managers](https://libtmux.org/en/ts/latest/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/ts/latest/workspace/configuration/ > Define the session, windows, panes and commands loaded by the workspace CLI. **Workspace Manager concept example** A working example of the core library. It can change without notice. A workspace document describes one tmux session. Save this as `configuration.yaml`: ```yaml title="configuration.yaml" session_name: configuration-example windows: - window_name: editor layout: even-horizontal panes: - printf ready - null ``` Load it on the private socket from the [installation walkthrough](https://libtmux.org/en/ts/latest/workspace/guides/installation/): ```console $ tmux-workspace load \ -S "$WORKSPACE_TMP/tmux.sock" \ -d \ --json \ configuration.yaml ``` The CLI parses the document and validates its execution fields before creating windows and sending commands. YAML and JSON use the same field names. A successful load means construction and command delivery completed; pane applications can still be starting or failing independently. ## Choose the fields for your task - [Session](https://libtmux.org/en/ts/latest/workspace/configuration/session/) sets the name, shared options and environment. - [Windows](https://libtmux.org/en/ts/latest/workspace/configuration/windows/) sets indexes, layouts and option timing. - [Panes](https://libtmux.org/en/ts/latest/workspace/configuration/panes/) defines commands, launch shells and focus. - [Commands](https://libtmux.org/en/ts/latest/workspace/configuration/commands/) controls ordering, Enter and delays. - [Environment](https://libtmux.org/en/ts/latest/workspace/configuration/environment/) separates loader settings from pane variables. - [Directories](https://libtmux.org/en/ts/latest/workspace/configuration/directories/) explains discovery and working directories. - [Layouts](https://libtmux.org/en/ts/latest/workspace/configuration/layouts/) arranges the panes. - [Hooks](https://libtmux.org/en/ts/latest/workspace/configuration/hooks/) runs checked bootstrap programs and optional extensions. ## CLI and application code These pages describe the `tmux-workspace` executable. Application code uses the separate [workspace library](https://libtmux.org/en/ts/latest/workspace/internals/), whose accepted fields and build semantics have their own contract. A successful generic [conversion](https://libtmux.org/en/ts/latest/workspace/cli/convert/) preserves document values; it does not validate that a loader can execute them. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Session configuration Source: https://libtmux.org/en/ts/latest/workspace/configuration/session/ > Name a workspace and apply session options and environment. **Workspace Manager concept example** A working example of the core library. It can change without notice. Set [`session_name`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-session-name) and an ordered, nonempty [`windows`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-windows) list. Use a simple name without tmux target separators such as `:` and `.`. ```yaml title="session.yaml" session_name: session-example environment: PROJECT_MODE: development options: status: false windows: - window_name: shell panes: [null] ``` ## Session fields | Field | Effect | | --- | --- | | `session_name` | Session to create or reuse | | `windows` | Windows to construct in order | | `start_directory` | Starting directory inherited by child configuration | | `environment` | Variables supplied to the workspace | | `options` | Options applied to this session | | `global_options` | Options applied globally on the selected tmux server | | `shell_command_before` | Commands prepended to each pane's commands | | `suppress_history` | History policy inherited by windows and panes | | `before_script` | Checked bootstrap process | | `workspace_builder_options` | Builder settings such as prompt readiness | Use [`global_options`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-global-options) only when every session on that server should share the change. Select a private socket for examples and automated jobs. An existing session is reused under the loader's policy. Use [`load -s NAME`](https://libtmux.org/en/ts/latest/workspace/cli/load/) when a second copy needs another name. Loading does not remove unrelated sessions or reconcile away extra windows. Read [environment](https://libtmux.org/en/ts/latest/workspace/configuration/environment/), [commands](https://libtmux.org/en/ts/latest/workspace/configuration/commands/) and [hooks](https://libtmux.org/en/ts/latest/workspace/configuration/hooks/) for the behavior behind those fields. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Window configuration Source: https://libtmux.org/en/ts/latest/workspace/configuration/windows/ > Set window names, indexes, layouts, options and focus. **Workspace Manager concept example** A working example of the core library. It can change without notice. Each item in [`windows`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-windows) creates one window with its own ordered pane list. Set [`window_index`](https://libtmux.org/en/tmux/latest/catalog/formats/window_index/) when the tmux index matters independently of list position. ```yaml title="windows.yaml" session_name: windows-example windows: - window_name: tools window_index: 2 layout: even-horizontal focus: true options: automatic-rename: false options_after: synchronize-panes: true panes: - printf left - printf right ``` [`options`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-options) applies during construction. `options_after` applies after initial pane commands, which is useful for enabling synchronized typing after each pane has received its own setup. Later input in a synchronized pane can reach the other panes in that window. ## Launch settings [`start_directory`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-start-directory) supplies a directory for panes that do not override it. `window_shell` supplies their launch command; a pane's `shell` overrides it. Set [`environment`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-environment) for a window-wide launch map and read [environment inheritance](https://libtmux.org/en/ts/latest/workspace/configuration/environment/) before overriding it per pane. Use distinct explicit indexes. `focus: true` selects the window after building. An explicit [layout](https://libtmux.org/en/ts/latest/workspace/configuration/layouts/) makes the intended arrangement clear across terminal sizes. [Pane configuration](https://libtmux.org/en/ts/latest/workspace/configuration/panes/) controls each pane's contents. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Pane configuration Source: https://libtmux.org/en/ts/latest/workspace/configuration/panes/ > Choose pane commands, launch settings and focus. **Workspace Manager concept example** A working example of the core library. It can change without notice. Each entry in a window's `panes` list describes one pane. A string is a command; [`null`]() leaves a blank shell pane. A mapping provides launch and command settings. ```yaml title="panes.yaml" session_name: panes-example windows: - window_name: work layout: even-horizontal panes: - null - shell: /bin/sh focus: true shell_command: - printf ready - printf second ``` The second pane launches `/bin/sh`, receives both commands in order and becomes the active pane. A command list inside one pane does not create extra panes. ## Overrides - [`start_directory`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-start-directory) overrides the inherited working directory. - `shell` overrides the window's launch command. - [`environment`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-environment) supplies the pane's launch environment map. - [`shell_command_before`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-shell-command-before) adds setup after session and window setup. - [`enter`](), `sleep_before` and `sleep_after` supply command defaults. - [`suppress_history`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-suppress-history) overrides the inherited history policy. Set focus explicitly when automation depends on which pane is selected. Use returned pane IDs for later operations instead of assuming that creation order is a stable tmux ID. Read [commands](https://libtmux.org/en/ts/latest/workspace/configuration/commands/) for Enter and delay behavior and [environment](https://libtmux.org/en/ts/latest/workspace/configuration/environment/) for variable handling. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Workspace commands Source: https://libtmux.org/en/ts/latest/workspace/configuration/commands/ > Order pane setup and command delivery, Enter handling and delays. **Workspace Manager concept example** A working example of the core library. It can change without notice. [`shell_command_before`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-shell-command-before) adds setup for every affected pane. Setup is ordered from session to window to pane, followed by that pane's `shell_command` entries. ```yaml title="commands.yaml" session_name: commands-example shell_command_before: - printf session-setup windows: - window_name: shell shell_command_before: - printf window-setup panes: - shell_command_before: - printf pane-setup shell_command: - cmd: printf ready sleep_after: 0.01 - cmd: printf waiting enter: false sleep_after: 0 ``` The final command is typed without Enter. Delays are measured in seconds and pause delivery; they do not verify that an application is ready or that an earlier shell command succeeded. ## Enter and timing Pane-level [`enter`](), `sleep_before` and `sleep_after` establish defaults. Command mappings can change those defaults. An override carries to following commands in that pane until another override. Set an explicit value when later commands need to restore Enter or remove a delay. ## History and readiness History suppression prefixes sent commands with a space. The shell still needs its own setting to ignore leading-space commands, such as Bash's `HISTCONTROL=ignorespace` or zsh's `HIST_IGNORE_SPACE`. Prompt readiness delays initial input while a shell draws its prompt. It is separate from application readiness and command completion. Use a checked [before script](https://libtmux.org/en/ts/latest/workspace/configuration/hooks/) for bootstrap work whose exit status must stop the load on failure. See [environment](https://libtmux.org/en/ts/latest/workspace/configuration/environment/) before putting variable expressions in commands. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Workspace environment Source: https://libtmux.org/en/ts/latest/workspace/configuration/environment/ > Configure the loader process and the variables available to pane commands. **Workspace Manager concept example** A working example of the core library. It can change without notice. The CLI's process environment controls discovery and optional runtimes. Configuration [`environment`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-environment) maps provide variables to the workspace's shells. ```yaml title="environment.yaml" session_name: environment-example environment: DOC_SESSION: session windows: - window_name: shell environment: DOC_WINDOW: window panes: - environment: DOC_PANE: pane shell_command: 'printf "ENV=%s|%s|%s\n" "$DOC_SESSION" "$DOC_WINDOW" "$DOC_PANE"' - shell_command: 'printf "ENV=%s|%s|%s\n" "$DOC_SESSION" "$DOC_WINDOW" "$DOC_PANE"' ``` A pane map selects its launch environment in place of the window map. Session variables still apply. Repeat a window variable in the pane map when that pane needs it too. Avoid putting credentials in example files or diagnostic output. ## Variable expressions The loader expands defined variables in configuration values before delivery. An expression can therefore use the invoking process's value before the pane shell reads it. Use explicit configuration variables and inspect resulting commands when moving a workspace between environments. ## Loader settings | Variable | Use | | --- | --- | | `TMUXP_CONFIGDIR` | Preferred existing directory for saved workspaces | | `XDG_CONFIG_HOME` | Base for the `tmuxp` configuration directory | | `EDITOR` | Editor used by [`edit`](https://libtmux.org/en/ts/latest/workspace/cli/edit/) | | `TMUX_WORKSPACE_PYTHON` | Optional interpreter for `shell` and supported extensions | | `NO_COLOR` | Disable terminal color when nonempty | These are process settings, not workspace YAML keys. Read [discovery](https://libtmux.org/en/ts/latest/workspace/guides/discovery/), [editing](https://libtmux.org/en/ts/latest/workspace/cli/edit/) and [shell inspection](https://libtmux.org/en/ts/latest/workspace/cli/shell/) for their task-specific behavior. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Files and directories Source: https://libtmux.org/en/ts/latest/workspace/configuration/directories/ > Resolve saved workspace files and the working directories used by panes. **Workspace Manager concept example** A working example of the core library. It can change without notice. Use an explicit file path when debugging workspace discovery. A directory such as `.` selects a project configuration; a saved name selects a global workspace. See [finding workspaces](https://libtmux.org/en/ts/latest/workspace/guides/discovery/) for that lookup order. ## Set a starting directory ```yaml title="directories.yaml" session_name: directories-example start_directory: ./ windows: - window_name: shell start_directory: ./ panes: - start_directory: ./ shell_command: pwd ``` An explicit relative session directory starts from the configuration file's directory. Child directories resolve through their parent configuration. Use absolute paths when a workspace deliberately points outside its project. Quote home shortcuts in YAML, such as `"~/src/project"`; an unquoted `~` is a null value. An omitted directory lets the loader and tmux use their invocation context. The explicit relative directory in this example selects the file's project context. ## Verify the running pane A saved path can be absent on another machine. Inspect the real pane directory after loading rather than relying on successful YAML parsing. tmux can fall back to a home directory when a requested path does not exist. Bootstrap paths and process working directories have separate rules. See [before scripts](https://libtmux.org/en/ts/latest/workspace/configuration/hooks/) before using one to create directories. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Window layouts Source: https://libtmux.org/en/ts/latest/workspace/configuration/layouts/ > Arrange panes with tmux layout names or a saved layout. **Workspace Manager concept example** A working example of the core library. It can change without notice. Choose a layout for each window. `even-horizontal` gives panes equal widths: ```yaml title="layouts.yaml" session_name: layouts-example windows: - window_name: work layout: even-horizontal panes: [null, null, null] ``` Other common tmux names include `even-vertical`, `main-horizontal`, `main-vertical` and `tiled`. Full names avoid version-dependent abbreviation ambiguity. Available names follow the selected tmux daemon. ## Saved layouts and terminal size A captured layout describes pane geometry. Loading validates its syntax and pane capacity, then tmux applies it to the actual window size. Resizing can change the final dimensions. Use a named layout when exact saved geometry is unnecessary. Set window and pane `focus` explicitly when the active target matters. Layout arrangement and active-pane selection are different settings. [Capture](https://libtmux.org/en/ts/latest/workspace/cli/freeze/) can save a running layout; inspect it before [reloading](https://libtmux.org/en/ts/latest/workspace/guides/export-session/) on a smaller terminal. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Bootstrap scripts and extensions Source: https://libtmux.org/en/ts/latest/workspace/configuration/hooks/ > Run a checked bootstrap process before workspace commands. **Workspace Manager concept example** A working example of the core library. It can change without notice. Use [`before_script`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-before-script) when setup must finish successfully before configured windows are built. The command is split into an executable and arguments; shell operators require an explicit shell. ```yaml title="hooks.yaml" session_name: hooks-example before_script: /bin/sh -c 'printf bootstrap-ready' windows: - window_name: shell panes: [null] ``` The CLI checks the child process status. A failure stops that workspace's build. The result describes retained effects; an earlier input or borrowed session can still exist. A pane's `shell_command` only sends input and does not provide this process-status guarantee. ## Paths and output A relative script path beginning with `.` is resolved from the workspace file. The script's working directory uses the configured session directory when present, otherwise the invocation directory. The script runs before workspace pane commands. Reusing an existing session does not replay its bootstrap. Machine output captures or streams child output through the CLI protocol. Read [output](https://libtmux.org/en/ts/latest/workspace/reference/output/) before parsing bootstrap records. ## Prompt readiness The `pane_readiness` setting under [`workspace_builder_options`](https://libtmux.org/en/ts/latest/workspace/configuration/session/#session-fields-workspace-builder-options) accepts `auto`, `always` or [`never`](). It controls a bounded wait before initial pane input. It does not wait for a server process to accept connections. Commands can still be delivered when the prompt wait expires. ## Optional extensions Nonempty `plugins` or `workspace_builder` values select the optional Python extension runtime. Set `TMUX_WORKSPACE_PYTHON` to an interpreter with a compatible tmuxp 1.74 installation. Ordinary documents use the native builder. Extensions run executable code and can make changes outside the CLI's own tracked operations. Inspect reported effects and errors before retrying them. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # tmux client library for TypeScript Source: https://libtmux.org/en/ts/latest/core/ > tmux client library for TypeScript. Control tmux, connect to and create servers, navigate sessions, windows, and panes, send keys, watch for changes via control mode, capture pane contents Control tmux, connect to and create servers, navigate sessions, windows, and panes, send keys, watch for changes via control mode, capture pane contents. ## At a glance | Type | Wraps | | ---- | ----- | | [`server.Server`](https://libtmux.org/en/ts/latest/reference/server-server/) | A tmux server | | [`session.Session`](https://libtmux.org/en/ts/latest/reference/session-session/) | A session, ID `$n` | | [`window.Window`](https://libtmux.org/en/ts/latest/reference/window-window/) | A window in a session, ID `@n` | | [`pane.Pane`](https://libtmux.org/en/ts/latest/reference/pane-pane/) | A pane in a window, ID `%n` | ## Typed API - Typed objects instead of parsed format strings: [`pane.Pane`](https://libtmux.org/en/ts/latest/reference/pane-pane/) - Addressing by tmux ID: [`common.PaneId`](https://libtmux.org/en/ts/latest/reference/common-paneid/) - Filtering and queries over tmux objects: [`selection.Selection.where`](https://libtmux.org/en/ts/latest/reference/selection-selection-where/) - Typed errors instead of exit codes and stderr: [`errors.LibTmuxError`](https://libtmux.org/en/ts/latest/reference/errors-libtmuxerror/) ## What you get over the tmux CLI - Connect to or start a tmux server: [`server.Server`](https://libtmux.org/en/ts/latest/reference/server-server/) - Traversal from a server down to its panes: [`server.Server.panes`](https://libtmux.org/en/ts/latest/reference/server-server-panes/) - Send keys to a pane: [`pane.Pane.sendKeys`](https://libtmux.org/en/ts/latest/reference/pane-pane-sendkeys/) - Watch for changes through tmux control mode: [`server.Server.watch`](https://libtmux.org/en/ts/latest/reference/server-server-watch/) - Capture pane contents: [`pane.Pane.capture`](https://libtmux.org/en/ts/latest/reference/pane-pane-capture/) - Arguments passed as a list, with no shell quoting: [`server.Server.cmd`](https://libtmux.org/en/ts/latest/reference/server-server-cmd/) - A typed error when the running tmux lacks a feature: [`errors.VersionTooLowError`](https://libtmux.org/en/ts/latest/reference/errors-versiontoolowerror/) - Async operations: [`server.Server.newSession`](https://libtmux.org/en/ts/latest/reference/server-server-newsession/) - [Quickstart](https://libtmux.org/en/ts/latest/guides/getting-started/): Install the package and run a complete program. - [Guides](https://libtmux.org/en/ts/latest/guides/): Task guides for TypeScript. - [Topics](https://libtmux.org/en/ts/latest/topics/): Subject-by-subject, with TypeScript in every code block. - [Examples](https://libtmux.org/en/ts/latest/examples/): Complete programs, sourced from the code each port tests. - [API reference](https://libtmux.org/en/ts/latest/reference/): Types and functions of the TypeScript API. - [Testing](https://libtmux.org/en/ts/latest/guides/testing-with-libtmux/): Test code that uses tmux with an isolated server. --- # Examples Source: https://libtmux.org/en/ts/latest/workspace/examples/ > Workspace configurations and complete command walkthroughs. **Workspace Manager concept example** A working example of the core library. It can change without notice. These examples use the workspace command. For programs using the builder library, read the [internal API examples](https://libtmux.org/en/ts/latest/workspace/internals/examples/). - [Workspace gallery](https://libtmux.org/en/ts/latest/workspace/examples/gallery/): Configurations for pane layouts, commands and environment, with prerequisites. - [Load a workspace](https://libtmux.org/en/ts/latest/workspace/guides/installation/): Run the installation and loading walkthrough on a private socket. - [Capture and reload](https://libtmux.org/en/ts/latest/workspace/guides/export-session/): Export a live session and use the result as a workspace. --- # Examples Source: https://libtmux.org/en/ts/latest/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: [`scripts/check-doc-runnable.ts`]() checks that a block tagged with its example source matches that file line for line. The integration suite executes the source program. See [Testing with libtmux](https://libtmux.org/en/ts/latest/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/ts/latest/examples/attach-and-send-keys/): Find a session, send a command, and read its output. - [Capture pane output](https://libtmux.org/en/ts/latest/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/ts/latest/examples/workspace-from-file/): Create a session, windows, and panes from configuration. --- # Attach and send keys Source: https://libtmux.org/en/ts/latest/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/ts/latest/guides/attaching-to-tmux/). The examples include setup, error handling, and cleanup. [Source and verification](https://libtmux.org/en/ts/latest/examples/attach-and-send-keys/#where-this-comes-from) identifies their files and checks. ```typescript file="examples/quickstart/quickstart.ts" import { Server, TmuxCommandError, type ServerSnapshot } from "libtmux"; /** * A runnable tour of the API, driven by the tests so it cannot rot. * * Every step here appears in README.md. */ export async function quickstart(server: Server): Promise { // Nothing is read until you ask. `snapshot()` is the only step that talks to // tmux; everything reachable from it resolves locally. const session = await server.newSession({ name: "quickstart" }); const editor = await session.newWindow({ name: "editor" }); await editor.split(); const snapshot = await server.snapshot(); // Declarative filtering, serializable and stable on the wire. const found = snapshot.windows.where({ name: "editor" }).one(); // Relations are plain properties: no await, no tmux command. const paneCount = found.panes.length; if (paneCount !== 2) throw new Error(`expected two panes, saw ${String(paneCount)}`); // A criterion is spelled like the handle accessor it filters. if (snapshot.panes.count({ currentCommand: { contains: "" } }) === 0) { throw new Error("expected panes to report a current command"); } const first = found.panes.at(0); if (first === undefined) throw new Error("expected a pane"); await first.sendKeys("echo hello-from-libtmux", { literal: true }); // Failures carry their parts rather than a formatted sentence. try { await server.setOption("not-a-real-option", "1"); } catch (error) { if (!(error instanceof TmuxCommandError)) throw error; if (error.args[0] !== "set-option") throw error; } return snapshot; } ``` ## 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/ts/latest/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/ts/latest/guides/querying-and-filtering/) covers absent and ambiguous matches. ## Where this comes from **Source:** [`examples/quickstart/quickstart.ts`]() **In this page:** read whole from the file **Checked by:** run against real tmux by `bun test examples`; its first half is also mirrored into README.md under a `` marker, checked line-for-line by [`scripts/check-doc-runnable.ts`]() ### 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/ts/latest/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/ts/latest/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. ```typescript title="capture.ts" import { mkdtemp, readdir, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { setTimeout as delay } from "node:timers/promises"; import { Server } from "libtmux"; const directory = await mkdtemp(join(tmpdir(), "libtmux-capture-")); const server = new Server({ socketPath: join(directory, "tmux.sock"), configFile: "/dev/null", timeoutMs: 5_000, }); const failures: unknown[] = []; try { const signal = AbortSignal.timeout(5_000); const session = await server.newSession({ name: "capture", shellCommand: "sh", signal, environment: { ENV: "/dev/null" }, }); const pane = session.activePane; if (!pane) throw new Error("The session has no active pane"); await pane.sendKeys("printf '\\nlibtmux capture ready\\n'", { signal }); for (;;) { const lines = await pane.capture({ signal }); const line = lines.find((line) => line === "libtmux capture ready"); if (line !== undefined) { console.log(line); break; } await delay(20, undefined, { signal }); } } catch (error) { failures.push(error); } finally { try { if ((await readdir(directory)).includes("tmux.sock")) await server.kill(); await rm(directory, { recursive: true }); } catch (error) { failures.push(new Error( `Cleanup failed; inspect ${directory}`, { cause: error }, )); } } if (failures.length > 0) throw new AggregateError(failures, "Capture failed"); ``` Cleanup checks the private socket even if startup fails. If stopping tmux fails, the error reports the retained directory so the server remains reachable. ## 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/ts/latest/guides/capturing-output/) covers capture options, while [Sending keys](https://libtmux.org/en/ts/latest/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.ts` and this file as [`package.json`](). Use Bun 1.4.2 or newer. ```json title="package.json" {"type":"module","dependencies":{"libtmux":"file:./libtmux/packages/libtmux"}} ``` ```console $ git clone https://github.com/libtmux/libtmux-ts libtmux && git -C libtmux checkout 3fe1ca654b81b8cbf4a13b777a001a3298c87a6f && bun install && bun run capture.ts ``` ## 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/ts/latest/workspace/examples/gallery/ > Start from complete configurations for pane layout, commands and environment. **Workspace Manager concept example** A working example of the core library. It can change without notice. Each configuration below is a complete workspace document. Save it to a file and load it on the private socket from the [installation walkthrough](https://libtmux.org/en/ts/latest/workspace/guides/installation/). ## Two blank panes ```yaml title="gallery-blank.yaml" session_name: gallery-blank windows: - window_name: work layout: even-horizontal panes: [null, null] ``` Blank panes open their shells without application-specific prerequisites. Change the [layout](https://libtmux.org/en/ts/latest/workspace/configuration/layouts/) to arrange them vertically. ## Setup before pane commands ```yaml title="gallery-commands.yaml" session_name: gallery-commands shell_command_before: - printf setup windows: - window_name: shell panes: - shell_command: - printf first - printf second ``` Both commands run in one pane after its inherited setup. Read [command ordering](https://libtmux.org/en/ts/latest/workspace/configuration/commands/) before adding delays or commands that should remain unsubmitted. ## More complete examples - [Session options and environment](https://libtmux.org/en/ts/latest/workspace/configuration/session/). - [Explicit window index and synchronized input](https://libtmux.org/en/ts/latest/workspace/configuration/windows/). - [Pane launch shell and focus](https://libtmux.org/en/ts/latest/workspace/configuration/panes/). - [Inherited directories](https://libtmux.org/en/ts/latest/workspace/configuration/directories/). - [Environment overrides](https://libtmux.org/en/ts/latest/workspace/configuration/environment/). - [Checked bootstrap process](https://libtmux.org/en/ts/latest/workspace/configuration/hooks/). Use the [workspace library](https://libtmux.org/en/ts/latest/workspace/internals/) when application code needs to construct sessions directly. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Guides Source: https://libtmux.org/en/ts/latest/workspace/guides/ > Install the workspace command, find configurations and automate tmux sessions. **Workspace Manager concept example** A working example of the core library. It can change without notice. Choose a task below. The [CLI reference](https://libtmux.org/en/ts/latest/workspace/cli/) documents commands and options; [Internals](https://libtmux.org/en/ts/latest/workspace/internals/) covers the workspace builder library. - [Install and load](https://libtmux.org/en/ts/latest/workspace/guides/installation/): Install the command and load a workspace on a private socket. - [Find workspace files](https://libtmux.org/en/ts/latest/workspace/guides/discovery/): Discover, search and edit configurations. - [Automate workspace loading](https://libtmux.org/en/ts/latest/workspace/guides/automation/): Use machine output and exit codes in scripts. - [Export a session](https://libtmux.org/en/ts/latest/workspace/guides/export-session/): Capture a running session and load it again. - [Troubleshooting](https://libtmux.org/en/ts/latest/workspace/guides/troubleshooting/): Diagnose installation, configuration and execution problems. --- # Guides Source: https://libtmux.org/en/ts/latest/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/ts/latest/concepts/) explains the object model and transport choices. [Examples](https://libtmux.org/en/ts/latest/examples/) provides complete programs with setup and cleanup. - [Getting started](https://libtmux.org/en/ts/latest/guides/getting-started/): Install tmux and run a complete example. - [Attaching to tmux](https://libtmux.org/en/ts/latest/guides/attaching-to-tmux/): Select a socket and find or create a session. - [Sending keys](https://libtmux.org/en/ts/latest/guides/sending-keys/): Send literal text, named keys, and Enter. - [Capturing output](https://libtmux.org/en/ts/latest/guides/capturing-output/): Read the screen or scrollback and wait for a result. - [Filtering and querying](https://libtmux.org/en/ts/latest/guides/querying-and-filtering/): Find objects and handle missing or ambiguous matches. - [Testing](https://libtmux.org/en/ts/latest/guides/testing-with-libtmux/): Use isolated tmux servers and manage test cleanup. --- # Getting started Source: https://libtmux.org/en/ts/latest/guides/getting-started/ > Run a complete program with this language library. Use `libtmux` to create sessions, send input and read pane output from TypeScript. The [complete capture program](https://libtmux.org/en/ts/latest/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`]() returns captured lines. The complete program uses [`AbortSignal.timeout`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static) for a deadline and matches a whole output line. Its cleanup checks whether the private socket exists, including when startup fails, and reports shutdown errors. ## Connect to an existing server Use the [complete attach program](https://libtmux.org/en/ts/latest/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/ts/latest/guides/sending-keys/) explains input, and [Capturing output](https://libtmux.org/en/ts/latest/guides/capturing-output/) explains completion. [Querying and filtering](https://libtmux.org/en/ts/latest/guides/querying-and-filtering/) selects a target. --- # Attaching to tmux Source: https://libtmux.org/en/ts/latest/guides/attaching-to-tmux/ > Connect to an existing tmux server and find a session with TypeScript. 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.ts`. `LIBTMUX_SOCKET_PATH` selects the existing server. The launcher below supplies a private socket for trying the example. ```typescript title="connect.ts" import { Server } from "libtmux"; const socketPath = process.env.LIBTMUX_SOCKET_PATH; if (!socketPath) throw new Error("Set LIBTMUX_SOCKET_PATH to an existing socket"); const server = new Server({ socketPath, timeoutMs: 5_000 }); const snapshot = await server.snapshot({ signal: AbortSignal.timeout(5_000) }); const session = snapshot.sessions.one({ name: "work" }); console.log(session.name); ``` ## Setup and run Use an empty directory on Linux with Git and tmux 3.3a or newer installed. This example was checked with Bun 1.4.2. Save this file beside the program using the displayed filename. ```json title="package.json" {"type":"module","dependencies":{"libtmux":"file:./libtmux/packages/libtmux"}} ``` 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-ts-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 $ git clone https://github.com/libtmux/libtmux-ts libtmux && git -C libtmux checkout 3fe1ca654b81b8cbf4a13b777a001a3298c87a6f && bun install && sh run.sh bun run connect.ts ``` 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/ts/latest/examples/capture-pane-output/). Continue with [Sending keys](https://libtmux.org/en/ts/latest/guides/sending-keys/) once you have a pane handle. --- # Sending keys Source: https://libtmux.org/en/ts/latest/guides/sending-keys/ > Send text and named keys, then wait for the result. [`Pane.sendKeys`]() sends Enter by default. Use `enter: false` to type without submitting and `literal: true` when characters could be interpreted as key names. Pass an abort signal to bound the operation. ## Run the complete program [Capture pane output](https://libtmux.org/en/ts/latest/examples/capture-pane-output/) supplies the full TypeScript 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`]() returns captured lines. The complete program uses [`AbortSignal.timeout`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static) for a deadline and matches a whole output line. Its cleanup checks whether the private socket exists, including when startup fails, and reports shutdown errors. ## Where to go next [Capturing output](https://libtmux.org/en/ts/latest/guides/capturing-output/) covers the output side. [Attaching to tmux](https://libtmux.org/en/ts/latest/guides/attaching-to-tmux/) connects to a server you already own. --- # Capturing output Source: https://libtmux.org/en/ts/latest/guides/capturing-output/ > Read pane output with an explicit completion condition. [`Pane.capture`]() returns captured lines. The complete program uses [`AbortSignal.timeout`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static) for a deadline and matches a whole output line. Its cleanup checks whether the private socket exists, including when startup fails, and reports shutdown errors. ## Run the complete program [Capture pane output](https://libtmux.org/en/ts/latest/examples/capture-pane-output/) includes the full TypeScript 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/ts/latest/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/ts/latest/topics/waiting-and-retry/) documents this port's waiting APIs and failure handling. --- # Querying and filtering Source: https://libtmux.org/en/ts/latest/guides/querying-and-filtering/ > Choose a target and handle missing or ambiguous results. Take a snapshot with [`Server.snapshot`](), then use [`snapshot.sessions.one`]() with an exact name predicate. The complete program reports an absent result and leaves the existing tmux server running. A snapshot describes the read that created it; later commands can still fail if an object has disappeared. ## Require exactly one match [Attaching to tmux](https://libtmux.org/en/ts/latest/guides/attaching-to-tmux/) provides the complete TypeScript 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/ts/latest/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/ts/latest/guides/testing-with-libtmux/ > Use an isolated server and check cleanup failures. The repository's internal test harness is not a published API. For an external test, create a [`Server`]() with a private socket and register cleanup in your test framework. The complete capture program demonstrates startup checks, a bounded output wait and visible cleanup failures. ## Run a complete example [Capture pane output](https://libtmux.org/en/ts/latest/examples/capture-pane-output/) includes a complete TypeScript 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/ts/latest/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/ts/latest/guides/sending-keys/) returning successfully does not establish that the application finished. [Capturing output](https://libtmux.org/en/ts/latest/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/ts/latest/workspace/guides/installation/ > Build the workspace command and load a session on a private tmux socket. **Workspace Manager concept example** A working example of the core library. It can change without notice. Build the documented `tmux-workspace` revision, then load a small session on a private socket. Use a Unix shell with tmux 3.3a or newer on `PATH`. ## Build the command Fetch the documented source revision, then build from its repository root. Keep the exported `PATH` in this shell for the rest of the walkthrough. ```console $ git clone --filter=blob:none https://github.com/libtmux/libtmux-ts.git ``` ```console $ cd libtmux-ts ``` ```console $ git fetch --depth=1 origin f36d692552bb9a373b45338bb5fece854e57cc3d ``` ```console $ git checkout --detach FETCH_HEAD ``` Use Bun and Node.js 22 or newer. Install the locked dependencies and build the core package before the CLI: ```console $ bun install --frozen-lockfile ``` ```console $ bun run --cwd packages/libtmux build ``` ```console $ bun run --cwd packages/workspace-cli build ``` ```console $ WORKSPACE_BIN="$(mktemp -d)" ``` ```console $ ln -s "$PWD/packages/workspace-cli/dist/main.js" "$WORKSPACE_BIN/tmux-workspace" ``` ```console $ export PATH="$WORKSPACE_BIN:$PATH" ``` The launcher runs the built JavaScript using Node. Keep the source directory in place while using it. ```console $ tmux-workspace --help ``` ## Create the input Keep this shell open. Create a temporary working directory on a filesystem that supports Unix sockets, then enter it: ```console $ WORKSPACE_TMP="$(mktemp -d)" ``` ```console $ cd "$WORKSPACE_TMP" ``` Save this as `workspace.yaml`: ```yaml title="workspace.yaml" session_name: workspace-guide windows: - window_name: editor layout: even-horizontal panes: [null, null] ``` ## Load and inspect ```console $ tmux-workspace load \ -S "$WORKSPACE_TMP/tmux.sock" \ -f /dev/null \ -d \ --json \ workspace.yaml ``` `-d` leaves the session detached. Inspect its panes using the same socket: ```console $ tmux -S "$WORKSPACE_TMP/tmux.sock" list-panes -t '=workspace-guide:editor' ``` Attach interactively with [`tmux -S "$WORKSPACE_TMP/tmux.sock" attach-session -t '=workspace-guide'`](https://libtmux.org/en/tmux/latest/manual/attach-session/). Detach with your tmux detach binding before continuing. ## Capture and clean up ```console $ tmux-workspace freeze -S "$WORKSPACE_TMP/tmux.sock" --json workspace-guide ``` Try [export and reload](https://libtmux.org/en/ts/latest/workspace/guides/export-session/) before cleanup. Capture cannot recover original scripts, command history or application state. Remove only the session created by this walkthrough when finished: ```console $ tmux -S "$WORKSPACE_TMP/tmux.sock" kill-session -t '=workspace-guide' ``` The configuration remains in the temporary directory. Keep the session running when following guides that continue this example. ## Continue [Configuration](https://libtmux.org/en/ts/latest/workspace/configuration/) describes execution fields; [discovery](https://libtmux.org/en/ts/latest/workspace/guides/discovery/) finds saved files. Read the [load reference](https://libtmux.org/en/ts/latest/workspace/cli/load/) and [automation](https://libtmux.org/en/ts/latest/workspace/guides/automation/) for attachment, output and failure handling. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Find saved workspaces Source: https://libtmux.org/en/ts/latest/workspace/guides/discovery/ > Resolve explicit files, project directories and saved workspace names. **Workspace Manager concept example** A working example of the core library. It can change without notice. Use an explicit path, such as [`./workspace.yaml`](https://libtmux.org/en/ts/latest/workspace/guides/installation/#create-the-input), to select one document. Pass a project directory such as `.` to use its [`.tmuxp.yaml`](https://libtmux.org/en/ts/latest/workspace/guides/discovery/#list-available-files), [`.tmuxp.yml`](https://libtmux.org/en/ts/latest/workspace/guides/discovery/#list-available-files) or [`.tmuxp.json`](https://libtmux.org/en/ts/latest/workspace/guides/discovery/#list-available-files) configuration. A bare saved name uses the global workspace directory. ## List available files ```console $ tmux-workspace ls --json ``` Discovery includes project configurations in the current directory and its parents, plus saved global workspaces. The first existing global directory wins, in this order: 1. `TMUXP_CONFIGDIR`. 2. `$XDG_CONFIG_HOME/tmuxp`, with [`~/.config`](https://libtmux.org/en/ts/latest/workspace/guides/discovery/#list-available-files) as the XDG default. 3. [`~/.tmuxp`](https://libtmux.org/en/ts/latest/workspace/guides/discovery/#list-available-files). An existing empty directory remains selected. A missing directory does not override an existing fallback merely because its environment variable is set. ## Search by content ```console $ tmux-workspace search --json window:editor ``` Use [search](https://libtmux.org/en/ts/latest/workspace/cli/search/) for field prefixes and pattern rules. Use [edit](https://libtmux.org/en/ts/latest/workspace/cli/edit/) to open a discovered workspace, or [load](https://libtmux.org/en/ts/latest/workspace/cli/load/) with an explicit path when a name is ambiguous. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Automate workspace operations Source: https://libtmux.org/en/ts/latest/workspace/guides/automation/ > Run detached commands with explicit inputs and machine-readable results. **Workspace Manager concept example** A working example of the core library. It can change without notice. Give automation an explicit file, endpoint and attachment choice. Continue the [installation walkthrough](https://libtmux.org/en/ts/latest/workspace/guides/installation/) with this detached operation: ```console $ tmux-workspace load \ -S "$WORKSPACE_TMP/tmux.sock" \ -d \ --json \ workspace.yaml ``` Check the process exit status, parse its JSON result, then inspect any reported partial effects. A failed later input does not imply that earlier sessions were removed. Keep stderr separate from the result stream. ## Follow progress Use NDJSON when the caller needs records while a load is running: ```console $ tmux-workspace load \ -S "$WORKSPACE_TMP/tmux.sock" \ -d \ --ndjson \ workspace.yaml ``` Parse one complete JSON value per line. Treat a closed stream or missing final result as incomplete work. Do not infer success from an earlier creation event. ## Make retries deliberate Use a unique session name for independent jobs. Reusing a name follows the loader's existing-session policy; it is not a request to reset that session. Capture IDs and retained effects from the result before deciding what to clean up or retry. Remove only sessions the job owns. Read [output](https://libtmux.org/en/ts/latest/workspace/reference/output/) and [errors](https://libtmux.org/en/ts/latest/workspace/reference/exit-codes/) for the command's machine interface. A pane's process can outlive the CLI and can fail after successful command delivery. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Export and reload a session Source: https://libtmux.org/en/ts/latest/workspace/guides/export-session/ > Capture a running session, inspect the document and load a second copy. **Workspace Manager concept example** A working example of the core library. It can change without notice. Capture the session created by the [installation walkthrough](https://libtmux.org/en/ts/latest/workspace/guides/installation/) to a new YAML file: ```console $ tmux-workspace freeze \ -S "$WORKSPACE_TMP/tmux.sock" \ --json \ --workspace-format yaml \ --save-to workspace-export.yaml \ workspace-guide ``` Review the saved commands, directories and layout. Capture reads current tmux state; it cannot recover original arguments, shell history, scripts, comments or application state. A captured command may need editing before replay. ## Load a second copy Use a fresh session name on the same private server: ```console $ tmux-workspace load \ -S "$WORKSPACE_TMP/tmux.sock" \ -d \ -s workspace-replayed \ --json \ workspace-export.yaml ``` Inspect the second copy's panes: ```console $ tmux -S "$WORKSPACE_TMP/tmux.sock" list-panes -t '=workspace-replayed' ``` Remove that copy when finished: ```console $ tmux -S "$WORKSPACE_TMP/tmux.sock" kill-session -t '=workspace-replayed' ``` [Capture](https://libtmux.org/en/ts/latest/workspace/cli/freeze/) explains destination handling. [Conversion](https://libtmux.org/en/ts/latest/workspace/cli/convert/) changes file encoding without proving the document can be loaded. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Troubleshoot a workspace Source: https://libtmux.org/en/ts/latest/workspace/guides/troubleshooting/ > Find the failed stage before retrying a workspace operation. **Workspace Manager concept example** A working example of the core library. It can change without notice. Start with the error message and exit status. A partially completed load can leave sessions or windows running; inspect its result before retrying or cleaning up. ## Confirm the command and input ```console $ tmux-workspace debug-info --json ``` Check the executable version, selected tmux binary and workspace directories. Use an explicit file path to bypass saved-name lookup. Verify the socket matches the one used for inspection and capture. ## Common failures | Symptom | Next check | | --- | --- | | Workspace not found | Explicit path, file extension and global discovery directory | | Unsupported field | CLI configuration fields and the reported field path | | tmux unavailable | Executable path, permissions and selected socket | | Existing session mismatch | Running window names and the requested document | | Layout rejected | Layout name, pane capacity and the selected tmux version | | File already exists | Select a new output path or authorize replacement with `--force` | | Script failed | Child status, captured output and working directory | | Interactive context required | Use [`load -d`](https://libtmux.org/en/ts/latest/workspace/cli/load/) for automation; provide a terminal for interactive work | ## Record a load Continue the [installation walkthrough](https://libtmux.org/en/ts/latest/workspace/guides/installation/) and append diagnostic records to a local file: ```console $ tmux-workspace --log-level debug load \ -S "$WORKSPACE_TMP/tmux.sock" \ -d \ --json \ --log-file workspace-load.log \ workspace.yaml ``` Logs may include script output and local paths. Inspect them before sharing a bug report. Include the command, versions, minimal configuration, exit status and relevant result; remove private values. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Inspect a workspace through MCP Source: https://libtmux.org/en/ts/latest/workspace/guides/inspect-with-mcp/ > Connect the development TypeScript MCP server to a session loaded by its native workspace CLI. **Workspace Manager concept example** A working example of the core library. It can change without notice. Inspect the session you loaded with the TypeScript workspace CLI by pointing its MCP server at the same tmux socket. The loaded windows and panes are ordinary tmux objects; discovery returns their existing IDs. **This guide uses development `workspace-cli` source.** Continue the [installation walkthrough](https://libtmux.org/en/ts/latest/workspace/guides/installation/#load-and-inspect) through its detached load, keeping that shell and `WORKSPACE_TMP` available. Leave the `workspace-guide` session running. Build both executables from the same native repository checkout; released package instructions may describe different MCP contracts. ## Build the MCP server Run from the native repository root with the installation walkthrough's toolchain and dependencies. ```console $ bun run --cwd packages/mcp build ``` The installation walkthrough has already installed the frozen dependencies and built the local core package. Keep the MCP output chunks, workspace packages and installed dependencies available to Node. ## Select the same socket Configure an MCP client to launch the following command with the shown environment. The client owns the process's standard input and output for JSON-RPC messages. ```console $ LIBTMUX_TOOLSETS=inspect \ LIBTMUX_SOCKET_PATH="$WORKSPACE_TMP/tmux.sock" \ node packages/mcp/dist/server.js ``` In a client's configuration file, use absolute executable or script paths and expand `WORKSPACE_TMP` to its actual value. Configuration files do not perform shell variable expansion. Retain the environment used to build and run the native executable. For a workspace loaded with `-L NAME`, set `LIBTMUX_SOCKET=NAME` instead of `LIBTMUX_SOCKET_PATH`. Do not set both. If the CLI selected a binary through `TMUX_BIN`, give that same path to MCP through `LIBTMUX_TMUX_BIN`. ## Inspect and wait 1. Discover tools with `tools/list` and read the [`tmux://capabilities`]() resource. Confirm that its resolved endpoint matches the loaded socket. 2. Call [list_sessions][mcp-source], then [list_windows][mcp-source] with `session: "workspace-guide"`, and [list_panes][mcp-source]. Retain the returned session, window and pane IDs. 3. Select one returned pane ID for capture or a bounded text wait. Use the argument names below; discover the full schema before adding options. | Tool | Arguments | | --- | --- | | [capture_pane][mcp-source] | `"paneId"`, `"maxLines"` | | [wait_for_text][mcp-source] | `"paneId"`, `"patterns"`, `"timeoutMs"` in milliseconds | Set `"timeoutMs"` to `10000` for a ten-second wait. A pending wait permits other inspection calls on the same connection. To check that behavior, start a wait for text absent from the pane, then request [list_panes][mcp-source] before its deadline. Client cancellation uses `notifications/cancelled` with the outstanding request ID; the connection remains usable for inspection. Capture omits trailing empty rows. Use [snapshot_pane][mcp-source] for structured pane state and [capture_since][mcp-source] for incremental observation; their budgets and cursor fields are described in the discovered schemas. If discovery does not show `workspace-guide`, compare the resolved socket in capabilities with the CLI's `-S` path. A different socket selects a different daemon even when session names match. ## Close the connection Close the MCP connection's standard input to stop the server and release pending work. This separately loaded workspace remains running. When you finish the walkthrough, remove only its session on the same socket: ```console $ tmux \ -S "$WORKSPACE_TMP/tmux.sock" \ kill-session \ -t '=workspace-guide' ``` The configuration remains in the temporary directory until you remove it. See the verified [native workspace workflow][workspace-source] and [development MCP reference][mcp-source] for this source contract. The site's released MCP pages retain their version-pinned contracts. [workspace-source]: https://github.com/libtmux/libtmux-ts/blob/3db812d1aaca4501e26b1cff7551d28ab1fdf530/packages/workspace-cli/README.md [mcp-source]: https://github.com/libtmux/libtmux-ts/blob/3db812d1aaca4501e26b1cff7551d28ab1fdf530/packages/mcp/README.md --- # TypeScript workspace internals Source: https://libtmux.org/en/ts/latest/workspace/internals/ > Architecture and development interfaces of the TypeScript workspace builder. **Workspace Manager concept example** A working example of the core library. It can change without notice. Build and inspect tmux sessions from application code with the workspace library. To load files from a terminal, start with the [native CLI walkthrough](https://libtmux.org/en/ts/latest/workspace/guides/installation/). ## Builder pipeline [`parseWorkspace`]() validates input data. [`planWorkspace`]() inspects the target session and reports proposed topology changes; [`applyWorkspace`]() performs the changes through a caller-owned [`Server`](). The caller supplies file reading, command-line handling, attachment, and application lifetime. ## Read the implementation - [Guides](https://libtmux.org/en/ts/latest/workspace/internals/guides/) show builder setup and application code. - [Topics](https://libtmux.org/en/ts/latest/workspace/internals/topics/) explain configuration, behavior, and failures. - [Examples](https://libtmux.org/en/ts/latest/workspace/internals/examples/) exercise the builder through the language API. - [API](https://libtmux.org/en/ts/latest/workspace/reference/) links the configuration and construction interfaces. ## Implementation scope `@libtmux/workspace` applies a declared session layout to a libtmux [`Server`](). Describe windows, panes, working directories, and shell commands as data. Applying the same description again reuses matching objects. The package manages tmux structure. It does not supervise processes or restart commands that have exited. Commands run only in newly created panes by default. ## Package and runtime Use `@libtmux/workspace` alongside `libtmux`. The published package supports Node and Bun; its YAML convenience parser requires Bun. You can use validated JavaScript objects under either runtime. Real tmux control requires tmux on the host. The package documents Linux as its supported runtime platform. Read the [configuration and convergence rules](https://libtmux.org/en/ts/latest/workspace/internals/topics/) before applying a description. The caller supplies input data; the library does not discover files or load runtime extensions. [Package documentation](https://github.com/libtmux/libtmux-ts/blob/f85b8de551353f746d50eaf36bf0112f4fe5a528/packages/workspace/README.md) --- # TypeScript workspace builder behavior Source: https://libtmux.org/en/ts/latest/workspace/internals/topics/ > Internal configuration, application, and failure contracts of the TypeScript workspace builder. **Workspace Manager concept example** A working example of the core library. It can change without notice. Applying a workspace reconciles the requested structure with a named session. It can create missing objects, rename windows, and remove eligible surplus objects. It returns the resulting [`Session`](). ## Ownership and shared objects A session created by the package carries the reserved `@libtmux-workspace` option. The default `prune: "owned"` removes surplus only from a session with that ownership stamp. Applying to a session created elsewhere adds the missing structure and preserves its surplus windows and panes. `prune: "never"` disables removals. `prune: "always"` authorizes removals for that call without stamping persistent ownership. Inspect a fresh plan before using that policy on an existing session. Windows match by position rather than numeric tmux index. A linked surplus window is unlinked from this session. Grouped sessions retain surplus windows, and shared windows retain surplus panes, because removing those objects would affect their other placements. ## Commands and options The default `commands: "create-only"` sends setup and pane commands only in panes created by the current apply. `commands: "always"` replays them in reused panes too. Completion means workspace operations finished; it does not mean a long-running command is ready to accept requests. Named options are applied each time. Removing a key from the description does not unset its current tmux value. Working directories inherit from workspace to window to pane, with the most specific value winning. ## Plans and failures [`planWorkspace`]() describes topology changes without applying them. The plan contains object identities and retention reasons; it does not describe option, layout, focus, or command changes. Another tmux client can change the session after planning, so the plan is advisory. [`WorkspaceApplyError`]() reports completed milestones, the failed stage, and the underlying cause. Its [`requiresReplan`]() flag requires a fresh inspection after failure. There is no rollback, and a transport failure may leave command delivery uncertain. Do not infer that replaying the same command is safe from a failed apply alone. [Workspace behavior](https://github.com/libtmux/libtmux-ts/blob/f85b8de551353f746d50eaf36bf0112f4fe5a528/packages/workspace/README.md) --- # Use the TypeScript workspace builder Source: https://libtmux.org/en/ts/latest/workspace/internals/guides/ > Apply a workspace, review planned changes, and handle partial failures. **Workspace Manager concept example** A working example of the core library. It can change without notice. Apply a workspace to create or reconcile its session, windows, and panes. Start with the [complete TypeScript example](https://libtmux.org/en/ts/latest/workspace/internals/examples/): it includes imports, project setup, the selected library source, run commands, and private-server cleanup. ## Create a session [`applyWorkspace`]() accepts a [`Server`]() and workspace configuration. Await it to receive the resulting session. Pane commands can still be running when it returns. The complete example uses a private socket and registers cleanup before applying the workspace. A failed apply can leave a session or some of its windows in place. For a workspace you want to keep, choose the intended server explicitly and retain the returned session. ## Read configuration [`parseWorkspace`]() from `@libtmux/workspace/config` validates an object produced by your chosen JSON or YAML parser. [`parseWorkspaceYaml`]() uses Bun's YAML parser. Unknown fields fail validation. With another runtime, parse the document first and pass the resulting object to [`parseWorkspace`](). ## Review changes and failures [`planWorkspace`]() reads the server and reports planned structural creation, removal, retention, and window renames. Options, layouts, focus, and command effects are outside that plan. Review removals and retained entries, then apply promptly. Replan after an outside change. When an apply fails after mutation may have started, [`WorkspaceApplyError`]() records completed milestones and the failed stage. Its [`requiresReplan`]() flag is true; rediscover the current structure before retrying. Completed command effects remain part of the application's recovery decision. [Topics](https://libtmux.org/en/ts/latest/workspace/internals/topics/) explains command replay and pruning policies. The [configuration parser](https://github.com/libtmux/libtmux-ts/blob/3fe1ca654b81b8cbf4a13b777a001a3298c87a6f/packages/workspace/src/config.ts) and [builder contracts](https://github.com/libtmux/libtmux-ts/blob/3fe1ca654b81b8cbf4a13b777a001a3298c87a6f/packages/workspace/src/builder.ts) cover these entry points. --- # TypeScript workspace builder examples Source: https://libtmux.org/en/ts/latest/workspace/internals/examples/ > Build and inspect a workspace on a private tmux server with TypeScript. **Workspace Manager concept example** A working example of the core library. It can change without notice. Create a workspace with two windows and two editor panes, inspect the result, then stop its private tmux server. The `/bin/cat` commands keep panes open without depending on an application or log file. ## Prepare the project Use Bun 1.4.2 or newer, Git, and tmux 3.3a or newer on Unix. Create an empty consumer directory: ```console $ mkdir workspace-example && cd workspace-example ``` Fetch the source revision used by this example: ```console $ git init libtmux-source && \ git -C libtmux-source remote add origin https://github.com/libtmux/libtmux-ts.git && \ git -C libtmux-source fetch --depth 1 origin 3fe1ca654b81b8cbf4a13b777a001a3298c87a6f && \ git -C libtmux-source checkout --detach FETCH_HEAD ``` Create the project manifest. Both packages come from the same source tree: ```json title="package.json" { "private": true, "type": "module", "workspaces": [ "libtmux-source/packages/libtmux", "libtmux-source/packages/workspace" ], "dependencies": { "libtmux": "workspace:*", "@libtmux/workspace": "workspace:*" } } ``` The local workspaces keep the consumer and companion on the same core module from that checkout. Install the dependencies: ```console $ bun install --production ``` ## Build and remove a workspace Create the program below. The bootstrap session keeps the private server running while the program sets its default shell and builds the workspace. Cleanup covers a failed build as well as a successful one. ```typescript title="workspace.ts" import { mkdtemp, readdir, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { Server } from "libtmux"; import { applyWorkspace } from "@libtmux/workspace"; const directory = await mkdtemp(join(tmpdir(), "libtmux-workspace-")); const server = new Server({ socketPath: join(directory, "tmux.sock"), configFile: "/dev/null", environment: { ...process.env, ENV: "/dev/null", BASH_ENV: "/dev/null" }, timeoutMs: 5_000, }); const failures: unknown[] = []; try { await server.newSession({ name: "bootstrap", shellCommand: "/bin/cat" }); await server.setGlobalOption("session", "default-shell", "/bin/sh"); const session = await applyWorkspace(server, { session_name: "workspace-example", windows: [ { window_name: "editor", panes: ["/bin/cat", "/bin/cat"] }, { window_name: "logs", panes: ["/bin/cat"] }, ], }); const windows = session.windows.toArray(); const editor = windows.find((window) => window.name === "editor"); if (windows.length !== 2 || editor?.panes.length !== 2) { throw new Error("Expected two windows and two editor panes"); } console.log(`built: ${windows.length} windows`); console.log(`editor: ${editor.panes.length} panes`); } catch (error) { failures.push(error); } finally { for (const cleanup of [ async () => { if ((await readdir(directory)).includes("tmux.sock")) await server.kill(); await rm(directory, { recursive: true }); }, ]) { try { await cleanup(); } catch (error) { failures.push(error); } } } if (failures.length > 0) throw new AggregateError(failures, "Workspace example failed"); ``` [`newSession`]() can fail after starting tmux. Cleanup checks the owned socket even if that call did not return. If stopping tmux fails, the program keeps the socket directory and reports the error. ## Verification Run the program: ```console $ bun run workspace.ts ``` Expected output: ```text built: 2 windows editor: 2 panes ``` [`applyWorkspace`]() returns the built session snapshot. Its windows and panes reflect the completed build; request another snapshot after later changes. The program removes every session on the private server before exiting. For a workspace that stays open, let the application retain its explicitly selected server and choose when to stop it. A failed build can leave partial work; the example's server cleanup removes it. [Example source](https://github.com/libtmux/libtmux-ts/blob/3fe1ca654b81b8cbf4a13b777a001a3298c87a6f/examples/workspace/workspace.ts); [Workspace builder source](https://github.com/libtmux/libtmux-ts/blob/3fe1ca654b81b8cbf4a13b777a001a3298c87a6f/packages/workspace/src/builder.ts). --- # TypeScript workspace builder API Source: https://libtmux.org/en/ts/latest/workspace/reference/ > Internal reference for the TypeScript workspace builder and configuration APIs. **Workspace Manager concept example** A working example of the core library. It can change without notice. Import planning and application from `@libtmux/workspace`, and parsers from `@libtmux/workspace/config`. Application operates on a core libtmux [`Server`]() supplied by the caller; creating that server does not choose a workspace or apply one automatically. ## Parse and validate [`parseWorkspace`](https://libtmux.org/en/ts/latest/workspace/reference/config-parseworkspace/) validates data already read by your application. [`parseWorkspaceYaml`](https://libtmux.org/en/ts/latest/workspace/reference/config-parseworkspaceyaml/) adds Bun's YAML parsing. Both produce the workspace configuration consumed by the builder. ## Plan and apply [`planWorkspace`](https://libtmux.org/en/ts/latest/workspace/reference/builder-planworkspace/) returns a description of membership changes. [`WorkspacePlan`](https://libtmux.org/en/ts/latest/workspace/reference/planning-workspaceplan/) records creations, removals, renames, and retained surplus. [`applyWorkspace`](https://libtmux.org/en/ts/latest/workspace/reference/builder-applyworkspace/) performs the work and resolves to the resulting [`Session`](). Its options control pruning and whether commands run in existing panes. Planning accepts pruning policy; command policy belongs to application. ## Handle failure [`WorkspaceApplyError`](https://libtmux.org/en/ts/latest/workspace/reference/builder-workspaceapplyerror/) preserves the cause and completed milestones. Reinspect tmux before retrying; the error is not a transaction log of every effect or a receipt for shell commands. The language API builds workspaces directly. Availability through an MCP server is a separate protocol capability; consult this port's [MCP section](https://libtmux.org/en/ts/latest/mcp/) for its advertised tools. [Public exports](https://github.com/libtmux/libtmux-ts/blob/f85b8de551353f746d50eaf36bf0112f4fe5a528/packages/workspace/package.json) ## API declarations - [builder.applyWorkspace](https://libtmux.org/en/ts/latest/workspace/reference/builder-applyworkspace/) - [operation_options.ApplyWorkspaceOptions](https://libtmux.org/en/ts/latest/workspace/reference/operation_options-applyworkspaceoptions/) - [ownership.claimSession](https://libtmux.org/en/ts/latest/workspace/reference/ownership-claimsession/) - [operation_options.CommandPolicy](https://libtmux.org/en/ts/latest/workspace/reference/operation_options-commandpolicy/) - [config.initialPaneStartDirectory](https://libtmux.org/en/ts/latest/workspace/reference/config-initialpanestartdirectory/) - [ownership.mayPrune](https://libtmux.org/en/ts/latest/workspace/reference/ownership-mayprune/) - [config.optionValue](https://libtmux.org/en/ts/latest/workspace/reference/config-optionvalue/) - [ownership.ownedByWorkspace](https://libtmux.org/en/ts/latest/workspace/reference/ownership-ownedbyworkspace/) - [config.paneCommands](https://libtmux.org/en/ts/latest/workspace/reference/config-panecommands/) - [config.paneStartDirectory](https://libtmux.org/en/ts/latest/workspace/reference/config-panestartdirectory/) - [config.paneWantsFocus](https://libtmux.org/en/ts/latest/workspace/reference/config-panewantsfocus/) - [config.parseWorkspace](https://libtmux.org/en/ts/latest/workspace/reference/config-parseworkspace/) - [config.parseWorkspaceYaml](https://libtmux.org/en/ts/latest/workspace/reference/config-parseworkspaceyaml/) - [builder.planWorkspace](https://libtmux.org/en/ts/latest/workspace/reference/builder-planworkspace/) - [operation_options.PlanWorkspaceOptions](https://libtmux.org/en/ts/latest/workspace/reference/operation_options-planworkspaceoptions/) - [ownership.PrunePolicy](https://libtmux.org/en/ts/latest/workspace/reference/ownership-prunepolicy/) - [config.windowStartDirectory](https://libtmux.org/en/ts/latest/workspace/reference/config-windowstartdirectory/) - [config.Workspace](https://libtmux.org/en/ts/latest/workspace/reference/config-workspace/) - [builder.WorkspaceApplyError](https://libtmux.org/en/ts/latest/workspace/reference/builder-workspaceapplyerror/) - [builder.WorkspaceApplyMilestone](https://libtmux.org/en/ts/latest/workspace/reference/builder-workspaceapplymilestone/) - [builder.WorkspaceApplyStage](https://libtmux.org/en/ts/latest/workspace/reference/builder-workspaceapplystage/) - [config.WorkspaceInput](https://libtmux.org/en/ts/latest/workspace/reference/config-workspaceinput/) - [config.WorkspaceOptionValue](https://libtmux.org/en/ts/latest/workspace/reference/config-workspaceoptionvalue/) - [config.WorkspacePane](https://libtmux.org/en/ts/latest/workspace/reference/config-workspacepane/) - [planning.WorkspacePaneCreation](https://libtmux.org/en/ts/latest/workspace/reference/planning-workspacepanecreation/) - [planning.WorkspacePaneRemoval](https://libtmux.org/en/ts/latest/workspace/reference/planning-workspacepaneremoval/) - [planning.WorkspacePlan](https://libtmux.org/en/ts/latest/workspace/reference/planning-workspaceplan/) - [planning.WorkspaceRetention](https://libtmux.org/en/ts/latest/workspace/reference/planning-workspaceretention/) - [config.WorkspaceWindow](https://libtmux.org/en/ts/latest/workspace/reference/config-workspacewindow/) - [planning.WorkspaceWindowCreation](https://libtmux.org/en/ts/latest/workspace/reference/planning-workspacewindowcreation/) - [config.WorkspaceWindowInput](https://libtmux.org/en/ts/latest/workspace/reference/config-workspacewindowinput/) - [planning.WorkspaceWindowPlacement](https://libtmux.org/en/ts/latest/workspace/reference/planning-workspacewindowplacement/) - [planning.WorkspaceWindowRemoval](https://libtmux.org/en/ts/latest/workspace/reference/planning-workspacewindowremoval/) - [planning.WorkspaceWindowRename](https://libtmux.org/en/ts/latest/workspace/reference/planning-workspacewindowrename/) --- # Workspace reference generation Source: https://libtmux.org/en/ts/latest/workspace/internals/documentation/ > Generate command references from the parser and verify task examples against the CLI. **Workspace Manager concept example** A working example of the core library. It can change without notice. The executable's parser owns its command names, arguments and options. Keep reference generation tied to those definitions. ## Command metadata Commander owns the command definitions. The package generates Markdown, a JSON command catalog and completion scripts from those definitions. `docs:check` checks their freshness. See [shell completion](https://libtmux.org/en/ts/latest/workspace/cli/completion/) for end-user setup. A generated parser reference describes syntax; task examples also need to exercise the underlying services and their cleanup. ## Site integration Record the CLI's own source revision independently from the core library reference. Keep commands, configuration and examples specific to that source. Use the same content selection for HTML, search, Markdown and machine exports. Verify guides against a private tmux server, with cleanup limited to the objects the test owns. Check failure cases as well as successful construction. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Linking and consuming our docs Source: https://libtmux.org/en/ts/latest/meta/linking/ > Find documentation exports for search engines, bots, LLMs and other documentation sites. We welcome bots, search engines, SEO tools, LLMs and other clients to use our documentation. Read a page in your browser, fetch its Markdown, discover pages through a manifest, or link to documented objects from another site. ## Choose an export The page footer links to the exports for its documentation tree. Use those links to select a language, version or preview. | File or format | Use it for | | --- | --- | | [llms.txt](https://libtmux.org/en/llms.txt) | Discover guides, API references and agent prompts through a Markdown index. | | [llms-full.txt](https://libtmux.org/en/llms-full.txt) | Fetch guides and MCP contracts together as Markdown. API references are linked separately. | | [docs.json](https://libtmux.org/en/docs.json) | Discover page titles, URLs, descriptions, headings and Markdown URLs in a structured manifest. | | Markdown | Read one page as text using its footer's **Markdown** link. | | Raw source | Inspect the source file using its footer's **Raw source** link, where available. | | [objects-full.inv](https://libtmux.org/en/objects-full.inv) | Resolve Sphinx references across shared docs, each port's default version, or its latest until the default has published a catalog, and tmux reference versions. | | objects.inv | Resolve Sphinx references within one port and version, or one tmux documentation tree. | | [targets.json](https://libtmux.org/en/targets.json) | Browse inventory keys, display names and destination URLs as JSON. A scoped catalog sits beside each root inventory. The root one lists fallbacks and ports left out. | The root exports above cover the assembled site. Port exports describe the selected port and version. For a single API declaration, start with `docs.json` and follow its reference and symbol-index links. ## Link from Sphinx The [Intersphinx guide](https://libtmux.org/en/meta/intersphinx/) explains how to configure inventories, choose native roles or portable labels, and preserve references when a page moves or changes its title. Browse [Intersphinx examples](https://libtmux.org/en/meta/intersphinx/examples/) for copyable RST and MyST references to library APIs, tmux C declarations, hooks, format variables, CLI commands and schema fields, paired with their destinations. ## Discover and index pages Use the [sitemap](https://libtmux.org/en/sitemap-index.xml) to discover indexable pages. Follow [robots.txt](https://libtmux.org/robots.txt) and each page's robots metadata: pull-request previews, component demos and search-index shards are excluded from crawling, and alternate versions can carry `noindex`. Choose a versioned documentation tree when a reference needs a particular release. The full inventory follows each port's advertised default; a port's `objects.inv` describes the selected version. --- # Link to libtmux from Sphinx Source: https://libtmux.org/en/ts/latest/meta/intersphinx/ > Use Intersphinx inventories to reference libtmux APIs and documentation. Sphinx can resolve references to libtmux APIs, guides, headings, MCP objects, schema fields, and other documented targets. The footer links to the full inventory and the inventory for the page's port or tmux version. Browse [Intersphinx examples](https://libtmux.org/en/meta/intersphinx/examples/) for copyable RST and MyST references paired with their destinations. For Markdown exports, manifests and crawler discovery, see [Linking and consuming our docs](https://libtmux.org/en/meta/linking/). ## Configure Intersphinx Enable the built-in extension in your project's `conf.py`: `None` discovers `objects.inv` at the configured base URL. The port mapping above selects the Python `latest` tree. Copy the base URL of another port or version to select its inventory. The full inventory includes shared documentation, the configured default version of each assembled port, and distinct tmux reference versions. It is generated after site assembly. Each port inventory includes the rendered targets in that exact version. The tmux inventory includes the shared tmux guides and the latest CLI manual, options, hooks, formats, and C source reference. A version mapping such as `tmux-3-7c` includes only that release's manual, catalog, and C declarations. Manual and C reference pages link to the same version inventory in the footer. Use mapping names without dots when writing MyST reference roles. ## Choose a reference Every exported target has a portable label that works with `std:ref`, without installing a language or MCP domain. Open `targets.json` beside the inventory and copy its [`key`](). Its `href` and `display` identify the destination. For example, the Python [`libtmux.Pane`]() declaration has this reStructuredText reference: ```rst :external+libtmux:ref:`Pane ` ``` With MyST enabled in your project, the same label works in Markdown: ```markdown {external+libtmux:ref}`Pane ` ``` Native Python, C++, JavaScript, and C objects also have aliases for their built-in roles. A scoped Python inventory supports: ```rst :external+libtmux-python:py:class:`libtmux.Pane` ``` The tmux mapping provides native C roles and portable manual references: ```rst :external+tmux:c:struct:`cmd` :external+tmux:ref:`capture-pane ` ``` Command options also work with Sphinx's program context: ```rst .. program:: tmuxp load :external+libtmux-python:option:`--append` ``` The full inventory qualifies native names by port, such as `py:libtmux.Pane`. A fully qualified alias includes the product too: `py:core:libtmux.Pane`. Short aliases are offered only when they identify one destination. Configuration values, command options, environment variables, and glossary terms use standard-domain types where their renderers identify those semantics. ## Stable labels A portable key contains `scope:product:category:identity`. Its encoding preserves uppercase letters, punctuation, and Unicode, because `std:ref` lowercases targets. `%50ane` and [`pane`]() therefore remain distinct. Copy the key from the catalog without decoding its percent escapes. Keys are independent of display titles and destination URLs. API public IDs, protocol wire identities, JSON Pointers, named parameters, and native method identities supply their names. Authored documents can retain `inventoryId` and explicit HTML fragment IDs when their titles or routes change. Contributors preserve renamed keys in the inventory alias catalog and use the existing page redirect mechanism for retired routes. ### Preserve published links If `meta/intersphinx.md` moves to `meta/linking.md`, retain its logical ID and list the retired route in the new page's frontmatter: ```yaml inventoryId: intersphinx aliases: - meta/intersphinx ``` The document key remains `site:core:doc:intersphinx`, and the old route redirects to the new page. Retain existing heading fragment IDs when their text changes. When an identity or fragment changes intentionally, map the former keys to current targets in `site/src/data/inventory-aliases.json`. For example, choosing `inventoryId: linking` and changing `stable-labels` to `stable-references` needs these entries: ```json [ { "scope": "site", "from": "site:core:doc:intersphinx", "to": "site:core:doc:linking" }, { "scope": "site", "from": "site:core:heading:intersphinx%23stable-labels", "to": "site:core:heading:linking%23stable-references", "fragment": "stable-labels" } ] ``` The document entry preserves `std:ref` and `std:doc` references. The heading entry preserves `std:ref`; `fragment` also installs the retired HTML anchor at the new destination. Keep the route alias too: inventory aliases do not redirect retired URLs. Copy [`to`]() from the current target catalog. Retain earlier [`from`]() entries and update their destinations when renaming again. Former native role names, such as a Python class name, need preservation in the native metadata. Existing `objects.inv` and `reference/objects.inv` endpoints remain compatibility exports. New integrations should use the full inventory, a port's root inventory, or a tmux root inventory to obtain the complete target catalog and case-safe labels. See the [Sphinx Intersphinx documentation](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) for named inventories and cross-reference syntax. --- # Intersphinx examples Source: https://libtmux.org/en/ts/latest/meta/intersphinx/examples/ > Compare Sphinx and MyST references to APIs, tmux C declarations, hooks, format variables, CLI commands and schema fields. import { referenceHref } from '../../../../lib/api-models' Copy a reference and compare its destination below. These examples cover native language roles, portable labels, full and scoped inventories, and links into tmux C declarations, hooks, format variables and CLI commands. ## Configure the inventories Add these mappings to your Sphinx project's `conf.py`: `None` discovers `objects.inv` at the mapping's base URL. The full inventory uses each port's advertised default version. The `py` mapping explicitly selects `latest`; `tmux` selects the latest tmux manual and C reference. Use the root URL from an inventory's footer link when selecting a preview or another release. ## Native Python roles A named inventory selects the Python tree: ```rst :external+py:py:class:`libtmux.Pane` ``` Destination: [Pane](https://libtmux.org/en/py/latest/reference/libtmux-pane/#libtmux.Pane). The full inventory qualifies native names by port: ```rst :external+full:py:class:`py:libtmux.Pane` ``` Destination: Pane in the Python default version. For automatic lookup, use the ordinary role. A local definition takes precedence over Intersphinx: ```rst :py:class:`libtmux.Pane` ``` Destination: [Pane](https://libtmux.org/en/py/latest/reference/libtmux-pane/#libtmux.Pane). ## Portable labels Portable labels work with the standard reference role, including languages that have no built-in Sphinx domain. Copy the key from `targets.json`. ```rst :external+full:ref:`Pane ` :external+py:ref:`Pane ` ``` Destinations: Full inventory: Pane, [Scoped inventory: Pane](https://libtmux.org/en/py/latest/reference/libtmux-pane/#libtmux.Pane). The external role searches the configured inventories without selecting one. This native name is unqualified only in the scoped Python inventory: ```rst :external:py:class:`libtmux.Pane` ``` Destination: [Pane](https://libtmux.org/en/py/latest/reference/libtmux-pane/#libtmux.Pane). ## MyST roles and inventory URLs Enable `myst_parser` alongside `sphinx.ext.intersphinx` for Markdown sources. Named roles accept the same targets as reStructuredText: ```markdown {external+py:py:class}`libtmux.Pane` ``` Destination: [Pane](https://libtmux.org/en/py/latest/reference/libtmux-pane/#libtmux.Pane). Portable labels retain their percent escapes inside reference roles: ```markdown {external+full:ref}`Pane ` ``` Destination: Pane in the Python default version. MyST's inventory URL syntax also supports native aliases: ```markdown [Pane](inv:py:py:class#libtmux.Pane) ``` Destination: [Pane](https://libtmux.org/en/py/latest/reference/libtmux-pane/#libtmux.Pane). Use role syntax for percent-encoded portable keys: MyST normalizes escapes in `inv:` URLs. Keep mapping names free of dots, as in `tmux-3-7c`, so MyST can parse the role name. When using an inventory URL, specify its domain and object type if a name is both a document and a label. ## tmux C declarations The tmux mapping provides Sphinx's built-in C roles: ```rst :external+tmux:c:struct:`cmd` :external+tmux:c:func:`cmd_find_target` ``` Destinations: [cmd](https://libtmux.org/en/tmux/latest/reference/c-struct-cmd/#c%3Astruct%3Acmd), [cmd_find_target](https://libtmux.org/en/tmux/latest/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target). Select a release with its own mapping. The full inventory also offers version-qualified native aliases: ```rst :external+tmux-3-7c:c:func:`cmd_find_target` :external+full:c:func:`tmux@3.7c:cmd_find_target` :external+full:c:func:`tmux@latest:cmd_find_target` ``` Destinations: [Scoped: cmd_find_target in 3.7c](https://libtmux.org/en/tmux/3.7c/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target), [Full: cmd_find_target in 3.7c](https://libtmux.org/en/tmux/3.7c/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target), [Full: cmd_find_target in latest](https://libtmux.org/en/tmux/latest/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target). MyST supports the same C roles and a typed inventory URL: ```markdown {external+tmux:c:struct}`cmd` {external+tmux:c:func}`cmd_find_target` {external+full:c:func}`tmux@3.7c:cmd_find_target` [cmd_find_target](inv:tmux:c:function#cmd_find_target) ``` Destinations: [MyST: cmd](https://libtmux.org/en/tmux/latest/reference/c-struct-cmd/#c%3Astruct%3Acmd), [MyST: cmd_find_target](https://libtmux.org/en/tmux/latest/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target), [MyST full: cmd_find_target in 3.7c](https://libtmux.org/en/tmux/3.7c/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target), [Inventory URL: cmd_find_target](https://libtmux.org/en/tmux/latest/reference/c-function-cmd_find_target/#c%3Afunction%3Acmd_find_target). The C reference links each declaration to its source file and revision. Portable labels also address its signatures, parameters, and sections. ## tmux hooks Link a hook name to its catalog page with a portable label. The same key works in the scoped tmux inventory and the full inventory: ```rst :external+tmux:ref:`after-new-session ` :external+full:ref:`after-new-session ` ``` Destinations: [Scoped: after-new-session](https://libtmux.org/en/tmux/latest/catalog/hooks/after-new-session/), [Full: after-new-session](https://libtmux.org/en/tmux/latest/catalog/hooks/after-new-session/). In MyST, use the same key inside a reference role. Preserve its percent escapes: ```markdown {external+tmux:ref}`after-new-session ` {external+full:ref}`after-new-session ` ``` Destinations: [MyST scoped: after-new-session](https://libtmux.org/en/tmux/latest/catalog/hooks/after-new-session/), [MyST full: after-new-session](https://libtmux.org/en/tmux/latest/catalog/hooks/after-new-session/). ## tmux formats Link a format variable such as [`#{session_name}`](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/) to its catalog entry: ```rst :external+tmux:ref:`session_name ` :external+full:ref:`session_name ` ``` Destinations: [Scoped: session_name](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/), [Full: session_name](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/). The MyST references select the same scoped or full inventory: ```markdown {external+tmux:ref}`session_name ` {external+full:ref}`session_name ` ``` Destinations: [MyST scoped: session_name](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/), [MyST full: session_name](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/). ## tmux CLI manual The same tmux inventory covers command pages: ```rst :external+tmux:ref:`capture-pane ` ``` Destination: [capture-pane](https://libtmux.org/en/tmux/latest/manual/capture-pane/). The document role works when the target is a whole page: ```rst :external+tmux:doc:`Full manual ` ``` Destination: [Full tmux manual](https://libtmux.org/en/tmux/latest/manual/full/). Select a command's manual page with the document role. Its portable key also works in the full inventory: ```rst :external+tmux:doc:`tmux new-session ` :external+full:doc:`tmux new-session ` ``` Destinations: [Scoped: new-session](https://libtmux.org/en/tmux/latest/manual/new-session/), [Full: new-session](https://libtmux.org/en/tmux/latest/manual/new-session/). Use the same document role in MyST: ```markdown {external+tmux:doc}`tmux new-session ` {external+full:doc}`tmux new-session ` ``` Destinations: [MyST scoped: new-session](https://libtmux.org/en/tmux/latest/manual/new-session/), [MyST full: new-session](https://libtmux.org/en/tmux/latest/manual/new-session/). ## Command options, environment variables, and terms The Python port's workspace documentation exports standard-domain objects. Set the program context before referencing an option: ```rst .. program:: tmuxp load :external+py:option:`--append` ``` Destination: [tmuxp load --append](https://libtmux.org/en/py/latest/workspace/cli/load/#arguments-and-flags-a-append). Environment variables and glossary terms use their own roles. Qualify the product when a term appears in more than one glossary: ```rst :external+py:envvar:`COLUMNS` :external+py:term:`async ` ``` Destinations: [COLUMNS](https://libtmux.org/en/py/latest/workspace/configuration/environment/#cli-and-runtime-variables-columns-lines-rows), [async](https://libtmux.org/en/py/latest/reference/glossary/#async). ## MCP tools and schema fields Portable labels also address protocol objects and individual JSON Schema fields. No custom MCP domain is required: ```markdown {external+py:ref}`Read tools batch ` {external+py:ref}`on_error ` ``` Destinations: [Read tools batch](https://libtmux.org/en/py/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch), [on_error](https://libtmux.org/en/py/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Fon_error). ## Shared documentation and headings The full inventory includes the shared documentation: ```rst :external+full:doc:`Inventory guide ` :external+full:ref:`Configure Intersphinx ` ``` Destinations: [Inventory guide](https://libtmux.org/en/meta/intersphinx/), [Configure Intersphinx](https://libtmux.org/en/meta/intersphinx/#configure-intersphinx). ## Local files and fallback locations Download an inventory and pass its filename as the second mapping value. The first value remains the documentation URL used in generated links: An ordered list tries a local copy before the HTTP inventory: See the [inventory guide](https://libtmux.org/en/meta/intersphinx/) for key stability and the [Sphinx Intersphinx reference](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) for configuration options. --- # AI policy Source: https://libtmux.org/en/ts/latest/meta/ai-policy/ > Use the libtmux packages with AI tools. When contributing, check what you submit and wait for a maintainer's invitation before preparing a pull request. Last revised October 25, 2026 Use these packages with AI tools as you like. When contributing, check what you submit and wait for a maintainer's invitation before preparing a pull request. This policy covers the libraries, ports, and documentation in the [libtmux](https://github.com/libtmux) and [tmux-python](https://github.com/tmux-python) organizations, including their issues, comments, discussions, reviews, and pull requests. ## 1. For users: About these packages We encourage you to use AI tools with our libraries and documentation, including to generate code that calls the libraries. We want these projects to be useful in the way you work. Some of what we publish supports that workflow: - [MCP integrations](https://libtmux.org/en/py/latest/mcp/) that let assistants interact with tmux. - Markdown documentation and `llms.txt` and `llms-full.txt` resources linked from documentation pages. - [`AGENTS.md`]() and other repository instructions for tools working on the codebase. Use the documentation for the package, language, and version you are working with. ### How the ports are made The ports build on [tmuxp](https://tmuxp.git-pull.com/), started in 2013, and [libtmux](https://libtmux.git-pull.com/), started in 2016. Both projects predate today's LLM coding tools. Current work on the original projects and the ports uses AI assistance. Maintainers guide the design, review changes, test behavior against real tmux, and decide what ships. They remain responsible for what the projects include and maintain. ### Stability Packages in the [libtmux organization](https://github.com/libtmux) are experimental unless their README says otherwise. Names and APIs may change between releases. Pin an exact version and review changes before upgrading. ## 2. For contributors: How to report issues, ideas, suggestions, and security issues A useful issue is a contribution in its own right. Your experience helps us see what breaks, what feels awkward, and what is missing. You do not need to arrive with a patch. Open bugs, ideas, and suggestions in the repository of the package they concern. Report suspected security vulnerabilities privately using the route below. ### Bugs Tell us what you tried, what happened, and what you expected. Include a small example we can run, the library and tmux versions, and the actual output. Include relevant logs and error messages as they appeared, and distinguish what you observed from possible explanations. Bug reports are welcome whether the code you were running was handwritten or generated. Include the code that ran. A conversation transcript is usually unnecessary; include relevant prompts or tool calls when they are needed to reproduce the problem. ### Ideas and suggestions Explain what you wanted to accomplish and where the current design gets in your way. We welcome feedback on: - Usability: what was hard to find or get right, and where the documentation misled you. - Language conventions: whether a port feels natural in the language you use. - Aesthetics: how an API, a page, or an error message reads. - Missing capabilities: what you could not accomplish with the current API. If an API you expected is missing, describe the task and why that API would help. ### Security issues Report suspected security vulnerabilities privately. Use **Report a vulnerability** on the affected repository's security page where available. Include the affected package and version, the tmux version, what you observed, and reproduction steps or relevant code references if available. Distinguish verified behavior from suspected impact. Please coordinate public disclosure with us so we can investigate and, where needed, prepare a fix. Command execution explicitly requested through documented features is expected behavior and does not, by itself, establish a vulnerability. Explain any additional failure, such as data being interpreted as commands unexpectedly or an intended security boundary being crossed. ### Writing your report Short reports, typos, and imperfect English are fine. Translation and writing assistance are welcome; check that the result says what you mean and preserves the facts you observed. Your experience matters more than a polished report. ### Using AI tools If AI materially helped prepare your issue, comment, discussion, review, or pull request, say which tools you used, what they did, and what you checked yourself. Using these tools does not count against a contribution. You remain responsible for what you submit. Do not send generated code, reports, or explanations you have not checked. ### Pull requests Before preparing a pull request, open an issue or comment on an existing issue about the proposed change. Wait for a maintainer to invite a PR for an agreed scope. Opening an issue alone is not an invitation. PRs submitted without that agreement may be closed without review. Arrange security fixes through the private reporting route. Even when we agree that something should change, we may prefer to write the implementation ourselves. Review must consider correctness, supported tmux versions, language conventions, documentation, and ongoing maintenance. Checking those can take more time than writing the change, whether it was handwritten or generated. If we invite a PR, understand the changes, test them, and be able to explain them. Follow the project's contribution instructions, and describe the tests you ran and the versions you used. Generated code and tests can share the same mistake, so passing tests alone do not show that a change fits the project. Submit only material you have the right to contribute on terms compatible with the project's license. Identify outside code, tests, or text incorporated into the contribution, including material adapted with AI assistance, and provide its source and license. Keep required notices, and raise unclear permissions before including the material. These source and licensing requirements apply to maintainers too.

Acknowledgments: Informed by Pallets’ LLM and AI Policy, tmux’s AI contribution guidelines, and OpenJDK’s Interim Policy on Generative AI. Licensing references: the GNU GPL FAQ on translating code and license compatibility. All sources consulted .

--- # Third-party notices Source: https://libtmux.org/en/ts/latest/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. --- # Exit codes and errors Source: https://libtmux.org/en/ts/latest/workspace/reference/exit-codes/ > Use process status and structured error codes to handle workspace failures. **Workspace Manager concept example** A working example of the core library. It can change without notice. Check the process status before treating a result as complete. A failed load can report retained effects; a later failure does not undo an earlier input. | Exit status | Meaning | | --- | --- | | `0` | Command completed; an explicitly declined prompt can also finish without changes | | `1` | Workspace validation or operation failure | | `2` | Invalid arguments or execution context | | `130` | Interrupted operation | Child commands such as [`edit`](https://libtmux.org/en/ts/latest/workspace/cli/edit/) can propagate another nonzero child status. ## Machine errors With `--json` or `--ndjson`, diagnostics identify a `code` and readable `message`. Use the code for program decisions and keep the message for users. | Code | Condition | | --- | --- | | `workspace_not_found` | Requested workspace was not found | | `invalid_workspace` | Document shape or value is invalid | | `unsupported_key` | An execution field is unsupported | | `session_not_found` | The selected session does not exist | | `session_mismatch` | Existing session does not match the requested document | | `tmux_unavailable` | tmux cannot be found or used | | `tmux_failed` | A tmux operation failed | | `script_failed` | A bootstrap process failed | | `destination_exists` | A file would be replaced without authorization | | `usage` | Arguments or execution context are invalid | | `interrupted` | A signal stopped the operation | Additional codes describe implementation failures such as a closed output stream, unavailable runtime or log-file failure. Keep unknown codes visible instead of assuming they mean success. See [troubleshooting](https://libtmux.org/en/ts/latest/workspace/guides/troubleshooting/) for collecting a useful report. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Output formats Source: https://libtmux.org/en/ts/latest/workspace/reference/output/ > Read JSON results, NDJSON events and diagnostics from the workspace command. **Workspace Manager concept example** A working example of the core library. It can change without notice. Every command accepts `--json` and `--ndjson`. JSON writes one document to stdout. NDJSON writes one JSON record per line and takes precedence if both flags are present. Machine output contains no terminal styling. ## Choose a stream ```console $ tmux-workspace ls --json ``` The shape depends on the operation: listing and search describe workspace records; conversion and import can return the translated document; loading describes completed work and failures. Saving a document returns information about that save. The file's YAML/JSON encoding is controlled separately by `--workspace-format`. Use [automation](https://libtmux.org/en/ts/latest/workspace/guides/automation/) for a detached load and streamed progress. Read stdout as results and stderr as diagnostics. Check the exit status even when stdout contains valid data. ## Partial work and interrupted streams Load results can contain completed inputs, created IDs and retained effects. Treat a failed operation as partial until its result tells you what remains. A creation event alone does not establish that the workspace finished. An output failure or interruption can leave a final record unwritten or incomplete. A consumer must handle EOF and parse errors. Preserve the exit status and inspect the private server before retrying mutations. ## Child output and logging Machine calls encode captured child text so it cannot be confused with result records. The optional [inspection shell](https://libtmux.org/en/ts/latest/workspace/cli/shell/) reports its child status along with captured output. A nonzero editor status is propagated. Captured child results retain up to 64 KiB of source bytes per stream and mark truncation. NDJSON forwards child output as it arrives. [`load --log-file PATH`](https://libtmux.org/en/ts/latest/workspace/cli/load/) appends diagnostics to a separate file. `--log-level` selects advisory detail. A later log-file failure reports a diagnostic and preserves the operation's result; the log can end with an incomplete record. ## Human output `--color auto|always|never` selects styling; nonempty `NO_COLOR` disables color. Human progress uses the terminal. `--no-progress` disables drawing without hiding errors. Redirected or machine output avoids the progress display. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Runtime and configuration support Source: https://libtmux.org/en/ts/latest/workspace/reference/compatibility/ > Runtime requirements and configuration boundaries for the TypeScript workspace command. **Workspace Manager concept example** A working example of the core library. It can change without notice. `tmux-workspace` is the TypeScript command for loading and capturing tmux workspaces. The [installation guide](https://libtmux.org/en/ts/latest/workspace/guides/installation/) builds the documented source revision and runs a session on a private socket. The walkthroughs require tmux 3.3a or newer. A daemon older than 3.3a is refused before any effect; see [tmux support](https://libtmux.org/en/tmux/guides/tmux-support/). ## Runtime and execution The CLI runs on Node.js 22 or newer and can be built with Bun. Use the installation guide for the documented revision. Ordinary load, capture, discovery, search, conversion and import use native services. Search uses JavaScript regular expressions. Explicit plugins, custom workspace builders and `shell` use an optional interpreter with tmuxp 1.74.0. Select it with `TMUX_WORKSPACE_PYTHON`. Empty extension selections keep native execution. The CLI and `@libtmux/workspace` are separate implementations. The library's convergence API and strict schema have a different contract from CLI loading. ## Configuration and failure handling Read [configuration](https://libtmux.org/en/ts/latest/workspace/configuration/) for the CLI's fields. Unsupported execution fields fail visibly; generic [conversion](https://libtmux.org/en/ts/latest/workspace/cli/convert/) preserves document values without proving that they can be executed. Use [machine output](https://libtmux.org/en/ts/latest/workspace/reference/output/) for automation and check both the process status and any retained effects. Capture reads live tmux state; it cannot recover original command arguments, scripts, comments or application state. [Examples](https://libtmux.org/en/ts/latest/workspace/examples/gallery/) provide complete starter documents. Their pane commands can need additional applications and directories when adapted. Use [library internals](https://libtmux.org/en/ts/latest/workspace/internals/) for the programmatic builder. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). --- # Topics Source: https://libtmux.org/en/ts/latest/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/ts/latest/concepts/) introduces the shared object model. The concept guides also cover [control mode vs one-shot](https://libtmux.org/en/ts/latest/concepts/transports/), [filtering and queries](https://libtmux.org/en/ts/latest/concepts/queries/), and [workspaces](https://libtmux.org/en/ts/latest/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/ts/latest/topics/architecture/): Locate operations and field definitions in the library source. - [Traversal](https://libtmux.org/en/ts/latest/topics/traversal/): Navigate related objects, test membership, and compare identity. - [Ownership and cleanup](https://libtmux.org/en/ts/latest/topics/context-managers/): Manage cleanup on block exit and identify objects that need a kill. - [Pane interaction](https://libtmux.org/en/ts/latest/topics/pane-interaction/): Choose input modes, capture ranges, and completion waits. - [Options and hooks](https://libtmux.org/en/ts/latest/topics/options-and-hooks/): Configure tmux and register event commands at a supported scope. - [Format-token fields](https://libtmux.org/en/ts/latest/topics/format-tokens/): Read typed state and handle absent fields. - [Waiting and retrying](https://libtmux.org/en/ts/latest/topics/waiting-and-retry/): Wait on a condition or a named tmux signal. - [Environment](https://libtmux.org/en/ts/latest/topics/environment/): Locate objects from process variables and configure new panes. - [Socket and servers](https://libtmux.org/en/ts/latest/topics/socket-and-servers/): Select a server, check liveness, and detect a replacement daemon. - [Errors and exceptions](https://libtmux.org/en/ts/latest/topics/errors-and-exceptions/): Handle command failures and decide whether a mutation can be retried. --- # Architecture Source: https://libtmux.org/en/ts/latest/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/ts/latest/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. ```typescript await pane.sendKeys("echo hi"); await pane.kill(); ``` ## Reading tmux fields Object IDs become tmux targets (`-t`). Format variables (`#{...}`) provide the state returned by tmux. [`packages/libtmux/src/_generated/format_fields.ts`]() records each token's scope and first tmux version. [`packages/libtmux/src/_generated/field_aliases.ts`]() provides camelCase aliases for fields on [`Pane`](), [`Session`](), and [`Window`](). ## Source layout The public classes live in [`packages/libtmux/src/server.ts`](), [`packages/libtmux/src/session.ts`](), [`packages/libtmux/src/window.ts`](), [`packages/libtmux/src/pane.ts`](), and [`packages/libtmux/src/client.ts`](). Their operations are split by concern under [`packages/libtmux/src/_internal/operations/`](), including [`packages/libtmux/src/_internal/operations/pane_io.ts`](), [`packages/libtmux/src/_internal/operations/hooks.ts`](), [`packages/libtmux/src/_internal/operations/options.ts`](), and [`packages/libtmux/src/_internal/operations/topology.ts`](). [`packages/libtmux/src/_generated/`]() contains the generated field catalogs. Workspaces and the MCP server have separate packages in the same repository. --- # Traversal Source: https://libtmux.org/en/ts/latest/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/ts/latest/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/ts/latest/concepts/server-session-window-pane/). Await [`Server.sessions`](), then read [`Session.windows`]() and [`Window.panes`]() from the loaded graph. [`session.windows`]() and [`window.panes`]() read the graph loaded by [`await server.sessions()`]() without additional tmux commands. ## 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. [`session.Session.panes`]() returns a [`Selection`]() from the session's captured graph. Reading it does not issue another tmux command; refresh the snapshot when you need newer state. ## 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/ts/latest/concepts/server-session-window-pane/) introduces that distinction: [`Pane.window`]() and [`Window.session`]() are getters that follow the relationships in the loaded graph. ## One walk, down and back up List a session's windows, then look up a parent and compare its identity with the starting object: ```typescript const session = (await server.sessions())[0]; const window = session.windows[0]; const pane = window.panes[0]; pane.window.id === window.id; window.session.id === 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 the [`Session.activeWindow`]() and [`Window.activePane`]() getters. [Format-token fields](https://libtmux.org/en/ts/latest/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: `Selection` is iterable. Iterate and compare IDs, or spread it into an array for standard array operations. ## 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 the handles’ `id` properties when checking identity on the same server. --- # Ownership and cleanup Source: https://libtmux.org/en/ts/latest/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/ts/latest/concepts/workspaces/) for a temporary layout example. ## Release connections and kill owned sessions Control connections and notification streams implement `[Symbol.asyncDispose]`. `await using` releases those handles; it leaves the watched session and panes running. Use `finally` to kill a session your program owns: ```typescript const session = await server.newSession({ name: "work" }); try { const window = await session.newWindow({ name: "editor" }); await window.panes.at(0)?.sendKeys("echo hi"); } finally { await session.kill(); } ``` ## 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/ts/latest/guides/testing-with-libtmux/). --- # Pane interaction Source: https://libtmux.org/en/ts/latest/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/ts/latest/examples/attach-and-send-keys/) provides examples. [Sending keys](https://libtmux.org/en/ts/latest/guides/sending-keys/) and [Capturing output](https://libtmux.org/en/ts/latest/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.sendKeys(text, { enter: false })` **Type + Enter (default):** [`pane.sendKeys(text)`]() **How "literal" is chosen:** `{ literal: true }` option ### 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: ```typescript await pane.sendKeys("echo hi", { enter: false }); await pane.sendKeys("echo hi"); ``` ## 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. ```typescript await pane.capture(); ``` ## 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. [Capture pane output](https://libtmux.org/en/ts/latest/examples/capture-pane-output/) shows capture and waiting examples. [Waiting and retrying](https://libtmux.org/en/ts/latest/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/ts/latest/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.showOptions()`]() **Read effective/inherited:** [`pane.showResolvedOptions()`]() **Set:** [`pane.setOption(name, value)`]() **Unset:** [`pane.unsetOption(name)`]() ### Examples After a successful write completes, read the option to obtain its updated value. The following examples set, read, and unset an option: ```typescript await pane.setOption("automatic-rename", "off"); await pane.showOptions(); await pane.unsetOption("automatic-rename"); ``` ## Hooks **Set:** [`pane.setHook(name, command, { append })`]() **Unset:** [`pane.unsetHook(name)`]() **List:** [`pane.showHooks()`]() (all; no singular `showHook`) **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 or pass `{ append: true }` to append. Set and list a session hook. The next section explains window and pane scope limitations: ```typescript await session.setHook("session-renamed", "display-message 'renamed'"); await session.showHooks(); ``` ## 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 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/ts/latest/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 [`undefined`](). 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: ```typescript pane.deadSignal; // undefined under the same conditions ``` ## Field availability Field accessors retain the scope and version requirements of tmux tokens. [`packages/libtmux/src/_generated/format_fields.ts`]() records each token's scope and first tmux version. For example, [`pane_zoomed_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_zoomed_flag/) has pane scope and requires tmux 3.7. [`packages/libtmux/src/_generated/field_aliases.ts`]() supplies the camelCase alias `pane.zoomedFlag`. 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 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/ts/latest/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/ts/latest/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/ts/latest/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:** [`connectedServer.waitFor(matches, options)`]() **Where it lives:** The public control-connection API. Tests a predicate over [`ServerSnapshot`](); see [Control mode vs one-shot](https://libtmux.org/en/ts/latest/concepts/transports/). ### Examples [`waitFor`]() subscribes before reading a server snapshot so it does not miss a change between those steps. ```typescript await using live = await server.connect(); await live.waitFor((snapshot) => snapshot.windows.exists({ name: "build" })); ``` ## 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: The public API does not expose the channel handshake used internally by the test server during startup. 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/ts/latest/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/ts/latest/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:** Not listed. **Session:** [`Session.fromEnv()`]() **Window:** Not listed. **Pane:** Not listed. ### Examples Use [`Session.fromEnv()`]() to resolve the session of the current process. ```typescript const session = await Session.fromEnv(); ``` Environment lookup requires valid tmux targeting variables. If your process can run outside tmux, handle that case before using the result. ## tmux's own environment variable store Like [Options and hooks](https://libtmux.org/en/ts/latest/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.setEnvironment(name, value)`](), [`session.setEnvironment(...)`]() **Read all:** [`server.showEnvironment()`](), [`session.showEnvironment()`]() **Unset:** [`server.unsetEnvironment(name)`](), [`session.unsetEnvironment(name)`]() ### Examples ```typescript await server.setEnvironment("EDITOR", "vim"); await session.setEnvironment("EDITOR", "hx"); await session.showEnvironment(); ``` [`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`. --- # Socket and servers Source: https://libtmux.org/en/ts/latest/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 `new Server()` selects the default socket. Set `socketName` to select a named socket, or `socketPath` to use an explicit path. ```typescript const named = new Server({ socketName: "work" }); ``` Choose either a socket name or a socket path. tmux uses `TMUX_TMPDIR` to resolve the directory for default and named sockets. Supplying both selectors raises [`TypeError`](). ## 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.isAlive`]() returns a promise of a boolean. [`Server.raiseIfDead`]() throws when the server is unavailable and retains the reason reported by tmux. ```typescript if (await server.isAlive()) { await server.snapshot(); } ``` [`isAlive()`]() returns a boolean. Use [`raiseIfDead()`]() when you need failure details. ## 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 [`await server.kill()`](). [`TmuxServerRestartedError`]() reports an operation whose handle encountered a replacement daemon on the same socket. 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/ts/latest/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/ts/latest/concepts/queries/#the-cardinality-contract-side-by-side). ## A failed command, as a value [`TmuxCommandError`]() reports a command tmux rejected. [`TmuxTransportError`]() reports a failure to obtain a reply. Catch these error types separately when the distinction affects recovery. Distinguish a command rejected by tmux from a transport failure: ```typescript import { TmuxCommandError, TmuxTransportError } from "libtmux"; try { await pane.capture(); } catch (error) { if (error instanceof TmuxCommandError) { error.args; // the argument vector error.exitCode; error.stderr; // tmux's own lines } else if (error instanceof TmuxTransportError) { error.kind; // "cancelled" | "pipe" | "protocol" | "spawn" | "timeout" error.delivery; // see below: this is the question a retry depends on } } ``` ## 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: [`TmuxTransportError.delivery`]() distinguishes `not_started`, [`written`](), `replied`, and `indeterminate`. Only `not_started` establishes that retrying cannot repeat an already-dispatched command. ```typescript import { TmuxTransportError } from "libtmux"; try { await session.newWindow({ name: "build" }); } catch (error) { if (error instanceof TmuxTransportError && error.delivery === "not_started") { // safe to retry: nothing reached tmux } } ``` Treat unknown delivery as potentially executed. A `not_started` result means the request did not reach tmux. A [`written`]() result means the transport accepted the request but no terminal reply arrived. 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. --- # API glossary Source: https://libtmux.org/en/ts/latest/reference/glossary/ > Kinds, modifiers and package labels in the TypeScript API reference. ## Symbol kinds Kinds identify declarations in the TypeScript API reference. ### class A TypeScript class declaring a runtime constructor and members, with a corresponding instance type. References: [TypeScript classes](https://www.typescriptlang.org/docs/handbook/2/classes.html). ### interface A TypeScript type describing a structural contract. It does not create a runtime object or constructor. References: [TypeScript interfaces](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#interfaces). ### function A TypeScript callable with typed parameters and a return type. References: [TypeScript functions](https://www.typescriptlang.org/docs/handbook/2/functions.html). ### method A TypeScript function member declared on a class or object type. References: [TypeScript methods](https://www.typescriptlang.org/docs/handbook/2/classes.html#methods). ### property A TypeScript object member, including a stored field or an accessor. Getters and setters can execute code; the type declaration alone does not promise storage. References: [TypeScript fields](https://www.typescriptlang.org/docs/handbook/2/classes.html#fields); [TypeScript getters and setters](https://www.typescriptlang.org/docs/handbook/2/classes.html#getters--setters). ### attribute A TypeScript field or declared object member in this reference. References: [TypeScript fields](https://www.typescriptlang.org/docs/handbook/2/classes.html#fields). ### typealias A TypeScript name for a type expression, including a union, object or function type. It does not create a runtime constructor or a distinct nominal type. References: [TypeScript type aliases](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-aliases). ## Modifiers Modifiers add information about calling, implementing, or accessing a declaration. Their precise effect follows the language and the signature. ### static A TypeScript member accessed on its class constructor rather than on an instance. References: [TypeScript static members](https://www.typescriptlang.org/docs/handbook/2/classes.html#static-members). ### async A TypeScript async function returning a Promise. Awaiting it can suspend its caller without implying a new thread. References: [TypeScript async/await in ES6 targets](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-1-7.html#asyncawait-support-in-es6-targets-node-v4). ### readonly A TypeScript member that cannot be assigned through that typed reference after its permitted initialization. Referenced objects may still be mutable; readonly does not freeze them. References: [TypeScript readonly fields](https://www.typescriptlang.org/docs/handbook/2/classes.html#readonly). ### overload Multiple TypeScript call signatures describing accepted argument and result combinations. A function implementation supplies one body; callers use its exposed overload signatures. References: [TypeScript overloads](https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads). ### private A TypeScript member restricted to its declaring class. The private keyword is checked by TypeScript; JavaScript #private fields also enforce privacy at runtime. References: [TypeScript member visibility](https://www.typescriptlang.org/docs/handbook/2/classes.html#member-visibility). ## Package context Package labels identify where an API is supplied. ### package The npm package supplying this TypeScript API. Package identity and module import paths can differ. References: [TypeScript modules and packages](https://www.typescriptlang.org/docs/handbook/modules/reference.html#node_modules-package-lookups). --- # tmux MCP, built in TypeScript Source: https://libtmux.org/en/ts/latest/mcp/ > Run or embed @libtmux/mcp to inspect tmux, drive panes, and wait for commands. **MCP concept example** A working example of the core library. It can change without notice. `@libtmux/mcp` exposes tmux through an MCP stdio server and an embeddable TypeScript factory. Clients can inspect topology, capture output, run framed shell commands, and create or arrange panes. The package requires Node 22 or newer, or Bun 1.3.14 or newer, plus tmux 3.3a or newer. Real tmux operation is supported on Linux; the package's macOS artifact checks do not establish runtime support. ## Start here - [Install](https://libtmux.org/en/ts/latest/mcp/#install) points an MCP client at this server. - [Tools](https://libtmux.org/en/ts/latest/mcp/tools/) lists the MCP operations, arguments, and results. - [Guides](https://libtmux.org/en/ts/latest/mcp/guides/) install and connect a client. - [Topics](https://libtmux.org/en/ts/latest/mcp/topics/) explain toolsets, socket provenance, and waiting. - [Examples](https://libtmux.org/en/ts/latest/mcp/examples/) call a tool, then explore server internals. - [Language API](https://libtmux.org/en/ts/latest/mcp/reference/) documents embedding and implementation types. The server exposes a static [`tmux://capabilities`]() resource. It does not register workflow prompts or dynamic hierarchy resources. Use [Workspace Manager](https://libtmux.org/en/ts/latest/workspace/) to load and apply declarative configurations in application code. MCP clients create topology through individual tools; there is no workspace-file tool. [Package and runtime contract](https://github.com/libtmux/libtmux-ts/blob/f85b8de551353f746d50eaf36bf0112f4fe5a528/packages/mcp/README.md). --- # TypeScript MCP topics Source: https://libtmux.org/en/ts/latest/mcp/topics/ > Understand immutable tool selection, tmux provenance, pane protections, and output cursors. **MCP concept example** A working example of the core library. It can change without notice. The TypeScript MCP server selects its endpoint and tool surface at startup. Later environment changes do not retarget a running process. ## Toolsets and startup provenance `inspect`, `manage`, `execute`, and `teardown` are independent sets. `LIBTMUX_TOOLSETS` selects sets, `LIBTMUX_TOOLS` adds exact names, and `LIBTMUX_EXCLUDE_TOOLS` removes names last. Exclusions also govern nested operations in [`call_read_tools_batch`](). An explicitly empty selection starts with no tools. Unknown names, empty comma-separated elements, and retired safety/allowlist variables fail startup before contacting tmux. Without socket or configuration variables, the executable selects `libtmux-mcp`. If it creates that daemon with the shipped minimal configuration and verifies its startup marker, all four sets are enabled by default. Existing or explicitly selected daemons default to `inspect,manage,execute`. Tool filtering controls this MCP interface. A shell command still acts with the tmux user's authority, and a socket name does not confine processes. ## Pane input and human activity Input preflight checks caller context, attached human clients, pane modes, and synchronized-input membership. A `force` argument confirms only the exact MCP caller pane; it does not override the other checks. [`run_shell_command`]() requires one live supported POSIX shell and refuses a synchronized input cohort. It checks before setup and immediately before dispatch. These observations are not an atomic tmux transaction. ## Commands, waits, and cursors Use [`run_shell_command`]() for authored commands. Its result separates command output from the echoed wrapper and includes the real exit status. It runs the command in a subshell, so directory and environment changes do not persist in the parent shell. Use [`wait_for_text`]() for output produced elsewhere and [`capture_since`]() for repeated reads. Waits report why they stopped, their effective timeout, and captured output. Cancelling a request stops its wait. Setting `LIBTMUX_MCP_LIVE=0` prevents control-mode connections. [`wait_for_text`]() remains listed but returns a `no_stream` error; [`capture_since`]() returns a bounded non-streaming capture. [Tool and runtime semantics](https://github.com/libtmux/libtmux-ts/blob/f85b8de551353f746d50eaf36bf0112f4fe5a528/packages/mcp/README.md). --- # Connect a TypeScript MCP client Source: https://libtmux.org/en/ts/latest/mcp/guides/ > Launch @libtmux/mcp on a named socket and select the tools the client receives. **MCP concept example** A working example of the core library. It can change without notice. Launch `@libtmux/mcp` from a client with a dedicated socket name and an explicit toolset selection. Ensure the client can locate Node or Bun and tmux in its own environment. ## Start the stdio server With Node 22 or newer: ```console $ LIBTMUX_SOCKET=docs-agent LIBTMUX_TOOLSETS=inspect \ npx -y @libtmux/mcp@latest ``` The process waits for MCP requests on stdin. Its diagnostics go to stderr. For clients using the `mcpServers` format: ```json { "mcpServers": { "tmux-typescript": { "command": "npx", "args": ["-y", "@libtmux/mcp@latest"], "env": { "LIBTMUX_SOCKET": "docs-agent", "LIBTMUX_TOOLSETS": "inspect" } } } } ``` ## Verify and expand the surface After connecting, read [`tmux://capabilities`]() and call [`list_sessions`](). The resource reports the frozen tool selection and connection provenance. To permit authored commands, choose `inspect,execute`. Add `manage` for topology changes classified in that set. Read each tool's classification instead of assuming that creating a pane has no process effects. For an exact selection, set `LIBTMUX_TOOLSETS` to the empty string and `LIBTMUX_TOOLS` to [`list_sessions`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/)`,`[`capture_pane`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/). Restart after changing the environment. ## Choose another endpoint `LIBTMUX_SOCKET_PATH` selects an absolute socket path and is mutually exclusive with `LIBTMUX_SOCKET`. `LIBTMUX_TMUX_BIN` selects the executable. `LIBTMUX_TMUX_CONFIG` supplies a nonempty absolute configuration path when starting a daemon; connecting to an existing daemon cannot replace its startup configuration. [Launch and configuration source](https://github.com/libtmux/libtmux-ts/blob/f85b8de551353f746d50eaf36bf0112f4fe5a528/packages/mcp/README.md). --- # TypeScript MCP examples Source: https://libtmux.org/en/ts/latest/mcp/examples/ > Connect an embedded TypeScript MCP client and list a private tmux session. **MCP concept example** A working example of the core library. It can change without notice. Connect a client using the [setup guide](https://libtmux.org/en/ts/latest/mcp/guides/), then call [`list_sessions`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/). ## List sessions Send this params object through the connected client's MCP tools/call request: ```json { "name": "list_sessions", "arguments": {} } ``` Use the returned session IDs when choosing a window or pane. ## Internals The complete program below embeds a TypeScript MCP client and server with linked in-memory transports. It offers only [`list_sessions`](); a client that launches the stdio server does not need embedding code. ### Prepare the project Use Bun 1.4.2 or newer, Git, and tmux 3.3a or newer on Unix. Create an empty consumer directory: ```console $ mkdir mcp-example && cd mcp-example ``` Fetch the source revision used by this example: ```console $ git init libtmux-source && \ git -C libtmux-source remote add origin https://github.com/libtmux/libtmux-ts.git && \ git -C libtmux-source fetch --depth 1 origin 3fe1ca654b81b8cbf4a13b777a001a3298c87a6f && \ git -C libtmux-source checkout --detach FETCH_HEAD ``` Create the project manifest. The core and MCP packages come from that source tree; the SDK version matches the MCP package's dependency: ```json title="package.json" { "private": true, "type": "module", "workspaces": [ "libtmux-source/packages/libtmux", "libtmux-source/packages/mcp" ], "dependencies": { "libtmux": "workspace:*", "@libtmux/mcp": "workspace:*", "@modelcontextprotocol/sdk": "1.30.0" } } ``` The local workspaces keep the consumer and companion on the same core module from that checkout. Install the dependencies: ```console $ bun install --production ``` ### Connect an embedded client Create the program below. It starts a private tmux session, connects both sides of the transport, checks the offered tools, then calls [`list_sessions`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/). Cleanup closes the MCP client and server before stopping tmux. Operation and cleanup failures stay visible. ```typescript title="mcp.ts" import { mkdtemp, readdir, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; import { createTmuxMcpServer } from "@libtmux/mcp"; import { Server } from "libtmux"; const directory = await mkdtemp(join(tmpdir(), "libtmux-mcp-example-")); const server = new Server({ socketPath: join(directory, "tmux.sock"), configFile: "/dev/null", environment: { ...process.env, ENV: "/dev/null", BASH_ENV: "/dev/null" }, timeoutMs: 5_000, }); const failures: unknown[] = []; let client: Client | undefined; let mcp: ReturnType | undefined; try { await server.newSession({ name: "mcp-example", shellCommand: "/bin/cat" }); mcp = createTmuxMcpServer(server, { callerEnvironment: {}, environment: { LIBTMUX_TOOLSETS: "", LIBTMUX_TOOLS: "list_sessions" }, }); client = new Client({ name: "example", version: "1.0.0" }); const [clientSide, serverSide] = InMemoryTransport.createLinkedPair(); await Promise.all([ mcp.connect(serverSide), client.connect(clientSide, { timeout: 5_000 }), ]); const offered = (await client.listTools(undefined, { timeout: 5_000 })) .tools.map((tool) => tool.name); if (offered.length !== 1 || offered[0] !== "list_sessions") { throw new Error(`Unexpected tools: ${offered.join(", ")}`); } const result = await client.callTool( { name: "list_sessions", arguments: {} }, undefined, { timeout: 5_000 }, ); if (result.isError) throw new Error(JSON.stringify(result.content)); const sessions = result.structuredContent?.sessions; if (!Array.isArray(sessions) || sessions.length !== 1 || sessions[0]?.name !== "mcp-example") { throw new Error("Expected the example's private session"); } console.log(`tools: ${offered.join(", ")}`); console.log(`sessions: ${sessions[0].name}`); } catch (error) { failures.push(error); } finally { for (const cleanup of [ () => client?.close(), () => mcp?.close(), async () => { if ((await readdir(directory)).includes("tmux.sock")) await server.kill(); await rm(directory, { recursive: true }); }, ]) { try { await cleanup(); } catch (error) { failures.push(error); } } } if (failures.length > 0) throw new AggregateError(failures, "MCP example failed"); ``` [`newSession`]() can fail after starting tmux. Cleanup checks the owned socket even if that call did not return. If stopping tmux fails, the program keeps the socket directory and reports the error. ### Run the example's checks Run the program: ```console $ bun run mcp.ts ``` Expected output: ```text tools: list_sessions sessions: mcp-example ``` An empty `LIBTMUX_TOOLSETS` plus one name in `LIBTMUX_TOOLS` selects only that operation. `callerEnvironment: {}` avoids importing the surrounding pane's identity into the embedded server. The explicitly configured [`Server`]() selects the private socket. Use the result's structured session IDs for later tool requests. Check `isError` before reading successful output; the [tool reference](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/) describes its schema. [Embedded server source](https://github.com/libtmux/libtmux-ts/blob/3fe1ca654b81b8cbf4a13b777a001a3298c87a6f/packages/mcp/src/server.ts); [upstream agent example](https://github.com/libtmux/libtmux-ts/blob/3fe1ca654b81b8cbf4a13b777a001a3298c87a6f/examples/mcp-agent/mcp-agent.ts); [upstream example tests](https://github.com/libtmux/libtmux-ts/blob/3fe1ca654b81b8cbf4a13b777a001a3298c87a6f/examples/mcp-agent/mcp-agent.test.ts). For declarative application code, see [Workspace builder examples](https://libtmux.org/en/ts/latest/workspace/internals/examples/). --- # TypeScript MCP API Source: https://libtmux.org/en/ts/latest/mcp/reference/ > Find the TypeScript server factory and the MCP tool, schema, and capability contracts. **MCP concept example** A working example of the core library. It can change without notice. For MCP client requests, use the [tool reference](https://libtmux.org/en/ts/latest/mcp/tools/). This page covers language APIs for embedding or extending the server. Import the server factory to embed MCP. Use protocol tool names when communicating through an MCP client. ## Embedding API [`createTmuxMcpServer(tmux, options)`]() accepts a libtmux [`Server`]() and returns the SDK's [`McpServer`](https://ts.sdk.modelcontextprotocol.io/server#server-overview). Options can supply the caller environment, tool-selection environment, resolved policy, and startup provenance. Without supplied provenance, the factory treats the server as unprobed with unknown configuration. [`serverFromEnvironment(environment)`]() builds the libtmux endpoint from startup configuration. The executable combines endpoint resolution, startup probing, policy selection, and stdio transport. An embedding application owns its transport and shutdown. [Exported server functions](https://github.com/libtmux/libtmux-ts/blob/f85b8de551353f746d50eaf36bf0112f4fe5a528/packages/mcp/src/server.ts) and [in-process example](https://libtmux.org/en/ts/latest/mcp/examples/) describe this boundary. ## MCP reference The [tool reference](https://libtmux.org/en/ts/latest/mcp/tools/) covers wire operations. Registered tools publish input schemas, output schemas, structured results, and effect annotations. The startup selection determines which tools are listed and callable. [`tmux://capabilities`]() is a static JSON resource containing the frozen surface and its declarations. There are no workflow prompts or dynamic hierarchy-resource subscriptions. [Resource registration](https://github.com/libtmux/libtmux-ts/blob/f85b8de551353f746d50eaf36bf0112f4fe5a528/packages/mcp/src/resources.ts). Workspace parsing and application belong to [`@libtmux/workspace`](https://libtmux.org/en/ts/latest/workspace/reference/), not to a workspace MCP tool. ## API declarations - [mcp.startup.ConfigurationProvenance](https://libtmux.org/en/ts/latest/mcp/reference/mcp-startup-configurationprovenance/) - [mcp.server.createTmuxMcpServer](https://libtmux.org/en/ts/latest/mcp/reference/mcp-server-createtmuxmcpserver/) - [mcp.server.describeStartupFailure](https://libtmux.org/en/ts/latest/mcp/reference/mcp-server-describestartupfailure/) - [mcp.server.main](https://libtmux.org/en/ts/latest/mcp/reference/mcp-server-main/) - [mcp.policy.Policy](https://libtmux.org/en/ts/latest/mcp/reference/mcp-policy-policy/) - [mcp.server.serverFromEnvironment](https://libtmux.org/en/ts/latest/mcp/reference/mcp-server-serverfromenvironment/) - [mcp.startup.ServerStartup](https://libtmux.org/en/ts/latest/mcp/reference/mcp-startup-serverstartup/) - [mcp.startup.ServerState](https://libtmux.org/en/ts/latest/mcp/reference/mcp-startup-serverstate/) - [mcp.policy.Toolset](https://libtmux.org/en/ts/latest/mcp/reference/mcp-policy-toolset/) [Protocol catalog](https://libtmux.org/en/ts/latest/mcp/tools.json) --- # MCP API glossary Source: https://libtmux.org/en/ts/latest/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 TypeScript API reference. ### class A TypeScript class declaring a runtime constructor and members, with a corresponding instance type. References: [TypeScript classes](https://www.typescriptlang.org/docs/handbook/2/classes.html). ### interface A TypeScript type describing a structural contract. It does not create a runtime object or constructor. References: [TypeScript interfaces](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#interfaces). ### function A TypeScript callable with typed parameters and a return type. References: [TypeScript functions](https://www.typescriptlang.org/docs/handbook/2/functions.html). ### method A TypeScript function member declared on a class or object type. References: [TypeScript methods](https://www.typescriptlang.org/docs/handbook/2/classes.html#methods). ### property A TypeScript object member, including a stored field or an accessor. Getters and setters can execute code; the type declaration alone does not promise storage. References: [TypeScript fields](https://www.typescriptlang.org/docs/handbook/2/classes.html#fields); [TypeScript getters and setters](https://www.typescriptlang.org/docs/handbook/2/classes.html#getters--setters). ### attribute A TypeScript field or declared object member in this reference. References: [TypeScript fields](https://www.typescriptlang.org/docs/handbook/2/classes.html#fields). ### typealias A TypeScript name for a type expression, including a union, object or function type. It does not create a runtime constructor or a distinct nominal type. References: [TypeScript type aliases](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-aliases). ## Modifiers Modifiers add information about calling, implementing, or accessing a declaration. Their precise effect follows the language and the signature. ### static A TypeScript member accessed on its class constructor rather than on an instance. References: [TypeScript static members](https://www.typescriptlang.org/docs/handbook/2/classes.html#static-members). ### async A TypeScript async function returning a Promise. Awaiting it can suspend its caller without implying a new thread. References: [TypeScript async/await in ES6 targets](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-1-7.html#asyncawait-support-in-es6-targets-node-v4). ### readonly A TypeScript member that cannot be assigned through that typed reference after its permitted initialization. Referenced objects may still be mutable; readonly does not freeze them. References: [TypeScript readonly fields](https://www.typescriptlang.org/docs/handbook/2/classes.html#readonly). ### overload Multiple TypeScript call signatures describing accepted argument and result combinations. A function implementation supplies one body; callers use its exposed overload signatures. References: [TypeScript overloads](https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads). ### private A TypeScript member restricted to its declaring class. The private keyword is checked by TypeScript; JavaScript #private fields also enforce privacy at runtime. References: [TypeScript member visibility](https://www.typescriptlang.org/docs/handbook/2/classes.html#member-visibility). ## Package context Package labels identify where an API is supplied. ### package The npm package supplying this TypeScript API. Package identity and module import paths can differ. References: [TypeScript modules and packages](https://www.typescriptlang.org/docs/handbook/modules/reference.html#node_modules-package-lookups). --- # TypeScript-based tmux workspace manager Source: https://libtmux.org/en/ts/latest/workspace/ > Describe a tmux session in a file, then load, inspect and capture it. **Workspace Manager concept example** A working example of the core library. It can change without notice. The `tmux-workspace` CLI is published to npm, numbered 0.1.N. Pin its version when automation depends on its output. `tmux-workspace` creates tmux sessions from YAML or JSON. A file describes windows, panes, commands, directories and environment. Load it from a terminal or request machine output for automation. ## Load a workspace from the terminal 1. [Install the command and load a workspace](https://libtmux.org/en/ts/latest/workspace/guides/installation/). 2. [Configure windows and panes](https://libtmux.org/en/ts/latest/workspace/configuration/). 3. [Capture and reload a session](https://libtmux.org/en/ts/latest/workspace/guides/export-session/). The [CLI manual](https://libtmux.org/en/ts/latest/workspace/cli/) covers discovery, search, editing, loading, capture, conversion and import. [Examples](https://libtmux.org/en/ts/latest/workspace/examples/gallery/) provide complete configurations with their prerequisites. ## Automate and inspect Use [`load -d`](https://libtmux.org/en/ts/latest/workspace/cli/load/) when the caller should return without attaching. `--json` returns a result, and `--ndjson` supports a stream of records. Read [automation](https://libtmux.org/en/ts/latest/workspace/guides/automation/) for retry and cleanup decisions and [errors](https://libtmux.org/en/ts/latest/workspace/reference/exit-codes/) for failure handling. Loaded workspaces are ordinary tmux sessions. Select the same socket when inspecting them from tmux or the [MCP server](https://libtmux.org/en/ts/latest/mcp/). ## Build from application code The [workspace library](https://libtmux.org/en/ts/latest/workspace/internals/) has its own API and configuration contract. Use it when a program needs direct control over construction. The CLI task guides here describe the `tmux-workspace` executable and link to its documented source revision. [CLI source](https://github.com/libtmux/libtmux-ts/blob/f36d692552bb9a373b45338bb5fece854e57cc3d/packages/workspace-cli/README.md). - [CLI Manual](https://libtmux.org/en/ts/latest/workspace/cli/): Commands, options and machine output. - [Configuration](https://libtmux.org/en/ts/latest/workspace/configuration/): Workspace fields, normalization and execution. - [Install and load](https://libtmux.org/en/ts/latest/workspace/guides/installation/): Load a workspace on a private socket, then capture it. - [Example gallery](https://libtmux.org/en/ts/latest/workspace/examples/gallery/): Workspace files to start from, with their prerequisites. - [Runtime support](https://libtmux.org/en/ts/latest/workspace/reference/compatibility/): Runtime requirements and supported behavior. - [Internals](https://libtmux.org/en/ts/latest/workspace/internals/): The workspace library, for building sessions from code. --- # API glossary Source: https://libtmux.org/en/ts/latest/workspace/reference/glossary/ > Kinds, modifiers and package labels in the TypeScript API reference. ## Symbol kinds Kinds identify declarations in the TypeScript API reference. ### class A TypeScript class declaring a runtime constructor and members, with a corresponding instance type. References: [TypeScript classes](https://www.typescriptlang.org/docs/handbook/2/classes.html). ### interface A TypeScript type describing a structural contract. It does not create a runtime object or constructor. References: [TypeScript interfaces](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#interfaces). ### function A TypeScript callable with typed parameters and a return type. References: [TypeScript functions](https://www.typescriptlang.org/docs/handbook/2/functions.html). ### method A TypeScript function member declared on a class or object type. References: [TypeScript methods](https://www.typescriptlang.org/docs/handbook/2/classes.html#methods). ### property A TypeScript object member, including a stored field or an accessor. Getters and setters can execute code; the type declaration alone does not promise storage. References: [TypeScript fields](https://www.typescriptlang.org/docs/handbook/2/classes.html#fields); [TypeScript getters and setters](https://www.typescriptlang.org/docs/handbook/2/classes.html#getters--setters). ### attribute A TypeScript field or declared object member in this reference. References: [TypeScript fields](https://www.typescriptlang.org/docs/handbook/2/classes.html#fields). ### typealias A TypeScript name for a type expression, including a union, object or function type. It does not create a runtime constructor or a distinct nominal type. References: [TypeScript type aliases](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-aliases). ## Modifiers Modifiers add information about calling, implementing, or accessing a declaration. Their precise effect follows the language and the signature. ### static A TypeScript member accessed on its class constructor rather than on an instance. References: [TypeScript static members](https://www.typescriptlang.org/docs/handbook/2/classes.html#static-members). ### async A TypeScript async function returning a Promise. Awaiting it can suspend its caller without implying a new thread. References: [TypeScript async/await in ES6 targets](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-1-7.html#asyncawait-support-in-es6-targets-node-v4). ### readonly A TypeScript member that cannot be assigned through that typed reference after its permitted initialization. Referenced objects may still be mutable; readonly does not freeze them. References: [TypeScript readonly fields](https://www.typescriptlang.org/docs/handbook/2/classes.html#readonly). ### overload Multiple TypeScript call signatures describing accepted argument and result combinations. A function implementation supplies one body; callers use its exposed overload signatures. References: [TypeScript overloads](https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads). ### private A TypeScript member restricted to its declaring class. The private keyword is checked by TypeScript; JavaScript #private fields also enforce privacy at runtime. References: [TypeScript member visibility](https://www.typescriptlang.org/docs/handbook/2/classes.html#member-visibility). ## Package context Package labels identify where an API is supplied. ### package The npm package supplying this TypeScript API. Package identity and module import paths can differ. References: [TypeScript modules and packages](https://www.typescriptlang.org/docs/handbook/modules/reference.html#node_modules-package-lookups). --- # Tools Source: https://libtmux.org/en/ts/latest/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 concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) The reference configuration advertises 45 tools. Your server’s available objects depend on its configuration. [Setup documentation](https://libtmux.org/en/ts/latest/mcp/guides/) explains how to connect a client. ## Server3 tools[#](https://libtmux.org/en/ts/latest/mcp/tools/#tools-server) [create​_session](https://libtmux.org/en/ts/latest/mcp/tools/create_session/) Start a pane’s configured process; accepts no command payload. Create a detached session and return it with its first window and pane, so you can start working without listing anything first. [get​_server​_info](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/) Inspect tmux metadata; accepts no client-supplied executable input. The tmux server this process drives: its socket, version, daemon pid, and totals. Check the version before using a feature that needs a recent tmux. [list​_sessions](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/) Inspect tmux metadata; accepts no client-supplied executable input. Every session on this server with its id, name, window count, and whether anyone is attached. Metadata only — for what a pane shows, use [capture_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/) or [search_panes](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/). ## Session5 tools[#](https://libtmux.org/en/ts/latest/mcp/tools/#tools-session) [create​_window](https://libtmux.org/en/ts/latest/mcp/tools/create_window/) Start a pane’s configured process; accepts no command payload. Add a window to a session and return it with its pane. [get​_session​_info](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/) Inspect tmux metadata; accepts no client-supplied executable input. Return metadata for one session without listing every session. [kill​_session](https://libtmux.org/en/ts/latest/mcp/tools/kill_session/) Delete tmux state; accepts no command payload. Remove a session. Windows and panes shared with another session remain available there. [list​_windows](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/) Inspect tmux metadata; accepts no client-supplied executable input. Windows on this server, optionally restricted to one session by id or name. [rename​_session](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/) Change tmux state; no client-supplied executable input. Rename a session. Its id does not change, so targets by id keep working. ## Window9 tools[#](https://libtmux.org/en/ts/latest/mcp/tools/#tools-window) [get​_window​_info](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/) Inspect tmux metadata; accepts no client-supplied executable input. Return metadata and placements for one window. [kill​_window](https://libtmux.org/en/ts/latest/mcp/tools/kill_window/) Delete tmux state; accepts no command payload. Close a window and every pane in it. [list​_panes](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/) Inspect tmux metadata; accepts no client-supplied executable input. Panes on this server, with the command each is running and its directory. Marks the pane this server runs in (isCallerPane) and panes a person is watching (isAttended). Metadata only — [search_panes](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/) reads their contents. [move​_window](https://libtmux.org/en/ts/latest/mcp/tools/move_window/) Change tmux state; no client-supplied executable input. Move a window to another index, or into another session. [rename​_window](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/) Change tmux state; no client-supplied executable input. Rename a window. Its id does not change. [resize​_window](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/) Change tmux state; no client-supplied executable input. Set a window’s size in cells. A detached window is whatever size tmux guessed, and a program that formats to its terminal width truncates to that at the source — no capture option recovers those columns, because they were never printed. [resize_pane](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/) only redistributes space inside a window and cannot grow one. A client attached to the window will overwrite this when it next changes; window-size manual makes a size of your own stick. [select​_layout](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/) Change tmux state; no client-supplied executable input. Rearrange a window’s panes. Takes one of tmux’s named layouts, or a layout string from an earlier window whose `metadataComplete` is true to reproduce it exactly. [select​_window](https://libtmux.org/en/ts/latest/mcp/tools/select_window/) Change tmux state; no client-supplied executable input. Make a window the current one in its session. [split​_window](https://libtmux.org/en/ts/latest/mcp/tools/split_window/) Start a pane’s configured process; accepts no command payload. Split a pane and return the new one. Direction is where the new pane goes relative to the one you split. ## Pane18 tools[#](https://libtmux.org/en/ts/latest/mcp/tools/#tools-pane) [capture​_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/) Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. The text a pane is showing, or its scrollback. Negative `start` reaches back into history (-100 is a hundred lines above the top of the screen). For repeated reads of the same pane use [capture_since](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/) instead — it returns only what is new. [capture​_since](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/) Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. What a pane has printed since you last looked. Call it once with no cursor to start watching and get the current screen; keep the cursor it returns and pass it back each time after that, and you are charged only for what is new. This is the tool for watching a build, a log, or a test run — not a [capture_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/) loop. Set waitMs to block until something arrives rather than returning empty. Reports the stream in the order it was written, so a program that draws by moving the cursor (a progress bar, a full-screen TUI) reads jumbled here — [capture_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/) renders those. [clear​_pane​_scrollback](https://libtmux.org/en/ts/latest/mcp/tools/clear_pane_scrollback/) Delete tmux state; accepts no command payload. Discard the retained scrollback history for one pane. [find​_pane​_by​_position](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/) Inspect tmux metadata; accepts no client-supplied executable input. Find the pane occupying a named corner of a window. [get​_pane​_info](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/) Inspect tmux metadata; accepts no client-supplied executable input. One pane’s metadata: what it runs, where, how big, and whether it is yours or watched. Does not read its contents — [capture_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/) does that. [kill​_pane](https://libtmux.org/en/ts/latest/mcp/tools/kill_pane/) Delete tmux state; accepts no command payload. Close a pane and the process in it. Refuses the pane this server runs in and every pane a person is watching; force confirms only this server’s exact caller pane. [paste​_text](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/) Send input to a pane’s program; a shell that receives it runs it with your user’s permissions. Put text into a pane without tmux interpreting any of it as key names. Use for content — a password, a code block, anything with characters a key parser would claim. [resize​_pane](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/) Change tmux state; no client-supplied executable input. Resize a pane, either to a size or by an amount in a direction. Give width/height for an absolute size, or direction with amount for a nudge. [respawn​_pane](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/) Start a pane’s configured process; accepts no command payload. Restart a pane’s command in place, keeping the pane and its id. Use to recover a pane whose process died, rather than killing and re-splitting. [run​_shell​_command](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/) Run a shell command in a pane with your user’s permissions. Run a shell command in a pane, wait for it to finish, and report its exit status and output. Prefer this over [send_keys](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/) plus [capture_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/): it frames the command so a pane’s echo of what you typed can never be mistaken for what the command printed, and it knows when the command actually ended rather than guessing from the screen. The command runs in a subshell, so cd and export do not persist to a later call. A pane is effectively single-writer: this server reserves it until the command settles, but another process with the same tmux socket can still write into it. [search​_panes](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/) Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Find which panes are showing something. Searches pane contents, not their names — use [list_panes](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/) for metadata. Returns the matching lines with their pane, so you can target one without capturing them all. Literal matching stops at one 256 KiB aggregate UTF-8 byte budget. [select​_pane](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/) Change tmux state; no client-supplied executable input. Make a pane the active one in its window. Moves the cursor of anyone attached to that window. [send​_keys](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/) Send input to a pane’s program; a shell that receives it runs it with your user’s permissions. Send keystrokes to a pane. Use for TUIs, control keys (C-c), and partial lines. For a shell command whose result you want, use [run_shell_command](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/) — it waits for completion and reports exit status, which this does not. [send​_keys​_batch](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/) Send input to a pane’s program; a shell that receives it runs it with your user’s permissions. Send an ordered batch of pane-input operations, resolving and checking each row’s configured cohort immediately before input. Stop or continue on error. [set​_pane​_title](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/) Change tmux state; no client-supplied executable input. Give a pane a title. Useful for labelling what an agent put where, since the title shows in [list_panes](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/) and survives the command changing. [set​_synchronize​_panes](https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/) Change tmux state; no client-supplied executable input. Set the window default for synchronized pane input. Pane overrides still determine each effective configured cohort. [snapshot​_pane](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/) Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Return bounded terminal content and pane metadata in one MCP response. The metadata and capture come from separate tmux requests and are not an atomic snapshot. [swap​_pane](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/) Change tmux state; no client-supplied executable input. Exchange two panes’ positions. Their ids and contents travel with them. ## Hooks1 tool[#](https://libtmux.org/en/ts/latest/mcp/tools/#tools-hooks) [show​_hooks](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/) Read configured tmux commands; accepts no client-supplied executable input. Returned values may contain executable configuration. Read the hooks a server or session runs. Read-only: a hook set here would outlive this process and keep firing in somebody’s tmux. Put hooks a server should keep in its config file. ## Options and environment4 tools[#](https://libtmux.org/en/ts/latest/mcp/tools/#tools-options-and-environment) [set​_history​_limit](https://libtmux.org/en/ts/latest/mcp/tools/set_history_limit/) Change tmux state; no client-supplied executable input. Set the default retained scrollback line limit through a bounded integer. [set​_mouse​_enabled](https://libtmux.org/en/ts/latest/mcp/tools/set_mouse_enabled/) Change tmux state; no client-supplied executable input. Set the global tmux mouse option through a closed boolean schema. [show​_environment](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/) Read the tmux environment; accepts no client-supplied executable input. Returned values may contain secrets. The environment tmux gives processes it starts, at server or session scope. This is what a new pane will inherit, not what a running one has. [show​_option](https://libtmux.org/en/ts/latest/mcp/tools/show_option/) Read configured tmux commands; accepts no client-supplied executable input. Returned values may contain executable configuration. Read one named tmux option at server, session, window, or pane scope. ## Coordination2 tools[#](https://libtmux.org/en/ts/latest/mcp/tools/#tools-coordination) [signal​_channel](https://libtmux.org/en/ts/latest/mcp/tools/signal_channel/) Change tmux state; no client-supplied executable input. Signal a tmux [wait-for](https://libtmux.org/en/tmux/latest/manual/wait-for/) channel. [wait​_for​_channel](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_channel/) Change tmux state; no client-supplied executable input. Wait until a tmux [wait-for](https://libtmux.org/en/tmux/latest/manual/wait-for/) channel is signalled. ## Other tools3 tools[#](https://libtmux.org/en/ts/latest/mcp/tools/#tools-other-tools) [call​_read​_tools​_batch](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/) Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Invoke a serial batch of at most 16 inspect tools. One client approval covers every nested name; inner tools receive no separate approval. The structured result is capped below 1,000,000 bytes, preserves every operation row, and reports explicit stop and truncation accounting. [get​_tmux​_variables](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/) Read configured tmux commands; accepts no client-supplied executable input. Returned values may contain executable configuration. Resolve validated tmux variable names without accepting raw format syntax. [wait​_for​_text](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/) Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Wait until a pane prints something, streaming tmux’s notifications rather than polling. Use for output you did NOT author — another process, a person, a background job. For a command you wrote, use [run_shell_command](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/): it knows when the command ended and reports exit status, which no text match can. This discounts text this server itself typed into the pane, for as long as it is unsubmitted or was submitted within the last ten seconds, so a command you just sent cannot match its own echo — but a pane not yet reading input can still echo type-ahead back once it starts, so wait for a prompt before typing into a cold shell. Whatever happens you get back what the pane printed and why the wait ended — a timeout is never an empty answer. ## [Resources](https://libtmux.org/en/ts/latest/mcp/resources/#resources-fixed-resources) 1 advertised in the reference configuration. ## [Resource templates](https://libtmux.org/en/ts/latest/mcp/resources/) This server does not advertise resource templates in the reference configuration. ## [Prompts](https://libtmux.org/en/ts/latest/mcp/prompts/) This server does not advertise prompts 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/ts/latest/mcp/tools.json). Source: [`libtmux/libtmux-ts@46cccfef2a54`](https://github.com/libtmux/libtmux-ts/tree/46cccfef2a546de55ce8b308249b8c76339089a0). The [language API reference](https://libtmux.org/en/ts/latest/mcp/reference/) documents embedding and implementation types. Source revision: [libtmux/libtmux-ts@ecc3eaca0b4e05a77360da9d56790b409282c63b](https://github.com/libtmux/libtmux-ts/tree/ecc3eaca0b4e05a77360da9d56790b409282c63b). --- # call_read_tools_batch Source: https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/ > Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Invoke a serial batch of at most 16 inspect tools. One client approval covers every nested name; inner tools receive no separate approval. The structured result is capped below 1,000,000 bytes, preserves every operation row, and reports explicit stop and truncation accounting. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **call_read_tools_batch**( [onError](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2FonError)?: "stop" | "continue", [operations](https://libtmux.org/en/ts/latest/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)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>, ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L618)][¶](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch) Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Invoke a serial batch of at most 16 inspect tools. One client approval covers every nested name; inner tools receive no separate approval. The structured result is capped below 1,000,000 bytes, preserves every operation row, and reports explicit stop and truncation accounting. * MCP request method `tools/call` Send `call_read_tools_batch` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.parameters) * **[`onError`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2FonError)**? ("stop" | "continue") Whether a failed operation ends the batch. Defaults to stop. * **[`operations`](https://libtmux.org/en/ts/latest/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)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")>) The read-only tool calls to run, in order, in one approval. * minItems `1` * maxItems `16` - **[Items](https://libtmux.org/en/ts/latest/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)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") | [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Matches one or more variants. * **[Variant 1](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F0)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F0%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`list_sessions`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/), exactly the shape it takes when called on its own. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F0%2Fproperties%2Ftool)** ("list_sessions") Run [`list_sessions`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/) as this step of the batch. No other properties are accepted. * **[Variant 2](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F1)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F1%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`list_windows`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/), exactly the shape it takes when called on its own. * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F1%2Fproperties%2Farguments%2Fproperties%2Fsession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id ($1) or name. Omit for all sessions. No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F1%2Fproperties%2Ftool)** ("list_windows") Run [`list_windows`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/) as this step of the batch. No other properties are accepted. * **[Variant 3](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F2)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F2%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`list_panes`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/), exactly the shape it takes when called on its own. * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F2%2Fproperties%2Farguments%2Fproperties%2Fsession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id ($1) or name. * **[`window`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F2%2Fproperties%2Farguments%2Fproperties%2Fwindow)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F2%2Fproperties%2Ftool)** ("list_panes") Run [`list_panes`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/) as this step of the batch. No other properties are accepted. * **[Variant 4](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F3)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F3%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`get_pane_info`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/), exactly the shape it takes when called on its own. * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F3%2Fproperties%2Farguments%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F3%2Fproperties%2Ftool)** ("get_pane_info") Run [`get_pane_info`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/) as this step of the batch. No other properties are accepted. * **[Variant 5](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F4)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F4%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`get_server_info`](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/), exactly the shape it takes when called on its own. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F4%2Fproperties%2Ftool)** ("get_server_info") Run [`get_server_info`](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/) as this step of the batch. No other properties are accepted. * **[Variant 6](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F5)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F5%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`capture_pane`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/), exactly the shape it takes when called on its own. * **[`end`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F5%2Fproperties%2Farguments%2Fproperties%2Fend)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Last line, on the same scale as start: 0 is the top of the visible screen and negative reaches back into history. It does not count back from the bottom, so end:-1 is one line above the screen top, not the last line of output. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`joinWrapped`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F5%2Fproperties%2Farguments%2Fproperties%2FjoinWrapped)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Rejoin lines tmux wrapped. * **[`maxLines`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F5%2Fproperties%2Farguments%2Fproperties%2FmaxLines)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Keep at most this many lines, from the end. Defaults to the server limit. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F5%2Fproperties%2Farguments%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`start`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F5%2Fproperties%2Farguments%2Fproperties%2Fstart)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) First line; negative reaches into scrollback. * minimum `-9007199254740991` * maximum `9007199254740991` No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F5%2Fproperties%2Ftool)** ("capture_pane") Run [`capture_pane`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/) as this step of the batch. No other properties are accepted. * **[Variant 7](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F6)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F6%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`capture_since`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/), exactly the shape it takes when called on its own. * **[`cursor`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F6%2Fproperties%2Farguments%2Fproperties%2Fcursor)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The cursor from your previous [capture_since](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/). Omit on the first call. * pattern `"^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$"` * **[`maxLines`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F6%2Fproperties%2Farguments%2Fproperties%2FmaxLines)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Keep at most this many lines, from the end. Defaults to the server limit. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F6%2Fproperties%2Farguments%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`waitMs`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F6%2Fproperties%2Farguments%2Fproperties%2FwaitMs)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Wait up to this long for new output before answering. Default 0. * minimum `0` * maximum `9007199254740991` No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F6%2Fproperties%2Ftool)** ("capture_since") Run [`capture_since`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/) as this step of the batch. No other properties are accepted. * **[Variant 8](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F7)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F7%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`search_panes`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/), exactly the shape it takes when called on its own. * **[`maxMatchesPerPane`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F7%2Fproperties%2Farguments%2Fproperties%2FmaxMatchesPerPane)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Stop after this many matches in each pane. Defaults to the server limit. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`pattern`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F7%2Fproperties%2Farguments%2Fproperties%2Fpattern)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Non-empty literal text to find. * minLength `1` * **[`regex`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F7%2Fproperties%2Farguments%2Fproperties%2Fregex)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Interpret pattern using libtmux’s bounded regular-expression grammar. * **[`scrollbackLines`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F7%2Fproperties%2Farguments%2Fproperties%2FscrollbackLines)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) How far above the visible screen to search. Default 0. * minimum `0` * maximum `9007199254740991` * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F7%2Fproperties%2Farguments%2Fproperties%2Fsession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Restrict to one session by id or name. No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F7%2Fproperties%2Ftool)** ("search_panes") Run [`search_panes`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/) as this step of the batch. No other properties are accepted. * **[Variant 9](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F8)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F8%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`show_option`](https://libtmux.org/en/ts/latest/mcp/tools/show_option/), exactly the shape it takes when called on its own. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F8%2Fproperties%2Farguments%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The tmux option to read, such as “status-left”. * **[`scope`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F8%2Fproperties%2Farguments%2Fproperties%2Fscope)**? ("server" | "session" | "global-session" | "window" | "global-window" | "pane") Default server. * **[`target`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F8%2Fproperties%2Farguments%2Fproperties%2Ftarget)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id/name or pane id, for the matching scope. No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F8%2Fproperties%2Ftool)** ("show_option") Run [`show_option`](https://libtmux.org/en/ts/latest/mcp/tools/show_option/) as this step of the batch. No other properties are accepted. * **[Variant 10](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F9)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F9%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`show_hooks`](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/), exactly the shape it takes when called on its own. * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F9%2Fproperties%2Farguments%2Fproperties%2Fsession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session scope; omit for server scope. No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F9%2Fproperties%2Ftool)** ("show_hooks") Run [`show_hooks`](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/) as this step of the batch. No other properties are accepted. * **[Variant 11](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F10)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F10%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`show_environment`](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/), exactly the shape it takes when called on its own. * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F10%2Fproperties%2Farguments%2Fproperties%2Fsession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id ($1) or name. Omit for the server environment. No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F10%2Fproperties%2Ftool)** ("show_environment") Run [`show_environment`](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/) as this step of the batch. No other properties are accepted. * **[Variant 12](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F11)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F11%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`get_session_info`](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/), exactly the shape it takes when called on its own. * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F11%2Fproperties%2Farguments%2Fproperties%2Fsession)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id ($1) or name. No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F11%2Fproperties%2Ftool)** ("get_session_info") Run [`get_session_info`](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/) as this step of the batch. No other properties are accepted. * **[Variant 13](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F12)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F12%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`get_window_info`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/), exactly the shape it takes when called on its own. * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F12%2Fproperties%2Farguments%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F12%2Fproperties%2Ftool)** ("get_window_info") Run [`get_window_info`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/) as this step of the batch. No other properties are accepted. * **[Variant 14](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F13)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F13%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`find_pane_by_position`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/), exactly the shape it takes when called on its own. * **[`corner`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F13%2Fproperties%2Farguments%2Fproperties%2Fcorner)** ("top-left" | "top-right" | "bottom-left" | "bottom-right") Which corner of the window’s layout to resolve. * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F13%2Fproperties%2Farguments%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F13%2Fproperties%2Ftool)** ("find_pane_by_position") Run [`find_pane_by_position`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/) as this step of the batch. No other properties are accepted. * **[Variant 15](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F14)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F14%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`get_tmux_variables`](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/), exactly the shape it takes when called on its own. * **[`names`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F14%2Fproperties%2Farguments%2Fproperties%2Fnames)** ([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)")>) Variable names to resolve, such as “pane_current_command” — bare names, not `#{…}` format syntax. * minItems `1` * maxItems `32` - **[Items](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F14%2Fproperties%2Farguments%2Fproperties%2Fnames%2Fitems)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * pattern `"^[A-Za-z][A-Za-z0-9_]*$"` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F14%2Fproperties%2Farguments%2Fproperties%2FpaneId)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F14%2Fproperties%2Ftool)** ("get_tmux_variables") Run [`get_tmux_variables`](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/) as this step of the batch. No other properties are accepted. * **[Variant 16](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F15)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`arguments`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F15%2Fproperties%2Farguments)**? ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) Arguments for [`snapshot_pane`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/), exactly the shape it takes when called on its own. * **[`maxLines`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F15%2Fproperties%2Farguments%2Fproperties%2FmaxLines)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Keep at most this many lines, from the end. Defaults to the server limit. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F15%2Fproperties%2Farguments%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` No other properties are accepted. * **[`tool`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.input%2Fproperties%2Foperations%2Fitems%2FanyOf%2F15%2Fproperties%2Ftool)** ("snapshot_pane") Run [`snapshot_pane`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/) as this step of the batch. No other properties are accepted. ## Result[#](https://libtmux.org/en/ts/latest/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/ts/latest/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)")) * minimum `0` * maximum `9007199254740991` * **[`onError`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2FonError)** ("stop" | "continue") * **[`results`](https://libtmux.org/en/ts/latest/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)")>) * **[Items](https://libtmux.org/en/ts/latest/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)")) * **[`error`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Ferror)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/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)")) * minimum `0` * maximum `9007199254740991` * **[`result`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fresult)** ([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)")) Matches one or more variants. * **[Variant 1](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fresult%2FanyOf%2F0)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`content`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fresult%2FanyOf%2F0%2Fproperties%2Fcontent)** ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")\) * **[`isError`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fresult%2FanyOf%2F0%2Fproperties%2FisError)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`structuredContent`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2Fresult%2FanyOf%2F0%2Fproperties%2FstructuredContent)**? ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\) * **[`resultTruncated`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Fresults%2Fitems%2Fproperties%2FresultTruncated)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`success`](https://libtmux.org/en/ts/latest/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)")) * **[`tool`](https://libtmux.org/en/ts/latest/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)")) No other properties are accepted. * **[`stoppedAt`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2FstoppedAt)** ([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)")) Matches one or more variants. * **[Variant 1](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2FstoppedAt%2FanyOf%2F0)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `0` * maximum `9007199254740991` * **[`succeeded`](https://libtmux.org/en/ts/latest/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)")) * minimum `0` * maximum `9007199254740991` * **[`truncated`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2Ftruncated)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`truncatedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.output%2Fproperties%2FtruncatedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `0` * maximum `9007199254740991` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/call_read_tools_batch/#mcp.tool.call_read_tools_batch.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/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 { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "onError": { "description": "Whether a failed operation ends the batch. Defaults to stop.", "enum": [ "stop", "continue" ], "type": "string" }, "operations": { "description": "The read-only tool calls to run, in order, in one approval.", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `list_sessions`, exactly the shape it takes when called on its own.", "properties": {}, "type": "object" }, "tool": { "const": "list_sessions", "description": "Run `list_sessions` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `list_windows`, exactly the shape it takes when called on its own.", "properties": { "session": { "description": "Session id ($1) or name. Omit for all sessions.", "type": "string" } }, "type": "object" }, "tool": { "const": "list_windows", "description": "Run `list_windows` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `list_panes`, exactly the shape it takes when called on its own.", "properties": { "session": { "description": "Session id ($1) or name.", "type": "string" }, "window": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "type": "object" }, "tool": { "const": "list_panes", "description": "Run `list_panes` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `get_pane_info`, exactly the shape it takes when called on its own.", "properties": { "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "paneId" ], "type": "object" }, "tool": { "const": "get_pane_info", "description": "Run `get_pane_info` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `get_server_info`, exactly the shape it takes when called on its own.", "properties": {}, "type": "object" }, "tool": { "const": "get_server_info", "description": "Run `get_server_info` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `capture_pane`, exactly the shape it takes when called on its own.", "properties": { "end": { "description": "Last line, on the same scale as start: 0 is the top of the visible screen and negative reaches back into history. It does not count back from the bottom, so end:-1 is one line above the screen top, not the last line of output.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "joinWrapped": { "description": "Rejoin lines tmux wrapped.", "type": "boolean" }, "maxLines": { "description": "Keep at most this many lines, from the end. Defaults to the server limit.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "start": { "description": "First line; negative reaches into scrollback.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "paneId" ], "type": "object" }, "tool": { "const": "capture_pane", "description": "Run `capture_pane` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `capture_since`, exactly the shape it takes when called on its own.", "properties": { "cursor": { "description": "The cursor from your previous capture_since. Omit on the first call.", "pattern": "^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$", "type": "string" }, "maxLines": { "description": "Keep at most this many lines, from the end. Defaults to the server limit.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "waitMs": { "description": "Wait up to this long for new output before answering. Default 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" } }, "required": [ "paneId" ], "type": "object" }, "tool": { "const": "capture_since", "description": "Run `capture_since` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `search_panes`, exactly the shape it takes when called on its own.", "properties": { "maxMatchesPerPane": { "description": "Stop after this many matches in each pane. Defaults to the server limit.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "pattern": { "description": "Non-empty literal text to find.", "minLength": 1, "type": "string" }, "regex": { "description": "Interpret pattern using libtmux's bounded regular-expression grammar.", "type": "boolean" }, "scrollbackLines": { "description": "How far above the visible screen to search. Default 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "session": { "description": "Restrict to one session by id or name.", "type": "string" } }, "required": [ "pattern" ], "type": "object" }, "tool": { "const": "search_panes", "description": "Run `search_panes` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `show_option`, exactly the shape it takes when called on its own.", "properties": { "name": { "description": "The tmux option to read, such as \"status-left\".", "type": "string" }, "scope": { "description": "Default server.", "enum": [ "server", "session", "global-session", "window", "global-window", "pane" ], "type": "string" }, "target": { "description": "Session id/name or pane id, for the matching scope.", "type": "string" } }, "required": [ "name" ], "type": "object" }, "tool": { "const": "show_option", "description": "Run `show_option` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `show_hooks`, exactly the shape it takes when called on its own.", "properties": { "session": { "description": "Session scope; omit for server scope.", "type": "string" } }, "type": "object" }, "tool": { "const": "show_hooks", "description": "Run `show_hooks` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `show_environment`, exactly the shape it takes when called on its own.", "properties": { "session": { "description": "Session id ($1) or name. Omit for the server environment.", "type": "string" } }, "type": "object" }, "tool": { "const": "show_environment", "description": "Run `show_environment` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `get_session_info`, exactly the shape it takes when called on its own.", "properties": { "session": { "description": "Session id ($1) or name.", "type": "string" } }, "required": [ "session" ], "type": "object" }, "tool": { "const": "get_session_info", "description": "Run `get_session_info` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `get_window_info`, exactly the shape it takes when called on its own.", "properties": { "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "windowId" ], "type": "object" }, "tool": { "const": "get_window_info", "description": "Run `get_window_info` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `find_pane_by_position`, exactly the shape it takes when called on its own.", "properties": { "corner": { "description": "Which corner of the window's layout to resolve.", "enum": [ "top-left", "top-right", "bottom-left", "bottom-right" ], "type": "string" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "corner", "windowId" ], "type": "object" }, "tool": { "const": "find_pane_by_position", "description": "Run `find_pane_by_position` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `get_tmux_variables`, exactly the shape it takes when called on its own.", "properties": { "names": { "description": "Variable names to resolve, such as \"pane_current_command\" — bare names, not `#{…}` format syntax.", "items": { "pattern": "^[A-Za-z][A-Za-z0-9_]*$", "type": "string" }, "maxItems": 32, "minItems": 1, "type": "array", "x-libtmux-tmux-format": "validated-variable-name" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "names" ], "type": "object" }, "tool": { "const": "get_tmux_variables", "description": "Run `get_tmux_variables` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" }, { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": false, "description": "Arguments for `snapshot_pane`, exactly the shape it takes when called on its own.", "properties": { "maxLines": { "description": "Keep at most this many lines, from the end. Defaults to the server limit.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "paneId" ], "type": "object" }, "tool": { "const": "snapshot_pane", "description": "Run `snapshot_pane` as this step of the batch.", "type": "string" } }, "required": [ "tool" ], "type": "object" } ] }, "maxItems": 16, "minItems": 1, "type": "array" } }, "required": [ "operations" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "failed": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "onError": { "enum": [ "stop", "continue" ], "type": "string" }, "results": { "items": { "additionalProperties": false, "properties": { "error": { "type": [ "string", "null" ] }, "index": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "result": { "anyOf": [ { "additionalProperties": {}, "properties": { "content": { "items": {}, "type": "array" }, "isError": { "type": "boolean" }, "structuredContent": { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" } }, "required": [ "content" ], "type": "object" }, { "type": "null" } ] }, "resultTruncated": { "type": "boolean" }, "success": { "type": "boolean" }, "tool": { "type": "string" } }, "required": [ "error", "index", "result", "resultTruncated", "success", "tool" ], "type": "object" }, "type": "array" }, "stoppedAt": { "anyOf": [ { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "succeeded": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "truncated": { "type": "boolean" }, "truncatedBytes": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" } }, "required": [ "failed", "onError", "results", "stoppedAt", "succeeded", "truncated", "truncatedBytes" ], "type": "object" } ``` --- # capture_pane Source: https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/ > Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. The text a pane is showing, or its scrollback. Negative start reaches back into history (-100 is a hundred lines above the top of the screen). For repeated reads of the same pane use capture_since instead — it returns only what is new. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **capture_pane**( [end](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fend)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [joinWrapped](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2FjoinWrapped)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [maxLines](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2FmaxLines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [paneId](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [start](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fstart)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/capture.ts#L27)][¶](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane) Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. The text a pane is showing, or its scrollback. Negative `start` reaches back into history (-100 is a hundred lines above the top of the screen). For repeated reads of the same pane use [capture_since](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/) instead — it returns only what is new. * MCP request method `tools/call` Send `capture_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.parameters) * **[`end`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fend)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Last line, on the same scale as start: 0 is the top of the visible screen and negative reaches back into history. It does not count back from the bottom, so end:-1 is one line above the screen top, not the last line of output. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`joinWrapped`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2FjoinWrapped)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Rejoin lines tmux wrapped. * **[`maxLines`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2FmaxLines)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Keep at most this many lines, from the end. Defaults to the server limit. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`start`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.input%2Fproperties%2Fstart)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) First line; negative reaches into scrollback. * minimum `-9007199254740991` * maximum `9007199254740991` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`byteClamped`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.output%2Fproperties%2FbyteClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether the byte ceiling shortened the capture. * **[`droppedLines`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.output%2Fproperties%2FdroppedLines)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Lines cut from the front to fit maxLines. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`effectiveEnd`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.output%2Fproperties%2FeffectiveEnd)** ([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)")) Matches one or more variants. * **[Variant 1](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.output%2Fproperties%2FeffectiveEnd%2FanyOf%2F0)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`effectiveStart`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.output%2Fproperties%2FeffectiveStart)** ([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)")) Matches one or more variants. * **[Variant 1](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.output%2Fproperties%2FeffectiveStart%2FanyOf%2F0)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`omittedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.output%2Fproperties%2FomittedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.output%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`rangeClamped`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.output%2Fproperties%2FrangeClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether a result ceiling shortened the range. * **[`returnedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.output%2Fproperties%2FreturnedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`text`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.output%2Fproperties%2Ftext)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`totalLines`](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.output%2Fproperties%2FtotalLines)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) How many lines the capture held before trimming. * minimum `-9007199254740991` * maximum `9007199254740991` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/#mcp.tool.capture_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "end": { "description": "Last line, on the same scale as start: 0 is the top of the visible screen and negative reaches back into history. It does not count back from the bottom, so end:-1 is one line above the screen top, not the last line of output.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "joinWrapped": { "description": "Rejoin lines tmux wrapped.", "type": "boolean" }, "maxLines": { "description": "Keep at most this many lines, from the end. Defaults to the server limit.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "start": { "description": "First line; negative reaches into scrollback.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "byteClamped": { "description": "Whether the byte ceiling shortened the capture.", "type": "boolean" }, "droppedLines": { "description": "Lines cut from the front to fit maxLines.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "effectiveEnd": { "anyOf": [ { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, { "type": "null" } ] }, "effectiveStart": { "anyOf": [ { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, { "type": "null" } ] }, "omittedBytes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "rangeClamped": { "description": "Whether a result ceiling shortened the range.", "type": "boolean" }, "returnedBytes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "text": { "type": "string" }, "totalLines": { "description": "How many lines the capture held before trimming.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "byteClamped", "droppedLines", "effectiveEnd", "effectiveStart", "omittedBytes", "paneId", "rangeClamped", "returnedBytes", "text", "totalLines" ], "type": "object" } ``` --- # capture_since Source: https://libtmux.org/en/ts/latest/mcp/tools/capture_since/ > Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. What a pane has printed since you last looked. Call it once with no cursor to start watching and get the current screen; keep the cursor it returns and pass it back each time after that, and you are charged only for what is new. This is the tool for watching a build, a log, or a test run — not a capture_pane loop. Set waitMs to block until something arrives rather than returning empty. Reports the stream in the order it was written, so a program that draws by moving the cursor (a progress bar, a full-screen TUI) reads jumbled here — capture_pane renders those. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **capture_since**( [cursor](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fcursor)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [maxLines](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2FmaxLines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [paneId](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [waitMs](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2FwaitMs)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/capture.ts#L132)][¶](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since) Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. What a pane has printed since you last looked. Call it once with no cursor to start watching and get the current screen; keep the cursor it returns and pass it back each time after that, and you are charged only for what is new. This is the tool for watching a build, a log, or a test run — not a [capture_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/) loop. Set waitMs to block until something arrives rather than returning empty. Reports the stream in the order it was written, so a program that draws by moving the cursor (a progress bar, a full-screen TUI) reads jumbled here — [capture_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/) renders those. * MCP request method `tools/call` Send `capture_since` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.parameters) * **[`cursor`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2Fcursor)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The cursor from your previous capture_since. Omit on the first call. * pattern `"^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$"` * **[`maxLines`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2FmaxLines)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Keep at most this many lines, from the end. Defaults to the server limit. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`waitMs`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.input%2Fproperties%2FwaitMs)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Wait up to this long for new output before answering. Default 0. * minimum `0` * maximum `9007199254740991` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`byteClamped`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%2Fproperties%2FbyteClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether the byte ceiling shortened this result. * **[`cursor`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%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)")) Pass this to the next capture_since call; null means streaming was unavailable. Matches one or more variants. * **[Variant 1](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%2Fproperties%2Fcursor%2FanyOf%2F0)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * pattern `"^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$"` * **[`droppedLines`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%2Fproperties%2FdroppedLines)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`effectiveTimeoutMs`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%2Fproperties%2FeffectiveTimeoutMs)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The wait ceiling applied; zero when this call did not wait on a live stream. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`missedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%2Fproperties%2FmissedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Output that scrolled past before this read reached it. Non-zero means you fell behind. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`omittedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%2Fproperties%2FomittedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Result bytes omitted after capture or streaming. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`rangeClamped`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%2Fproperties%2FrangeClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether result limits shortened a grid capture. * **[`returnedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%2Fproperties%2FreturnedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`seeded`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%2Fproperties%2Fseeded)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) True when this call started the watch and returned the screen. * **[`streaming`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%2Fproperties%2Fstreaming)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) False when no control connection was available and this fell back to capturing. * **[`text`](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.output%2Fproperties%2Ftext)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/#mcp.tool.capture_since.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "cursor": { "description": "The cursor from your previous capture_since. Omit on the first call.", "pattern": "^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$", "type": "string" }, "maxLines": { "description": "Keep at most this many lines, from the end. Defaults to the server limit.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "waitMs": { "description": "Wait up to this long for new output before answering. Default 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" } }, "required": [ "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "byteClamped": { "description": "Whether the byte ceiling shortened this result.", "type": "boolean" }, "cursor": { "anyOf": [ { "pattern": "^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$", "type": "string" }, { "type": "null" } ], "description": "Pass this to the next capture_since call; null means streaming was unavailable." }, "droppedLines": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "effectiveTimeoutMs": { "description": "The wait ceiling applied; zero when this call did not wait on a live stream.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "missedBytes": { "description": "Output that scrolled past before this read reached it. Non-zero means you fell behind.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "omittedBytes": { "description": "Result bytes omitted after capture or streaming.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "rangeClamped": { "description": "Whether result limits shortened a grid capture.", "type": "boolean" }, "returnedBytes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "seeded": { "description": "True when this call started the watch and returned the screen.", "type": "boolean" }, "streaming": { "description": "False when no control connection was available and this fell back to capturing.", "type": "boolean" }, "text": { "type": "string" } }, "required": [ "byteClamped", "cursor", "droppedLines", "effectiveTimeoutMs", "missedBytes", "paneId", "omittedBytes", "rangeClamped", "returnedBytes", "seeded", "streaming", "text" ], "type": "object" } ``` --- # clear_pane_scrollback Source: https://libtmux.org/en/ts/latest/mcp/tools/clear_pane_scrollback/ > Delete tmux state; accepts no command payload. Discard the retained scrollback history for one pane. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **clear_pane_scrollback**( [paneId](https://libtmux.org/en/ts/latest/mcp/tools/clear_pane_scrollback/#mcp.tool.clear_pane_scrollback.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L575)][¶](https://libtmux.org/en/ts/latest/mcp/tools/clear_pane_scrollback/#mcp.tool.clear_pane_scrollback) Delete tmux state; accepts no command payload. Discard the retained scrollback history for one pane. * MCP request method `tools/call` Send `clear_pane_scrollback` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/clear_pane_scrollback/#mcp.tool.clear_pane_scrollback.parameters) * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/clear_pane_scrollback/#mcp.tool.clear_pane_scrollback.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/clear_pane_scrollback/#mcp.tool.clear_pane_scrollback.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`cleared`](https://libtmux.org/en/ts/latest/mcp/tools/clear_pane_scrollback/#mcp.tool.clear_pane_scrollback.output%2Fproperties%2Fcleared)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/clear_pane_scrollback/#mcp.tool.clear_pane_scrollback.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/clear_pane_scrollback/#mcp.tool.clear_pane_scrollback.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "cleared": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "cleared" ], "type": "object" } ``` --- # create_session Source: https://libtmux.org/en/ts/latest/mcp/tools/create_session/ > Start a pane's configured process; accepts no command payload. Create a detached session and return it with its first window and pane, so you can start working without listing anything first. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **create_session**( [height](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fheight)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [name](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fname)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [startDirectory](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2FstartDirectory)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [width](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fwidth)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [windowName](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2FwindowName)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/lifecycle.ts#L68)][¶](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session) Start a pane’s configured process; accepts no command payload. Create a detached session and return it with its first window and pane, so you can start working without listing anything first. * MCP request method `tools/call` Send `create_session` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.parameters) * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fheight)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Rows. Default 24, because a detached session has no client to size it. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fname)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session name; tmux picks a number when omitted. * **[`startDirectory`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2FstartDirectory)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Working directory for the first pane. Defaults to the server’s. * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fwidth)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Columns. Default 80, and a program that formats to its terminal width — ps, git log —graph, docker ps — truncates to that at the source, where no capture option can recover it. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2FwindowName)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Name for the first window, so the session does not open with a stray shell. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The new session’s first pane. Target this. * pattern `"^%\\d+$"` * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`attachedClients`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession%2Fproperties%2FattachedClients)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Raw client count from tmux; 0 means detached. Includes control-mode clients - this server’s own [wait_for_text](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/) or other live read holds one open while it runs, and another program on this socket may hold others. See humanAttachedClients for a person-only count. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`humanAttachedClients`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession%2Fproperties%2FhumanAttachedClients)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) attachedClients minus every control-mode client, this server’s own included. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether the session name is complete. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from the session name. * minimum `0` * maximum `9007199254740991` * **[`windows`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession%2Fproperties%2Fwindows)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) How many windows it holds. * minimum `-9007199254740991` * maximum `9007199254740991` No other properties are accepted. * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/create_session/#mcp.tool.create_session.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "height": { "description": "Rows. Default 24, because a detached session has no client to size it.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "name": { "description": "Session name; tmux picks a number when omitted.", "type": "string", "x-libtmux-tmux-format": "literalized-once" }, "startDirectory": { "description": "Working directory for the first pane. Defaults to the server's.", "type": "string", "x-libtmux-tmux-format": "literalized-once" }, "width": { "description": "Columns. Default 80, and a program that formats to its terminal width — ps, git log --graph, docker ps — truncates to that at the source, where no capture option can recover it.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "windowName": { "description": "Name for the first window, so the session does not open with a stray shell.", "type": "string", "x-libtmux-tmux-format": "literalized-once" } }, "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "paneId": { "description": "The new session's first pane. Target this.", "pattern": "^%\\d+$", "type": "string" }, "session": { "additionalProperties": false, "properties": { "attachedClients": { "description": "Raw client count from tmux; 0 means detached. Includes control-mode clients - this server's own wait_for_text or other live read holds one open while it runs, and another program on this socket may hold others. See humanAttachedClients for a person-only count.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "humanAttachedClients": { "description": "attachedClients minus every control-mode client, this server's own included.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "metadataComplete": { "description": "Whether the session name is complete.", "type": "boolean" }, "name": { "type": "string" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from the session name.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "windows": { "description": "How many windows it holds.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "attachedClients", "humanAttachedClients", "id", "metadataComplete", "name", "omittedMetadataBytes", "windows" ], "type": "object" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "paneId", "session", "windowId" ], "type": "object" } ``` --- # create_window Source: https://libtmux.org/en/ts/latest/mcp/tools/create_window/ > Start a pane's configured process; accepts no command payload. Add a window to a session and return it with its pane. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **create_window**( [name](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fname)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [session](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fsession): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [startDirectory](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2FstartDirectory)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/lifecycle.ts#L147)][¶](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window) Start a pane’s configured process; accepts no command payload. Add a window to a session and return it with its pane. * MCP request method `tools/call` Send `create_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.parameters) * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fname)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Name for the new window. * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2Fsession)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id ($1) or name. * **[`startDirectory`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.input%2Fproperties%2FstartDirectory)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Working directory for the new pane. Defaults to the session’s. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`window`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`layout`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2Flayout)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) tmux’s layout string; feed it back only when metadataComplete is true. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`panes`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2Fpanes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements)** ([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)")>) Retained sessions and indexes where this window is linked. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this placement is current in its session. * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`zoomed`](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.output%2Fproperties%2Fwindow%2Fproperties%2Fzoomed)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/create_window/#mcp.tool.create_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "name": { "description": "Name for the new window.", "type": "string", "x-libtmux-tmux-format": "literalized-once" }, "session": { "description": "Session id ($1) or name.", "type": "string" }, "startDirectory": { "description": "Working directory for the new pane. Defaults to the session's.", "type": "string", "x-libtmux-tmux-format": "literalized-once" } }, "required": [ "session" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "window": { "additionalProperties": false, "properties": { "id": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "layout": { "description": "tmux's layout string; feed it back only when metadataComplete is true.", "type": "string" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "name": { "type": "string" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "panes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "placements": { "description": "Retained sessions and indexes where this window is linked.", "items": { "additionalProperties": false, "properties": { "active": { "description": "Whether this placement is current in its session.", "type": "boolean" }, "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName", "active" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "zoomed": { "type": "boolean" } }, "required": [ "id", "layout", "metadataComplete", "name", "omittedMetadataBytes", "panes", "omittedPlacements", "placements", "placementsComplete", "zoomed" ], "type": "object" } }, "required": [ "paneId", "window" ], "type": "object" } ``` --- # find_pane_by_position Source: https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/ > Inspect tmux metadata; accepts no client-supplied executable input. Find the pane occupying a named corner of a window. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **find_pane_by_position**( [corner](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fcorner): "top-left" | "top-right" | "bottom-left" | "bottom-right", [windowId](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2FwindowId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L233)][¶](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position) Inspect tmux metadata; accepts no client-supplied executable input. Find the pane occupying a named corner of a window. * MCP request method `tools/call` Send `find_pane_by_position` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.parameters) * **[`corner`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2Fcorner)** ("top-left" | "top-right" | "bottom-left" | "bottom-right") Which corner of the window’s layout to resolve. * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.input%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/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)") * **[`pane`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this is its window’s active pane. * **[`command`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The command tmux reports running in it. * **[`cwd`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Fcwd)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Its current working directory. * **[`dead`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Fdead)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether its process exited and remain-on-exit kept it. * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Fheight)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id. Prefer this for entity-scoped targeting. * pattern `"^%\\d+$"` * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`isAttended`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2FisAttended)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) A person is currently looking at this pane. * **[`isCallerPane`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2FisCallerPane)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) This is the pane this MCP server runs in. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Fplacements)** ([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)")>) Retained session and window indexes through which this pane is reachable. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`title`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Ftitle)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2Fwidth)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.output%2Fproperties%2Fpane%2Fproperties%2FwindowName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/find_pane_by_position/#mcp.tool.find_pane_by_position.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/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 { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "corner": { "description": "Which corner of the window's layout to resolve.", "enum": [ "top-left", "top-right", "bottom-left", "bottom-right" ], "type": "string" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "corner", "windowId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "pane": { "additionalProperties": false, "properties": { "active": { "description": "Whether this is its window's active pane.", "type": "boolean" }, "command": { "description": "The command tmux reports running in it.", "type": "string" }, "cwd": { "description": "Its current working directory.", "type": "string" }, "dead": { "description": "Whether its process exited and remain-on-exit kept it.", "type": "boolean" }, "height": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable pane id. Prefer this for entity-scoped targeting.", "pattern": "^%\\d+$", "type": "string" }, "index": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "isAttended": { "description": "A person is currently looking at this pane.", "type": "boolean" }, "isCallerPane": { "description": "This is the pane this MCP server runs in.", "type": "boolean" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "placements": { "description": "Retained session and window indexes through which this pane is reachable.", "items": { "additionalProperties": false, "properties": { "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "title": { "type": "string" }, "width": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "windowName": { "type": "string" } }, "required": [ "active", "command", "cwd", "dead", "height", "id", "index", "isAttended", "isCallerPane", "metadataComplete", "omittedMetadataBytes", "omittedPlacements", "placements", "placementsComplete", "title", "width", "windowId", "windowName" ], "type": "object" } }, "required": [ "pane" ], "type": "object" } ``` --- # get_pane_info Source: https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/ > Inspect tmux metadata; accepts no client-supplied executable input. One pane's metadata: what it runs, where, how big, and whether it is yours or watched. Does not read its contents — capture_pane does that. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **get_pane_info**( [paneId](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/discovery.ts#L196)][¶](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info) Inspect tmux metadata; accepts no client-supplied executable input. One pane’s metadata: what it runs, where, how big, and whether it is yours or watched. Does not read its contents — [capture_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/) does that. * MCP request method `tools/call` Send `get_pane_info` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.parameters) * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/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)") * **[`pane`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this is its window’s active pane. * **[`command`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The command tmux reports running in it. * **[`cwd`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Fcwd)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Its current working directory. * **[`dead`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Fdead)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether its process exited and remain-on-exit kept it. * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Fheight)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id. Prefer this for entity-scoped targeting. * pattern `"^%\\d+$"` * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`isAttended`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2FisAttended)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) A person is currently looking at this pane. * **[`isCallerPane`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2FisCallerPane)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) This is the pane this MCP server runs in. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Fplacements)** ([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)")>) Retained session and window indexes through which this pane is reachable. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`title`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Ftitle)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2Fwidth)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.output%2Fproperties%2Fpane%2Fproperties%2FwindowName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/get_pane_info/#mcp.tool.get_pane_info.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "pane": { "additionalProperties": false, "properties": { "active": { "description": "Whether this is its window's active pane.", "type": "boolean" }, "command": { "description": "The command tmux reports running in it.", "type": "string" }, "cwd": { "description": "Its current working directory.", "type": "string" }, "dead": { "description": "Whether its process exited and remain-on-exit kept it.", "type": "boolean" }, "height": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable pane id. Prefer this for entity-scoped targeting.", "pattern": "^%\\d+$", "type": "string" }, "index": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "isAttended": { "description": "A person is currently looking at this pane.", "type": "boolean" }, "isCallerPane": { "description": "This is the pane this MCP server runs in.", "type": "boolean" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "placements": { "description": "Retained session and window indexes through which this pane is reachable.", "items": { "additionalProperties": false, "properties": { "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "title": { "type": "string" }, "width": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "windowName": { "type": "string" } }, "required": [ "active", "command", "cwd", "dead", "height", "id", "index", "isAttended", "isCallerPane", "metadataComplete", "omittedMetadataBytes", "omittedPlacements", "placements", "placementsComplete", "title", "width", "windowId", "windowName" ], "type": "object" } }, "required": [ "pane" ], "type": "object" } ``` --- # get_server_info Source: https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/ > Inspect tmux metadata; accepts no client-supplied executable input. The tmux server this process drives: its socket, version, daemon pid, and totals. Check the version before using a feature that needs a recent tmux. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **get_server_info**() tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/discovery.ts#L216)][¶](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/#mcp.tool.get_server_info) Inspect tmux metadata; accepts no client-supplied executable input. The tmux server this process drives: its socket, version, daemon pid, and totals. Check the version before using a feature that needs a recent tmux. * MCP request method `tools/call` Send `get_server_info` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/#mcp.tool.get_server_info.parameters) No named arguments. ## Result[#](https://libtmux.org/en/ts/latest/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)") * **[`panes`](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/#mcp.tool.get_server_info.output%2Fproperties%2Fpanes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`pid`](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/#mcp.tool.get_server_info.output%2Fproperties%2Fpid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) * **[`sessions`](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/#mcp.tool.get_server_info.output%2Fproperties%2Fsessions)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`socketPath`](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/#mcp.tool.get_server_info.output%2Fproperties%2FsocketPath)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) * **[`version`](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/#mcp.tool.get_server_info.output%2Fproperties%2Fversion)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`windows`](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/#mcp.tool.get_server_info.output%2Fproperties%2Fwindows)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/#mcp.tool.get_server_info.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/get_server_info/#mcp.tool.get_server_info.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": {}, "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "panes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "pid": { "type": [ "string", "null" ] }, "sessions": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "socketPath": { "type": [ "string", "null" ] }, "version": { "type": "string" }, "windows": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "panes", "pid", "sessions", "socketPath", "version", "windows" ], "type": "object" } ``` --- # get_session_info Source: https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/ > Inspect tmux metadata; accepts no client-supplied executable input. Return metadata for one session without listing every session. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **get_session_info**( [session](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.input%2Fproperties%2Fsession): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L190)][¶](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info) Inspect tmux metadata; accepts no client-supplied executable input. Return metadata for one session without listing every session. * MCP request method `tools/call` Send `get_session_info` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.parameters) * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.input%2Fproperties%2Fsession)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id ($1) or name. ## Result[#](https://libtmux.org/en/ts/latest/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)") * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fsession)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`attachedClients`](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fsession%2Fproperties%2FattachedClients)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Raw client count from tmux; 0 means detached. Includes control-mode clients - this server’s own [wait_for_text](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/) or other live read holds one open while it runs, and another program on this socket may hold others. See humanAttachedClients for a person-only count. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`humanAttachedClients`](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fsession%2Fproperties%2FhumanAttachedClients)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) attachedClients minus every control-mode client, this server’s own included. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fsession%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fsession%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether the session name is complete. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fsession%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fsession%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from the session name. * minimum `0` * maximum `9007199254740991` * **[`windows`](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.output%2Fproperties%2Fsession%2Fproperties%2Fwindows)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) How many windows it holds. * minimum `-9007199254740991` * maximum `9007199254740991` No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/get_session_info/#mcp.tool.get_session_info.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "session": { "description": "Session id ($1) or name.", "type": "string" } }, "required": [ "session" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "session": { "additionalProperties": false, "properties": { "attachedClients": { "description": "Raw client count from tmux; 0 means detached. Includes control-mode clients - this server's own wait_for_text or other live read holds one open while it runs, and another program on this socket may hold others. See humanAttachedClients for a person-only count.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "humanAttachedClients": { "description": "attachedClients minus every control-mode client, this server's own included.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "metadataComplete": { "description": "Whether the session name is complete.", "type": "boolean" }, "name": { "type": "string" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from the session name.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "windows": { "description": "How many windows it holds.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "attachedClients", "humanAttachedClients", "id", "metadataComplete", "name", "omittedMetadataBytes", "windows" ], "type": "object" } }, "required": [ "session" ], "type": "object" } ``` --- # get_tmux_variables Source: https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/ > Read configured tmux commands; accepts no client-supplied executable input. Returned values may contain executable configuration. Resolve validated tmux variable names without accepting raw format syntax. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **get_tmux_variables**( [names](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/#mcp.tool.get_tmux_variables.input%2Fproperties%2Fnames): [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)")>, [paneId](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/#mcp.tool.get_tmux_variables.input%2Fproperties%2FpaneId)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L263)][¶](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/#mcp.tool.get_tmux_variables) Read configured tmux commands; accepts no client-supplied executable input. Returned values may contain executable configuration. Resolve validated tmux variable names without accepting raw format syntax. * MCP request method `tools/call` Send `get_tmux_variables` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/#mcp.tool.get_tmux_variables.parameters) * **[`names`](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/#mcp.tool.get_tmux_variables.input%2Fproperties%2Fnames)** ([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)")>) Variable names to resolve, such as “pane_current_command” — bare names, not `#{…}` format syntax. * minItems `1` * maxItems `32` - **[Items](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/#mcp.tool.get_tmux_variables.input%2Fproperties%2Fnames%2Fitems)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * pattern `"^[A-Za-z][A-Za-z0-9_]*$"` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/#mcp.tool.get_tmux_variables.input%2Fproperties%2FpaneId)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/#mcp.tool.get_tmux_variables.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`values`](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/#mcp.tool.get_tmux_variables.output%2Fproperties%2Fvalues)** ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\) No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/#mcp.tool.get_tmux_variables.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/get_tmux_variables/#mcp.tool.get_tmux_variables.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "names": { "description": "Variable names to resolve, such as \"pane_current_command\" — bare names, not `#{…}` format syntax.", "items": { "pattern": "^[A-Za-z][A-Za-z0-9_]*$", "type": "string" }, "maxItems": 32, "minItems": 1, "type": "array", "x-libtmux-tmux-format": "validated-variable-name" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "names" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "values": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" } }, "required": [ "values" ], "type": "object" } ``` --- # get_window_info Source: https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/ > Inspect tmux metadata; accepts no client-supplied executable input. Return metadata and placements for one window. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **get_window_info**( [windowId](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.input%2Fproperties%2FwindowId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L216)][¶](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info) Inspect tmux metadata; accepts no client-supplied executable input. Return metadata and placements for one window. * MCP request method `tools/call` Send `get_window_info` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.parameters) * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.input%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/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)") * **[`window`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`layout`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2Flayout)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) tmux’s layout string; feed it back only when metadataComplete is true. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`panes`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2Fpanes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements)** ([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)")>) Retained sessions and indexes where this window is linked. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this placement is current in its session. * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`zoomed`](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.output%2Fproperties%2Fwindow%2Fproperties%2Fzoomed)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/get_window_info/#mcp.tool.get_window_info.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "windowId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "window": { "additionalProperties": false, "properties": { "id": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "layout": { "description": "tmux's layout string; feed it back only when metadataComplete is true.", "type": "string" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "name": { "type": "string" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "panes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "placements": { "description": "Retained sessions and indexes where this window is linked.", "items": { "additionalProperties": false, "properties": { "active": { "description": "Whether this placement is current in its session.", "type": "boolean" }, "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName", "active" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "zoomed": { "type": "boolean" } }, "required": [ "id", "layout", "metadataComplete", "name", "omittedMetadataBytes", "panes", "omittedPlacements", "placements", "placementsComplete", "zoomed" ], "type": "object" } }, "required": [ "window" ], "type": "object" } ``` --- # kill_pane Source: https://libtmux.org/en/ts/latest/mcp/tools/kill_pane/ > Delete tmux state; accepts no command payload. Close a pane and the process in it. Refuses the pane this server runs in and every pane a person is watching; force confirms only this server's exact caller pane. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **kill_pane**( [force](https://libtmux.org/en/ts/latest/mcp/tools/kill_pane/#mcp.tool.kill_pane.input%2Fproperties%2Fforce)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [paneId](https://libtmux.org/en/ts/latest/mcp/tools/kill_pane/#mcp.tool.kill_pane.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/lifecycle.ts#L323)][¶](https://libtmux.org/en/ts/latest/mcp/tools/kill_pane/#mcp.tool.kill_pane) Delete tmux state; accepts no command payload. Close a pane and the process in it. Refuses the pane this server runs in and every pane a person is watching; force confirms only this server’s exact caller pane. * MCP request method `tools/call` Send `kill_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/kill_pane/#mcp.tool.kill_pane.parameters) * **[`force`](https://libtmux.org/en/ts/latest/mcp/tools/kill_pane/#mcp.tool.kill_pane.input%2Fproperties%2Fforce)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Allow this to target the pane this server itself was called from, which is otherwise refused. It does not override the refusal to touch a pane a person is watching. * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/kill_pane/#mcp.tool.kill_pane.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/kill_pane/#mcp.tool.kill_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`killed`](https://libtmux.org/en/ts/latest/mcp/tools/kill_pane/#mcp.tool.kill_pane.output%2Fproperties%2Fkilled)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/kill_pane/#mcp.tool.kill_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/kill_pane/#mcp.tool.kill_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "force": { "description": "Allow this to target the pane this server itself was called from, which is otherwise refused. It does not override the refusal to touch a pane a person is watching.", "type": "boolean" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "killed": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "killed" ], "type": "object" } ``` --- # kill_session Source: https://libtmux.org/en/ts/latest/mcp/tools/kill_session/ > Delete tmux state; accepts no command payload. Remove a session. Windows and panes shared with another session remain available there. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **kill_session**( [force](https://libtmux.org/en/ts/latest/mcp/tools/kill_session/#mcp.tool.kill_session.input%2Fproperties%2Fforce)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [session](https://libtmux.org/en/ts/latest/mcp/tools/kill_session/#mcp.tool.kill_session.input%2Fproperties%2Fsession): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/lifecycle.ts#L386)][¶](https://libtmux.org/en/ts/latest/mcp/tools/kill_session/#mcp.tool.kill_session) Delete tmux state; accepts no command payload. Remove a session. Windows and panes shared with another session remain available there. * MCP request method `tools/call` Send `kill_session` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/kill_session/#mcp.tool.kill_session.parameters) * **[`force`](https://libtmux.org/en/ts/latest/mcp/tools/kill_session/#mcp.tool.kill_session.input%2Fproperties%2Fforce)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Allow this to target the pane this server itself was called from, which is otherwise refused. It does not override the refusal to touch a pane a person is watching. * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/kill_session/#mcp.tool.kill_session.input%2Fproperties%2Fsession)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id ($1) or name. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/kill_session/#mcp.tool.kill_session.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`killed`](https://libtmux.org/en/ts/latest/mcp/tools/kill_session/#mcp.tool.kill_session.output%2Fproperties%2Fkilled)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/kill_session/#mcp.tool.kill_session.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/kill_session/#mcp.tool.kill_session.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "force": { "description": "Allow this to target the pane this server itself was called from, which is otherwise refused. It does not override the refusal to touch a pane a person is watching.", "type": "boolean" }, "session": { "description": "Session id ($1) or name.", "type": "string" } }, "required": [ "session" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "killed": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" } }, "required": [ "killed" ], "type": "object" } ``` --- # kill_window Source: https://libtmux.org/en/ts/latest/mcp/tools/kill_window/ > Delete tmux state; accepts no command payload. Close a window and every pane in it. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **kill_window**( [force](https://libtmux.org/en/ts/latest/mcp/tools/kill_window/#mcp.tool.kill_window.input%2Fproperties%2Fforce)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [windowId](https://libtmux.org/en/ts/latest/mcp/tools/kill_window/#mcp.tool.kill_window.input%2Fproperties%2FwindowId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/lifecycle.ts#L352)][¶](https://libtmux.org/en/ts/latest/mcp/tools/kill_window/#mcp.tool.kill_window) Delete tmux state; accepts no command payload. Close a window and every pane in it. * MCP request method `tools/call` Send `kill_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/kill_window/#mcp.tool.kill_window.parameters) * **[`force`](https://libtmux.org/en/ts/latest/mcp/tools/kill_window/#mcp.tool.kill_window.input%2Fproperties%2Fforce)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Allow this to target the pane this server itself was called from, which is otherwise refused. It does not override the refusal to touch a pane a person is watching. * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/kill_window/#mcp.tool.kill_window.input%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/kill_window/#mcp.tool.kill_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`killed`](https://libtmux.org/en/ts/latest/mcp/tools/kill_window/#mcp.tool.kill_window.output%2Fproperties%2Fkilled)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/kill_window/#mcp.tool.kill_window.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/kill_window/#mcp.tool.kill_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "force": { "description": "Allow this to target the pane this server itself was called from, which is otherwise refused. It does not override the refusal to touch a pane a person is watching.", "type": "boolean" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "windowId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "killed": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "killed" ], "type": "object" } ``` --- # list_panes Source: https://libtmux.org/en/ts/latest/mcp/tools/list_panes/ > Inspect tmux metadata; accepts no client-supplied executable input. Panes on this server, with the command each is running and its directory. Marks the pane this server runs in (isCallerPane) and panes a person is watching (isAttended). Metadata only — search_panes reads their contents. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **list_panes**( [session](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fsession)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [window](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fwindow)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/discovery.ts#L150)][¶](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes) Inspect tmux metadata; accepts no client-supplied executable input. Panes on this server, with the command each is running and its directory. Marks the pane this server runs in (isCallerPane) and panes a person is watching (isAttended). Metadata only — [search_panes](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/) reads their contents. * MCP request method `tools/call` Send `list_panes` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.parameters) * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fsession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id ($1) or name. * **[`window`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.input%2Fproperties%2Fwindow)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`complete`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fcomplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`omittedEntries`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2FomittedEntries)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`panes`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes)** ([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/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this is its window’s active pane. * **[`command`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The command tmux reports running in it. * **[`cwd`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fcwd)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Its current working directory. * **[`dead`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fdead)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether its process exited and remain-on-exit kept it. * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fheight)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id. Prefer this for entity-scoped targeting. * pattern `"^%\\d+$"` * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`isAttended`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FisAttended)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) A person is currently looking at this pane. * **[`isCallerPane`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FisCallerPane)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) This is the pane this MCP server runs in. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fplacements)** ([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)")>) Retained session and window indexes through which this pane is reachable. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`title`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Ftitle)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fwidth)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FwindowName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/#mcp.tool.list_panes.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "session": { "description": "Session id ($1) or name.", "type": "string" }, "window": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "complete": { "type": "boolean" }, "omittedEntries": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "panes": { "items": { "additionalProperties": false, "properties": { "active": { "description": "Whether this is its window's active pane.", "type": "boolean" }, "command": { "description": "The command tmux reports running in it.", "type": "string" }, "cwd": { "description": "Its current working directory.", "type": "string" }, "dead": { "description": "Whether its process exited and remain-on-exit kept it.", "type": "boolean" }, "height": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable pane id. Prefer this for entity-scoped targeting.", "pattern": "^%\\d+$", "type": "string" }, "index": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "isAttended": { "description": "A person is currently looking at this pane.", "type": "boolean" }, "isCallerPane": { "description": "This is the pane this MCP server runs in.", "type": "boolean" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "placements": { "description": "Retained session and window indexes through which this pane is reachable.", "items": { "additionalProperties": false, "properties": { "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "title": { "type": "string" }, "width": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "windowName": { "type": "string" } }, "required": [ "active", "command", "cwd", "dead", "height", "id", "index", "isAttended", "isCallerPane", "metadataComplete", "omittedMetadataBytes", "omittedPlacements", "placements", "placementsComplete", "title", "width", "windowId", "windowName" ], "type": "object" }, "type": "array" } }, "required": [ "complete", "omittedEntries", "panes" ], "type": "object" } ``` --- # list_sessions Source: https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/ > Inspect tmux metadata; accepts no client-supplied executable input. Every session on this server with its id, name, window count, and whether anyone is attached. Metadata only — for what a pane shows, use capture_pane or search_panes. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **list_sessions**() tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/discovery.ts#L60)][¶](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions) Inspect tmux metadata; accepts no client-supplied executable input. Every session on this server with its id, name, window count, and whether anyone is attached. Metadata only — for what a pane shows, use [capture_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/) or [search_panes](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/). * MCP request method `tools/call` Send `list_sessions` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.parameters) No named arguments. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`complete`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fcomplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`omittedEntries`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2FomittedEntries)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessions`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fsessions)** ([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/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fsessions%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`attachedClients`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fsessions%2Fitems%2Fproperties%2FattachedClients)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Raw client count from tmux; 0 means detached. Includes control-mode clients - this server’s own [wait_for_text](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/) or other live read holds one open while it runs, and another program on this socket may hold others. See humanAttachedClients for a person-only count. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`humanAttachedClients`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fsessions%2Fitems%2Fproperties%2FhumanAttachedClients)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) attachedClients minus every control-mode client, this server’s own included. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fsessions%2Fitems%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fsessions%2Fitems%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether the session name is complete. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fsessions%2Fitems%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fsessions%2Fitems%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from the session name. * minimum `0` * maximum `9007199254740991` * **[`windows`](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.output%2Fproperties%2Fsessions%2Fitems%2Fproperties%2Fwindows)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) How many windows it holds. * minimum `-9007199254740991` * maximum `9007199254740991` No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/list_sessions/#mcp.tool.list_sessions.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": {}, "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "complete": { "type": "boolean" }, "omittedEntries": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessions": { "items": { "additionalProperties": false, "properties": { "attachedClients": { "description": "Raw client count from tmux; 0 means detached. Includes control-mode clients - this server's own wait_for_text or other live read holds one open while it runs, and another program on this socket may hold others. See humanAttachedClients for a person-only count.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "humanAttachedClients": { "description": "attachedClients minus every control-mode client, this server's own included.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "metadataComplete": { "description": "Whether the session name is complete.", "type": "boolean" }, "name": { "type": "string" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from the session name.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "windows": { "description": "How many windows it holds.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "attachedClients", "humanAttachedClients", "id", "metadataComplete", "name", "omittedMetadataBytes", "windows" ], "type": "object" }, "type": "array" } }, "required": [ "complete", "omittedEntries", "sessions" ], "type": "object" } ``` --- # list_windows Source: https://libtmux.org/en/ts/latest/mcp/tools/list_windows/ > Inspect tmux metadata; accepts no client-supplied executable input. Windows on this server, optionally restricted to one session by id or name. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **list_windows**( [session](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.input%2Fproperties%2Fsession)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/discovery.ts#L105)][¶](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows) Inspect tmux metadata; accepts no client-supplied executable input. Windows on this server, optionally restricted to one session by id or name. * MCP request method `tools/call` Send `list_windows` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.parameters) * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.input%2Fproperties%2Fsession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id ($1) or name. Omit for all sessions. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`complete`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fcomplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`omittedEntries`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2FomittedEntries)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`windows`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows)** ([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/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`layout`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2Flayout)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) tmux’s layout string; feed it back only when metadataComplete is true. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`panes`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2Fpanes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2Fplacements)** ([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)")>) Retained sessions and indexes where this window is linked. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this placement is current in its session. * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`zoomed`](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.output%2Fproperties%2Fwindows%2Fitems%2Fproperties%2Fzoomed)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/list_windows/#mcp.tool.list_windows.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "session": { "description": "Session id ($1) or name. Omit for all sessions.", "type": "string" } }, "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "complete": { "type": "boolean" }, "omittedEntries": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "windows": { "items": { "additionalProperties": false, "properties": { "id": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "layout": { "description": "tmux's layout string; feed it back only when metadataComplete is true.", "type": "string" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "name": { "type": "string" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "panes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "placements": { "description": "Retained sessions and indexes where this window is linked.", "items": { "additionalProperties": false, "properties": { "active": { "description": "Whether this placement is current in its session.", "type": "boolean" }, "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName", "active" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "zoomed": { "type": "boolean" } }, "required": [ "id", "layout", "metadataComplete", "name", "omittedMetadataBytes", "panes", "omittedPlacements", "placements", "placementsComplete", "zoomed" ], "type": "object" }, "type": "array" } }, "required": [ "complete", "omittedEntries", "windows" ], "type": "object" } ``` --- # move_window Source: https://libtmux.org/en/ts/latest/mcp/tools/move_window/ > Change tmux state; no client-supplied executable input. Move a window to another index, or into another session. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **move_window**( [index](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Findex)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [session](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fsession)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [sourceIndex](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2FsourceIndex)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [sourceSession](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2FsourceSession)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [windowId](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2FwindowId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/layout.ts#L268)][¶](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window) Change tmux state; no client-supplied executable input. Move a window to another index, or into another session. * MCP request method `tools/call` Send `move_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.parameters) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Findex)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Destination index. Defaults to the next free one. * minimum `0` * maximum `9007199254740991` * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2Fsession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Destination session id or name. * **[`sourceIndex`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2FsourceIndex)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Source window index. Required when the session has several placements of the id. * minimum `0` * maximum `9007199254740991` * **[`sourceSession`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2FsourceSession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Source session id or name. Required when the id has several placements. * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.input%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`window`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`layout`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2Flayout)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) tmux’s layout string; feed it back only when metadataComplete is true. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`panes`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2Fpanes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements)** ([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)")>) Retained sessions and indexes where this window is linked. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this placement is current in its session. * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`zoomed`](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.output%2Fproperties%2Fwindow%2Fproperties%2Fzoomed)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/move_window/#mcp.tool.move_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "index": { "description": "Destination index. Defaults to the next free one.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "session": { "description": "Destination session id or name.", "type": "string" }, "sourceIndex": { "description": "Source window index. Required when the session has several placements of the id.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "sourceSession": { "description": "Source session id or name. Required when the id has several placements.", "type": "string" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "windowId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "window": { "additionalProperties": false, "properties": { "id": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "layout": { "description": "tmux's layout string; feed it back only when metadataComplete is true.", "type": "string" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "name": { "type": "string" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "panes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "placements": { "description": "Retained sessions and indexes where this window is linked.", "items": { "additionalProperties": false, "properties": { "active": { "description": "Whether this placement is current in its session.", "type": "boolean" }, "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName", "active" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "zoomed": { "type": "boolean" } }, "required": [ "id", "layout", "metadataComplete", "name", "omittedMetadataBytes", "panes", "omittedPlacements", "placements", "placementsComplete", "zoomed" ], "type": "object" } }, "required": [ "window" ], "type": "object" } ``` --- # paste_text Source: https://libtmux.org/en/ts/latest/mcp/tools/paste_text/ > Send input to a pane's program; a shell that receives it runs it with your user's permissions. Put text into a pane without tmux interpreting any of it as key names. Use for content — a password, a code block, anything with characters a key parser would claim. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **paste_text**( [enter](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fenter)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [force](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fforce)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [paneId](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [text](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Ftext): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/input.ts#L189)][¶](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text) Send input to a pane’s program; a shell that receives it runs it with your user’s permissions. Put text into a pane without tmux interpreting any of it as key names. Use for content — a password, a code block, anything with characters a key parser would claim. * MCP request method `tools/call` Send `paste_text` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.parameters) * **[`enter`](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fenter)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Press Enter afterwards. Default false. * **[`force`](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Fforce)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Allow writing to the pane this server itself was called from, which is otherwise refused. It does not override the refusal to write to a pane a person is watching — a pane an attached client has on screen is still refused with force. * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`text`](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.input%2Fproperties%2Ftext)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Text to paste. Sent through a tmux buffer, so a shell’s line editor does not redraw on every character. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`bytes`](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.output%2Fproperties%2Fbytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.output%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/paste_text/#mcp.tool.paste_text.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "enter": { "description": "Press Enter afterwards. Default false.", "type": "boolean" }, "force": { "description": "Allow writing to the pane this server itself was called from, which is otherwise refused. It does not override the refusal to write to a pane a person is watching — a pane an attached client has on screen is still refused with force.", "type": "boolean" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "text": { "description": "Text to paste. Sent through a tmux buffer, so a shell's line editor does not redraw on every character.", "type": "string" } }, "required": [ "paneId", "text" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "bytes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "bytes", "paneId" ], "type": "object" } ``` --- # rename_session Source: https://libtmux.org/en/ts/latest/mcp/tools/rename_session/ > Change tmux state; no client-supplied executable input. Rename a session. Its id does not change, so targets by id keep working. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **rename_session**( [name](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.input%2Fproperties%2Fname): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [session](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.input%2Fproperties%2Fsession): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/lifecycle.ts#L234)][¶](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session) Change tmux state; no client-supplied executable input. Rename a session. Its id does not change, so targets by id keep working. * MCP request method `tools/call` Send `rename_session` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.parameters) * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.input%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The session’s new name. * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.input%2Fproperties%2Fsession)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id ($1) or name. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fsession)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`attachedClients`](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fsession%2Fproperties%2FattachedClients)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Raw client count from tmux; 0 means detached. Includes control-mode clients - this server’s own [wait_for_text](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/) or other live read holds one open while it runs, and another program on this socket may hold others. See humanAttachedClients for a person-only count. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`humanAttachedClients`](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fsession%2Fproperties%2FhumanAttachedClients)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) attachedClients minus every control-mode client, this server’s own included. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fsession%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fsession%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether the session name is complete. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fsession%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fsession%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from the session name. * minimum `0` * maximum `9007199254740991` * **[`windows`](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.output%2Fproperties%2Fsession%2Fproperties%2Fwindows)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) How many windows it holds. * minimum `-9007199254740991` * maximum `9007199254740991` No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/rename_session/#mcp.tool.rename_session.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "name": { "description": "The session's new name.", "type": "string", "x-libtmux-tmux-format": "literalized-once" }, "session": { "description": "Session id ($1) or name.", "type": "string" } }, "required": [ "name", "session" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "session": { "additionalProperties": false, "properties": { "attachedClients": { "description": "Raw client count from tmux; 0 means detached. Includes control-mode clients - this server's own wait_for_text or other live read holds one open while it runs, and another program on this socket may hold others. See humanAttachedClients for a person-only count.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "humanAttachedClients": { "description": "attachedClients minus every control-mode client, this server's own included.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "metadataComplete": { "description": "Whether the session name is complete.", "type": "boolean" }, "name": { "type": "string" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from the session name.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "windows": { "description": "How many windows it holds.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "attachedClients", "humanAttachedClients", "id", "metadataComplete", "name", "omittedMetadataBytes", "windows" ], "type": "object" } }, "required": [ "session" ], "type": "object" } ``` --- # rename_window Source: https://libtmux.org/en/ts/latest/mcp/tools/rename_window/ > Change tmux state; no client-supplied executable input. Rename a window. Its id does not change. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **rename_window**( [name](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fname): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [windowId](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2FwindowId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/lifecycle.ts#L260)][¶](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window) Change tmux state; no client-supplied executable input. Rename a window. Its id does not change. * MCP request method `tools/call` Send `rename_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.parameters) * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The window’s new name. * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.input%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`window`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`layout`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2Flayout)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) tmux’s layout string; feed it back only when metadataComplete is true. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`panes`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2Fpanes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements)** ([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)")>) Retained sessions and indexes where this window is linked. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this placement is current in its session. * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`zoomed`](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.output%2Fproperties%2Fwindow%2Fproperties%2Fzoomed)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/rename_window/#mcp.tool.rename_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "name": { "description": "The window's new name.", "type": "string", "x-libtmux-tmux-format": "literalized-once" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "name", "windowId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "window": { "additionalProperties": false, "properties": { "id": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "layout": { "description": "tmux's layout string; feed it back only when metadataComplete is true.", "type": "string" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "name": { "type": "string" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "panes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "placements": { "description": "Retained sessions and indexes where this window is linked.", "items": { "additionalProperties": false, "properties": { "active": { "description": "Whether this placement is current in its session.", "type": "boolean" }, "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName", "active" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "zoomed": { "type": "boolean" } }, "required": [ "id", "layout", "metadataComplete", "name", "omittedMetadataBytes", "panes", "omittedPlacements", "placements", "placementsComplete", "zoomed" ], "type": "object" } }, "required": [ "window" ], "type": "object" } ``` --- # resize_pane Source: https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/ > Change tmux state; no client-supplied executable input. Resize a pane, either to a size or by an amount in a direction. Give width/height for an absolute size, or direction with amount for a nudge. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **resize_pane**( [amount](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Famount)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [direction](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fdirection)?: "up" | "down" | "left" | "right", [height](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fheight)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [paneId](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [width](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fwidth)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [zoom](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fzoom)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/layout.ts#L85)][¶](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane) Change tmux state; no client-supplied executable input. Resize a pane, either to a size or by an amount in a direction. Give width/height for an absolute size, or direction with amount for a nudge. * MCP request method `tools/call` Send `resize_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.parameters) * **[`amount`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Famount)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Cells to move by. Needs direction. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`direction`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fdirection)**? ("up" | "down" | "left" | "right") Adjust by an amount in this direction instead of setting a size. * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fheight)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Set the pane height, in rows. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fwidth)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Set the width, in columns. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`zoom`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.input%2Fproperties%2Fzoom)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) true makes this pane fill its window, false restores the layout. A state, not a toggle: sending the same value twice is a no-op. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`pane`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this is its window’s active pane. * **[`command`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The command tmux reports running in it. * **[`cwd`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Fcwd)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Its current working directory. * **[`dead`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Fdead)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether its process exited and remain-on-exit kept it. * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Fheight)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id. Prefer this for entity-scoped targeting. * pattern `"^%\\d+$"` * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`isAttended`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2FisAttended)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) A person is currently looking at this pane. * **[`isCallerPane`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2FisCallerPane)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) This is the pane this MCP server runs in. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements)** ([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)")>) Retained session and window indexes through which this pane is reachable. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`title`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Ftitle)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2Fwidth)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.output%2Fproperties%2Fpane%2Fproperties%2FwindowName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/#mcp.tool.resize_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "amount": { "description": "Cells to move by. Needs direction.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "direction": { "description": "Adjust by an amount in this direction instead of setting a size.", "enum": [ "up", "down", "left", "right" ], "type": "string" }, "height": { "description": "Set the pane height, in rows.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "width": { "description": "Set the width, in columns.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "zoom": { "description": "true makes this pane fill its window, false restores the layout. A state, not a toggle: sending the same value twice is a no-op.", "type": "boolean" } }, "required": [ "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "pane": { "additionalProperties": false, "properties": { "active": { "description": "Whether this is its window's active pane.", "type": "boolean" }, "command": { "description": "The command tmux reports running in it.", "type": "string" }, "cwd": { "description": "Its current working directory.", "type": "string" }, "dead": { "description": "Whether its process exited and remain-on-exit kept it.", "type": "boolean" }, "height": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable pane id. Prefer this for entity-scoped targeting.", "pattern": "^%\\d+$", "type": "string" }, "index": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "isAttended": { "description": "A person is currently looking at this pane.", "type": "boolean" }, "isCallerPane": { "description": "This is the pane this MCP server runs in.", "type": "boolean" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "placements": { "description": "Retained session and window indexes through which this pane is reachable.", "items": { "additionalProperties": false, "properties": { "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "title": { "type": "string" }, "width": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "windowName": { "type": "string" } }, "required": [ "active", "command", "cwd", "dead", "height", "id", "index", "isAttended", "isCallerPane", "metadataComplete", "omittedMetadataBytes", "omittedPlacements", "placements", "placementsComplete", "title", "width", "windowId", "windowName" ], "type": "object" } }, "required": [ "pane" ], "type": "object" } ``` --- # resize_window Source: https://libtmux.org/en/ts/latest/mcp/tools/resize_window/ > Change tmux state; no client-supplied executable input. Set a window's size in cells. A detached window is whatever size tmux guessed, and a program that formats to its terminal width truncates to that at the source — no capture option recovers those columns, because they were never printed. resize_pane only redistributes space inside a window and cannot grow one. A client attached to the window will overwrite this when it next changes; window-size manual makes a size of your own stick. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **resize_window**( [height](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fheight)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [width](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fwidth)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [windowId](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2FwindowId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/layout.ts#L311)][¶](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window) Change tmux state; no client-supplied executable input. Set a window’s size in cells. A detached window is whatever size tmux guessed, and a program that formats to its terminal width truncates to that at the source — no capture option recovers those columns, because they were never printed. [resize_pane](https://libtmux.org/en/ts/latest/mcp/tools/resize_pane/) only redistributes space inside a window and cannot grow one. A client attached to the window will overwrite this when it next changes; window-size manual makes a size of your own stick. * MCP request method `tools/call` Send `resize_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.parameters) * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fheight)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Set the height, in rows. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2Fwidth)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Set the width, in columns. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.input%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`window`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`layout`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2Flayout)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) tmux’s layout string; feed it back only when metadataComplete is true. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`panes`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2Fpanes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements)** ([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)")>) Retained sessions and indexes where this window is linked. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this placement is current in its session. * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`zoomed`](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.output%2Fproperties%2Fwindow%2Fproperties%2Fzoomed)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/resize_window/#mcp.tool.resize_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "height": { "description": "Set the height, in rows.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "width": { "description": "Set the width, in columns.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "windowId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "window": { "additionalProperties": false, "properties": { "id": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "layout": { "description": "tmux's layout string; feed it back only when metadataComplete is true.", "type": "string" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "name": { "type": "string" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "panes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "placements": { "description": "Retained sessions and indexes where this window is linked.", "items": { "additionalProperties": false, "properties": { "active": { "description": "Whether this placement is current in its session.", "type": "boolean" }, "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName", "active" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "zoomed": { "type": "boolean" } }, "required": [ "id", "layout", "metadataComplete", "name", "omittedMetadataBytes", "panes", "omittedPlacements", "placements", "placementsComplete", "zoomed" ], "type": "object" } }, "required": [ "window" ], "type": "object" } ``` --- # respawn_pane Source: https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/ > Start a pane's configured process; accepts no command payload. Restart a pane's command in place, keeping the pane and its id. Use to recover a pane whose process died, rather than killing and re-splitting. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **respawn_pane**( [force](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fforce)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [killFirst](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2FkillFirst)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [paneId](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [startDirectory](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2FstartDirectory)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/lifecycle.ts#L282)][¶](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane) Start a pane’s configured process; accepts no command payload. Restart a pane’s command in place, keeping the pane and its id. Use to recover a pane whose process died, rather than killing and re-splitting. * MCP request method `tools/call` Send `respawn_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.parameters) * **[`force`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fforce)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Allow this to target the pane this server itself was called from, which is otherwise refused. It does not override the refusal to touch a pane a person is watching. * **[`killFirst`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2FkillFirst)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Replace a still-running process. Default false. * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`startDirectory`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2FstartDirectory)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Working directory for the restarted command. Defaults to the pane’s. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`pane`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this is its window’s active pane. * **[`command`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The command tmux reports running in it. * **[`cwd`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Fcwd)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Its current working directory. * **[`dead`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Fdead)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether its process exited and remain-on-exit kept it. * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Fheight)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id. Prefer this for entity-scoped targeting. * pattern `"^%\\d+$"` * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`isAttended`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2FisAttended)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) A person is currently looking at this pane. * **[`isCallerPane`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2FisCallerPane)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) This is the pane this MCP server runs in. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements)** ([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)")>) Retained session and window indexes through which this pane is reachable. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`title`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Ftitle)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2Fwidth)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane%2Fproperties%2FwindowName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "force": { "description": "Allow this to target the pane this server itself was called from, which is otherwise refused. It does not override the refusal to touch a pane a person is watching.", "type": "boolean" }, "killFirst": { "description": "Replace a still-running process. Default false.", "type": "boolean" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "startDirectory": { "description": "Working directory for the restarted command. Defaults to the pane's.", "type": "string", "x-libtmux-tmux-format": "literalized-once" } }, "required": [ "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "pane": { "additionalProperties": false, "properties": { "active": { "description": "Whether this is its window's active pane.", "type": "boolean" }, "command": { "description": "The command tmux reports running in it.", "type": "string" }, "cwd": { "description": "Its current working directory.", "type": "string" }, "dead": { "description": "Whether its process exited and remain-on-exit kept it.", "type": "boolean" }, "height": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable pane id. Prefer this for entity-scoped targeting.", "pattern": "^%\\d+$", "type": "string" }, "index": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "isAttended": { "description": "A person is currently looking at this pane.", "type": "boolean" }, "isCallerPane": { "description": "This is the pane this MCP server runs in.", "type": "boolean" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "placements": { "description": "Retained session and window indexes through which this pane is reachable.", "items": { "additionalProperties": false, "properties": { "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "title": { "type": "string" }, "width": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "windowName": { "type": "string" } }, "required": [ "active", "command", "cwd", "dead", "height", "id", "index", "isAttended", "isCallerPane", "metadataComplete", "omittedMetadataBytes", "omittedPlacements", "placements", "placementsComplete", "title", "width", "windowId", "windowName" ], "type": "object" } }, "required": [ "pane" ], "type": "object" } ``` --- # run_shell_command Source: https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/ > Run a shell command in a pane with your user's permissions. Run a shell command in a pane, wait for it to finish, and report its exit status and output. Prefer this over send_keys plus capture_pane: it frames the command so a pane's echo of what you typed can never be mistaken for what the command printed, and it knows when the command actually ended rather than guessing from the screen. The command runs in a subshell, so cd and export do not persist to a later call. A pane is effectively single-writer: this server reserves it until the command settles, but another process with the same tmux socket can still write into it. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **run_shell_command**( [command](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.input%2Fproperties%2Fcommand): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [force](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.input%2Fproperties%2Fforce)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [maxLines](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.input%2Fproperties%2FmaxLines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [paneId](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [timeoutMs](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.input%2Fproperties%2FtimeoutMs)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/input.ts#L304)][¶](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command) Run a shell command in a pane with your user’s permissions. Run a shell command in a pane, wait for it to finish, and report its exit status and output. Prefer this over [send_keys](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/) plus [capture_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/): it frames the command so a pane’s echo of what you typed can never be mistaken for what the command printed, and it knows when the command actually ended rather than guessing from the screen. The command runs in a subshell, so cd and export do not persist to a later call. A pane is effectively single-writer: this server reserves it until the command settles, but another process with the same tmux socket can still write into it. * MCP request method `tools/call` Send `run_shell_command` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.parameters) * **[`command`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.input%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The shell command to run. * **[`force`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.input%2Fproperties%2Fforce)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Allow writing to the pane this server itself was called from, which is otherwise refused. It does not override the refusal to write to a pane a person is watching — a pane an attached client has on screen is still refused with force. * **[`maxLines`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.input%2Fproperties%2FmaxLines)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Keep at most this many lines, from the end. Defaults to the server limit. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`timeoutMs`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.input%2Fproperties%2FtimeoutMs)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) How long to wait. Clamped by the server ceiling; the result says what was used. * maximum `9007199254740991` * exclusiveMinimum `0` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`droppedLines`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2FdroppedLines)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Lines of output withheld by maxLines. The text half says so in a notice; a caller reading only the structured half would otherwise take the tail for the whole. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`effectiveTimeoutMs`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2FeffectiveTimeoutMs)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The timeout actually enforced. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`exitStatus`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2FexitStatus)** ([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)")) The command’s exit status; null if it did not finish. Matches one or more variants. * **[Variant 1](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2FexitStatus%2FanyOf%2F0)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`foreignOutputSuspected`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2FforeignOutputSuspected)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Another writer printed into this pane while the command ran. Output that could be attributed to them was removed; what is left may still include theirs. False means no foreign marker was seen, not that the output is certainly this command’s. * **[`missedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2FmissedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Output that fell out of the pane’s buffer before this read reached it. Nonzero means the command printed more than was kept, so the output here starts partway through it. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`omittedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2FomittedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Output bytes omitted by the result ceiling. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`outcome`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2Foutcome)** ("completed" | "timed_out" | "pane_died" | "cancelled") Why this returned. Read it rather than inferring from the text. * **[`output`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2Foutput)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The bounded tail of the command’s output. * **[`outputComplete`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2FoutputComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) False when capture or result limits omitted any command output. * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`returnedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2FreturnedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 output bytes returned. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`stillRunning`](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.output%2Fproperties%2FstillRunning)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether the command may still be running after this call returned. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/#mcp.tool.run_shell_command.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "command": { "description": "The shell command to run.", "type": "string" }, "force": { "description": "Allow writing to the pane this server itself was called from, which is otherwise refused. It does not override the refusal to write to a pane a person is watching — a pane an attached client has on screen is still refused with force.", "type": "boolean" }, "maxLines": { "description": "Keep at most this many lines, from the end. Defaults to the server limit.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "timeoutMs": { "description": "How long to wait. Clamped by the server ceiling; the result says what was used.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" } }, "required": [ "command", "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "droppedLines": { "description": "Lines of output withheld by maxLines. The text half says so in a notice; a caller reading only the structured half would otherwise take the tail for the whole.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "effectiveTimeoutMs": { "description": "The timeout actually enforced.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "exitStatus": { "anyOf": [ { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, { "type": "null" } ], "description": "The command's exit status; null if it did not finish." }, "foreignOutputSuspected": { "description": "Another writer printed into this pane while the command ran. Output that could be attributed to them was removed; what is left may still include theirs. False means no foreign marker was seen, not that the output is certainly this command's.", "type": "boolean" }, "missedBytes": { "description": "Output that fell out of the pane's buffer before this read reached it. Nonzero means the command printed more than was kept, so the output here starts partway through it.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "omittedBytes": { "description": "Output bytes omitted by the result ceiling.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "outcome": { "description": "Why this returned. Read it rather than inferring from the text.", "enum": [ "completed", "timed_out", "pane_died", "cancelled" ], "type": "string" }, "output": { "description": "The bounded tail of the command's output.", "type": "string" }, "outputComplete": { "description": "False when capture or result limits omitted any command output.", "type": "boolean" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "returnedBytes": { "description": "UTF-8 output bytes returned.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "stillRunning": { "description": "Whether the command may still be running after this call returned.", "type": "boolean" } }, "required": [ "effectiveTimeoutMs", "droppedLines", "missedBytes", "omittedBytes", "foreignOutputSuspected", "exitStatus", "outcome", "output", "outputComplete", "paneId", "returnedBytes", "stillRunning" ], "type": "object" } ``` --- # search_panes Source: https://libtmux.org/en/ts/latest/mcp/tools/search_panes/ > Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Find which panes are showing something. Searches pane contents, not their names — use list_panes for metadata. Returns the matching lines with their pane, so you can target one without capturing them all. Literal matching stops at one 256 KiB aggregate UTF-8 byte budget. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **search_panes**( [maxMatchesPerPane](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2FmaxMatchesPerPane)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [pattern](https://libtmux.org/en/ts/latest/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/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fregex)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [scrollbackLines](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2FscrollbackLines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [session](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fsession)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/search.ts#L78)][¶](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes) Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Find which panes are showing something. Searches pane contents, not their names — use [list_panes](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/) for metadata. Returns the matching lines with their pane, so you can target one without capturing them all. Literal matching stops at one 256 KiB aggregate UTF-8 byte budget. * MCP request method `tools/call` Send `search_panes` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.parameters) * **[`maxMatchesPerPane`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2FmaxMatchesPerPane)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Stop after this many matches in each pane. Defaults to the server limit. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`pattern`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fpattern)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Non-empty literal text to find. * minLength `1` * **[`regex`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fregex)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Interpret pattern using libtmux’s bounded regular-expression grammar. * **[`scrollbackLines`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2FscrollbackLines)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) How far above the visible screen to search. Default 0. * minimum `0` * maximum `9007199254740991` * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.input%2Fproperties%2Fsession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Restrict to one session by id or name. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`capturesByteClamped`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FcapturesByteClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`effectiveScrollbackLines`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FeffectiveScrollbackLines)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`matches`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches)** ([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/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`lineNumber`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2FlineNumber)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2Fplacements)** ([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/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`text`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2Ftext)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2Fmatches%2Fitems%2Fproperties%2FwindowName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`matchesTruncated`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FmatchesTruncated)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`matchingByteClamped`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FmatchingByteClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`matchingLineClamped`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FmatchingLineClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`matchingTimeClamped`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FmatchingTimeClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`paneLimitClamped`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FpaneLimitClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`panesFailed`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FpanesFailed)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`panesSearched`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FpanesSearched)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`scrollbackClamped`](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.output%2Fproperties%2FscrollbackClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/search_panes/#mcp.tool.search_panes.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "maxMatchesPerPane": { "description": "Stop after this many matches in each pane. Defaults to the server limit.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "pattern": { "description": "Non-empty literal text to find.", "minLength": 1, "type": "string" }, "regex": { "description": "Interpret pattern using libtmux's bounded regular-expression grammar.", "type": "boolean" }, "scrollbackLines": { "description": "How far above the visible screen to search. Default 0.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "session": { "description": "Restrict to one session by id or name.", "type": "string" } }, "required": [ "pattern" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "capturesByteClamped": { "type": "boolean" }, "effectiveScrollbackLines": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "matches": { "items": { "additionalProperties": false, "properties": { "lineNumber": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "placements": { "items": { "additionalProperties": false, "properties": { "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName" ], "type": "object" }, "type": "array" }, "text": { "type": "string" }, "windowName": { "type": "string" } }, "required": [ "lineNumber", "paneId", "placements", "text", "windowName" ], "type": "object" }, "type": "array" }, "matchesTruncated": { "type": "boolean" }, "matchingByteClamped": { "type": "boolean" }, "matchingLineClamped": { "type": "boolean" }, "matchingTimeClamped": { "type": "boolean" }, "paneLimitClamped": { "type": "boolean" }, "panesFailed": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "panesSearched": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "scrollbackClamped": { "type": "boolean" } }, "required": [ "capturesByteClamped", "effectiveScrollbackLines", "matches", "matchingByteClamped", "matchingLineClamped", "matchingTimeClamped", "matchesTruncated", "paneLimitClamped", "panesFailed", "panesSearched", "scrollbackClamped" ], "type": "object" } ``` --- # select_layout Source: https://libtmux.org/en/ts/latest/mcp/tools/select_layout/ > Change tmux state; no client-supplied executable input. Rearrange a window's panes. Takes one of tmux's named layouts, or a layout string from an earlier window whose metadataComplete is true to reproduce it exactly. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **select_layout**( [layout](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Flayout): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [windowId](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2FwindowId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/layout.ts#L201)][¶](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout) Change tmux state; no client-supplied executable input. Rearrange a window’s panes. Takes one of tmux’s named layouts, or a layout string from an earlier window whose `metadataComplete` is true to reproduce it exactly. * MCP request method `tools/call` Send `select_layout` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.parameters) * **[`layout`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2Flayout)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) One of even-horizontal, even-vertical, main-horizontal, main-vertical, tiled, or a tmux layout string. * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.input%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`window`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`layout`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2Flayout)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) tmux’s layout string; feed it back only when metadataComplete is true. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`panes`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2Fpanes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements)** ([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)")>) Retained sessions and indexes where this window is linked. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this placement is current in its session. * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`zoomed`](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.output%2Fproperties%2Fwindow%2Fproperties%2Fzoomed)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/select_layout/#mcp.tool.select_layout.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "layout": { "description": "One of even-horizontal, even-vertical, main-horizontal, main-vertical, tiled, or a tmux layout string.", "type": "string" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "layout", "windowId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "window": { "additionalProperties": false, "properties": { "id": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "layout": { "description": "tmux's layout string; feed it back only when metadataComplete is true.", "type": "string" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "name": { "type": "string" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "panes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "placements": { "description": "Retained sessions and indexes where this window is linked.", "items": { "additionalProperties": false, "properties": { "active": { "description": "Whether this placement is current in its session.", "type": "boolean" }, "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName", "active" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "zoomed": { "type": "boolean" } }, "required": [ "id", "layout", "metadataComplete", "name", "omittedMetadataBytes", "panes", "omittedPlacements", "placements", "placementsComplete", "zoomed" ], "type": "object" } }, "required": [ "window" ], "type": "object" } ``` --- # select_pane Source: https://libtmux.org/en/ts/latest/mcp/tools/select_pane/ > Change tmux state; no client-supplied executable input. Make a pane the active one in its window. Moves the cursor of anyone attached to that window. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **select_pane**( [paneId](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/layout.ts#L151)][¶](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane) Change tmux state; no client-supplied executable input. Make a pane the active one in its window. Moves the cursor of anyone attached to that window. * MCP request method `tools/call` Send `select_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.parameters) * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`pane`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this is its window’s active pane. * **[`command`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The command tmux reports running in it. * **[`cwd`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Fcwd)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Its current working directory. * **[`dead`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Fdead)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether its process exited and remain-on-exit kept it. * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Fheight)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id. Prefer this for entity-scoped targeting. * pattern `"^%\\d+$"` * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`isAttended`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2FisAttended)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) A person is currently looking at this pane. * **[`isCallerPane`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2FisCallerPane)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) This is the pane this MCP server runs in. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements)** ([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)")>) Retained session and window indexes through which this pane is reachable. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`title`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Ftitle)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2Fwidth)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.output%2Fproperties%2Fpane%2Fproperties%2FwindowName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/select_pane/#mcp.tool.select_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "pane": { "additionalProperties": false, "properties": { "active": { "description": "Whether this is its window's active pane.", "type": "boolean" }, "command": { "description": "The command tmux reports running in it.", "type": "string" }, "cwd": { "description": "Its current working directory.", "type": "string" }, "dead": { "description": "Whether its process exited and remain-on-exit kept it.", "type": "boolean" }, "height": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable pane id. Prefer this for entity-scoped targeting.", "pattern": "^%\\d+$", "type": "string" }, "index": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "isAttended": { "description": "A person is currently looking at this pane.", "type": "boolean" }, "isCallerPane": { "description": "This is the pane this MCP server runs in.", "type": "boolean" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "placements": { "description": "Retained session and window indexes through which this pane is reachable.", "items": { "additionalProperties": false, "properties": { "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "title": { "type": "string" }, "width": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "windowName": { "type": "string" } }, "required": [ "active", "command", "cwd", "dead", "height", "id", "index", "isAttended", "isCallerPane", "metadataComplete", "omittedMetadataBytes", "omittedPlacements", "placements", "placementsComplete", "title", "width", "windowId", "windowName" ], "type": "object" } }, "required": [ "pane" ], "type": "object" } ``` --- # select_window Source: https://libtmux.org/en/ts/latest/mcp/tools/select_window/ > Change tmux state; no client-supplied executable input. Make a window the current one in its session. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **select_window**( [sourceIndex](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2FsourceIndex)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [sourceSession](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2FsourceSession)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [windowId](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2FwindowId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/layout.ts#L173)][¶](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window) Change tmux state; no client-supplied executable input. Make a window the current one in its session. * MCP request method `tools/call` Send `select_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.parameters) * **[`sourceIndex`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2FsourceIndex)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Source window index. Required when the session has several placements of the id. * minimum `0` * maximum `9007199254740991` * **[`sourceSession`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2FsourceSession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Source session id or name. Required when the id has several placements. * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.input%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`window`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`layout`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2Flayout)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) tmux’s layout string; feed it back only when metadataComplete is true. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`panes`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2Fpanes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements)** ([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)")>) Retained sessions and indexes where this window is linked. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this placement is current in its session. * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`zoomed`](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.output%2Fproperties%2Fwindow%2Fproperties%2Fzoomed)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/select_window/#mcp.tool.select_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "sourceIndex": { "description": "Source window index. Required when the session has several placements of the id.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "sourceSession": { "description": "Source session id or name. Required when the id has several placements.", "type": "string" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "windowId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "window": { "additionalProperties": false, "properties": { "id": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "layout": { "description": "tmux's layout string; feed it back only when metadataComplete is true.", "type": "string" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "name": { "type": "string" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "panes": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "placements": { "description": "Retained sessions and indexes where this window is linked.", "items": { "additionalProperties": false, "properties": { "active": { "description": "Whether this placement is current in its session.", "type": "boolean" }, "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName", "active" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "zoomed": { "type": "boolean" } }, "required": [ "id", "layout", "metadataComplete", "name", "omittedMetadataBytes", "panes", "omittedPlacements", "placements", "placementsComplete", "zoomed" ], "type": "object" } }, "required": [ "window" ], "type": "object" } ``` --- # send_keys Source: https://libtmux.org/en/ts/latest/mcp/tools/send_keys/ > Send input to a pane's program; a shell that receives it runs it with your user's permissions. Send keystrokes to a pane. Use for TUIs, control keys (C-c), and partial lines. For a shell command whose result you want, use run_shell_command — it waits for completion and reports exit status, which this does not. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **send_keys**( [enter](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fenter)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [force](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fforce)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [keys](https://libtmux.org/en/ts/latest/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/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fliteral)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [paneId](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/input.ts#L116)][¶](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys) Send input to a pane’s program; a shell that receives it runs it with your user’s permissions. Send keystrokes to a pane. Use for TUIs, control keys (C-c), and partial lines. For a shell command whose result you want, use [run_shell_command](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/) — it waits for completion and reports exit status, which this does not. * MCP request method `tools/call` Send `send_keys` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.parameters) * **[`enter`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fenter)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Press Enter afterwards. Default true. * **[`force`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fforce)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Allow writing to the pane this server itself was called from, which is otherwise refused. It does not override the refusal to write to a pane a person is watching — a pane an attached client has on screen is still refused with force. * **[`keys`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fkeys)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Keys to send. tmux key names like C-c work unless literal is true. * **[`literal`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2Fliteral)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Send the text as-is, without resolving key names. * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`attended`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.output%2Fproperties%2Fattended)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) A person is watching a configured cohort member. * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.output%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`resolvedPaneIds`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.output%2Fproperties%2FresolvedPaneIds)** ([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)")>) Configured cohort at the immediate preflight, not a delivery receipt. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.output%2Fproperties%2FresolvedPaneIds%2Fitems)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`sent`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.output%2Fproperties%2Fsent)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/#mcp.tool.send_keys.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "enter": { "description": "Press Enter afterwards. Default true.", "type": "boolean" }, "force": { "description": "Allow writing to the pane this server itself was called from, which is otherwise refused. It does not override the refusal to write to a pane a person is watching — a pane an attached client has on screen is still refused with force.", "type": "boolean" }, "keys": { "description": "Keys to send. tmux key names like C-c work unless literal is true.", "type": "string" }, "literal": { "description": "Send the text as-is, without resolving key names.", "type": "boolean" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "keys", "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "attended": { "description": "A person is watching a configured cohort member.", "type": "boolean" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "resolvedPaneIds": { "description": "Configured cohort at the immediate preflight, not a delivery receipt.", "items": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "type": "array" }, "sent": { "type": "boolean" } }, "required": [ "attended", "paneId", "resolvedPaneIds", "sent" ], "type": "object" } ``` --- # send_keys_batch Source: https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/ > Send input to a pane's program; a shell that receives it runs it with your user's permissions. Send an ordered batch of pane-input operations, resolving and checking each row's configured cohort immediately before input. Stop or continue on error. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **send_keys_batch**( [onError](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2FonError)?: "stop" | "continue", [operations](https://libtmux.org/en/ts/latest/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)")>, ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L468)][¶](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch) Send input to a pane’s program; a shell that receives it runs it with your user’s permissions. Send an ordered batch of pane-input operations, resolving and checking each row’s configured cohort immediately before input. Stop or continue on error. * MCP request method `tools/call` Send `send_keys_batch` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.parameters) * **[`onError`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2FonError)**? ("stop" | "continue") Whether a failed operation ends the batch. Defaults to stop. * **[`operations`](https://libtmux.org/en/ts/latest/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)")>) The key sends to run, in order, one pane each. * minItems `1` * maxItems `64` - **[Items](https://libtmux.org/en/ts/latest/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)")) * **[`enter`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Fenter)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Press Enter afterwards. Default true. * **[`force`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Fforce)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Allow this server’s own caller pane, as on [`send_keys`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/). * **[`keys`](https://libtmux.org/en/ts/latest/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 for this pane, as on [`send_keys`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/). * **[`literal`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2Fliteral)**? ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Send the text literally rather than resolving key names. * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.input%2Fproperties%2Foperations%2Fitems%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/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)") * **[`completed`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Fcompleted)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`failures`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Ffailures)** ([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/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Ffailures%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Ffailures%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`reason`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Ffailures%2Fitems%2Fproperties%2Freason)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`targets`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Ftargets)** ([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/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Ftargets%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Ftargets%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`resolvedPaneIds`](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Ftargets%2Fitems%2Fproperties%2FresolvedPaneIds)** ([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)")>) * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.output%2Fproperties%2Ftargets%2Fitems%2Fproperties%2FresolvedPaneIds%2Fitems)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/send_keys_batch/#mcp.tool.send_keys_batch.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "onError": { "description": "Whether a failed operation ends the batch. Defaults to stop.", "enum": [ "stop", "continue" ], "type": "string" }, "operations": { "description": "The key sends to run, in order, one pane each.", "items": { "properties": { "enter": { "description": "Press Enter afterwards. Default true.", "type": "boolean" }, "force": { "description": "Allow this server's own caller pane, as on `send_keys`.", "type": "boolean" }, "keys": { "description": "Keys for this pane, as on `send_keys`.", "type": "string" }, "literal": { "description": "Send the text literally rather than resolving key names.", "type": "boolean" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "keys", "paneId" ], "type": "object" }, "maxItems": 64, "minItems": 1, "type": "array" } }, "required": [ "operations" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "completed": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "failures": { "items": { "additionalProperties": false, "properties": { "index": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "reason": { "type": "string" } }, "required": [ "index", "reason" ], "type": "object" }, "type": "array" }, "targets": { "items": { "additionalProperties": false, "properties": { "index": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "resolvedPaneIds": { "items": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "type": "array" } }, "required": [ "index", "resolvedPaneIds" ], "type": "object" }, "type": "array" } }, "required": [ "completed", "failures", "targets" ], "type": "object" } ``` --- # set_history_limit Source: https://libtmux.org/en/ts/latest/mcp/tools/set_history_limit/ > Change tmux state; no client-supplied executable input. Set the default retained scrollback line limit through a bounded integer. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **set_history_limit**( [lines](https://libtmux.org/en/ts/latest/mcp/tools/set_history_limit/#mcp.tool.set_history_limit.input%2Fproperties%2Flines): [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L420)][¶](https://libtmux.org/en/ts/latest/mcp/tools/set_history_limit/#mcp.tool.set_history_limit) Change tmux state; no client-supplied executable input. Set the default retained scrollback line limit through a bounded integer. * MCP request method `tools/call` Send `set_history_limit` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/set_history_limit/#mcp.tool.set_history_limit.parameters) * **[`lines`](https://libtmux.org/en/ts/latest/mcp/tools/set_history_limit/#mcp.tool.set_history_limit.input%2Fproperties%2Flines)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Scrollback lines each new pane keeps. Applies to panes made after this. * minimum `0` * maximum `2000000` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/set_history_limit/#mcp.tool.set_history_limit.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`lines`](https://libtmux.org/en/ts/latest/mcp/tools/set_history_limit/#mcp.tool.set_history_limit.output%2Fproperties%2Flines)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/set_history_limit/#mcp.tool.set_history_limit.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/set_history_limit/#mcp.tool.set_history_limit.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "lines": { "description": "Scrollback lines each new pane keeps. Applies to panes made after this.", "maximum": 2000000, "minimum": 0, "type": "integer" } }, "required": [ "lines" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "lines": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "lines" ], "type": "object" } ``` --- # set_mouse_enabled Source: https://libtmux.org/en/ts/latest/mcp/tools/set_mouse_enabled/ > Change tmux state; no client-supplied executable input. Set the global tmux mouse option through a closed boolean schema. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **set_mouse_enabled**( [enabled](https://libtmux.org/en/ts/latest/mcp/tools/set_mouse_enabled/#mcp.tool.set_mouse_enabled.input%2Fproperties%2Fenabled): [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L404)][¶](https://libtmux.org/en/ts/latest/mcp/tools/set_mouse_enabled/#mcp.tool.set_mouse_enabled) Change tmux state; no client-supplied executable input. Set the global tmux mouse option through a closed boolean schema. * MCP request method `tools/call` Send `set_mouse_enabled` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/set_mouse_enabled/#mcp.tool.set_mouse_enabled.parameters) * **[`enabled`](https://libtmux.org/en/ts/latest/mcp/tools/set_mouse_enabled/#mcp.tool.set_mouse_enabled.input%2Fproperties%2Fenabled)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether tmux should report mouse events. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/set_mouse_enabled/#mcp.tool.set_mouse_enabled.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`enabled`](https://libtmux.org/en/ts/latest/mcp/tools/set_mouse_enabled/#mcp.tool.set_mouse_enabled.output%2Fproperties%2Fenabled)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/set_mouse_enabled/#mcp.tool.set_mouse_enabled.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/set_mouse_enabled/#mcp.tool.set_mouse_enabled.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "enabled": { "description": "Whether tmux should report mouse events.", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "type": "object" } ``` --- # set_pane_title Source: https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/ > Change tmux state; no client-supplied executable input. Give a pane a title. Useful for labelling what an agent put where, since the title shows in list_panes and survives the command changing. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **set_pane_title**( [paneId](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [title](https://libtmux.org/en/ts/latest/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)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/layout.ts#L350)][¶](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title) Change tmux state; no client-supplied executable input. Give a pane a title. Useful for labelling what an agent put where, since the title shows in [list_panes](https://libtmux.org/en/ts/latest/mcp/tools/list_panes/) and survives the command changing. * MCP request method `tools/call` Send `set_pane_title` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.parameters) * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`title`](https://libtmux.org/en/ts/latest/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 pane’s new title. ## Result[#](https://libtmux.org/en/ts/latest/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)") * **[`pane`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this is its window’s active pane. * **[`command`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The command tmux reports running in it. * **[`cwd`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Fcwd)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Its current working directory. * **[`dead`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Fdead)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether its process exited and remain-on-exit kept it. * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Fheight)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id. Prefer this for entity-scoped targeting. * pattern `"^%\\d+$"` * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`isAttended`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2FisAttended)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) A person is currently looking at this pane. * **[`isCallerPane`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2FisCallerPane)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) This is the pane this MCP server runs in. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Fplacements)** ([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)")>) Retained session and window indexes through which this pane is reachable. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`title`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Ftitle)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2Fwidth)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.output%2Fproperties%2Fpane%2Fproperties%2FwindowName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/set_pane_title/#mcp.tool.set_pane_title.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "title": { "description": "The pane's new title.", "type": "string", "x-libtmux-tmux-format": "literalized-once" } }, "required": [ "paneId", "title" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "pane": { "additionalProperties": false, "properties": { "active": { "description": "Whether this is its window's active pane.", "type": "boolean" }, "command": { "description": "The command tmux reports running in it.", "type": "string" }, "cwd": { "description": "Its current working directory.", "type": "string" }, "dead": { "description": "Whether its process exited and remain-on-exit kept it.", "type": "boolean" }, "height": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable pane id. Prefer this for entity-scoped targeting.", "pattern": "^%\\d+$", "type": "string" }, "index": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "isAttended": { "description": "A person is currently looking at this pane.", "type": "boolean" }, "isCallerPane": { "description": "This is the pane this MCP server runs in.", "type": "boolean" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "placements": { "description": "Retained session and window indexes through which this pane is reachable.", "items": { "additionalProperties": false, "properties": { "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "title": { "type": "string" }, "width": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "windowName": { "type": "string" } }, "required": [ "active", "command", "cwd", "dead", "height", "id", "index", "isAttended", "isCallerPane", "metadataComplete", "omittedMetadataBytes", "omittedPlacements", "placements", "placementsComplete", "title", "width", "windowId", "windowName" ], "type": "object" } }, "required": [ "pane" ], "type": "object" } ``` --- # set_synchronize_panes Source: https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/ > Change tmux state; no client-supplied executable input. Set the window default for synchronized pane input. Pane overrides still determine each effective configured cohort. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **set_synchronize_panes**( [enabled](https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/#mcp.tool.set_synchronize_panes.input%2Fproperties%2Fenabled): [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [windowId](https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/#mcp.tool.set_synchronize_panes.input%2Fproperties%2FwindowId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L441)][¶](https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/#mcp.tool.set_synchronize_panes) Change tmux state; no client-supplied executable input. Set the window default for synchronized pane input. Pane overrides still determine each effective configured cohort. * MCP request method `tools/call` Send `set_synchronize_panes` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/#mcp.tool.set_synchronize_panes.parameters) * **[`enabled`](https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/#mcp.tool.set_synchronize_panes.input%2Fproperties%2Fenabled)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether typing into one pane of this window types into all of them. * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/#mcp.tool.set_synchronize_panes.input%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/#mcp.tool.set_synchronize_panes.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`enabled`](https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/#mcp.tool.set_synchronize_panes.output%2Fproperties%2Fenabled)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/#mcp.tool.set_synchronize_panes.output%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/#mcp.tool.set_synchronize_panes.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/set_synchronize_panes/#mcp.tool.set_synchronize_panes.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "enabled": { "description": "Whether typing into one pane of this window types into all of them.", "type": "boolean" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "enabled", "windowId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" } }, "required": [ "enabled", "windowId" ], "type": "object" } ``` --- # show_environment Source: https://libtmux.org/en/ts/latest/mcp/tools/show_environment/ > Read the tmux environment; accepts no client-supplied executable input. Returned values may contain secrets. The environment tmux gives processes it starts, at server or session scope. This is what a new pane will inherit, not what a running one has. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **show_environment**( [session](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/#mcp.tool.show_environment.input%2Fproperties%2Fsession)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/settings.ts#L199)][¶](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/#mcp.tool.show_environment) Read the tmux environment; accepts no client-supplied executable input. Returned values may contain secrets. The environment tmux gives processes it starts, at server or session scope. This is what a new pane will inherit, not what a running one has. * MCP request method `tools/call` Send `show_environment` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/#mcp.tool.show_environment.parameters) * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/#mcp.tool.show_environment.input%2Fproperties%2Fsession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id ($1) or name. Omit for the server environment. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/#mcp.tool.show_environment.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`complete`](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/#mcp.tool.show_environment.output%2Fproperties%2Fcomplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`environment`](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/#mcp.tool.show_environment.output%2Fproperties%2Fenvironment)** ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\) * **[`omittedEntries`](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/#mcp.tool.show_environment.output%2Fproperties%2FomittedEntries)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/#mcp.tool.show_environment.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/show_environment/#mcp.tool.show_environment.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "session": { "description": "Session id ($1) or name. Omit for the server environment.", "type": "string" } }, "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "complete": { "type": "boolean" }, "environment": { "additionalProperties": { "type": [ "string", "null" ] }, "propertyNames": { "type": "string" }, "type": "object" }, "omittedEntries": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "complete", "environment", "omittedEntries" ], "type": "object" } ``` --- # show_hooks Source: https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/ > Read configured tmux commands; accepts no client-supplied executable input. Returned values may contain executable configuration. Read the hooks a server or session runs. Read-only: a hook set here would outlive this process and keep firing in somebody's tmux. Put hooks a server should keep in its config file. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **show_hooks**( [session](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/#mcp.tool.show_hooks.input%2Fproperties%2Fsession)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/settings.ts#L138)][¶](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/#mcp.tool.show_hooks) Read configured tmux commands; accepts no client-supplied executable input. Returned values may contain executable configuration. Read the hooks a server or session runs. Read-only: a hook set here would outlive this process and keep firing in somebody’s tmux. Put hooks a server should keep in its config file. * MCP request method `tools/call` Send `show_hooks` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/#mcp.tool.show_hooks.parameters) * **[`session`](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/#mcp.tool.show_hooks.input%2Fproperties%2Fsession)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session scope; omit for server scope. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/#mcp.tool.show_hooks.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`complete`](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/#mcp.tool.show_hooks.output%2Fproperties%2Fcomplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`hooks`](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/#mcp.tool.show_hooks.output%2Fproperties%2Fhooks)** ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\) * **[`omittedEntries`](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/#mcp.tool.show_hooks.output%2Fproperties%2FomittedEntries)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`unset`](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/#mcp.tool.show_hooks.output%2Fproperties%2Funset)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Hook names tmux defines that carry no command, and so are not listed. * minimum `-9007199254740991` * maximum `9007199254740991` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/#mcp.tool.show_hooks.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/show_hooks/#mcp.tool.show_hooks.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "session": { "description": "Session scope; omit for server scope.", "type": "string" } }, "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "complete": { "type": "boolean" }, "hooks": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "omittedEntries": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "unset": { "description": "Hook names tmux defines that carry no command, and so are not listed.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "complete", "hooks", "omittedEntries", "unset" ], "type": "object" } ``` --- # show_option Source: https://libtmux.org/en/ts/latest/mcp/tools/show_option/ > Read configured tmux commands; accepts no client-supplied executable input. Returned values may contain executable configuration. Read one named tmux option at server, session, window, or pane scope. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **show_option**( [name](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Fname): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [scope](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Fscope)?: "server" | "session" | "global-session" | "window" | "global-window" | "pane", [target](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Ftarget)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/settings.ts#L105)][¶](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option) Read configured tmux commands; accepts no client-supplied executable input. Returned values may contain executable configuration. Read one named tmux option at server, session, window, or pane scope. * MCP request method `tools/call` Send `show_option` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.parameters) * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The tmux option to read, such as “status-left”. * **[`scope`](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Fscope)**? ("server" | "session" | "global-session" | "window" | "global-window" | "pane") Default server. * **[`target`](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.input%2Fproperties%2Ftarget)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session id/name or pane id, for the matching scope. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`name`](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.output%2Fproperties%2Fname)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`scope`](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.output%2Fproperties%2Fscope)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`value`](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.output%2Fproperties%2Fvalue)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/show_option/#mcp.tool.show_option.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "name": { "description": "The tmux option to read, such as \"status-left\".", "type": "string" }, "scope": { "description": "Default server.", "enum": [ "server", "session", "global-session", "window", "global-window", "pane" ], "type": "string" }, "target": { "description": "Session id/name or pane id, for the matching scope.", "type": "string" } }, "required": [ "name" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "value": { "type": [ "string", "null" ] } }, "required": [ "name", "scope", "value" ], "type": "object" } ``` --- # signal_channel Source: https://libtmux.org/en/ts/latest/mcp/tools/signal_channel/ > Change tmux state; no client-supplied executable input. Signal a tmux wait-for channel. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **signal_channel**( [channel](https://libtmux.org/en/ts/latest/mcp/tools/signal_channel/#mcp.tool.signal_channel.input%2Fproperties%2Fchannel): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L386)][¶](https://libtmux.org/en/ts/latest/mcp/tools/signal_channel/#mcp.tool.signal_channel) Change tmux state; no client-supplied executable input. Signal a tmux [wait-for](https://libtmux.org/en/tmux/latest/manual/wait-for/) channel. * MCP request method `tools/call` Send `signal_channel` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/signal_channel/#mcp.tool.signal_channel.parameters) * **[`channel`](https://libtmux.org/en/ts/latest/mcp/tools/signal_channel/#mcp.tool.signal_channel.input%2Fproperties%2Fchannel)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The tmux [wait-for](https://libtmux.org/en/tmux/latest/manual/wait-for/) channel to signal. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/signal_channel/#mcp.tool.signal_channel.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`channel`](https://libtmux.org/en/ts/latest/mcp/tools/signal_channel/#mcp.tool.signal_channel.output%2Fproperties%2Fchannel)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`signalled`](https://libtmux.org/en/ts/latest/mcp/tools/signal_channel/#mcp.tool.signal_channel.output%2Fproperties%2Fsignalled)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/signal_channel/#mcp.tool.signal_channel.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/signal_channel/#mcp.tool.signal_channel.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "channel": { "description": "The tmux wait-for channel to signal.", "type": "string" } }, "required": [ "channel" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "channel": { "type": "string" }, "signalled": { "type": "boolean" } }, "required": [ "channel", "signalled" ], "type": "object" } ``` --- # snapshot_pane Source: https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/ > Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Return bounded terminal content and pane metadata in one MCP response. The metadata and capture come from separate tmux requests and are not an atomic snapshot. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **snapshot_pane**( [maxLines](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2FmaxLines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [paneId](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L305)][¶](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane) Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Return bounded terminal content and pane metadata in one MCP response. The metadata and capture come from separate tmux requests and are not an atomic snapshot. * MCP request method `tools/call` Send `snapshot_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.parameters) * **[`maxLines`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2FmaxLines)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Keep at most this many lines, from the end. Defaults to the server limit. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`content`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fcontent)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`cursorX`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2FcursorX)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`cursorY`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2FcursorY)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`droppedLines`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2FdroppedLines)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`inMode`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2FinMode)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`pane`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this is its window’s active pane. * **[`command`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The command tmux reports running in it. * **[`cwd`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Fcwd)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Its current working directory. * **[`dead`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Fdead)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether its process exited and remain-on-exit kept it. * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Fheight)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id. Prefer this for entity-scoped targeting. * pattern `"^%\\d+$"` * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`isAttended`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2FisAttended)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) A person is currently looking at this pane. * **[`isCallerPane`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2FisCallerPane)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) This is the pane this MCP server runs in. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements)** ([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)")>) Retained session and window indexes through which this pane is reachable. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`title`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Ftitle)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2Fwidth)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2Fpane%2Fproperties%2FwindowName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`scrollPosition`](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.output%2Fproperties%2FscrollPosition)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/snapshot_pane/#mcp.tool.snapshot_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "maxLines": { "description": "Keep at most this many lines, from the end. Defaults to the server limit.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "content": { "type": "string" }, "cursorX": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "cursorY": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "droppedLines": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "inMode": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "pane": { "additionalProperties": false, "properties": { "active": { "description": "Whether this is its window's active pane.", "type": "boolean" }, "command": { "description": "The command tmux reports running in it.", "type": "string" }, "cwd": { "description": "Its current working directory.", "type": "string" }, "dead": { "description": "Whether its process exited and remain-on-exit kept it.", "type": "boolean" }, "height": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable pane id. Prefer this for entity-scoped targeting.", "pattern": "^%\\d+$", "type": "string" }, "index": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "isAttended": { "description": "A person is currently looking at this pane.", "type": "boolean" }, "isCallerPane": { "description": "This is the pane this MCP server runs in.", "type": "boolean" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "placements": { "description": "Retained session and window indexes through which this pane is reachable.", "items": { "additionalProperties": false, "properties": { "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "title": { "type": "string" }, "width": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "windowName": { "type": "string" } }, "required": [ "active", "command", "cwd", "dead", "height", "id", "index", "isAttended", "isCallerPane", "metadataComplete", "omittedMetadataBytes", "omittedPlacements", "placements", "placementsComplete", "title", "width", "windowId", "windowName" ], "type": "object" }, "scrollPosition": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "content", "cursorX", "cursorY", "droppedLines", "inMode", "pane", "scrollPosition" ], "type": "object" } ``` --- # split_window Source: https://libtmux.org/en/ts/latest/mcp/tools/split_window/ > Start a pane's configured process; accepts no command payload. Split a pane and return the new one. Direction is where the new pane goes relative to the one you split. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **split_window**( [direction](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fdirection)?: "above" | "below" | "left" | "right", [paneId](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [startDirectory](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2FstartDirectory)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/lifecycle.ts#L190)][¶](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window) Start a pane’s configured process; accepts no command payload. Split a pane and return the new one. Direction is where the new pane goes relative to the one you split. * MCP request method `tools/call` Send `split_window` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.parameters) * **[`direction`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2Fdirection)**? ("above" | "below" | "left" | "right") Default below. * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`startDirectory`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.input%2Fproperties%2FstartDirectory)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Defaults to the directory the pane being split is in. ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`pane`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this is its window’s active pane. * **[`command`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The command tmux reports running in it. * **[`cwd`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Fcwd)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Its current working directory. * **[`dead`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Fdead)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether its process exited and remain-on-exit kept it. * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Fheight)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id. Prefer this for entity-scoped targeting. * pattern `"^%\\d+$"` * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`isAttended`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2FisAttended)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) A person is currently looking at this pane. * **[`isCallerPane`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2FisCallerPane)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) This is the pane this MCP server runs in. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Fplacements)** ([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)")>) Retained session and window indexes through which this pane is reachable. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`title`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Ftitle)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2Fwidth)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.output%2Fproperties%2Fpane%2Fproperties%2FwindowName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/split_window/#mcp.tool.split_window.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "direction": { "description": "Default below.", "enum": [ "above", "below", "left", "right" ], "type": "string" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "startDirectory": { "description": "Defaults to the directory the pane being split is in.", "type": "string", "x-libtmux-tmux-format": "literalized-once" } }, "required": [ "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "pane": { "additionalProperties": false, "properties": { "active": { "description": "Whether this is its window's active pane.", "type": "boolean" }, "command": { "description": "The command tmux reports running in it.", "type": "string" }, "cwd": { "description": "Its current working directory.", "type": "string" }, "dead": { "description": "Whether its process exited and remain-on-exit kept it.", "type": "boolean" }, "height": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable pane id. Prefer this for entity-scoped targeting.", "pattern": "^%\\d+$", "type": "string" }, "index": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "isAttended": { "description": "A person is currently looking at this pane.", "type": "boolean" }, "isCallerPane": { "description": "This is the pane this MCP server runs in.", "type": "boolean" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "placements": { "description": "Retained session and window indexes through which this pane is reachable.", "items": { "additionalProperties": false, "properties": { "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "title": { "type": "string" }, "width": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "windowName": { "type": "string" } }, "required": [ "active", "command", "cwd", "dead", "height", "id", "index", "isAttended", "isCallerPane", "metadataComplete", "omittedMetadataBytes", "omittedPlacements", "placements", "placementsComplete", "title", "width", "windowId", "windowName" ], "type": "object" } }, "required": [ "pane" ], "type": "object" } ``` --- # swap_pane Source: https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/ > Change tmux state; no client-supplied executable input. Exchange two panes' positions. Their ids and contents travel with them. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **swap_pane**( [otherPaneId](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.input%2Fproperties%2FotherPaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [paneId](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/layout.ts#L230)][¶](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane) Change tmux state; no client-supplied executable input. Exchange two panes’ positions. Their ids and contents travel with them. * MCP request method `tools/call` Send `swap_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.parameters) * **[`otherPaneId`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.input%2Fproperties%2FotherPaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`complete`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fcomplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) * **[`omittedEntries`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2FomittedEntries)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `0` * maximum `9007199254740991` * **[`panes`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes)** ([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/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`active`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Factive)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether this is its window’s active pane. * **[`command`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fcommand)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The command tmux reports running in it. * **[`cwd`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fcwd)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Its current working directory. * **[`dead`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fdead)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether its process exited and remain-on-exit kept it. * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fheight)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`id`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fid)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id. Prefer this for entity-scoped targeting. * pattern `"^%\\d+$"` * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`isAttended`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FisAttended)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) A person is currently looking at this pane. * **[`isCallerPane`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FisCallerPane)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) This is the pane this MCP server runs in. * **[`metadataComplete`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FmetadataComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether every projected metadata string is complete. * **[`omittedMetadataBytes`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FomittedMetadataBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes omitted from projected metadata strings. * minimum `0` * maximum `9007199254740991` * **[`omittedPlacements`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FomittedPlacements)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Later placements omitted. * minimum `0` * maximum `9007199254740991` * **[`placements`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fplacements)** ([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)")>) Retained session and window indexes through which this pane is reachable. * **[Items](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fplacements%2Fitems)** ([object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")) * **[`index`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2Findex)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The window index in this session. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`sessionId`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable session id, e.g. $1. * pattern `"^\\$\\d+$"` * **[`sessionName`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fplacements%2Fitems%2Fproperties%2FsessionName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. * **[`placementsComplete`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FplacementsComplete)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether placements contains every placement. * **[`title`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Ftitle)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2Fwidth)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) * minimum `-9007199254740991` * maximum `9007199254740991` * **[`windowId`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FwindowId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable window id, e.g. @1. * pattern `"^@\\d+$"` * **[`windowName`](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.output%2Fproperties%2Fpanes%2Fitems%2Fproperties%2FwindowName)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) No other properties are accepted. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/swap_pane/#mcp.tool.swap_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "otherPaneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" } }, "required": [ "otherPaneId", "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "complete": { "type": "boolean" }, "omittedEntries": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "panes": { "items": { "additionalProperties": false, "properties": { "active": { "description": "Whether this is its window's active pane.", "type": "boolean" }, "command": { "description": "The command tmux reports running in it.", "type": "string" }, "cwd": { "description": "Its current working directory.", "type": "string" }, "dead": { "description": "Whether its process exited and remain-on-exit kept it.", "type": "boolean" }, "height": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "id": { "description": "Stable pane id. Prefer this for entity-scoped targeting.", "pattern": "^%\\d+$", "type": "string" }, "index": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "isAttended": { "description": "A person is currently looking at this pane.", "type": "boolean" }, "isCallerPane": { "description": "This is the pane this MCP server runs in.", "type": "boolean" }, "metadataComplete": { "description": "Whether every projected metadata string is complete.", "type": "boolean" }, "omittedMetadataBytes": { "description": "UTF-8 bytes omitted from projected metadata strings.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "omittedPlacements": { "description": "Later placements omitted.", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "placements": { "description": "Retained session and window indexes through which this pane is reachable.", "items": { "additionalProperties": false, "properties": { "index": { "description": "The window index in this session.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "sessionId": { "description": "Stable session id, e.g. $1.", "pattern": "^\\$\\d+$", "type": "string" }, "sessionName": { "type": "string" } }, "required": [ "index", "sessionId", "sessionName" ], "type": "object" }, "type": "array" }, "placementsComplete": { "description": "Whether placements contains every placement.", "type": "boolean" }, "title": { "type": "string" }, "width": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "windowId": { "description": "Stable window id, e.g. @1.", "pattern": "^@\\d+$", "type": "string" }, "windowName": { "type": "string" } }, "required": [ "active", "command", "cwd", "dead", "height", "id", "index", "isAttended", "isCallerPane", "metadataComplete", "omittedMetadataBytes", "omittedPlacements", "placements", "placementsComplete", "title", "width", "windowId", "windowName" ], "type": "object" }, "type": "array" } }, "required": [ "complete", "omittedEntries", "panes" ], "type": "object" } ``` --- # wait_for_channel Source: https://libtmux.org/en/ts/latest/mcp/tools/wait_for_channel/ > Change tmux state; no client-supplied executable input. Wait until a tmux wait-for channel is signalled. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **wait_for_channel**( [channel](https://libtmux.org/en/ts/latest/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)"), [timeoutMs](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.input%2Fproperties%2FtimeoutMs)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/target.ts#L358)][¶](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel) Change tmux state; no client-supplied executable input. Wait until a tmux [wait-for](https://libtmux.org/en/tmux/latest/manual/wait-for/) channel is signalled. * MCP request method `tools/call` Send `wait_for_channel` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.parameters) * **[`channel`](https://libtmux.org/en/ts/latest/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)")) The tmux [wait-for](https://libtmux.org/en/tmux/latest/manual/wait-for/) channel name. * **[`timeoutMs`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.input%2Fproperties%2FtimeoutMs)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Give up after this long. Defaults to the server’s wait ceiling. * maximum `9007199254740991` * exclusiveMinimum `0` ## Result[#](https://libtmux.org/en/ts/latest/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)") * **[`channel`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.output%2Fproperties%2Fchannel)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * **[`signalled`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.output%2Fproperties%2Fsignalled)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_channel/#mcp.tool.wait_for_channel.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "channel": { "description": "The tmux wait-for channel name.", "type": "string" }, "timeoutMs": { "description": "Give up after this long. Defaults to the server's wait ceiling.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" } }, "required": [ "channel" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "channel": { "type": "string" }, "signalled": { "type": "boolean" } }, "required": [ "channel", "signalled" ], "type": "object" } ``` --- # wait_for_text Source: https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/ > Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Wait until a pane prints something, streaming tmux's notifications rather than polling. Use for output you did NOT author — another process, a person, a background job. For a command you wrote, use run_shell_command: it knows when the command ended and reports exit status, which no text match can. This discounts text this server itself typed into the pane, for as long as it is unsubmitted or was submitted within the last ten seconds, so a command you just sent cannot match its own echo — but a pane not yet reading input can still echo type-ahead back once it starts, so wait for a prompt before typing into a cold shell. Whatever happens you get back what the pane printed and why the wait ended — a timeout is never an empty answer. tool MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * **wait_for_text**( [cursor](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fcursor)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [maxLines](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2FmaxLines)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [paneId](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2FpaneId): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [patterns](https://libtmux.org/en/ts/latest/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)")>, [regex](https://libtmux.org/en/ts/latest/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)"), [timeoutMs](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2FtimeoutMs)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), ) tool \[[source](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/mcp/src/tools/wait.ts#L503)][¶](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text) Read pane output; accepts no client-supplied executable input. Returned content may be sensitive or untrusted. Wait until a pane prints something, streaming tmux’s notifications rather than polling. Use for output you did NOT author — another process, a person, a background job. For a command you wrote, use [run_shell_command](https://libtmux.org/en/ts/latest/mcp/tools/run_shell_command/): it knows when the command ended and reports exit status, which no text match can. This discounts text this server itself typed into the pane, for as long as it is unsubmitted or was submitted within the last ten seconds, so a command you just sent cannot match its own echo — but a pane not yet reading input can still echo type-ahead back once it starts, so wait for a prompt before typing into a cold shell. Whatever happens you get back what the pane printed and why the wait ended — a timeout is never an empty answer. * MCP request method `tools/call` Send `wait_for_text` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.parameters) * **[`cursor`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fcursor)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Start from a cursor an earlier [capture_since](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/) or wait returned. * pattern `"^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$"` * **[`maxLines`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2FmaxLines)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Keep at most this many lines, from the end. Defaults to the server limit. * maximum `9007199254740991` * exclusiveMinimum `0` * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`patterns`](https://libtmux.org/en/ts/latest/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)")>) Any one of these ends the wait. Omit to wait for any output at all. * maxItems `64` - **[Items](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2Fpatterns%2Fitems)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * minLength `1` * **[`regex`](https://libtmux.org/en/ts/latest/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)")) Interpret patterns using libtmux’s bounded regular-expression grammar. * **[`timeoutMs`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.input%2Fproperties%2FtimeoutMs)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Clamped by the server ceiling; the result reports what was used. * maximum `9007199254740991` * exclusiveMinimum `0` ## Result[#](https://libtmux.org/en/ts/latest/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)") * **[`alreadyOnScreen`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FalreadyOnScreen)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) The pattern is on the pane now but printed before this wait began, so the wait could not match it. Read it with [capture_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/) rather than waiting again. * **[`cursor`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%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)")) Pass to [capture_since](https://libtmux.org/en/ts/latest/mcp/tools/capture_since/) or another wait; null means the live stream cannot be resumed. Matches one or more variants. * **[Variant 1](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Fcursor%2FanyOf%2F0)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) * pattern `"^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$"` * **[`droppedLines`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FdroppedLines)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Output lines omitted by the result limit. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`effectiveTimeoutMs`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FeffectiveTimeoutMs)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) The timeout actually enforced, after clamping. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`matched`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Fmatched)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) The text that matched, or null. * **[`missedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FmissedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Retained output lost before this read; non-zero means the result is incomplete. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`omittedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FomittedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Output bytes omitted by the result ceiling. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`outcome`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Foutcome)** ("matched" | "timed_out" | "pane_died" | "no_stream" | "cancelled" | "output_lost" | "stream_lost") Why the wait ended. Read this rather than guessing from the output. * **[`output`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Foutput)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) The bounded tail of what the pane printed while waiting. * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Stable pane id, e.g. %1. * pattern `"^%\\d+$"` * **[`returnedBytes`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FreturnedBytes)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) UTF-8 bytes returned across output and screen. * minimum `-9007199254740991` * maximum `9007199254740991` * **[`screen`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2Fscreen)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) What the pane shows now after a miss, unless result limits omit it; see screenClamped. * **[`screenClamped`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FscreenClamped)** ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) Whether result limits shortened the pane screen. * **[`streamFailure`](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.output%2Fproperties%2FstreamFailure)** ("connection_lost" | "events_dropped" | "expired" | "hub_closed" | "topology_changed" | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Why the live stream ended, or null while it remained valid. No other properties are accepted. ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.annotations) * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/wait_for_text/#mcp.tool.wait_for_text.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "cursor": { "description": "Start from a cursor an earlier capture_since or wait returned.", "pattern": "^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$", "type": "string" }, "maxLines": { "description": "Keep at most this many lines, from the end. Defaults to the server limit.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "patterns": { "description": "Any one of these ends the wait. Omit to wait for any output at all.", "items": { "minLength": 1, "type": "string" }, "maxItems": 64, "type": "array" }, "regex": { "description": "Interpret patterns using libtmux's bounded regular-expression grammar.", "type": "boolean" }, "timeoutMs": { "description": "Clamped by the server ceiling; the result reports what was used.", "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" } }, "required": [ "paneId" ], "type": "object" } ``` Output schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "properties": { "alreadyOnScreen": { "description": "The pattern is on the pane now but printed before this wait began, so the wait could not match it. Read it with capture_pane rather than waiting again.", "type": "boolean" }, "cursor": { "anyOf": [ { "pattern": "^ltxc1\\.[0-9a-f]{32}\\.(?:0|[1-9][0-9]*)$", "type": "string" }, { "type": "null" } ], "description": "Pass to capture_since or another wait; null means the live stream cannot be resumed." }, "droppedLines": { "description": "Output lines omitted by the result limit.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "effectiveTimeoutMs": { "description": "The timeout actually enforced, after clamping.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "matched": { "description": "The text that matched, or null.", "type": [ "string", "null" ] }, "missedBytes": { "description": "Retained output lost before this read; non-zero means the result is incomplete.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "omittedBytes": { "description": "Output bytes omitted by the result ceiling.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "outcome": { "description": "Why the wait ended. Read this rather than guessing from the output.", "enum": [ "matched", "timed_out", "pane_died", "no_stream", "cancelled", "output_lost", "stream_lost" ], "type": "string" }, "output": { "description": "The bounded tail of what the pane printed while waiting.", "type": "string" }, "paneId": { "description": "Stable pane id, e.g. %1.", "pattern": "^%\\d+$", "type": "string" }, "returnedBytes": { "description": "UTF-8 bytes returned across output and screen.", "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "screen": { "description": "What the pane shows now after a miss, unless result limits omit it; see screenClamped.", "type": "string" }, "screenClamped": { "description": "Whether result limits shortened the pane screen.", "type": "boolean" }, "streamFailure": { "anyOf": [ { "enum": [ "connection_lost", "events_dropped", "expired", "hub_closed", "topology_changed" ], "type": "string" }, { "type": "null" } ], "description": "Why the live stream ended, or null while it remained valid." } }, "required": [ "alreadyOnScreen", "cursor", "droppedLines", "effectiveTimeoutMs", "matched", "missedBytes", "omittedBytes", "outcome", "output", "paneId", "returnedBytes", "screen", "screenClamped", "streamFailure" ], "type": "object" } ``` --- # Prompts Source: https://libtmux.org/en/ts/latest/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 concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) The reference configuration advertises 0 prompts. Your server’s available objects depend on its configuration. [Setup documentation](https://libtmux.org/en/ts/latest/mcp/guides/) explains how to connect a client. This server does not advertise prompts 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/ts/latest/mcp/tools.json). Source: [`libtmux/libtmux-ts@46cccfef2a54`](https://github.com/libtmux/libtmux-ts/tree/46cccfef2a546de55ce8b308249b8c76339089a0). The [language API reference](https://libtmux.org/en/ts/latest/mcp/reference/) documents embedding and implementation types. Source revision: [libtmux/libtmux-ts@ecc3eaca0b4e05a77360da9d56790b409282c63b](https://github.com/libtmux/libtmux-ts/tree/ecc3eaca0b4e05a77360da9d56790b409282c63b). --- # Resources Source: https://libtmux.org/en/ts/latest/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 concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) The reference configuration advertises 1 resources and resource templates. Your server’s available objects depend on its configuration. [Setup documentation](https://libtmux.org/en/ts/latest/mcp/guides/) explains how to connect a client. ## Fixed resources1 object[#](https://libtmux.org/en/ts/latest/mcp/resources/#resources-fixed-resources) [capabilities](https://libtmux.org/en/ts/latest/mcp/resources/capabilities/) The frozen structured-tool surface and its capability declarations. Reference configuration * `LIBTMUX_TOOLSETS` `inspect,manage,execute,teardown` Protocol version: `2025-11-25`. [Download the full protocol catalog](https://libtmux.org/en/ts/latest/mcp/tools.json). Source: [`libtmux/libtmux-ts@46cccfef2a54`](https://github.com/libtmux/libtmux-ts/tree/46cccfef2a546de55ce8b308249b8c76339089a0). The [language API reference](https://libtmux.org/en/ts/latest/mcp/reference/) documents embedding and implementation types. Source revision: [libtmux/libtmux-ts@ecc3eaca0b4e05a77360da9d56790b409282c63b](https://github.com/libtmux/libtmux-ts/tree/ecc3eaca0b4e05a77360da9d56790b409282c63b). --- # capabilities Source: https://libtmux.org/en/ts/latest/mcp/resources/capabilities/ > The frozen structured-tool surface and its capability declarations. resource MCPlatest MCP concept example A working example of the core library. It can change without notice. [What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha) * `tmux://capabilities` resource [¶](https://libtmux.org/en/ts/latest/mcp/resources/capabilities/#mcp.resource.tmux%3A%2F%2Fcapabilities) The frozen structured-tool surface and its capability declarations. * MCP request method `resources/read` Send the resource URI shown above. * MIME type `application/json` ## URI parameters[#](https://libtmux.org/en/ts/latest/mcp/resources/capabilities/#mcp.resource.tmux%3A%2F%2Fcapabilities.parameters) Read this resource using its fixed URI. ## Result[#](https://libtmux.org/en/ts/latest/mcp/resources/capabilities/#mcp.resource.tmux%3A%2F%2Fcapabilities.result) Returns resource contents for the requested URI with MIME type `application/json`. ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/resources/capabilities/#mcp.resource.tmux%3A%2F%2Fcapabilities.schemas) Use the complete advertised contract for validation and client integration. Registration ```json { "description": "The frozen structured-tool surface and its capability declarations.", "mimeType": "application/json", "name": "capabilities", "title": "Capabilities", "uri": "tmux://capabilities" } ``` Source revision: [libtmux/libtmux-ts@ecc3eaca0b4e05a77360da9d56790b409282c63b](https://github.com/libtmux/libtmux-ts/tree/ecc3eaca0b4e05a77360da9d56790b409282c63b).