# create_session

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

> Create a new tmux session.

MCP is in development

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

Create a new tmux session.

Check [list_sessions](https://libtmux.org/en/py/latest/mcp/tools/list_sessions/) first to avoid name conflicts. A new session starts with one window and one pane. Values in `environment` are stored in the tmux session environment, so future panes inherit them too.

[All Python tools](https://libtmux.org/en/py/latest/mcp/tools/) · [JSON](https://libtmux.org/en/py/latest/mcp/tools/create_session.json) · [Source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/server_tools.py#L372)

## Arguments

* `environment` optional

  Environment variables to store in the session environment. Accepts either a dict of env vars or a JSON-serialized string of the same — the latter is the cursor-composer-1 workaround described in :func:\`libtmux_mcp.\_utils.\_coerce_dict_arg\`. Each item appears in the tmux client argv as one \`\`-eKEY=VALUE\`\` element and may be visible to host process inspection during launch. tmux retains the values in tmux session state, where \`\`show-environment\`\` can reveal them. They reach the initial and future child environments unless a later spawn overrides them. MCP audit redaction does not hide these surfaces. Pass credential references, not literal credentials.

  Default: `null`.

* `session_name` optional

  Name for the new session.

  Default: `null`.

* `socket_name` optional

  tmux socket name. Defaults to LIBTMUX_SOCKET env var.

  Default: `null`.

* `start_directory` optional

  Existing directory to start in. \`\`\~\`\` expands; a relative path resolves against the MCP server process's directory.

  Default: `null`.

* `suppress_persistent_history` optional · boolean

  Whether to suppress persistent history for the spawned shell. Defaults to False for MCP and direct Python calls. This per-call option does not inherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these controls.

  Default: `false`.

* `window_name` optional

  Name for the initial window.

  Default: `null`.

* `x` optional

  Width of the initial window.

  Default: `null`.

* `y` optional

  Height of the initial window.

  Default: `null`.

## Schemas

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

Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "environment": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Environment variables to store in the session environment. Accepts\neither a dict of env vars or a JSON-serialized string of the same —\nthe latter is the cursor-composer-1 workaround described in\n:func:`libtmux_mcp._utils._coerce_dict_arg`. Each item appears in the\ntmux client argv as one ``-eKEY=VALUE`` element and may be visible to\nhost process inspection during launch. tmux retains the values in\ntmux session state, where ``show-environment`` can reveal them. They reach\nthe initial and future child environments unless a later spawn\noverrides them. MCP audit redaction does not hide these surfaces. Pass\ncredential references, not literal credentials."
    },
    "session_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Name for the new session."
    },
    "socket_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "tmux socket name. Defaults to LIBTMUX_SOCKET env var."
    },
    "start_directory": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Existing directory to start in. ``~`` expands; a relative path\nresolves against the MCP server process's directory."
    },
    "suppress_persistent_history": {
      "default": false,
      "description": "Whether to suppress persistent history for the spawned shell. Defaults\nto False for MCP and direct Python calls. This per-call option does not\ninherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these\ncontrols.",
      "type": "boolean"
    },
    "window_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Name for the initial window."
    },
    "x": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Width of the initial window."
    },
    "y": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Height of the initial window."
    }
  },
  "type": "object"
}
```

Output schema

```json
{
  "description": "Serialized tmux session.",
  "properties": {
    "active_pane_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Pane id (``%N``) of the session's active pane. Guaranteed non-None on ``create_session`` return (libtmux creates the session with one initial pane). May be None from ``list_sessions`` rows for sessions in transient teardown states where ``active_pane`` is unavailable."
    },
    "session_attached": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Attached client count"
    },
    "session_created": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Creation timestamp"
    },
    "session_id": {
      "description": "Session ID (e.g. '$1')",
      "type": "string"
    },
    "session_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session name"
    },
    "window_count": {
      "description": "Number of windows",
      "type": "integer"
    }
  },
  "required": [
    "session_id",
    "window_count"
  ],
  "type": "object"
}
```

Tool annotations

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