claude-team-mcp 0.3.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

claude_team_mcp/iterm_utils.py

@@ -6,7 +6,6 @@ from the original primitives.py for use in the MCP server.
 """
 
 import logging
-import os
 import re
 from typing import TYPE_CHECKING, Optional
 
@@ -18,6 +17,8 @@ if TYPE_CHECKING:
     from iterm2.tab import Tab as ItermTab
     from iterm2.window import Window as ItermWindow
 
+    from .cli_backends import AgentCLI
+
 from .subprocess_cache import cached_system_profiler
 
 logger = logging.getLogger("claude-team-mcp.iterm_utils")
@@ -95,6 +96,10 @@ async def send_prompt(session: "ItermSession", text: str, submit: bool = True) -
     The delay scales with text length since longer pastes take more time
     for the terminal to process.
 
+    Note: This function is primarily for Claude Code. For Codex, use
+    send_prompt_for_agent() which provides the longer pre-Enter delay
+    that Codex requires.
+
     Args:
         session: iTerm2 session object
         text: The text to send
@@ -126,6 +131,63 @@ async def send_prompt(session: "ItermSession", text: str, submit: bool = True) -
         await session.async_send_text(KEYS["enter"])
 
 
+# Pre-Enter delay for Codex (in seconds).
+# Codex uses crossterm in raw mode - batch text sending works fine,
+# but it needs a longer delay before Enter than Claude does.
+# Testing showed 200ms is reliable; 50ms (Claude's default) is too short.
+CODEX_PRE_ENTER_DELAY = 0.5  # 500ms minimum for Codex input processing
+
+
+async def send_prompt_for_agent(
+    session: "ItermSession",
+    text: str,
+    agent_type: str = "claude",
+    submit: bool = True,
+) -> None:
+    """
+    Send a prompt to an iTerm2 session, with agent-specific input handling.
+
+    Both Claude and Codex handle batch/burst text input correctly. The key
+    difference is the delay needed before pressing Enter:
+
+    - **Claude Code**: 50ms delay before Enter is sufficient.
+    - **Codex**: Needs ~250ms delay before Enter for reliable input processing.
+
+    Args:
+        session: iTerm2 session object
+        text: The text to send
+        agent_type: The agent type identifier ("claude" or "codex")
+        submit: If True, press Enter after sending text
+    """
+    import asyncio
+
+    if agent_type == "codex":
+        # Codex: batch send text, but use longer pre-Enter delay.
+        # For long/multi-line prompts, iTerm2's bracketed paste mode needs
+        # time to complete before Enter is sent. Use the same delay
+        # calculation as send_prompt() but ensure at least CODEX_PRE_ENTER_DELAY.
+        await session.async_send_text(text)
+        if submit:
+            # Calculate delay based on text length (same as send_prompt)
+            line_count = text.count("\n")
+            char_count = len(text)
+            if line_count > 0:
+                paste_delay = min(2.0, 0.1 + (line_count * 0.01) + (char_count / 1000 * 0.05))
+            else:
+                paste_delay = 0.05
+            # Use whichever is larger: paste delay or Codex minimum
+            delay = max(CODEX_PRE_ENTER_DELAY, paste_delay)
+            logger.debug(
+                "send_prompt_for_agent: codex chars=%d lines=%d delay=%.3fs",
+                char_count, line_count, delay
+            )
+            await asyncio.sleep(delay)
+            await session.async_send_text(KEYS["enter"])
+    else:
+        # Claude Code and other agents: use standard send_prompt
+        await send_prompt(session, text, submit=submit)
+
+
 async def read_screen(session: "ItermSession") -> list[str]:
     """
     Read all lines from an iTerm2 session's screen.
@@ -232,19 +294,15 @@ async def create_window(
     from iterm2.window import Window
 
     # Create the window
-    # Note: We conditionally pass profile_customizations only when not None
-    # due to iterm2 library's type stubs not marking it as Optional
+    # Build kwargs conditionally - only include profile if explicitly set,
+    # otherwise let iTerm2 use its default. Empty string causes INVALID_PROFILE_NAME.
+    kwargs: dict = {}
+    if profile is not None:
+        kwargs["profile"] = profile
     if profile_customizations is not None:
-        window = await Window.async_create(
-            connection,
-            profile=profile if profile is not None else "",
-            profile_customizations=profile_customizations,
-        )
-    else:
-        window = await Window.async_create(
-            connection,
-            profile=profile if profile is not None else "",
-        )
+        kwargs["profile_customizations"] = profile_customizations
+
+    window = await Window.async_create(connection, **kwargs)
 
     if window is None:
         raise RuntimeError("Failed to create iTerm2 window")
@@ -294,12 +352,14 @@ async def split_pane(
     Returns:
         The new session created in the split pane.
     """
-    return await session.async_split_pane(
-        vertical=vertical,
-        before=before,
-        profile=profile,
-        profile_customizations=profile_customizations,
-    )
+    # Build kwargs conditionally - only include profile if explicitly set
+    kwargs: dict = {"vertical": vertical, "before": before}
+    if profile is not None:
+        kwargs["profile"] = profile
+    if profile_customizations is not None:
+        kwargs["profile_customizations"] = profile_customizations
+
+    return await session.async_split_pane(**kwargs)
 
 
 async def close_pane(session: "ItermSession", force: bool = False) -> bool:
@@ -452,10 +512,77 @@ async def wait_for_claude_ready(
     return False
 
 
+async def wait_for_agent_ready(
+    session: "ItermSession",
+    cli: "AgentCLI",
+    timeout_seconds: float = 15.0,
+    poll_interval: float = 0.2,
+    stable_count: int = 2,
+) -> bool:
+    """
+    Wait for an agent CLI to be ready to accept input.
+
+    Generic version of wait_for_claude_ready() that uses the CLI's ready_patterns.
+    Polls the screen content and waits for any of the CLI's ready patterns to appear.
+
+    Args:
+        session: iTerm2 session to monitor
+        cli: The AgentCLI instance providing ready_patterns
+        timeout_seconds: Maximum time to wait for readiness
+        poll_interval: Time between screen content checks
+        stable_count: Number of consecutive stable reads before considering ready
+
+    Returns:
+        True if agent became ready, False if timeout was reached
+    """
+    import asyncio
+    import time
+
+    patterns = cli.ready_patterns()
+    start_time = time.monotonic()
+    last_content = None
+    stable_reads = 0
+
+    while (time.monotonic() - start_time) < timeout_seconds:
+        try:
+            content = await read_screen_text(session)
+            lines = content.split('\n')
+
+            # Check if content is stable (same as last read)
+            if content == last_content:
+                stable_reads += 1
+            else:
+                stable_reads = 0
+                last_content = content
+
+            # Only check for readiness after content has stabilized
+            if stable_reads >= stable_count:
+                for line in lines:
+                    stripped = line.strip()
+                    for pattern in patterns:
+                        if pattern in stripped:
+                            logger.debug(
+                                f"Agent ready: found pattern '{pattern}' in line"
+                            )
+                            return True
+
+        except Exception as e:
+            # Screen read failed, retry
+            logger.debug(f"Screen read failed during agent ready check: {e}")
+
+        await asyncio.sleep(poll_interval)
+
+    logger.warning(
+        f"Timeout waiting for {cli.engine_id} readiness ({timeout_seconds}s)"
+    )
+    return False
+
+
 # =============================================================================
-# Claude Session Control
+# Agent Session Control
 # =============================================================================
 
+
 def build_stop_hook_settings_file(marker_id: str) -> str:
     """
     Build a settings file for Stop hook injection.
@@ -500,6 +627,84 @@ def build_stop_hook_settings_file(marker_id: str) -> str:
     return str(settings_file)
 
 
+async def start_agent_in_session(
+    session: "ItermSession",
+    cli: "AgentCLI",
+    project_path: str,
+    dangerously_skip_permissions: bool = False,
+    env: Optional[dict[str, str]] = None,
+    shell_ready_timeout: float = 10.0,
+    agent_ready_timeout: float = 30.0,
+    stop_hook_marker_id: Optional[str] = None,
+    output_capture_path: Optional[str] = None,
+) -> None:
+    """
+    Start an agent CLI in an existing iTerm2 session.
+
+    Changes to the project directory and launches the agent in a single
+    atomic command (cd && <agent>). Waits for shell readiness before sending
+    the command, then waits for the agent's ready patterns to appear.
+
+    Args:
+        session: iTerm2 session to use
+        cli: AgentCLI instance defining command and arguments
+        project_path: Directory to run the agent in
+        dangerously_skip_permissions: If True, add skip-permissions flag
+        env: Optional dict of environment variables to set before running agent
+        shell_ready_timeout: Max seconds to wait for shell prompt
+        agent_ready_timeout: Max seconds to wait for agent to start
+        stop_hook_marker_id: If provided, inject a Stop hook for completion detection
+            (only used if cli.supports_settings_file() returns True)
+        output_capture_path: If provided, capture agent's stdout/stderr to this file
+            using tee. Useful for agents that output JSONL for idle detection.
+
+    Raises:
+        RuntimeError: If shell not ready or agent fails to start within timeout
+    """
+    # Wait for shell to be ready
+    shell_ready = await wait_for_shell_ready(session, timeout_seconds=shell_ready_timeout)
+    if not shell_ready:
+        raise RuntimeError(
+            f"Shell not ready after {shell_ready_timeout}s in {project_path}. "
+            "Terminal may still be initializing."
+        )
+
+    # Build settings file for Stop hook injection if supported
+    settings_file = None
+    if stop_hook_marker_id and cli.supports_settings_file():
+        settings_file = build_stop_hook_settings_file(stop_hook_marker_id)
+
+    # Build the full command using the AgentCLI abstraction
+    agent_cmd = cli.build_full_command(
+        dangerously_skip_permissions=dangerously_skip_permissions,
+        settings_file=settings_file,
+        env_vars=env,
+    )
+
+    # Add output capture via tee if requested
+    # This pipes stdout/stderr to both the terminal and a file (for JSONL parsing)
+    if output_capture_path:
+        agent_cmd = f"{agent_cmd} 2>&1 | tee {output_capture_path}"
+
+    # Combine cd and agent into atomic command to avoid race condition.
+    # Shell executes "cd /path && agent" as a unit - if cd fails, agent won't run.
+    cmd = f"cd {project_path} && {agent_cmd}"
+    
+    logger.info(f"start_agent_in_session: Running command: {cmd[:200]}...")
+
+    await send_prompt(session, cmd)
+
+    # Wait for agent to actually start (detect ready patterns, not blind sleep)
+    if not await wait_for_agent_ready(
+        session, cli, timeout_seconds=agent_ready_timeout
+    ):
+        raise RuntimeError(
+            f"{cli.engine_id} failed to start in {project_path} within "
+            f"{agent_ready_timeout}s. Check that '{cli.command()}' command is "
+            "available and authentication is configured."
+        )
+
+
 async def start_claude_in_session(
     session: "ItermSession",
     project_path: str,
@@ -512,6 +717,7 @@ async def start_claude_in_session(
     """
     Start Claude Code in an existing iTerm2 session.
 
+    Convenience wrapper around start_agent_in_session() for Claude.
     Changes to the project directory and launches Claude Code in a single
     atomic command (cd && claude). Waits for shell readiness before sending
     the command, then waits for Claude's startup banner to appear.
@@ -534,50 +740,38 @@ async def start_claude_in_session(
     Raises:
         RuntimeError: If shell not ready or Claude fails to start within timeout
     """
-    # Wait for shell to be ready
-    shell_ready = await wait_for_shell_ready(session, timeout_seconds=shell_ready_timeout)
-    if not shell_ready:
-        raise RuntimeError(
-            f"Shell not ready after {shell_ready_timeout}s in {project_path}. "
-            "Terminal may still be initializing."
-        )
-
-    # Build claude command with flags
-    # Allow overriding the claude command via environment variable (e.g., "happy")
-    claude_cmd = os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
-    is_default_claude_command = claude_cmd == "claude"
-
-    if dangerously_skip_permissions:
-        claude_cmd += " --dangerously-skip-permissions"
-
-    # Only add --settings for the default 'claude' command.
-    # Custom commands like 'happy' have their own session tracking mechanisms
-    # (e.g., Happy uses a SessionStart hook for mobile app integration).
-    # Adding our --settings flag conflicts with theirs because Claude only
-    # uses the first --settings file, breaking their session tracking.
-    # See HAPPY_INTEGRATION_RESEARCH.md for full analysis.
-    if stop_hook_marker_id and is_default_claude_command:
-        settings_file = build_stop_hook_settings_file(stop_hook_marker_id)
-        claude_cmd += f" --settings {settings_file}"
-
-    # Prepend environment variables to claude (not cd)
-    if env:
-        env_exports = " ".join(f"{k}={v}" for k, v in env.items())
-        claude_cmd = f"{env_exports} {claude_cmd}"
-
-    # Combine cd and claude into atomic command to avoid race condition.
-    # Shell executes "cd /path && claude" as a unit - if cd fails, claude won't run.
-    # This eliminates the need for a second wait_for_shell_ready after cd.
-    cmd = f"cd {project_path} && {claude_cmd}"
+    from .cli_backends import claude_cli
+
+    await start_agent_in_session(
+        session=session,
+        cli=claude_cli,
+        project_path=project_path,
+        dangerously_skip_permissions=dangerously_skip_permissions,
+        env=env,
+        shell_ready_timeout=shell_ready_timeout,
+        agent_ready_timeout=claude_ready_timeout,
+        stop_hook_marker_id=stop_hook_marker_id,
+    )
 
-    await send_prompt(session, cmd)
 
-    # Wait for Claude to actually start (detect banner, not blind sleep)
-    if not await wait_for_claude_ready(session, timeout_seconds=claude_ready_timeout):
-        raise RuntimeError(
-            f"Claude failed to start in {project_path} within {claude_ready_timeout}s. "
-            "Check that 'claude' command is available and authentication is configured."
-        )
+# Legacy alias for backward compatibility with Claude-specific code
+# that checks for banner patterns. Uses wait_for_agent_ready with claude_cli.
+async def _wait_for_claude_ready_via_agent(
+    session: "ItermSession",
+    timeout_seconds: float = 15.0,
+    poll_interval: float = 0.2,
+    stable_count: int = 2,
+) -> bool:
+    """Internal helper - uses wait_for_agent_ready with Claude CLI."""
+    from .cli_backends import claude_cli
+
+    return await wait_for_agent_ready(
+        session=session,
+        cli=claude_cli,
+        timeout_seconds=timeout_seconds,
+        poll_interval=poll_interval,
+        stable_count=stable_count,
+    )
 
 
 # =============================================================================

claude_team_mcp/names.py

@@ -119,6 +119,9 @@ DUOS: dict[str, list[str]] = {
     "tia_tamera": ["Tia", "Tamera"],
     "statler_waldorf": ["Statler", "Waldorf"],
     "laverne_shirley": ["Laverne", "Shirley"],
+    # Star Trek
+    "kirk_khan": ["Kirk", "Khan"],
+    "picard_q": ["Picard", "Q"],
 }
 
 # Terrific trios - famous threesomes

claude_team_mcp/registry.py

@@ -10,13 +10,16 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Literal, Optional
 
 if TYPE_CHECKING:
     from iterm2.session import Session as ItermSession
 
 from .session_state import get_project_dir, parse_session
 
+# Type alias for supported agent types
+AgentType = Literal["claude", "codex"]
+
 
 @dataclass(frozen=True)
 class TerminalId:
@@ -87,6 +90,9 @@ class ManagedSession:
     # Terminal-agnostic identifier (auto-populated from iterm_session if not set)
     terminal_id: Optional[TerminalId] = None
 
+    # Agent type: "claude" (default) or "codex"
+    agent_type: AgentType = "claude"
+
     def __post_init__(self):
         """Auto-populate terminal_id from iterm_session if not set."""
         if self.terminal_id is None and self.iterm_session is not None:
@@ -94,7 +100,7 @@ class ManagedSession:
 
     def to_dict(self) -> dict:
         """Convert to dictionary for MCP tool responses."""
-        return {
+        result = {
             "session_id": self.session_id,
             "terminal_id": str(self.terminal_id) if self.terminal_id else None,
             "name": self.name or self.session_id,
@@ -106,7 +112,9 @@ class ManagedSession:
             "coordinator_annotation": self.coordinator_annotation,
             "worktree_path": str(self.worktree_path) if self.worktree_path else None,
             "main_repo_path": str(self.main_repo_path) if self.main_repo_path else None,
+            "agent_type": self.agent_type,
         }
+        return result
 
     def update_activity(self) -> None:
         """Update the last_activity timestamp."""
@@ -139,47 +147,77 @@ class ManagedSession:
         """
         Get the path to this session's JSONL file.
 
-        Automatically tries to discover the session if not already known.
+        For Claude workers: uses marker-based discovery in ~/.claude/projects/.
+        For Codex workers: searches ~/.codex/sessions/ for matching session files.
 
         Returns:
             Path object, or None if session cannot be discovered
         """
-        # Auto-discover if not already known (using marker-based discovery)
-        if not self.claude_session_id:
-            self.discover_claude_session_by_marker()
+        if self.agent_type == "codex":
+            # For Codex, search the sessions directory
+            from .idle_detection import find_codex_session_file
 
-        if not self.claude_session_id:
-            return None
-        return get_project_dir(self.project_path) / f"{self.claude_session_id}.jsonl"
+            return find_codex_session_file(max_age_seconds=600)
+        else:
+            # For Claude, use marker-based discovery
+            # Auto-discover if not already known
+            if not self.claude_session_id:
+                self.discover_claude_session_by_marker()
+
+            if not self.claude_session_id:
+                return None
+            return get_project_dir(self.project_path) / f"{self.claude_session_id}.jsonl"
 
     def get_conversation_state(self):
         """
         Parse and return the current conversation state.
 
+        For Claude workers: uses parse_session() for Claude's JSONL format.
+        For Codex workers: uses parse_codex_session() for Codex's JSONL format.
+
         Returns:
             SessionState object, or None if JSONL not available
         """
         jsonl_path = self.get_jsonl_path()
         if not jsonl_path or not jsonl_path.exists():
             return None
-        return parse_session(jsonl_path)
+
+        if self.agent_type == "codex":
+            from .session_state import parse_codex_session
+
+            return parse_codex_session(jsonl_path)
+        else:
+            return parse_session(jsonl_path)
 
     def is_idle(self) -> bool:
         """
-        Check if this session is idle using stop hook detection.
+        Check if this session is idle.
+
+        For Claude: Uses stop hook detection - session is idle if its Stop hook
+        has fired and no messages have been sent after it.
 
-        A session is idle if its Stop hook has fired and no messages
-        have been sent after it.
+        For Codex: Searches ~/.codex/sessions/ for the session file and checks
+        for agent_message events which indicate the agent finished responding.
 
         Returns:
-            True if idle, False if working or JSONL not available
+            True if idle, False if working or session file not available
         """
-        from .idle_detection import is_idle as check_is_idle
-
-        jsonl_path = self.get_jsonl_path()
-        if not jsonl_path or not jsonl_path.exists():
-            return False
-        return check_is_idle(jsonl_path, self.session_id)
+        if self.agent_type == "codex":
+            from .idle_detection import find_codex_session_file, is_codex_idle
+
+            # Find the session file (will be discovered from ~/.codex/sessions/)
+            session_file = find_codex_session_file(max_age_seconds=600)
+            if not session_file:
+                return False
+            return is_codex_idle(session_file)
+        else:
+            # Default: Claude Code with Stop hook detection
+            from .idle_detection import is_idle as check_is_idle
+
+            jsonl_path = self.get_jsonl_path()
+            if not jsonl_path or not jsonl_path.exists():
+                return False
+            return check_is_idle(jsonl_path, self.session_id)
 
     def get_conversation_stats(self) -> dict | None:
         """

claude_team_mcp/schemas/__init__.py

@@ -0,0 +1,5 @@
+"""Schema definitions for parsing CLI output formats."""
+
+from . import codex
+
+__all__ = ["codex"]