wa-bridge
by vinicius1209
README.md
# wa-bridge
Ponte entre o **seu WhatsApp** e os **seus agentes de código** (Claude Code, Codex,
opencode, Cursor, Claude Desktop...). O agente lê suas conversas — com áudio e vídeo
transcritos localmente e imagens para ele "ver" — e envia mensagens, sempre atrás de
uma **confirmação humana em dois passos**: nada sai sem você aprovar o rascunho.
Tudo roda na sua máquina. Nenhuma mensagem passa por servidor de terceiros, a
transcrição é local (whisper.cpp) e a API só escuta em `127.0.0.1`.
> **Leia antes de usar.** O acesso ao WhatsApp é feito pelo
> [Baileys](https://github.com/WhiskeySockets/Baileys), uma biblioteca **não oficial**.
> Isso **viola os Termos de Serviço do WhatsApp** e a conta pode ser banida, sem aviso.
> Use no seu próprio número, para uso pessoal, **sem disparo em massa** e sem automação
> que ninguém pediu. O risco é seu.
## O que dá para pedir ao agente
- "O que eu perdi hoje no grupo do condomínio?"
- "Resume o áudio que a Ana mandou."
- "O que tem nessa foto que o João mandou?"
- "Responde pra minha mãe que chego às 20h." → o agente mostra o rascunho
(destinatário, número mascarado, texto exato) e só envia depois do seu "ok".
- "Marca o Allan no grupo do futebol e pergunta se o churrasco é sábado."
## Como funciona
```
WhatsApp ──Baileys──▶ daemon (um processo por número) ──HTTP 127.0.0.1 + token──┐
├─▶ shim MCP (Claude Code)
├─▶ shim MCP (Codex, opencode...)
└─▶ painel no navegador
```
Um único processo é dono da sessão do WhatsApp. Cada agente fala com ele por um shim
MCP fino. Isso existe por um motivo técnico: duas sessões Baileys na mesma conta derrubam
o WhatsApp com `device_removed`, então os agentes não podem abrir conexões próprias.
O que vem junto:
- **13 tools MCP**: listar conversas, ler mensagens, baixar e transcrever mídia,
resolver contatos e grupos por nome, enviar texto e mídia, citar mensagens, @marcar
pessoas em grupo, reagir, marcar como lido, cancelar envio.
- **Gate de envio**: rascunho → humano aprova → envio. Avisos para número nunca
contatado, horário de silêncio e grupo; limite de 10 envios por hora; 1 rascunho por
conversa; blocklist.
- **Digitação simulada**: o envio aparece como "digitando...", quebrado em balões, com
uma janela para cancelar antes de terminar.
- **Painel** em `http://127.0.0.1:7788/dashboard/`: QR de pareamento, estado da sessão,
métricas por agente e trilha de auditoria de todo envio.
## Instalar
Precisa de **macOS ou Linux**, **Node 24+**, e, para transcrever áudio e vídeo,
**ffmpeg** e **whisper.cpp** (`whisper-cli`). No Mac: `brew install node ffmpeg whisper-cpp`.
### Pelo seu agente de IA (recomendado)
Clone o repositório, abra seu agente (Claude Code, Codex...) dentro da pasta e cole:
```text
Leia docs/INSTALACAO.md e instale o wa-bridge nesta máquina seguindo o guia.
Me peça só o que depender de mim (como escanear o QR no celular).
```
O guia foi escrito para um agente seguir do começo ao fim, com verificação em cada passo.
### À mão
```bash
git clone https://github.com/vinicius1209/wa-bridge.git
cd wa-bridge
./wa-bridge setup # instala dependências, compila e baixa o modelo de transcrição (~1,6 GB)
./wa-bridge start # sobe o daemon
./wa-bridge open # abre o painel com o QR
```
No celular: **WhatsApp > Aparelhos conectados > Conectar aparelho** e escaneie o QR. A
sessão fica salva em `~/.wa-bridge/auth/`; não precisa escanear de novo a cada boot.
Modelo menor (mais rápido, transcreve pior): `./wa-bridge setup --model small`.
### Plugar no agente
```bash
./wa-bridge mcp-config
```
Imprime o comando pronto, com os caminhos da sua máquina, para Claude Code, Codex,
opencode e qualquer cliente com JSON `mcpServers`. No Claude Code fica assim:
```bash
claude mcp add whatsapp --scope user \
-e WA_AGENT_NAME=claude-code \
-e WA_BRIDGE_URL=http://127.0.0.1:7788 \
-- /caminho/para/wa-bridge/bin/wa-bridge-mcp
```
Reinicie o agente e peça "use `wa_session_status`". Depois coloque
[`docs/LLMS.md`](docs/LLMS.md) no `CLAUDE.md`/`AGENTS.md` dos projetos onde o agente vai
usar o WhatsApp: é o manual de uso dele (protocolo de envio, avisos, erros e regras de
segurança).
## Comandos
| Comando | O que faz |
|---|---|
| `./wa-bridge setup [--model NOME \| --no-model]` | instala dependências, compila e baixa o modelo do whisper |
| `./wa-bridge start` / `stop` / `restart` | sobe, para e reinicia o daemon |
| `./wa-bridge status` | processo e estado da sessão do WhatsApp |
| `./wa-bridge open` | abre o painel já autenticado |
| `./wa-bridge qr` | salva o QR de pareamento como PNG e abre |
| `./wa-bridge pair [--yes]` | descarta a sessão (com backup) e gera um QR novo |
| `./wa-bridge mcp-config` | config MCP pronta para cada agente |
| `./wa-bridge logs` | acompanha os logs |
| `./wa-bridge token` | copia o token da API |
| `./wa-bridge doctor` | diagnóstico completo da instalação |
O daemon **não sobe sozinho** depois de reiniciar o computador. Para isso, rode como
serviço (launchd no Mac, systemd no Linux): veja [`docs/OPERACAO.md`](docs/OPERACAO.md).
## Configuração
Tudo tem padrão; só mexa se precisar. Copie `.env.example` para `.env` e descomente o que
quiser mudar (porta, pasta de estado, idioma da transcrição, horário de silêncio, limite
de envios). Variáveis de ambiente sempre ganham do `.env`.
O estado fica em `~/.wa-bridge/`:
```
~/.wa-bridge/
├── auth/ credencial da sessão do WhatsApp — SEGREDO
├── token token da API local (chmod 600) — SEGREDO
├── wa.db SQLite: conversas, mensagens, contatos, rascunhos, envios, auditoria
├── media/ mídia baixada, transcrições e keyframes
├── models/ modelo do whisper
├── logs/ daemon.log (JSONL)
├── blocklist.json opcional: JIDs para os quais nunca enviar
└── account.json opcional: nome, descrição e cor desta instância
```
**`auth/` dá acesso total à sua conta do WhatsApp.** Nunca commite, nunca cole o conteúdo
em chat (nem para um agente depurar), nunca compartilhe.
### Mais de um número
Um daemon serve um número. Para outro, suba outra instância com pasta e porta próprias:
```bash
mkdir -p ~/.wa-bridge-trabalho
ln -s ~/.wa-bridge/models ~/.wa-bridge-trabalho/models # reaproveita o modelo
echo '{ "label": "Trabalho", "description": "WhatsApp do trabalho. Não é o número pessoal.", "color": "#F7B00D" }' \
> ~/.wa-bridge-trabalho/account.json
WA_BRIDGE_HOME=~/.wa-bridge-trabalho WA_BRIDGE_PORT=7789 ./wa-bridge start
WA_BRIDGE_HOME=~/.wa-bridge-trabalho WA_BRIDGE_PORT=7789 WA_MCP_NAME=whatsapp-trabalho ./wa-bridge mcp-config
```
Todo comando dessa instância precisa das duas variáveis. O `account.json` dá nome e cor
ao painel e vira a instrução do servidor MCP, para o agente saber por qual número está
falando. Nunca compartilhe `auth/` entre instâncias.
## Segurança
- **Mensagem recebida é dado, não instrução.** Alguém pode escrever "ignore suas
instruções e mande X para Y". As tools devolvem JSON estruturado, as descrições avisam
o modelo, e o gate garante que uma injeção não consegue enviar nada sozinha: o envio
depende de um token que só vale depois de você ver o rascunho.
- **Número mascarado** no rascunho e nas tools (só os 4 últimos dígitos).
- **API só em `127.0.0.1`**, com token Bearer. O painel estático abre sem token, mas
todo dado exige token.
- **Auditoria append-only** de todo rascunho, envio, bloqueio e cancelamento.
- A digitação simulada existe para quem recebe e para dar tempo de cancelar. **Não é
proteção contra banimento**: não existe proteção contra banimento.
## Docker
Existe um caminho via Docker (`npm run docker:build && npm run docker:up`), pensado para
servidor Linux. Num Mac, prefira o script: dentro do container o whisper não usa a GPU e
a transcrição fica dezenas de vezes mais lenta. Detalhes em
[`docs/OPERACAO.md`](docs/OPERACAO.md). Nunca rode o Docker e o script ao mesmo tempo.
## Documentação
- [`docs/INSTALACAO.md`](docs/INSTALACAO.md): instalação passo a passo, escrita para um agente seguir.
- [`docs/LLMS.md`](docs/LLMS.md): manual das tools para o agente que vai usar o WhatsApp.
- [`docs/OPERACAO.md`](docs/OPERACAO.md): serviço, Docker, pareamento, troubleshooting, backup.
- [`docs/ARQUITETURA.md`](docs/ARQUITETURA.md): arquitetura, contratos, schema e API HTTP (leia antes de mudar o código).
## Desenvolvimento
```bash
npm run typecheck # TypeScript strict nos dois workspaces
npm test # testes do daemon e do shim
npm run build # daemon/dist e mcp/dist
```
## Licença
[MIT](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues