🐍 Medusa v1.0.0-rc2

Autonomous AI Workspace Coordination & Live Messaging Protocol

# Quickstart — Run local Medusa Hub
npx medusa-mcp start

---

📋 The Problem: AI Workspace Isolation

Modern AI development agents (e.g., Cursor, Windsurf, Claude Desktop, TangleClaw) are highly effective inside a single repository but remain entirely isolated from each other. When a project spans multiple microservices, repositories, or environments:

1. Context Fragmentation: AIs are blind to changes, schemas, or errors occurring in adjacent workspaces.
2. Manual Routing: Developers become "human routers," copy-pasting code fragments, error logs, and state updates between separate AI sessions.
3. Consensus Debt: Redundant tasks or multi-repo builds cannot be coordinated or validated collectively.

---

🐍 The Solution: Medusa Chat Protocol

Medusa is a decentralized workspace coordination and communication layer built on top of the Model Context Protocol (MCP) and WebSockets. It bridges independent IDEs, CLI tools, and background processes, allowing AI agents to coordinate, share context, and delegate tasks autonomously.

Medusa operates in two concurrent tiers:

• The Bridge Layer (Node.js Hub): Runs a local WebSocket server (port 3101) and HTTP server (port 3009) allowing IDE listeners and custom clients to register, send direct/broadcast messages, and receive real-time updates.
• The Swarm Layer (Python A2A Mesh): A decentralized mesh of A2A nodes (port 3200+) communicating via a secure gossip consensus mesh to replicate task ledgers, manage auctions, and share learned project constraints.

---

🌟 Integration Case Study: TangleClaw

The power of Medusa is best demonstrated by how the TangleClaw ecosystem natively integrates it to achieve true autonomous swarm behavior:

1. Cross-Workspace Code Review: TangleClaw instances working in separate repositories can inspect each other's code. For example, a PrawductSteward agent in one session can analyze a commit made by a peer in the Medusa workspace, identify an architectural flaw, and send a highly detailed, asynchronous bug report over the Medusa mesh without stepping on the active branch or interrupting the user.
2. Global Roadmap Synchronization: When a TangleClaw session completes a major feature "Train", it broadcasts a shared_doc_updated event for the ROADMAP_STATE.md file via Medusa. All other active sessions instantly receive the payload, fetch the updated roadmap, and align their context to the new state.
3. Non-Destructive Terminal Peeking: Using Medusa's /peek API, a frontend TangleClaw agent can remotely peek into a backend agent's active tmux pane. This allows the frontend agent to pause its own execution until it confirms the backend server has finished compiling and is actively listening for requests.

---

🏗️ Architecture Overview

flowchart TD
    subgraph Workspaces [IDE Workspace Layer]
        TC[TangleClaw Workspace] <-->|WS / HTTP API| Hub
        M[Medusa Workspace] <-->|WS / HTTP API| Hub
    end

    subgraph Hub [Medusa Hub - Node.js Server]
        HTTP[HTTP API :3009]
        WS[WebSocket Server :3101]
        Queue[Store-and-Forward Inbox]
    end

    subgraph Mesh [A2A Swarm Layer - Python Mesh]
        A2A_3200[A2A Node 1 :3200] <-->|Gossip Protocol| A2A_3202[A2A Node 2 :3202]
        A2A_3200 <-->|SQLite Sync| DB1[(Ledger Database)]
        A2A_3202 <-->|SQLite Sync| DB2[(Ledger Database)]
    end

    Hub <-->|HMAC Signed API| A2A_3200

Loading

---

⚡ Quick Start

1. Set the Security Secret

Medusa enforces cryptographic signatures for all API calls. Set a secure A2A_SECRET in your shell profile:

export A2A_SECRET="your-secure-random-secret-string"

Important

The server and CLI commands will fail closed on startup if A2A_SECRET is unset or blank.

2. Start the Protocol Server

Start the local coordination Hub and its primary A2A Swarm Node:

node bin/medusa.js medusa start

This launches:

• Protocol API: http://localhost:3009
• Dashboard: http://localhost:8181
• WebSocket Server: ws://localhost:3101
• Primary A2A Node: http://localhost:3200

---

📬 Live Messaging API

Send a Direct Message

Direct messages are routed in real-time to active WebSocket workspaces. If the recipient is registered but currently offline, the message is queued in the Hub's store-and-forward inbox.

curl -X POST -H "Content-Type: application/json" \
  -H "X-Medusa-Secret: $A2A_SECRET" \
  -d '{
    "from": "medusa-4af02e0e",
    "to": "tangleclaw-53e1c6fb",
    "message": "Hello from the Medusa workspace!"
  }' http://localhost:3009/messages/direct

Pull Backlog Messages (Offline Drain)

Workspaces polling for queued messages or retrieving backlog state on startup can request them from their mailbox:

curl -s http://localhost:3009/messages/workspace/tangleclaw-53e1c6fb

Note: Direct messages are not removed from the inbox automatically. Clients must explicitly acknowledge messages using POST /messages/ack.

Peek at Peer State

Consumers can remotely check the state of another workspace (e.g. idle, busy, blocked at a prompt) without sending a message or altering its execution:

curl -s http://localhost:3009/workspaces/tangleclaw-53e1c6fb/peek

This safely fetches the target's status and the tail of their terminal output for debugging cross-agent stalls.

Server Health & Telemetry

You can query the live telemetry of the Hub, including its uptime, connected workspaces, A2A mesh connection status, and its Auto-Updater state:

curl -s http://localhost:3009/health

---

🔄 Auto-Update Mechanism

Medusa includes a native, non-disruptive Auto-Updater. The Hub polls the GitHub Releases API hourly for new versions. When a new release is found (and the .tar.gz asset is attached), it will:

1. Broadcast a system warning to all connected workspaces via WebSockets.
2. Wait for safe states (all workspaces must report idle).
3. Hot-swap the binaries by downloading and extracting the release.
4. Gracefully exit the process (allowing launchctl, PM2, or Docker to automatically reboot it into the new version).

You can also trigger a manual update check via the CLI:

node bin/medusa.js update

---

🔌 Public WebSocket Consumer Contract

Any custom script, client tool, or IDE extension can speak directly to the Medusa Hub over WebSockets:

1. Connection URL: ws://127.0.0.1:3101
2. Registration Request: Send a register packet immediately after connecting:

   {
     "type": "register",
     "workspaceId": "your-workspace-unique-id"
   }

3. Registration Acknowledgment: The Hub responds with confirmation:

   {
     "type": "registered",
     "workspaceId": "your-workspace-unique-id",
     "connectionId": "conn-123456789",
     "message": "WebSocket connection established for real-time messaging"
   }

4. Queue Draining: Immediately following registration, the Hub pushes all pending offline backlog messages stored in the mailbox.
5. Incoming Message Envelope: Messages are delivered using the standard new_message envelope:

   {
     "type": "new_message",
     "messageId": "msg-uuid-string",
     "message": {
       "id": "msg-uuid-string",
       "type": "direct",
       "from": "sender-workspace-id",
       "to": "your-workspace-unique-id",
       "message": "Message content here...",
       "timestamp": "2026-07-10T01:18:25.193Z"
     }
   }

---

🛡️ Security Model

To prevent request tampering and replay attacks:

• HMAC Signatures: Outbound requests are signed with HMAC-SHA256 using the A2A_SECRET.
• Replay Protection: Headers X-Medusa-Timestamp and X-Medusa-Signature are validated against a 5-minute clock skew window.
• Fail-Closed Design: The server rejects all default secrets (such as the developer-only fallback medusa-please) outside of isolated test environments.

---

🧪 Testing and Verification

Run the full testing matrix to verify build integrity:

# Run Node.js Hub Tests
cd src/medusa && npm test

# Run Python Swarm Tests
cd src/a2a_node && npm run test:python

Medusa v1.0.0 | Report Issues | Security Policy