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

claude_team_mcp/config_cli.py

@@ -0,0 +1,263 @@
+"""
+CLI helpers for claude-team configuration commands.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict
+from pathlib import Path
+from collections.abc import Callable, Mapping
+
+from . import config as config_module
+from .config import ClaudeTeamConfig, ConfigError, parse_config
+
+_ALLOWED_AGENT_TYPES = {"claude", "codex"}
+_ALLOWED_LAYOUTS = {"auto", "new"}
+_ALLOWED_TERMINAL_BACKENDS = {"iterm", "tmux"}
+_ALLOWED_ISSUE_TRACKERS = {"beads", "pebbles"}
+
+
+def init_config(
+    *,
+    force: bool = False,
+    config_path: Path | None = None,
+) -> Path:
+    """Write the default config file to disk and return the path."""
+
+    path = _resolve_config_path(config_path)
+    if path.exists() and not force:
+        raise ConfigError(f"Config file already exists: {path}")
+    config = config_module.default_config()
+    return config_module.save_config(config, path)
+
+
+def load_effective_config_data(
+    *,
+    env: Mapping[str, str] | None = None,
+    config_path: Path | None = None,
+) -> dict:
+    """Load config data with environment overrides applied."""
+
+    config = config_module.load_config(config_path)
+    data = asdict(config)
+    _apply_env_overrides(data, env or os.environ)
+    return data
+
+
+def render_config_json(
+    *,
+    env: Mapping[str, str] | None = None,
+    config_path: Path | None = None,
+) -> str:
+    """Render the effective config as formatted JSON."""
+
+    data = load_effective_config_data(env=env, config_path=config_path)
+    return json.dumps(data, indent=2, sort_keys=True)
+
+
+def get_config_value(
+    key: str,
+    *,
+    env: Mapping[str, str] | None = None,
+    config_path: Path | None = None,
+) -> object:
+    """Return a single config value by dotted path."""
+
+    data = load_effective_config_data(env=env, config_path=config_path)
+    return _get_nested_value(data, key)
+
+
+def set_config_value(
+    key: str,
+    raw_value: str,
+    *,
+    config_path: Path | None = None,
+) -> ClaudeTeamConfig:
+    """Set a config value by dotted path, validate, and persist."""
+
+    config = config_module.load_config(config_path)
+    data = asdict(config)
+    parsed_value = _parse_cli_value(key, raw_value)
+    _set_nested_value(data, key, parsed_value)
+    updated = parse_config(data)
+    config_module.save_config(updated, _resolve_config_path(config_path))
+    return updated
+
+
+def format_value_json(value: object) -> str:
+    """Format a single config value as JSON."""
+
+    return json.dumps(value)
+
+
+def _resolve_config_path(config_path: Path | None) -> Path:
+    # Resolve the config path, defaulting to ~/.claude-team/config.json.
+    return (config_path or config_module.CONFIG_PATH).expanduser()
+
+
+def _apply_env_overrides(data: dict, env: Mapping[str, str]) -> None:
+    # Apply env overrides using the same precedence logic as runtime helpers.
+    command_override = env.get("CLAUDE_TEAM_COMMAND")
+    if command_override:
+        data["commands"]["claude"] = command_override
+
+    codex_override = env.get("CLAUDE_TEAM_CODEX_COMMAND")
+    if codex_override:
+        data["commands"]["codex"] = codex_override
+
+    # Terminal backend is a direct override (mirrors select_backend_id).
+    backend_override = env.get("CLAUDE_TEAM_TERMINAL_BACKEND")
+    if backend_override:
+        data["terminal"]["backend"] = backend_override.strip().lower()
+
+    # Issue tracker override mirrors detect_issue_tracker validation.
+    tracker_override = env.get("CLAUDE_TEAM_ISSUE_TRACKER")
+    if tracker_override:
+        normalized = tracker_override.strip().lower()
+        if normalized in _ALLOWED_ISSUE_TRACKERS:
+            data["issue_tracker"]["override"] = normalized
+
+    # Events overrides use integer parsing with graceful fallback.
+    max_size_override = env.get("CLAUDE_TEAM_EVENTS_MAX_SIZE_MB")
+    if max_size_override:
+        parsed = _parse_int_override(max_size_override)
+        if parsed is not None:
+            data["events"]["max_size_mb"] = parsed
+
+    recent_hours_override = env.get("CLAUDE_TEAM_EVENTS_RECENT_HOURS")
+    if recent_hours_override:
+        parsed = _parse_int_override(recent_hours_override)
+        if parsed is not None:
+            data["events"]["recent_hours"] = parsed
+
+
+def _parse_int_override(raw_value: str) -> int | None:
+    # Parse env overrides as integers; invalid values are ignored.
+    try:
+        return int(raw_value)
+    except ValueError:
+        return None
+
+
+def _parse_cli_value(key: str, raw_value: str) -> object:
+    # Parse CLI values according to the config schema.
+    parser = _FIELD_PARSERS.get(key)
+    if parser is None:
+        raise ConfigError(f"Unknown config key: {key}")
+    return parser(raw_value, key)
+
+
+def _parse_optional_string(raw_value: str, field: str) -> str | None:
+    # Parse optional string fields (allows null).
+    if _is_null(raw_value):
+        return None
+    if not raw_value.strip():
+        raise ConfigError(f"{field} cannot be empty")
+    return raw_value
+
+
+def _parse_bool(raw_value: str, field: str) -> bool:
+    # Parse boolean values in JSON-compatible form.
+    normalized = raw_value.strip().lower()
+    if normalized == "true":
+        return True
+    if normalized == "false":
+        return False
+    raise ConfigError(f"{field} must be a boolean")
+
+
+def _parse_int(raw_value: str, field: str) -> int:
+    # Parse integer values with minimum validation.
+    try:
+        value = int(raw_value.strip())
+    except ValueError as exc:
+        raise ConfigError(f"{field} must be an integer") from exc
+    if value < 1:
+        raise ConfigError(f"{field} must be at least 1")
+    return value
+
+
+def _parse_literal(raw_value: str, field: str, allowed: set[str]) -> str:
+    # Parse literal string values constrained to allowed sets.
+    value = raw_value.strip()
+    if value not in allowed:
+        joined = ", ".join(sorted(allowed))
+        raise ConfigError(f"{field} must be one of: {joined}")
+    return value
+
+
+def _parse_optional_literal(
+    raw_value: str,
+    field: str,
+    allowed: set[str],
+) -> str | None:
+    # Parse nullable literal values constrained to allowed sets.
+    if _is_null(raw_value):
+        return None
+    return _parse_literal(raw_value, field, allowed)
+
+
+def _is_null(raw_value: str) -> bool:
+    # Treat "null" as a request to clear optional fields.
+    return raw_value.strip().lower() == "null"
+
+
+def _get_nested_value(data: dict, key: str) -> object:
+    # Retrieve values by dotted path, validating against known keys.
+    if key not in _GET_KEYS:
+        raise ConfigError(f"Unknown config key: {key}")
+    parts = key.split(".")
+    current: object = data
+    for part in parts:
+        if not isinstance(current, dict) or part not in current:
+            raise ConfigError(f"Unknown config key: {key}")
+        current = current[part]
+    return current
+
+
+def _set_nested_value(data: dict, key: str, value: object) -> None:
+    # Assign values by dotted path, ensuring the key exists.
+    parts = key.split(".")
+    current: dict = data
+    for part in parts[:-1]:
+        if part not in current or not isinstance(current[part], dict):
+            raise ConfigError(f"Unknown config key: {key}")
+        current = current[part]
+    leaf = parts[-1]
+    if leaf not in current:
+        raise ConfigError(f"Unknown config key: {key}")
+    current[leaf] = value
+
+
+_FIELD_PARSERS: dict[str, Callable[[str, str], object]] = {
+    "commands.claude": _parse_optional_string,
+    "commands.codex": _parse_optional_string,
+    "defaults.agent_type": lambda value, field: _parse_literal(
+        value,
+        field,
+        _ALLOWED_AGENT_TYPES,
+    ),
+    "defaults.skip_permissions": _parse_bool,
+    "defaults.use_worktree": _parse_bool,
+    "defaults.layout": lambda value, field: _parse_literal(
+        value,
+        field,
+        _ALLOWED_LAYOUTS,
+    ),
+    "terminal.backend": lambda value, field: _parse_optional_literal(
+        value,
+        field,
+        _ALLOWED_TERMINAL_BACKENDS,
+    ),
+    "events.max_size_mb": _parse_int,
+    "events.recent_hours": _parse_int,
+    "issue_tracker.override": lambda value, field: _parse_optional_literal(
+        value,
+        field,
+        _ALLOWED_ISSUE_TRACKERS,
+    ),
+}
+
+_GET_KEYS = set(_FIELD_PARSERS.keys()) | {"version"}

claude_team_mcp/issue_tracker/__init__.py

@@ -9,10 +9,16 @@ from __future__ import annotations
 import logging
 import os
 from dataclasses import dataclass, field
-from typing import Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from claude_team_mcp.config import ClaudeTeamConfig
 
 logger = logging.getLogger("claude-team-mcp")
 
+# Environment variable for explicit tracker override (highest priority).
+ISSUE_TRACKER_ENV_VAR = "CLAUDE_TEAM_ISSUE_TRACKER"
+
 
 @runtime_checkable
 class IssueTrackerBackend(Protocol):
@@ -86,16 +92,74 @@ BACKEND_REGISTRY: dict[str, IssueTrackerBackend] = {
 }
 
 
-def detect_issue_tracker(project_path: str) -> IssueTrackerBackend | None:
+def detect_issue_tracker(
+    project_path: str,
+    config: ClaudeTeamConfig | None = None,
+) -> IssueTrackerBackend | None:
     """
     Detect the issue tracker backend for the given project path.
 
+    Resolution order (highest to lowest priority):
+      1. CLAUDE_TEAM_ISSUE_TRACKER environment variable
+      2. config.issue_tracker.override setting
+      3. Marker directory detection (.pebbles, .beads)
+
     Args:
         project_path: Absolute or relative path to the project root.
+        config: Optional config object. If None, config is loaded from disk.
 
     Returns:
-        The detected IssueTrackerBackend, or None if no markers are present.
+        The detected IssueTrackerBackend, or None if no tracker is configured
+        or detected.
     """
+    # Priority 1: Environment variable override.
+    env_override = os.environ.get(ISSUE_TRACKER_ENV_VAR)
+    if env_override:
+        backend = BACKEND_REGISTRY.get(env_override.lower())
+        if backend:
+            logger.debug(
+                "Using issue tracker '%s' from %s env var",
+                backend.name,
+                ISSUE_TRACKER_ENV_VAR,
+            )
+            return backend
+        logger.warning(
+            "Unknown issue tracker '%s' in %s; ignoring",
+            env_override,
+            ISSUE_TRACKER_ENV_VAR,
+        )
+
+    # Priority 2: Config file override.
+    if config is None:
+        # Lazy import to avoid circular dependency at module load time.
+        try:
+            from claude_team_mcp.config import ConfigError, load_config
+
+            config = load_config()
+        except ConfigError as exc:
+            logger.warning("Invalid config file; ignoring overrides: %s", exc)
+            config = None
+
+    if config and config.issue_tracker.override:
+        backend = BACKEND_REGISTRY.get(config.issue_tracker.override)
+        if backend:
+            logger.debug(
+                "Using issue tracker '%s' from config override",
+                backend.name,
+            )
+            return backend
+        # Config validation should prevent this, but handle gracefully.
+        logger.warning(
+            "Unknown issue tracker '%s' in config; ignoring",
+            config.issue_tracker.override,
+        )
+
+    # Priority 3: Marker directory detection.
+    return _detect_from_markers(project_path)
+
+
+def _detect_from_markers(project_path: str) -> IssueTrackerBackend | None:
+    """Detect issue tracker by checking for marker directories."""
     beads_marker = os.path.join(project_path, BEADS_BACKEND.marker_dir)
     pebbles_marker = os.path.join(project_path, PEBBLES_BACKEND.marker_dir)
 
@@ -128,5 +192,6 @@ __all__ = [
     "BEADS_BACKEND",
     "PEBBLES_BACKEND",
     "BACKEND_REGISTRY",
+    "ISSUE_TRACKER_ENV_VAR",
     "detect_issue_tracker",
 ]

claude_team_mcp/server.py

@@ -398,8 +398,10 @@ def run_server(transport: str = "stdio", port: int = 8766):
 def main():
     """CLI entry point with argument parsing."""
     import argparse
+    import sys
 
     parser = argparse.ArgumentParser(description="Claude Team MCP Server")
+    # Global server options apply when no subcommand is provided.
     parser.add_argument(
         "--http",
         action="store_true",
@@ -411,9 +413,76 @@ def main():
         default=8766,
         help="Port for HTTP mode (default: 8766)",
     )
+    # Config subcommands for reading/writing ~/.claude-team/config.json.
+    subparsers = parser.add_subparsers(dest="command")
+
+    config_parser = subparsers.add_parser(
+        "config",
+        help="Manage claude-team configuration",
+    )
+    config_subparsers = config_parser.add_subparsers(dest="config_command")
+
+    init_parser = config_subparsers.add_parser(
+        "init",
+        help="Write default config to disk",
+    )
+    init_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing config file",
+    )
+
+    config_subparsers.add_parser(
+        "show",
+        help="Show effective config (file + env overrides)",
+    )
+
+    get_parser = config_subparsers.add_parser(
+        "get",
+        help="Get a single config value by dotted path",
+    )
+    get_parser.add_argument("key", help="Dotted config key (e.g. defaults.layout)")
+
+    set_parser = config_subparsers.add_parser(
+        "set",
+        help="Set a single config value by dotted path",
+    )
+    set_parser.add_argument("key", help="Dotted config key (e.g. defaults.layout)")
+    set_parser.add_argument("value", help="Value to set")
 
     args = parser.parse_args()
 
+    # Handle config subcommands early to avoid starting the server.
+    if args.command == "config":
+        from .config import ConfigError
+        from .config_cli import (
+            format_value_json,
+            get_config_value,
+            init_config,
+            render_config_json,
+            set_config_value,
+        )
+
+        try:
+            if args.config_command == "init":
+                path = init_config(force=args.force)
+                print(path)
+            elif args.config_command == "show":
+                print(render_config_json())
+            elif args.config_command == "get":
+                value = get_config_value(args.key)
+                print(format_value_json(value))
+            elif args.config_command == "set":
+                set_config_value(args.key, args.value)
+            else:
+                config_parser.print_help()
+                raise SystemExit(2)
+        except ConfigError as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            raise SystemExit(1) from exc
+        return
+
+    # Default behavior: run the MCP server.
     if args.http:
         run_server(transport="streamable-http", port=args.port)
     else:

claude_team_mcp/terminal_backends/__init__.py

@@ -2,18 +2,36 @@
 
 from __future__ import annotations
 
+import logging
 import os
 from typing import Mapping
 
+from ..config import ClaudeTeamConfig, ConfigError, load_config
 from .base import TerminalBackend, TerminalSession
 from .iterm import ItermBackend, MAX_PANES_PER_TAB
 from .tmux import TmuxBackend
 
+logger = logging.getLogger("claude-team-mcp")
 
-def select_backend_id(env: Mapping[str, str] | None = None) -> str:
-    """Select a terminal backend id based on environment configuration."""
-    environ = env or os.environ
+
+def select_backend_id(
+    env: Mapping[str, str] | None = None,
+    config: ClaudeTeamConfig | None = None,
+) -> str:
+    """Select a terminal backend id based on environment and config."""
+    environ = os.environ if env is None else env
     configured = environ.get("CLAUDE_TEAM_TERMINAL_BACKEND")
+    if configured:
+        return configured.strip().lower()
+    if config is None:
+        try:
+            config = load_config()
+        except ConfigError as exc:
+            logger.warning(
+                "Invalid config file; ignoring terminal backend override: %s", exc
+            )
+            config = None
+    configured = config.terminal.backend if config else None
     if configured:
         return configured.strip().lower()
     if environ.get("TMUX"):

claude_team_mcp/terminal_backends/tmux.py

@@ -7,6 +7,7 @@ Provides a TerminalBackend implementation backed by tmux CLI commands.
 from __future__ import annotations
 
 import asyncio
+import hashlib
 import re
 import subprocess
 import uuid
@@ -44,7 +45,11 @@ ISSUE_ID_PATTERN = re.compile(r"\b[A-Za-z][A-Za-z0-9]*-[A-Za-z0-9]*\d[A-Za-z0-9]
 
 SHELL_READY_MARKER = "CLAUDE_TEAM_READY_7f3a9c"
 CODEX_PRE_ENTER_DELAY = 0.5
-TMUX_SESSION_NAME = "claude-team"
+TMUX_SESSION_PREFIX = "claude-team"
+TMUX_SESSION_HASH_LEN = 8
+TMUX_SESSION_SLUG_MAX = 32
+TMUX_SESSION_FALLBACK = "project"
+TMUX_SESSION_PREFIXED = f"{TMUX_SESSION_PREFIX}-"
 
 LAYOUT_PANE_NAMES = {
     "single": ["main"],
@@ -62,6 +67,47 @@ LAYOUT_SELECT = {
 }
 
 
+# Normalize a project name into a tmux-safe slug.
+def _tmux_safe_slug(value: str) -> str:
+    slug = re.sub(r"[^A-Za-z0-9_-]+", "-", value.strip())
+    slug = slug.strip("-_")
+    if not slug:
+        return TMUX_SESSION_FALLBACK
+    if len(slug) > TMUX_SESSION_SLUG_MAX:
+        slug = slug[:TMUX_SESSION_SLUG_MAX].rstrip("-_")
+    return slug or TMUX_SESSION_FALLBACK
+
+
+def project_name_from_path(project_path: str | None) -> str | None:
+    """Return a display name for a project path, handling worktree paths."""
+    if not project_path:
+        return None
+    path = Path(project_path)
+    parts = path.parts
+    if ".worktrees" in parts:
+        worktrees_index = parts.index(".worktrees")
+        if worktrees_index > 0:
+            return parts[worktrees_index - 1]
+    return path.name
+
+
+def tmux_session_name_for_project(project_path: str | None) -> str:
+    """Return the per-project tmux session name for a given project path."""
+    project_name = project_name_from_path(project_path) or TMUX_SESSION_FALLBACK
+    slug = _tmux_safe_slug(project_name)
+    if project_path:
+        digest_source = project_path
+    else:
+        digest_source = uuid.uuid4().hex
+    digest = hashlib.sha1(digest_source.encode("utf-8")).hexdigest()[:TMUX_SESSION_HASH_LEN]
+    return f"{TMUX_SESSION_PREFIXED}{slug}-{digest}"
+
+
+# Determine whether a tmux session is managed by claude-team.
+def _is_managed_session_name(session_name: str) -> bool:
+    return session_name.startswith(TMUX_SESSION_PREFIXED)
+
+
 class TmuxBackend(TerminalBackend):
     """Terminal backend adapter for tmux."""
 
@@ -94,23 +140,24 @@ class TmuxBackend(TerminalBackend):
         profile: str | None = None,
         profile_customizations: Any | None = None,
     ) -> TerminalSession:
-        """Create a worker window in the claude-team tmux session."""
+        """Create a worker window in a per-project tmux session."""
         if profile or profile_customizations:
             raise ValueError("tmux backend does not support profiles")
 
         base_name = name or self._generate_window_name()
-        project_name = self._project_name_from_path(project_path)
+        project_name = project_name_from_path(project_path)
         resolved_issue_id = self._resolve_issue_id(issue_id, coordinator_annotation)
         window_name = self._format_window_name(base_name, project_name, resolved_issue_id)
+        session_name = tmux_session_name_for_project(project_path)
 
         # Ensure the dedicated session exists, then create a new window for this worker.
         try:
-            await self._run_tmux(["has-session", "-t", TMUX_SESSION_NAME])
+            await self._run_tmux(["has-session", "-t", session_name])
             output = await self._run_tmux(
                 [
                     "new-window",
                     "-t",
-                    TMUX_SESSION_NAME,
+                    session_name,
                     "-n",
                     window_name,
                     "-P",
@@ -124,7 +171,7 @@ class TmuxBackend(TerminalBackend):
                     "new-session",
                     "-d",
                     "-s",
-                    TMUX_SESSION_NAME,
+                    session_name,
                     "-n",
                     window_name,
                     "-P",
@@ -138,7 +185,7 @@ class TmuxBackend(TerminalBackend):
             raise RuntimeError("Failed to determine tmux pane id for new window")
 
         metadata = {
-            "session_name": TMUX_SESSION_NAME,
+            "session_name": session_name,
             "window_id": window_id,
             "window_index": window_index,
             "window_name": window_name,
@@ -295,13 +342,12 @@ class TmuxBackend(TerminalBackend):
         return panes
 
     async def list_sessions(self) -> list[TerminalSession]:
-        """List all tmux panes in the claude-team session."""
+        """List all tmux panes in claude-team-managed sessions."""
         try:
             output = await self._run_tmux(
                 [
                     "list-panes",
-                    "-t",
-                    TMUX_SESSION_NAME,
+                    "-a",
                     "-F",
                     "#{session_name}\t#{window_id}\t#{window_name}\t#{window_index}\t#{pane_index}\t#{pane_id}",
                 ]
@@ -320,6 +366,8 @@ class TmuxBackend(TerminalBackend):
             if len(parts) != 6:
                 continue
             session_name, window_id, window_name, window_index, pane_index, pane_id = parts
+            if not _is_managed_session_name(session_name):
+                continue
             sessions.append(
                 TerminalSession(
                     backend_id=self.backend_id,
@@ -349,8 +397,7 @@ class TmuxBackend(TerminalBackend):
             output = await self._run_tmux(
                 [
                     "list-panes",
-                    "-t",
-                    TMUX_SESSION_NAME,
+                    "-a",
                     "-F",
                     "#{session_name}\t#{window_id}\t#{window_index}\t#{pane_index}\t#{pane_active}\t#{pane_id}",
                 ]
@@ -368,6 +415,8 @@ class TmuxBackend(TerminalBackend):
             if len(parts) != 6:
                 continue
             session_name, window_id, window_index, pane_index, pane_active, pane_id = parts
+            if not _is_managed_session_name(session_name):
+                continue
             panes_by_window.setdefault((session_name, window_id, window_index), []).append(
                 {
                     "pane_id": pane_id,
@@ -576,18 +625,6 @@ class TmuxBackend(TerminalBackend):
 
         return False
 
-    # Extract a display name for the project from a project path.
-    def _project_name_from_path(self, project_path: str | None) -> str | None:
-        if not project_path:
-            return None
-        path = Path(project_path)
-        parts = path.parts
-        if ".worktrees" in parts:
-            worktrees_index = parts.index(".worktrees")
-            if worktrees_index > 0:
-                return parts[worktrees_index - 1]
-        return path.name
-
     # Resolve an issue id from explicit input or a coordinator annotation.
     def _resolve_issue_id(
         self,

claude_team_mcp/tools/discover_workers.py

@@ -43,7 +43,7 @@ def register_tools(mcp: FastMCP, ensure_connection) -> None:
         by claude-team write their terminal IDs into the JSONL
         (e.g., <!claude-team-iterm:UUID!> or <!claude-team-tmux:%1!>), enabling
         reliable detection and recovery after MCP server restarts.
-        For tmux, only panes in the shared "claude-team" session are scanned.
+        For tmux, only panes in claude-team-managed sessions are scanned.
 
         Only JSONL files modified within max_age seconds are checked. If a session
         was started more than max_age seconds ago and hasn't had recent activity,