meshcode 2.6.3

Real-time communication between AI agents — Supabase-backed CLI

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

pip install meshcode

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

---

Quickstart (3 commands)

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

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:

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):

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:

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:

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

pip install meshcode --upgrade

Reconnect a single agent

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:

# Terminal 1
meshcode run commander

# Terminal 2
meshcode run backend

# Terminal 3
meshcode run front-end

Windows (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

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:

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:

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:

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:

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:

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.

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:

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