Create session¶

`create_session`¶

create_session

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.

Do not pass credentials directly in environment. Values persist in the new session, can be inspected with show_environment, and reach its initial pane and future panes. Pass credential references instead; see Safety tiers for details.

suppress_persistent_history defaults to false for MCP and direct Python calls. It does not inherit LIBTMUX_SUPPRESS_HISTORY. Leave it false to add no history controls for this call. That choice cannot remove inherited, session, or startup-file controls.

Set it to true and create_session copies and merges best-effort no-disk history controls into the tmux session environment. They reach the initial pane and future panes in that session. The shell can retain in-memory history, and a startup file can override these controls after the process starts.

When you enable it, tmux environment arguments are added, but the spawned process command text is not prefixed or rewritten. If you also pass environment, any history-control values must agree with the policy. A conflict fails the call, names the variable without including the conflicting value, and is never retried without suppression. See History suppression for shell behavior and Safety tiers for output, scrollback, process, transcript, hook, and logging boundaries.

Example:

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

Response (SessionInfo):

{
  "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 (the libtmux layer 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 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.
`socket_name`	str	no	—	tmux socket name. Defaults to LIBTMUX_SOCKET env var.
`suppress_persistent_history`	bool	no	`False`	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.

Create session¶

create_session¶

`create_session`¶