wormhole

Wormhole is a collaborative AI workflow manager that provides a shared memory layer across multiple AI tools (e.g., Claude Code, GitHub Copilot, Cursor) so you can switch tools mid-task without losing context. It centralizes actions like logging, knowledge capture, and session management, and exposes a web UI to visualize sessions, events, and insights. Use the MCP tools to start sessions, pull context, log decisions and edits, and save learnings for intent-aware search. Typical usage involves starting a session, reading relevant project context, logging file edits and decisions as you work, and then ending the session with a summary. The UI lets you inspect dashboards, timelines, and analytics to improve collaboration across agents.

Prerequisites:

• Node.js and npm installed on your system
• Basic familiarity with MCP (Model Context Protocol) tooling

Option 1: npx (Recommended)

1. Ensure you have npx available (comes with npm)
2. Run a Wormhole MCP instance via npx:

npx wormhole-mcp

Option 2: Global Install

1. Install the MCP package globally:

npm install -g wormhole-mcp

2. Use the command in your MCP config as: {"command": "wormhole-mcp", "args": []}

Option 3: From Source

1. Clone the repository and install dependencies:

git clone https://github.com/fatmali/wormhole.git
cd wormhole
npm install
npm run build

2. Use the built server by pointing to the dist/server.js with Node:

"command": "node", "args": ["/path/to/wormhole/dist/server.js"]

Note: The exact invocation may differ if you use the published npm package wormhole-mcp via npx or a local build.

Tips and notes:

• The MCP UI is accessed via the built-in web interface (npx wormhole ui). The default port is 3000 unless you specify otherwise.
• Environment variables and config options can tailor logging, session naming, and knowledge capture behavior; refer to plugin and config docs for details.
• When using get_recent, you can filter by limit, detail level, delta queries, and tags to focus on relevant activity.
• If you integrate Claude Code, Copilot, or Cursor, ensure each tool is properly configured to emit and read MCP events (log, get_recent, save_knowledge, etc.).
• The system supports conflict detection and stale event rejection to help maintain consistent state across agents.