Create session

create_session

create_session

mutating tool

Create a new tmux session.

Returns:

SessionInfo

Use when you need a new isolated workspace. Sessions are the top-level container — create one before creating windows or panes.

Avoid when a session with the target name already exists — check with list_sessions first, or the command will fail.

Side effects: Creates a new tmux session with one window and one pane.

Example:

{
  "tool": "create_session",
  "arguments": {
    "session_name": "dev"
  }
}

Response:

{
  "session_id": "$1",
  "session_name": "dev",
  "window_count": 1,
  "session_attached": "0",
  "session_created": "1774521872",
  "active_pane_id": "%0"
}

Tip

The returned active_pane_id is the pane ID (%N) of the session’s initial pane. It’s guaranteed non-None immediately after create_session (libtmux always creates the session with one initial pane), so you can target subsequent send_keys / split_window / capture_pane calls directly without a follow-up list_panes round-trip — saving an MCP call in the most common “new session, then act on it” workflow.

Parameters

Parameter	Type	Required	Default	Description
session_name	str	no	—	Name for the new session.
window_name	str	no	—	Name for the initial window.
start_directory	str	no	—	Working directory for the session.
x	int	no	—	Width of the initial window.
y	int	no	—	Height of the initial window.
environment	dict[str, str] | str	no	—	Environment variables to set. 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.
socket_name	str	no	—	tmux socket name. Defaults to LIBTMUX_SOCKET env var.