mtrx-cli 0.1.14 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrx-cli",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "MATRX CLI for routing Codex, Claude, and Cursor through Matrx",
   "homepage": "https://mtrx.so",
   "repository": {
@@ -27,6 +27,7 @@
     "src/matrx/cli/__init__.py",
     "src/matrx/cli/cursor_ca.py",
     "src/matrx/cli/cursor_config.py",
+    "src/matrx/cli/cursor_hooks.py",
     "src/matrx/cli/cursor_daemon.py",
     "src/matrx/cli/cursor_launcher.py",
     "src/matrx/cli/cursor_proxy.py",

package/src/matrx/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.14"
+__version__ = "0.1.16"

package/src/matrx/cli/cursor_config.py

@@ -388,7 +388,7 @@ def restore_cursor_settings(
     return ok
 
 
-def print_manual_setup_instructions(proxy_url: str) -> None:
+def print_manual_setup_instructions(proxy_url: str, *, api_key_hint: str = "your Matrx key (mx_...)") -> None:
     """Print step-by-step instructions for the user to configure Cursor manually."""
     print()
     print("  Could not auto-configure Cursor settings.")
@@ -397,7 +397,7 @@ def print_manual_setup_instructions(proxy_url: str) -> None:
     print("  1. Open Cursor Settings (Cmd+, or Ctrl+,)")
     print("  2. Go to Models")
     print("  3. In the OpenAI API Keys section:")
-    print(f"     - API Key:           mtrx-cursor-proxy")
+    print(f"     - API Key:           {api_key_hint}")
     print(f"     - Override Base URL:  {proxy_url}")
     print("     - Toggle ON 'Override OpenAI Base URL'")
     print()

package/src/matrx/cli/cursor_hooks.py

@@ -0,0 +1,213 @@
+"""
+Cursor Hooks integration for MTRX telemetry.
+
+Uses Cursor's official Hooks API (https://cursor.com/docs/hooks) to send
+session/agent events to MTRX. Works regardless of how Cursor was launched
+(Dock, Spotlight, CLI) - same clean model as Claude/Codex.
+
+Configures ~/.cursor/hooks.json and a Python script that POSTs to
+POST /v1/telemetry/cursor/hooks.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from pathlib import Path
+
+from matrx.cli.state import config_dir
+
+logger = logging.getLogger(__name__)
+
+_CURSOR_HOME = Path.home() / ".cursor"
+_HOOKS_JSON = _CURSOR_HOME / "hooks.json"
+_HOOKS_DIR = _CURSOR_HOME / "hooks"
+_MTRX_HOOK_SCRIPT = _HOOKS_DIR / "mtrx-telemetry.py"
+_CONFIG_PATH = "cursor-hooks-config.json"
+
+_MTRX_HOOK_MARKER = "# MTRX cursor hooks (managed by mtrx cursor)"
+_MTRX_HOOKS_KEY = "_mtrx_managed_hooks"
+
+
+def _hooks_config_path() -> Path:
+    return config_dir() / _CONFIG_PATH
+
+
+def _read_hooks_json() -> dict:
+    if not _HOOKS_JSON.exists():
+        return {"version": 1, "hooks": {}}
+    try:
+        return json.loads(_HOOKS_JSON.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.debug("cursor_hooks: could not read hooks.json: %s", exc)
+        return {"version": 1, "hooks": {}}
+
+
+def _write_hooks_json(data: dict) -> bool:
+    try:
+        _HOOKS_JSON.parent.mkdir(parents=True, exist_ok=True)
+        _HOOKS_JSON.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+        return True
+    except OSError as exc:
+        logger.debug("cursor_hooks: could not write hooks.json: %s", exc)
+        return False
+
+
+def _hook_script_content() -> str:
+    return '''#!/usr/bin/env python3
+"""MTRX Cursor hooks telemetry — forwards events to MTRX. Managed by mtrx cursor."""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+def _config_path() -> Path:
+    config_dir = Path(os.environ.get("MTRX_CONFIG_DIR", Path.home() / ".config" / "mtrx"))
+    return config_dir / "cursor-hooks-config.json"
+
+def _log_path() -> Path:
+    return _config_path().parent / "logs" / "cursor-hooks.log"
+
+def _log(msg: str) -> None:
+    try:
+        log_file = _log_path()
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        with log_file.open("a") as f:
+            f.write(f"{ts} {msg}\n")
+    except OSError:
+        pass
+
+def main() -> None:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        print("{}")
+        return
+    event = payload.get("hook_event_name", "?")
+    conv = (payload.get("conversation_id") or payload.get("session_id") or "?")[:16]
+    cfg_path = _config_path()
+    if not cfg_path.exists():
+        _log(f"{event} conv={conv} skip=no_config")
+        print("{}")
+        return
+    try:
+        cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        _log(f"{event} conv={conv} skip=config_error")
+        print("{}")
+        return
+    url = (cfg.get("matrx_base_url") or "").rstrip("/") + "/v1/telemetry/cursor/hooks"
+    key = (cfg.get("matrx_key") or "").strip()
+    if not url or not key or not key.startswith("mx_"):
+        print("{}")
+        return
+    try:
+        import urllib.request
+        req = urllib.request.Request(
+            url,
+            data=json.dumps(payload).encode(),
+            headers={"Content-Type": "application/json", "X-Matrx-Key": key},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            status = resp.status
+        _log(f"{event} conv={conv} ok status={status}")
+    except Exception as e:
+        _log(f"{event} conv={conv} err={type(e).__name__}")
+    print("{}")
+
+if __name__ == "__main__":
+    main()
+'''
+
+
+def install_mtrx_hooks(matrx_key: str, matrx_base_url: str) -> bool:
+    """
+    Install MTRX hooks: create script, config, and merge into hooks.json.
+
+    Hooks: sessionEnd, stop — fire-and-forget telemetry to MTRX.
+    """
+    base = (matrx_base_url or "").rstrip("/")
+    if not base or not matrx_key or not matrx_key.startswith("mx_"):
+        return False
+
+    # Write hook script
+    try:
+        _HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+    except PermissionError as exc:
+        logger.debug("cursor_hooks: permission denied: %s", exc)
+        raise ValueError(
+            "Cannot create ~/.cursor/hooks — directory may be owned by root. "
+            "Run: sudo chown -R $(whoami) ~/.cursor"
+        ) from exc
+
+    script_path = _HOOKS_DIR / "mtrx-telemetry.py"
+    try:
+        script_path.write_text(_hook_script_content(), encoding="utf-8")
+        script_path.chmod(0o755)
+    except OSError as exc:
+        logger.debug("cursor_hooks: could not write script: %s", exc)
+        return False
+
+    # Write config (script reads this at runtime)
+    cfg_path = _hooks_config_path()
+    config_dir().mkdir(parents=True, exist_ok=True)
+    try:
+        cfg_path.write_text(
+            json.dumps({"matrx_key": matrx_key, "matrx_base_url": base}),
+            encoding="utf-8",
+        )
+        cfg_path.chmod(0o600)
+    except OSError as exc:
+        logger.debug("cursor_hooks: could not write config: %s", exc)
+        return False
+
+    # Merge into hooks.json — use ./hooks/mtrx-telemetry.py (relative to ~/.cursor/)
+    hooks = _read_hooks_json()
+    if "hooks" not in hooks:
+        hooks["hooks"] = {}
+    if "version" not in hooks:
+        hooks["version"] = 1
+
+    managed = {
+        "sessionEnd": [{"command": "./hooks/mtrx-telemetry.py"}],
+        "stop": [{"command": "./hooks/mtrx-telemetry.py"}],
+    }
+    for hook_name, defs in managed.items():
+        existing = hooks["hooks"].get(hook_name) or []
+        # Avoid duplicate
+        our_cmd = "./hooks/mtrx-telemetry.py"
+        if not any(d.get("command") == our_cmd for d in existing):
+            existing.extend(defs)
+        hooks["hooks"][hook_name] = existing
+
+    return _write_hooks_json(hooks)
+
+
+def remove_mtrx_hooks() -> bool:
+    """Remove MTRX hooks from hooks.json and delete config + script."""
+    removed = False
+    hooks = _read_hooks_json()
+    if "hooks" in hooks:
+        our_cmd = "./hooks/mtrx-telemetry.py"
+        for hook_name in ("sessionEnd", "stop"):
+            defs = hooks["hooks"].get(hook_name) or []
+            new_defs = [d for d in defs if d.get("command") != our_cmd]
+            if len(new_defs) != len(defs):
+                removed = True
+            hooks["hooks"][hook_name] = new_defs if new_defs else []
+    if removed:
+        _write_hooks_json(hooks)
+    _hooks_config_path().unlink(missing_ok=True)
+    _MTRX_HOOK_SCRIPT.unlink(missing_ok=True)
+    return removed
+
+
+def is_mtrx_hooks_installed() -> bool:
+    """Return True if MTRX hooks are configured."""
+    return _hooks_config_path().exists() and _MTRX_HOOK_SCRIPT.exists()

package/src/matrx/cli/cursor_proxy.py

@@ -31,6 +31,7 @@ from typing import Any
 import httpx
 
 from matrx.cli.cursor_ca import CertCache, load_ca
+from matrx.cli.cursor_reroute import is_ai_path, try_reroute_to_matrx
 
 logger = logging.getLogger(__name__)
 
@@ -259,7 +260,11 @@ class MITMProxy:
         up_writer: asyncio.StreamWriter,
         hostname: str,
     ) -> None:
-        """Forward HTTP/1.1 request-response pairs, logging each to telemetry."""
+        """Forward HTTP/1.1 request-response pairs, logging each to telemetry.
+
+        For AI paths (RunSSE, StreamCpp, etc.), attempts to reroute through MTRX
+        for live injection. If reroute succeeds, responds from MTRX; else forwards.
+        """
         while True:
             req_line = await client_reader.readline()
             if not req_line:
@@ -272,15 +277,62 @@ class MITMProxy:
             method = parts[0] if parts else "?"
             path = parts[1] if len(parts) > 1 else "/"
 
-            up_writer.write(req_line)
-
-            req_headers, req_cl, req_chunked = await self._forward_headers(
-                client_reader, up_writer
-            )
-
-            req_body_size = await self._forward_body(
-                client_reader, up_writer, req_cl, req_chunked
-            )
+            req_body_size = 0
+            # For AI paths: buffer request and try rerouting through MTRX (live injection)
+            if method == "POST" and is_ai_path(path):
+                req_headers, req_cl, req_chunked = await self._read_headers_only(
+                    client_reader
+                )
+                req_body = await self._read_body_to_bytes(
+                    client_reader, req_cl, req_chunked
+                )
+                req_body_size = len(req_body)
+                result = await try_reroute_to_matrx(
+                    path=path,
+                    method=method,
+                    req_headers=req_headers,
+                    req_body=req_body,
+                    matrx_base_url=self.matrx_base_url,
+                    matrx_key=self.matrx_key,
+                    session_id=str(uuid.uuid4()),
+                )
+                if result is not None:
+                    success, resp_headers, resp_body, is_streaming = result
+                    if success and resp_body is not None:
+                        self._request_count += 1
+                        self._write_http_response(
+                            client_writer, 200, resp_headers, resp_body
+                        )
+                        asyncio.create_task(
+                            self._ship_telemetry(
+                                hostname=hostname,
+                                method=method,
+                                path=path,
+                                status_code=200,
+                                req_body_size=len(req_body),
+                                resp_body_size=len(resp_body),
+                                elapsed_ms=0,
+                                content_type=resp_headers.get("content-type", ""),
+                                is_streaming=is_streaming,
+                            )
+                        )
+                        continue
+                    # Reroute returned but failed — fall through to forward
+                # Reroute not implemented or failed — forward to upstream
+                up_writer.write(req_line)
+                await self._write_headers(up_writer, req_headers)
+                up_writer.write(req_body)
+                await up_writer.drain()
+            else:
+                up_writer.write(req_line)
+                req_headers, req_cl, req_chunked = await self._forward_headers(
+                    client_reader, up_writer
+                )
+                req_body_size = await self._forward_body(
+                    client_reader, up_writer, req_cl, req_chunked
+                )
+                if req_body_size == 0 and req_cl > 0:
+                    req_body_size = req_cl
 
             started = time.monotonic()
 
@@ -336,6 +388,76 @@ class MITMProxy:
             if "close" in conn_h:
                 break
 
+    async def _read_headers_only(
+        self, reader: asyncio.StreamReader
+    ) -> tuple[dict[str, str], int, bool]:
+        """Read headers without writing. Returns (headers_dict, content_length, is_chunked)."""
+        headers: dict[str, str] = {}
+        content_length = -1
+        chunked = False
+        while True:
+            line = await reader.readline()
+            decoded = line.decode("utf-8", errors="replace").strip()
+            if not decoded:
+                break
+            if ":" in decoded:
+                k, _, v = decoded.partition(":")
+                k_lower = k.strip().lower()
+                v_stripped = v.strip()
+                headers[k_lower] = v_stripped
+                if k_lower == "content-length":
+                    content_length = int(v_stripped)
+                elif k_lower == "transfer-encoding" and "chunked" in v_stripped.lower():
+                    chunked = True
+        return headers, content_length, chunked
+
+    async def _read_body_to_bytes(
+        self,
+        reader: asyncio.StreamReader,
+        content_length: int,
+        chunked: bool,
+    ) -> bytes:
+        """Read body into bytes (no writer)."""
+        if content_length > 0:
+            return await reader.read(content_length)
+        if chunked:
+            parts: list[bytes] = []
+            while True:
+                size_line = await reader.readline()
+                size_str = size_line.decode("utf-8", errors="replace").strip()
+                try:
+                    chunk_size = int(size_str.split(";")[0], 16)
+                except ValueError:
+                    break
+                if chunk_size == 0:
+                    await reader.readline()  # trailer
+                    break
+                parts.append(await reader.read(chunk_size))
+                await reader.readline()  # crlf
+            return b"".join(parts)
+        return b""
+
+    def _write_headers(
+        self, writer: asyncio.StreamWriter, headers: dict[str, str]
+    ) -> None:
+        """Write headers as HTTP lines (caller must drain)."""
+        for k, v in headers.items():
+            writer.write(f"{k}: {v}\r\n".encode())
+        writer.write(b"\r\n")
+
+    def _write_http_response(
+        self,
+        writer: asyncio.StreamWriter,
+        status: int,
+        resp_headers: dict[str, str],
+        resp_body: bytes,
+    ) -> None:
+        """Write a complete HTTP response."""
+        writer.write(f"HTTP/1.1 {status} OK\r\n".encode())
+        self._write_headers(writer, resp_headers)
+        writer.write(resp_body)
+        # Caller should drain
+
     async def _forward_headers(
         self,
         reader: asyncio.StreamReader,
@@ -434,6 +556,81 @@ class MITMProxy:
             await writer.drain()
         return total
 
+    async def _read_headers_only(
+        self, reader: asyncio.StreamReader
+    ) -> tuple[dict[str, str], int, bool]:
+        """Read headers from reader without writing. Returns (headers, content_length, chunked)."""
+        headers: dict[str, str] = {}
+        content_length = -1
+        chunked = False
+        while True:
+            line = await reader.readline()
+            decoded = line.decode("utf-8", errors="replace").strip()
+            if not decoded:
+                break
+            if ":" in decoded:
+                k, _, v = decoded.partition(":")
+                k_lower = k.strip().lower()
+                v_stripped = v.strip()
+                headers[k_lower] = v_stripped
+                if k_lower == "content-length":
+                    content_length = int(v_stripped)
+                elif k_lower == "transfer-encoding" and "chunked" in v_stripped.lower():
+                    chunked = True
+        return headers, content_length, chunked
+
+    async def _read_body_to_bytes(
+        self,
+        reader: asyncio.StreamReader,
+        content_length: int,
+        chunked: bool,
+    ) -> bytes:
+        """Read body into bytes."""
+        if content_length > 0:
+            return await reader.readexactly(content_length)
+        if chunked:
+            parts: list[bytes] = []
+            while True:
+                size_line = await reader.readline()
+                size_str = size_line.decode("utf-8", errors="replace").strip()
+                try:
+                    chunk_size = int(size_str.split(";")[0], 16)
+                except ValueError:
+                    break
+                if chunk_size == 0:
+                    await reader.readline()  # trailer
+                    break
+                parts.append(await reader.readexactly(chunk_size))
+                await reader.readline()  # crlf
+            return b"".join(parts)
+        return b""
+
+    def _write_headers(
+        self, writer: asyncio.StreamWriter, headers: dict[str, str]
+    ) -> None:
+        """Write HTTP headers to writer."""
+        for k, v in headers.items():
+            # Capitalize header key (e.g. content-type -> Content-Type)
+            name = "-".join(p.capitalize() for p in k.split("-"))
+            writer.write(f"{name}: {v}\r\n".encode())
+        writer.write(b"\r\n")
+
+    def _write_http_response(
+        self,
+        writer: asyncio.StreamWriter,
+        status: int,
+        headers: dict[str, str],
+        body: bytes,
+    ) -> None:
+        """Write a complete HTTP response."""
+        writer.write(f"HTTP/1.1 {status} OK\r\n".encode())
+        if "content-length" not in {k.lower() for k in headers} and body:
+            headers = dict(headers)
+            headers["Content-Length"] = str(len(body))
+        self._write_headers(writer, headers)
+        writer.write(body)
+        # Note: drain is caller's responsibility
+
     # -----------------------------------------------------------------
     # Raw bidirectional pipe (for opaque tunnels)
     # -----------------------------------------------------------------

package/src/matrx/cli/launcher.py

@@ -85,6 +85,8 @@ def _runtime_agent_basename(tool: str) -> tuple[str, str, list[str], str]:
         return "codex-cli", "Codex CLI", ["cli", "codex"], "codex"
     if tool == "claude":
         return "claude-cli", "Claude CLI", ["claude", "cli"], "claude_code"
+    if tool == "gemini":
+        return "gemini-cli", "Gemini CLI", ["gemini", "cli"], "gemini_code"
     normalized = f"{tool}-cli"
     return normalized, f"{tool.capitalize()} CLI", ["cli", tool], tool
 
@@ -117,6 +119,8 @@ def find_executable(tool: str) -> str | None:
         candidates.extend(["claude.exe", "claude.cmd"])
     if tool == "codex":
         candidates.extend(["codex.exe", "codex.cmd"])
+    if tool == "gemini":
+        candidates.extend(["gemini.exe", "gemini.cmd"])
     for candidate in candidates:
         found = shutil.which(candidate)
         if found:
@@ -163,6 +167,13 @@ def build_launch_plan(
             env,
             orchestration=orchestration,
         )
+    elif tool == "gemini":
+        env, auth_source = _build_gemini_env(
+            state,
+            route,
+            env,
+            orchestration=orchestration,
+        )
     else:
         raise ValueError(f"Unsupported tool: {tool}")
 
@@ -229,6 +240,8 @@ def validate_launch_plan(plan: LaunchPlan, state: dict) -> None:
         _validate_claude_launch_plan(plan, state)
     if plan.tool == "codex":
         _validate_codex_launch_plan(plan, state)
+    if plan.tool == "gemini":
+        _validate_gemini_launch_plan(plan, state)
 
 
 def claude_credentials_path() -> Path:
@@ -519,6 +532,59 @@ def _build_codex_env(
     return env, "existing_codex_auth", passthrough_args
 
 
+def _build_gemini_env(
+    state: dict,
+    route: str,
+    env: dict[str, str],
+    *,
+    orchestration: dict | None = None,
+) -> tuple[dict[str, str], str]:
+    matrx = state["auth"]["matrx"]
+    # Assuming we might store Gemini-specific keys in future, or use OpenAI key fallback
+    # For now, we don't have a specific 'gemini' auth section in state.py, but we can assume
+    # if direct route, we use env var.
+    proxy_base = ensure_v1_url(matrx.get("base_url"))
+    mx_key, matrx_auth_source = _resolve_matrx_route_key(state, env)
+    
+    # Check for direct key in env or potentially saved elsewhere
+    direct_key = (env.get("GOOGLE_API_KEY") or "").strip()
+
+    if route == "matrx":
+        if not mx_key:
+            raise ValueError("No Matrx key available. Run: mtrx login matrx --key mx_... or set MTRX_KEY")
+        
+        # Clear existing Gemini config to force proxy usage
+        env.pop("MTRX_KEY", None)
+        
+        # Set Proxy Config
+        env["GOOGLE_GEMINI_BASE_URL"] = proxy_base
+        env["GEMINI_API_ENDPOINT"] = proxy_base
+        env["GOOGLE_API_KEY"] = mx_key
+        
+        # Matrx-specific headers (if supported by the tool, or for our own tracking)
+        # Note: Standard Gemini CLI might not support custom headers via env vars easily.
+        # We rely on the Base URL routing to Matrx proxy which handles the logic.
+        
+        return env, matrx_auth_source
+
+    # Direct route: clear any matrx-managed env vars
+    env.pop("MTRX_KEY", None)
+    
+    # Clear proxy overrides
+    _clear_if_matches(env, "GOOGLE_GEMINI_BASE_URL", proxy_base)
+    _clear_if_matches(env, "GEMINI_API_ENDPOINT", proxy_base)
+    
+    # Clear key if it was the Matrx key
+    current_key = (env.get("GOOGLE_API_KEY") or "").strip()
+    if current_key == mx_key or current_key.startswith("mx_"):
+        env.pop("GOOGLE_API_KEY", None)
+
+    if env.get("GOOGLE_API_KEY"):
+        return env, "existing_google_env"
+        
+    return env, "missing_auth"
+
+
 def _build_claude_env(
     state: dict,
     route: str,
@@ -765,6 +831,31 @@ def _validate_claude_launch_plan(plan: LaunchPlan, state: dict) -> None:
         raise ValueError("Claude Matrx route should not set ANTHROPIC_API_KEY")
 
 
+def _validate_gemini_launch_plan(plan: LaunchPlan, state: dict) -> None:
+    if plan.route != "matrx":
+        return
+
+    expected_base_url = ensure_v1_url(state.get("auth", {}).get("matrx", {}).get("base_url"))
+    
+    base_url = (plan.env.get("GOOGLE_GEMINI_BASE_URL") or "").strip()
+    if not base_url:
+         # Try the other one
+         base_url = (plan.env.get("GEMINI_API_ENDPOINT") or "").strip()
+
+    if not base_url:
+        raise ValueError("Gemini Matrx route is missing GOOGLE_GEMINI_BASE_URL or GEMINI_API_ENDPOINT")
+        
+    if base_url != expected_base_url:
+        raise ValueError(
+            "Gemini Matrx route must use the Matrx /v1 base URL. "
+            f"Got: {base_url}"
+        )
+
+    mx_key = (plan.env.get("GOOGLE_API_KEY") or "").strip()
+    if not mx_key.startswith("mx_"):
+        raise ValueError("Gemini Matrx route is missing a valid GOOGLE_API_KEY (should be mx_...)")
+
+
 def _validate_codex_launch_plan(plan: LaunchPlan, state: dict) -> None:
     if plan.route != "matrx":
         return
@@ -825,6 +916,16 @@ def describe_launch_plan(plan: LaunchPlan, state: dict) -> list[str]:
             "  persistent_route: disabled",
         ]
 
+    if plan.tool == "gemini":
+        base_url = ensure_v1_url(state.get("auth", {}).get("matrx", {}).get("base_url"))
+        return [
+            "Launching gemini via Matrx",
+            f"  base_url: {base_url}",
+            f"  auth_source: {plan.auth_source}",
+            "  runtime_route: env injection",
+            "  persistent_route: disabled",
+        ]
+
     return []
 
 
@@ -881,6 +982,9 @@ def _sync_tool_route_config(state: dict, *, tool: str, route: str) -> bool:
         return _cleanup_claude_managed_config(state)
     if tool == "codex":
         return _sync_codex_route_config(state, route=route)
+    if tool == "gemini":
+        # Gemini currently relies on env vars, no config file sync implemented yet.
+        return False
     return False
 
 

package/src/matrx/cli/main.py

@@ -74,7 +74,7 @@ def main(argv: list[str] | None = None) -> int:
         return _cmd_doctor()
     if args.command == "personal":
         return _cmd_personal(args)
-    if args.command in {"codex", "claude"}:
+    if args.command in {"codex", "claude", "gemini"}:
         return _cmd_launch(args.command, args.route, remainder)
     if args.command == "cursor":
         return _cmd_cursor(args)
@@ -97,7 +97,7 @@ def _build_parser() -> argparse.ArgumentParser:
     login.add_argument("--import", dest="do_import", action="store_true")
 
     use = subparsers.add_parser("use")
-    use.add_argument("tool", choices=["codex", "claude", "cursor"])
+    use.add_argument("tool", choices=["codex", "claude", "cursor", "gemini"])
     use.add_argument("route", choices=["direct", "matrx"])
 
     subparsers.add_parser("help")
@@ -116,6 +116,9 @@ def _build_parser() -> argparse.ArgumentParser:
     claude = subparsers.add_parser("claude")
     claude.add_argument("--route", choices=["direct", "matrx"])
 
+    gemini = subparsers.add_parser("gemini")
+    gemini.add_argument("--route", choices=["direct", "matrx"])
+
     cursor = subparsers.add_parser("cursor")
     cursor.add_argument("--route", choices=["direct", "matrx"])
     cursor.add_argument("--status", action="store_true", help="Check proxy status")
@@ -506,8 +509,13 @@ def _cmd_use(args) -> int:
 def _restore_cursor_if_needed() -> None:
     import json as _json
 
+    from matrx.cli.cursor_hooks import remove_mtrx_hooks
     from matrx.cli.cursor_service import is_proxy_running, uninstall_service
 
+    # Remove MTRX Cursor hooks
+    if remove_mtrx_hooks():
+        print("Cursor hooks removed.")
+
     # Stop the MITM proxy service if it's running
     if is_proxy_running():
         uninstall_service()
@@ -548,6 +556,7 @@ def _cmd_status() -> int:
     print("Defaults:")
     print(f"  codex: {_default_route_label(configured_route(state, 'codex'))}")
     print(f"  claude: {_default_route_label(configured_route(state, 'claude'))}")
+    print(f"  gemini: {_default_route_label(configured_route(state, 'gemini'))}")
     print(f"  cursor: {_default_route_label(configured_route(state, 'cursor'))}")
     print("Auth:")
     print(
@@ -562,7 +571,7 @@ def _cmd_status() -> int:
     local = "present" if claude_oauth_available() else "missing"
     print(f"  claude-code oauth: {imported}, local credentials: {local}")
     print("Tool config:")
-    for tool in ("codex", "claude"):
+    for tool in ("codex", "claude", "gemini"):
         config_status = get_tool_config_status(state, tool)
         route = configured_route(state, tool)
         if tool == "codex" and config_status["verified"] and not config_status["configured"]:
@@ -584,6 +593,7 @@ def _cmd_status() -> int:
     print("Executables:")
     print(f"  codex: {find_executable('codex') or 'not found'}")
     print(f"  claude: {find_executable('claude') or 'not found'}")
+    print(f"  gemini: {find_executable('gemini') or 'not found'}")
     profiles = _legacy_shell_proxy_profiles()
     active_env = _active_claude_proxy_env()
     if profiles or active_env:
@@ -698,7 +708,7 @@ def _cmd_doctor() -> int:
     workspace_binding = get_workspace_binding(state, cwd=os.environ.get("PWD") or os.getcwd()) or {}
     workspace_matrx_key = (workspace_binding.get("matrx_key") or "").strip()
 
-    for tool in ("codex", "claude"):
+    for tool in ("codex", "claude", "gemini"):
         found = find_executable(tool)
         if found:
             print(f"[ok] {tool} executable: {found}")
@@ -763,7 +773,7 @@ def _cmd_doctor() -> int:
             "[warn] Cleanup: `unfunction claude 2>/dev/null || true` and `unset ANTHROPIC_BASE_URL ANTHROPIC_CUSTOM_HEADERS ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN MATRX_ACTIVE_ROUTE MATRX_BASE_URL MATRX_API_KEY MATRX_CLAUDE_MODE MATRX_FALLBACK_ENABLED MATRX_PROXY_TIMEOUT_SEC ANTHROPIC_DIRECT_BASE_URL`",
         )
 
-    for tool in ("codex", "claude", "cursor"):
+    for tool in ("codex", "claude", "gemini", "cursor"):
         route = configured_route(state, tool)
         if route == "matrx" and not _has_matrx_login(state, env=os.environ):
             print(f"[fail] Default {tool} route is matrx but no Matrx key is saved")
@@ -836,43 +846,29 @@ def _cmd_launch(tool: str, route: str | None, remainder: list[str]) -> int:
 
 
 def _cmd_cursor(args) -> int:
-    import json as _json
-
-    from matrx.cli.cursor_ca import (
-        ca_cert_path,
-        ca_exists,
-        generate_ca,
-        is_ca_trusted,
-        trust_ca_system,
-    )
-    from matrx.cli.cursor_proxy import DEFAULT_PORT, PROXY_HOST
-    from matrx.cli.cursor_launcher import (
-        find_cursor_executable,
-        launch_cursor_with_proxy,
-    )
-    from matrx.cli.cursor_service import (
-        get_proxy_status,
-        install_service,
-        is_proxy_running,
-        uninstall_service,
-    )
+    from matrx.cli.cursor_hooks import install_mtrx_hooks, is_mtrx_hooks_installed
+    from matrx.cli.cursor_launcher import find_cursor_executable
 
     route = args.route
 
-    # --status: just report proxy health
+    # --status: report Base URL override + hooks status
     if args.status:
-        status = get_proxy_status()
-        if status:
-            print("MTRX Cursor proxy: running")
-            print(f"  requests processed: {status.get('requests', '?')}")
-        else:
-            print("MTRX Cursor proxy: not running")
+        state = load_state()
+        hooks_installed = is_mtrx_hooks_installed()
+        base_url = ensure_v1_url(state.get("auth", {}).get("matrx", {}).get("base_url"))
+        prev_path = config_dir() / "cursor-previous-settings.json"
+        configured = prev_path.exists()
+        print("MTRX Cursor integration:")
+        print(f"  mode: {'Base URL override (all models)' if configured else 'not configured'}")
+        print(f"  hooks: {'active (sessionEnd, stop → telemetry)' if hooks_installed else 'not installed'}")
+        if configured:
+            print(f"  matrx: {base_url}")
         return 0
 
-    # --stop: tear down the proxy
+    # --stop: tear down
     if args.stop:
         _restore_cursor_if_needed()
-        print("Cursor route set to direct — MTRX proxy disabled.")
+        print("Cursor route set to direct — MTRX disabled.")
         return 0
 
     state = load_state()
@@ -886,7 +882,7 @@ def _cmd_cursor(args) -> int:
             print("  Restart Cursor for settings to take effect.")
         return 0
 
-    # --- matrx route: set up the MITM proxy ---
+    # --- matrx route: Base URL override (works with any Cursor model: Claude, GPT, Gemini, etc.) ---
 
     try:
         state, login_changed = _complete_matrx_login(state)
@@ -910,6 +906,7 @@ def _cmd_cursor(args) -> int:
     matrx_base_url = ensure_root_url(
         state.get("auth", {}).get("matrx", {}).get("base_url")
     )
+    matrx_proxy_url = ensure_v1_url(matrx_base_url)
 
     if initialized or login_changed or promoted:
         save_state(state)
@@ -919,73 +916,40 @@ def _cmd_cursor(args) -> int:
             "Use `mtrx use cursor direct` to opt out.",
         )
 
-    # Step 1: Generate CA certificate if needed
-    if not ca_exists():
-        print("Generating MTRX CA certificate...")
-        generate_ca()
-        print(f"  CA cert: {ca_cert_path()}")
-
-    # Step 2: Trust CA (one-time)
-    if not is_ca_trusted():
-        print("Trusting MTRX CA certificate (may require password)...")
-        if trust_ca_system():
-            print("  CA trusted in system keychain.")
-        else:
-            print(
-                f"  [warn] Could not auto-trust CA. Cursor needs NODE_EXTRA_CA_CERTS={ca_cert_path()}"
-            )
-            print(
-                "  You can manually trust it or set the env var before launching Cursor."
-            )
-
-    # Step 3: Install and start the proxy service
-    proxy_url = f"http://{PROXY_HOST}:{DEFAULT_PORT}"
-    if is_proxy_running():
-        print(f"MTRX proxy already running on {proxy_url}")
+    # Configure Cursor's Override Base URL — sends chat to MTRX (any model: Claude, GPT-5, Gemini, etc.)
+    prev_path = config_dir() / "cursor-previous-settings.json"
+    previous = configure_cursor_for_proxy(matrx_proxy_url, mx_key)
+    if previous is not None:
+        prev_path.write_text(__import__("json").dumps(previous), encoding="utf-8")
     else:
-        print("Starting MTRX Cursor proxy service...")
-        if install_service(
-            matrx_key=mx_key,
-            matrx_base_url=matrx_base_url,
-            host=PROXY_HOST,
-            port=DEFAULT_PORT,
-        ):
-            print(f"  Proxy running on {proxy_url}")
-        else:
-            print("[warn] Proxy service may not have started. Check logs at:")
-            print(f"  {config_dir() / 'logs' / 'cursor-proxy.err.log'}")
-
-    # Step 4: Configure Cursor's settings.json
-    conf_dir = config_dir()
-    conf_dir.mkdir(parents=True, exist_ok=True)
+        print(
+            "[warn] Could not write Cursor state.vscdb. Try manual setup:",
+            file=sys.stderr,
+        )
+        print_manual_setup_instructions(matrx_proxy_url, api_key_hint="your Matrx key (mx_...)")
 
-    previous = configure_cursor_proxy_settings(
-        proxy_url=proxy_url,
-        ca_cert_path=str(ca_cert_path()),
-    )
-    prev_path = conf_dir / "cursor-proxy-previous-settings.json"
-    prev_path.write_text(_json.dumps(previous), encoding="utf-8")
+    # Hooks for session telemetry
+    install_mtrx_hooks(mx_key, matrx_base_url)
 
-    print()
-    print("Cursor configured to route ALL traffic through MTRX.")
-    print(f"  proxy:      {proxy_url}")
-    print(f"  ca_cert:    {ca_cert_path()}")
-    print(f"  telemetry:  {matrx_base_url}/v1/telemetry/cursor")
-    print()
-
-    # Launch Cursor with proxy env vars (required for traffic to flow)
+    # Optional: launch Cursor
     if getattr(args, "launch", False):
-        from matrx.cli.cursor_launcher import find_cursor_executable, launch_cursor_with_proxy
-
-        if launch_cursor_with_proxy(proxy_url, str(ca_cert_path())):
-            print("  Launched Cursor with proxy env vars — traffic will flow through MTRX.")
+        exe = find_cursor_executable()
+        if exe:
+            import subprocess
+            try:
+                subprocess.Popen([exe], start_new_session=True)
+                print("Launched Cursor.")
+            except Exception:
+                print("[warn] Could not launch Cursor.", file=sys.stderr)
         else:
-            print("  [warn] Could not launch Cursor. Is it installed?")
-            print("  To route traffic, launch Cursor via: mtrx cursor --launch")
-    else:
-        print("  To route traffic, launch Cursor via: mtrx cursor --launch")
-        print("  (Cursor must be started with proxy env vars; Dock/Spotlight launch won't work)")
+            print("[warn] Could not find Cursor executable.", file=sys.stderr)
+
+    print()
+    print("Cursor configured for MTRX — chat routes through Matrx (all models).")
+    print(f"  base URL: {matrx_proxy_url}")
     print()
+    print("  Works with any Cursor Pro model: Claude, GPT-5, Gemini, and more.")
+    print("  Restart Cursor for settings to take effect.")
     print("  Check status: mtrx cursor --status")
     print("  To disable:   mtrx use cursor direct")
     return 0

package/src/matrx/cli/state.py

@@ -46,6 +46,7 @@ DEFAULT_STATE: dict = {
     "defaults": {
         "codex": None,
         "claude": None,
+        "gemini": None,
         "cursor": None,
     },
     "workspaces": {
@@ -93,6 +94,19 @@ DEFAULT_STATE: dict = {
                 "previous_matrx_block": None,
                 "previous_values": {},
             },
+            "gemini": {
+                "configured": False,
+                "verified": False,
+                "config_path": None,
+                "backup_path": None,
+                "original_backup_path": None,
+                "config_fingerprint": None,
+                "matrx_key_fingerprint": None,
+                "last_verified_at": None,
+                "previous_model_provider": None,
+                "previous_matrx_block": None,
+                "previous_values": {},
+            },
         },
     },
 }