mtrx-cli 0.1.21 → 0.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrx-cli",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "MATRX CLI for routing Codex, Claude, and Cursor through Matrx",
   "homepage": "https://mtrx.so",
   "repository": {
@@ -35,6 +35,7 @@
     "src/matrx/cli/cursor_service.py",
     "src/matrx/cli/launcher.py",
     "src/matrx/cli/main.py",
+    "src/matrx/cli/project_cmds.py",
     "src/matrx/cli/state.py"
   ],
   "engines": {

package/src/matrx/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.21"
+__version__ = "0.1.23"

package/src/matrx/cli/launcher.py

@@ -64,6 +64,10 @@ MATRX_ENV_KEYS = {
     "ANTHROPIC_CUSTOM_HEADERS",
 }
 
+# Avoid routing Codex/Claude/Gemini through Cursor's MITM proxy when running
+# from Cursor's integrated terminal. These tools should talk directly to MATRX.
+_PROXY_ENV_KEYS = ("HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy")
+
 MTRX_CODEX_BLOCK_START = "# >>> mtrx managed codex route >>>"
 MTRX_CODEX_BLOCK_END = "# <<< mtrx managed codex route <<<"
 VALID_ROUTES = {"direct", "matrx"}
@@ -511,6 +515,8 @@ def _build_codex_env(
     if route == "matrx":
         if not mx_key:
             raise ValueError("No Matrx key available. Run: mtrx login matrx --key mx_... or set MTRX_KEY")
+        for key in _PROXY_ENV_KEYS:
+            env.pop(key, None)
         provider_bearer = env_openai_key or direct_key or read_codex_access_token()
         if not provider_bearer:
             raise ValueError(
@@ -579,33 +585,23 @@ def _build_gemini_env(
     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_root = ensure_root_url(matrx.get("base_url"))
     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()
+    direct_key = (env.get("GEMINI_API_KEY") or 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
+        for key in _PROXY_ENV_KEYS:
+            env.pop(key, None)
         env.pop("MTRX_KEY", None)
-
         group_id, project_id = _resolve_matrx_context_overrides(state, env)
         session_id = str(uuid.uuid4())
         runtime_agent_id = (
             (orchestration or {}).get("agent_id")
             or _runtime_agent_basename("gemini")[0]
         )
-
-        # Build a project-aware proxy base URL so the proxy can identify the project
-        # even though Gemini CLI doesn't support custom request headers via env vars.
-        # We append matrx context as query params which the proxy reads.
-        proxy_base_with_ctx = proxy_base
         ctx_params: list[str] = []
         if project_id:
             ctx_params.append(f"mtrx_project={project_id}")
@@ -613,31 +609,65 @@ def _build_gemini_env(
             ctx_params.append(f"mtrx_session={session_id}")
         if runtime_agent_id:
             ctx_params.append(f"mtrx_agent={runtime_agent_id}")
-        if ctx_params:
-            proxy_base_with_ctx = f"{proxy_base}?{'&'.join(ctx_params)}"
+        git_branch, git_commit = _capture_git_context(_workspace_cwd(env))
+        if git_branch:
+            ctx_params.append(f"mtrx_branch={git_branch}")
+        if git_commit:
+            ctx_params.append(f"mtrx_commit={git_commit}")
+
+        query_suffix = f"?{'&'.join(ctx_params)}" if ctx_params else ""
+        env_snap = _capture_env_snapshot()
+        env_b64 = base64.b64encode(json.dumps(env_snap).encode()).decode() if env_snap else ""
+        custom_headers = [
+            f"x-matrx-key: {mx_key}",
+            f"x-matrx-agent-id: {runtime_agent_id}",
+            "x-matrx-provider: gemini_code",
+            f"x-matrx-session-id: {session_id}",
+        ]
+        if group_id:
+            custom_headers.append(f"x-matrx-group: {group_id}")
+        if project_id:
+            custom_headers.append(f"x-matrx-project-id: {project_id}")
+        if git_branch:
+            custom_headers.append(f"x-matrx-branch: {git_branch}")
+        if git_commit:
+            custom_headers.append(f"x-matrx-commit: {git_commit}")
+        if env_b64:
+            custom_headers.append(f"x-matrx-env: {env_b64}")
 
-        # Set Proxy Config
-        env["GOOGLE_GEMINI_BASE_URL"] = proxy_base_with_ctx
-        env["GEMINI_API_ENDPOINT"] = proxy_base_with_ctx
-        env["GOOGLE_API_KEY"] = mx_key
+        env["GOOGLE_GEMINI_BASE_URL"] = f"{proxy_base}/v1beta{query_suffix}"
+        env["GOOGLE_VERTEX_BASE_URL"] = f"{proxy_base}/v1beta{query_suffix}"
+        env["GEMINI_API_ENDPOINT"] = env["GOOGLE_GEMINI_BASE_URL"]
+        env["CODE_ASSIST_ENDPOINT"] = proxy_base
+        env["GEMINI_CLI_CUSTOM_HEADERS"] = ", ".join(custom_headers)
+        env["GEMINI_API_KEY_AUTH_MECHANISM"] = "bearer"
 
         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"):
+    for key in (
+        "GOOGLE_GEMINI_BASE_URL",
+        "GOOGLE_VERTEX_BASE_URL",
+        "GEMINI_API_ENDPOINT",
+        "CODE_ASSIST_ENDPOINT",
+    ):
+        value = (env.get(key) or "").strip()
+        if "matrx" in value.lower() or "mtrx.so" in value.lower():
+            env.pop(key, None)
+
+    custom_headers = (env.get("GEMINI_CLI_CUSTOM_HEADERS") or "").strip().lower()
+    if "x-matrx-" in custom_headers:
+        env.pop("GEMINI_CLI_CUSTOM_HEADERS", None)
+    if (env.get("GEMINI_API_KEY_AUTH_MECHANISM") or "").strip().lower() == "bearer":
+        env.pop("GEMINI_API_KEY_AUTH_MECHANISM", None)
+
+    if env.get("GEMINI_API_KEY") or env.get("GOOGLE_API_KEY"):
         return env, "existing_google_env"
-        
+
+    if direct_key:
+        return env, "existing_gemini_auth"
+
     return env, "missing_auth"
 
 
@@ -658,6 +688,8 @@ def _build_claude_env(
     if route == "matrx":
         if not mx_key:
             raise ValueError("No Matrx key available. Run: mtrx login matrx --key mx_... or set MTRX_KEY")
+        for key in _PROXY_ENV_KEYS:
+            env.pop(key, None)
         env.pop("MTRX_KEY", None)
         env.pop("MATRX_CLAUDE_MODE", None)
         env["MATRX_BASE_URL"] = proxy_root
@@ -906,26 +938,40 @@ def _validate_gemini_launch_plan(plan: LaunchPlan, state: dict) -> None:
         return
 
     expected_base_url = ensure_v1_url(state.get("auth", {}).get("matrx", {}).get("base_url"))
+    expected_gemini_base = f"{expected_base_url}/v1beta"
 
     base_url = (plan.env.get("GOOGLE_GEMINI_BASE_URL") or "").strip()
     if not base_url:
         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")
+        raise ValueError("Gemini Matrx route is missing GOOGLE_GEMINI_BASE_URL")
 
-    # Strip query params before comparing (project_id context may be appended as ?mtrx_project=...)
     base_url_no_qs = base_url.split("?")[0].rstrip("/")
-    expected_no_qs = expected_base_url.rstrip("/")
+    expected_no_qs = expected_gemini_base.rstrip("/")
     if base_url_no_qs != expected_no_qs:
         raise ValueError(
-            "Gemini Matrx route must use the Matrx /v1 base URL. "
+            "Gemini Matrx route must use the Matrx Gemini-native 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_...)")
+    vertex_base = (plan.env.get("GOOGLE_VERTEX_BASE_URL") or "").strip()
+    if vertex_base and vertex_base.split("?")[0].rstrip("/") != expected_no_qs:
+        raise ValueError("Gemini Matrx route is missing a Matrx GOOGLE_VERTEX_BASE_URL")
+
+    code_assist_endpoint = (plan.env.get("CODE_ASSIST_ENDPOINT") or "").strip().rstrip("/")
+    if code_assist_endpoint != expected_base_url.rstrip("/"):
+        raise ValueError("Gemini Matrx route is missing a Matrx CODE_ASSIST_ENDPOINT")
+
+    custom_headers = (plan.env.get("GEMINI_CLI_CUSTOM_HEADERS") or "").strip().lower()
+    if "x-matrx-key:" not in custom_headers:
+        raise ValueError("Gemini Matrx route is missing GEMINI_CLI_CUSTOM_HEADERS with X-Matrx-Key")
+    if "x-matrx-provider: gemini_code" not in custom_headers:
+        raise ValueError("Gemini Matrx route is missing GEMINI_CLI_CUSTOM_HEADERS with X-Matrx-Provider=gemini_code")
+    if "x-matrx-session-id:" not in custom_headers:
+        raise ValueError("Gemini Matrx route is missing GEMINI_CLI_CUSTOM_HEADERS with X-Matrx-Session-Id")
+    if "x-matrx-agent-id:" not in custom_headers:
+        raise ValueError("Gemini Matrx route is missing GEMINI_CLI_CUSTOM_HEADERS with X-Matrx-Agent-Id")
 
 
 def _validate_codex_launch_plan(plan: LaunchPlan, state: dict) -> None:
@@ -991,10 +1037,13 @@ def describe_launch_plan(plan: LaunchPlan, state: dict) -> list[str]:
     if plan.tool == "gemini":
         base_url = ensure_v1_url(state.get("auth", {}).get("matrx", {}).get("base_url"))
         _, project_id = _resolve_matrx_context_overrides(state, dict(plan.env))
+        custom_headers = (plan.env.get("GEMINI_CLI_CUSTOM_HEADERS") or "").strip()
         lines = [
             "Launching gemini via Matrx",
-            f"  base_url: {base_url}",
+            f"  gemini_base_url: {plan.env.get('GOOGLE_GEMINI_BASE_URL') or ''}",
+            f"  code_assist_endpoint: {plan.env.get('CODE_ASSIST_ENDPOINT') or ''}",
             f"  auth_source: {plan.auth_source}",
+            f"  custom_headers_present: {bool(custom_headers)}",
             "  runtime_route: env injection",
             "  persistent_route: disabled",
         ]

package/src/matrx/cli/project_cmds.py

@@ -0,0 +1,526 @@
+"""
+CLI commands for managing Matrx projects.
+
+mtrx project list         — list all projects in your org
+mtrx project current      — show which project is active in this workspace
+mtrx project switch <name>— bind this workspace to a project
+mtrx project create <name>— create a new project and optionally bind workspace
+mtrx project init         — interactive: link this git repo to a Matrx project
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import httpx
+
+from matrx.cli.state import (
+    ensure_root_url,
+    get_workspace_binding,
+    normalize_matrx_key,
+    resolve_workspace_root,
+    set_workspace_binding,
+    load_state,
+    save_state,
+)
+
+
+# ---------------------------------------------------------------------------
+# Internal API helper
+# ---------------------------------------------------------------------------
+
+def _api(
+    state: dict,
+    *,
+    method: str,
+    path: str,
+    key: str,
+    json_body: dict | None = None,
+) -> 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=15) as client:
+            response = client.request(method, url, headers=headers, json=json_body)
+    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
+    saved = normalize_matrx_key(state.get("auth", {}).get("matrx", {}).get("key"))
+    return saved
+
+
+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
+
+
+# ---------------------------------------------------------------------------
+# project list
+# ---------------------------------------------------------------------------
+
+def cmd_list(args) -> int:
+    state = load_state()
+    try:
+        key = _require_key(state)
+        ctx = _api(state, method="GET", path="/auth/context", key=key)
+        org_id = (ctx.get("org_id") or "").strip()
+        if not org_id:
+            print("Could not determine org_id from auth context.", file=sys.stderr)
+            return 1
+        projects = _api(state, method="GET", path=f"/orgs/{org_id}/projects", key=key)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    items = projects if isinstance(projects, list) else projects.get("projects", [])
+    if not items:
+        print("No projects found. Create one with: mtrx project create <name>")
+        return 0
+
+    # Determine which project is active for this workspace
+    binding = get_workspace_binding(state, cwd=os.getcwd()) or {}
+    active_project_id = (
+        os.environ.get("MTRX_PROJECT_ID")
+        or binding.get("project_id")
+        or ""
+    ).strip()
+
+    print(f"{'  ':2}{'NAME':<30} {'SLUG':<25} {'ID'}")
+    print("-" * 80)
+    for p in items:
+        pid = p.get("id", "")
+        name = p.get("name", "")
+        slug = p.get("slug", "")
+        marker = "* " if pid == active_project_id else "  "
+        default_tag = " [default]" if p.get("is_default") else ""
+        print(f"{marker}{name:<30} {slug:<25} {pid}{default_tag}")
+
+    if active_project_id:
+        print(f"\n* = active project for this workspace")
+    else:
+        print("\nNo project bound to this workspace. Run: mtrx project switch <name>")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# project current
+# ---------------------------------------------------------------------------
+
+def cmd_current(args) -> int:
+    state = load_state()
+    binding = get_workspace_binding(state, cwd=os.getcwd()) or {}
+    workspace_root = resolve_workspace_root(os.getcwd())
+
+    env_project_id = (os.environ.get("MTRX_PROJECT_ID") or "").strip()
+    env_group_id = (os.environ.get("MTRX_GROUP_ID") or "").strip()
+    binding_project_id = (binding.get("project_id") or "").strip()
+    binding_group_id = (binding.get("group_id") or "").strip()
+
+    print(f"Workspace: {workspace_root}")
+
+    # Try to fetch project name from API
+    active_project_id = env_project_id or binding_project_id
+    if active_project_id:
+        try:
+            key = _require_key(state)
+            ctx = _api(state, method="GET", path="/auth/context", key=key)
+            org_id = (ctx.get("org_id") or "").strip()
+            if org_id:
+                projects = _api(state, method="GET", path=f"/orgs/{org_id}/projects", key=key)
+                items = projects if isinstance(projects, list) else projects.get("projects", [])
+                match = next((p for p in items if p.get("id") == active_project_id), None)
+                if match:
+                    source = "env var" if env_project_id else "workspace binding"
+                    print(f"Active project: {match['name']} ({match['slug']}) [{source}]")
+                    print(f"  project_id: {active_project_id}")
+                    if active_project_id == env_project_id:
+                        print(f"  override: MTRX_PROJECT_ID env var takes priority")
+                    if env_group_id or binding_group_id:
+                        print(f"  group_id: {env_group_id or binding_group_id}")
+                    return 0
+        except ValueError:
+            pass
+
+        source = "env var" if env_project_id else "workspace binding"
+        print(f"Active project: {active_project_id} [{source}] (could not fetch name)")
+    else:
+        print("No project bound to this workspace.")
+        print("  Run: mtrx project switch <name>  to bind a project")
+        print("  Run: mtrx project list           to see available projects")
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# project switch
+# ---------------------------------------------------------------------------
+
+def cmd_switch(args) -> int:
+    name_or_slug = (getattr(args, "name", "") or "").strip()
+    if not name_or_slug:
+        print("Usage: mtrx project switch <name-or-slug>", file=sys.stderr)
+        return 1
+
+    state = load_state()
+    try:
+        key = _require_key(state)
+        ctx = _api(state, method="GET", path="/auth/context", key=key)
+        org_id = (ctx.get("org_id") or "").strip()
+        if not org_id:
+            print("Could not determine org_id from auth context.", file=sys.stderr)
+            return 1
+        projects = _api(state, method="GET", path=f"/orgs/{org_id}/projects", key=key)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    items = projects if isinstance(projects, list) else projects.get("projects", [])
+    needle = name_or_slug.lower()
+    match = next(
+        (
+            p for p in items
+            if p.get("name", "").lower() == needle
+            or p.get("slug", "").lower() == needle
+            or p.get("id", "").lower() == needle
+        ),
+        None,
+    )
+    if match is None:
+        print(f"Project '{name_or_slug}' not found.", file=sys.stderr)
+        print(f"Available: {', '.join(p.get('slug') or p.get('name', '') for p in items)}", file=sys.stderr)
+        return 1
+
+    changed = set_workspace_binding(state, cwd=os.getcwd(), project_id=match["id"])
+    if changed:
+        save_state(state)
+
+    workspace_root = resolve_workspace_root(os.getcwd())
+    print(f"Switched to project: {match['name']} ({match['slug']})")
+    print(f"  project_id: {match['id']}")
+    if match.get("repo_url"):
+        print(f"  repo_url:   {match['repo_url']}")
+    print(f"  workspace:  {workspace_root}")
+    print(f"  This workspace will now route all LLM calls to this project.")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# project create
+# ---------------------------------------------------------------------------
+
+def cmd_create(args) -> int:
+    name = (getattr(args, "name", "") or "").strip()
+    if not name:
+        print("Usage: mtrx project create <name> [--description TEXT]", file=sys.stderr)
+        return 1
+    description = (getattr(args, "description", "") or "").strip() or None
+
+    state = load_state()
+    try:
+        key = _require_key(state)
+        ctx = _api(state, method="GET", path="/auth/context", key=key)
+        org_id = (ctx.get("org_id") or "").strip()
+        if not org_id:
+            print("Could not determine org_id from auth context.", file=sys.stderr)
+            return 1
+
+        body: dict = {"name": name}
+        if description:
+            body["description"] = description
+
+        project = _api(
+            state,
+            method="POST",
+            path=f"/orgs/{org_id}/projects",
+            key=key,
+            json_body=body,
+        )
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    print(f"Created project: {project.get('name')} ({project.get('slug')})")
+    print(f"  project_id: {project.get('id')}")
+
+    # Ask if they want to bind this workspace
+    if sys.stdin.isatty() and sys.stdout.isatty():
+        answer = input("Bind this workspace to the new project? [Y/n] ").strip().lower()
+        if answer in {"", "y", "yes"}:
+            changed = set_workspace_binding(state, cwd=os.getcwd(), project_id=project["id"])
+            if changed:
+                save_state(state)
+            print(f"  Workspace bound to: {project.get('name')}")
+    else:
+        # Non-interactive: auto-bind
+        changed = set_workspace_binding(state, cwd=os.getcwd(), project_id=project["id"])
+        if changed:
+            save_state(state)
+        print(f"  Workspace auto-bound to: {project.get('name')}")
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# project init
+# ---------------------------------------------------------------------------
+
+def _git_remote_url() -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True,
+            text=True,
+            timeout=3,
+            check=False,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip() or None
+    except (OSError, subprocess.SubprocessError):
+        pass
+    return None
+
+
+def _git_current_branch() -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            capture_output=True,
+            text=True,
+            timeout=3,
+            check=False,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip() or None
+    except (OSError, subprocess.SubprocessError):
+        pass
+    return None
+
+
+def _is_interactive() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def _prompt(prompt: str, default: str = "") -> str:
+    if not _is_interactive():
+        return default
+    result = input(prompt).strip()
+    return result or default
+
+
+def _patch_project_repo_metadata(
+    state: dict,
+    *,
+    key: str,
+    org_id: str,
+    project: dict,
+    repo_url: str | None,
+    branch: str | None,
+) -> None:
+    if not repo_url or not project.get("id"):
+        return
+    try:
+        _api(
+            state,
+            method="PATCH",
+            path=f"/orgs/{org_id}/projects/{project['id']}",
+            key=key,
+            json_body={
+                "repo_url": repo_url,
+                "default_branch": branch or "main",
+            },
+        )
+    except ValueError:
+        pass
+
+
+def cmd_init(args) -> int:
+    state = load_state()
+    try:
+        key = _require_key(state)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    workspace_root = resolve_workspace_root(os.getcwd())
+    repo_url = _git_remote_url()
+    branch = _git_current_branch()
+
+    print(f"Matrx project init")
+    print(f"  workspace: {workspace_root}")
+    if repo_url:
+        print(f"  git remote: {repo_url}")
+    if branch:
+        print(f"  branch: {branch}")
+    print()
+
+    # Check if already bound
+    binding = get_workspace_binding(state, cwd=os.getcwd()) or {}
+    existing_project_id = (binding.get("project_id") or "").strip()
+    if existing_project_id:
+        print(f"This workspace is already bound to project: {existing_project_id}")
+        if _is_interactive():
+            answer = _prompt("Rebind to a different project? [y/N] ", "n")
+            if answer.lower() not in {"y", "yes"}:
+                print("No changes made.")
+                return 0
+
+    try:
+        ctx = _api(state, method="GET", path="/auth/context", key=key)
+        org_id = (ctx.get("org_id") or "").strip()
+        if not org_id:
+            print("Could not determine org_id from auth context.", file=sys.stderr)
+            return 1
+        projects = _api(state, method="GET", path=f"/orgs/{org_id}/projects", key=key)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    items = projects if isinstance(projects, list) else projects.get("projects", [])
+
+    if not items:
+        print("No projects found in your org.")
+        if _is_interactive():
+            answer = _prompt("Create a new project now? [Y/n] ", "y")
+            if answer.lower() in {"", "y", "yes"}:
+                return _create_and_bind(state, key, org_id, workspace_root, repo_url, branch)
+        return 1
+
+    # Show existing projects
+    print("Available projects:")
+    for i, p in enumerate(items, 1):
+        default_tag = " [default]" if p.get("is_default") else ""
+        print(f"  {i}. {p.get('name')} ({p.get('slug')}){default_tag}")
+    print(f"  {len(items) + 1}. Create a new project")
+    print()
+
+    if not _is_interactive():
+        # Non-interactive: bind to default project
+        default_proj = next((p for p in items if p.get("is_default")), items[0])
+        changed = set_workspace_binding(state, cwd=os.getcwd(), project_id=default_proj["id"])
+        if changed:
+            save_state(state)
+        _patch_project_repo_metadata(
+            state,
+            key=key,
+            org_id=org_id,
+            project=default_proj,
+            repo_url=repo_url,
+            branch=branch,
+        )
+        print(f"Bound to default project: {default_proj['name']}")
+        return 0
+
+    choice_str = _prompt(f"Select project [1-{len(items) + 1}]: ", "1")
+    try:
+        choice = int(choice_str)
+    except ValueError:
+        print("Invalid selection.", file=sys.stderr)
+        return 1
+
+    if choice == len(items) + 1:
+        return _create_and_bind(state, key, org_id, workspace_root, repo_url, branch)
+
+    if not (1 <= choice <= len(items)):
+        print("Invalid selection.", file=sys.stderr)
+        return 1
+
+    selected = items[choice - 1]
+    changed = set_workspace_binding(state, cwd=os.getcwd(), project_id=selected["id"])
+    if changed:
+        save_state(state)
+    _patch_project_repo_metadata(
+        state,
+        key=key,
+        org_id=org_id,
+        project=selected,
+        repo_url=repo_url,
+        branch=branch,
+    )
+
+    print(f"\nBound workspace to project: {selected['name']} ({selected['slug']})")
+    print(f"  project_id: {selected['id']}")
+    print(f"  workspace:  {workspace_root}")
+    print(f"\nAll LLM calls from this directory will now route to this project.")
+    return 0
+
+
+def _create_and_bind(
+    state: dict,
+    key: str,
+    org_id: str,
+    workspace_root: str,
+    repo_url: str | None,
+    branch: str | None,
+) -> int:
+    repo_name = None
+    if repo_url:
+        # Derive a default name from the repo URL (e.g. github.com/org/my-repo -> my-repo)
+        repo_name = repo_url.rstrip("/").split("/")[-1]
+        if repo_name.endswith(".git"):
+            repo_name = repo_name[:-4]
+
+    default_name = repo_name or Path(workspace_root).name
+    if _is_interactive():
+        name = _prompt(f"Project name [{default_name}]: ", default_name)
+        description = _prompt("Description (optional): ", "")
+    else:
+        name = default_name
+        description = ""
+
+    name = name.strip() or default_name
+    body: dict = {"name": name}
+    if description.strip():
+        body["description"] = description.strip()
+
+    try:
+        project = _api(
+            state,
+            method="POST",
+            path=f"/orgs/{org_id}/projects",
+            key=key,
+            json_body=body,
+        )
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    changed = set_workspace_binding(state, cwd=os.getcwd(), project_id=project["id"])
+    if changed:
+        save_state(state)
+    _patch_project_repo_metadata(
+        state,
+        key=key,
+        org_id=org_id,
+        project=project,
+        repo_url=repo_url,
+        branch=branch,
+    )
+
+    print(f"\nCreated and bound project: {project.get('name')} ({project.get('slug')})")
+    print(f"  project_id: {project.get('id')}")
+    print(f"  workspace:  {workspace_root}")
+    print(f"\nAll LLM calls from this directory will now route to this project.")
+    return 0