Run an arbitrary tmux command and return its raw result.

This is the universal escape hatch — it runs tmux <args> verbatim, so it can do anything the target's tmux supports. Pass the subcommand and its flags as a list, e.g. args=["new-window", "-t", "mysess", "-n", "logs"]. Do NOT include the leading "tmux".

Returns {"stdout", "stderr", "exit_code"}. Non-zero exit codes are returned, not raised, so you can inspect failures.

target selects where tmux runs: omit (or "local") for the local machine, a named profile from the config file, or an ad-hoc ssh destination like "user@host".

Evaluate a tmux format string (e.g. "#{pane_current_path}").

Uses display-message -p to expand any #{...} format variable. Optional target_pane sets the context (-t) the format is evaluated against. Returns {"value": }.

Report the target's tmux version and whether it is supported (1.8+).

List configured targets: 'local' plus any named profiles from config.

Kill the tmux server on the target (destructive: ends ALL sessions).

List all sessions on the target with id, name, window count, etc.

Check whether a session exists. Returns {"exists": bool}.

Create a new session (detached by default).

Optional command runs as the first pane's command; start_directory sets the working dir; width/height size the detached session. attach_or_create=True makes the call idempotent: if a session named name already exists it is reused (its id/name returned) instead of erroring, otherwise it is created. tmux's own new-session -A attaches the existing session, which a headless MCP server has no terminal to do; so the reuse here is a detached has-session check (the create-time options below only apply when the session is actually created). env (-e KEY=VAL, tmux 3.0+) sets session environment variables before the first command launches; ignored with a note on older tmux. Returns the created (or existing) session's {"id", "name"}.

Rename a session.

Kill a session (destructive). Ends all its windows and panes.

List windows. With session, lists that session's windows; otherwise all windows on the server (-a).

Create a window. session is the target session (or "sess:index").

Set select=False to create it in the background (-d). Returns the new window's {"id", "index", "name"}.

Make a window the active one (e.g. window="mysess:2").

Switch to the previously selected window (last-window).

With session (-t), acts on that session; otherwise the current one. Returns {"selected": "last"}.

Rotate a window to its next preset layout (next-layout).

With window (-t), acts on that window; otherwise the current one. Returns {"window": window}.

Rename a window.

Move/renumber a window from src to dst (e.g. "sess:5").

Swap two windows.

Restart the command in a window (respawn-window), reusing it in place.

Like tmux_respawn_pane but for a whole window (its single/first pane). By default tmux only respawns a window whose command has exited; set kill=True (-k) to force-restart a live one. command defaults to the window's original command; start_directory sets its cwd (-c). env (-e KEY=VAL, tmux 3.0+) injects environment variables; ignored with a note on older tmux.

Returns {"respawned": True, "window": window}.

Kill a window (destructive).

List panes. Scope to a window (-t), a session (-s), or the whole server (default, -a).

Split a pane. By default splits left/right; vertical=True splits top/bottom. percentage sizes the new pane (e.g. 30). select=False keeps focus on the original pane (-d).

Returns the new pane's {"id", "index"}.

Make a pane the active one.

Switch to the previously active pane (last-pane).

With window (-t), acts on that window; otherwise the current one. Returns {"selected": "last"}.

Set a pane's title (select-pane -T, tmux 2.6+).

The title is the #{pane_title} reported by tmux_list_panes; it's a handy label for agents driving several panes (it does not change the window name). Requires tmux 2.6+; on older tmux it is a no-op with a note.

Returns {"pane": target_pane, "title": title} (or {"notes": [...]}).

Resize a pane by a number of cells in one or more directions.

Swap two panes.

Kill a pane (destructive).

Wipe a pane's scrollback history (clear-history -t pane).

Use this before a tmux_send_keys / tmux_run so a subsequent tmux_capture_pane(start=...) starts from a clean slate, without the previous output bleeding into the captured range. It clears the scrollback buffer only — the visible screen is untouched.

Returns {"cleared": True, "pane": target_pane}.

Restart the command in a pane (respawn-pane), reusing it in place.

Useful for retrying a crashed command or supervising a service without recreating the window layout. By default tmux only respawns a pane whose command has already exited; set kill=True (-k) to force-restart one that is still running. command is the shell command to run (defaults to the pane's original command); start_directory sets its cwd (-c). env (-e KEY=VAL, tmux 3.0+) injects environment variables; ignored with a note on older tmux.

Returns {"respawned": True, "pane": target_pane}.

Apply a named layout (even-horizontal, even-vertical, main-horizontal, main-vertical, tiled) or a layout string to a window.

Send input to a pane.

Two modes (provide exactly one of text / keys):

• text: a literal string. With literal=True (default) it is sent exactly as written via send-keys -l (so "C-c" types those three characters). Set literal=False to let tmux interpret key names inside the string.

• keys: a list of tmux key tokens interpreted by tmux, e.g. ["C-c"], ["Escape"], ["Up", "Up", "Enter"].

enter=True appends an Enter keypress after the input — the usual way to "run" a typed command. Returns {"sent": True}.

Capture (read) the visible contents and/or scrollback of a pane.

This is the primary way to observe output. start/end select a scrollback line range (-S/-E): negative or "-" for the start of history, e.g. start=-100 grabs the last 100+ lines. escapes=True keeps ANSI color/escape sequences (-e). join=True rejoins wrapped lines (-J). trim=True (default) drops the empty padding lines tmux emits below the last line of real content; set trim=False to keep the raw capture.

Returns {"content": }.

Set a tmux option.

scope is one of "server" (-s), "session" (default), "window" (-w), or "pane" (-p, requires newer tmux). target_entity is the -t target for session/window/pane scope.

Show tmux options for a scope. Returns {"options": {name: value}}.

List paste buffers with their names and sizes.

Set a paste buffer's contents (optionally named with -b).

Paste a buffer into a pane. delete=True removes the buffer after (-d).

Delete a named paste buffer.

Write a paste buffer to a file (save-buffer).

name selects a named buffer (-b); the default is the most recent one. append=True appends to the file instead of overwriting (-a). IMPORTANT: path is resolved on the target — for an SSH target it is a file on the remote host, not the local machine.

Returns {"saved": path, "name": name}.

Load a file's contents into a paste buffer (load-buffer).

name stores it under a named buffer (-b). IMPORTANT: path is resolved on the target — for an SSH target it is a file on the remote host, not the local machine.

Returns {"loaded": path, "name": name}.

Set or unset an environment variable for a session (or globally).

Set global_=True (-g) to affect the global environment that new sessions inherit, instead of one session. With a value, sets the variable; commands spawned afterwards in that session's panes inherit it (the race-free alternative to an export typed via send_keys).

To clear a variable, pass remove=True (-r, mark it for removal so the child sees it unset even if it exists globally) or unset=True (-u, delete it from this session's environment). session is the -t target.

Returns {"set"/"removed"/"unset": name, ...}.

Show a session's environment (or the global one with global_=True).

With name, returns just that variable. Variables tmux has marked for removal (shown by tmux as -NAME) are reported as removed=True with a null value.

Returns {"environment": {name: value_or_None}, "removed": [names...]}.

Wait until pattern appears in a pane, or timeout seconds elapse.

pattern is a substring by default, or a regular expression when regex=True. history optionally includes that many scrollback lines in each check (-S -history). Returns {"matched", "elapsed", "content"} where content is the last capture taken.

Caveat: the pane also shows the command you typed, so a pattern can match your own echoed input line rather than the command's output. To wait for a command to finish and get just its output, prefer tmux_run.

Wait until a pane's visible content stops changing.

Returns once the capture is unchanged for idle_seconds (i.e. output has settled), or after timeout. Returns {"idle", "elapsed", "content"}.

Run a shell command in a pane and return just its output + exit code.

Types command into the pane bracketed by unique markers, then polls until the command finishes, and returns the text printed between the markers. This is the reliable alternative to send-keys + sleep + capture.

Intended for NON-interactive commands at a shell prompt. Returns {"completed", "exit_code", "output", "elapsed"}; on timeout, completed is False and output holds the raw capture so far.

List clients attached to the server.

With session, lists only the clients attached to that session (-t). Each client has its tty, attached session, and size. Returns {"clients": [...]}.

Report basic server facts: pid, socket path, and tmux version.

Returns {"pid", "socket_path", "version", "supported"}.

Show a message on a client's status line.

Unlike tmux_query (which prints an expanded format to you via display-message -p), this displays message on the tmux screen of the attached client. #{...} format variables in message are expanded against target_pane's context if given. Returns {"displayed": True}.

Link a window into another location (it then appears in both).

src is the source window (e.g. "sess1:2"), dst the destination (e.g. "sess2:" for the next free index, or "sess2:5"). select=False links it in the background (-d). The same window now lives in both spots; use tmux_unlink_window to remove a link.

Unlink a window (remove one of its links).

Fails if the window is only linked once, unless it is not the last — tmux refuses to leave a window with no links. Use tmux_kill_window to destroy it outright.

Break a pane out into a new window of its own.

window_name names the new window; select=False creates it in the background (-d). Returns the new window's {"id", "index", "name"}.

Join pane src into dst's window as a new split (the inverse of break-pane).

By default splits left/right; vertical=True stacks top/bottom. percentage sizes the joined pane. select=False keeps focus on the original pane (-d).

Find windows whose name, title, or current command matches pattern.

pattern is matched case-insensitively as a substring. Scope to a session, or search the whole server (default). Returns the matching window records {"matches": [...]}.

(tmux's own find-window is interactive — it opens a chooser in an attached client — so this performs a non-interactive search over list-windows instead, which is what an agent actually wants.)

Pipe a pane's output to a shell command (great for logging).

With command, tmux feeds everything the pane prints to that command's stdin, e.g. command="cat >> /tmp/pane.log". only_new=True (-o) toggles: if a pipe is already open it is closed, otherwise opened. Call with no command to stop piping. Returns {"piping": bool}.

Set (or unset) a hook that runs a tmux command on an event.

hook is the event name, e.g. "pane-died" or "session-created"; command is the tmux command to run (a command string like 'display "gone"'). global_=True (-g) sets it server-wide; unset=True (-u) removes the hook instead. Requires tmux 2.2+.

Show the hooks set on the server/session. Returns {"hooks": {name: command}}.

Run a shell command from tmux via run-shell.

background=True (-b) runs it without waiting. Note: tmux surfaces the command's stdout in a message/copy buffer rather than returning it here, so output is usually empty — to capture a command's output prefer tmux_run. Returns {"output", "exit_code"}.

Run a tmux command conditionally with if-shell.

Runs condition as a shell command; if it succeeds, runs the tmux command if_command, otherwise else_command (if given). is_format=True (-F) treats condition as a tmux format that is true unless it evaluates to empty or "0" (no shell). background=True (-b) runs in the background.

List key bindings, optionally restricted to one key table (e.g. "prefix", "root", "copy-mode"). Returns the raw bindings as {"keys": , "lines": [...]} — one bind-key ... line each.

Bind key to a tmux command.

command is the tmux command + args as a list, e.g. ["new-window", "-n", "logs"]. table selects the key table; root=True (-n) binds in the root table so no prefix is needed; repeat=True (-r) allows the key to repeat. Returns {"bound": key}.

Unbind a key. Provide key, or all=True (-a) to clear every binding (in table if given). root=True (-n) targets the root table. Returns {"unbound": ...}.

Enter (or exit) copy mode in a pane.

page_up=True (-u) scrolls up one page on entry. exit=True leaves copy mode instead (sends the copy-mode cancel command, tmux 2.4+). Returns {"copy_mode": bool}.

Scroll within copy mode.

direction is one of: up, down, page-up, page-down, halfpage-up, halfpage-down, top, bottom. amount repeats the step (ignored for top/bottom). Enters copy mode first if needed. Requires tmux 2.4+.

Search the scrollback in copy mode for pattern.

backward=True searches towards the top of history (the usual direction for finding recent output); set backward=False to search forward. Enters copy mode first if needed. Requires tmux 2.4+. Returns {"searched": ...}.

Open (or reuse) a control-mode stream attached to session.

Starts a persistent tmux -C attach -t <session> connection that captures pane output and window/layout events. Idempotent per (target, session). Returns {"stream_id", "session", "target", "alive"}; pass the stream_id to tmux_stream_read/_send/_stop.

Pass width/height (both, tmux 2.4+) to set the control client's size via refresh-client -C WxH right after attach — otherwise it defaults to 80x24 and wraps %output for wider panes oddly. The size is re-applied automatically if the connection drops and reconnects; tmux_stream_resize changes it later. The connection also auto-reconnects on an unexpected drop (e.g. a flaky SSH link), surfacing reconnected/disconnected events in the stream.

Set a stream's control-client size (refresh-client -C WxH, tmux 2.4+).

Use this when pane output wraps at the wrong width — a control client defaults to 80x24. The size sticks across auto-reconnects. Returns {"stream_id", "width", "height"}.

Long-poll new events from a stream (blocks until output or timeout).

Returns {"events", "cursor", "alive", "lagged"}. Each event has a seq, a type ("output", "window-add", "layout-change", "exit", ...) and, where relevant, pane/window/session ids and data. For "output" events data is the decoded pane text (ANSI stripped unless strip_ansi=False).

Filter with pane (e.g. "%0") and/or kinds (e.g. ["output"]). The cursor auto-advances between calls, so just call again to get the next batch; pass an explicit cursor to re-read from a known point. lagged is true if the buffer overflowed and some events were dropped.

Run a tmux command over the stream's control connection.

command is a tmux command line (no leading "tmux"), e.g. "list-windows". Returns {"reply"} with the command's text reply. Errors from tmux are raised. Output the command triggers in panes still arrives as %output events via tmux_stream_read.

List active control-mode streams and their state. Returns {"streams": [{stream_id, session, target, alive, buffered, panes, ...}]}.

Stop a stream: detach the control client (the session keeps running) and free the connection. Returns {"stopped": stream_id}.