create_session

Create a new tmux session.

Check 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 · JSON · Source

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

{
  "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

{
  "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

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

Scripting & web

Compiled & native

JVM

.NET

tmux

create_session

Arguments

Schemas