# create_session Source: https://libtmux.org/en/py/stable/mcp/tools/create_session/ > Create a new tmux session. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **create_session**( [environment](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fenvironment)?: [Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [session_name](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fsession_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [start_directory](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fstart_directory)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [suppress_persistent_history](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fsuppress_persistent_history)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [window_name](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fwindow_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [x](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fx)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [y](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fy)?: [integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/server_tools.py#L372)][¶](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session) Create a new tmux session. Check [list_sessions](https://libtmux.org/en/py/stable/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. * MCP request method `tools/call` Send `create_session` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.parameters) * **[`environment`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fenvironment)**? = `null` ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) 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 `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`](https://libtmux.org/en/tmux/latest/manual/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. * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Name for the new session. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. Defaults to LIBTMUX_SOCKET env var. * **[`start_directory`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fstart_directory)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Existing directory to start in. `~` expands; a relative path resolves against the MCP server process’s directory. * **[`suppress_persistent_history`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fsuppress_persistent_history)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) 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. * **[`window_name`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fwindow_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Name for the initial window. * **[`x`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fx)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width of the initial window. * **[`y`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.input%2Fproperties%2Fy)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height of the initial window. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`active_pane_id`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Factive_pane_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) 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`](https://libtmux.org/en/py/stable/mcp/tools/list_sessions/) rows for sessions in transient teardown states where `active_pane` is unavailable. * **[`session_attached`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession_attached)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Attached client count * **[`session_created`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession_created)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Creation timestamp * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Session ID (e.g. ‘$1’) * **[`session_name`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fsession_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Session name * **[`window_count`](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.output%2Fproperties%2Fwindow_count)** ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)")) Number of windows ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/create_session/#mcp.tool.create_session.schemas) Use the complete advertised contract for validation and client integration. 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" } ```