run_command

Python

Python
Ruby Unavailable
Lua Unavailable
TypeScript
Rust
Go
Java
.NET
C++
Swift

Run a shell command in a pane, wait for completion, and capture output.

Use for the common terminal workflow: run this command, wait until it completes, then report whether it succeeded. The command is sent to the pane’s interactive shell, followed by a private tmux wait-for signal and a private pane option carrying the shell exit status. This is the AUTHORED-output path — the command you pass is what the wait synchronizes on. Reserve wait_for_text for output you did not author: another process, a human, or a background job.

The command runs in a subshell, so cd, export and other shell state changes do not persist to later calls.

All Python tools · JSON · Source

Arguments

command required · string: Shell command to run in the target pane.
max_lines optional: Maximum pane output lines to return. Defaults to all captured visible output; pass a small value for a tail-only summary.
Default: null.
pane_id optional: Pane ID (e.g. '%1').
Default: null.
session_id optional: Session ID (e.g. '$1') for pane resolution.
Default: null.
session_name optional: Session name for pane resolution.
Default: null.
socket_name optional: tmux socket name.
Default: null.
suppress_history optional · boolean: For MCP calls, omission uses the server's LIBTMUX_SUPPRESS_HISTORY default; an explicit value overrides it. Direct Python calls default to False. Best effort: the shell must honor space-prefixed history suppression. Suppression requires a single-line command; multiline commands remain available when suppression is false.
Default: true.
timeout optional · number: Maximum seconds to wait for command completion. Capped by the same server wait ceiling as ``wait_for_text``; an over-large value is not an error — the wait returns at the ceiling and the timeout actually enforced is reported on ``RunCommandResult.effective_timeout``.
Default: 30.
window_id optional: Window ID for pane resolution.
Default: null.

Schemas

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

Input schema

{
  "additionalProperties": false,
  "properties": {
    "command": {
      "description": "Shell command to run in the target pane.",
      "type": "string"
    },
    "max_lines": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Maximum pane output lines to return. Defaults to all captured\nvisible output; pass a small value for a tail-only summary."
    },
    "pane_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Pane ID (e.g. '%1')."
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session ID (e.g. '$1') for pane resolution."
    },
    "session_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session name for pane resolution."
    },
    "socket_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "tmux socket name."
    },
    "suppress_history": {
      "default": true,
      "description": "For MCP calls, omission uses the server's LIBTMUX_SUPPRESS_HISTORY\ndefault; an explicit value overrides it. Direct Python calls default\nto False. Best effort: the shell must honor space-prefixed history\nsuppression. Suppression requires a single-line command; multiline\ncommands remain available when suppression is false.",
      "type": "boolean"
    },
    "timeout": {
      "default": 30,
      "description": "Maximum seconds to wait for command completion. Capped by the\nsame server wait ceiling as ``wait_for_text``; an over-large\nvalue is not an error — the wait returns at the ceiling and\nthe timeout actually enforced is reported on\n``RunCommandResult.effective_timeout``.",
      "type": "number"
    },
    "window_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Window ID for pane resolution."
    }
  },
  "required": [
    "command"
  ],
  "type": "object"
}

Output schema

{
  "description": "Result of running a shell command in a pane.",
  "properties": {
    "effective_timeout": {
      "description": "Seconds actually enforced for command completion. Server policy caps the requested ``timeout``; compare against what you passed to see a clamp.",
      "type": "number"
    },
    "elapsed_seconds": {
      "description": "Time spent waiting in seconds",
      "type": "number"
    },
    "exit_status": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Shell exit status, or None when the command timed out"
    },
    "output": {
      "description": "Tail-preserved pane output after the wait completes",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "output_truncated": {
      "default": false,
      "description": "True when output was tail-preserved to stay within max_lines",
      "type": "boolean"
    },
    "output_truncated_lines": {
      "default": 0,
      "description": "Number of pane lines dropped from the head when truncating",
      "type": "integer"
    },
    "pane_id": {
      "description": "Pane ID that received the command",
      "type": "string"
    },
    "timed_out": {
      "description": "True when the wait timed out",
      "type": "boolean"
    }
  },
  "required": [
    "pane_id",
    "timed_out",
    "elapsed_seconds",
    "effective_timeout"
  ],
  "type": "object"
}

Tool annotations

{
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": true,
  "readOnlyHint": false
}