set_session_name
Rename an iTerm2 session to a specified name. Optionally target a specific session by UUID, otherwise renames the active session.
Instructions
Set the title/name of an iTerm2 session.
:param name: The new session name. :param session_id: Target session UUID. Defaults to the active session.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| session_id | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/iterm2_mcp/server.py:360-368 (handler)The async handler function for the 'set_session_name' tool. Accepts a name and optional session_id, resolves the session via _session(), calls async_set_name() on it, and returns a confirmation string.
async def set_session_name(name: str, session_id: str | None = None) -> str: """Set the title/name of an iTerm2 session. :param name: The new session name. :param session_id: Target session UUID. Defaults to the active session. """ sess = await _session(session_id) await sess.async_set_name(name) return f"Renamed session {sess.session_id} to {name!r}" - src/iterm2_mcp/server.py:359-359 (registration)Registration of the tool via the @mcp.tool() decorator on the set_session_name function.
@mcp.tool() - src/iterm2_mcp/server.py:48-69 (helper)The _session() helper used by set_session_name to resolve a session_id (or fall back to the active session).
async def _session(session_id: str | None) -> iterm2.Session: """Resolve a session by ID, falling back to the currently active session. :param session_id: A specific session UUID to target, or ``None`` to use the currently focused window/tab/pane. """ app = await _app() if session_id: sess = app.get_session_by_id(session_id) if sess is None: raise ValueError(f"No session found with ID {session_id!r}") return sess win = app.current_terminal_window if win is None: raise RuntimeError("No active iTerm2 window.") tab = win.current_tab if tab is None: raise RuntimeError("No active tab in the current window.") sess = tab.current_session if sess is None: raise RuntimeError("No active session in the current tab.") return sess - src/iterm2_mcp/server.py:360-365 (schema)Type signature and docstring defining the input schema: name (str, required), session_id (str | None, optional).
async def set_session_name(name: str, session_id: str | None = None) -> str: """Set the title/name of an iTerm2 session. :param name: The new session name. :param session_id: Target session UUID. Defaults to the active session. """