Co-Work

Sincronização Git segura e observável para projetos locais.

Instalação rápida

Quando publicado no npm:

npx cowork-sync-cli doctor .

O pacote instala somente o CLI e inicia o agente nativo correspondente à sua plataforma. A versão atual publicada para este workspace é Windows x64; outras plataformas são recusadas explicitamente até terem um agente nativo próprio. Não há shell remoto nem script de pós-instalação oculto.

Para publicar uma release, use uma conta npm autenticada:

npm login
npm run release:check
npm publish

O hook prepublishOnly executa a suíte completa e confirma que o executável empacotado é byte a byte igual ao binário compilado.

Suporte atual:

Windows x64      suportado
Linux x64        planejado
macOS x64/arm64  planejado

Compilar com MSYS2 UCRT64

gcc -std=c11 -Wall -Wextra -O2 cowork.c peer.c protocol.c \
  -Wl,-Bstatic -lsodium -Wl,-Bdynamic -lws2_32 -lcrypt32 \
  -o cowork.exe

Uso direto do agente C

O projeto precisa ter um remote Git configurado, preferencialmente via SSH:

git -C C:/projeto remote -v

Em um computador, observe alterações e envie checkpoints:

./cowork.exe watch C:/projeto origin

No outro, busque e aplique somente avanços lineares:

./cowork.exe sync C:/projeto origin

Para acompanhar automaticamente o remote no outro computador:

./cowork.exe follow C:/projeto origin

Uso pelo CLI

npx cowork-sync-cli doctor C:/projeto
npx cowork-sync-cli watch C:/projeto origin
npx cowork-sync-cli follow C:/projeto origin
npx cowork-sync-cli discover 10

MCP para agentes de IA

O Co-Work inclui um servidor Model Context Protocol por stdio. Ele expõe contexto Git e sincronização controlada para agentes como Codex, Claude Desktop e hosts compatíveis. Leituras são separadas de operações de escrita; git_sync e git_commit devem ser aprovados pelo host do agente.

Para testar localmente:

node mcp-server.js

Configuração típica de um cliente MCP:

{
  "mcpServers": {
    "cowork": {
      "command": "npx",
      "args": ["--yes", "cowork-sync-cli@latest", "mcp"],
      "env": { "COWORK_PROJECT": "C:\\projeto" }
    }
  }
}

O servidor aceita apenas o projeto definido em COWORK_PROJECT (ou no diretório de trabalho do processo quando essa variável não existe). Para um ambiente com vários projetos, informe caminhos adicionais em COWORK_ALLOW_REPOS, separados pelo delimitador da plataforma. Leituras de .git, .cowork, .env e arquivos de credenciais são recusadas.

Ferramentas disponíveis: project_status, git_diff, git_log, git_read_file, cowork_conflicts, git_sync e git_commit. Também há os recursos cowork://project/status, cowork://project/diff e o prompt review_sync. O servidor nunca oferece shell arbitrário, leitura fora do repositório ou git add automático. Cada resultado de ferramenta bem-sucedido tem structuredContent e um envelope JSON versionado (contract, ok, data, meta); o texto JSON continua presente para clientes MCP legados.

Setup visual das CLIs

Para instalar o Co-Work MCP com uma experiência guiada, execute no projeto:

npx cowork-sync-cli@latest setup

O TUI permite selecionar somente Cursor, Codex, Claude Code e OpenCode. Ele usa uma interface compacta com teclado e mouse, diferencia CLI disponível de configuração MCP existente, mostra progresso, preserva backups com o sufixo .cowork-backup-* e não confunde o diretório de onde o comando foi executado com um projeto Git. Para fixar o workspace explicitamente:

npx cowork-sync-cli@latest setup --project=C:/projeto

Para automação ou integração com outro agente, use JSON sem abrir o TUI:

npx cowork-sync-cli@latest setup --json
npx cowork-sync-cli@latest setup --project=C:/projeto --install=cursor,codex --json

O setup não instala agentes, não solicita credenciais e não sobrescreve silenciosamente configurações sem manter uma cópia anterior.

Ou use um único processo:

npx cowork-sync-cli start C:/projeto origin

Para inspecionar estados P2P recebidos sem aplicar nada:

npx cowork-sync-cli conflicts C:/projeto

O formato de transporte está documentado em PROTOCOL.md, incluindo framing, ordem de bytes e invariantes de segurança para futuras implementações Linux/macOS.

Identidade e sessão P2P

O agente já possui um handshake autenticado para a próxima camada de transporte:

./cowork.exe keygen C:/projeto
./cowork.exe fingerprint C:/projeto
./cowork.exe trust C:/projeto FINGERPRINT_DO_OUTRO_PC
./cowork.exe share C:/projeto 47600
./cowork.exe join C:/projeto 192.168.1.20 47600

O agente direto também aceita cowork.exe --version e cowork.exe --help.

Execute keygen e trust uma vez em cada PC. O fingerprint salvo fica em .cowork/trusted.peers; depois disso share e join usam essa confiança sem exigir a chave na linha de comando. Também é possível informar o fingerprint explicitamente quando necessário.

Para revogar um peer salvo, use cowork untrust C:/projeto FINGERPRINT.

discover procura sessões share na LAN. O anúncio contém apenas nome do projeto, porta e fingerprint público; o fingerprint ainda precisa ser confirmado no comando join.

Para redes sem conexão direta, um terceiro computador pode executar o relay cego:

npx cowork-sync-cli relay 47620
npx cowork-sync-cli share-via C:/projeto relay.example 47620 sala-azul
npx cowork-sync-cli join-via C:/projeto relay.example 47620 sala-azul

O relay só encaminha bytes. A autenticação e a criptografia continuam acontecendo entre os dois projetos; o relay não recebe as chaves nem o conteúdo Git.

Se o relay cair, share-via e join-via reconectam ao mesmo host e sala, refazem o pareamento criptográfico e retomam a partir do HEAD trocado no novo handshake.

Se a conexão direta cair depois do pareamento, join tenta reconectar automaticamente e share continua aceitando novas conexões autenticadas na mesma porta. Uma falha de fingerprint, projeto ou branch não é mascarada por tentativas; ela encerra a sessão e exige correção explícita.

No início de cada sessão os peers trocam também o HEAD atual. Isso permite retomar uma sessão depois que ambos os processos foram fechados e transferir só o intervalo Git que falta; quando os commits são iguais, nenhum bundle é enviado.

As identidades usam Ed25519 para assinatura, X25519 para derivação de chave e uma chave privada protegida pelo DPAPI do Windows. O handshake rejeita qualquer fingerprint diferente do informado. share envia o bundle inicial e acompanha novos checkpoints; join permanece conectado. Os dois lados também enviam suas alterações. O primeiro bundle contém a base completa; checkpoints seguintes usam somente o intervalo Git desde a última base comum quando possível. Cada avanço recebido é aplicado somente com fast-forward. listen e connect continuam disponíveis para testar apenas o handshake.

Antes da sincronização, os peers também trocam uma identidade derivada das raízes do histórico Git e da branch atual. Projetos diferentes ou branches diferentes são recusados antes de qualquer arquivo ser aplicado.

Se os dois lados criarem commits divergentes, a sincronização pausa com segurança: o bundle recebido continua preservado em refs/remotes/cowork/peer/<branch> e nenhum arquivo é sobrescrito. O terminal informa o comando Git para revisar e resolver o merge manualmente.

O programa nunca executa comandos recebidos do outro computador. Ele chama o Git diretamente, sem shell, cria commits automáticos e recusa merges que exigiriam sobrescrever ou resolver conflitos automaticamente.

Antes de usar:

git -C C:/projeto config user.name "Seu Nome"
git -C C:/projeto config user.email "[email protected]"
git -C C:/projeto add -A
git -C C:/projeto commit -m "estado inicial"