voicesmith-mcp 1.0.4 → 1.0.7

package/README.md

@@ -11,7 +11,7 @@ Local AI voice for coding assistants. Gives your AI a real voice (text-to-speech
 - **54 distinct voices** via Kokoro ONNX (local TTS, ~300MB model)
 - **Speech-to-text** via faster-whisper (local STT, ~150MB model)
 - **Voice activity detection** via Silero VAD (local, 2MB)
-- **Multi-session support** — run multiple IDE sessions, each with its own voice
+- **Multi-session support** — run multiple Claude Code sessions, each with its own voice (single session for Cursor/Codex)
 - **Works with Claude Code, Cursor, and Codex**
 
 ## Quick Start
@@ -69,7 +69,11 @@ The MCP server runs as a local process alongside your IDE. It communicates over
 
 ## Multi-Session
 
-Multiple IDE sessions can run simultaneously. Each gets a unique voice name and HTTP port. Session coordination uses a shared registry (`sessions.json`) with file locking. Cross-session audio is serialized via `flock` to prevent overlapping playback.
+**Claude Code:** Full multi-session support. Multiple Claude Code sessions can run simultaneously, each with its own voice. Session identity is tracked via Claude's `session_id` — resuming a session reclaims the same voice, and multiple terminals sharing the same session share the same voice. Orphaned servers are detected and cleaned up automatically.
+
+**Cursor / Codex:** Single session only. Cursor runs one MCP server per config (shared across tabs), and Codex has no multi-session hooks. Voice works normally — just no multi-session coordination.
+
+Cross-session audio is serialized via `flock` to prevent overlapping playback.
 
 ## Configuration
 
@@ -102,11 +106,11 @@ Re-run `npx voicesmith-mcp install` to change your voice or update settings. Exi
 
 ## Supported IDEs
 
-| IDE | Config Location | Rules Location |
-|-----|----------------|----------------|
-| Claude Code | `~/.claude.json` | `~/.claude/CLAUDE.md` |
-| Cursor | `~/.cursor/mcp.json` | `~/.cursor/rules/voicesmith.mdc` |
-| Codex | `~/.codex/mcp.json` | `~/.codex/AGENTS.md` |
+| IDE | Config Location | Rules Location | Multi-Session |
+|-----|----------------|----------------|---------------|
+| Claude Code | `~/.claude.json` | `~/.claude/CLAUDE.md` | Yes (via session_id) |
+| Cursor | `~/.cursor/mcp.json` | `~/.cursor/rules/voicesmith.mdc` | No (single server) |
+| Codex | `~/.codex/mcp.json` | `~/.codex/AGENTS.md` | No (single session) |
 
 ## Uninstall
 

package/hooks/session-start.sh

@@ -1,44 +1,115 @@
 #!/bin/bash
-# VoiceSmith MCP — SessionStart hook (lightweight)
-# Discovers this session's assigned voice name and injects it as context.
-# No TTS calls — just reads sessions.json and returns the name.
+# VoiceSmith MCP — SessionStart hook
+# 1. Receives session_id from Claude Code via stdin JSON
+# 2. Sends session_id to the MCP server's POST /session endpoint
+# 3. Server reconciles voice with sibling sessions (same session_id)
+# 4. Returns the assigned voice name as additionalContext
 
 SESSIONS_FILE="$HOME/.local/share/voicesmith-mcp/sessions.json"
 INPUT=$(cat)
 
+# Parse session_id from hook input (all hooks receive session_id via stdin)
+SESSION_ID=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('session_id', ''))
+except:
+    pass
+" 2>/dev/null)
+
 SESSION_NAME=""
 SESSION_VOICE=""
 
 if [ -f "$SESSIONS_FILE" ]; then
-    SESSION_INFO=$(python3 -c "
+    # Find this session's MCP server port (by PID liveness, prefer tmux match)
+    PORT=$(python3 -c "
 import json, os
 try:
     with open('$SESSIONS_FILE') as f:
         data = json.load(f)
-    tmux_session = os.environ.get('VOICESMITH_TMUX', '')
+    tmux = os.environ.get('VOICESMITH_TMUX', '')
+    # Try tmux match first
     for s in data.get('sessions', []):
         try:
             os.kill(s['pid'], 0)
-            if tmux_session and s.get('tmux_session') == tmux_session:
-                print(f\"{s['name']}|{s['voice']}\")
-                break
+            if tmux and s.get('tmux_session') == tmux:
+                print(s['port'])
+                raise SystemExit
+        except (OSError, ProcessLookupError):
+            pass
+    # Fallback: most recent alive session
+    for s in reversed(data.get('sessions', [])):
+        try:
+            os.kill(s['pid'], 0)
+            print(s['port'])
+            break
         except (OSError, ProcessLookupError):
             pass
-    else:
-        for s in reversed(data.get('sessions', [])):
-            try:
-                os.kill(s['pid'], 0)
+except:
+    pass
+" 2>/dev/null)
+
+    # Send session_id to the server if we have both port and session_id
+    if [ -n "$PORT" ] && [ -n "$SESSION_ID" ]; then
+        RESPONSE=$(curl -s --max-time 3 -X POST \
+            -H "Content-Type: application/json" \
+            -d "{\"session_id\": \"$SESSION_ID\"}" \
+            "http://127.0.0.1:$PORT/session" 2>/dev/null)
+
+        if [ -n "$RESPONSE" ]; then
+            SESSION_NAME=$(echo "$RESPONSE" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    s = d.get('session', {})
+    print(s.get('name', ''))
+except:
+    pass
+" 2>/dev/null)
+            SESSION_VOICE=$(echo "$RESPONSE" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    s = d.get('session', {})
+    print(s.get('voice', ''))
+except:
+    pass
+" 2>/dev/null)
+        fi
+    fi
+
+    # Fallback: read sessions.json directly if HTTP call didn't work
+    if [ -z "$SESSION_NAME" ]; then
+        SESSION_INFO=$(python3 -c "
+import json, os
+try:
+    with open('$SESSIONS_FILE') as f:
+        data = json.load(f)
+    tmux = os.environ.get('VOICESMITH_TMUX', '')
+    for s in data.get('sessions', []):
+        try:
+            os.kill(s['pid'], 0)
+            if tmux and s.get('tmux_session') == tmux:
                 print(f\"{s['name']}|{s['voice']}\")
-                break
-            except (OSError, ProcessLookupError):
-                pass
-except Exception:
+                raise SystemExit
+        except (OSError, ProcessLookupError):
+            pass
+    for s in reversed(data.get('sessions', [])):
+        try:
+            os.kill(s['pid'], 0)
+            print(f\"{s['name']}|{s['voice']}\")
+            break
+        except (OSError, ProcessLookupError):
+            pass
+except:
     pass
 " 2>/dev/null)
 
-    if [ -n "$SESSION_INFO" ]; then
-        SESSION_NAME=$(echo "$SESSION_INFO" | cut -d'|' -f1)
-        SESSION_VOICE=$(echo "$SESSION_INFO" | cut -d'|' -f2)
+        if [ -n "$SESSION_INFO" ]; then
+            SESSION_NAME=$(echo "$SESSION_INFO" | cut -d'|' -f1)
+            SESSION_VOICE=$(echo "$SESSION_INFO" | cut -d'|' -f2)
+        fi
     fi
 fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voicesmith-mcp",
-  "version": "1.0.4",
+  "version": "1.0.7",
   "description": "Local AI voice for coding assistants — TTS & STT via MCP. Kokoro ONNX + faster-whisper, fully offline.",
   "bin": {
     "voicesmith-mcp": "bin/cli.js"

package/server.py

@@ -175,6 +175,9 @@ class _VoiceHTTPHandler(BaseHTTPRequestHandler):
                 "ready": True,
                 "name": _session_info.get("name") if _session_info else None,
                 "port": _session_info.get("port") if _session_info else None,
+                "session_id": _session_info.get("session_id") if _session_info else None,
+                "mcp_connected": _event_loop is not None,
+                "uptime_s": round(time.time() - _startup_time),
                 "last_tool_call_age_s": round(time.time() - _last_tool_call),
             })
             self.send_response(200)
@@ -189,9 +192,38 @@ class _VoiceHTTPHandler(BaseHTTPRequestHandler):
             self._handle_listen()
         elif self.path == "/speak":
             self._handle_speak()
+        elif self.path == "/session":
+            self._handle_session_update()
         else:
             self.send_error(404)
 
+    def _handle_session_update(self):
+        """Receive session_id from the SessionStart hook and reconcile voice."""
+        global _session_info
+
+        try:
+            content_length = int(self.headers.get("Content-Length", 0))
+            body = self.rfile.read(content_length) if content_length > 0 else b"{}"
+            params = json.loads(body)
+        except (json.JSONDecodeError, ValueError):
+            self._json_response(400, {"error": "invalid_json"})
+            return
+
+        session_id = params.get("session_id")
+        if not session_id:
+            self._json_response(400, {"error": "missing_session_id"})
+            return
+
+        from session_registry import update_session_id
+        updated = update_session_id(os.getpid(), session_id)
+
+        if updated:
+            _session_info = updated
+            logger.info(f"Session updated: session_id={session_id}, name={updated['name']}")
+            self._json_response(200, {"success": True, "session": updated})
+        else:
+            self._json_response(404, {"error": "session_not_found"})
+
     def _handle_speak(self):
         """Synthesize and play speech via HTTP. Used by SessionStart hook for preheat intro."""
         if _event_loop is None:
@@ -831,12 +863,17 @@ def _start_preheat_intro():
         return
 
     def _intro():
-        # Wait for server to settle
+        # Wait for server to settle — also gives the SessionStart hook
+        # time to fire and update _session_info with session_id and
+        # possibly a different name (multi-terminal sibling reconciliation)
         time.sleep(1.5)
+        # Re-read _session_info in case the hook updated it during the sleep
+        intro_name = _session_info.get("name", default_name) if _session_info else default_name
+        intro_voice = _session_info.get("voice", default_voice) if _session_info else default_voice
         try:
-            result = _tts_engine.synthesize(f"{name} here, ready to go.", voice, 1.0)
+            result = _tts_engine.synthesize(f"{intro_name} here, ready to go.", intro_voice, 1.0)
             _audio_player.play(result.samples, result.sample_rate)
-            logger.info(f"Preheat intro spoken: {name}")
+            logger.info(f"Preheat intro spoken: {intro_name}")
         except Exception as e:
             logger.warning(f"Preheat intro failed: {e}")
 

package/session_registry.py

@@ -9,8 +9,8 @@ import fcntl
 import json
 import os
 import signal
+import subprocess
 import time
-import urllib.request
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
@@ -59,20 +59,26 @@ def _write_sessions(path: Path, sessions: list[dict]) -> None:
         json.dump({"sessions": sessions}, f, indent=2)
 
 
-# Max seconds since last MCP tool call before considering a session stale.
-# If a server hasn't had any tool calls in this time, it's likely orphaned
-# (MCP client disconnected but process is still running).
-_STALE_ACTIVITY_THRESHOLD = 300  # 5 minutes
+def _get_ppid(pid: int) -> int:
+    """Get the parent PID of a process. Returns 0 on failure."""
+    try:
+        result = subprocess.run(
+            ["ps", "-o", "ppid=", "-p", str(pid)],
+            capture_output=True, text=True, timeout=2,
+        )
+        return int(result.stdout.strip()) if result.returncode == 0 else 0
+    except Exception:
+        return 0
 
 
-def _session_healthy(session: dict, activity_threshold: int = _STALE_ACTIVITY_THRESHOLD) -> bool:
-    """Check if a session is alive and actively used.
+def _session_healthy(session: dict) -> bool:
+    """Check if a session is alive and its parent (IDE) is still running.
 
-    Three checks:
-    1. PID alive (fast, catches crashed processes)
-    2. HTTP health check on /status (catches completely dead servers)
-    3. Activity check — if last_tool_call_age_s exceeds threshold, the server
-       is alive but orphaned (no MCP client connected)
+    Checks:
+    1. PID alive — catches crashed server processes
+    2. Parent PID alive — if the parent (Claude Code, Cursor, etc.) died,
+       the server is orphaned. On macOS/Linux, orphaned processes get
+       reparented to PID 1 (launchd/init).
     """
     pid = session.get("pid", 0)
     if not _pid_alive(pid):
@@ -82,33 +88,15 @@ def _session_healthy(session: dict, activity_threshold: int = _STALE_ACTIVITY_TH
     if pid == os.getpid():
         return True
 
-    port = session.get("port")
-    if not port:
-        return False
-
-    try:
-        url = f"http://127.0.0.1:{port}/status"
-        req = urllib.request.Request(url, method="GET")
-        with urllib.request.urlopen(req, timeout=2) as resp:
-            data = json.loads(resp.read())
-            if not data.get("ready", False):
-                raise ValueError("not ready")
-
-            # Check activity age — if server hasn't had MCP tool calls
-            # in a while, it's orphaned
-            age = data.get("last_tool_call_age_s")
-            if age is not None and age > activity_threshold:
-                logger.info(
-                    f"Session '{session.get('name')}' (pid {pid}) inactive "
-                    f"for {age}s — treating as stale"
-                )
-                raise ValueError("inactive")
-
-            return True
-    except Exception:
-        # Server not responding or inactive — it's orphaned
-        logger.info(f"Session '{session.get('name')}' (pid {pid}) stale on port {port}")
-        # Kill the orphaned process
+    # Check if the server's parent process is still alive.
+    # If parent is PID 1 (launchd/init), the IDE exited and the server
+    # was reparented — it's orphaned.
+    ppid = _get_ppid(pid)
+    if ppid <= 1:
+        logger.info(
+            f"Session '{session.get('name')}' (pid {pid}) orphaned "
+            f"(parent pid {ppid}) — treating as stale"
+        )
         try:
             os.kill(pid, signal.SIGTERM)
             logger.info(f"Sent SIGTERM to orphaned process {pid}")
@@ -116,19 +104,19 @@ def _session_healthy(session: dict, activity_threshold: int = _STALE_ACTIVITY_TH
             pass
         return False
 
+    return True
 
-def _clean_stale(sessions: list[dict], aggressive: bool = False) -> list[dict]:
-    """Remove sessions that are dead or unresponsive.
 
-    Args:
-        aggressive: If True, use a shorter activity threshold (10s instead of 5min).
-                    Used during startup registration to quickly reclaim names from
-                    orphaned servers that haven't fully shut down yet.
+def _clean_stale(sessions: list[dict]) -> list[dict]:
+    """Remove sessions that are dead or orphaned.
+
+    Detection logic:
+    1. PID dead → remove immediately
+    2. Parent PID is 1 (launchd/init) → IDE exited, server orphaned → kill and remove
     """
-    threshold = 10 if aggressive else _STALE_ACTIVITY_THRESHOLD
     alive = []
     for s in sessions:
-        if _session_healthy(s, activity_threshold=threshold):
+        if _session_healthy(s):
             alive.append(s)
         else:
             logger.info(f"Removed stale session: {s.get('name')} (pid {s.get('pid')})")
@@ -223,7 +211,7 @@ def register_session(
         sessions = _read_sessions(path)
         # Aggressive cleanup on startup — use short activity threshold
         # to quickly reclaim names from orphaned servers
-        sessions = _clean_stale(sessions, aggressive=True)
+        sessions = _clean_stale(sessions)
 
         taken_names = {s["name"] for s in sessions}
 
@@ -233,7 +221,7 @@ def register_session(
             time.sleep(2)
             fcntl.flock(f, fcntl.LOCK_EX)
             sessions = _read_sessions(path)
-            sessions = _clean_stale(sessions, aggressive=True)
+            sessions = _clean_stale(sessions)
             _write_sessions(path, sessions)
             taken_names = {s["name"] for s in sessions}
 
@@ -257,6 +245,7 @@ def register_session(
             "voice": voice,
             "port": port,
             "pid": os.getpid(),
+            "session_id": None,  # Set later by SessionStart hook
             "tmux_session": tmux_session,
             "started_at": datetime.now(timezone.utc).isoformat(),
         }
@@ -289,6 +278,62 @@ def unregister_session() -> None:
     logger.info("Session unregistered")
 
 
+def update_session_id(pid: int, session_id: str) -> Optional[dict]:
+    """Set the session_id on this PID's entry and reconcile voice with siblings.
+
+    When the SessionStart hook fires, it sends the session_id to the server.
+    The server calls this to:
+    1. Set session_id on its own entry
+    2. Check if a living sibling (same session_id) already has a voice
+    3. If so, adopt that voice (shared session = shared voice)
+
+    Returns the updated session dict, or None if PID not found.
+    """
+    path = _sessions_path()
+    if not path.exists():
+        return None
+
+    try:
+        with open(path, "r+") as f:
+            fcntl.flock(f, fcntl.LOCK_EX)
+            sessions = _read_sessions(path)
+            sessions = _clean_stale(sessions)
+
+            # Find our entry
+            our_entry = None
+            for s in sessions:
+                if s.get("pid") == pid:
+                    our_entry = s
+                    break
+
+            if our_entry is None:
+                return None
+
+            # Set session_id
+            our_entry["session_id"] = session_id
+
+            # Look for living siblings with the same session_id
+            for s in sessions:
+                if (s.get("session_id") == session_id
+                        and s.get("pid") != pid
+                        and _pid_alive(s.get("pid", 0))):
+                    # Sibling found — adopt its name and voice
+                    if s["name"] != our_entry["name"]:
+                        logger.info(
+                            f"Adopting sibling voice: {our_entry['name']} → {s['name']} "
+                            f"(shared session_id {session_id})"
+                        )
+                        our_entry["name"] = s["name"]
+                        our_entry["voice"] = s["voice"]
+                    break
+
+            _write_sessions(path, sessions)
+            return dict(our_entry)
+    except OSError as e:
+        logger.warning(f"Failed to update session_id: {e}")
+        return None
+
+
 def get_active_sessions() -> list[dict]:
     """Return list of active sessions (stale PIDs filtered out)."""
     path = _sessions_path()