Wormhole 🌀

Collaborative AI Workflow Manager

Keep your AI coding agents in sync. Wormhole gives Claude Code, GitHub Copilot, and Cursor a shared memory layer—so when you switch tools mid-task, nothing gets lost.

Works across:

• 🔀 Multiple subagents within the same tool (e.g., parallel Claude tasks)
• 🔄 Different AI tools entirely (Claude ↔ Copilot ↔ Cursor)

⚠️ Disclaimer: Wormhole is an early-stage project. APIs and behavior may change, and there may be rough edges. It’s built in the open and evolving fast based on real developer feedback.

Features

• Universal Logging - Single log tool for any action type
• Event Tagging - Categorize events with tags for better organization
• Session Management - Named work sessions with isolation
• Token Optimized - Compact output, delta queries, relevance filtering
• Conflict Detection - Know when agents touch the same files
• Stale Event Rejection - Automatically filters out file edits that no longer exist in the current project state
• Web UI Visualization - View sessions, timeline events, and insights with npx wormhole ui

Quick Start

Try instantly with npx (no installation required):

npx wormhole-mcp

Web UI

Visualize your agent activity with the built-in web interface:

# Start the UI server (default port: 3000)
npx wormhole ui

# Or specify a custom port
npx wormhole ui 8080

Then open http://localhost:3000 in your browser to see:

• 📊 Dashboard - Stats on events, sessions, and agents
• ⏱️ Timeline - Visual event stream with filtering
• 📋 Sessions - All work sessions with details
• 📈 Insights - Action types and tag analytics

Installation

Option 1: npx (Recommended)

Claude Code — Add to ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "wormhole": {
      "command": "npx",
      "args": ["-y", "wormhole-mcp"]
    }
  }
}

GitHub Copilot — Add to .vscode/mcp.json in your project:

{
  "servers": {
    "wormhole": {
      "command": "npx",
      "args": ["-y", "wormhole-mcp"]
    }
  }
}

Option 2: Global Install

npm install -g wormhole-mcp

Then use "command": "wormhole-mcp" in your config.

Option 3: From Source

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

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

### Claude Code Plugin

For Claude Code users, there's an optional plugin that bundles the MCP server config with a skill:

```bash
# Install the plugin
claude /install-plugin ./node_modules/wormhole-mcp/plugins/wormhole

Or test locally:

claude --plugin-dir ./node_modules/wormhole-mcp/plugins/wormhole

Then invoke with /wormhole:wormhole in Claude Code.

Standalone skill (simpler):

cp -r node_modules/wormhole-mcp/skills/wormhole .claude/skills/

MCP Tools

log

Universal logging for any action type:

// Log a command
log({
  action: "cmd_run",
  agent_id: "claude-code",
  project_path: "/path/to/project",
  content: { command: "npm test", exit_code: 0 },
  tags: ["testing", "ci"]  // Optional: categorize events
})

// Log a file edit
log({
  action: "file_edit",
  agent_id: "claude-code",
  project_path: "/path/to/project",
  content: { file_path: "src/auth.ts", description: "Added JWT validation" },
  tags: ["bugfix", "auth"]
})

// Log a decision
log({
  action: "decision",
  agent_id: "claude-code",
  project_path: "/path/to/project",
  content: { decision: "Use Zod for validation", rationale: "Already in deps" }
})

// Log test results
log({
  action: "test_result",
  agent_id: "claude-code",
  project_path: "/path/to/project",
  content: { test_suite: "auth.test.ts", status: "passed" }
})

// Log user feedback
log({
  action: "feedback",
  agent_id: "claude-code",
  project_path: "/path/to/project",
  content: { agent_suggestion: "Use async/await", user_response: "rejected", user_note: "Legacy code" }
})

// Log todos
log({
  action: "todos",
  agent_id: "claude-code",
  project_path: "/path/to/project",
  content: {
    items: [
      { task: "Add input validation", status: "pending", priority: "high" },
      { task: "Write unit tests", status: "done" },
      { task: "Update README", status: "pending" }
    ],
    context: "Auth refactor"
  }
})

// Log plan output
log({
  action: "plan_output",
  agent_id: "claude-code",
  project_path: "/path/to/project",
  content: {
    title: "API Authentication Design",
    type: "architecture",
    content: "Use JWT with refresh tokens, store in httpOnly cookies..."
  }
})

Action Types:

• cmd_run - Command executions
• file_edit - File modifications
• decision - Design decisions with rationale
• test_result - Test outcomes
• feedback - User acceptance/rejection
• todos - Task items with status tracking
• plan_output - Planning artifacts (design, architecture, tasks)
• Any custom type you need

get_recent

Get recent activity (compact by default):

get_recent({ project_path: "/path/to/project" })

Output:

[5m] claude: npm test → ✓
[8m] cursor: edit auth.ts "Add JWT"
[12m] copilot: decided "Use Zod for validation"
[15m] claude: auth.test.ts ✓
cursor: evt_123

Options:

• limit - Max events (default: 5)
• detail - minimal | normal | full
• since_cursor - Only new events (delta query)
• related_to - Filter by file paths
• action_types - Filter by action types
• tags - Filter by tags (e.g., ["bugfix", "feature"])

get_tags

Get all unique tags used in a project with counts:

get_tags({ project_path: "/path/to/project" })
// Output: 
// tags:
// bugfix (12)
// feature (8)
// testing (5)
// auth (3)

Options:

• with_counts - Include event counts per tag (default: true)

check_conflicts

Detect concurrent file edits:

check_conflicts({ project_path: "/path/to/project" })

Stale Event Rejection

Wormhole automatically tracks and validates file edits to ensure agents never act on stale information. When a file_edit event is logged with a diff, Wormhole:

1. Extracts the full patch - Stores all added/removed lines from the diff
2. Validates on query - When events are retrieved via get_recent or conflict detection, each file edit is checked against the current file state
3. Fuzzy matching - Uses intelligent matching to handle code that moved positions, only rejecting truly stale edits
4. Auto-filters - Rejected events are automatically excluded from results

How it works

When you log a file edit:

log({
  action: "file_edit",
  agent_id: "claude-code",
  project_path: "/path/to/project",
  content: {
    file_path: "src/auth.ts",
    description: "Added JWT validation",
    diff: `--- a/src/auth.ts
+++ b/src/auth.ts
@@ -10,6 +10,7 @@
 function validateToken(token: string) {
+  const decoded = jwt.verify(token, SECRET);
   return decoded;
 }`
  }
})

Wormhole stores the full diff in the payload. Later, when another agent queries recent events:

• File still has the change → Event is included
• Code was removed or changed → Event is silently filtered out
• Code moved to different location → Still recognized (fuzzy match)

Note: The diff field is NOT truncated (unlike other content fields), ensuring accurate validation even for large changes.

This ensures agents always work with accurate context about what's currently in the codebase.

Validation Algorithm

The patch validation uses intelligent fuzzy matching:

For Added Lines (+):

• Checks if the added code exists anywhere in the current file
• Uses normalized comparison (trimmed whitespace)
• Accepts partial matches (code that contains or is contained by the search)
• Requires 60% of added lines to match for validation

For Removed Lines (-):

• If a "removed" line still exists in the file → patch is stale
• This catches cases where a deletion was reverted

Edge Cases Handled:

• File deleted: Patch fails validation
• Code refactored: Fuzzy matching still finds the logic if it exists
• Whitespace changes: Normalized comparison ignores formatting
• Line movements: Searches entire file, not just original position
• No patch stored: Event is kept (backward compatibility)
• Already rejected: Event is skipped on subsequent queries

Performance

• Validation runs only when events are queried (lazy evaluation)
• File I/O is cached by OS for repeated reads
• Minimal overhead: ~1-5ms per file_edit event
• Database stores full diffs efficiently as TEXT columns

cleanup

Clean up events with scopes:

// Clean entire project
cleanup({ scope: "project", project_path: "/path/to/project" })

// Clean specific session
cleanup({ scope: "session", session_id: "abc-123" })

// Clean everything
cleanup({ scope: "all", force: true })

Session Management

start_session

Start a named work session:

start_session({
  project_path: "/path/to/project",
  agent_id: "claude-code",
  name: "bugfix-auth",
  description: "Fixing login timeout issue"
})
// → session started: bugfix-auth (abc-123-def)

Sessions automatically isolate context—previous events hidden from queries.

end_session

End a session with summary:

end_session({
  session_id: "abc-123-def",
  summary: "Fixed timeout by optimizing DB query"
})

list_sessions

View sessions:

list_sessions({ project_path: "/path/to/project" })

Output:

● bugfix-auth (2h) by claude
○ feature-payment (1d) by cursor

switch_session

Resume a previous session:

switch_session({ session_id: "xyz-789" })

Configuration

Config file: ~/.wormhole/config.json

{
  "retention_hours": 24,
  "max_payload_chars": 200,
  "auto_cleanup": true,
  "default_detail": "minimal",
  "default_limit": 5
}

Note: The max_payload_chars setting truncates most content fields for display, but diff fields in file_edit events are always stored in full to enable accurate stale-event validation.

Token Optimization

Wormhole minimizes token usage:

• Compact output by default
• Delta queries with since_cursor
• 200-char payload limits
• 5 events default limit

Typical task: ~400 tokens vs ~5,000 without optimization.

Architecture

┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ Claude Code │  │  Copilot    │  │   Cursor    │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │
       └────────────────┼────────────────┘
                        │
                ┌───────▼───────┐
                │   Wormhole    │
                │  MCP Server   │
                └───────┬───────┘
                        │
                ┌───────▼───────┐
                │    SQLite     │
                │  timeline.db  │
                └───────────────┘

Data Storage

• Database: ~/.wormhole/timeline.db
• Config: ~/.wormhole/config.json
• Archives: ~/.wormhole/archives/

License

MIT