Tools¶

Which tool do I want?¶

Reading terminal content?

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

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

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

• Don’t know which pane? → search_panes readonly

• Need to wait for specific output? → wait_for_text readonly

• Need to wait for any change? → wait_for_content_change readonly

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

• Need an arbitrary tmux variable? → display_message readonly

Targeting a pane by layout?

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

• Already know the pane_id → use it directly

Running a command?

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

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

• wait_for_channel mutating — 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 readonly, wait_for_content_change readonly, or capture_since readonly

• Pasting multi-line text? → paste_text mutating

Creating workspace structure?

• New session → create_session mutating

• New window → create_window mutating

• New pane → split_window mutating

Navigating?

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

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

Rearranging layout?

• Swap two panes → swap_pane mutating

• Move window → move_window mutating

• Change layout → select_layout mutating

Scrollback / copy mode?

• Enter copy mode → enter_copy_mode mutating

• Exit copy mode → exit_copy_mode mutating

• Log output to file → pipe_pane mutating

Coordinating across panes?

• Block until signalled → wait_for_channel mutating

• Signal a waiter → signal_channel mutating

Batching typed tool calls?

• Read-only observations → call_readonly_tools_batch readonly

• Ordered readonly + mutating workflows → call_mutating_tools_batch mutating

• Reviewed workflows that include destructive steps → call_destructive_tools_batch destructive

Staging multi-line input?

• Stage content → load_buffer mutating

• Push into pane → paste_buffer mutating

• Read back → show_buffer readonly

• Free server state → delete_buffer mutating

Auditing tmux hooks?

• Enumerate → show_hooks readonly

• Inspect one → show_hook readonly

Changing settings?

• tmux options → show_option readonly / set_option mutating

• Environment vars → show_environment readonly / set_environment mutating

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 readonly¶

Read tmux state without changing anything.

Act mutating¶

Create or modify tmux objects.

Destroy destructive¶

Tear down tmux objects. Not reversible.