Content
# 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`
- **Knowledge Capture & Search** - Save decisions/pitfalls and surface them with intent-aware search
## Quick Start
Try instantly with npx (no installation required):
```bash
npx wormhole-mcp
```
### Minimal Workflow (token-optimized)
1) `start_session`
2) Pull context: `search_project_knowledge` + `get_recent`
3) Before edits: `check_conflicts`
4) During work: `log` every file_edit/cmd_run/decision/test_result/todos
5) Capture learnings: `save_knowledge` (decision/pitfall/convention/constraint)
6) Finish: `end_session` with summary
```javascript
start_session({ project_path: ".", agent_id: "copilot", name: "fix-auth" })
search_project_knowledge({ project_path: ".", intent: "debugging", query: "auth" })
get_recent({ project_path: "." })
check_conflicts({ project_path: ".", files: ["src/auth.ts"] })
log({ action: "file_edit", agent_id: "copilot", project_path: ".", content: { file_path: "src/auth.ts", description: "Fix timeout" } })
save_knowledge({ project_path: ".", knowledge_type: "decision", title: "Use async DB client", content: "Prevents blocking" })
end_session({ session_id: "abc-123", summary: "Auth fixed; tests green" })
```
## Web UI
Visualize your agent activity with the built-in web interface:
```bash
# 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`:
```json
{
"mcpServers": {
"wormhole": {
"command": "npx",
"args": ["-y", "wormhole-mcp"]
}
}
}
```
**GitHub Copilot** — Add to `.vscode/mcp.json` in your project:
```json
{
"servers": {
"wormhole": {
"command": "npx",
"args": ["-y", "wormhole-mcp"]
}
}
}
```
### Option 2: Global Install
```bash
npm install -g wormhole-mcp
```
Then use `"command": "wormhole-mcp"` in your config.
### Option 3: From Source
```bash
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:
```bash
claude --plugin-dir ./node_modules/wormhole-mcp/plugins/wormhole
```
Then invoke with `/wormhole:wormhole` in Claude Code.
**Standalone skill** (simpler):
```bash
cp -r node_modules/wormhole-mcp/skills/wormhole .claude/skills/
```
## MCP Tools
### `log`
Universal logging for any action type:
```javascript
// 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):
```javascript
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:
```javascript
get_tags({ project_path: "/path/to/project" })
// Output:
// tags:
// bugfix (12)
### `save_knowledge`
Persist decisions, pitfalls, conventions, or constraints so agents don’t repeat mistakes.
```javascript
save_knowledge({
project_path: "/path/to/project",
knowledge_type: "pitfall",
title: "Avoid fs.readFileSync in handlers",
content: "Blocks event loop; causes timeouts",
confidence: 0.9
})
```
### `search_project_knowledge`
Intent-aware lookup of stored knowledge. Prefers types that match your intent.
```javascript
search_project_knowledge({
project_path: "/path/to/project",
intent: "debugging",
query: "auth"
})
// → [{ type: "pitfall", summary: "Avoid fs.readFileSync", confidence: 0.9 }]
```
// feature (8)
// testing (5)
// auth (3)
```
**Options:**
- `with_counts` - Include event counts per tag (default: true)
### `check_conflicts`
Detect concurrent file edits:
```javascript
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:
```javascript
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:
```javascript
// 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:
```javascript
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:
```javascript
end_session({
session_id: "abc-123-def",
summary: "Fixed timeout by optimizing DB query"
})
```
### `list_sessions`
View sessions:
```javascript
list_sessions({ project_path: "/path/to/project" })
```
**Output:**
```
● bugfix-auth (2h) by claude
○ feature-payment (1d) by cursor
```
### `switch_session`
Resume a previous session:
```javascript
switch_session({ session_id: "xyz-789" })
```
---
## Configuration
Config file: `~/.wormhole/config.json`
```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 for `get_recent` responses through four key strategies:
### 1. Compact Output Format (Default)
Instead of returning raw JSON, events are formatted as single-line summaries:
```
# Compact (default) - ~35 chars per event
[5m] claude: npm test → ✓
# vs Full JSON - ~200+ chars per event
{"id":42,"agent_id":"claude-code","action":"cmd_run","payload":"{\"command\":\"npm test\",\"exit_code\":0}","timestamp":1706621234567,"project_path":"/path/to/project","session_id":"abc-123"}
```
The `detail` parameter controls verbosity:
- `minimal` (default) — Single-line summaries with symbols (✓/✗)
- `normal` — Multi-line with key details
- `full` — Complete JSON payloads
### 2. Payload Truncation
Content fields are truncated to 200 characters by default (`max_payload_chars` config):
```javascript
// Stored/displayed as:
"Added authentication middleware with JWT validation and refresh token..."
// Instead of full 2000+ char description
```
**Exception:** `diff` fields in `file_edit` events are never truncated—they're needed for stale event validation.
### 3. Delta Queries
Use `since_cursor` to fetch only events since your last query:
```javascript
// First call returns events + cursor
get_recent({ project_path: "." })
// → [5 events] + cursor: evt_42
// Subsequent call returns only NEW events
get_recent({ project_path: ".", since_cursor: "evt_42" })
// → [0-2 events] instead of repeating all 5
```
This prevents re-sending the same context repeatedly.
### 4. Low Default Limits
- `default_limit: 5` — Returns only 5 most recent events
- Agents can increase with `limit` param when needed
### Token Comparison
| Scenario | Without Optimization | With Optimization |
|----------|---------------------|-------------------|
| 5 events, first query | ~500-1000 tokens | ~100 tokens |
| 5 events, delta query (2 new) | ~500-1000 tokens | ~40 tokens |
| 10 events, full detail | ~2000+ tokens | ~800 tokens |
### Configuration
Adjust in `~/.wormhole/config.json`:
```json
{
"max_payload_chars": 200,
"default_detail": "minimal",
"default_limit": 5
}
```
## 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
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available