Sessions

Inspect readonly

list_sessions readonly

List all tmux sessions.

Returns: list[SessionInfo]

Use when you need session names, IDs, or attached status before deciding which session to target.

Avoid when you need window or pane details — use list_windows readonly or list_panes readonly instead.

Side effects: None. Readonly.

Example:

{
  "tool": "list_sessions",
  "arguments": {}
}

Response:

[
  {
    "session_id": "$0",
    "session_name": "myproject",
    "window_count": 2,
    "session_attached": "0",
    "session_created": "1774521871"
  }
]

Parameters

Parameter	Type	Required	Default	Description
socket_name	str	no	—	tmux socket name. Defaults to LIBTMUX_SOCKET env var.
filters	dict[str, str], str	no	—	Django-style filters as a dict (e.g. {"session_name__contains": "dev"}) or as a JSON string. Some MCP clients require the string form.

---

get_server_info readonly

Get information about the tmux server.

Returns: ServerInfo

Use when you need to verify the tmux server is running, check its PID, or inspect server-level state before creating sessions.

Avoid when you only need session names — use list_sessions readonly.

Side effects: None. Readonly.

Parameters

Parameter	Type	Required	Default	Description
socket_name	str	no	—	tmux socket name. Defaults to LIBTMUX_SOCKET env var.

Act mutating

create_session mutating

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 readonly first, or the command will fail.

Side effects: Creates a new tmux session. Attaches if attach is true.

Example:

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

Response:

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

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]	no	—	Environment variables to set.
socket_name	str	no	—	tmux socket name. Defaults to LIBTMUX_SOCKET env var.

---

rename_session mutating

Rename a tmux session.

Returns: SessionInfo

Use when a session name no longer reflects its purpose.

Side effects: Renames the session. Existing references by old name will break.

Example:

{
  "tool": "rename_session",
  "arguments": {
    "session_name": "old-name",
    "new_name": "new-name"
  }
}

Response:

{
  "session_id": "$0",
  "session_name": "new-name",
  "window_count": 2,
  "session_attached": "0",
  "session_created": "1774521871"
}

Parameters

Parameter	Type	Required	Default	Description
new_name	str	yes	—	New name for the session.
session_name	str	no	—	Current session name to look up.
session_id	str	no	—	Session ID (e.g. ‘$1’) to look up.
socket_name	str	no	—	tmux socket name. Defaults to LIBTMUX_SOCKET env var.

Destroy destructive

kill_session destructive

Kill a tmux session.

Returns: str

Use when you’re done with a workspace and want to clean up. Kills all windows and panes in the session.

Avoid when you only want to close one window — use kill_window destructive.

Side effects: Destroys the session and all its contents. Not reversible.

Parameters

Parameter	Type	Required	Default	Description
session_name	str	no	—	Session name to look up.
session_id	str	no	—	Session ID (e.g. ‘$1’) to look up.
socket_name	str	no	—	tmux socket name. Defaults to LIBTMUX_SOCKET env var.

---

kill_server destructive

Kill the tmux server and all its sessions.

Returns: str

Use when you need to tear down the entire tmux server. This kills every session, window, and pane.

Avoid when you only need to remove one session — use kill_session destructive.

Side effects: Destroys everything. Not reversible.

Parameters

Parameter	Type	Required	Default	Description
socket_name	str	no	—	tmux socket name. Defaults to LIBTMUX_SOCKET env var.