mtrx-cli 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrx-cli",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "MATRX CLI for routing Codex, Claude, and Cursor through Matrx",
   "homepage": "https://mtrx.so",
   "repository": {
@@ -31,6 +31,7 @@
     "src/matrx/cli/cursor_daemon.py",
     "src/matrx/cli/cursor_launcher.py",
     "src/matrx/cli/cursor_proxy.py",
+    "src/matrx/cli/cursor_reroute.py",
     "src/matrx/cli/cursor_service.py",
     "src/matrx/cli/launcher.py",
     "src/matrx/cli/main.py",

package/src/matrx/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.15"
+__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

@@ -62,25 +62,43 @@ 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"
@@ -97,9 +115,10 @@ def main() -> None:
             method="POST",
         )
         with urllib.request.urlopen(req, timeout=10) as resp:
-            pass
-    except Exception:
-        pass
+            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__":
@@ -118,7 +137,15 @@ def install_mtrx_hooks(matrx_key: str, matrx_base_url: str) -> bool:
         return False
 
     # Write hook script
-    _HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+    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")

package/src/matrx/cli/cursor_proxy.py

@@ -32,6 +32,16 @@ import httpx
 
 from matrx.cli.cursor_ca import CertCache, load_ca
 
+try:
+    from matrx.cli.cursor_reroute import is_ai_path, try_reroute_to_matrx
+except ImportError:
+    # Stubs when cursor_reroute not available (e.g. npm package omit).
+    def is_ai_path(path: str) -> bool:
+        return False
+
+    async def try_reroute_to_matrx(*, path: str, method: str, **kwargs: Any) -> None:
+        return None
+
 logger = logging.getLogger(__name__)
 
 DEFAULT_PORT = 8842
@@ -259,7 +269,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 +286,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 +397,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 +565,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/cursor_reroute.py

@@ -0,0 +1,76 @@
+"""
+Cursor → MTRX rerouting for live injection.
+
+When the MITM proxy intercepts Cursor's AI traffic (RunSSE, StreamCpp, etc.),
+this module reroutes it through MTRX instead of forwarding to Cursor's servers.
+That enables the full suite: memory injection, compression, loop guard, etc.
+
+Cursor uses Connect/gRPC protocol with binary protobuf. We parse the request,
+convert to OpenAI/Anthropic format, call MTRX, and convert the response back.
+
+Refs: cursor-tap (https://github.com/burpheart/cursor-tap), everestmz/cursor-rpc
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Cursor AI RPC paths (Connect protocol). RunSSE = main chat, StreamCpp = code completion.
+_AI_PATH_PATTERNS = (
+    r"RunSSE",
+    r"StreamCpp",
+    r"BidiAppend",
+    r"AgentService",
+    r"AiService",
+)
+
+
+def is_ai_path(path: str) -> bool:
+    """Return True if this path is an AI/LLM endpoint we should reroute to MTRX."""
+    if not path:
+        return False
+    return any(re.search(p, path, re.IGNORECASE) for p in _AI_PATH_PATTERNS)
+
+
+def _cursor_model_to_openai(cursor_model: str) -> str:
+    """Map Cursor model names to OpenAI-style names MTRX expects."""
+    # Cursor uses names like "claude-sonnet-4" or "gpt-4o" - usually compatible
+    normalized = (cursor_model or "").strip().lower()
+    if not normalized:
+        return "gpt-4o"  # fallback
+    return cursor_model
+
+
+async def try_reroute_to_matrx(
+    *,
+    path: str,
+    method: str,
+    req_headers: dict[str, str],
+    req_body: bytes,
+    matrx_base_url: str,
+    matrx_key: str,
+    session_id: str | None = None,
+    group_id: str | None = None,
+    project_id: str | None = None,
+) -> tuple[bool, dict[str, str], bytes | None, bool] | None:
+    """
+    Attempt to reroute a Cursor AI request through MTRX.
+
+    Returns:
+        (success, response_headers, response_body, is_streaming) if handled,
+        None to fall back to normal forward.
+    """
+    if method != "POST" or not is_ai_path(path):
+        return None
+
+    # TODO: Full protobuf parsing. Cursor uses Connect/gRPC with binary frames.
+    # For now we don't have the proto conversion - fall back to forward.
+    # When implemented: parse req_body, extract messages+model, call MTRX,
+    # convert response back to Cursor's gRPC format.
+    logger.debug("cursor_reroute: path=%s would reroute (protobuf conversion not yet implemented)", path)
+    return None

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")
@@ -553,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(
@@ -567,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"]:
@@ -589,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:
@@ -703,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}")
@@ -768,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")
@@ -842,22 +847,28 @@ def _cmd_launch(tool: str, route: str | None, remainder: list[str]) -> int:
 
 def _cmd_cursor(args) -> int:
     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: report hooks status
+    # --status: report Base URL override + hooks status
     if args.status:
-        if is_mtrx_hooks_installed():
-            print("MTRX Cursor hooks: active")
-            print("  sessionEnd, stop → telemetry to MTRX")
-        else:
-            print("MTRX Cursor hooks: not installed")
+        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
     if args.stop:
         _restore_cursor_if_needed()
-        print("Cursor route set to direct — MTRX hooks disabled.")
+        print("Cursor route set to direct — MTRX disabled.")
         return 0
 
     state = load_state()
@@ -866,12 +877,12 @@ def _cmd_cursor(args) -> int:
 
     if effective_route == "direct":
         _restore_cursor_if_needed()
-        print("Cursor route set to direct — MTRX hooks disabled.")
+        print("Cursor route set to direct — MTRX proxy disabled.")
         if cursor_is_running():
             print("  Restart Cursor for settings to take effect.")
         return 0
 
-    # --- matrx route: install Cursor Hooks (official, works like Claude/Codex) ---
+    # --- matrx route: Base URL override (works with any Cursor model: Claude, GPT, Gemini, etc.) ---
 
     try:
         state, login_changed = _complete_matrx_login(state)
@@ -895,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)
@@ -904,17 +916,42 @@ def _cmd_cursor(args) -> int:
             "Use `mtrx use cursor direct` to opt out.",
         )
 
-    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")
+    # 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("[warn] Could not install Cursor hooks. Check ~/.cursor/ is writable.", file=sys.stderr)
-        return 1
+        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_...)")
+
+    # Hooks for session telemetry
+    install_mtrx_hooks(mx_key, matrx_base_url)
+
+    # Optional: launch Cursor
+    if getattr(args, "launch", False):
+        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 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": {},
+            },
         },
     },
 }