Agent Live Share
Agent Live Share
Agent Live Share é um servidor MCP que permite que vários agentes de programação trabalhem no mesmo workspace real, sem clones, worktrees ou cópias paralelas. Em vez de dividir o repositório, os agentes compartilham os arquivos e negociam acesso a cada arquivo antes de editá-lo.
A analogia é “Live Share para agentes”, mas com coordenação explícita: salas, tarefas, locks exclusivos por arquivo, patches com hash esperado e checkpoints que pausam gravações.
Nome público e codename: o produto público é Agent Live Share. Collab MCP é o codename interno usado em
AGENTS.md,CLAUDE.md, comentários, nomes de módulos, logs e ferramentascollab_*. O binário e o server name continuamcollab-mcppara não quebrar o contrato atual; a implementação é a mesma.Status 0.1.0: modo local cooperativo, endpoint loopback por padrão. A autenticação Bearer por principal, a autorização por workspace e os fluxos multicliente estão implementados e testados. Não há validação de clientes reais em produção, Tailscale configurado, bridge stdio, modo estrito ou UI.
O problema
Agentes diferentes normalmente resolvem concorrência criando clones, branches ou worktrees. Isso funciona isoladamente, mas não resolve o caso de duas pessoas trabalhando no mesmo sistema real ao mesmo tempo: o trabalho precisa aparecer imediatamente para todos, e a divisão de arquivos precisa ser negociada sem sobrescritas silenciosas.
Agent Live Share coordena esse espaço compartilhado:
o coordinator propõe a divisão e acompanha dependências;
workers aceitam e executam tarefas em arquivos diferentes;
reviewers revisam handoffs quando o convite permite;
o lock exclusivo organiza a posse temporária de um arquivo;
patches com
expectedHashevitam salvar uma leitura antiga por cima do trabalho de outro agente;o checkpoint pausa escritas para testes e commits em um estado estável.
Related MCP server: Agent Collab MCP
Principais recursos
Área | Recurso |
Salas | Coordinator, worker e reviewer; convite; heartbeat; transferência explícita de coordenação |
Comunicação | Mensagens de sala e diretas, polling por cursor, solicitações de plano e respostas correlacionadas |
Trabalho | Tarefas, dependências, progresso, bloqueios, handoffs e revisão |
Workspace | Catálogo allowlisted, leitura/busca, patch delimitado, criação, histórico, backup e restauração |
Concorrência | Lock exclusivo global por workspace, heartbeat, expiração e negociação por mensagem |
Integridade |
|
Checkpoints | Início por coordinator atual, pausa global de mutações, encerramento anti-deadlock e eventos de autoria |
Identidade | Bearer por principal, somente hash persistido, revogação imediata, sessão de sala vinculada ao principal |
Autorização |
|
Operação | CLI de credenciais, health público, |
Arquitetura
flowchart LR
OC["OpenCode"] --> MCP["Agent Live Share<br/>MCP Streamable HTTP<br/>Bearer por principal"]
CX["Codex"] --> MCP
CC["Claude Code"] --> MCP
MCP --> COL["Collaboration<br/>rooms · messages · tasks · handoffs"]
MCP --> WS["Workspace<br/>read/search · patches · versions · checkpoints"]
MCP --> LK["Locking<br/>exclusive locks · heartbeat"]
COL --> DB[("SQLite<br/>state · hashes · audit")]
WS --> DB
LK --> DB
WS --> HOST[("One host workspace<br/>same files for every agent")]O servidor escuta em loopback por padrão (127.0.0.1:3100). O acesso remoto não é habilitado por este repositório; o runbook de Tailscale Serve em adapters/tailscale é um template, não uma configuração validada.
Como funciona
1. Principal e sessão são coisas diferentes
O Bearer identifica a pessoa, o cliente ou a instalação — o principal. O token de sessão de sala identifica o agente dentro de uma sala específica. Um principal pode criar ou entrar em várias salas, mas um sessionToken vazado não funciona com o Bearer de outro principal.
O Bearer é configurado no cliente MCP e nunca é argumento de tool. A sessão de sala é devolvida uma única vez por collab_create_room ou collab_join_room.
2. Coordinator distribui o trabalho
O criador da sala vira coordinator + worker. Ele pode criar convites, propor tarefas, atribuir trabalho, criar checkpoints e responder solicitações de plano. A coordenação é explícita e transferível; não há eleição automática nem failover mágico.
3. Arquivos diferentes avançam em paralelo
Dois agentes podem ler e editar arquivos distintos ao mesmo tempo. Para gravar em um arquivo existente, o fluxo é:
ler o arquivo e guardar
hash/version;adquirir um lock exclusivo do arquivo;
reler o arquivo depois do lock — o hash pode ter mudado;
aplicar um patch delimitado com
expectedHash;liberar o lock e publicar progresso/handoff.
O lock é global por workspace, não por sala. Se duas salas apontam para o mesmo workspace, elas disputam o mesmo arquivo. O conflito retorna dono, intenção e expiração para negociação; não há roubo de lock pelo coordinator.
4. Hash impede sobrescrita, lock organiza a posse
O lock não substitui a verificação de conteúdo. Mesmo com um lock válido, uma gravação com hash antigo é rejeitada. O histórico mantém o estado anterior e o novo, com autor, sessão e data; restaurar publica uma nova versão em vez de apagar o passado.
5. Checkpoint pausa o workspace
O coordinator atual pode iniciar um checkpoint quando não há locks ativos. Enquanto ele estiver aberto, patches, criações e restaurações falham com CHECKPOINT_IN_PROGRESS. Qualquer coordinator atual do mesmo workspace pode encerrar — regra anti-deadlock — e a autoria de criação e encerramento fica registrada.
6. Falhas de escrita são recuperáveis
Antes de tocar o disco, o servidor grava um journal com o conteúdo anterior, o conteúdo pretendido, o lock e o plano de versões. Se o processo cair entre o disco e o registro da versão, a próxima operação tenta finalizar ou descartar o journal de forma conservadora. Se o disco foi alterado externamente e o estado é indecidível, o arquivo fica bloqueado para novas mutações até revisão, em vez de adivinhar.
Quickstart
Requisitos
Node.js >= 24 (validado com 24.19);
npm;
Windows é o ambiente principal validado; CI usa Node 24 em
windows-latest;um cliente MCP com suporte a Streamable HTTP e header
Authorization.
Node 22 não é suportado nesta versão. No primeiro CI público,
better-sqlite3@13.2.0não obteve um prebuild compatível no runner Windows/Node 22 e caiu paranode-gyp; onode-gyp11.5 não reconheceu o Visual Studio 18 do runner. Exigir Node 24 evita depender de compilação nativa/Visual Studio e corresponde ao runtime realmente validado.
O projeto não é publicado no npm. Rode a partir do checkout.
1. Instale
git clone https://github.com/viniciusadami-ux/agent-live-share.git
cd agent-live-share
npm ciNo PowerShell deste projeto usamos npm.cmd; em outros shells, npm é equivalente.
2. Crie um principal
Copy-Item workspaces.example.json workspaces.json
npm.cmd run auth:create -- "Seu Nome / OpenCode"Em macOS/Linux, use cp workspaces.example.json workspaces.json.
O comando imprime uma vez o prin_... e o Bearer collab_p_.... Guarde o Bearer no gerenciador de segredos do cliente; não o coloque em arquivo versionado, mensagem, issue ou workspace.
3. Autorize o principal no workspace
Edite workspaces.json e substitua o placeholder de allowedPrincipals pelo prin_... exibido:
{
"workspaces": [
{
"id": "demo",
"name": "Workspace de demonstração",
"rootPath": "./fixtures/demo-workspace",
"allowedPrincipals": ["prin_00000000-0000-0000-0000-000000000000"]
}
]
}allowedPrincipals é uma lista exata e fail-closed: sem o ID, nenhuma operação de workspace/lock/checkpoint é autorizada. Um convite de sala não substitui essa lista. workspaces.json contém roots reais e é ignorado pelo Git.
4. Inicie o servidor
npm.cmd run devO endpoint MCP fica em http://127.0.0.1:3100/mcp e o health em http://127.0.0.1:3100/health. Configure no cliente MCP:
Authorization: Bearer collab_p_...Para executar o build compilado:
npm.cmd run build
npm.cmd start5. Valide a conexão
Com o servidor ativo:
$env:COLLAB_MCP_URL = "http://127.0.0.1:3100/mcp"
$env:COLLAB_MCP_BEARER = "collab_p_..."
npm.cmd run check:mcpO script faz handshake, lista as 37 tools e chama collab_status. Ele não cria sala, não executa shell e não imprime o token.
6. Abra a sala
O primeiro agente cria a sala com um workspaceId retornado por collab_list_workspaces (só o Bearer já basta) ou pelo operador. Os demais entram com um inviteToken entregue por canal privado.
Clientes MCP
Os adapters são templates e documentação, não conexões validadas. Nenhum cliente real ou Tailscale foi executado neste repositório.
Cliente | Template | Observação |
OpenCode V2 |
| |
Codex / ChatGPT desktop |
| |
Claude Code |
| |
Cliente MCP genérico | Requisitos de Streamable HTTP | |
Tailscale Serve | Runbook privado; não configurado/validado |
O protocolo operacional compartilhado e o inventário de tools estão em adapters/shared/AGENT_PROTOCOL.md e adapters/shared/TOOL_REFERENCE.md.
Segurança
O workspace é único e real no host; os agentes leem e alteram exatamente os mesmos arquivos.
/mcpexige Bearer;/healthé público e não contém tokens, roots ou caminho do SQLite.Tokens de transporte e de sessão são persistidos somente como SHA-256; o Bearer é exibido uma vez pelo CLI.
allowedPrincipalsé configuração do servidor, lista exata sem wildcard, revalidada em cada operação sensível.rootPathé configurado somente emworkspaces.json; nenhuma tool aceita caminho do host, root ou lista de principals.O binding padrão é loopback. Host, proxy, CORS e rate limiting têm defaults conservadores.
O modo é cooperativo: ferramentas nativas de edição/shell podem ignorar locks, hashes, checkpoints e autorização. O MCP só protege o que passa por ele.
Não há acesso remoto pronto. Tailscale, ACL, autenticação OAuth, bridge stdio e modo estrito não foram validados.
Leia SECURITY.md para o modelo de ameaças, escopo de reporte e limitações.
CLI
Comando | Uso |
| Cria um principal; imprime o Bearer uma única vez |
| Lista IDs, nomes e status, sem token/hash |
| Revoga uma credencial; o transporte passa a retornar 401 |
| Handshake + 37 tools + |
Ferramentas MCP
São 37 tools, agrupadas em:
Categoria | Qtd. | Exemplos |
Diagnóstico | 1 |
|
Colaboração | 20 |
|
Workspace | 8 |
|
Locking | 5 |
|
Checkpoint | 3 |
|
O inventário completo, campos e respostas está em adapters/shared/TOOL_REFERENCE.md.
Testes e qualidade
Comando | O que faz |
| TypeScript estrito |
| Suíte completa: 200 testes / 24 arquivos |
| Compila |
| Aplicação integrada, 2 clientes MCP, 37 tools, lock/patch |
| Smoke isolado da fundação |
| Verificação de conexão com Bearer |
A suíte cobre autenticação 401/403/429, vínculo principal↔sessão, revogação, autorização por workspace, descoberta de workspace, isolamento de salas, locks, hash antigo, negociação, handoff, checkpoint, expiração e reinício com o mesmo SQLite. 200 testes passam em Windows/Node 24 localmente; CI executa Node 24 em windows-latest.
Segurança de dependências: npm audit --omit=dev = 0 vulnerabilidades de produção; no momento da publicação há 3 advisories dev na cadeia Vitest/Vite, documentados no CHANGELOG.
Estrutura do projeto
src/
├── index.ts # entrypoint
├── application.ts # composição integrada
├── config/ # ambiente, logger e workspaces
├── contracts/ # IDs, erros, papéis e principal
├── persistence/ # SQLite e migrations (v1…v30)
├── collaboration/ # salas, mensagens, tarefas, handoffs
├── workspace/ # arquivos, versões, patches, checkpoints
├── locking/ # locks exclusivos
├── server/ # MCP HTTP, auth de transporte, health
└── cli/auth.ts # credenciais
adapters/ # templates e protocolo compartilhado
fixtures/demo-workspace/ # workspace descartável
tests/ # fundação, auth, integração e módulosDocumentação profunda de arquitetura, decisões e histórico: AGENTS.md e CLAUDE.md. São documentos internos de engenharia; o README é o ponto de entrada público.
Limitações e roadmap
Limitações atuais, sem promessas de pronto:
não há delete, rename/move ou criação de diretórios; o pai de um arquivo novo precisa existir;
não há edição concorrente do mesmo arquivo, CRDT ou merge automático;
o modo cooperativo não impede escritas nativas ou shell;
não há bridge stdio, OAuth, modo estrito, UI/dashboard ou operações Git;
autorização é por workspace, não por sala/role; ainda não há administração remota de
allowedPrincipals;clientes reais OpenCode/Codex/Claude Code e Tailscale não foram validados;
rate limiting é em memória, por processo, e cobre tentativas Bearer inválidas;
advisories dev do Vitest/Vite permanecem; o runtime de produção está limpo.
Próximos passos honestos: validar um cliente real em loopback, revisar Tailscale Serve/ACL em ambiente controlado, executar o piloto OpenCode + Codex, adicionar autorização por sala/administração de acesso e, depois, bridge stdio/modo estrito.
Contribuição
Leia CONTRIBUTING.md, siga o Código de Conduta e reporte vulnerabilidades conforme SECURITY.md. Mudanças devem preservar o modo cooperativo documentado, os limites de entrada e a autorização por workspace.
Licença
MIT © 2026 Vinicius Adami Cabral. Veja LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Multiplayer for the coding agents your team already uses: shared tasks, decisions, skills and tools.
Coding agents in one repo see each other, get warned before shared edits, and message.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables multiple AI agents like Claude and Codex to coordinate on the same project through shared tasks, file locks, and a real-time dashboard, preventing conflicts and streamlining collaborative development.5 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables multiple AI coding agents to collaborate on a project by coordinating tasks, file leases, and messages through a shared hub, preventing conflicts and enabling parallel development.MIT
- AlicenseNot gradedqualityCmaintenanceEnables multiple AI coding agents to collaborate on the same Git repository without conflicts through isolated worktrees, file locking, automated test verification, and a serialized merge queue.8MIT
- AlicenseBqualityBmaintenanceEnables multiple coding agents sharing one repository to coordinate their work through time-limited directory and file leases, an enforced pre-tool-use hook, shared presence tracking, messaging, and an audit history, so they never edit or run each other's files concurrently.1558 PyPIMIT