# create_window

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

> Create a new window in a tmux session.

MCP is in development

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

Create a new window in a tmux session.

Creates a window with one pane. Use [split_window](https://libtmux.org/en/py/latest/mcp/tools/split_window/) to add more panes afterward.

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

## Arguments

* `attach` optional · boolean

  Whether to make the new window active.

  Default: `false`.

* `direction` optional

  Window placement direction.

  Default: `null`.

* `environment` optional

  Per-process environment as a mapping or JSON object string. Values do not modify the tmux session environment. Each item becomes a tmux \`\`-e\`\` launch option. Values may be visible to host process inspection in the tmux client argv during launch and in the child environment afterward; MCP audit redaction does not hide either surface. Pass credential references, not literal credentials.

  Default: `null`.

* `session_id` optional

  Session ID (e.g. '$1') to look up.

  Default: `null`.

* `session_name` optional

  Session name to look up.

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

  Default: `null`.

## Schemas

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

Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "attach": {
      "default": false,
      "description": "Whether to make the new window active.",
      "type": "boolean"
    },
    "direction": {
      "anyOf": [
        {
          "enum": [
            "before",
            "after"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Window placement direction."
    },
    "environment": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Per-process environment as a mapping or JSON object string. Values do\nnot modify the tmux session environment. Each item becomes a tmux\n``-e`` launch option. Values may be visible to host process inspection\nin the tmux client argv during launch and in the child environment\nafterward; MCP audit redaction does not hide either surface. Pass\ncredential references, not literal credentials."
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session ID (e.g. '$1') to look up."
    },
    "session_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session name to look up."
    },
    "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 new window."
    }
  },
  "type": "object"
}
```

Output schema

```json
{
  "description": "Serialized tmux window.",
  "properties": {
    "active_pane_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Pane id (``%N``) of the window's active pane."
    },
    "pane_count": {
      "description": "Number of panes",
      "type": "integer"
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Parent session ID"
    },
    "session_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Parent session name"
    },
    "window_active": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Active flag ('1' or '0')"
    },
    "window_height": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Height in rows"
    },
    "window_id": {
      "description": "Window ID (e.g. '@1')",
      "type": "string"
    },
    "window_index": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Window index"
    },
    "window_layout": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Layout string"
    },
    "window_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Window name"
    },
    "window_width": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Width in columns"
    }
  },
  "required": [
    "window_id",
    "pane_count"
  ],
  "type": "object"
}
```

Tool annotations

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