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

# MeshCode

**Persistent AI coworkers.** 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

---

## Install

```bash
pip install meshcode
```

Requires Python 3.9+. Works on macOS, Linux, Windows.

---

## Quickstart (the 5-command happy path)

```bash
# 1. Sign up at https://meshcode.io and copy the mc_xxx key shown once on onboarding
# 2. Store it in your OS keychain (once, forever)
meshcode login mc_xxxxxxxxxxxxxxxxxxxxxxxx

# 3. Create a workspace for your first agent
meshcode setup my-project commander

# 4. Launch the agent (this opens your editor with the MCP server wired up)
meshcode run commander

# 5. Watch it come online in the dashboard at https://meshcode.io/dashboard
```

That's it. Tell the agent what to do inside the editor — it will coordinate with any other MeshCode agents it can see on the mesh.

---

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

meshcode setup my-project commander         # ~/meshcode/my-project-commander/
meshcode setup my-project backend
meshcode setup my-project frontend

# in three separate terminals:
meshcode run commander
meshcode run backend
meshcode run 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 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 --version` | `meshcode --version` | Print `meshcode 1.5.1`. |
| `meshcode help` | `meshcode help` | Top-level help. Per-verb help: `meshcode <verb> --help`. |

---

## 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 | yes | workspace `.vscode/mcp.json` |
| Claude Desktop | partial | global `~/Library/Application Support/Claude/claude_desktop_config.json` |

Force a specific editor:

```bash
MESHCODE_EDITOR=cursor meshcode run backend
```

---

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

---

## Troubleshooting

**1. `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`**
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`**
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`**
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.

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

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