claude-team-mcp 0.3.0__tar.gz → 0.3.2__tar.gz

claude_team_mcp-0.3.2/.beads/.local_version

@@ -0,0 +1 @@
+0.44.0

claude_team_mcp-0.3.2/.beads/daemon.lock

@@ -0,0 +1,7 @@
+{
+  "pid": 48335,
+  "parent_pid": 48323,
+  "database": "/Users/phaedrus/Projects/claude-team/.beads/beads.db",
+  "version": "0.44.0",
+  "started_at": "2026-01-07T00:04:00.114512Z"
+}

{claude_team_mcp-0.3.0 → claude_team_mcp-0.3.2}/.beads/daemon.log

@@ -10610,3 +10610,33 @@ time=2026-01-05T13:59:42.898-08:00 level=INFO msg="Git HEAD change detected: %s"
 time=2026-01-05T13:59:43.901-08:00 level=INFO msg="Import triggered by file change"
 time=2026-01-05T13:59:43.901-08:00 level=INFO msg="Starting %s..." !BADKEY=auto-import
 time=2026-01-05T13:59:43.903-08:00 level=INFO msg="Skipping %s: JSONL content unchanged" !BADKEY=auto-import
+time=2026-01-05T14:16:19.112-08:00 level=INFO msg="Received signal %v, shutting down..." !BADKEY=terminated
+time=2026-01-06T16:04:00.127-08:00 level=INFO msg="Daemon started (interval: %v, auto-commit: %v, auto-push: %v)" !BADKEY=5s !BADKEY=false !BADKEY=false
+time=2026-01-06T16:04:00.128-08:00 level=INFO msg="using database" path=/Users/phaedrus/Projects/claude-team/.beads/beads.db
+time=2026-01-06T16:04:00.133-08:00 level=INFO msg="database opened" path=/Users/phaedrus/Projects/claude-team/.beads/beads.db freshness_checking=true
+time=2026-01-06T16:04:00.133-08:00 level=INFO msg="upgrading .beads/.gitignore"
+time=2026-01-06T16:04:00.133-08:00 level=WARN msg="failed to upgrade .gitignore" error="open .beads/.gitignore: no such file or directory"
+time=2026-01-06T16:04:00.137-08:00 level=INFO msg="Repository fingerprint validated: %s" !BADKEY=d0d96a12
+time=2026-01-06T16:04:00.137-08:00 level=WARN msg="database schema version mismatch" db_version=0.41.0 daemon_version=0.44.0
+time=2026-01-06T16:04:00.137-08:00 level=INFO msg="auto-upgrading database to daemon version"
+time=2026-01-06T16:04:00.137-08:00 level=INFO msg="database version updated" version=0.44.0
+time=2026-01-06T16:04:00.138-08:00 level=INFO msg="starting RPC server" socket=/Users/phaedrus/Projects/claude-team/.beads/bd.sock
+time=2026-01-06T16:04:00.138-08:00 level=INFO msg="RPC server ready (socket listening)"
+time=2026-01-06T16:04:00.143-08:00 level=INFO msg="registered in global registry"
+time=2026-01-06T16:04:00.143-08:00 level=INFO msg="Starting %s..." !BADKEY="sync cycle"
+time=2026-01-06T16:04:00.151-08:00 level=INFO msg="Exported to JSONL"
+time=2026-01-06T16:04:01.700-08:00 level=INFO msg="Pulled sync branch %s" !BADKEY=beads-sync
+time=2026-01-06T16:04:01.701-08:00 level=INFO msg="Synced JSONL from sync branch to main repo"
+time=2026-01-06T16:04:01.731-08:00 level=INFO msg="Imported from JSONL"
+time=2026-01-06T16:04:01.742-08:00 level=INFO msg="Sync cycle complete"
+time=2026-01-06T16:04:01.743-08:00 level=INFO msg="monitoring parent process" pid=0
+time=2026-01-06T16:04:01.743-08:00 level=INFO msg="using event-driven mode"
+time=2026-01-06T16:04:01.743-08:00 level=INFO msg="Auto-pull disabled: use 'git pull' manually to sync remote changes"
+time=2026-01-06T16:04:01.812-08:00 level=INFO msg="File change detected: %s" !BADKEY=/Users/phaedrus/Projects/claude-team/.beads/issues.jsonl
+time=2026-01-06T16:04:02.973-08:00 level=INFO msg="Import triggered by file change"
+time=2026-01-06T16:04:02.974-08:00 level=INFO msg="Starting %s..." !BADKEY=auto-import
+time=2026-01-06T16:04:02.974-08:00 level=INFO msg="Skipping %s: JSONL content unchanged" !BADKEY=auto-import
+time=2026-01-06T16:04:06.349-08:00 level=INFO msg="File change detected: %s" !BADKEY=/Users/phaedrus/Projects/claude-team/.beads/issues.jsonl
+time=2026-01-06T16:04:07.351-08:00 level=INFO msg="Import triggered by file change"
+time=2026-01-06T16:04:07.352-08:00 level=INFO msg="Starting %s..." !BADKEY=auto-import
+time=2026-01-06T16:04:07.352-08:00 level=INFO msg="Skipping %s: JSONL content unchanged" !BADKEY=auto-import

claude_team_mcp-0.3.2/.beads/daemon.pid

@@ -0,0 +1 @@
+48335

claude_team_mcp-0.3.2/HAPPY_INTEGRATION_RESEARCH.md

@@ -0,0 +1,187 @@
+# Happy Integration Research
+
+## Problem Statement
+
+When `CLAUDE_TEAM_COMMAND=happy` is set, sessions spawn and work in iTerm2 but Happy mobile shows them as empty. Running `happy` directly from terminal works fine.
+
+## Root Cause: `--settings` Flag Conflict
+
+### How claude-team spawns sessions
+
+In `src/claude_team_mcp/iterm_utils.py:545-552`:
+
+```python
+claude_cmd = os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
+if dangerously_skip_permissions:
+    claude_cmd += " --dangerously-skip-permissions"
+if stop_hook_marker_id:
+    settings_file = build_stop_hook_settings_file(stop_hook_marker_id)
+    claude_cmd += f" --settings {settings_file}"
+```
+
+This creates a command like:
+```
+happy --dangerously-skip-permissions --settings ~/.claude/claude-team-settings/worker-xxx.json
+```
+
+**Claude-team's settings file** (`~/.claude/claude-team-settings/worker-xxx.json`):
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "echo [worker-done:xxx]"
+      }]
+    }]
+  }
+}
+```
+
+### How Happy processes the command
+
+When Happy receives `--settings <file>`, it treats it as an unknown arg and passes it through to Claude via `options.claudeArgs`. Then in `dist/index-B3gQr6vs.mjs:311-314`:
+
+```javascript
+if (opts.claudeArgs) {
+  args.push(...opts.claudeArgs);  // Includes claude-team's --settings
+}
+args.push("--settings", opts.hookSettingsPath);  // Happy's own --settings
+```
+
+**Happy's settings file** (`~/.happy/tmp/hooks/session-hook-<pid>.json`):
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "matcher": "*",
+      "hooks": [{
+        "type": "command",
+        "command": "node \".../session_hook_forwarder.cjs\" <port>"
+      }]
+    }]
+  }
+}
+```
+
+### The Conflict
+
+Claude receives TWO `--settings` flags:
+```
+claude ... --settings <claude-team-file> --settings <happy-file>
+```
+
+Claude likely only uses the **first** `--settings` file (standard CLI behavior), meaning:
+- Claude has the **Stop hook** (claude-team's) - for idle detection
+- Claude does **NOT** have the **SessionStart hook** (Happy's) - for session tracking
+
+### Why Happy mobile shows empty sessions
+
+Happy's session tracking relies on the `SessionStart` hook:
+1. Hook fires when Claude starts
+2. Hook script POSTs session ID to Happy's local hook server (port varies per session)
+3. Happy daemon receives session ID and updates session metadata
+4. Mobile app displays session
+
+Without the SessionStart hook firing, Happy never learns the Claude session ID, so the session appears empty in the mobile app.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/claude_team_mcp/iterm_utils.py:459-500` | `build_stop_hook_settings_file()` creates Stop hook settings |
+| `src/claude_team_mcp/iterm_utils.py:545-552` | Command building that adds `--settings` |
+| Happy `dist/index-B3gQr6vs.mjs:311-314` | Args processing that adds Happy's `--settings` |
+| Happy `dist/index-B3gQr6vs.mjs:4928-4953` | `generateHookSettingsFile()` creates SessionStart hook settings |
+| Happy `dist/index-B3gQr6vs.mjs:4861-4927` | Hook server that receives session notifications |
+| Happy `scripts/session_hook_forwarder.cjs` | Script executed by SessionStart hook |
+
+## Solution Options
+
+### Option A: Don't add `--settings` when using Happy
+
+When `CLAUDE_TEAM_COMMAND=happy`, skip adding the `--settings` flag entirely:
+
+```python
+claude_cmd = os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
+if dangerously_skip_permissions:
+    claude_cmd += " --dangerously-skip-permissions"
+
+# Only add stop hook settings when NOT using happy
+if stop_hook_marker_id and claude_cmd == "claude":
+    settings_file = build_stop_hook_settings_file(stop_hook_marker_id)
+    claude_cmd += f" --settings {settings_file}"
+```
+
+**Tradeoff:** Loses idle detection for Happy-spawned workers. Claude-team would need an alternative mechanism.
+
+### Option B: Merge hooks into one settings file
+
+Create a combined settings file that includes BOTH hooks:
+
+```python
+def build_merged_settings_file(marker_id: str, happy_port: int) -> str:
+    settings = {
+        "hooks": {
+            "Stop": [{
+                "hooks": [{
+                    "type": "command",
+                    "command": f"echo [worker-done:{marker_id}]"
+                }]
+            }],
+            "SessionStart": [{
+                "matcher": "*",
+                "hooks": [{
+                    "type": "command",
+                    "command": f"node /path/to/session_hook_forwarder.cjs {happy_port}"
+                }]
+            }]
+        }
+    }
+    # ...
+```
+
+**Tradeoff:** Requires knowing Happy's hook server port, which is dynamic and only known after Happy starts its hook server.
+
+### Option C: Coordinate with Happy's hook mechanism
+
+Have claude-team discover Happy's hook port and integrate with it, or use Happy's daemon API directly for session tracking.
+
+**Tradeoff:** Complex integration, tight coupling with Happy internals.
+
+### Option D: Request Happy feature - external settings support
+
+Ask Happy to support inheriting/merging external `--settings` files instead of overwriting:
+
+```javascript
+// In Happy's args processing
+if (arg === "--settings") {
+    options.externalSettings = args[++i];  // Store for later merging
+}
+
+// When building Claude args
+const mergedSettings = mergeSettings(opts.externalSettings, opts.hookSettingsPath);
+args.push("--settings", mergedSettings);
+```
+
+**Tradeoff:** Requires Happy changes, but cleanest solution.
+
+## Recommended Approach
+
+**Short-term (Option A):** Detect when using Happy and skip the `--settings` flag. Accept the loss of Stop-hook-based idle detection. Use an alternative like polling the JSONL for assistant message patterns.
+
+**Long-term (Option D):** Request Happy add support for merging external settings files, or document how to integrate with Happy's session tracking API directly.
+
+## Testing Verification
+
+To verify the root cause:
+1. Run `happy` directly from terminal - check that SessionStart hook fires (session shows in mobile)
+2. Run via claude-team with `CLAUDE_TEAM_COMMAND=happy` - SessionStart hook should NOT fire
+3. Temporarily remove claude-team's `--settings` flag and respawn - session should appear in mobile
+
+## Additional Notes
+
+- Happy's daemon runs in background and must be started for session tracking
+- Happy auto-starts daemon if not running (line 6469-6478)
+- Session metadata includes `startedBy: "terminal"` vs `"daemon"` - may affect visibility
+- Happy's hook server port is ephemeral (assigned at runtime)

{claude_team_mcp-0.3.0 → claude_team_mcp-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-team-mcp
-Version: 0.3.0
+Version: 0.3.2
 Summary: MCP server for managing multiple Claude Code sessions via iTerm2
 Project-URL: Homepage, https://github.com/Martian-Engineering/claude-team
 Project-URL: Repository, https://github.com/Martian-Engineering/claude-team
@@ -140,6 +140,19 @@ Add to your Claude Code MCP settings. You can configure this at:
 
 After adding the configuration, restart Claude Code for it to take effect.
 
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_TEAM_COMMAND` | `claude` | Override the command used to start Claude Code in worker sessions. Useful for running alternative CLI implementations like `happy`. |
+| `CLAUDE_TEAM_PROJECT_DIR` | (none) | When set, allows using `"project_path": "auto"` in worker configs to automatically use this path. |
+
+Example using an alternative CLI:
+
+```bash
+export CLAUDE_TEAM_COMMAND=happy
+```
+
 ## MCP Tools
 
 ### Worker Management

{claude_team_mcp-0.3.0 → claude_team_mcp-0.3.2}/README.md

@@ -110,6 +110,19 @@ Add to your Claude Code MCP settings. You can configure this at:
 
 After adding the configuration, restart Claude Code for it to take effect.
 
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_TEAM_COMMAND` | `claude` | Override the command used to start Claude Code in worker sessions. Useful for running alternative CLI implementations like `happy`. |
+| `CLAUDE_TEAM_PROJECT_DIR` | (none) | When set, allows using `"project_path": "auto"` in worker configs to automatically use this path. |
+
+Example using an alternative CLI:
+
+```bash
+export CLAUDE_TEAM_COMMAND=happy
+```
+
 ## MCP Tools
 
 ### Worker Management

{claude_team_mcp-0.3.0 → claude_team_mcp-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "claude-team-mcp"
-version = "0.3.0"
+version = "0.3.2"
 description = "MCP server for managing multiple Claude Code sessions via iTerm2"
 readme = "README.md"
 requires-python = ">=3.11"

{claude_team_mcp-0.3.0 → claude_team_mcp-0.3.2}/src/claude_team_mcp/iterm_utils.py

@@ -6,6 +6,7 @@ from the original primitives.py for use in the MCP server.
 """
 
 import logging
+import os
 import re
 from typing import TYPE_CHECKING, Optional
 
@@ -515,6 +516,11 @@ async def start_claude_in_session(
     atomic command (cd && claude). Waits for shell readiness before sending
     the command, then waits for Claude's startup banner to appear.
 
+    The command used to launch Claude Code can be overridden by setting
+    the CLAUDE_TEAM_COMMAND environment variable (defaults to "claude").
+    This is useful for running alternative Claude CLI implementations
+    like "happy" or for testing purposes.
+
     Args:
         session: iTerm2 session to use
         project_path: Directory to run Claude in
@@ -537,10 +543,20 @@ async def start_claude_in_session(
         )
 
     # Build claude command with flags
-    claude_cmd = "claude"
+    # 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"
-    if stop_hook_marker_id:
+
+    # 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}"
 

claude_team_mcp-0.3.2/tests/test_iterm_utils.py

@@ -0,0 +1,136 @@
+"""Tests for iterm_utils module."""
+
+import os
+from unittest.mock import patch
+
+import pytest
+
+from claude_team_mcp.iterm_utils import build_stop_hook_settings_file
+
+
+class TestClaudeCommandBuilding:
+    """Tests for Claude command building logic in start_claude_in_session.
+
+    These tests verify the --settings flag behavior based on CLAUDE_TEAM_COMMAND.
+    The actual start_claude_in_session function is async and requires iTerm2,
+    so we test the command building logic by examining the key conditions.
+    """
+
+    def test_default_claude_command_gets_settings(self):
+        """Default 'claude' command should get --settings flag for idle detection."""
+        # Simulate the logic from start_claude_in_session
+        with patch.dict(os.environ, {}, clear=False):
+            # Remove CLAUDE_TEAM_COMMAND if present
+            os.environ.pop("CLAUDE_TEAM_COMMAND", None)
+
+            claude_cmd = os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
+            is_default_claude_command = claude_cmd == "claude"
+
+            assert claude_cmd == "claude"
+            assert is_default_claude_command is True
+
+            # With a stop_hook_marker_id, --settings should be added
+            stop_hook_marker_id = "test-marker-123"
+            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}"
+
+            assert "--settings" in claude_cmd
+            assert "test-marker-123" in settings_file
+
+    def test_custom_command_skips_settings(self):
+        """Custom commands like 'happy' should NOT get --settings flag.
+
+        Custom commands have their own session tracking mechanisms.
+        Adding --settings conflicts with them (e.g., Happy's SessionStart hook).
+        """
+        with patch.dict(os.environ, {"CLAUDE_TEAM_COMMAND": "happy"}):
+            claude_cmd = os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
+            is_default_claude_command = claude_cmd == "claude"
+
+            assert claude_cmd == "happy"
+            assert is_default_claude_command is False
+
+            # With a stop_hook_marker_id, --settings should NOT be added
+            stop_hook_marker_id = "test-marker-123"
+            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}"
+
+            assert "--settings" not in claude_cmd
+
+    def test_custom_command_with_path_skips_settings(self):
+        """Custom commands specified as paths should also skip --settings."""
+        with patch.dict(os.environ, {"CLAUDE_TEAM_COMMAND": "/usr/local/bin/happy"}):
+            claude_cmd = os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
+            is_default_claude_command = claude_cmd == "claude"
+
+            assert claude_cmd == "/usr/local/bin/happy"
+            assert is_default_claude_command is False
+
+            stop_hook_marker_id = "test-marker-123"
+            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}"
+
+            assert "--settings" not in claude_cmd
+
+    def test_dangerously_skip_permissions_still_added(self):
+        """--dangerously-skip-permissions should be added regardless of command."""
+        # Test with default claude
+        with patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("CLAUDE_TEAM_COMMAND", None)
+            claude_cmd = os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
+
+            dangerously_skip_permissions = True
+            if dangerously_skip_permissions:
+                claude_cmd += " --dangerously-skip-permissions"
+
+            assert "--dangerously-skip-permissions" in claude_cmd
+
+        # Test with custom command
+        with patch.dict(os.environ, {"CLAUDE_TEAM_COMMAND": "happy"}):
+            claude_cmd = os.environ.get("CLAUDE_TEAM_COMMAND", "claude")
+
+            dangerously_skip_permissions = True
+            if dangerously_skip_permissions:
+                claude_cmd += " --dangerously-skip-permissions"
+
+            assert "--dangerously-skip-permissions" in claude_cmd
+            assert claude_cmd == "happy --dangerously-skip-permissions"
+
+
+class TestBuildStopHookSettingsFile:
+    """Tests for the stop hook settings file builder."""
+
+    def test_creates_valid_settings_file(self):
+        """Settings file should contain Stop hook with marker."""
+        import json
+        from pathlib import Path
+
+        marker_id = "test-abc123"
+        settings_path = build_stop_hook_settings_file(marker_id)
+
+        # Verify file exists and is valid JSON
+        settings_file = Path(settings_path)
+        assert settings_file.exists()
+
+        content = json.loads(settings_file.read_text())
+        assert "hooks" in content
+        assert "Stop" in content["hooks"]
+
+        # Verify marker is in the command
+        stop_hooks = content["hooks"]["Stop"]
+        assert len(stop_hooks) > 0
+        command = stop_hooks[0]["hooks"][0]["command"]
+        assert marker_id in command
+
+    def test_settings_file_in_expected_location(self):
+        """Settings file should be in ~/.claude/claude-team-settings/."""
+        from pathlib import Path
+
+        marker_id = "location-test-456"
+        settings_path = build_stop_hook_settings_file(marker_id)
+
+        expected_dir = Path.home() / ".claude" / "claude-team-settings"
+        assert settings_path.startswith(str(expected_dir))

{claude_team_mcp-0.3.0 → claude_team_mcp-0.3.2}/uv.lock

@@ -114,7 +114,7 @@ wheels = [
 
 [[package]]
 name = "claude-team-mcp"
-version = "0.2.1"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "iterm2" },

claude_team_mcp-0.3.0/.beads/.local_version

@@ -1 +0,0 @@
-0.42.0

claude_team_mcp-0.3.0/.beads/daemon.lock

@@ -1,7 +0,0 @@
-{
-  "pid": 6716,
-  "parent_pid": 6710,
-  "database": "/Users/phaedrus/Projects/claude-team/.beads/beads.db",
-  "version": "0.41.0",
-  "started_at": "2025-12-30T17:49:19.75181Z"
-}

claude_team_mcp-0.3.0/.beads/daemon.pid

@@ -1 +0,0 @@
-6716