meshcode 2.0.1__tar.gz → 2.0.3__tar.gz

{meshcode-2.0.1 → meshcode-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.0.1
+Version: 2.0.3
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT
@@ -153,7 +153,9 @@ meshcode revoke-member my-project <user> # kick a member instantly
 | `meshcode status` | `meshcode status` | Show the logged-in account and version. |
 | `meshcode send` (legacy) | `meshcode send my-project a:b '{"need":"..."}'` | Pre-1.5 manual message send (MCP tools are preferred). |
 | `meshcode read` (legacy) | `meshcode read my-project backend` | Pre-1.5 manual read. |
-| `meshcode --version` | `meshcode --version` | Print `meshcode 1.5.1`. |
+| `meshcode projects` | `meshcode projects` | List all your meshworks and their agents. |
+| `meshcode list` | `meshcode list` | Alias for `meshcode projects`. |
+| `meshcode --version` | `meshcode --version` | Print current version. |
 | `meshcode help` | `meshcode help` | Top-level help. Per-verb help: `meshcode <verb> --help`. |
 
 ---
@@ -251,10 +253,11 @@ pip install meshcode --upgrade
 ### Reconnect a single agent
 
 ```bash
-meshcode run <agent-name>
+meshcode setup my-project agent-name   # ensures workspace exists (safe to re-run)
+meshcode run agent-name                # opens your editor
 ```
 
-That's it. This reopens your editor with the agent's MCP server. The agent automatically:
+Since v2.0.2, `meshcode run` **auto-recovers** if the workspace was deleted — it queries the server, recreates the workspace, and launches. So `meshcode run agent-name` alone is usually enough. The agent automatically:
 1. Loads its persistent memories (`meshcode_recall()`)
 2. Checks who else is online (`meshcode_status()`)
 3. Picks up any open tasks (`meshcode_tasks()`)
@@ -326,21 +329,49 @@ If an agent is offline, the dashboard shows a **Reconnect** button on its card.
 
 ## Troubleshooting
 
-**1. `No credentials found. Run meshcode login first.`**
+**1. `no workspace found for agent 'X'`**
+Your local workspace was deleted or never created. Since v2.0.2, `meshcode run` auto-recovers by querying the server. If you're on an older version:
+```bash
+pip install meshcode --upgrade          # get v2.0.2+
+meshcode run agent-name                 # auto-recovers now
+```
+If auto-recovery fails (no API key stored), run setup manually:
+```bash
+meshcode setup my-project agent-name    # recreates ~/meshcode/my-project-agent-name/
+meshcode run agent-name
+```
+
+**2. `meshcode projects` shows no projects (but dashboard shows them)**
+Before v2.0.2, the `projects` command used an unauthenticated query blocked by row-level security. Upgrade:
+```bash
+pip install meshcode --upgrade
+meshcode projects                       # now uses your API key
+```
+
+**3. `No credentials found. Run meshcode login first.`**
 You haven't stored a key yet. Grab your `mc_xxx` from https://meshcode.io/onboarding and run:
 ```bash
 meshcode login mc_xxxxxxxxxxxx
 ```
 
-**2. `agent already running in another window`**
+**4. `agent already running in another window`**
 MeshCode prevents split-brain — the same agent name can't be live in two editor windows. Close the other window, or use a different agent name.
 
-**3. `scoped api key cannot access this project`**
+**5. `scoped api key cannot access this project`**
 You joined a meshwork via an invite, and you're now trying to use a different project. Scoped keys only work for the one mesh they were minted for. Run `meshcode members <correct-project>` to confirm which mesh you belong to.
 
-**4. `meshcode: command not found`**
+**6. `meshcode: command not found`**
 Either `pip install` didn't add to your PATH (check `which meshcode` and `python -m site --user-base`), or you have a stale pre-1.0.0 `~/bin/meshcode` shim shadowing the real binary — delete it.
 
+**7. `could not resolve project 'X': project not found`**
+Wrong project name. Since v2.0.2, `meshcode setup` will suggest your real projects when it can't find the one you typed. Check the exact name:
+```bash
+meshcode projects                       # lists all your meshworks
+```
+
+**8. Unknown command (e.g., `meshcode list`)**
+Since v2.0.2, the CLI suggests the closest match instead of dumping the full help text. Common aliases: `list` and `ls` both work for `projects`.
+
 **5. `MCP server failed to start` in the Claude Code `/mcp` panel**
 Run `claude --debug` to see the underlying error. Nine times out of ten it's a stale or missing key — run `meshcode login mc_xxx` again.
 

{meshcode-2.0.1 → meshcode-2.0.3}/README.md

@@ -128,7 +128,9 @@ meshcode revoke-member my-project <user> # kick a member instantly
 | `meshcode status` | `meshcode status` | Show the logged-in account and version. |
 | `meshcode send` (legacy) | `meshcode send my-project a:b '{"need":"..."}'` | Pre-1.5 manual message send (MCP tools are preferred). |
 | `meshcode read` (legacy) | `meshcode read my-project backend` | Pre-1.5 manual read. |
-| `meshcode --version` | `meshcode --version` | Print `meshcode 1.5.1`. |
+| `meshcode projects` | `meshcode projects` | List all your meshworks and their agents. |
+| `meshcode list` | `meshcode list` | Alias for `meshcode projects`. |
+| `meshcode --version` | `meshcode --version` | Print current version. |
 | `meshcode help` | `meshcode help` | Top-level help. Per-verb help: `meshcode <verb> --help`. |
 
 ---
@@ -226,10 +228,11 @@ pip install meshcode --upgrade
 ### Reconnect a single agent
 
 ```bash
-meshcode run <agent-name>
+meshcode setup my-project agent-name   # ensures workspace exists (safe to re-run)
+meshcode run agent-name                # opens your editor
 ```
 
-That's it. This reopens your editor with the agent's MCP server. The agent automatically:
+Since v2.0.2, `meshcode run` **auto-recovers** if the workspace was deleted — it queries the server, recreates the workspace, and launches. So `meshcode run agent-name` alone is usually enough. The agent automatically:
 1. Loads its persistent memories (`meshcode_recall()`)
 2. Checks who else is online (`meshcode_status()`)
 3. Picks up any open tasks (`meshcode_tasks()`)
@@ -301,21 +304,49 @@ If an agent is offline, the dashboard shows a **Reconnect** button on its card.
 
 ## Troubleshooting
 
-**1. `No credentials found. Run meshcode login first.`**
+**1. `no workspace found for agent 'X'`**
+Your local workspace was deleted or never created. Since v2.0.2, `meshcode run` auto-recovers by querying the server. If you're on an older version:
+```bash
+pip install meshcode --upgrade          # get v2.0.2+
+meshcode run agent-name                 # auto-recovers now
+```
+If auto-recovery fails (no API key stored), run setup manually:
+```bash
+meshcode setup my-project agent-name    # recreates ~/meshcode/my-project-agent-name/
+meshcode run agent-name
+```
+
+**2. `meshcode projects` shows no projects (but dashboard shows them)**
+Before v2.0.2, the `projects` command used an unauthenticated query blocked by row-level security. Upgrade:
+```bash
+pip install meshcode --upgrade
+meshcode projects                       # now uses your API key
+```
+
+**3. `No credentials found. Run meshcode login first.`**
 You haven't stored a key yet. Grab your `mc_xxx` from https://meshcode.io/onboarding and run:
 ```bash
 meshcode login mc_xxxxxxxxxxxx
 ```
 
-**2. `agent already running in another window`**
+**4. `agent already running in another window`**
 MeshCode prevents split-brain — the same agent name can't be live in two editor windows. Close the other window, or use a different agent name.
 
-**3. `scoped api key cannot access this project`**
+**5. `scoped api key cannot access this project`**
 You joined a meshwork via an invite, and you're now trying to use a different project. Scoped keys only work for the one mesh they were minted for. Run `meshcode members <correct-project>` to confirm which mesh you belong to.
 
-**4. `meshcode: command not found`**
+**6. `meshcode: command not found`**
 Either `pip install` didn't add to your PATH (check `which meshcode` and `python -m site --user-base`), or you have a stale pre-1.0.0 `~/bin/meshcode` shim shadowing the real binary — delete it.
 
+**7. `could not resolve project 'X': project not found`**
+Wrong project name. Since v2.0.2, `meshcode setup` will suggest your real projects when it can't find the one you typed. Check the exact name:
+```bash
+meshcode projects                       # lists all your meshworks
+```
+
+**8. Unknown command (e.g., `meshcode list`)**
+Since v2.0.2, the CLI suggests the closest match instead of dumping the full help text. Common aliases: `list` and `ls` both work for `projects`.
+
 **5. `MCP server failed to start` in the Claude Code `/mcp` panel**
 Run `claude --debug` to see the underlying error. Nine times out of ten it's a stale or missing key — run `meshcode login mc_xxx` again.
 

{meshcode-2.0.1 → meshcode-2.0.3}/meshcode/__init__.py

@@ -1,2 +1,2 @@
 """MeshCode — Real-time communication between AI agents."""
-__version__ = "2.0.1"
+__version__ = "2.0.3"

{meshcode-2.0.1 → meshcode-2.0.3}/meshcode/comms_v4.py

@@ -1248,19 +1248,32 @@ def show_history(project, last_n=20, between=None):
 
 
 def list_projects():
-    projects_data = sb_select("mc_projects", "", order="created_at.asc")
-    if not projects_data:
-        print("[COMMS] Sin proyectos")
+    api_key = _load_api_key_for_cli()
+    if not api_key:
+        print("[meshcode] Not authenticated. Run `meshcode login <api_key>` first.")
+        return
+
+    data = sb_rpc("mc_list_user_projects", {"p_api_key": api_key})
+    if isinstance(data, dict) and data.get("error"):
+        print(f"[meshcode] ERROR: {data['error']}")
+        return
+
+    projects = []
+    if isinstance(data, dict):
+        projects = data.get("projects", [])
+
+    if not projects:
+        print("[meshcode] No projects found. Create one at meshcode.io or with `meshcode_create_meshwork`.")
         return
 
     print(f"\n{'='*60}")
-    print(f" PROYECTOS ACTIVOS (Supabase)")
+    print(f" YOUR MESHWORKS")
     print(f"{'='*60}")
 
-    for proj in projects_data:
-        agents = sb_select("mc_agents", f"project_id=eq.{proj['id']}", order="name.asc")
+    for proj in projects:
+        agents = proj.get("agents", [])
         statuses = [f"{a['name']}({a.get('status','?')})" for a in agents]
-        print(f"  [{proj['name']}] {', '.join(statuses) if statuses else 'sin agentes'}")
+        print(f"  [{proj['name']}] {', '.join(statuses) if statuses else 'no agents'}")
     print()
 
 
@@ -1894,7 +1907,7 @@ if __name__ == "__main__":
         proj = sys.argv[2] if len(sys.argv) > 2 else None
         show_status(proj)
 
-    elif cmd == "projects":
+    elif cmd in ("projects", "list", "ls"):
         list_projects()
 
     elif cmd == "history":
@@ -2181,6 +2194,37 @@ if __name__ == "__main__":
         show_help()
 
     else:
-        print(f"[ERROR] Comando desconocido: {cmd}")
-        show_help()
+        known_cmds = [
+            "register", "send", "broadcast", "read", "check", "watch",
+            "board", "update", "status", "projects", "list", "ls",
+            "history", "clear", "unregister", "connect", "disconnect",
+            "setup", "run", "invite", "join", "invites", "members",
+            "revoke-invite", "revoke-member", "login", "prefs", "launcher",
+            "help", "profile", "validate-sessions", "wake-headless",
+        ]
+        # Simple fuzzy: prefix match + Levenshtein-like best match
+        suggestions = [c for c in known_cmds if c.startswith(cmd)]
+        if not suggestions:
+            # Try substring match
+            suggestions = [c for c in known_cmds if cmd in c]
+        if not suggestions:
+            # Levenshtein distance 2 or less
+            def _dist(a, b):
+                if len(a) > len(b): a, b = b, a
+                dists = list(range(len(a) + 1))
+                for j, cb in enumerate(b):
+                    new = [j + 1]
+                    for i, ca in enumerate(a):
+                        cost = 0 if ca == cb else 1
+                        new.append(min(new[-1] + 1, dists[i + 1] + 1, dists[i] + cost))
+                    dists = new
+                return dists[-1]
+            scored = [(c, _dist(cmd, c)) for c in known_cmds]
+            suggestions = [c for c, d in scored if d <= 2]
+
+        if suggestions:
+            print(f"[meshcode] Unknown command: '{cmd}'. Did you mean: {', '.join(suggestions[:3])}?")
+        else:
+            print(f"[meshcode] Unknown command: '{cmd}'.")
+        print(f"[meshcode] Run `meshcode help` for all commands.")
         sys.exit(1)

{meshcode-2.0.1 → meshcode-2.0.3}/meshcode/meshcode_mcp/realtime.py

@@ -13,6 +13,7 @@ import logging
 import ssl
 from collections import deque
 from typing import Any, Awaitable, Callable, Deque, Dict, Optional
+from urllib.parse import quote as url_quote
 
 try:
     import certifi
@@ -138,7 +139,7 @@ class RealtimeListener:
                                 "event": "INSERT",
                                 "schema": "meshcode",
                                 "table": "mc_messages",
-                                "filter": f"to_agent=eq.{self.agent_name}",
+                                "filter": f"to_agent=eq.{url_quote(self.agent_name, safe='')}",
                             }
                         ]
                     }

{meshcode-2.0.1 → meshcode-2.0.3}/meshcode/meshcode_mcp/server.py

@@ -44,18 +44,23 @@ def _try_auto_wake(from_agent: str, preview: str) -> None:
     """
     if _IN_WAIT or not _AUTO_WAKE:
         return
-    import subprocess, platform
-    nudge = f"You have a new mesh message from {from_agent}: {preview[:60]}. Check your inbox with meshcode_check()."
+    import subprocess, platform, re
+    # Sanitize inputs: strip everything except alphanumeric, spaces, basic punctuation
+    safe_agent = re.sub(r'[^a-zA-Z0-9_\- ]', '', from_agent)[:50]
+    safe_preview = re.sub(r'[^a-zA-Z0-9_\-.,!? ]', '', preview)[:60]
+    nudge = f"New mesh message from {safe_agent}: {safe_preview}. Check inbox with meshcode_check()."
     system = platform.system()
     try:
         if system == "Darwin":
-            # Find which terminal app is running this process
+            # Use xdotool-style approach: pass nudge as argument, not interpolated script
             parent_app = os.environ.get("TERM_PROGRAM", "Terminal")
             app_name = "iTerm" if "iTerm" in parent_app else "Terminal"
+            # Escape for AppleScript string: replace backslash and double-quote
+            as_safe = nudge.replace("\\", "\\\\").replace('"', '\\"')
             script = f'''
             tell application "{app_name}"
                 tell application "System Events"
-                    keystroke "{nudge}"
+                    keystroke "{as_safe}"
                     keystroke return
                 end tell
             end tell
@@ -64,15 +69,17 @@ def _try_auto_wake(from_agent: str, preview: str) -> None:
                              stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
             log.info(f"auto-wake: injected nudge via {app_name} AppleScript")
         elif system == "Windows":
+            # Sanitize for SendKeys: strip braces and special SendKeys metacharacters
+            sk_safe = nudge.replace("{", "").replace("}", "").replace("+", "").replace("^", "").replace("%", "").replace("~", "")
             ps_script = f'''
             Add-Type -AssemblyName System.Windows.Forms
-            [System.Windows.Forms.SendKeys]::SendWait("{nudge}{{ENTER}}")
+            [System.Windows.Forms.SendKeys]::SendWait("{sk_safe}{{ENTER}}")
             '''
             subprocess.Popen(["powershell", "-Command", ps_script],
                              stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
             log.info("auto-wake: injected nudge via PowerShell SendKeys")
         else:
-            # Linux — best-effort with xdotool
+            # Linux — xdotool takes args directly, not shell-interpolated (safe)
             subprocess.Popen(["xdotool", "type", "--clearmodifiers", nudge + "\n"],
                              stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
             log.info("auto-wake: injected nudge via xdotool")
@@ -1258,6 +1265,9 @@ def _sync_to_obsidian(key: str, value: Any) -> None:
     Writes markdown notes with YAML frontmatter to MeshCode/<agent>/ folder.
     Failures are logged but never block the main memory write.
     """
+    from datetime import datetime
+    from urllib.request import Request, urlopen
+    from urllib.error import URLError
     try:
         import importlib
         prefs_mod = importlib.import_module("meshcode.preferences")
@@ -1265,10 +1275,6 @@ def _sync_to_obsidian(key: str, value: Any) -> None:
         if not config:
             return
 
-        from datetime import datetime
-        from urllib.request import Request, urlopen
-        from urllib.error import URLError
-
         # Build markdown note with YAML frontmatter
         timestamp = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
         if isinstance(value, (dict, list)):

{meshcode-2.0.1 → meshcode-2.0.3}/meshcode/run_agent.py

@@ -32,6 +32,77 @@ WORKSPACES_ROOT = Path.home() / "meshcode"
 REGISTRY_PATH = WORKSPACES_ROOT / ".registry.json"
 
 
+def _try_auto_setup(agent: str, project: Optional[str] = None) -> Optional[Tuple[Path, str]]:
+    """If agent exists on the server but has no local workspace, auto-create it.
+
+    Returns (workspace_path, project_name) on success, None on failure.
+    """
+    try:
+        from .setup_clients import _load_supabase_env, setup_workspace
+        import importlib
+        secrets_mod = importlib.import_module("meshcode.secrets")
+    except Exception:
+        return None
+
+    api_key = secrets_mod.get_api_key(profile="default")
+    if not api_key:
+        return None
+
+    sb = _load_supabase_env()
+
+    # Ask the server which project(s) this agent belongs to
+    try:
+        from urllib.request import Request, urlopen
+        body = json.dumps({"p_api_key": api_key, "p_agent_name": agent}).encode()
+        req = Request(
+            f"{sb['SUPABASE_URL']}/rest/v1/rpc/mc_resolve_agent_projects",
+            data=body,
+            method="POST",
+            headers={
+                "apikey": sb["SUPABASE_KEY"],
+                "Authorization": f"Bearer {sb['SUPABASE_KEY']}",
+                "Content-Type": "application/json",
+            },
+        )
+        with urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read().decode())
+    except Exception:
+        return None
+
+    if not isinstance(data, dict) or data.get("error"):
+        return None
+
+    projects = data.get("projects", [])
+    if not projects:
+        return None
+
+    # If user specified a project, filter to that one
+    if project:
+        projects = [p for p in projects if p["project_name"] == project]
+        if not projects:
+            return None
+
+    if len(projects) > 1:
+        print(f"[meshcode] Agent '{agent}' exists in multiple projects:", file=sys.stderr)
+        for p in projects:
+            print(f"[meshcode]   meshcode run {agent} --project {p['project_name']}", file=sys.stderr)
+        print(f"[meshcode] Specify which one with --project.", file=sys.stderr)
+        return None
+
+    resolved_project = projects[0]["project_name"]
+    role = projects[0].get("role", "")
+
+    print(f"[meshcode] Workspace recreated automatically for agent '{agent}' (project: {resolved_project})")
+    rc = setup_workspace(resolved_project, agent, role)
+    if rc != 0:
+        return None
+
+    ws = WORKSPACES_ROOT / f"{resolved_project}-{agent}"
+    if ws.exists():
+        return ws, resolved_project
+    return None
+
+
 def _load_registry() -> dict:
     if not REGISTRY_PATH.exists():
         return {}
@@ -41,11 +112,12 @@ def _load_registry() -> dict:
         return {}
 
 
-def _find_agent_workspace(agent: str, project: Optional[str] = None) -> Optional[Tuple[Path, str]]:
+def _find_agent_workspace(agent: str, project: Optional[str] = None, quiet: bool = False) -> Optional[Tuple[Path, str]]:
     """Look up the agent in the registry. Returns (workspace_path, project_name) or None.
 
     If multiple agents share the same name across projects, requires the
     user to disambiguate by passing project explicitly.
+    When quiet=True, suppresses error messages (used before auto-setup fallback).
     """
     reg = _load_registry()
     agents = reg.get("agents", {})
@@ -55,11 +127,11 @@ def _find_agent_workspace(agent: str, project: Optional[str] = None) -> Optional
     if info:
         ws = Path(info["workspace"])
         if not ws.exists():
-            print(f"[meshcode] ERROR: workspace dir for '{agent}' is missing: {ws}", file=sys.stderr)
-            print(f"[meshcode]        Re-run: meshcode setup {info.get('project','<project>')} {agent}", file=sys.stderr)
+            # Don't print error in quiet mode — caller will try auto-setup
             return None
         if project and info.get("project") != project:
-            print(f"[meshcode] ERROR: agent '{agent}' belongs to project '{info.get('project')}', not '{project}'", file=sys.stderr)
+            if not quiet:
+                print(f"[meshcode] ERROR: agent '{agent}' belongs to project '{info.get('project')}', not '{project}'", file=sys.stderr)
             return None
         return ws, info.get("project", "")
 
@@ -81,8 +153,6 @@ def _find_agent_workspace(agent: str, project: Optional[str] = None) -> Optional
                 print(f"[meshcode] Disambiguate: meshcode run {agent} --project <name>", file=sys.stderr)
                 return None
 
-    print(f"[meshcode] ERROR: no workspace found for agent '{agent}'", file=sys.stderr)
-    print(f"[meshcode]        Run `meshcode setup <project> {agent}` first.", file=sys.stderr)
     return None
 
 
@@ -122,9 +192,14 @@ def run(agent: str, project: Optional[str] = None, editor_override: Optional[str
         print(f"[meshcode]        (or copy this exact line into a new terminal: meshcode run {agent})", file=sys.stderr)
         return 2
 
-    found = _find_agent_workspace(agent, project)
+    found = _find_agent_workspace(agent, project, quiet=True)
     if not found:
-        return 2
+        # Auto-setup: if agent exists on the server, recreate workspace
+        found = _try_auto_setup(agent, project)
+        if not found:
+            print(f"[meshcode] ERROR: no workspace found for agent '{agent}'", file=sys.stderr)
+            print(f"[meshcode]        Run `meshcode setup <project> {agent}` first.", file=sys.stderr)
+            return 2
     ws, resolved_project = found
     server_id = f"meshcode-{resolved_project}-{agent}"
 

{meshcode-2.0.1 → meshcode-2.0.3}/meshcode/setup_clients.py

@@ -120,6 +120,8 @@ def _resolve_project_id(api_key: str, project: str, sb: Dict[str, str]) -> str:
                 return data["project_id"]
             if isinstance(data, dict) and data.get("error"):
                 print(f"[meshcode] ERROR: could not resolve project '{project}': {data['error']}", file=sys.stderr)
+                # Try to suggest the user's actual projects
+                _suggest_projects(api_key, sb)
                 sys.exit(2)
     except Exception as e:
         print(f"[meshcode] ERROR: could not resolve project '{project}': {e}", file=sys.stderr)
@@ -128,6 +130,32 @@ def _resolve_project_id(api_key: str, project: str, sb: Dict[str, str]) -> str:
     return ""
 
 
+def _suggest_projects(api_key: str, sb: dict):
+    """Try to list the user's projects to help with typos."""
+    try:
+        from urllib.request import Request as _Req, urlopen as _urlopen
+        body = json.dumps({"p_api_key": api_key}).encode()
+        req = _Req(
+            f"{sb['SUPABASE_URL']}/rest/v1/rpc/mc_list_user_projects",
+            data=body,
+            method="POST",
+            headers={
+                "apikey": sb["SUPABASE_KEY"],
+                "Authorization": f"Bearer {sb['SUPABASE_KEY']}",
+                "Content-Type": "application/json",
+            },
+        )
+        with _urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read().decode())
+        projects = data.get("projects", []) if isinstance(data, dict) else []
+        if projects:
+            print(f"[meshcode] Your projects:", file=sys.stderr)
+            for p in projects:
+                print(f"[meshcode]   - {p['name']}", file=sys.stderr)
+    except Exception:
+        pass
+
+
 def _build_server_block(project: str, project_id: str, agent: str, role: str,
                          api_key: str, sb: Dict[str, str],
                          keychain_profile: str = "default") -> Dict[str, Any]:
@@ -591,17 +619,26 @@ def setup(*args) -> int:
         if args[0] == "claude-desktop":
             # Claude Desktop needs global config — only exception
             if len(args) < 3:
-                print("Usage: meshcode setup claude-desktop <project> <agent> [role]", file=sys.stderr)
+                print(f"[meshcode] Missing agent name.", file=sys.stderr)
+                if len(args) >= 2:
+                    print(f"[meshcode] Usage: meshcode setup claude-desktop {args[1]} <agent-name>", file=sys.stderr)
+                else:
+                    print(f"[meshcode] Usage: meshcode setup claude-desktop <project> <agent>", file=sys.stderr)
                 return 1
             return setup_global(args[0], args[1], args[2], args[3] if len(args) > 3 else "")
         # All other clients: redirect to workspace flow (no global pollution)
         print(f"[meshcode] NOTE: 'meshcode setup {args[0]}' is deprecated. Using workspace flow.", file=sys.stderr)
         if len(args) < 3:
-            print("Usage: meshcode setup <project> <agent> [role]", file=sys.stderr)
+            print(f"[meshcode] Missing agent name.", file=sys.stderr)
+            if len(args) >= 2:
+                print(f"[meshcode] Usage: meshcode setup {args[1]} <agent-name>", file=sys.stderr)
+            else:
+                print(f"[meshcode] Usage: meshcode setup <project> <agent>", file=sys.stderr)
             return 1
         return setup_workspace(args[1], args[2], args[3] if len(args) > 3 else "")
 
     if len(args) < 2:
-        print("Usage: meshcode setup <project> <agent> [role]", file=sys.stderr)
+        print(f"[meshcode] Missing agent name.", file=sys.stderr)
+        print(f"[meshcode] Usage: meshcode setup {args[0]} <agent-name>", file=sys.stderr)
         return 1
     return setup_workspace(args[0], args[1], args[2] if len(args) > 2 else "")

{meshcode-2.0.1 → meshcode-2.0.3}/meshcode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.0.1
+Version: 2.0.3
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT
@@ -153,7 +153,9 @@ meshcode revoke-member my-project <user> # kick a member instantly
 | `meshcode status` | `meshcode status` | Show the logged-in account and version. |
 | `meshcode send` (legacy) | `meshcode send my-project a:b '{"need":"..."}'` | Pre-1.5 manual message send (MCP tools are preferred). |
 | `meshcode read` (legacy) | `meshcode read my-project backend` | Pre-1.5 manual read. |
-| `meshcode --version` | `meshcode --version` | Print `meshcode 1.5.1`. |
+| `meshcode projects` | `meshcode projects` | List all your meshworks and their agents. |
+| `meshcode list` | `meshcode list` | Alias for `meshcode projects`. |
+| `meshcode --version` | `meshcode --version` | Print current version. |
 | `meshcode help` | `meshcode help` | Top-level help. Per-verb help: `meshcode <verb> --help`. |
 
 ---
@@ -251,10 +253,11 @@ pip install meshcode --upgrade
 ### Reconnect a single agent
 
 ```bash
-meshcode run <agent-name>
+meshcode setup my-project agent-name   # ensures workspace exists (safe to re-run)
+meshcode run agent-name                # opens your editor
 ```
 
-That's it. This reopens your editor with the agent's MCP server. The agent automatically:
+Since v2.0.2, `meshcode run` **auto-recovers** if the workspace was deleted — it queries the server, recreates the workspace, and launches. So `meshcode run agent-name` alone is usually enough. The agent automatically:
 1. Loads its persistent memories (`meshcode_recall()`)
 2. Checks who else is online (`meshcode_status()`)
 3. Picks up any open tasks (`meshcode_tasks()`)
@@ -326,21 +329,49 @@ If an agent is offline, the dashboard shows a **Reconnect** button on its card.
 
 ## Troubleshooting
 
-**1. `No credentials found. Run meshcode login first.`**
+**1. `no workspace found for agent 'X'`**
+Your local workspace was deleted or never created. Since v2.0.2, `meshcode run` auto-recovers by querying the server. If you're on an older version:
+```bash
+pip install meshcode --upgrade          # get v2.0.2+
+meshcode run agent-name                 # auto-recovers now
+```
+If auto-recovery fails (no API key stored), run setup manually:
+```bash
+meshcode setup my-project agent-name    # recreates ~/meshcode/my-project-agent-name/
+meshcode run agent-name
+```
+
+**2. `meshcode projects` shows no projects (but dashboard shows them)**
+Before v2.0.2, the `projects` command used an unauthenticated query blocked by row-level security. Upgrade:
+```bash
+pip install meshcode --upgrade
+meshcode projects                       # now uses your API key
+```
+
+**3. `No credentials found. Run meshcode login first.`**
 You haven't stored a key yet. Grab your `mc_xxx` from https://meshcode.io/onboarding and run:
 ```bash
 meshcode login mc_xxxxxxxxxxxx
 ```
 
-**2. `agent already running in another window`**
+**4. `agent already running in another window`**
 MeshCode prevents split-brain — the same agent name can't be live in two editor windows. Close the other window, or use a different agent name.
 
-**3. `scoped api key cannot access this project`**
+**5. `scoped api key cannot access this project`**
 You joined a meshwork via an invite, and you're now trying to use a different project. Scoped keys only work for the one mesh they were minted for. Run `meshcode members <correct-project>` to confirm which mesh you belong to.
 
-**4. `meshcode: command not found`**
+**6. `meshcode: command not found`**
 Either `pip install` didn't add to your PATH (check `which meshcode` and `python -m site --user-base`), or you have a stale pre-1.0.0 `~/bin/meshcode` shim shadowing the real binary — delete it.
 
+**7. `could not resolve project 'X': project not found`**
+Wrong project name. Since v2.0.2, `meshcode setup` will suggest your real projects when it can't find the one you typed. Check the exact name:
+```bash
+meshcode projects                       # lists all your meshworks
+```
+
+**8. Unknown command (e.g., `meshcode list`)**
+Since v2.0.2, the CLI suggests the closest match instead of dumping the full help text. Common aliases: `list` and `ls` both work for `projects`.
+
 **5. `MCP server failed to start` in the Claude Code `/mcp` panel**
 Run `claude --debug` to see the underlying error. Nine times out of ten it's a stale or missing key — run `meshcode login mc_xxx` again.
 

{meshcode-2.0.1 → meshcode-2.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "meshcode"
-version = "2.0.1"
+version = "2.0.3"
 description = "Real-time communication between AI agents — Supabase-backed CLI"
 readme = "README.md"
 license = {text = "MIT"}