claude-team-mcp 0.4.0__py3-none-any.whl

claude_team_mcp/__init__.py

@@ -0,0 +1,24 @@
+"""
+Claude Team MCP Server
+
+An MCP server that allows one Claude Code session to spawn and manage
+a team of other Claude Code sessions via iTerm2.
+"""
+
+__version__ = "0.1.0"
+
+from .colors import generate_tab_color, get_hue_for_index, hsl_to_rgb_tuple
+
+
+def main():
+    """Entry point for the claude-team command."""
+    from .server import main as server_main
+    server_main()
+
+
+__all__ = [
+    "main",
+    "generate_tab_color",
+    "get_hue_for_index",
+    "hsl_to_rgb_tuple",
+]

claude_team_mcp/__main__.py

@@ -0,0 +1,8 @@
+"""
+Allow running the package directly with: python -m claude_team_mcp
+"""
+
+from . import main
+
+if __name__ == "__main__":
+    main()

claude_team_mcp/cli_backends/__init__.py

@@ -0,0 +1,44 @@
+"""
+CLI Backends Module.
+
+Provides abstraction layer for different agent CLI tools (Claude Code, Codex, etc.)
+This allows claude-team to orchestrate multiple agent types through a unified interface.
+"""
+
+from .base import AgentCLI
+from .claude import ClaudeCLI, claude_cli
+from .codex import CodexCLI, codex_cli
+
+__all__ = [
+    "AgentCLI",
+    "ClaudeCLI",
+    "claude_cli",
+    "CodexCLI",
+    "codex_cli",
+    "get_cli_backend",
+]
+
+
+def get_cli_backend(agent_type: str = "claude") -> AgentCLI:
+    """
+    Get a CLI backend instance by agent type.
+
+    Args:
+        agent_type: The agent type ("claude" or "codex")
+
+    Returns:
+        An AgentCLI implementation instance
+
+    Raises:
+        ValueError: If the agent type is not supported
+    """
+    backends = {
+        "claude": claude_cli,
+        "codex": codex_cli,
+    }
+
+    if agent_type not in backends:
+        valid = ", ".join(sorted(backends.keys()))
+        raise ValueError(f"Unknown agent type: {agent_type}. Valid types: {valid}")
+
+    return backends[agent_type]

claude_team_mcp/cli_backends/base.py

@@ -0,0 +1,132 @@
+"""
+Base protocol for CLI agent backends.
+
+Defines the interface that all CLI backends (Claude, Codex, etc.) must implement.
+This abstraction allows claude-team to orchestrate different agent CLIs.
+"""
+
+from abc import abstractmethod
+from typing import Literal, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class AgentCLI(Protocol):
+    """
+    Protocol defining the interface for agent CLI backends.
+
+    Each implementation encapsulates the CLI-specific details:
+    - Command and arguments
+    - Ready detection patterns
+    - Idle/completion detection method
+    - Settings/hook injection support
+    """
+
+    @property
+    @abstractmethod
+    def engine_id(self) -> str:
+        """
+        Unique identifier for this CLI engine (e.g., "claude", "codex").
+
+        Used for configuration, logging, and distinguishing between backends.
+        """
+        ...
+
+    @abstractmethod
+    def command(self) -> str:
+        """
+        Return the CLI executable name or path.
+
+        Examples: "claude", "codex", "/usr/local/bin/custom-agent"
+        """
+        ...
+
+    @abstractmethod
+    def build_args(
+        self,
+        *,
+        dangerously_skip_permissions: bool = False,
+        settings_file: str | None = None,
+    ) -> list[str]:
+        """
+        Build the argument list for the CLI command.
+
+        Args:
+            dangerously_skip_permissions: If True, add flag to skip permission prompts
+            settings_file: Optional path to settings file for hook injection
+
+        Returns:
+            List of command-line arguments (not including the command itself)
+        """
+        ...
+
+    @abstractmethod
+    def ready_patterns(self) -> list[str]:
+        """
+        Return patterns that indicate the CLI is ready for input.
+
+        These patterns are searched for in terminal output to detect when
+        the agent has started and is ready to receive prompts.
+
+        Returns:
+            List of strings to search for in terminal output
+        """
+        ...
+
+    @abstractmethod
+    def idle_detection_method(self) -> Literal["stop_hook", "jsonl_stream", "none"]:
+        """
+        Return the method used to detect when the agent finishes responding.
+
+        - "stop_hook": Uses a Stop hook that fires when the agent completes
+        - "jsonl_stream": Monitors JSONL output for completion markers
+        - "none": No idle detection available (must use timeouts)
+
+        Returns:
+            The detection method identifier
+        """
+        ...
+
+    @abstractmethod
+    def supports_settings_file(self) -> bool:
+        """
+        Return whether this CLI supports --settings flag for hook injection.
+
+        If False, build_args() should ignore the settings_file parameter.
+        """
+        ...
+
+    def build_full_command(
+        self,
+        *,
+        dangerously_skip_permissions: bool = False,
+        settings_file: str | None = None,
+        env_vars: dict[str, str] | None = None,
+    ) -> str:
+        """
+        Build the complete command string including env vars.
+
+        This is a convenience method that combines command(), build_args(),
+        and optional environment variables into a single shell command string.
+
+        Args:
+            dangerously_skip_permissions: Skip permission prompts
+            settings_file: Settings file for hook injection
+            env_vars: Environment variables to prepend
+
+        Returns:
+            Complete command string ready for shell execution
+        """
+        cmd = self.command()
+        args = self.build_args(
+            dangerously_skip_permissions=dangerously_skip_permissions,
+            settings_file=settings_file if self.supports_settings_file() else None,
+        )
+
+        if args:
+            cmd = f"{cmd} {' '.join(args)}"
+
+        if env_vars:
+            env_exports = " ".join(f"{k}={v}" for k, v in env_vars.items())
+            cmd = f"{env_exports} {cmd}"
+
+        return cmd

claude_team_mcp/cli_backends/claude.py

@@ -0,0 +1,110 @@
+"""
+Claude Code CLI backend.
+
+Implements the AgentCLI protocol for Claude Code CLI.
+This preserves the existing behavior from iterm_utils.py.
+"""
+
+import os
+from typing import Literal
+
+from .base import AgentCLI
+
+
+class ClaudeCLI(AgentCLI):
+    """
+    Claude Code CLI implementation.
+
+    Supports:
+    - --dangerously-skip-permissions flag
+    - --settings flag for Stop hook injection
+    - Ready detection via TUI patterns (robot banner, '>' prompt, 'tokens' status)
+    - Idle detection via Stop hook markers in JSONL
+    """
+
+    @property
+    def engine_id(self) -> str:
+        """Return 'claude' as the engine identifier."""
+        return "claude"
+
+    def command(self) -> str:
+        """
+        Return the Claude CLI command.
+
+        Respects CLAUDE_TEAM_COMMAND environment variable for overrides
+        (e.g., "happy" wrapper).
+        """
+        return os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
+
+    def build_args(
+        self,
+        *,
+        dangerously_skip_permissions: bool = False,
+        settings_file: str | None = None,
+    ) -> list[str]:
+        """
+        Build Claude CLI arguments.
+
+        Args:
+            dangerously_skip_permissions: Add --dangerously-skip-permissions
+            settings_file: Path to settings JSON for Stop hook injection
+
+        Returns:
+            List of CLI arguments
+        """
+        args: list[str] = []
+
+        if dangerously_skip_permissions:
+            args.append("--dangerously-skip-permissions")
+
+        # Only add --settings for the default 'claude' command.
+        # Custom commands like 'happy' have their own session tracking mechanisms.
+        # See HAPPY_INTEGRATION_RESEARCH.md for full analysis.
+        if settings_file and self._is_default_command():
+            args.append("--settings")
+            args.append(settings_file)
+
+        return args
+
+    def ready_patterns(self) -> list[str]:
+        """
+        Return patterns indicating Claude TUI is ready.
+
+        These patterns appear in Claude's startup:
+        - '>' prompt indicates input ready
+        - 'tokens' in status bar
+        - Parts of the robot ASCII art banner
+        """
+        return [
+            ">",  # Input prompt
+            "tokens",  # Status bar
+            "Claude Code v",  # Version line in banner
+            "▐▛███▜▌",  # Top of robot head
+            "▝▜█████▛▘",  # Middle of robot
+        ]
+
+    def idle_detection_method(self) -> Literal["stop_hook", "jsonl_stream", "none"]:
+        """
+        Claude uses Stop hook for idle detection.
+
+        A Stop hook writes a marker to the JSONL when Claude finishes responding.
+        """
+        return "stop_hook"
+
+    def supports_settings_file(self) -> bool:
+        """
+        Claude supports --settings for hook injection.
+
+        Only returns True for the default 'claude' command.
+        Custom wrappers may have their own settings mechanisms.
+        """
+        return self._is_default_command()
+
+    def _is_default_command(self) -> bool:
+        """Check if using the default 'claude' command (not a custom wrapper)."""
+        cmd = os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
+        return cmd == "claude"
+
+
+# Singleton instance for convenience
+claude_cli = ClaudeCLI()

claude_team_mcp/cli_backends/codex.py

@@ -0,0 +1,110 @@
+"""
+OpenAI Codex CLI backend.
+
+Implements the AgentCLI protocol for OpenAI's Codex CLI.
+This is a basic implementation - full integration will be done in later tasks.
+
+Codex CLI reference: https://github.com/openai/codex
+"""
+
+import os
+from typing import Literal
+
+from .base import AgentCLI
+
+
+class CodexCLI(AgentCLI):
+    """
+    OpenAI Codex CLI implementation.
+
+    Note: This is a basic structure. Full Codex integration (ready detection,
+    idle detection, etc.) will be implemented in later tasks (cic-f7w.3+).
+
+    Codex CLI characteristics:
+    - Uses `codex` command
+    - Has --full-auto flag for non-interactive mode
+    - No known Stop hook equivalent (may need JSONL streaming or timeouts)
+    """
+
+    @property
+    def engine_id(self) -> str:
+        """Return 'codex' as the engine identifier."""
+        return "codex"
+
+    def command(self) -> str:
+        """
+        Return the Codex CLI command.
+
+        Respects CLAUDE_TEAM_CODEX_COMMAND environment variable for overrides
+        (e.g., "happy codex" wrapper).
+        """
+        return os.environ.get("CLAUDE_TEAM_CODEX_COMMAND", "codex")
+
+    def build_args(
+        self,
+        *,
+        dangerously_skip_permissions: bool = False,
+        settings_file: str | None = None,
+    ) -> list[str]:
+        """
+        Build Codex CLI arguments for interactive mode.
+
+        Args:
+            dangerously_skip_permissions: Maps to --full-auto for Codex
+            settings_file: Ignored - Codex doesn't support settings injection
+
+        Returns:
+            List of CLI arguments for interactive mode
+        """
+        args: list[str] = []
+
+        # Codex uses --dangerously-bypass-approvals-and-sandbox for autonomous operation
+        # (--full-auto doesn't work through happy wrapper)
+        if dangerously_skip_permissions:
+            args.append("--dangerously-bypass-approvals-and-sandbox")
+
+        # Note: settings_file is ignored - Codex doesn't support this
+        # Idle detection uses session file polling instead
+
+        return args
+
+
+    def ready_patterns(self) -> list[str]:
+        """
+        Return patterns indicating Codex CLI is ready for input.
+
+        Codex in interactive mode shows status bar when ready.
+        Updated for Codex CLI v0.80.0 behavior.
+        """
+        return [
+            "context left",  # Status bar shows "100% context left"
+            "for shortcuts",  # Status bar shows "? for shortcuts"
+            "What can I help you with?",  # Legacy prompt (older versions)
+            "codex>",  # Alternative prompt pattern
+            "»",  # Codex uses this prompt symbol
+            "Waiting for messages",  # Happy codex wrapper
+            "Codex Agent Running",  # Happy codex status bar
+        ]
+
+    def idle_detection_method(self) -> Literal["stop_hook", "jsonl_stream", "none"]:
+        """
+        Codex idle detection method.
+
+        Codex writes session files to ~/.codex/sessions/YYYY/MM/DD/.
+        The idle_detection module polls these files for agent_message
+        events which indicate the agent has finished responding.
+        """
+        return "jsonl_stream"
+
+    def supports_settings_file(self) -> bool:
+        """
+        Codex doesn't support --settings for hook injection.
+
+        Alternative completion detection methods will be needed.
+        """
+        return False
+
+
+
+# Singleton instance for convenience
+codex_cli = CodexCLI()

claude_team_mcp/colors.py

@@ -0,0 +1,108 @@
+"""
+Dynamic tab color generation for iTerm2 sessions.
+
+Generates visually distinct colors using the golden ratio for hue distribution,
+ensuring each session gets a unique, easily distinguishable tab color.
+"""
+
+import colorsys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from iterm2.color import Color as ItermColor
+
+
+# Golden ratio conjugate (φ - 1), used for even hue distribution
+GOLDEN_RATIO_CONJUGATE = 0.618033988749895
+
+# Default saturation and lightness values for tab colors (HSL)
+DEFAULT_SATURATION = 0.65  # 65%
+DEFAULT_LIGHTNESS = 0.55   # 55%
+
+
+def generate_tab_color(
+    index: int,
+    saturation: float = DEFAULT_SATURATION,
+    lightness: float = DEFAULT_LIGHTNESS,
+) -> "ItermColor":
+    """
+    Generate a distinct tab color for a given index.
+
+    Uses the golden ratio to distribute hues evenly across the color wheel,
+    ensuring that consecutively spawned sessions have visually distinct colors.
+    The golden ratio approach avoids clustering that can occur with linear
+    hue increments.
+
+    Args:
+        index: The session index (0-based). Each index produces a unique hue.
+        saturation: HSL saturation value (0.0-1.0). Default 0.65 (65%).
+        lightness: HSL lightness value (0.0-1.0). Default 0.55 (55%).
+
+    Returns:
+        iterm2.Color object ready to use with tab color APIs.
+
+    Example:
+        # First session gets a warm orange-red
+        color0 = generate_tab_color(0)
+
+        # Second session gets a contrasting blue-green
+        color1 = generate_tab_color(1)
+
+        # Colors remain visually distinct even for many sessions
+        color10 = generate_tab_color(10)
+    """
+    from iterm2.color import Color
+
+    # Calculate hue using golden ratio distribution
+    # Multiply index by golden ratio conjugate and take fractional part
+    # This distributes hues evenly across the color wheel
+    hue = (index * GOLDEN_RATIO_CONJUGATE) % 1.0
+
+    # Convert HSL to RGB (colorsys uses HLS ordering: hue, lightness, saturation)
+    r, g, b = colorsys.hls_to_rgb(hue, lightness, saturation)
+
+    # iterm2.Color expects integer RGB values 0-255
+    return Color(
+        r=int(r * 255),
+        g=int(g * 255),
+        b=int(b * 255),
+    )
+
+
+def hsl_to_rgb_tuple(
+    hue: float,
+    saturation: float = DEFAULT_SATURATION,
+    lightness: float = DEFAULT_LIGHTNESS,
+) -> tuple[int, int, int]:
+    """
+    Convert HSL values to RGB tuple (0-255 range).
+
+    Utility function for cases where raw RGB values are needed
+    instead of an iterm2.Color object.
+
+    Args:
+        hue: HSL hue value (0.0-1.0)
+        saturation: HSL saturation value (0.0-1.0)
+        lightness: HSL lightness value (0.0-1.0)
+
+    Returns:
+        Tuple of (red, green, blue) integers in 0-255 range.
+    """
+    # colorsys uses HLS (hue, lightness, saturation) ordering
+    r, g, b = colorsys.hls_to_rgb(hue, lightness, saturation)
+    return (int(r * 255), int(g * 255), int(b * 255))
+
+
+def get_hue_for_index(index: int) -> float:
+    """
+    Get the hue value (0.0-1.0) for a given index.
+
+    Useful when you need just the hue for custom color manipulation.
+
+    Args:
+        index: The session index (0-based)
+
+    Returns:
+        Hue value in range 0.0 to 1.0
+    """
+    return (index * GOLDEN_RATIO_CONJUGATE) % 1.0

claude_team_mcp/formatting.py

@@ -0,0 +1,120 @@
+"""
+Formatting utilities for Claude Team MCP.
+
+Provides functions for formatting session titles, badge text, and other
+display strings used in iTerm2 tabs and UI badges.
+"""
+
+from typing import Optional
+
+
+def format_session_title(
+    session_name: str,
+    issue_id: Optional[str] = None,
+    annotation: Optional[str] = None,
+) -> str:
+    """
+    Format a session title for iTerm2 tab display.
+
+    Creates a formatted title string combining session name, optional issue ID,
+    and optional annotation.
+
+    Args:
+        session_name: Session identifier (e.g., "worker-1")
+        issue_id: Optional issue/ticket ID (e.g., "cic-3dj")
+        annotation: Optional task annotation (e.g., "profile module")
+
+    Returns:
+        Formatted title string.
+
+    Examples:
+        >>> format_session_title("worker-1", "cic-3dj", "profile module")
+        '[worker-1] cic-3dj: profile module'
+
+        >>> format_session_title("worker-2", annotation="refactor auth")
+        '[worker-2] refactor auth'
+
+        >>> format_session_title("worker-3")
+        '[worker-3]'
+    """
+    # Build the title in parts
+    title_parts = [f"[{session_name}]"]
+
+    if issue_id and annotation:
+        # Both issue ID and annotation: "issue_id: annotation"
+        title_parts.append(f"{issue_id}: {annotation}")
+    elif issue_id:
+        # Only issue ID
+        title_parts.append(issue_id)
+    elif annotation:
+        # Only annotation
+        title_parts.append(annotation)
+
+    return " ".join(title_parts)
+
+
+def format_badge_text(
+    name: str,
+    bead: Optional[str] = None,
+    annotation: Optional[str] = None,
+    agent_type: Optional[str] = None,
+    max_annotation_length: int = 30,
+) -> str:
+    """
+    Format badge text with bead/name on first line, annotation on second.
+
+    Creates a multi-line string suitable for iTerm2 badge display:
+    - Line 1: Agent type prefix (if not "claude") + bead ID (if provided) or worker name
+    - Line 2: annotation (if provided), truncated if too long
+
+    Args:
+        name: Worker name (used if bead not provided)
+        bead: Optional bead/issue ID (e.g., "cic-3dj")
+        annotation: Optional task annotation
+        agent_type: Optional agent type ("claude" or "codex"). If "codex",
+            adds a prefix to the first line.
+        max_annotation_length: Maximum length for annotation line (default 30)
+
+    Returns:
+        Badge text, potentially multi-line.
+
+    Examples:
+        >>> format_badge_text("Groucho", "cic-3dj", "profile module")
+        'cic-3dj\\nprofile module'
+
+        >>> format_badge_text("Groucho", annotation="quick task")
+        'Groucho\\nquick task'
+
+        >>> format_badge_text("Groucho", "cic-3dj")
+        'cic-3dj'
+
+        >>> format_badge_text("Groucho")
+        'Groucho'
+
+        >>> format_badge_text("Groucho", annotation="a very long annotation here", max_annotation_length=20)
+        'Groucho\\na very long annot...'
+
+        >>> format_badge_text("Groucho", agent_type="codex")
+        '[Codex] Groucho'
+
+        >>> format_badge_text("Groucho", "cic-3dj", agent_type="codex")
+        '[Codex] cic-3dj'
+    """
+    # First line: bead if provided, otherwise name
+    first_line = bead if bead else name
+
+    # Add agent type prefix for non-Claude agents
+    if agent_type and agent_type != "claude":
+        # Capitalize the agent type for display (e.g., "codex" -> "Codex")
+        type_display = agent_type.capitalize()
+        first_line = f"[{type_display}] {first_line}"
+
+    # Second line: annotation if provided, with truncation
+    if annotation:
+        if len(annotation) > max_annotation_length:
+            # Reserve 3 chars for ellipsis
+            truncated = annotation[: max_annotation_length - 3].rstrip()
+            annotation = f"{truncated}..."
+        return f"{first_line}\n{annotation}"
+
+    return first_line