mtrx-cli 0.1.28 → 0.1.29

package/README.md

@@ -30,3 +30,19 @@ npx mtrx help
 - Python 3.10+ available as `python3`, `python`, or `py -3`
 
 This npm package is a thin wrapper around the Python CLI bundled in this repo.
+
+## Python dependencies
+
+The tarball only ships the CLI source under `src/` and sets `PYTHONPATH` so Python can import it. **Third-party libraries** (for example `httpx`, `fastapi`, etc.) are **not** bundled—you still need the **`matrx`** Python package installed into the same interpreter npm invokes:
+
+```bash
+pip install matrx
+```
+
+Or from a checkout of this repo:
+
+```bash
+pip install -e .
+```
+
+Use `mtrx doctor` after install if commands fail with missing-module errors.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mtrx-cli",
-  "version": "0.1.28",
-  "description": "MATRX CLI for routing Codex, Claude, and Cursor through Matrx",
+  "version": "0.1.29",
+  "description": "MATRX CLI for routing Codex, Claude, Gemini, and Cursor through Matrx",
   "homepage": "https://mtrx.so",
   "repository": {
     "type": "git",
@@ -35,6 +35,8 @@
     "src/matrx/cli/cursor_service.py",
     "src/matrx/cli/bootstrap.py",
     "src/matrx/cli/gemini_env_bootstrap.cjs",
+    "src/matrx/cli/indexer.py",
+    "src/matrx/cli/agent_cmds.py",
     "src/matrx/cli/launcher.py",
     "src/matrx/cli/main.py",
     "src/matrx/cli/project_cmds.py",

package/src/matrx/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.27"
+__version__ = "0.1.29"

package/src/matrx/cli/agent_cmds.py

@@ -0,0 +1,390 @@
+"""
+CLI commands for real-time agent coordination.
+
+mtrx agents list   [--group <id>]        — show agents active in the group right now
+mtrx agents push   <target> <prompt>     — push a task into another agent's inbox
+mtrx agents watch  [--group <id>]        — stream group events to the terminal (SSE)
+mtrx agents status [--group <id>]        — show this workspace's group/agent identity
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from datetime import datetime, timezone
+
+import httpx
+
+from matrx.cli.state import (
+    ensure_root_url,
+    get_workspace_binding,
+    load_state,
+    normalize_matrx_key,
+    resolve_workspace_root,
+)
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers (mirror pattern from project_cmds.py)
+# ---------------------------------------------------------------------------
+
+def _api(
+    state: dict,
+    *,
+    method: str,
+    path: str,
+    key: str,
+    json_body: dict | None = None,
+    params: dict | None = None,
+    timeout: float = 15.0,
+) -> dict:
+    base_url = ensure_root_url(state.get("auth", {}).get("matrx", {}).get("base_url"))
+    url = f"{base_url.rstrip('/')}/v1{path}"
+    headers: dict[str, str] = {"X-Matrx-Key": key}
+    if json_body is not None:
+        headers["Content-Type"] = "application/json"
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            response = client.request(
+                method, url, headers=headers, json=json_body, params=params
+            )
+    except httpx.HTTPError as exc:
+        raise ValueError(f"Matrx API request failed: {exc}") from exc
+    if response.status_code >= 400:
+        detail = response.text.strip() or response.reason_phrase
+        raise ValueError(
+            f"Matrx API error ({response.status_code}) for {path}: {detail}"
+        )
+    if response.status_code == 204 or not response.content:
+        return {}
+    return response.json()
+
+
+def _resolve_key(state: dict) -> str:
+    env_key = normalize_matrx_key(os.environ.get("MTRX_KEY"))
+    if env_key:
+        return env_key
+    binding = get_workspace_binding(state, cwd=os.getcwd()) or {}
+    binding_key = normalize_matrx_key(binding.get("matrx_key"))
+    if binding_key:
+        return binding_key
+    return normalize_matrx_key(
+        state.get("auth", {}).get("matrx", {}).get("key")
+    )
+
+
+def _require_key(state: dict) -> str:
+    key = _resolve_key(state)
+    if not key:
+        raise ValueError("No Matrx key found. Run: mtrx login matrx --key mx_...")
+    return key
+
+
+def _resolve_group_id(state: dict, args_group_id: str | None = None) -> str | None:
+    """Return the group_id to use: explicit flag > env var > workspace binding."""
+    if args_group_id:
+        return args_group_id.strip()
+    env_group = (os.environ.get("MTRX_GROUP_ID") or "").strip()
+    if env_group:
+        return env_group
+    binding = get_workspace_binding(state, cwd=os.getcwd()) or {}
+    return (binding.get("group_id") or "").strip() or None
+
+
+def _resolve_agent_id(args_agent_id: str | None = None) -> str | None:
+    """Return the agent_id: explicit flag > env var."""
+    if args_agent_id:
+        return args_agent_id.strip()
+    return (os.environ.get("MTRX_AGENT_ID") or "").strip() or None
+
+
+def _fmt_time(ts: float | None) -> str:
+    if ts is None:
+        return "—"
+    try:
+        dt = datetime.fromtimestamp(float(ts), tz=timezone.utc)
+        return dt.strftime("%H:%M:%S UTC")
+    except (ValueError, OSError):
+        return str(ts)
+
+
+# ---------------------------------------------------------------------------
+# mtrx agents list
+# ---------------------------------------------------------------------------
+
+def cmd_list(args) -> int:
+    """Show agents currently active in the group."""
+    state = load_state()
+    try:
+        key = _require_key(state)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    group_id = _resolve_group_id(state, getattr(args, "group", None))
+
+    if not group_id:
+        # Try to resolve via server
+        try:
+            ctx = _api(state, method="GET", path="/auth/context", key=key)
+            group_id = (ctx.get("default_group_id") or "").strip() or None
+        except ValueError:
+            pass
+
+    if not group_id:
+        print(
+            "No group_id set. Use --group <id>, set MTRX_GROUP_ID, or run: mtrx project switch",
+            file=sys.stderr,
+        )
+        return 1
+
+    include_history = getattr(args, "history", False)
+    try:
+        params: dict = {}
+        if include_history:
+            params["include_history"] = "true"
+            params["limit"] = str(getattr(args, "limit", 10))
+        data = _api(
+            state,
+            method="GET",
+            path=f"/groups/{group_id}/activity",
+            key=key,
+            params=params if params else None,
+        )
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    agents = data.get("active_agents", [])
+    if not agents:
+        print(f"No active agents in group {group_id}")
+    else:
+        print(f"Active agents in group {group_id}:\n")
+        print(f"  {'AGENT ID':<28} {'MODEL':<20} {'STARTED':<12}  TASK")
+        print("  " + "─" * 80)
+        for a in agents:
+            agent_id = str(a.get("agent_id", "?"))
+            model = str(a.get("model", "?"))[:18]
+            started = _fmt_time(a.get("started_at"))
+            task = str(a.get("task_summary", ""))[:60]
+            print(f"  {agent_id:<28} {model:<20} {started:<12}  {task}")
+
+    if include_history:
+        recent = data.get("recent_activities", [])
+        if recent:
+            print(f"\nRecent activities:")
+            for act in recent:
+                status = act.get("status", "?")
+                aid = str(act.get("agent_id", "?"))
+                summary = str(act.get("task_summary", ""))[:60]
+                completed = act.get("completed_at", "")
+                print(f"  [{status}] {aid}: {summary}  ({completed})")
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# mtrx agents push
+# ---------------------------------------------------------------------------
+
+def cmd_push(args) -> int:
+    """Push a task prompt into another agent's inbox."""
+    state = load_state()
+    try:
+        key = _require_key(state)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    target_agent_id = (getattr(args, "target", "") or "").strip()
+    if not target_agent_id:
+        print(
+            "Usage: mtrx agents push <target-agent-id> <prompt>",
+            file=sys.stderr,
+        )
+        return 1
+
+    prompt_parts = getattr(args, "prompt_parts", [])
+    prompt = " ".join(prompt_parts).strip() if prompt_parts else ""
+    if not prompt:
+        print("prompt must not be blank", file=sys.stderr)
+        return 1
+
+    group_id = _resolve_group_id(state, getattr(args, "group", None))
+    from_agent_id = _resolve_agent_id(getattr(args, "from_agent", None)) or "cli"
+
+    body: dict = {
+        "prompt": prompt,
+        "target_agent_id": target_agent_id,
+        "from_agent_id": from_agent_id,
+    }
+    if group_id:
+        body["group_id"] = group_id
+
+    try:
+        resp = _api(state, method="POST", path="/inbox/push", key=key, json_body=body)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    count = resp.get("count", "?")
+    gid = group_id or "(default)"
+    print(f"Task pushed to {target_agent_id} in group {gid} (queue depth: {count})")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# mtrx agents watch
+# ---------------------------------------------------------------------------
+
+def cmd_watch(args) -> int:
+    """Stream group events to the terminal over SSE."""
+    state = load_state()
+    try:
+        key = _require_key(state)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    group_id = _resolve_group_id(state, getattr(args, "group", None))
+    if not group_id:
+        print(
+            "No group_id set. Use --group <id> or set MTRX_GROUP_ID.",
+            file=sys.stderr,
+        )
+        return 1
+
+    base_url = ensure_root_url(
+        state.get("auth", {}).get("matrx", {}).get("base_url")
+    )
+
+    # Obtain a short-lived SSE token so we don't need to pass the API key in a
+    # persistent connection header.
+    try:
+        token_resp = _api(
+            state,
+            method="GET",
+            path=f"/groups/{group_id}/stream-token",
+            key=key,
+        )
+    except ValueError as exc:
+        print(f"Could not get stream token: {exc}", file=sys.stderr)
+        return 1
+
+    token = token_resp.get("token")
+    if not token:
+        print("Server did not return an SSE token.", file=sys.stderr)
+        return 1
+
+    stream_url = (
+        f"{base_url.rstrip('/')}/v1/groups/{group_id}/stream"
+        f"?sse_token={token}"
+    )
+
+    print(f"Watching group {group_id} (Ctrl-C to stop)...")
+    print()
+
+    try:
+        with httpx.Client(timeout=None) as client:
+            with client.stream("GET", stream_url) as resp:
+                if resp.status_code != 200:
+                    print(
+                        f"Stream error: HTTP {resp.status_code}",
+                        file=sys.stderr,
+                    )
+                    return 1
+                for line in resp.iter_lines():
+                    if not line:
+                        continue
+                    if line.startswith(": keepalive"):
+                        continue
+                    if line.startswith("data: "):
+                        raw = line[6:]
+                        try:
+                            evt = json.loads(raw)
+                            _print_event(evt)
+                        except json.JSONDecodeError:
+                            print(raw)
+    except KeyboardInterrupt:
+        print("\nStopped.")
+    except httpx.HTTPError as exc:
+        print(f"Stream error: {exc}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def _print_event(evt: dict) -> None:
+    ts = datetime.now(tz=timezone.utc).strftime("%H:%M:%S")
+    etype = evt.get("type", "event")
+    model = evt.get("model", "")
+    provider = evt.get("provider", "")
+    agent = evt.get("agent_id", "?")
+    tokens_in = evt.get("input_tokens", 0)
+    tokens_out = evt.get("output_tokens", 0)
+    status_code = evt.get("status_code", "")
+    latency = evt.get("latency_ms")
+    latency_str = f"{latency:.0f}ms" if latency else ""
+
+    # Colour codes (simple; no dependency)
+    GREEN, DIM, RESET = "\033[32m", "\033[2m", "\033[0m"
+    ok = status_code == 200 or status_code == ""
+    colour = GREEN if ok else "\033[31m"
+
+    print(
+        f"{DIM}{ts}{RESET} "
+        f"{colour}[{etype}]{RESET} "
+        f"agent={agent} "
+        f"model={model}/{provider} "
+        f"in={tokens_in} out={tokens_out} "
+        f"{latency_str}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# mtrx agents status
+# ---------------------------------------------------------------------------
+
+def cmd_status(args) -> int:
+    """Show this workspace's group / agent binding."""
+    state = load_state()
+    workspace_root = resolve_workspace_root(os.getcwd())
+    binding = get_workspace_binding(state, cwd=os.getcwd()) or {}
+
+    group_id = _resolve_group_id(state, getattr(args, "group", None))
+    agent_id = _resolve_agent_id(getattr(args, "agent", None))
+
+    print(f"Workspace:  {workspace_root}")
+    print(f"Group ID:   {group_id or '(not set)'}")
+    print(f"Agent ID:   {agent_id or '(not set)'}")
+
+    env_group = (os.environ.get("MTRX_GROUP_ID") or "").strip()
+    env_agent = (os.environ.get("MTRX_AGENT_ID") or "").strip()
+    if env_group:
+        print(f"  group from MTRX_GROUP_ID env var")
+    elif binding.get("group_id"):
+        print(f"  group from workspace binding")
+    if env_agent:
+        print(f"  agent from MTRX_AGENT_ID env var")
+
+    if not group_id:
+        print("\nTip: mtrx agents list --group <id>  OR  export MTRX_GROUP_ID=<id>")
+        return 0
+
+    # Fetch live count
+    try:
+        key = _require_key(state)
+        data = _api(
+            state,
+            method="GET",
+            path=f"/groups/{group_id}/activity",
+            key=key,
+        )
+        count = len(data.get("active_agents", []))
+        print(f"\nActive agents in group: {count}")
+    except ValueError:
+        pass
+
+    return 0

package/src/matrx/cli/bootstrap.py

@@ -5,9 +5,17 @@ Called by `mtrx init`.
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 from pathlib import Path
 
+from matrx.cli.state import (
+    get_workspace_binding,
+    load_state,
+    normalize_matrx_key,
+    resolve_workspace_root,
+)
+
 _DEFAULT_SYSTEMS_TEMPLATE = [
     {
         "id": "memory",
@@ -36,9 +44,9 @@ _DEFAULT_SYSTEMS_TEMPLATE = [
 ]
 
 
-def run_init(project_root: str = ".") -> None:
+def run_init(project_root: str = ".", *, refresh: bool = False) -> None:
     """Entry point for `mtrx init`."""
-    root = Path(project_root).resolve()
+    root = Path(resolve_workspace_root(project_root)).resolve()
     print(f"Matrx init: analyzing {root}")
 
     # Step 1: Load or create .matrx/systems.json
@@ -69,11 +77,59 @@ def run_init(project_root: str = ".") -> None:
     else:
         print("\n  No recently active systems detected (no git history or no matches).")
 
-    print(f"\n  Matrx will generate cards for detected systems on first use.")
-    print(f"  Run your agent — cards will be ready within the first few calls.\n")
+    print("\n  Matrx will generate cards for detected systems on first use.")
+    print("  Run your agent — cards will be ready within the first few calls.\n")
+
+    if refresh:
+        _refresh_llm_profile(root)
+
     print("  Done.")
 
 
+def _refresh_llm_profile(root: Path) -> None:
+    from matrx.cli.indexer import (
+        clear_init_cache,
+        resolve_project_id_for_launch,
+        trigger_index,
+    )
+
+    state = load_state()
+    key = _resolved_matrx_key(state, cwd=str(root))
+    if not key:
+        print("  Skipped codebase re-profile: Matrx login required.")
+        return
+
+    project_id = resolve_project_id_for_launch(state, key, cwd=str(root))
+    if not project_id:
+        print(
+            "  Skipped codebase re-profile: no Matrx project resolved for this workspace."
+        )
+        return
+
+    clear_init_cache(project_id)
+    print("  Profiling your codebase - this takes ~10 seconds...")
+    trigger_index(
+        state,
+        key,
+        cwd=str(root),
+        blocking=True,
+        timeout=30,
+        force_llm_profile=True,
+    )
+    print("  Codebase profile refresh requested.")
+
+
+def _resolved_matrx_key(state: dict, *, cwd: str) -> str:
+    env_key = normalize_matrx_key(os.environ.get("MTRX_KEY"))
+    if env_key:
+        return env_key
+    workspace_binding = get_workspace_binding(state, cwd=cwd) or {}
+    workspace_key = normalize_matrx_key(workspace_binding.get("matrx_key"))
+    if workspace_key:
+        return workspace_key
+    return normalize_matrx_key(state.get("auth", {}).get("matrx", {}).get("key")) or ""
+
+
 def _get_hot_files(root: Path, days: int = 30) -> dict[str, int]:
     """Parse git log, return file → touch count mapping."""
     try:

package/src/matrx/cli/indexer.py

@@ -0,0 +1,513 @@
+"""
+Background project indexer.
+
+When `mtrx claude/codex/gemini/cursor` is launched inside a git repo, this
+module fires a fire-and-forget daemon thread that deterministically scans the
+workspace and ships structural facts (languages, frameworks, manifests,
+top-level directories) to the Matrx backend, which persists them as
+PROJECT_FACT / STRUCTURE memories scoped to the matching project.
+
+Project resolution:
+  1. Existing workspace binding (~/.config/mtrx/state.json) wins.
+  2. Otherwise, match the git remote URL against project.repo_url in the org.
+  3. If neither resolves, the index is silently skipped.
+
+Re-index throttle: skipped if last run was <24h ago AND the file-list hash
+is unchanged.
+
+The thread never prints on success and never raises into the launcher.
+"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import os
+import re
+import subprocess
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+import httpx
+
+from matrx.cli.state import (
+    ensure_root_url,
+    get_workspace_binding,
+    load_state,
+    resolve_workspace_root,
+    save_state,
+)
+
+INDEX_MIN_INTERVAL_SEC = 24 * 3600
+INDEX_HTTP_TIMEOUT_SEC = 60
+_MAX_FILE_SIZE = 256 * 1024
+_MAX_FILES_FOR_IMPORT_SCAN = 400
+_SKIP_TOP_DIRS = {"node_modules", "dist", "build", "__pycache__", ".venv", "venv", ".next"}
+
+_LANG_BY_EXT: dict[str, str] = {
+    ".py": "Python",
+    ".js": "JavaScript",
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".jsx": "JavaScript",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".rb": "Ruby",
+    ".java": "Java",
+    ".kt": "Kotlin",
+    ".swift": "Swift",
+    ".cpp": "C++",
+    ".cc": "C++",
+    ".c": "C",
+    ".cs": "C#",
+    ".php": "PHP",
+    ".sh": "Shell",
+    ".sql": "SQL",
+}
+
+_FRAMEWORK_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"\b(?:from|import)\s+fastapi\b"), "FastAPI"),
+    (re.compile(r"\b(?:from|import)\s+flask\b"), "Flask"),
+    (re.compile(r"\b(?:from|import)\s+django\b"), "Django"),
+    (re.compile(r"\bfrom\s+sqlalchemy\b"), "SQLAlchemy"),
+    (re.compile(r"\bfrom\s+pydantic\b"), "Pydantic"),
+    (re.compile(r"\bimport\s+pandas\b"), "pandas"),
+    (re.compile(r"\bimport\s+numpy\b"), "NumPy"),
+    (re.compile(r"\bimport\s+torch\b"), "PyTorch"),
+    (re.compile(r"\bimport\s+tensorflow\b"), "TensorFlow"),
+    (re.compile(r"""from\s+['"]react['"]"""), "React"),
+    (re.compile(r"""from\s+['"]vue['"]"""), "Vue"),
+    (re.compile(r"""from\s+['"]next(?:/|['"])"""), "Next.js"),
+    (re.compile(r"""from\s+['"]express['"]"""), "Express"),
+    (re.compile(r"""from\s+['"]fastify['"]"""), "Fastify"),
+    (re.compile(r"""from\s+['"]@nestjs/"""), "NestJS"),
+    (re.compile(r"""from\s+['"]@angular/"""), "Angular"),
+    (re.compile(r"""from\s+['"]svelte['"]"""), "Svelte"),
+    (re.compile(r"""from\s+['"]tailwindcss['"]"""), "Tailwind"),
+]
+
+_MANIFEST_FILES: tuple[str, ...] = (
+    "package.json",
+    "pyproject.toml",
+    "requirements.txt",
+    "Cargo.toml",
+    "go.mod",
+    "Gemfile",
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts",
+    "composer.json",
+    "tsconfig.json",
+    "Dockerfile",
+)
+
+_PROFILE_MANIFEST_FILES: tuple[str, ...] = (
+    "pyproject.toml",
+    "requirements.txt",
+    "package.json",
+    "go.mod",
+    "Cargo.toml",
+)
+
+
+# ---------------------------------------------------------------------------
+# Git helpers
+# ---------------------------------------------------------------------------
+
+def _git_tracked_files(root: Path) -> list[str] | None:
+    """Return tracked + untracked-not-ignored files (relative). None if not a git repo."""
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(root), "ls-files", "-co", "--exclude-standard"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    return [ln.strip() for ln in result.stdout.splitlines() if ln.strip()]
+
+
+def _git_remote_url(root: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(root), "remote", "get-url", "origin"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def _normalize_remote_url(url: str) -> str:
+    u = url.strip()
+    if u.startswith("git@"):
+        # git@github.com:org/repo.git -> https://github.com/org/repo
+        host_path = u[len("git@") :].replace(":", "/", 1)
+        u = f"https://{host_path}"
+    # Strip scheme + embedded credentials
+    u = re.sub(r"^[a-zA-Z][a-zA-Z0-9+.-]*://(?:[^@/]+@)?", "https://", u)
+    u = u.rstrip("/")
+    if u.endswith(".git"):
+        u = u[:-4]
+    return u.lower()
+
+
+# ---------------------------------------------------------------------------
+# Deterministic scan
+# ---------------------------------------------------------------------------
+
+def _detect_languages(files: list[str]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for f in files:
+        ext = os.path.splitext(f)[1].lower()
+        lang = _LANG_BY_EXT.get(ext)
+        if lang:
+            counts[lang] = counts.get(lang, 0) + 1
+    return counts
+
+
+def _detect_frameworks(root: Path, files: list[str]) -> list[str]:
+    frameworks: set[str] = set()
+    scan_targets = [
+        f
+        for f in files
+        if os.path.splitext(f)[1].lower() in {".py", ".ts", ".tsx", ".js", ".jsx"}
+    ][:_MAX_FILES_FOR_IMPORT_SCAN]
+
+    for rel in scan_targets:
+        path = root / rel
+        try:
+            if path.stat().st_size > _MAX_FILE_SIZE:
+                continue
+            text = path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        for patt, name in _FRAMEWORK_PATTERNS:
+            if name not in frameworks and patt.search(text):
+                frameworks.add(name)
+    return sorted(frameworks)
+
+
+def _top_level_dirs(files: list[str]) -> list[str]:
+    dirs: dict[str, int] = {}
+    for f in files:
+        if "/" not in f:
+            continue
+        top = f.split("/", 1)[0]
+        if top.startswith(".") or top in _SKIP_TOP_DIRS:
+            continue
+        dirs[top] = dirs.get(top, 0) + 1
+    return [d for d, _ in sorted(dirs.items(), key=lambda kv: (-kv[1], kv[0]))[:10]]
+
+
+def _detect_manifests(root: Path, files: list[str]) -> dict[str, dict]:
+    tracked = set(files)
+    found: dict[str, dict] = {}
+    for name in _MANIFEST_FILES:
+        if name not in tracked:
+            continue
+        entry: dict = {"name": name}
+        path = root / name
+        try:
+            raw = path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            raw = ""
+        entry["size"] = len(raw)
+        if name == "package.json" and raw:
+            try:
+                parsed = json.loads(raw)
+                if isinstance(parsed, dict):
+                    if parsed.get("name"):
+                        entry["package_name"] = str(parsed["name"])
+                    dep_count = 0
+                    for field in ("dependencies", "devDependencies", "peerDependencies"):
+                        value = parsed.get(field)
+                        if isinstance(value, dict):
+                            dep_count += len(value)
+                    entry["dep_count"] = dep_count
+            except (ValueError, TypeError):
+                pass
+        found[name] = entry
+    return found
+
+
+def _read_truncated(path: Path, *, limit: int) -> str | None:
+    try:
+        text = path.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return None
+    return text[:limit]
+
+
+def _read_manifest_texts(root: Path, files: list[str], *, limit: int) -> dict[str, str]:
+    tracked = set(files)
+    texts: dict[str, str] = {}
+    for name in _PROFILE_MANIFEST_FILES:
+        if name not in tracked:
+            continue
+        text = _read_truncated(root / name, limit=limit)
+        if text:
+            texts[name] = text
+    return texts
+
+
+def build_index_payload(
+    root: Path,
+    *,
+    trigger_llm_profile: bool = False,
+) -> dict | None:
+    """Build the structural payload. Returns None if not a git repo."""
+    files = _git_tracked_files(root)
+    if files is None:
+        return None
+
+    h = hashlib.sha256()
+    for f in sorted(files):
+        h.update(f.encode("utf-8"))
+        h.update(b"\n")
+
+    return {
+        "workspace_root": str(root),
+        "file_count": len(files),
+        "file_list_hash": h.hexdigest(),
+        "languages": _detect_languages(files),
+        "frameworks": _detect_frameworks(root, files),
+        "top_directories": _top_level_dirs(files),
+        "manifests": _detect_manifests(root, files),
+        "readme": _read_truncated(root / "README.md", limit=4000),
+        "manifest_texts": _read_manifest_texts(root, files, limit=2000),
+        "trigger_llm_profile": trigger_llm_profile,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Project resolution
+# ---------------------------------------------------------------------------
+
+def _resolve_project_id(state: dict, key: str, root: Path) -> str | None:
+    binding = get_workspace_binding(state, cwd=str(root)) or {}
+    bound_id = (binding.get("project_id") or "").strip()
+    if bound_id:
+        return bound_id
+
+    remote = _git_remote_url(root)
+    if not remote:
+        return None
+    target = _normalize_remote_url(remote)
+
+    base_url = ensure_root_url(
+        state.get("auth", {}).get("matrx", {}).get("base_url")
+    ).rstrip("/")
+    headers = {"X-Matrx-Key": key}
+
+    try:
+        with httpx.Client(timeout=10) as client:
+            ctx_resp = client.get(f"{base_url}/v1/auth/context", headers=headers)
+            if ctx_resp.status_code != 200:
+                return None
+            org_id = (ctx_resp.json().get("org_id") or "").strip()
+            if not org_id:
+                return None
+
+            list_resp = client.get(
+                f"{base_url}/v1/orgs/{org_id}/projects", headers=headers
+            )
+            if list_resp.status_code != 200:
+                return None
+            payload = list_resp.json()
+    except (httpx.HTTPError, ValueError):
+        return None
+
+    items = payload if isinstance(payload, list) else payload.get("projects", [])
+    for project in items:
+        repo_url = (project.get("repo_url") or "").strip()
+        if repo_url and _normalize_remote_url(repo_url) == target:
+            return project.get("id")
+    return None
+
+
+def resolve_project_id_for_launch(
+    state: dict,
+    key: str,
+    *,
+    cwd: str | None = None,
+) -> str | None:
+    if not key:
+        return None
+    root = Path(resolve_workspace_root(cwd or os.getcwd()))
+    if not (root / ".git").exists():
+        return None
+    return _resolve_project_id(state, key, root)
+
+
+# ---------------------------------------------------------------------------
+# Cache + HTTP
+# ---------------------------------------------------------------------------
+
+def _should_skip(state: dict, project_id: str, *, file_list_hash: str) -> bool:
+    cache = state.get("index_cache", {})
+    entry = cache.get(project_id)
+    if not isinstance(entry, dict):
+        return False
+    if entry.get("file_list_hash") != file_list_hash:
+        return False
+    ts = str(entry.get("last_indexed_at") or "")
+    try:
+        last = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    except ValueError:
+        return False
+    age = (datetime.now(timezone.utc) - last).total_seconds()
+    return age < INDEX_MIN_INTERVAL_SEC
+
+
+def _record_cache(project_id: str, *, file_list_hash: str, workspace_root: str) -> None:
+    latest = load_state()
+    cache = latest.setdefault("index_cache", {})
+    cache[project_id] = {
+        "file_list_hash": file_list_hash,
+        "workspace_root": workspace_root,
+        "last_indexed_at": datetime.now(timezone.utc)
+        .isoformat(timespec="seconds")
+        .replace("+00:00", "Z"),
+    }
+    save_state(latest)
+
+
+def has_been_inited(state: dict, project_id: str) -> bool:
+    return project_id in state.get("init_cache", {})
+
+
+def _record_init(project_id: str) -> None:
+    latest = load_state()
+    inited_at = (
+        datetime.now(timezone.utc)
+        .isoformat(timespec="seconds")
+        .replace("+00:00", "Z")
+    )
+    latest.setdefault("init_cache", {})[project_id] = {
+        "inited_at": inited_at,
+    }
+    save_state(latest)
+
+
+def clear_init_cache(project_id: str) -> None:
+    latest = load_state()
+    cache = latest.setdefault("init_cache", {})
+    if project_id in cache:
+        cache.pop(project_id, None)
+        save_state(latest)
+
+
+def _post_index(base_url: str, key: str, project_id: str, payload: dict) -> dict | None:
+    url = f"{base_url.rstrip('/')}/v1/projects/{project_id}/index"
+    try:
+        with httpx.Client(timeout=INDEX_HTTP_TIMEOUT_SEC) as client:
+            resp = client.post(
+                url,
+                headers={"X-Matrx-Key": key, "Content-Type": "application/json"},
+                json=payload,
+            )
+    except httpx.HTTPError:
+        return None
+    if resp.status_code >= 400:
+        return None
+    try:
+        data = resp.json()
+    except ValueError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+# ---------------------------------------------------------------------------
+# Thread entry point
+# ---------------------------------------------------------------------------
+
+def _run_index(
+    state_snapshot: dict,
+    key: str,
+    root: Path,
+    *,
+    force_llm_profile: bool = False,
+) -> None:
+    try:
+        project_id = _resolve_project_id(state_snapshot, key, root)
+        if not project_id:
+            return
+
+        is_first_run = force_llm_profile or not has_been_inited(state_snapshot, project_id)
+        payload = build_index_payload(root, trigger_llm_profile=is_first_run)
+        if not payload:
+            return
+
+        if not is_first_run and _should_skip(
+            state_snapshot, project_id, file_list_hash=payload["file_list_hash"]
+        ):
+            return
+
+        base_url = ensure_root_url(
+            state_snapshot.get("auth", {}).get("matrx", {}).get("base_url")
+        )
+        response_data = _post_index(base_url, key, project_id, payload)
+        if response_data is None:
+            return
+
+        if is_first_run:
+            _record_init(project_id)
+
+        _record_cache(
+            project_id,
+            file_list_hash=payload["file_list_hash"],
+            workspace_root=str(root),
+        )
+    except Exception:
+        # Background task — never crash the launcher.
+        return
+
+
+def trigger_index(
+    state: dict,
+    key: str,
+    *,
+    cwd: str | None = None,
+    blocking: bool = False,
+    timeout: float | None = None,
+    force_llm_profile: bool = False,
+) -> None:
+    """Start an index run. Silent on success and failure."""
+    if not key:
+        return
+    root = Path(resolve_workspace_root(cwd or os.getcwd()))
+    if not (root / ".git").exists():
+        return
+    snapshot = copy.deepcopy(state)
+    thread = threading.Thread(
+        target=_run_index,
+        args=(snapshot, key, root),
+        kwargs={"force_llm_profile": force_llm_profile},
+        name="mtrx-indexer",
+        daemon=True,
+    )
+    thread.start()
+    if blocking:
+        thread.join(timeout=timeout)
+
+
+def trigger_background_index(
+    state: dict,
+    key: str,
+    *,
+    cwd: str | None = None,
+) -> None:
+    """Fire-and-forget index on a daemon thread. Silent on success and failure."""
+    trigger_index(state, key, cwd=cwd)

package/src/matrx/cli/main.py

@@ -80,7 +80,7 @@ def main(argv: list[str] | None = None) -> int:
         return _cmd_cursor(args)
     if args.command == "init":
         from matrx.cli.bootstrap import run_init
-        run_init()
+        run_init(refresh=getattr(args, "refresh", False))
         return 0
     if args.command == "project":
         return _cmd_project(args)
@@ -112,7 +112,15 @@ def _build_parser() -> argparse.ArgumentParser:
     subparsers.add_parser("version")
     subparsers.add_parser("status")
     subparsers.add_parser("doctor")
-    subparsers.add_parser("init", help="Initialize Matrx for an existing project (seeds system registry)")
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Initialize Matrx for an existing project (seeds system registry)",
+    )
+    init_parser.add_argument(
+        "--refresh",
+        action="store_true",
+        help="Force re-profile the codebase",
+    )
 
     personal = subparsers.add_parser("personal")
     personal_subparsers = personal.add_subparsers(dest="personal_command")
@@ -1112,20 +1120,31 @@ def _cmd_launch(tool: str, route: str | None, remainder: list[str]) -> int:
         return 1
 
     if effective_route == "matrx":
-        try:
-            from matrx.cli.indexer import trigger_background_index
-
-            trigger_background_index(
-                state,
-                _resolved_matrx_key(state, os.environ),
-                cwd=os.getcwd(),
-            )
-        except Exception:
-            pass
+        _trigger_index_for_launch(state, _resolved_matrx_key(state, os.environ))
 
     return launch(plan)
 
 
+def _trigger_index_for_launch(state: dict, key: str) -> None:
+    try:
+        from matrx.cli.indexer import (
+            has_been_inited,
+            resolve_project_id_for_launch,
+            trigger_background_index,
+            trigger_index,
+        )
+
+        project_id = resolve_project_id_for_launch(state, key, cwd=os.getcwd())
+        if project_id and not has_been_inited(state, project_id):
+            print("Profiling your codebase - this takes ~10 seconds...")
+            trigger_index(state, key, cwd=os.getcwd(), blocking=True, timeout=30)
+            print("Done. matrx is ready.\n")
+        else:
+            trigger_background_index(state, key, cwd=os.getcwd())
+    except Exception:
+        pass
+
+
 def _cmd_cursor(args) -> int:
     import json as _json
     import subprocess
@@ -1318,12 +1337,7 @@ def _cmd_cursor(args) -> int:
         else:
             print("[warn] Could not find Cursor executable. Open Cursor manually.", file=sys.stderr)
 
-    try:
-        from matrx.cli.indexer import trigger_background_index
-
-        trigger_background_index(state, mx_key, cwd=os.getcwd())
-    except Exception:
-        pass
+    _trigger_index_for_launch(state, mx_key)
 
     print()
     print("Cursor configured for MTRX — all traffic routed through MITM proxy.")