get_active_session
Return the ID and name of the currently focused iTerm2 session. Use this to identify the active terminal for automation.
Instructions
Return the ID and name of the currently focused iTerm2 session.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/iterm2_mcp/server.py:104-108 (handler)The @mcp.tool() decorated handler that returns the ID and name of the currently focused iTerm2 session. It delegates to the _session(None) helper which resolves the active session.
@mcp.tool() async def get_active_session() -> str: """Return the ID and name of the currently focused iTerm2 session.""" sess = await _session(None) return f"{sess.session_id} {sess.name or ''}".rstrip() - src/iterm2_mcp/server.py:104-104 (registration)The tool is registered via the @mcp.tool() decorator on the 'get_active_session' function, which registers it with the FastMCP instance.
@mcp.tool() - src/iterm2_mcp/server.py:48-69 (helper)The _session() helper resolves a session by ID or falls back to the currently active window/tab/session. It is called by get_active_session with session_id=None to get 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