claude-team-mcp 0.6.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

claude_team_mcp/tools/spawn_workers.py

@@ -19,20 +19,10 @@ if TYPE_CHECKING:
 from ..cli_backends import get_cli_backend
 from ..colors import generate_tab_color
 from ..formatting import format_badge_text, format_session_title
-from ..iterm_utils import (
-    MAX_PANES_PER_TAB,
-    create_multi_pane_layout,
-    find_available_window,
-    get_window_for_session,
-    send_prompt,
-    send_prompt_for_agent,
-    split_pane,
-    start_agent_in_session,
-    start_claude_in_session,
-)
 from ..names import pick_names_for_count
 from ..profile import apply_appearance_colors
 from ..registry import SessionStatus
+from ..terminal_backends import ItermBackend, MAX_PANES_PER_TAB
 from ..utils import HINTS, error_response, get_worktree_tracker_dir
 from ..worker_prompt import generate_worker_prompt, get_coordinator_guidance
 from ..worktree import WorktreeError, create_local_worktree
@@ -40,6 +30,13 @@ from ..worktree import WorktreeError, create_local_worktree
 logger = logging.getLogger("claude-team-mcp")
 
 
+class WorktreeConfig(TypedDict, total=False):
+    """Configuration for worktree creation."""
+
+    branch: str  # Optional: Branch name for the worktree
+    base: str  # Optional: Base ref/branch for the new branch
+
+
 class WorkerConfig(TypedDict, total=False):
     """Configuration for a single worker."""
 
@@ -51,6 +48,7 @@ class WorkerConfig(TypedDict, total=False):
     prompt: str  # Optional: Custom prompt (None = standard worker prompt)
     skip_permissions: bool  # Optional: Default False
     use_worktree: bool  # Optional: Create isolated worktree (default True)
+    worktree: WorktreeConfig  # Optional: Worktree settings (branch/base)
 
 
 def register_tools(mcp: FastMCP, ensure_connection) -> None:
@@ -65,9 +63,10 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
         """
         Spawn Claude Code worker sessions.
 
-        Creates worker sessions in iTerm2, each with its own pane, Claude instance,
-        and optional worktree. Workers can be spawned into existing windows (layout="auto")
-        or a fresh window (layout="new").
+        Creates worker sessions in the active terminal backend, each with its own pane
+        (iTerm) or window (tmux), Claude instance, and optional worktree. Workers can be
+        spawned into existing
+        windows (layout="auto") or a fresh window (layout="new").
 
         **Layout Modes:**
 
@@ -83,6 +82,10 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
            - 3 workers: triple vertical (left/middle/right)
            - 4 workers: quad layout (2x2 grid)
 
+        **tmux note:**
+           - Workers always get their own tmux window in the shared "claude-team" session.
+           - layout is ignored for tmux.
+
         **WorkerConfig fields:**
             project_path: Required. Path to the repository.
                 - Explicit path: Use this repo (e.g., "/path/to/repo")
@@ -107,6 +110,9 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                 - True: Creates worktree at <repo>/.worktrees/<bead>-<annotation>
                   or <repo>/.worktrees/<name>-<uuid>-<annotation>
                 - False: Worker uses the repo directory directly (no isolation)
+            worktree: Optional worktree configuration.
+                - branch: Branch name for the worktree
+                - base: Base ref/branch for the new branch
             name: Optional worker name override. Leaving this empty allows us to auto-pick names
                 from themed sets (Beatles, Marx Brothers, etc.) which aids visual identification.
             annotation: Optional task description. Shown on badge second line, used in
@@ -180,8 +186,6 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
             # Then immediately:
             message_workers(session_ids=["Groucho"], message="Your task is...")
         """
-        from iterm2.profile import LocalWriteOnlyProfile
-
         from ..session_state import await_marker_in_jsonl, generate_marker_message
 
         app_ctx = ctx.request_context.lifespan_context
@@ -201,8 +205,8 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
             if "project_path" not in w:
                 return error_response(f"Worker {i} missing required 'project_path'")
 
-        # Ensure we have a fresh connection
-        connection, app = await ensure_connection(app_ctx)
+        # Ensure we have a fresh backend connection/state
+        backend = await ensure_connection(app_ctx)
 
         try:
             # Get base session index for color generation
@@ -233,6 +237,7 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
             resolved_paths: list[str] = []
             worktree_paths: dict[int, Path] = {}  # index -> worktree path
             main_repo_paths: dict[int, Path] = {}  # index -> main repo
+            worktree_warnings: list[str] = []
 
             # Get CLAUDE_TEAM_PROJECT_DIR for "auto" paths
             env_project_dir = os.environ.get("CLAUDE_TEAM_PROJECT_DIR")
@@ -240,9 +245,26 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
             for i, (w, name) in enumerate(zip(workers, resolved_names)):
                 project_path = w["project_path"]
                 use_worktree = w.get("use_worktree", True)  # Default True
+                worktree_config = w.get("worktree")
+                worktree_explicitly_requested = worktree_config is not None
+                worktree_branch = None
+                worktree_base = None
                 bead = w.get("bead")
                 annotation = w.get("annotation")
 
+                if worktree_config is not None:
+                    if isinstance(worktree_config, dict):
+                        worktree_branch = worktree_config.get("branch")
+                        worktree_base = worktree_config.get("base")
+                        use_worktree = True
+                    elif isinstance(worktree_config, bool):
+                        use_worktree = worktree_config
+                    else:
+                        return error_response(
+                            f"Worker {i} has invalid 'worktree' configuration",
+                            hint="Expected a dict with optional 'branch'/'base' fields or a boolean.",
+                        )
+
                 # Step 1: Resolve repo path
                 if project_path == "auto":
                     if env_project_dir:
@@ -272,16 +294,28 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                             worker_name=name,
                             bead_id=bead,
                             annotation=annotation,
+                            branch=worktree_branch,
+                            base=worktree_base,
                         )
                         worktree_paths[i] = worktree_path
                         main_repo_paths[i] = repo_path
                         resolved_paths.append(str(worktree_path))
                         logger.info(f"Created local worktree for {name} at {worktree_path}")
                     except WorktreeError as e:
-                        logger.warning(
+                        warning_message = (
                             f"Failed to create worktree for {name}: {e}. "
                             "Using repo directly."
                         )
+                        if worktree_explicitly_requested:
+                            return error_response(
+                                warning_message,
+                                hint=(
+                                    "Verify the worktree branch/base settings and "
+                                    "that the repository is in a clean state."
+                                ),
+                            )
+                        logger.warning(warning_message)
+                        worktree_warnings.append(warning_message)
                         resolved_paths.append(str(repo_path))
                 else:
                     # No worktree - use repo directly
@@ -290,44 +324,72 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
             # Pre-generate session IDs for Stop hook injection
             session_ids = [str(uuid.uuid4())[:8] for _ in workers]
 
-            # Build profile customizations for each worker
-            profile_customizations: list[LocalWriteOnlyProfile] = []
-            for i, (w, name) in enumerate(zip(workers, resolved_names)):
-                customization = LocalWriteOnlyProfile()
+            # Build profile customizations for each worker (iTerm-only)
+            profile_customizations: list[object | None] = [None] * worker_count
+            if isinstance(backend, ItermBackend):
+                from iterm2.profile import LocalWriteOnlyProfile
 
-                bead = w.get("bead")
-                annotation = w.get("annotation")
-                agent_type = w.get("agent_type", "claude")
+                profile_customizations = []
+                for i, (w, name) in enumerate(zip(workers, resolved_names)):
+                    customization = LocalWriteOnlyProfile()
 
-                # Tab title
-                tab_title = format_session_title(name, issue_id=bead, annotation=annotation)
-                customization.set_name(tab_title)
+                    bead = w.get("bead")
+                    annotation = w.get("annotation")
+                    agent_type = w.get("agent_type", "claude")
 
-                # Tab color (unique per worker)
-                color = generate_tab_color(base_index + i)
-                customization.set_tab_color(color)
-                customization.set_use_tab_color(True)
+                    # Tab title
+                    tab_title = format_session_title(
+                        name, issue_id=bead, annotation=annotation
+                    )
+                    customization.set_name(tab_title)
 
-                # Badge (multi-line with bead/name, annotation, and agent type indicator)
-                badge_text = format_badge_text(
-                    name, bead=bead, annotation=annotation, agent_type=agent_type
-                )
-                customization.set_badge_text(badge_text)
+                    # Tab color (unique per worker)
+                    color = generate_tab_color(base_index + i)
+                    customization.set_tab_color(color)
+                    customization.set_use_tab_color(True)
+
+                    # Badge (multi-line with bead/name, annotation, and agent type indicator)
+                    badge_text = format_badge_text(
+                        name, bead=bead, annotation=annotation, agent_type=agent_type
+                    )
+                    customization.set_badge_text(badge_text)
 
-                # Apply current appearance mode colors
-                await apply_appearance_colors(customization, connection)
+                    # Apply current appearance mode colors
+                    await apply_appearance_colors(customization, backend.connection)
 
-                profile_customizations.append(customization)
+                    profile_customizations.append(customization)
 
             # Create panes based on layout mode
-            pane_sessions: list = []  # list of iTerm sessions
-
-            if layout == "auto":
+            pane_sessions: list = []  # list of terminal handles
+
+            if backend.backend_id == "tmux":
+                for i in range(worker_count):
+                    pane_sessions.append(
+                        await backend.create_session(
+                            name=resolved_names[i],
+                            project_path=resolved_paths[i],
+                            issue_id=workers[i].get("bead"),
+                            coordinator_annotation=workers[i].get("annotation"),
+                        )
+                    )
+            elif layout == "auto":
                 # Try to find an existing window where the ENTIRE batch fits.
                 # This keeps spawn batches together rather than spreading across windows.
-                target_tab = None
+                reuse_window = False
                 initial_pane_count = 0
-                first_session = None  # Session to split from
+                first_session = None  # Terminal handle to split from
+
+                def _count_tmux_panes(target_session, sessions) -> int:
+                    session_name = target_session.metadata.get("session_name")
+                    window_index = target_session.metadata.get("window_index")
+                    if not session_name or window_index is None:
+                        return 1
+                    return sum(
+                        1
+                        for session in sessions
+                        if session.metadata.get("session_name") == session_name
+                        and session.metadata.get("window_index") == window_index
+                    )
 
                 # Prefer the coordinator's window when running inside iTerm2.
                 # ITERM_SESSION_ID format is "wXtYpZ:UUID" - extract just the UUID.
@@ -335,67 +397,65 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                 coordinator_session_id = None
                 if iterm_session_env and ":" in iterm_session_env:
                     coordinator_session_id = iterm_session_env.split(":", 1)[1]
-                if coordinator_session_id:
-                    coordinator_session = None
-                    coordinator_tab = None
-
-                    for window in app.terminal_windows:
-                        for tab in window.tabs:
-                            for session in tab.sessions:
-                                if session.session_id == coordinator_session_id:
-                                    coordinator_session = session
-                                    coordinator_tab = tab
-                                    break
-                            if coordinator_session:
-                                break
-                        if coordinator_session:
+                if coordinator_session_id and isinstance(backend, ItermBackend):
+                    coordinator_handle = None
+                    for session_handle in await backend.list_sessions():
+                        if session_handle.native_id == coordinator_session_id:
+                            coordinator_handle = session_handle
                             break
 
-                    if coordinator_session and coordinator_tab:
-                        coordinator_window = await get_window_for_session(
-                            app, coordinator_session
+                    if coordinator_handle:
+                        coordinator_window = await backend.get_window_for_handle(
+                            coordinator_handle
                         )
                         if coordinator_window is not None:
-                            initial_pane_count = len(coordinator_tab.sessions)
-                            available_slots = MAX_PANES_PER_TAB - initial_pane_count
-                            if worker_count <= available_slots:
-                                target_tab = coordinator_tab
-                                first_session = coordinator_session
-                                logger.debug(
-                                    "Using coordinator window "
-                                    f"({initial_pane_count} panes, {available_slots} slots)"
-                                )
-
-                if target_tab is None:
-                    managed_iterm_ids: set[str] = {
-                        s.iterm_session.session_id
+                            native_session = backend.unwrap_session(coordinator_handle)
+                            coordinator_tab = native_session.tab
+                            if coordinator_tab is not None:
+                                initial_pane_count = len(coordinator_tab.sessions)
+                                available_slots = MAX_PANES_PER_TAB - initial_pane_count
+                                if worker_count <= available_slots:
+                                    reuse_window = True
+                                    first_session = coordinator_handle
+                                    logger.debug(
+                                        "Using coordinator window "
+                                        f"({initial_pane_count} panes, {available_slots} slots)"
+                                    )
+
+                if not reuse_window:
+                    managed_session_ids = {
+                        s.terminal_session.native_id
                         for s in registry.list_all()
-                        if s.iterm_session is not None
+                        if s.terminal_session.backend_id == backend.backend_id
                     }
 
                     # Find a window with enough space for ALL workers
-                    result = await find_available_window(
-                        app,
+                    result = await backend.find_available_window(
                         max_panes=MAX_PANES_PER_TAB,
-                        managed_session_ids=managed_iterm_ids,
+                        managed_session_ids=managed_session_ids,
                     )
 
                     if result:
-                        window, tab, existing_session = result
-                        initial_pane_count = len(tab.sessions)
+                        _, tab_or_window, existing_session = result
+                        first_session = existing_session
+                        if isinstance(backend, ItermBackend):
+                            initial_pane_count = len(tab_or_window.sessions)
+                        else:
+                            initial_pane_count = _count_tmux_panes(
+                                existing_session, await backend.list_sessions()
+                            )
                         available_slots = MAX_PANES_PER_TAB - initial_pane_count
 
                         if worker_count <= available_slots:
                             # Entire batch fits in this window
-                            target_tab = tab
-                            first_session = existing_session
+                            reuse_window = True
                             logger.debug(
                                 f"Batch of {worker_count} fits in existing window "
                                 f"({initial_pane_count} panes, {available_slots} slots)"
                             )
 
-                if target_tab:
-                    # Reuse existing window - track pane count locally (iTerm objects stale)
+                if reuse_window and first_session is not None:
+                    # Reuse existing window - track pane count locally
                     local_pane_count = initial_pane_count
                     final_pane_count = initial_pane_count + worker_count
                     # Track created sessions for splitting
@@ -411,7 +471,7 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                             #                    | worker2
                             if local_pane_count == 1:
                                 # First split: vertical from coordinator
-                                new_session = await split_pane(
+                                new_session = await backend.split_pane(
                                     first_session,
                                     vertical=True,
                                     before=False,
@@ -420,8 +480,11 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                                 )
                             else:
                                 # Second split: horizontal from first worker (stack on right)
-                                new_session = await split_pane(
-                                    created_sessions[0],
+                                split_target = (
+                                    created_sessions[0] if created_sessions else first_session
+                                )
+                                new_session = await backend.split_pane(
+                                    split_target,
                                     vertical=False,
                                     before=False,
                                     profile=None,
@@ -431,7 +494,7 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                             # Quad pattern: TL→TR(vsplit)→BL(hsplit)→BR(hsplit)
                             if local_pane_count == 1:
                                 # First split: vertical (left/right)
-                                new_session = await split_pane(
+                                new_session = await backend.split_pane(
                                     first_session,
                                     vertical=True,
                                     before=False,
@@ -440,7 +503,7 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                                 )
                             elif local_pane_count == 2:
                                 # Second split: horizontal from left pane (bottom-left)
-                                new_session = await split_pane(
+                                new_session = await backend.split_pane(
                                     first_session,
                                     vertical=False,
                                     before=False,
@@ -452,7 +515,7 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                                 tr_session = (
                                     created_sessions[0] if created_sessions else first_session
                                 )
-                                new_session = await split_pane(
+                                new_session = await backend.split_pane(
                                     tr_session,
                                     vertical=False,
                                     before=False,
@@ -482,12 +545,14 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                         window_layout = "quad"
                         pane_names = ["top_left", "top_right", "bottom_left", "bottom_right"]
 
-                    customizations_dict = {
-                        pane_names[i]: profile_customizations[i] for i in range(worker_count)
-                    }
+                    customizations_dict = None
+                    if isinstance(backend, ItermBackend):
+                        customizations_dict = {
+                            pane_names[i]: profile_customizations[i]
+                            for i in range(worker_count)
+                        }
 
-                    panes = await create_multi_pane_layout(
-                        connection,
+                    panes = await backend.create_multi_pane_layout(
                         window_layout,
                         profile=None,
                         profile_customizations=customizations_dict,
@@ -511,12 +576,14 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                     pane_names = ["top_left", "top_right", "bottom_left", "bottom_right"]
 
                 # Build customizations dict for layout
-                customizations_dict = {
-                    pane_names[i]: profile_customizations[i] for i in range(worker_count)
-                }
+                customizations_dict = None
+                if isinstance(backend, ItermBackend):
+                    customizations_dict = {
+                        pane_names[i]: profile_customizations[i]
+                        for i in range(worker_count)
+                    }
 
-                panes = await create_multi_pane_layout(
-                    connection,
+                panes = await backend.create_multi_pane_layout(
                     window_layout,
                     profile=None,
                     profile_customizations=customizations_dict,
@@ -549,25 +616,16 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                 else:
                     env = None
 
-                if agent_type == "codex":
-                    # Start Codex in interactive mode using start_agent_in_session
-                    cli = get_cli_backend("codex")
-                    await start_agent_in_session(
-                        session=session,
-                        cli=cli,
-                        project_path=project_path,
-                        dangerously_skip_permissions=worker_config.get("skip_permissions", False),
-                        env=env,
-                    )
-                else:
-                    # For Claude: use start_claude_in_session (convenience wrapper)
-                    await start_claude_in_session(
-                        session=session,
-                        project_path=project_path,
-                        dangerously_skip_permissions=worker_config.get("skip_permissions", False),
-                        env=env,
-                        stop_hook_marker_id=marker_id,
-                    )
+                cli = get_cli_backend(agent_type)
+                stop_hook_marker_id = marker_id if agent_type == "claude" else None
+                await backend.start_agent_in_session(
+                    handle=session,
+                    cli=cli,
+                    project_path=project_path,
+                    dangerously_skip_permissions=worker_config.get("skip_permissions", False),
+                    env=env,
+                    stop_hook_marker_id=stop_hook_marker_id,
+                )
 
             await asyncio.gather(*[start_agent_for_worker(i) for i in range(worker_count)])
 
@@ -575,7 +633,7 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
             managed_sessions = []
             for i in range(worker_count):
                 managed = registry.add(
-                    iterm_session=pane_sessions[i],
+                    terminal_session=pane_sessions[i],
                     project_path=resolved_paths[i],
                     name=resolved_names[i],
                     session_id=session_ids[i],
@@ -590,15 +648,28 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                     managed.main_repo_path = main_repo_paths[i]
                 managed_sessions.append(managed)
 
-            # Send marker messages for JSONL correlation (Claude only)
-            # Codex doesn't use JSONL markers for session tracking
+            # Send marker messages for JSONL correlation (Claude + Codex)
             for i, managed in enumerate(managed_sessions):
-                if managed.agent_type == "claude":
-                    marker_message = generate_marker_message(
-                        managed.session_id,
-                        iterm_session_id=managed.iterm_session.session_id,
-                    )
-                    await send_prompt(pane_sessions[i], marker_message, submit=True)
+                iterm_session_id = None
+                tmux_pane_ids = None
+                if managed.terminal_session.backend_id == "iterm":
+                    iterm_session_id = managed.terminal_session.native_id
+                elif managed.terminal_session.backend_id == "tmux":
+                    tmux_pane_ids = [managed.terminal_session.native_id]
+                marker_message = generate_marker_message(
+                    managed.session_id,
+                    iterm_session_id=iterm_session_id,
+                    tmux_pane_ids=tmux_pane_ids,
+                    project_path=(
+                        managed.project_path if managed.agent_type == "codex" else None
+                    ),
+                )
+                await backend.send_prompt_for_agent(
+                    pane_sessions[i],
+                    marker_message,
+                    agent_type=managed.agent_type,
+                    submit=True,
+                )
 
             # Wait for markers to appear in JSONL (Claude only)
             for i, managed in enumerate(managed_sessions):
@@ -646,8 +717,17 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
 
                 # Send prompt to the already-running agent (both Claude and Codex)
                 # Use agent-specific timing (Codex needs longer delay before Enter)
-                logger.info(f"Sending prompt to {managed.name} (agent_type={managed.agent_type}, chars={len(worker_prompt)})")
-                await send_prompt_for_agent(pane_sessions[i], worker_prompt, agent_type=managed.agent_type)
+                logger.info(
+                    "Sending prompt to %s (agent_type=%s, chars=%d)",
+                    managed.name,
+                    managed.agent_type,
+                    len(worker_prompt),
+                )
+                await backend.send_prompt_for_agent(
+                    pane_sessions[i],
+                    worker_prompt,
+                    agent_type=managed.agent_type,
+                )
                 logger.info(f"Prompt sent to {managed.name}")
 
             # Mark sessions ready
@@ -657,16 +737,13 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                 result_sessions[managed.name] = managed.to_dict()
 
             # Re-activate the window to bring it to focus
-            try:
-                await app.async_activate()
-                if pane_sessions:
-                    tab = pane_sessions[0].tab
-                    if tab is not None:
-                        window = tab.window
-                        if window is not None:
-                            await window.async_activate()
-            except Exception as e:
-                logger.debug(f"Failed to re-activate window: {e}")
+            if isinstance(backend, ItermBackend):
+                try:
+                    await backend.activate_app()
+                    if pane_sessions:
+                        await backend.activate_window_for_handle(pane_sessions[0])
+                except Exception as e:
+                    logger.debug(f"Failed to re-activate window: {e}")
 
             # Build worker summaries for coordinator guidance
             worker_summaries = []
@@ -695,6 +772,8 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
             # Add structured warning for programmatic access
             if workers_awaiting_task:
                 result["workers_awaiting_task"] = workers_awaiting_task
+            if worktree_warnings:
+                result["warnings"] = worktree_warnings
 
             return result
 

claude_team_mcp/tools/wait_idle_workers.py

@@ -92,6 +92,7 @@ def register_tools(mcp: FastMCP) -> None:
             session_infos.append(SessionInfo(
                 jsonl_path=jsonl_path,
                 session_id=session.session_id,  # Must use internal ID to match stop hook marker
+                agent_type=session.agent_type,
             ))
 
         # Report any missing sessions/files

claude_team_mcp/utils/errors.py

@@ -34,7 +34,7 @@ def error_response(
 HINTS = {
     "session_not_found": (
         "Run list_workers to see available workers, or discover_workers "
-        "to find orphaned iTerm2 sessions that can be adopted"
+        "to find orphaned terminal sessions that can be adopted"
     ),
     "project_path_missing": (
         "Verify the path exists. For git worktrees, check 'git worktree list'. "
@@ -44,9 +44,13 @@ HINTS = {
         "Ensure iTerm2 is running and Python API is enabled: "
         "iTerm2 → Preferences → General → Magic → Enable Python API"
     ),
+    "terminal_backend_required": (
+        "This tool only supports the iTerm2 or tmux backends. "
+        "Set CLAUDE_TEAM_TERMINAL_BACKEND=iterm or tmux, or run inside a supported terminal."
+    ),
     "registry_empty": (
         "No workers are being managed. Use spawn_workers to create new workers, "
-        "or discover_workers to find existing Claude sessions in iTerm2"
+        "or discover_workers to find existing Claude sessions in a supported terminal"
     ),
     "no_jsonl_file": (
         "Claude may not have started yet or the session file doesn't exist. "
@@ -73,7 +77,7 @@ def get_session_or_error(
 
     Args:
         registry: The session registry to search
-        session_id: ID to resolve (supports session_id, iterm_session_id, or name)
+        session_id: ID to resolve (supports session_id, terminal_id, or name)
 
     Returns:
         ManagedSession if found, or error dict with hint if not found