# start_program

Source: https://libtmux.org/en/ts/latest/mcp/tools/start_program/

> 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.

tool MCPlatest

MCP concept example

A working example of the core library. It can change without notice.

[What concept means](https://libtmux.org/en/meta/support/#concept-and-alpha)

* **start_program**( [argv](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2Fargv): [Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")>, [fromPaneId](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2FfromPaneId)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [height](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2Fheight)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [lifetimeMs](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2FlifetimeMs)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), [placement](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2Fplacement)?: "window" | "split", [startDirectory](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2FstartDirectory)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [width](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2Fwidth)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"), )

  tool \[[source](https://github.com/libtmux/libtmux-ts/blob/f7b03a361f7c97677406b4ab937b2772ddb5f7dd/packages/mcp/src/tools/programs.ts#L230)][¶](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program)

  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](https://libtmux.org/en/ts/latest/mcp/tools/run_program/) is the one-call form. [read_program](https://libtmux.org/en/ts/latest/mcp/tools/read_program/) reads its output as it is written and reports its exit; [send_keys](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/) reaches its paneId; [stop_program](https://libtmux.org/en/ts/latest/mcp/tools/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](https://libtmux.org/en/ts/latest/mcp/tools/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[#](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.parameters)

  * **[`argv`](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2Fargv)** ([Array](https://json-schema.org/understanding-json-schema/reference/array "array (JSON Schema)")<[string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")>)

    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`](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2FfromPaneId)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

    Run beside this pane, in its directory and session, as [run_program](https://libtmux.org/en/ts/latest/mcp/tools/run_program/) does.

    * pattern

      `"^%\\d+$"`

  * **[`height`](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2Fheight)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

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

    * maximum

      `10000`

    * exclusiveMinimum

      `0`

  * **[`lifetimeMs`](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2FlifetimeMs)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

    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`](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2Fplacement)**? ("window" | "split")

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

  * **[`startDirectory`](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2FstartDirectory)**? ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

    Directory the program starts in, taken literally; one that cannot be entered means the program never runs, and [read_program](https://libtmux.org/en/ts/latest/mcp/tools/read_program/) reports not_started.

  * **[`width`](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.input%2Fproperties%2Fwidth)**? ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

    Columns of the program’s terminal.

    * maximum

      `10000`

    * exclusiveMinimum

      `0`

  ## Result[#](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.result)

  Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")

  * **[`effectiveLifetimeMs`](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.output%2Fproperties%2FeffectiveLifetimeMs)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)"))

    The lifetime enforced.

    * minimum

      `-9007199254740991`

    * maximum

      `9007199254740991`

  * **[`paneId`](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.output%2Fproperties%2FpaneId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

    The program’s pane, for [send_keys](https://libtmux.org/en/ts/latest/mcp/tools/send_keys/) or [capture_pane](https://libtmux.org/en/ts/latest/mcp/tools/capture_pane/).

    * pattern

      `"^%\\d+$"`

  * **[`programId`](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.output%2Fproperties%2FprogramId)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"))

    Pass to [read_program](https://libtmux.org/en/ts/latest/mcp/tools/read_program/) and [stop_program](https://libtmux.org/en/ts/latest/mcp/tools/stop_program/).

  No other properties are accepted.

  ## Annotations[#](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.annotations)

  * [`destructiveHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#destructiveHint)

    `true`

  * [`idempotentHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#idempotentHint)

    `false`

  * [`openWorldHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#openWorldHint)

    `true`

  * [`readOnlyHint`](https://libtmux.org/en/ts/latest/mcp/reference/glossary/#readOnlyHint)

    `false`

  ## Protocol data[#](https://libtmux.org/en/ts/latest/mcp/tools/start_program/#mcp.tool.start_program.schemas)

  Use the complete advertised contract for validation and client integration.

  Input schema

  ```json
  {
    "$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

  ```json
  {
    "$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"
  }
  ```