Wormhole

Registra edições de arquivos, decisões e comandos para que os agentes permaneçam sincronizados, evitem conflitos e retomem de onde outros pararam.

GitHub

Experimente este MCPPatrocinado

Documentação

Wormhole 🌀

Gerenciador Colaborativo de Fluxos de Trabalho com IA

Mantenha seus agentes de codificação com IA sincronizados. O Wormhole oferece ao Claude Code, GitHub Copilot e Cursor uma camada de memória compartilhada—para que, ao alternar ferramentas no meio de uma tarefa, nada se perca.

Funciona com:

🔀 Múltiplos subagentes dentro da mesma ferramenta (ex.: tarefas paralelas do Claude)
🔄 Ferramentas de IA diferentes (Claude ↔ Copilot ↔ Cursor)

⚠️ Aviso: O Wormhole é um projeto em estágio inicial. APIs e comportamentos podem mudar, e pode haver arestas a serem polidas. Ele é construído de forma aberta e evolui rapidamente com base no feedback real de desenvolvedores.

Recursos

Registro Universal - Ferramenta única log para qualquer tipo de ação
Marcação de Eventos - Categorize eventos com tags para melhor organização
Gerenciamento de Sessões - Sessões de trabalho nomeadas com isolamento
Otimizado para Tokens - Saída compacta, consultas delta, filtragem por relevância
Detecção de Conflitos - Saiba quando agentes tocam nos mesmos arquivos
Rejeição de Eventos Obsoletos - Filtra automaticamente edições de arquivos que não existem mais no estado atual do projeto
Visualização via Web UI - Veja sessões, eventos de linha do tempo e insights com npx wormhole ui
Captura e Busca de Conhecimento - Salve decisões/armadilhas e exiba-as com busca consciente de intenção

Início Rápido

Experimente instantaneamente com npx (sem necessidade de instalação):

npx wormhole-mcp

Fluxo de Trabalho Mínimo (otimizado para tokens)

start_session
Obtenha contexto: search_project_knowledge + get_recent
Antes de editar: check_conflicts
Durante o trabalho: log para cada file_edit/cmd_run/decision/test_result/todos
Capture aprendizados: save_knowledge (decision/pitfall/convention/constraint)
Finalize: end_session com resumo

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 a atividade dos seus agentes com a interface web integrada:

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

# Or specify a custom port
npx wormhole ui 8080

Depois abra http://localhost:3000 no seu navegador para ver:

📊 Painel - Estatísticas sobre eventos, sessões e agentes
⏱️ Linha do Tempo - Fluxo visual de eventos com filtragem
📋 Sessões - Todas as sessões de trabalho com detalhes
📈 Insights - Tipos de ação e análises de tags

Instalação

Opção 1: npx (Recomendado)

Claude Code — Adicione ao ~/.claude/claude_code_config.json:

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

GitHub Copilot — Adicione ao .vscode/mcp.json no seu projeto:

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

Opção 2: Instalação Global

npm install -g wormhole-mcp

Depois use "command": "wormhole-mcp" na sua configuração.

Opção 3: A partir do Código Fonte

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

Use "command": "node" com "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

Ou teste localmente:

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

Depois invoque com /wormhole:wormhole no Claude Code.

Skill autônoma (mais simples):

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

Ferramentas MCP

`log`

Registro universal para qualquer tipo de ação:

// 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..."
  }
})

Tipos de Ação:

cmd_run - Execuções de comandos
file_edit - Modificações de arquivos
decision - Decisões de design com justificativa
test_result - Resultados de testes
feedback - Aceitação/rejeição do usuário
todos - Itens de tarefa com acompanhamento de status
plan_output - Artefatos de planejamento (design, arquitetura, tarefas)
Qualquer tipo personalizado que você precisar

`get_recent`

Obtenha atividade recente (compacta por padrão):

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

Saída:

[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

Opções:

limit - Máximo de eventos (padrão: 5)
detail - minimal | normal | full
since_cursor - Apenas novos eventos (consulta delta)
related_to - Filtrar por caminhos de arquivo
action_types - Filtrar por tipos de ação
tags - Filtrar por tags (ex.: ["bugfix", "feature"])

`get_tags`

Obtenha todas as tags exclusivas usadas em um projeto com contagens:

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`

Busca consciente de intenção do conhecimento armazenado. Prefere tipos que correspondem à sua intenção.

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

Rejeição de Eventos Obsoletos

O Wormhole rastreia e valida automaticamente edições de arquivos para garantir que os agentes nunca ajam com base em informações desatualizadas. Quando um evento file_edit é registrado com um diff, o Wormhole:

Extrai o patch completo - Armazena todas as linhas adicionadas/removidas do diff
Valida na consulta - Quando os eventos são recuperados via get_recent ou detecção de conflitos, cada edição de arquivo é verificada em relação ao estado atual do arquivo
Correspondência difusa - Usa correspondência inteligente para lidar com código que mudou de posição, rejeitando apenas edições verdadeiramente obsoletas
Filtragem automática - Eventos rejeitados são excluídos automaticamente dos resultados

Como funciona

Quando você registra uma edição de arquivo:

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;
 }`
  }
})

O Wormhole armazena o diff completo no payload. Depois, quando outro agente consulta eventos recentes:

O arquivo ainda tem a alteração → O evento é incluído
O código foi removido ou alterado → O evento é silenciosamente filtrado
O código mudou para outro local → Ainda é reconhecido (correspondência difusa)

Nota: O campo diff NÃO é truncado (diferente de outros campos de conteúdo), garantindo validação precisa mesmo para alterações grandes.

Isso garante que os agentes sempre trabalhem com contexto preciso sobre o que está atualmente no código.

Algoritmo de Validação

A validação de patch usa correspondência difusa inteligente:

Para Linhas Adicionadas (+):

Verifica se o código adicionado existe em qualquer lugar do arquivo atual
Usa comparação normalizada (espaços em branco removidos)
Aceita correspondências parciais (código que contém ou está contido na busca)
Requer 60% das linhas adicionadas correspondentes para validação

Para Linhas Removidas (-):

Se uma linha "removida" ainda existe no arquivo → o patch está obsoleto
Isso captura casos em que uma exclusão foi revertida

Casos Extremos Tratados:

Arquivo excluído: O patch falha na validação
Código refatorado: A correspondência difusa ainda encontra a lógica se ela existir
Alterações de espaços em branco: A comparação normalizada ignora formatação
Movimentação de linhas: Busca no arquivo inteiro, não apenas na posição original
Sem patch armazenado: O evento é mantido (compatibilidade retroativa)
Já rejeitado: O evento é ignorado em consultas subsequentes

Desempenho

A validação é executada apenas quando os eventos são consultados (avaliação preguiçosa)
A E/S de arquivos é armazenada em cache pelo SO para leituras repetidas
Sobrecarga mínima: ~1-5ms por evento file_edit
O banco de dados armazena diffs completos eficientemente como colunas TEXT

`cleanup`

Limpe eventos com escopos:

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

Gerenciamento de Sessões

`start_session`

Inicie uma sessão de trabalho nomeada:

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)

As sessões isolam automaticamente o contexto—eventos anteriores ficam ocultos das consultas.

`end_session`

Encerre uma sessão com resumo:

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

`list_sessions`

Veja as sessões:

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

Saída:

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

`switch_session`

Retome uma sessão anterior:

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

Configuração

Arquivo de configuração: ~/.wormhole/config.json

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

Nota: A configuração max_payload_chars trunca a maioria dos campos de conteúdo para exibição, mas os campos diff em eventos file_edit são sempre armazenados por completo para permitir validação precisa de eventos obsoletos.

Otimização de Tokens

O Wormhole minimiza o uso de tokens para respostas get_recent por meio de quatro estratégias principais:

1. Formato de Saída Compacto (Padrão)

Em vez de retornar JSON bruto, os eventos são formatados como resumos de linha única:

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

O parâmetro detail controla a verbosidade:

minimal (padrão) — Resumos de linha única com símbolos (✓/✗)
normal — Várias linhas com detalhes principais
full — Payloads JSON completos

2. Truncamento de Payload

Os campos de conteúdo são truncados para 200 caracteres por padrão (config max_payload_chars):

// Stored/displayed as:
"Added authentication middleware with JWT validation and refresh token..."

// Instead of full 2000+ char description

Exceção: Os campos diff em eventos file_edit nunca são truncados—eles são necessários para a validação de eventos obsoletos.

3. Consultas Delta

Use since_cursor para buscar apenas eventos desde sua última consulta:

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

Isso evita reenviar o mesmo contexto repetidamente.

4. Limites Padrão Baixos

default_limit: 5 — Retorna apenas os 5 eventos mais recentes
Os agentes podem aumentar com o parâmetro limit quando necessário

Comparação de Tokens

Cenário	Sem Otimização	Com Otimização
5 eventos, primeira consulta	~500-1000 tokens	~100 tokens
5 eventos, consulta delta (2 novos)	~500-1000 tokens	~40 tokens
10 eventos, detalhe completo	~2000+ tokens	~800 tokens

Configuração

Ajuste em ~/.wormhole/config.json:

{
  "max_payload_chars": 200,
  "default_detail": "minimal",
  "default_limit": 5
}

Arquitetura

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

Armazenamento de Dados

Banco de dados: ~/.wormhole/timeline.db
Configuração: ~/.wormhole/config.json
Arquivos: ~/.wormhole/archives/

Licença

MIT