# run_shell_command

Source: https://libtmux.org/en/rs/latest/mcp/tools/run_shell_command/

> Run a shell command in a pane, wait for it to finish, and report its exit status with everything it wrote. This is the tool for "run this and tell me if it worked". Output is the pane's raw output stream, not the rendered screen: nothing is missed, the shell prompt is not included, and a line redrawn in place repeats; capture_pane shows the screen. The command runs in a subshell, so cd and export do not persist and invalid syntax completes with a nonzero status. Valid inherited Bash and zsh ERR and DEBUG traps remain visible to the command while parent-shell traps and options remain unchanged. It requires one configured input recipient and observes its mode, liveness, input-off state, attended-client state, cohort, inherited-caller relation, known POSIX shell, and resolved route before watcher setup and again before dispatch. A process-wide endpoint-and-pane reservation blocks other MCP pane input until the completion marker or pane closure is proved. The resolved tmux executable and socket path must contain no ASCII terminal-control bytes. The reservation serializes this MCP's input, but tmux observations can still race with dispatch. The pane shell, tmux server, and configuration must be trusted. Reaching the deadline, cancelling, or an uncertain dispatch stops this request while its watcher keeps the reservation until completion is proved. To stop the command, send_keys with keys ["C-c"] alone passes the reservation, and the command reports completion when it ends; respawn_pane with kill_first replaces a program that ignores C-c and C-\. Run a shell command in a pane with your user's permissions.

MCP is in development

Server behavior and tool contracts may change. Tool availability depends on the server configuration.

Run a shell command in a pane, wait for it to finish, and report its exit status with everything it wrote. This is the tool for “run this and tell me if it worked”. Output is the pane’s raw output stream, not the rendered screen: nothing is missed, the shell prompt is not included, and a line redrawn in place repeats; [capture\_pane](https://libtmux.org/en/rs/latest/mcp/tools/capture_pane/) shows the screen. The command runs in a subshell, so cd and export do not persist and invalid syntax completes with a nonzero status. Valid inherited Bash and zsh ERR and DEBUG traps remain visible to the command while parent-shell traps and options remain unchanged. It requires one configured input recipient and observes its mode, liveness, input-off state, attended-client state, cohort, inherited-caller relation, known POSIX shell, and resolved route before watcher setup and again before dispatch. A process-wide endpoint-and-pane reservation blocks other MCP pane input until the completion marker or pane closure is proved. The resolved tmux executable and socket path must contain no ASCII terminal-control bytes. The reservation serializes this MCP’s input, but tmux observations can still race with dispatch. The pane shell, tmux server, and configuration must be trusted. Reaching the deadline, cancelling, or an uncertain dispatch stops this request while its watcher keeps the reservation until completion is proved. To stop the command, [send\_keys](https://libtmux.org/en/rs/latest/mcp/tools/send_keys/) with keys \[“C-c”] alone passes the reservation, and the command reports completion when it ends; [respawn\_pane](https://libtmux.org/en/rs/latest/mcp/tools/respawn_pane/) with kill\_first replaces a program that ignores C-c and C-. Run a shell command in a pane with your user’s permissions.

[All Rust tools](../) · [JSON](../run_shell_command.json) · [Source](https://github.com/libtmux/libtmux-rs/blob/f0e37052c232636b61d095817046e6bfc8f2ca40/crates/tmux-mcp/src/tools/observe.rs#L208)

## Arguments

* `command` required · string

  The command for the pane's trusted POSIX-compatible shell. Shell reserved words and special builtins must retain their standard meanings. The command runs inside a subshell, so several lines are fine and a bare \`exit\` does not end the pane's own shell. Invalid syntax is contained and completes with the shell's nonzero status. Valid inherited Bash and zsh \`ERR\` and \`DEBUG\` traps remain visible to the command while the pane's parent-shell traps and options remain unchanged.

* `pane` required · string

  The \`%\`-prefixed pane to run in.

* `seconds` optional · integer | null

  How long to allow, in seconds. Defaults to 30, capped at 600.

* `suppress_history` optional · boolean

  Whether to keep the command out of the shell's history.

  Default: `false`.

## Schemas

The schema defines required fields, nested values, defaults, and validation constraints.