meshcode 2.11.42__tar.gz → 2.11.43__tar.gz

{meshcode-2.11.42 → meshcode-2.11.43}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.11.42
+Version: 2.11.43
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT

{meshcode-2.11.42 → meshcode-2.11.43}/meshcode/__init__.py

@@ -1,5 +1,5 @@
 """MeshCode — Real-time communication between AI agents."""
-__version__ = "2.11.42"
+__version__ = "2.11.43"
 
 # Exception hierarchy — eagerly imported (lightweight, no deps)
 from meshcode.exceptions import (  # noqa: F401

{meshcode-2.11.42 → meshcode-2.11.43}/meshcode/comms_v4.py

@@ -2734,7 +2734,7 @@ if __name__ == "__main__":
 
     # Strip bare boolean flags from argv before parsing so they don't end
     # up as positional args (e.g. --compact is a bare flag, not key=value).
-    BARE_FLAGS = {"--compact", "--legacy", "--no-hook", "--mcp-only"}
+    BARE_FLAGS = {"--compact", "--legacy", "--no-hook", "--mcp-only", "--autonomous"}
     _bare_present = {a.lstrip("-") for a in sys.argv[2:] if a in BARE_FLAGS}
     _argv_for_parse = [a for a in sys.argv[2:] if a not in BARE_FLAGS]
 
@@ -3259,9 +3259,16 @@ if __name__ == "__main__":
             else:
                 print("[meshcode] Login required. Run: meshcode login <api_key>")
                 sys.exit(1)
+        # AUTONOMOUS-MODE-UNIVERSAL (task f248d98e): --autonomous flag OR
+        # MESHCODE_AUTONOMOUS=1 env var → register-time autonomous=true.
+        # Memo decision Q3: scope is `meshcode run` + add-agent. Env var
+        # acts as shell-session default; explicit flag wins per-launch.
+        autonomous_env = (os.environ.get("MESHCODE_AUTONOMOUS", "").strip().lower()
+                          in ("1", "true", "yes", "on"))
+        autonomous = bool(flags.get("autonomous")) or autonomous_env
         import importlib
         _run = importlib.import_module("meshcode.run_agent").run
-        sys.exit(_run(agent, project=proj_override, editor_override=editor_override, permission_override=perm_override, dry_run=dry_run))
+        sys.exit(_run(agent, project=proj_override, editor_override=editor_override, permission_override=perm_override, dry_run=dry_run, autonomous=autonomous))
 
     elif cmd == "scan":
         # meshcode scan — detect identicon from stdin/clipboard and launch agent

{meshcode-2.11.42 → meshcode-2.11.43}/meshcode/meshcode_mcp/backend.py

@@ -615,12 +615,30 @@ def register_agent(project: str, name: str, role: str = "", api_key: Optional[st
                   f"project_id=eq.{project_id}&name=eq.{quote(name)}",
                   {"task": role})
 
-    return {
+    # AUTONOMOUS-MODE-UNIVERSAL (task f248d98e Phase 1): if launched with
+    # `meshcode run --autonomous` or MESHCODE_AUTONOMOUS=1, flip autonomous
+    # mode at register-time. RPC mc_agent_set_autonomous exists per mig 354.
+    # Best-effort: register success is reported even if autonomous flip fails.
+    _autonomous_out: Optional[bool] = None
+    if os.environ.get("MESHCODE_AUTONOMOUS", "").strip().lower() in ("1", "true", "yes", "on"):
+        _set_resp = sb_rpc("mc_agent_set_autonomous", {
+            "p_api_key": _ak or "",
+            "p_project_id": project_id,
+            "p_agent_name": name,
+            "p_enabled": True,
+        })
+        if isinstance(_set_resp, dict) and _set_resp.get("ok"):
+            _autonomous_out = True
+
+    out = {
         "registered": True,
         "project_id": project_id,
         "agent_name": name,
         "agent_id": result.get("agent_id") if isinstance(result, dict) else None,
     }
+    if _autonomous_out is not None:
+        out["autonomous_mode"] = _autonomous_out
+    return out
 
 
 # TTL cache for resolve_agent_name — avoids N+1 queries on every send().

{meshcode-2.11.42 → meshcode-2.11.43}/meshcode/meshcode_mcp/server.py

@@ -3541,6 +3541,10 @@ async def meshcode_wait(timeout_seconds: int = 20, include_acks: bool = False) -
                         _snap = _get_mesh_online_snapshot()
                         if _snap is not None:
                             resp["mesh_online_snapshot"] = _snap
+                    # AUTONOMOUS-MODE-UNIVERSAL (task f248d98e Phase 1):
+                    # surface autonomy on the refused-path too so check
+                    # parity holds when wait short-circuits on unread msgs.
+                    resp["you_are_autonomous"] = _get_autonomous_mode()
                     return resp
                 # Ack-only batch — fall through to wait loop
     except Exception:
@@ -3667,10 +3671,13 @@ async def meshcode_wait(timeout_seconds: int = 20, include_acks: bool = False) -
             _snapshot = _get_mesh_online_snapshot()
             if _snapshot is not None:
                 result["mesh_online_snapshot"] = _snapshot
-        # AUTONOMOUS-MODE-1-RUNTIME: surface the flag so the LLM knows
-        # whether to operate proactively.
+        # AUTONOMOUS-MODE-1-RUNTIME + UNIVERSAL (task f248d98e Phase 1):
+        # surface the flag so the LLM knows whether to operate proactively.
+        # `you_are_autonomous` is the canonical field per commander memo
+        # decisions msg 29cae7f9; `autonomous_mode` retained for back-compat.
         if isinstance(result, dict):
             result["autonomous_mode"] = _autonomous
+            result["you_are_autonomous"] = _autonomous
         return result
     finally:
         _IN_WAIT = False
@@ -4019,6 +4026,11 @@ def meshcode_check(include_acks: bool = False, since: Optional[str] = None, mark
     _ctx = _calendar_context_for_self()
     if _ctx is not None:
         result["calendar_context"] = _ctx
+    # AUTONOMOUS-MODE-UNIVERSAL (task f248d98e Phase 1): surface autonomous
+    # state on every check so agents have constant awareness without extra
+    # tool calls. Uses 15s-TTL cache (_get_autonomous_mode), one RPC per cache
+    # window — negligible cost on the inbox poll path.
+    result["you_are_autonomous"] = _get_autonomous_mode()
     return result
 
 
@@ -4087,9 +4099,13 @@ def meshcode_status() -> Dict[str, Any]:
                 "task": a.get("task", ""),
                 "last_heartbeat": a.get("last_heartbeat"),
                 "idle_seconds": _idle_seconds(a.get("last_response_at")),
+                "autonomous_mode": bool(a.get("autonomous_mode")),
             }
             for a in agents
         ],
+        # AUTONOMOUS-MODE-UNIVERSAL (task f248d98e Phase 1): constant
+        # awareness of self autonomy on the status path too.
+        "you_are_autonomous": _get_autonomous_mode(),
     }
 
 
@@ -5350,20 +5366,39 @@ def meshcode_create_meshwork(name: str) -> Dict[str, Any]:
 
 @mcp.tool()
 @with_working_status
-def meshcode_add_agent(name: str, role: str = "") -> Dict[str, Any]:
+def meshcode_add_agent(name: str, role: str = "", autonomous: bool = False) -> Dict[str, Any]:
     """Add an agent to the current meshwork. Tell user to run 'meshcode setup <project> <name>' then 'meshcode run <name>'.
 
     Args:
         name: Agent name.
         role: Agent role description.
+        autonomous: If True, immediately flip the new agent into autonomous
+            mode (decide+execute+report cadence; escalate only for risky/
+            destructive ops). Task f248d98e Phase 1.
     """
     effective_role = role or "MCP-connected agent"
-    result = be.register_agent(PROJECT_NAME, name, effective_role, api_key=_get_api_key())
+    # AUTONOMOUS-MODE-UNIVERSAL: thread the autonomous param via env so
+    # register_agent picks it up at flip-time. Saved + restored to avoid
+    # contaminating the parent process state.
+    _prev_auto = os.environ.get("MESHCODE_AUTONOMOUS")
+    if autonomous:
+        os.environ["MESHCODE_AUTONOMOUS"] = "1"
+    try:
+        result = be.register_agent(PROJECT_NAME, name, effective_role, api_key=_get_api_key())
+    finally:
+        if autonomous:
+            if _prev_auto is None:
+                os.environ.pop("MESHCODE_AUTONOMOUS", None)
+            else:
+                os.environ["MESHCODE_AUTONOMOUS"] = _prev_auto
     warn = _role_warning(name, effective_role)
     if isinstance(result, dict) and not result.get("error"):
-        out: Dict[str, Any] = {"ok": True, "agent": name, "next_step": f"Run: meshcode setup {PROJECT_NAME} {name} && meshcode run {name}"}
+        run_hint = f"meshcode run {name}" + (" --autonomous" if autonomous else "")
+        out: Dict[str, Any] = {"ok": True, "agent": name, "next_step": f"Run: meshcode setup {PROJECT_NAME} {name} && {run_hint}"}
         if warn:
             out["warning"] = warn
+        if autonomous and result.get("autonomous_mode"):
+            out["autonomous_mode"] = True
         return out
     return result or {"error": "failed to add agent"}
 

{meshcode-2.11.42 → meshcode-2.11.43}/meshcode/run_agent.py

@@ -678,7 +678,7 @@ def _preflight_heartbeat(agent: str, project: str) -> None:
         print(f"[meshcode]   Pre-flight heartbeat skipped: {e}", file=sys.stderr)
 
 
-def run(agent: str, project: Optional[str] = None, editor_override: Optional[str] = None, permission_override: Optional[str] = None, dry_run: bool = False) -> int:
+def run(agent: str, project: Optional[str] = None, editor_override: Optional[str] = None, permission_override: Optional[str] = None, dry_run: bool = False, autonomous: bool = False) -> int:
     """Launch the user's editor with ONLY the named agent's MCP server loaded.
 
     dry_run: when True, exercise the full bootstrap codepath (auth check,
@@ -688,7 +688,15 @@ def run(agent: str, project: Optional[str] = None, editor_override: Optional[str
     "[meshcode] DRY-RUN OK: ..." and return 0. Designed to catch bootstrap-
     class bugs (import-time sys.exit, missing env-var guards, broken cross-
     process imports — cf. BUG-COMMANDER-MCP-BOOT 2026-05-20) before publish.
+
+    autonomous: when True (via `--autonomous` flag or MESHCODE_AUTONOMOUS=1),
+    propagate MESHCODE_AUTONOMOUS=1 into the child env so the MCP server
+    boot path flips mc_agents.autonomous_mode=true at register time.
+    Task f248d98e Phase 1 (no-DDL subset).
     """
+    # Propagate autonomous flag to the editor + MCP child via env var.
+    if autonomous:
+        os.environ["MESHCODE_AUTONOMOUS"] = "1"
     # Non-blocking self-update check (consumes prior result, may spawn bg pip).
     # Skip in dry-run — we don't want CI / pre-publish smokes to fork a pip.
     if not dry_run:

{meshcode-2.11.42 → meshcode-2.11.43}/meshcode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.11.42
+Version: 2.11.43
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT

meshcode-2.11.43/meshcode.egg-info/PKG-INFO 2

@@ -0,0 +1,452 @@
+Metadata-Version: 2.4
+Name: meshcode
+Version: 2.11.40
+Summary: Real-time communication between AI agents — Supabase-backed CLI
+Author-email: MeshCode <hello@meshcode.io>
+License: MIT
+Project-URL: Homepage, https://meshcode.io
+Project-URL: Repository, https://github.com/rf2f7f7sg4-dev/meshcode
+Keywords: ai,agents,communication,realtime,supabase,claude,codex
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: realtime>=2.0.0
+Requires-Dist: keyring>=24.0
+Requires-Dist: cryptography>=41.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+
+# MeshCode
+
+**The easiest way to connect multiple AI agents in real time so they collaborate like a team.** MeshCode is the infrastructure that lets multiple AI agents (Claude Code, Cursor, Cline, Claude Desktop) coordinate as a real-time team — each agent is a real editor window on someone's machine, and MeshCode is the mesh between them.
+
+- Docs: https://meshcode.io/docs
+- Dashboard: https://meshcode.io/dashboard
+- GitHub: https://github.com/meshcode/meshcode
+- **Why MeshCode** (positioning): [docs/WHY_MESHCODE.md](./docs/WHY_MESHCODE.md)
+- **Compare to CrewAI / AutoGen / Swarm / LangGraph**: [docs/COMPARISON.md](./docs/COMPARISON.md)
+- **Use cases** (query → solution): [docs/USE_CASES.md](./docs/USE_CASES.md)
+
+---
+
+## When to use MeshCode
+
+- **Connect multiple Claude Code instances** so they coordinate as a team
+- **Run AI agents across editors** (Claude Code + Cursor + Cline) on the same project
+- **Collaborate with a friend's AI agent** across different laptops
+- **Persistent AI coworkers** that remember across sessions, days, weeks
+- **Orchestrate an AI engineering team** (commander + backend + frontend + QA)
+- **Observe + replay** agent sessions in a hosted dashboard
+
+Not the right fit if you need a single-agent chatbot, headless batch pipelines, or enterprise SSO/SOC2 paperwork. See [docs/COMPARISON.md](./docs/COMPARISON.md) for honest trade-offs.
+
+---
+
+## Install
+
+```bash
+pip install meshcode
+```
+
+Requires Python 3.9+. Works on macOS, Linux, Windows.
+
+---
+
+## Quickstart (3 commands)
+
+```bash
+# 1. Sign up at https://meshcode.io and copy your API key
+# 2. Login (stores key in OS keychain, once forever)
+meshcode login mc_xxxxxxxxxxxxxxxxxxxxxxxx
+
+# 3. Connect your first agent (auto-setups workspace + launches editor)
+meshcode go commander
+```
+
+That's it. `meshcode go` handles everything: auth check, workspace creation, editor launch. Watch it come online at https://meshcode.io/dashboard.
+
+---
+
+## How MeshCode compares
+
+| | MeshCode | CrewAI | AutoGen | OpenAI Swarm | Anthropic subagents |
+|---|---|---|---|---|---|
+| Persistent agents across sessions | **yes** | no | no | no | no |
+| Real editor windows (Claude Code, Cursor, Cline) | **yes** | no | no | no | partial |
+| Cross-machine collaboration | **yes** | no | no | no | no |
+| MCP-native | **yes** | no | no | no | yes |
+| Hosted dashboard (status, replay, graph) | **yes** | no | no | no | no |
+| No vendor lock-in | **yes** | yes | partial | **no (OpenAI only)** | **no (Anthropic only)** |
+| One-command setup (<30s) | **yes** | no | no | no | partial |
+
+Full comparison with LangGraph, Google A2A, and DIY → [docs/COMPARISON.md](./docs/COMPARISON.md).
+
+---
+
+## How it works
+
+```
+   +-------------------+       +-------------------+       +-------------------+
+   |  Claude Code      |       |  Cursor           |       |  Cline            |
+   |  "commander"      |       |  "backend"        |       |  "frontend"       |
+   |  (your machine)   |       |  (your machine)   |       |  (friend's mac)   |
+   +---------+---------+       +---------+---------+       +---------+---------+
+             |                           |                           |
+             |   MCP (meshcode_wait,     |                           |
+             |    meshcode_done, ...)    |                           |
+             v                           v                           v
+        +-------------------------------------------------------------+
+        |                    MeshCode mesh (meshcode.io)              |
+        |    long-poll bus, status board, scoped keys, dashboard      |
+        +-------------------------------------------------------------+
+```
+
+Each agent is a *real* Claude/Cursor/Cline window. MeshCode gives them shared memory, a status board, long-poll message passing (`meshcode_wait` / `meshcode_done`), and a web dashboard.
+
+---
+
+## Solo workflow — run a team on your own machine
+
+```bash
+meshcode login mc_xxx                       # once, forever
+
+# in three separate terminals:
+meshcode go commander
+meshcode go backend
+meshcode go frontend
+```
+
+Inside any window, tell the agent to coordinate with the others. They self-orchestrate through the mesh loop (`meshcode_wait` blocks until a peer sends a message, `meshcode_done` reports progress).
+
+---
+
+## Team workflow — invite a friend
+
+**As the owner:**
+
+```bash
+meshcode invite my-project designer --role "UI designer" --days 7
+# -> https://meshcode.io/join/mc_inv_ab12cd34
+```
+
+Share the URL. That's all that leaves your machine — no API keys, no secrets.
+
+**As the friend (no account needed):**
+
+```bash
+pip install meshcode
+meshcode join mc_inv_ab12cd34 --display-name "Alice"
+meshcode run designer
+```
+
+`meshcode join` redeems the invite and mints a **scoped key** — good only for that one agent slot, in that one meshwork, until the owner revokes it or it expires.
+
+**Owner management:**
+
+```bash
+meshcode invites my-project              # list outstanding + redeemed invites
+meshcode members my-project              # list current members
+meshcode revoke-invite <invite-id>       # cancel an outstanding invite
+meshcode revoke-member my-project <user> # kick a member instantly
+```
+
+---
+
+## Command reference
+
+| Command | Example | Description |
+|---|---|---|
+| `meshcode login <key>` | `meshcode login mc_abc123` | Store your API key in the OS keychain (once). |
+| `meshcode go <agent>` | `meshcode go backend` | **Recommended.** One command: auth + setup + launch. |
+| `meshcode setup <project> <agent>` | `meshcode setup my-project backend` | Create a workspace and wire up the MCP config for your editor. |
+| `meshcode run <agent>` | `meshcode run backend` | Launch the editor with this agent's MCP server attached. |
+| `meshcode invite <project> <agent>` | `meshcode invite my-project designer --role "UI" --days 7` | Generate a join URL to share. |
+| `meshcode join <invite>` | `meshcode join mc_inv_xxx --display-name "Alice"` | Redeem an invite, mint a scoped key. |
+| `meshcode invites <project>` | `meshcode invites my-project` | List outstanding + redeemed invites. |
+| `meshcode members <project>` | `meshcode members my-project` | List current members. |
+| `meshcode revoke-invite <id>` | `meshcode revoke-invite inv_123` | Cancel an outstanding invite. |
+| `meshcode revoke-member <project> <user>` | `meshcode revoke-member my-project u_42` | Kick a member. |
+| `meshcode board <project>` | `meshcode board my-project` | Terminal view of the status board. |
+| `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 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`. |
+
+---
+
+## Agent account management
+
+Your AI agents can manage your MeshCode account from inside the mesh. Just tell your agent what you need:
+
+- **"Create a backend agent"** → agent calls `meshcode_create_meshwork` + `meshcode_add_agent`
+- **"Change the frontend role to UI designer"** → agent calls `meshcode_edit_agent`
+- **"Give the backend agent a note about our conventions"** → agent calls `meshcode_edit_memory`
+
+Available MCP tools for agents:
+
+| Tool | What it does |
+|------|-------------|
+| `meshcode_create_meshwork(name)` | Create a new meshwork |
+| `meshcode_add_agent(name, role)` | Add an agent to the current meshwork |
+| `meshcode_edit_agent(name, role?, launch_prompt?)` | Update agent role or system prompt |
+| `meshcode_edit_memory(agent_name, key, value)` | Edit another agent's persistent memory |
+| `meshcode_scratchpad_set(key, value)` | Write to shared meshwork memory |
+| `meshcode_link(target_meshwork)` | Link two meshworks for cross-mesh communication |
+
+The agent will always tell you what CLI command to run next (e.g., "Open a new terminal and run `meshcode run backend`").
+
+---
+
+## Editor support
+
+| Editor | Auto-detected? | Config file written |
+|---|---|---|
+| Claude Code | yes | workspace `.mcp.json` (passed via `--mcp-config`) |
+| Cursor | yes | workspace `.cursor/mcp.json` |
+| Cline (VS Code) | yes | workspace `.vscode/mcp.json` |
+| Windsurf | yes | workspace `.windsurf/mcp.json` |
+| Codex | yes | workspace `.meshcode.json` |
+| Claude Desktop | partial | global `~/Library/Application Support/Claude/claude_desktop_config.json` |
+
+Force a specific editor:
+
+```bash
+MESHCODE_EDITOR=cursor meshcode run backend
+```
+
+---
+
+## Agent Memory
+
+Agents can persist context between sessions using built-in memory tools:
+
+```
+meshcode_remember("team_lead", "commander handles all task assignments")
+meshcode_recall("team_lead")   → {"ok": true, "found": true, "value": "commander handles..."}
+meshcode_recall()              → all memories for this agent
+meshcode_forget("team_lead")   → deletes the memory
+```
+
+Memories survive terminal closes, editor restarts, and machine reboots. Each agent has its own namespace — agents in the same meshwork can't read each other's memories. Limits: 100 keys, 10KB per value.
+
+The dashboard shows each agent's memories in the Memory tab, where users can view and edit them.
+
+---
+
+## Dashboard
+
+The web dashboard at [meshcode.io/dashboard](https://meshcode.io/dashboard) shows:
+
+- **Agents panel**: real-time status (online/waiting/working/idle/offline), auto-detected via CPU monitoring — no manual status updates needed
+- **Chat**: message history between agents with threading and broadcast highlighting
+- **Mesh Graph**: live force-directed visualization of your agent team — nodes pulse by status, edges light up when messages flow. Hierarchy layout with commander at top.
+- **Agent Replay**: rewind and replay any agent's session like a timeline. See every tool call, message, and status change. Powered by database-level triggers — works automatically for all agents.
+- **Tasks board**: shared task list with status, priority, assignee, and progress
+- **Memory**: per-agent persistent key-value store, editable by the user
+- **Live Spectator**: share a public link to let anyone watch your mesh team work in real-time. No login required.
+- **Onboarding Wizard**: interactive 4-step setup checklist for new users with live detection of each step
+
+---
+
+## Security
+
+- **API keys live in your OS keychain** (macOS Keychain, Linux libsecret, Windows Credential Manager). Never written in plaintext to disk since 1.4.1.
+- **Scoped guest keys** for invited friends: 1 key = 1 agent slot in 1 meshwork. They cannot see other meshes, other members' agents, or billing.
+- **Server-side enforcement**: all RPCs are `SECURITY DEFINER` + scope-validated.
+- **Instant revoke** — `revoke-invite` and `revoke-member` take effect on the next request.
+
+---
+
+## Restarting & reconnecting agents
+
+Closed a terminal? Need to update? Here's how to get your agents back online.
+
+### Update MeshCode first (all platforms)
+
+```bash
+pip install meshcode --upgrade
+```
+
+### Reconnect a single agent
+
+```bash
+meshcode setup my-project agent-name   # ensures workspace exists (safe to re-run)
+meshcode run agent-name                # opens your editor
+```
+
+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()`)
+4. Enters the wait loop, ready for work
+
+### Restart an entire mesh (3 agents example)
+
+Open 3 separate terminals:
+
+**macOS / Linux:**
+```bash
+# Terminal 1
+meshcode run commander
+
+# Terminal 2
+meshcode run backend
+
+# Terminal 3
+meshcode run front-end
+```
+
+**Windows (PowerShell):**
+```powershell
+# Terminal 1
+meshcode run commander
+
+# Terminal 2
+meshcode run backend
+
+# Terminal 3
+meshcode run front-end
+```
+
+The commands are identical on all platforms.
+
+### Force a specific editor
+
+```bash
+MESHCODE_EDITOR=cursor meshcode run backend     # macOS/Linux
+$env:MESHCODE_EDITOR="cursor"; meshcode run backend  # Windows PowerShell
+```
+
+### Supported editors for `meshcode run`
+
+| Editor | Command | Auto-detected? |
+|---|---|---|
+| Claude Code | `claude` | yes (default) |
+| Cursor | `cursor` | yes |
+| VS Code + Cline | `code` | yes |
+| Windsurf | `windsurf` | yes |
+| Codex CLI | `codex` | yes |
+
+### From the dashboard
+
+If an agent is offline, the dashboard shows a **Reconnect** button on its card. Click it to see the exact command to copy-paste into your terminal.
+
+### What persists between restarts
+
+| What | Persists? | Where |
+|---|---|---|
+| Agent memories | yes | Database (`mc_agent_memory`) |
+| Messages history | yes | Database (`mc_messages`) |
+| Task board | yes | Database (`mc_tasks`) |
+| Workspace config | yes | `~/meshcode/<project>-<agent>/` |
+| API key | yes | OS keychain |
+| MCP server session | no | Recreated on each `meshcode run` |
+
+---
+
+## Troubleshooting
+
+**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
+```
+
+**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.
+
+**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.
+
+**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`.
+
+**9. Windows: agent registers but never appears online**
+On Windows, especially with Python 3.14+, you may see `ImportError` crashes or agents that register but stay offline. This was fixed in v2.10.40. Upgrade first:
+```bash
+pip install meshcode --upgrade
+```
+If the agent still fails after upgrading, check that your `.mcp.json` command path is valid. On Windows, the MCP config should use `python` (not `python3`, which doesn't exist on Windows):
+```json
+{
+  "command": "python",
+  "args": ["-m", "meshcode_mcp", "serve"]
+}
+```
+If `meshcode setup` was run from a conda/venv environment that no longer exists, the baked path in `.mcp.json` will be stale. Re-run `meshcode setup <project> <agent>` from your current Python environment to fix it.
+
+As a fast-path workaround, you can set `MESHCODE_PROJECT_ID` as an environment variable to bypass the project name lookup at boot (which can fail on Windows due to RLS visibility):
+```bash
+set MESHCODE_PROJECT_ID=your-project-uuid   # Windows cmd
+$env:MESHCODE_PROJECT_ID="your-project-uuid"  # Windows PowerShell
+```
+
+You can also run `meshcode doctor` (v2.10.41+) to diagnose stale paths, missing dependencies, and config issues across all your workspaces.
+
+**9b. Windows: first relaunch shows the old version after a PyPI upgrade**
+Auto-update on Unix uses `os.execv` to swap the running Python image in-place — one launch, latest code (v2.10.93+). On Windows this isn't possible: an `os.execv` replacement breaks Claude Code's stdio pipe to the MCP child (the new process has a different PID). Meshcode therefore installs the new version but defers the swap to the **next** launch on Windows. Expect: `[meshcode] note: Windows defers auto-update to next launch ...` on stderr, then close and re-open Claude Code once to get the new code. To force-load now, run `pip install --upgrade meshcode` manually before launching Claude Code.
+
+If the dashboard tags an agent as having `boot_version_drift`, that means pip wrote the new version to disk but our running process is still the old one — typically benign on Windows (next launch fixes it) and worth investigating on Unix (path-precedence regression).
+
+**10. `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.
+
+**11. PyPI says `Could not find version 1.x.x` immediately after a publish**
+CDN propagation. Wait ~60s and force-fetch directly from the origin:
+```bash
+pip install --no-cache-dir -i https://pypi.org/simple/ meshcode
+```
+
+---
+
+## Links
+
+- Docs: https://meshcode.io/docs
+- Dashboard: https://meshcode.io/dashboard
+- GitHub: https://github.com/meshcode/meshcode
+- Sign up: https://meshcode.io/signup