clear_buffer
Clears both the visible screen and scrollback buffer in iTerm2. Optionally specify a session UUID to target a specific session.
Instructions
Clear both the visible screen and the scrollback buffer.
Uses the iTerm2-proprietary OSC 1337 ; ClearScrollback control sequence
(https://iterm2.com/documentation-escape-codes.html).
:param session_id: Target session UUID. Defaults to the active session.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/iterm2_mcp/server.py:386-397 (handler)The 'clear_buffer' tool handler function. Decorated with @mcp.tool(), it clears the visible screen and scrollback buffer by sending the iTerm2-proprietary OSC 1337 ; ClearScrollback control sequence to the targeted session.
@mcp.tool() async def clear_buffer(session_id: str | None = None) -> str: """Clear both the visible screen and the scrollback buffer. Uses the iTerm2-proprietary ``OSC 1337 ; ClearScrollback`` control sequence (https://iterm2.com/documentation-escape-codes.html). :param session_id: Target session UUID. Defaults to the active session. """ sess = await _session(session_id) await sess.async_send_text("\x1b]1337;ClearScrollback\x07", suppress_broadcast=True) return f"Cleared buffer of session {sess.session_id}" - src/iterm2_mcp/server.py:386-386 (registration)The tool is registered via the @mcp.tool() decorator on line 386, which is a FastMCP decorator that registers the function as an MCP tool on the 'mcp' FastMCP instance (defined at line 21).
@mcp.tool() - src/iterm2_mcp/server.py:48-69 (helper)The '_session' helper function resolves a session ID or falls back to the active session. It is called by clear_buffer on line 395 to obtain the target 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