mtrx-cli 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrx-cli",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "MATRX CLI for routing Codex, Claude, and Cursor through Matrx",
   "homepage": "https://mtrx.so",
   "repository": {
@@ -27,7 +27,9 @@
     "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",
     "src/matrx/cli/cursor_service.py",
     "src/matrx/cli/launcher.py",

package/src/matrx/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.13"
+__version__ = "0.1.15"

package/src/matrx/cli/cursor_hooks.py

@@ -0,0 +1,186 @@
+"""
+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 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 main() -> None:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        print("{}")
+        return
+    cfg_path = _config_path()
+    if not cfg_path.exists():
+        print("{}")
+        return
+    try:
+        cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        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:
+            pass
+    except Exception:
+        pass
+    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
+    _HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+    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_launcher.py

@@ -0,0 +1,106 @@
+"""
+Cross-platform launcher for Cursor IDE with proxy environment variables.
+
+Cursor must be started with HTTP_PROXY, HTTPS_PROXY, and NODE_EXTRA_CA_CERTS
+for the MITM proxy to work. Launching from Dock/Spotlight does not pass
+these env vars; this module finds the Cursor executable and launches it
+with the correct environment on any platform.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def _cursor_executable_darwin() -> str | None:
+    """macOS: /Applications/Cursor.app/Contents/MacOS/Cursor."""
+    app = Path("/Applications/Cursor.app")
+    exe = app / "Contents" / "MacOS" / "Cursor"
+    if exe.exists():
+        return str(exe)
+    return None
+
+
+def _cursor_executable_linux() -> str | None:
+    """Linux: cursor in PATH or common install locations."""
+    cursor = shutil.which("cursor")
+    if cursor:
+        return cursor
+    for path in (
+        Path.home() / ".local" / "share" / "cursor" / "bin" / "cursor",
+        Path.home() / ".local" / "bin" / "cursor",
+    ):
+        if path.exists():
+            return str(path)
+    return None
+
+
+def _cursor_executable_windows() -> str | None:
+    """Windows: Cursor.exe in Local AppData."""
+    local = os.environ.get("LOCALAPPDATA", "")
+    if local:
+        for parts in (("Programs", "cursor", "Cursor.exe"), ("Cursor", "Cursor.exe")):
+            exe = Path(local) / Path(*parts)
+            if exe.exists():
+                return str(exe)
+        alt = Path(local) / "cursor" / "Cursor.exe"
+        if alt.exists():
+            return str(alt)
+    return None
+
+
+def find_cursor_executable() -> str | None:
+    """Return the path to the Cursor executable for the current platform."""
+    system = platform.system()
+    if system == "Darwin":
+        return _cursor_executable_darwin()
+    if system == "Linux":
+        return _cursor_executable_linux()
+    if system == "Windows":
+        return _cursor_executable_windows()
+    return None
+
+
+def launch_cursor_with_proxy(
+    proxy_url: str,
+    ca_cert_path: str,
+) -> bool:
+    """
+    Launch Cursor with HTTP_PROXY, HTTPS_PROXY, and NODE_EXTRA_CA_CERTS set.
+
+    Returns True if Cursor was launched, False if executable not found.
+    """
+    exe = find_cursor_executable()
+    if not exe:
+        return False
+
+    env = os.environ.copy()
+    env["HTTP_PROXY"] = proxy_url
+    env["HTTPS_PROXY"] = proxy_url
+    env["NODE_EXTRA_CA_CERTS"] = str(ca_cert_path)
+
+    kwargs: dict = {}
+    if platform.system() == "Windows":
+        kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.DETACHED_PROCESS
+
+    try:
+        subprocess.Popen(
+            [exe],
+            env=env,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=(platform.system() != "Windows"),
+            **kwargs,
+        )
+        return True
+    except OSError as exc:
+        logger.warning("Failed to launch Cursor: %s", exc)
+        return False

package/src/matrx/cli/main.py

@@ -120,6 +120,11 @@ def _build_parser() -> argparse.ArgumentParser:
     cursor.add_argument("--route", choices=["direct", "matrx"])
     cursor.add_argument("--status", action="store_true", help="Check proxy status")
     cursor.add_argument("--stop", action="store_true", help="Stop the proxy service")
+    cursor.add_argument(
+        "--launch",
+        action="store_true",
+        help="Launch Cursor with proxy env (required for traffic to flow)",
+    )
 
     return parser
 
@@ -501,8 +506,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()
@@ -831,39 +841,23 @@ 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_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
 
     route = args.route
 
-    # --status: just report proxy health
+    # --status: report hooks status
     if args.status:
-        status = get_proxy_status()
-        if status:
-            print("MTRX Cursor proxy: running")
-            print(f"  requests processed: {status.get('requests', '?')}")
+        if is_mtrx_hooks_installed():
+            print("MTRX Cursor hooks: active")
+            print("  sessionEnd, stop → telemetry to MTRX")
         else:
-            print("MTRX Cursor proxy: not running")
+            print("MTRX Cursor hooks: not installed")
         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 hooks disabled.")
         return 0
 
     state = load_state()
@@ -872,12 +866,12 @@ def _cmd_cursor(args) -> int:
 
     if effective_route == "direct":
         _restore_cursor_if_needed()
-        print("Cursor route set to direct — MTRX proxy disabled.")
+        print("Cursor route set to direct — MTRX hooks disabled.")
         if cursor_is_running():
             print("  Restart Cursor for settings to take effect.")
         return 0
 
-    # --- matrx route: set up the MITM proxy ---
+    # --- matrx route: install Cursor Hooks (official, works like Claude/Codex) ---
 
     try:
         state, login_changed = _complete_matrx_login(state)
@@ -910,66 +904,17 @@ 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}")
-    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)
-
-    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")
-
-    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()
-    if cursor_is_running():
-        print("  Cursor is running — restart it for settings to take effect.")
+    if install_mtrx_hooks(mx_key, matrx_base_url):
+        print()
+        print("Cursor configured with MTRX hooks — Chat & Agent usage flows to MTRX.")
+        print(f"  telemetry:  {matrx_base_url}/v1/telemetry/cursor/hooks")
+        print()
+        print("  Works with Cursor from Dock, Spotlight, or CLI — no special launch needed.")
+        print("  Check status: mtrx cursor --status")
+        print("  To disable:   mtrx use cursor direct")
     else:
-        print("  Settings will apply next time Cursor starts.")
-    print()
-    print("  Check status: mtrx cursor --status")
-    print("  To disable:   mtrx use cursor direct")
+        print("[warn] Could not install Cursor hooks. Check ~/.cursor/ is writable.", file=sys.stderr)
+        return 1
     return 0