# create_session

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

> Start a pane's configured process; accepts no command payload. Create a detached session and return it with its first window and pane, so you can start working without listing anything first.

MCP is in development

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

Start a pane’s configured process; accepts no command payload. Create a detached session and return it with its first window and pane, so you can start working without listing anything first.

[All TypeScript tools](https://libtmux.org/en/ts/latest/mcp/tools/) · [JSON](https://libtmux.org/en/ts/latest/mcp/tools/create_session.json) · [Source](https://github.com/libtmux/libtmux-ts/blob/b3f338c1a21e614ebf0dd6d55aa36a60db816618/packages/mcp/src/tools/lifecycle.ts#L68)

## Arguments

* `height` optional · integer

  Rows. Default 24, because a detached session has no client to size it.

* `name` optional · string

  Session name; tmux picks a number when omitted.

* `startDirectory` optional · string

  Working directory for the first pane. Defaults to the server's.

* `width` optional · integer

  Columns. Default 80, and a program that formats to its terminal width — ps, git log --graph, docker ps — truncates to that at the source, where no capture option can recover it.

* `windowName` optional · string

  Name for the first window, so the session does not open with a stray shell.

## Schemas

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

Input schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "height": {
      "description": "Rows. Default 24, because a detached session has no client to size it.",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    },
    "name": {
      "description": "Session name; tmux picks a number when omitted.",
      "type": "string",
      "x-libtmux-tmux-format": "literalized-once"
    },
    "startDirectory": {
      "description": "Working directory for the first pane. Defaults to the server's.",
      "type": "string",
      "x-libtmux-tmux-format": "literalized-once"
    },
    "width": {
      "description": "Columns. Default 80, and a program that formats to its terminal width — ps, git log --graph, docker ps — truncates to that at the source, where no capture option can recover it.",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "type": "integer"
    },
    "windowName": {
      "description": "Name for the first window, so the session does not open with a stray shell.",
      "type": "string",
      "x-libtmux-tmux-format": "literalized-once"
    }
  },
  "type": "object"
}
```

Output schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "properties": {
    "paneId": {
      "description": "The new session's first pane. Target this.",
      "pattern": "^%\\d+$",
      "type": "string"
    },
    "session": {
      "additionalProperties": false,
      "properties": {
        "attachedClients": {
          "description": "Raw client count from tmux; 0 means detached. Includes control-mode clients - this server's own wait_for_text or other live read holds one open while it runs, and another program on this socket may hold others. See humanAttachedClients for a person-only count.",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "type": "integer"
        },
        "humanAttachedClients": {
          "description": "attachedClients minus every control-mode client, this server's own included.",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "type": "integer"
        },
        "id": {
          "description": "Stable session id, e.g. $1.",
          "pattern": "^\\$\\d+$",
          "type": "string"
        },
        "metadataComplete": {
          "description": "Whether the session name is complete.",
          "type": "boolean"
        },
        "name": {
          "type": "string"
        },
        "omittedMetadataBytes": {
          "description": "UTF-8 bytes omitted from the session name.",
          "maximum": 9007199254740991,
          "minimum": 0,
          "type": "integer"
        },
        "windows": {
          "description": "How many windows it holds.",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "type": "integer"
        }
      },
      "required": [
        "attachedClients",
        "humanAttachedClients",
        "id",
        "metadataComplete",
        "name",
        "omittedMetadataBytes",
        "windows"
      ],
      "type": "object"
    },
    "windowId": {
      "description": "Stable window id, e.g. @1.",
      "pattern": "^@\\d+$",
      "type": "string"
    }
  },
  "required": [
    "paneId",
    "session",
    "windowId"
  ],
  "type": "object"
}
```

Tool annotations

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