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

claude_team_mcp/cli_backends/codex.py

@@ -58,10 +58,9 @@ class CodexCLI(AgentCLI):
         """
         args: list[str] = []
 
-        # Codex uses --dangerously-bypass-approvals-and-sandbox for autonomous operation
-        # (--full-auto doesn't work through happy wrapper)
+        # Codex uses --full-auto for autonomous operation.
         if dangerously_skip_permissions:
-            args.append("--dangerously-bypass-approvals-and-sandbox")
+            args.append("--full-auto")
 
         # Note: settings_file is ignored - Codex doesn't support this
         # Idle detection uses session file polling instead

claude_team_mcp/issue_tracker/__init__.py

@@ -0,0 +1,132 @@
+"""
+Issue tracker abstraction module.
+
+Defines a protocol and backend implementations for issue tracker commands.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+logger = logging.getLogger("claude-team-mcp")
+
+
+@runtime_checkable
+class IssueTrackerBackend(Protocol):
+    """
+    Protocol defining the issue tracker backend interface.
+
+    Backends provide a name, CLI command, marker directory, and command templates.
+    """
+
+    name: str
+    cli: str
+    marker_dir: str
+    commands: dict[str, str]
+
+
+@dataclass(frozen=True)
+class BeadsBackend:
+    """Beads issue tracker backend."""
+
+    name: str = "beads"
+    cli: str = "bd"
+    marker_dir: str = ".beads"
+    commands: dict[str, str] = field(
+        default_factory=lambda: {
+            "list": "bd --no-db list",
+            "ready": "bd --no-db ready",
+            "show": "bd --no-db show {issue_id}",
+            "update": "bd --no-db update {issue_id} --status {status}",
+            "close": "bd --no-db close {issue_id}",
+            "create": (
+                "bd --no-db create --title \"{title}\" --type {type} "
+                "--priority {priority} --description \"{description}\""
+            ),
+            "comment": "bd --no-db comment {issue_id} \"{comment}\"",
+            "dep_add": "bd --no-db dep add {issue_id} {dependency_id}",
+            "dep_tree": "bd --no-db dep tree {issue_id}",
+        }
+    )
+
+
+@dataclass(frozen=True)
+class PebblesBackend:
+    """Pebbles issue tracker backend."""
+
+    name: str = "pebbles"
+    cli: str = "pb"
+    marker_dir: str = ".pebbles"
+    commands: dict[str, str] = field(
+        default_factory=lambda: {
+            "list": "pb list",
+            "ready": "pb ready",
+            "show": "pb show {issue_id}",
+            "update": "pb update {issue_id} -status {status}",
+            "close": "pb close {issue_id}",
+            "create": (
+                "pb create -title \"{title}\" -type {type} -priority {priority} "
+                "-description \"{description}\""
+            ),
+            "comment": "pb comment {issue_id} -body \"{comment}\"",
+            "dep_add": "pb dep add {issue_id} {dependency_id}",
+            "dep_tree": "pb dep tree {issue_id}",
+        }
+    )
+
+
+BEADS_BACKEND = BeadsBackend()
+PEBBLES_BACKEND = PebblesBackend()
+BACKEND_REGISTRY: dict[str, IssueTrackerBackend] = {
+    BEADS_BACKEND.name: BEADS_BACKEND,
+    PEBBLES_BACKEND.name: PEBBLES_BACKEND,
+}
+
+
+def detect_issue_tracker(project_path: str) -> IssueTrackerBackend | None:
+    """
+    Detect the issue tracker backend for the given project path.
+
+    Args:
+        project_path: Absolute or relative path to the project root.
+
+    Returns:
+        The detected IssueTrackerBackend, or None if no markers are present.
+    """
+    beads_marker = os.path.join(project_path, BEADS_BACKEND.marker_dir)
+    pebbles_marker = os.path.join(project_path, PEBBLES_BACKEND.marker_dir)
+
+    # Check marker directories in the project root.
+    beads_present = os.path.isdir(beads_marker)
+    pebbles_present = os.path.isdir(pebbles_marker)
+
+    # Resolve the deterministic backend when both markers exist.
+    if beads_present and pebbles_present:
+        logger.warning(
+            "Both .beads and .pebbles found in %s; defaulting to pebbles",
+            project_path,
+        )
+        return PEBBLES_BACKEND
+
+    # Return the matching backend if only one marker exists.
+    if pebbles_present:
+        return PEBBLES_BACKEND
+
+    if beads_present:
+        return BEADS_BACKEND
+
+    return None
+
+
+__all__ = [
+    "IssueTrackerBackend",
+    "BeadsBackend",
+    "PebblesBackend",
+    "BEADS_BACKEND",
+    "PEBBLES_BACKEND",
+    "BACKEND_REGISTRY",
+    "detect_issue_tracker",
+]

claude_team_mcp/tools/__init__.py

@@ -8,7 +8,7 @@ from mcp.server.fastmcp import FastMCP
 
 from . import adopt_worker
 from . import annotate_worker
-from . import bd_help
+from . import issue_tracker_help
 from . import check_idle_workers
 from . import close_workers
 from . import discover_workers
@@ -31,7 +31,7 @@ def register_all_tools(mcp: FastMCP, ensure_connection) -> None:
     """
     # Tools that don't need ensure_connection
     annotate_worker.register_tools(mcp)
-    bd_help.register_tools(mcp)
+    issue_tracker_help.register_tools(mcp)
     check_idle_workers.register_tools(mcp)
     close_workers.register_tools(mcp)
     examine_worker.register_tools(mcp)

claude_team_mcp/tools/issue_tracker_help.py

@@ -0,0 +1,50 @@
+"""
+Issue tracker help tool.
+
+Provides issue_tracker_help for quick reference on issue tracking commands.
+"""
+
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+from ..issue_tracker import BACKEND_REGISTRY, detect_issue_tracker
+from ..utils import build_issue_tracker_help_text, build_issue_tracker_quick_commands
+
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register issue_tracker_help tool on the MCP server."""
+
+    @mcp.tool()
+    async def issue_tracker_help() -> dict:
+        """
+        Get a quick reference guide for using issue tracking.
+
+        Returns condensed documentation on tracker commands, workflow patterns,
+        and best practices for worker sessions. Call this tool when you need
+        guidance on tracking progress, adding comments, or managing issues.
+
+        Returns:
+            Dict with help text and key command examples
+        """
+        project_path = str(Path.cwd())
+        backend = detect_issue_tracker(project_path)
+        help_text = build_issue_tracker_help_text(backend)
+        quick_commands = build_issue_tracker_quick_commands(backend)
+
+        response = {
+            "help": help_text,
+            "quick_commands": quick_commands,
+            "worker_tip": (
+                "As a worker, add comments to track progress rather than closing issues. "
+                "The coordinator will close issues after reviewing your work."
+            ),
+        }
+
+        if backend is None:
+            response["supported_trackers"] = sorted(BACKEND_REGISTRY.keys())
+        else:
+            response["tracker"] = backend.name
+            response["cli"] = backend.cli
+
+        return response

claude_team_mcp/tools/message_workers.py

@@ -19,9 +19,10 @@ from ..idle_detection import (
     wait_for_any_idle as wait_for_any_idle_impl,
     SessionInfo,
 )
+from ..issue_tracker import detect_issue_tracker
 from ..iterm_utils import send_prompt_for_agent
 from ..registry import SessionStatus
-from ..utils import error_response, HINTS, WORKER_MESSAGE_HINT
+from ..utils import build_worker_message_hint, error_response, HINTS
 
 logger = logging.getLogger("claude-team-mcp")
 
@@ -187,8 +188,14 @@ def register_tools(mcp: FastMCP) -> None:
                 # Update status to busy
                 registry.update_status(sid, SessionStatus.BUSY)
 
-                # Append hint about bd_help tool to help workers understand beads
-                message_with_hint = message + WORKER_MESSAGE_HINT
+                # Append tracker-specific hint so workers know how to log progress.
+                tracker_path = (
+                    str(session.main_repo_path)
+                    if session.main_repo_path is not None
+                    else session.project_path
+                )
+                tracker_backend = detect_issue_tracker(tracker_path)
+                message_with_hint = message + build_worker_message_hint(tracker_backend)
 
                 # Send the message using agent-specific input handling.
                 # Codex needs a longer pre-Enter delay than Claude.

claude_team_mcp/tools/spawn_workers.py

@@ -23,6 +23,7 @@ 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,
@@ -32,7 +33,7 @@ from ..iterm_utils import (
 from ..names import pick_names_for_count
 from ..profile import apply_appearance_colors
 from ..registry import SessionStatus
-from ..utils import HINTS, error_response, get_worktree_beads_dir
+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
 
@@ -324,76 +325,140 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
             if layout == "auto":
                 # Try to find an existing window where the ENTIRE batch fits.
                 # This keeps spawn batches together rather than spreading across windows.
-                managed_iterm_ids: set[str] = {
-                    s.iterm_session.session_id
-                    for s in registry.list_all()
-                    if s.iterm_session is not None
-                }
-
-                # Find a window with enough space for ALL workers
-                result = await find_available_window(
-                    app,
-                    max_panes=MAX_PANES_PER_TAB,
-                    managed_session_ids=managed_iterm_ids,
-                )
-
                 target_tab = None
                 initial_pane_count = 0
                 first_session = None  # Session to split from
 
-                if result:
-                    window, tab, existing_session = result
-                    initial_pane_count = len(tab.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
-                        logger.debug(
-                            f"Batch of {worker_count} fits in existing window "
-                            f"({initial_pane_count} panes, {available_slots} slots)"
+                # Prefer the coordinator's window when running inside iTerm2.
+                # ITERM_SESSION_ID format is "wXtYpZ:UUID" - extract just the UUID.
+                iterm_session_env = os.environ.get("ITERM_SESSION_ID")
+                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:
+                            break
+
+                    if coordinator_session and coordinator_tab:
+                        coordinator_window = await get_window_for_session(
+                            app, coordinator_session
                         )
+                        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
+                        for s in registry.list_all()
+                        if s.iterm_session is not None
+                    }
+
+                    # Find a window with enough space for ALL workers
+                    result = await find_available_window(
+                        app,
+                        max_panes=MAX_PANES_PER_TAB,
+                        managed_session_ids=managed_iterm_ids,
+                    )
+
+                    if result:
+                        window, tab, existing_session = result
+                        initial_pane_count = len(tab.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
+                            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)
                     local_pane_count = initial_pane_count
-                    # Track created sessions for quad splitting
+                    final_pane_count = initial_pane_count + worker_count
+                    # Track created sessions for splitting
                     created_sessions: list = []
 
                     for i in range(worker_count):
-                        # Determine split direction based on local_pane_count
-                        # Incremental quad: TL→TR(vsplit)→BL(hsplit)→BR(hsplit)
-                        if local_pane_count == 1:
-                            # First split: vertical (left/right)
-                            new_session = await split_pane(
-                                first_session,
-                                vertical=True,
-                                before=False,
-                                profile=None,
-                                profile_customizations=profile_customizations[i],
-                            )
-                        elif local_pane_count == 2:
-                            # Second split: horizontal from left pane (creates bottom-left)
-                            # Use first_session (the original TL pane)
-                            new_session = await split_pane(
-                                first_session,
-                                vertical=False,
-                                before=False,
-                                profile=None,
-                                profile_customizations=profile_customizations[i],
-                            )
-                        else:  # local_pane_count == 3
-                            # Third split: horizontal from right pane (creates bottom-right)
-                            # The TR pane is the first one we created
-                            tr_session = created_sessions[0] if created_sessions else first_session
-                            new_session = await split_pane(
-                                tr_session,
-                                vertical=False,
-                                before=False,
-                                profile=None,
-                                profile_customizations=profile_customizations[i],
-                            )
+                        # Choose layout strategy based on final pane count:
+                        # - 3 panes: coordinator full left, workers stacked right
+                        # - 4 panes: quad (TL→TR→BL→BR)
+                        if final_pane_count == 3:
+                            # Layout: coordinator | worker1
+                            #                    |--------
+                            #                    | worker2
+                            if local_pane_count == 1:
+                                # First split: vertical from coordinator
+                                new_session = await split_pane(
+                                    first_session,
+                                    vertical=True,
+                                    before=False,
+                                    profile=None,
+                                    profile_customizations=profile_customizations[i],
+                                )
+                            else:
+                                # Second split: horizontal from first worker (stack on right)
+                                new_session = await split_pane(
+                                    created_sessions[0],
+                                    vertical=False,
+                                    before=False,
+                                    profile=None,
+                                    profile_customizations=profile_customizations[i],
+                                )
+                        else:
+                            # Quad pattern: TL→TR(vsplit)→BL(hsplit)→BR(hsplit)
+                            if local_pane_count == 1:
+                                # First split: vertical (left/right)
+                                new_session = await split_pane(
+                                    first_session,
+                                    vertical=True,
+                                    before=False,
+                                    profile=None,
+                                    profile_customizations=profile_customizations[i],
+                                )
+                            elif local_pane_count == 2:
+                                # Second split: horizontal from left pane (bottom-left)
+                                new_session = await split_pane(
+                                    first_session,
+                                    vertical=False,
+                                    before=False,
+                                    profile=None,
+                                    profile_customizations=profile_customizations[i],
+                                )
+                            else:  # local_pane_count == 3
+                                # Third split: horizontal from right pane (bottom-right)
+                                tr_session = (
+                                    created_sessions[0] if created_sessions else first_session
+                                )
+                                new_session = await split_pane(
+                                    tr_session,
+                                    vertical=False,
+                                    before=False,
+                                    profile=None,
+                                    profile_customizations=profile_customizations[i],
+                                )
 
                         pane_sessions.append(new_session)
                         created_sessions.append(new_session)
@@ -476,9 +541,13 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                 marker_id = session_ids[index]
                 agent_type = agent_types[index]
 
-                # Check for worktree and set BEADS_DIR if needed
-                beads_dir = get_worktree_beads_dir(project_path)
-                env = {"BEADS_DIR": beads_dir} if beads_dir else None
+                # Check for worktree and set tracker env var if needed.
+                tracker_info = get_worktree_tracker_dir(project_path)
+                if tracker_info:
+                    env_var, tracker_dir = tracker_info
+                    env = {env_var: tracker_dir}
+                else:
+                    env = None
 
                 if agent_type == "codex":
                     # Start Codex in interactive mode using start_agent_in_session
@@ -560,12 +629,18 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
                 if not bead and not custom_prompt:
                     workers_awaiting_task.append(managed.name)
 
+                tracker_path = (
+                    str(managed.main_repo_path)
+                    if managed.main_repo_path is not None
+                    else managed.project_path
+                )
                 worker_prompt = generate_worker_prompt(
                     managed.session_id,
                     resolved_names[i],
                     agent_type=managed.agent_type,
                     use_worktree=use_worktree,
                     bead=bead,
+                    project_path=tracker_path,
                     custom_prompt=custom_prompt,
                 )
 

claude_team_mcp/utils/__init__.py

@@ -2,16 +2,24 @@
 Shared utilities for Claude Team MCP tools.
 """
 
-from .constants import BEADS_HELP_TEXT, CONVERSATION_PAGE_SIZE, WORKER_MESSAGE_HINT
+from .constants import (
+    CONVERSATION_PAGE_SIZE,
+    ISSUE_TRACKER_HELP_TOOL,
+    build_issue_tracker_help_text,
+    build_issue_tracker_quick_commands,
+    build_worker_message_hint,
+)
 from .errors import error_response, HINTS, get_session_or_error
-from .worktree_detection import get_worktree_beads_dir
+from .worktree_detection import get_worktree_tracker_dir
 
 __all__ = [
-    "BEADS_HELP_TEXT",
     "CONVERSATION_PAGE_SIZE",
-    "WORKER_MESSAGE_HINT",
+    "ISSUE_TRACKER_HELP_TOOL",
+    "build_issue_tracker_help_text",
+    "build_issue_tracker_quick_commands",
+    "build_worker_message_hint",
     "error_response",
     "HINTS",
     "get_session_or_error",
-    "get_worktree_beads_dir",
+    "get_worktree_tracker_dir",
 ]