Tools¶

Which tool do I want?¶

Reading terminal content?

• Re-reading the same pane while it changes? → capture_since inspect

• Need a one-shot read of a known pane? → capture_pane inspect

• Need text + cursor + mode in one call? → snapshot_pane inspect

• Don’t know which pane? → search_panes inspect

• Need to wait for specific output? → wait_for_text inspect

• Need to wait for any new output? → wait_for_text inspect with patterns=null

• Only need metadata (PID, path, size)? → get_pane_info inspect

• Need an arbitrary tmux variable? → display_message inspect

Targeting a pane by layout?

• “The bottom-right pane”, “top-left”, any corner → find_pane_by_position inspect

• Already know the pane_id → use it directly

Running a command?

• run_command execute — one call to run a shell command, wait for completion, capture output, and return exit status

• send_keys execute / send_keys_batch execute — raw interactive input for TUIs, control keys, and persistent shell state

• wait_for_channel manage — 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 wait_for_text inspect or capture_since inspect

• Pasting multi-line text? → paste_text execute

Creating workspace structure?

• New session → create_session execute

• New window → create_window execute

• New pane → split_window execute

Navigating?

• Switch pane → select_pane manage (by ID or direction)

• Switch window → select_window manage (by ID, index, or direction)

Rearranging layout?

• Swap two panes → swap_pane manage

• Move window → move_window manage

• Change layout → select_layout manage

Scrollback / copy mode?

• Enter copy mode → enter_copy_mode manage

• Exit copy mode → exit_copy_mode manage

• Log output to file → pipe_pane execute

Coordinating across panes?

• Block until signalled → wait_for_channel manage

• Signal a waiter → signal_channel manage

Batching typed tool calls?

• Several inspect calls → call_read_tools_batch inspect

• Anything that writes → call the tool directly; a batch would hide its name from a client rule keyed on it

Staging multi-line input?

• Stage content → load_buffer manage

• Push into pane → paste_buffer execute

• Read back → show_buffer inspect

• Free server state → delete_buffer teardown

Auditing tmux hooks?

• Enumerate → show_hooks inspect

• Inspect one → show_hook inspect

Changing settings?

• tmux options → show_option inspect / set_option execute

• Environment vars → show_environment inspect / set_environment execute

Reaching for a workflow recipe? The server also ships four short MCP prompts the client renders for the model — see 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 inspect¶

Request tmux state or terminal output, or render server-local prompt text. The built-in operation does not pass caller input as a tmux or shell command. Configured tmux aliases and hooks may still execute; see Trust model.

Manage manage¶

Change tmux-managed structure, presentation, staging, or coordination state. The built-in operation does not supply a shell command, pane input, or a value tmux treats as executable configuration. Configured aliases and hooks may still execute; see Trust model.

Execute execute¶

Start a pane process, deliver input to one, or store state that can control later execution.

Teardown teardown¶

Delete tmux objects or retained scrollback. Not reversible.