(tools-overview)=

# Tools

Targeted tmux tools accept an optional `socket_name` parameter for
multi-server support. It defaults to the {envvar}`LIBTMUX_SOCKET` env
var. {toolref}`list-servers` discovers sockets itself, and batch tools
leave socket selection inside each nested tool's arguments. See
{ref}`configuration`.

## Which tool do I want?

**Reading terminal content?**
- Re-reading the same pane while it changes? → {tool}`capture-since`
- Need a one-shot read of a known pane? → {tool}`capture-pane`
- Need text + cursor + mode in one call? → {tool}`snapshot-pane`
- Don't know which pane? → {tool}`search-panes`
- Need to wait for specific output? → {tool}`wait-for-text`
- Need to wait for *any* change? → {tool}`wait-for-content-change`
- Only need metadata (PID, path, size)? → {tool}`get-pane-info`
- Need an arbitrary tmux variable? → {tool}`display-message`

**Targeting a pane by layout?**
- "The bottom-right pane", "top-left", any corner → {tool}`find-pane-by-position`
- Already know the `pane_id` → use it directly

**Running a command?**
- {tool}`run-command` — one call to run a shell command, wait for completion, capture output, and return exit status
- {tool}`send-keys` / {tool}`send-keys-batch` — raw interactive input for TUIs, control keys, and persistent shell state
- {tool}`wait-for-channel` — low-level custom completion when `run-command` does not fit the shell composition
- For output the agent does not author (third-party logs, daemon prompts), use {tool}`wait-for-text`, {tool}`wait-for-content-change`, or {tool}`capture-since`
- Pasting multi-line text? → {tool}`paste-text`

**Creating workspace structure?**
- New session → {tool}`create-session`
- New window → {tool}`create-window`
- New pane → {tool}`split-window`

**Navigating?**
- Switch pane → {tool}`select-pane` (by ID or direction)
- Switch window → {tool}`select-window` (by ID, index, or direction)

**Rearranging layout?**
- Swap two panes → {tool}`swap-pane`
- Move window → {tool}`move-window`
- Change layout → {tool}`select-layout`

**Scrollback / copy mode?**
- Enter copy mode → {tool}`enter-copy-mode`
- Exit copy mode → {tool}`exit-copy-mode`
- Log output to file → {tool}`pipe-pane`

**Coordinating across panes?**
- Block until signalled → {tool}`wait-for-channel`
- Signal a waiter → {tool}`signal-channel`

**Batching typed tool calls?**
- Read-only observations → {tool}`call-readonly-tools-batch`
- Ordered readonly + mutating workflows → {tool}`call-mutating-tools-batch`
- Reviewed workflows that include destructive steps → {tool}`call-destructive-tools-batch`

**Staging multi-line input?**
- Stage content → {tool}`load-buffer`
- Push into pane → {tool}`paste-buffer`
- Read back → {tool}`show-buffer`
- Free server state → {tool}`delete-buffer`

**Auditing tmux hooks?**
- Enumerate → {tool}`show-hooks`
- Inspect one → {tool}`show-hook`

**Changing settings?**
- tmux options → {tool}`show-option` / {tool}`set-option`
- Environment vars → {tool}`show-environment` / {tool}`set-environment`

**Reaching for a workflow recipe?** The server also ships four
short MCP prompts the client renders for the model — see
{doc}`/prompts`. They cover the most common patterns
(run-and-wait, diagnose-failing-pane, build-dev-workspace,
interrupt-gracefully) with embedded UUID-scoped wait channels and
shell-agnostic guidance.

## Inspect

Read tmux state without changing anything.

::::{grid} 1 2 3 3
:gutter: 2 2 3 3

:::{grid-item-card} list_sessions
:link: list-sessions
:link-type: ref
List all active sessions.
:::

:::{grid-item-card} list_windows
:link: list-windows
:link-type: ref
List windows in a session.
:::

:::{grid-item-card} list_panes
:link: list-panes
:link-type: ref
List panes in a window.
:::

:::{grid-item-card} capture_pane
:link: capture-pane
:link-type: ref
Read visible content of a pane.
:::

:::{grid-item-card} capture_since
:link: capture-since
:link-type: ref
Start a cursor, then read only new pane output.
:::

:::{grid-item-card} get_pane_info
:link: get-pane-info
:link-type: ref
Get detailed pane metadata.
:::

:::{grid-item-card} get_session_info
:link: get-session-info
:link-type: ref
Get detailed session metadata.
:::

:::{grid-item-card} get_window_info
:link: get-window-info
:link-type: ref
Get detailed window metadata.
:::

:::{grid-item-card} find_pane_by_position
:link: find-pane-by-position
:link-type: ref
Resolve "the bottom-right pane" (or any corner) to a `PaneInfo`.
:::

:::{grid-item-card} search_panes
:link: search-panes
:link-type: ref
Search text across panes.
:::

:::{grid-item-card} wait_for_text
:link: wait-for-text
:link-type: ref
Wait for text to appear in a pane.
:::

:::{grid-item-card} get_server_info
:link: get-server-info
:link-type: ref
Get tmux server info.
:::

:::{grid-item-card} call_readonly_tools_batch
:link: call-readonly-tools-batch
:link-type: ref
Call typed readonly tools in order.
:::

:::{grid-item-card} list_servers
:link: list-servers
:link-type: ref
Discover live tmux servers under `$TMUX_TMPDIR`.
:::

:::{grid-item-card} show_option
:link: show-option
:link-type: ref
Query a tmux option value.
:::

:::{grid-item-card} show_environment
:link: show-environment
:link-type: ref
Show tmux environment variables.
:::

:::{grid-item-card} snapshot_pane
:link: snapshot-pane
:link-type: ref
Rich capture: content + cursor + mode + scroll.
:::

:::{grid-item-card} wait_for_content_change
:link: wait-for-content-change
:link-type: ref
Wait for any screen change.
:::

:::{grid-item-card} display_message
:link: display-message
:link-type: ref
Query arbitrary tmux format strings.
:::

:::{grid-item-card} show_buffer
:link: show-buffer
:link-type: ref
Read back an MCP-staged paste buffer.
:::

:::{grid-item-card} show_hooks
:link: show-hooks
:link-type: ref
Enumerate configured tmux hooks at a scope.
:::

:::{grid-item-card} show_hook
:link: show-hook
:link-type: ref
Inspect a single tmux hook by name.
:::

::::

## Act

Create or modify tmux objects.

::::{grid} 1 2 3 3
:gutter: 2 2 3 3

:::{grid-item-card} create_session
:link: create-session
:link-type: ref
Start a new tmux session.
:::

:::{grid-item-card} create_window
:link: create-window
:link-type: ref
Add a window to a session.
:::

:::{grid-item-card} split_window
:link: split-window
:link-type: ref
Split a window into panes.
:::

:::{grid-item-card} send_keys
:link: send-keys
:link-type: ref
Send raw keystrokes to a pane.
:::

:::{grid-item-card} send_keys_batch
:link: send-keys-batch
:link-type: ref
Send several ordered raw-input operations.
:::

:::{grid-item-card} run_command
:link: run-command
:link-type: ref
Run a shell command and report exit status.
:::

:::{grid-item-card} call_mutating_tools_batch
:link: call-mutating-tools-batch
:link-type: ref
Call typed readonly or mutating tools in order.
:::

:::{grid-item-card} rename_session
:link: rename-session
:link-type: ref
Rename a session.
:::

:::{grid-item-card} rename_window
:link: rename-window
:link-type: ref
Rename a window.
:::

:::{grid-item-card} resize_pane
:link: resize-pane
:link-type: ref
Adjust pane dimensions.
:::

:::{grid-item-card} resize_window
:link: resize-window
:link-type: ref
Adjust window dimensions.
:::

:::{grid-item-card} select_layout
:link: select-layout
:link-type: ref
Set window layout.
:::

:::{grid-item-card} set_pane_title
:link: set-pane-title
:link-type: ref
Set pane title.
:::

:::{grid-item-card} clear_pane
:link: clear-pane
:link-type: ref
Clear pane content.
:::

:::{grid-item-card} respawn_pane
:link: respawn-pane
:link-type: ref
Restart a pane's process, keeping its `pane_id`.
:::

:::{grid-item-card} set_option
:link: set-option
:link-type: ref
Set a tmux option.
:::

:::{grid-item-card} set_environment
:link: set-environment
:link-type: ref
Set a tmux environment variable.
:::

:::{grid-item-card} select_pane
:link: select-pane
:link-type: ref
Focus a pane by ID or direction.
:::

:::{grid-item-card} select_window
:link: select-window
:link-type: ref
Focus a window by ID, index, or direction.
:::

:::{grid-item-card} swap_pane
:link: swap-pane
:link-type: ref
Exchange positions of two panes.
:::

:::{grid-item-card} move_window
:link: move-window
:link-type: ref
Move window to another index or session.
:::

:::{grid-item-card} pipe_pane
:link: pipe-pane
:link-type: ref
Stream pane output to a file.
:::

:::{grid-item-card} enter_copy_mode
:link: enter-copy-mode
:link-type: ref
Enter copy mode for scrollback.
:::

:::{grid-item-card} exit_copy_mode
:link: exit-copy-mode
:link-type: ref
Exit copy mode.
:::

:::{grid-item-card} paste_text
:link: paste-text
:link-type: ref
Paste multi-line text via tmux buffer.
:::

:::{grid-item-card} load_buffer
:link: load-buffer
:link-type: ref
Stage multi-line text into an MCP-namespaced tmux buffer.
:::

:::{grid-item-card} paste_buffer
:link: paste-buffer
:link-type: ref
Paste an MCP buffer into a target pane.
:::

:::{grid-item-card} wait_for_channel
:link: wait-for-channel
:link-type: ref
Block until a tmux ``wait-for`` channel is signalled.
:::

:::{grid-item-card} signal_channel
:link: signal-channel
:link-type: ref
Wake clients blocked on a ``wait-for`` channel.
:::

::::

## Destroy

Tear down tmux objects. Not reversible.

::::{grid} 1 2 3 3
:gutter: 2 2 3 3

:::{grid-item-card} kill_session
:link: kill-session
:link-type: ref
Destroy a session and all its windows.
:::

:::{grid-item-card} kill_window
:link: kill-window
:link-type: ref
Destroy a window and all its panes.
:::

:::{grid-item-card} kill_pane
:link: kill-pane
:link-type: ref
Destroy a pane.
:::

:::{grid-item-card} kill_server
:link: kill-server
:link-type: ref
Kill the entire tmux server.
:::

:::{grid-item-card} call_destructive_tools_batch
:link: call-destructive-tools-batch
:link-type: ref
Call typed tools including destructive steps.
:::

:::{grid-item-card} delete_buffer
:link: delete-buffer
:link-type: ref
Delete an MCP-staged tmux paste buffer.
:::

::::

```{toctree}
:hidden:
:caption: Tools by tmux scope

server/index
batch/index
session/index
window/index
pane/index
buffer/index
hook/index
```