set_badge
Display custom translucent text on an iTerm2 session badge for easy identification.
Instructions
Set the iTerm2 session badge (translucent overlay text).
The profile's Badge field must reference \(user.badge) for the value
to show up; this is the default in stock profiles.
:param badge: Text to display as the badge. :param session_id: Target session UUID. Defaults to the active session.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| badge | Yes | ||
| session_id | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/iterm2_mcp/server.py:371-383 (handler)The handler for the 'set_badge' tool. Resolves the target session, then sets 'user.badge' via iTerm2's async_set_variable API.
@mcp.tool() async def set_badge(badge: str, session_id: str | None = None) -> str: """Set the iTerm2 session badge (translucent overlay text). The profile's Badge field must reference ``\\(user.badge)`` for the value to show up; this is the default in stock profiles. :param badge: Text to display as the badge. :param session_id: Target session UUID. Defaults to the active session. """ sess = await _session(session_id) await sess.async_set_variable("user.badge", badge) return f"Set badge on session {sess.session_id} to {badge!r}" - src/iterm2_mcp/server.py:371-371 (registration)Registration of set_badge as an MCP tool via the @mcp.tool() decorator. The FastMCP instance 'mcp' is created on line 21.
@mcp.tool()