Metadata-Version: 2.4
Name: meshcode
Version: 2.10.54
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

# 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.

**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
