tool MCPlatest

`start_program`

start_program( argv: Array<string>, fromPaneId?: string, height?: integer, lifetimeMs?: integer, placement?: "window" | "split", startDirectory?: string, width?: integer, )

tool [source]¶

Run a program in a new pane of its own with your user’s permissions. Start a program in a pane of its own and return at once with a programId. Use it for a program that runs longer than one wait, such as a build or a server, or one that needs keys between reads; run_program is the one-call form. read_program reads its output as it is written and reports its exit; send_keys reaches its paneId; stop_program ends it. This server ends it and removes its pane when lifetimeMs runs out, even if no later call arrives, and tmux does if this server dies. No shell parses argv, and PAGER and GIT_PAGER are cat. It takes no input, keep, inheritShell or separateStderr: for those, use run_program. Requires tmux 3.8 or newer.

MCP request method: tools/call Send start_program as the tool name, with the arguments below.

Arguments#

argv (Array<string>) #

The program and its arguments, as given: [“git”, “status”, “—short”]. Put variables first with env: [“env”, “CI=1”, “make”, “test”].

minItems
1
maxItems
256
fromPaneId? (string) #

Run beside this pane, in its directory and session, as run_program does.

pattern
"^%\\d+$"
height? (integer) #

Rows of the program’s terminal. Defaults to tmux’s default-size.

maximum
10000
exclusiveMinimum
0
lifetimeMs? (integer) #

How long the program may run: it is ended and its pane removed this long after the start. 10 minutes by default; longer than 60 is cut to that.

maximum
9007199254740991
exclusiveMinimum
0
placement? ("window" | "split") #

With fromPaneId: “window”, the default, or “split” beside the pane, where a person watching it sees the program. Focus stays put.
startDirectory? (string) #

Directory the program starts in, taken literally; one that cannot be entered means the program never runs, and read_program reports not_started.
width? (integer) #

Columns of the program’s terminal.

maximum
10000
exclusiveMinimum
0

Result#

Returns object

effectiveLifetimeMs (integer) #

The lifetime enforced.

minimum
-9007199254740991
maximum
9007199254740991
paneId (string) #

The program’s pane, for send_keys or capture_pane.

pattern
"^%\\d+$"
programId (string) #

Pass to read_program and stop_program.

No other properties are accepted.

Annotations#

destructiveHint: true
idempotentHint: false
openWorldHint: true
readOnlyHint: false

Protocol data#

Use the complete advertised contract for validation and client integration.

Input schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "argv": {
      "description": "The program and its arguments, as given: [\"git\", \"status\", \"--short\"]. Put variables first with env: [\"env\", \"CI=1\", \"make\", \"test\"].",
      "items": {
        "type": "string"
      },
      "maxItems": 256,
      "minItems": 1,
      "type": "array"
    },
    "fromPaneId": {
      "description": "Run beside this pane, in its directory and session, as run_program does.",
      "pattern": "^%\\d+$",
      "type": "string"
    },
    "height": {
      "description": "Rows of the program's terminal. Defaults to tmux's default-size.",
      "exclusiveMinimum": 0,
      "maximum": 10000,
      "type": "integer"
    },
    "lifetimeMs": {
      "description": "How long the program may run: it is ended and its pane removed this long after the start. 10 minutes by default; longer than 60 is cut to that.",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    },
    "placement": {
      "description": "With fromPaneId: \"window\", the default, or \"split\" beside the pane, where a person watching it sees the program. Focus stays put.",
      "enum": [
        "window",
        "split"
      ],
      "type": "string"
    },
    "startDirectory": {
      "description": "Directory the program starts in, taken literally; one that cannot be entered means the program never runs, and read_program reports not_started.",
      "type": "string"
    },
    "width": {
      "description": "Columns of the program's terminal.",
      "exclusiveMinimum": 0,
      "maximum": 10000,
      "type": "integer"
    }
  },
  "required": [
    "argv"
  ],
  "type": "object"
}

Output schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "properties": {
    "effectiveLifetimeMs": {
      "description": "The lifetime enforced.",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "type": "integer"
    },
    "paneId": {
      "description": "The program's pane, for send_keys or capture_pane.",
      "pattern": "^%\\d+$",
      "type": "string"
    },
    "programId": {
      "description": "Pass to read_program and stop_program.",
      "type": "string"
    }
  },
  "required": [
    "effectiveLifetimeMs",
    "paneId",
    "programId"
  ],
  "type": "object"
}

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

`start_program`

Arguments#

Result#

Annotations#

Protocol data#