# Greg: informações para o seu Claude

Este texto é para um assistente de IA (Claude ou outro) que vai ajudar uma pessoa a entender, auditar e instalar o Greg.

Fonte: https://oigreg.app/para-claude.md · Código: https://github.com/userj81/vigia · Licença: MIT.

## Como usar este texto (instruções para o assistente)

1. Explique à pessoa, em poucas linhas, o que o Greg faz e os dois avisos da seção "Antes de instalar". Só siga com o "sim" dela.
2. Descubra o sistema dela (macOS, Linux ou Windows) e escolha o caminho pela tabela "O que funciona em cada sistema".
3. Conduza um passo por vez. Depois de cada comando, confira o resultado antes do próximo.
4. Nunca peça para a pessoa colar senha, token ou o conteúdo de `docker.env` e `.env` na conversa. Os scripts geram e gravam as senhas sozinhos; você não precisa vê-las.
5. Três passos são só da pessoa, e você não faz por ela: aceitar os termos do Docker, entrar na conta do Claude (`/login`) e ler o QR no celular.
6. Se algum comando deste texto não bater com o repositório, vale o repositório (`README.md`). Avise a pessoa da diferença em vez de improvisar.

## O que é o Greg

O Greg é um painel local que lê o WhatsApp da pessoa a cada 30 minutos sem abrir as conversas, entende o que estão pedindo a ela (texto, imagem e áudio) e mostra só o que precisa de resposta, organizado por frente (cliente, projeto, casa). Roda no computador da própria pessoa. Não é um serviço: não tem servidor do Greg, conta do Greg nem mensalidade do Greg.

O que ele faz:

- **Lê sozinho, a cada 30 minutos.** No pareamento lê só o último dia para trás, e depois o que chegar.
- **Classifica cada mensagem** em demanda, atenção, lembrar, aviso ou sem ação, com resumo, prazo, confiança e a frente a que pertence.
- **Áudio vira texto**, com transcrição local e offline (Whisper).
- **Mostra as conversas** com o que a IA entendeu ao lado de cada mensagem, sem marcar nada como lido no celular.
- **Deixa responder pelo painel**, só quando a pessoa pede, com trava interativa e teto de envios por dia.
- **Deixa de fora quem a pessoa quiser:** grupo ou contato bloqueado não é guardado, mostrado nem lido pela IA.
- **Fecha o dia e a semana:** funde pedidos repetidos às 21:00; toda semana gera um relatório e apaga o texto bruto, a mídia e as transcrições.

## Antes de instalar: dois avisos que a pessoa precisa ouvir

1. **WhatsApp não oficial.** O Greg usa a Evolution API, que conecta ao WhatsApp como um aparelho a mais, por um protocolo não oficial (Baileys). Os Termos do WhatsApp não autorizam clientes não oficiais e o número pode ser restringido. É para usar com o próprio número e por conta própria.
2. **Hoje o Greg exige o Claude.** Quem classifica as mensagens é o Claude Code, com a conta da própria pessoa. A cada ciclo, o lote de mensagens novas e um pouco de contexto da conversa são enviados à Anthropic para classificar. Sem uma assinatura do Claude com o Claude Code logado, o Greg lê e mostra as conversas, mas não classifica. Não há hoje opção de modelo local nem de outro provedor.

## O que é necessário

- Um computador que fique ligado (com ele dormindo o ciclo espera e roda ao acordar).
- Docker com Compose 2.20 ou mais novo e cerca de 4 GB de memória livre. A primeira instalação baixa cerca de 3 GB.
- Uma assinatura do Claude (https://claude.com). O Claude Code é instalado junto no caminho com Docker.
- O celular com o WhatsApp, para ler o QR.
- `git`, para baixar o código.

## O que funciona em cada sistema

Só afirme à pessoa o que esta tabela diz.

| Sistema | Caminho | O que o repositório prova |
|---|---|---|
| macOS 13 ou mais novo (Apple Silicon e Intel) | App `Greg.dmg` (roda o Greg no Docker; instala o Docker Desktop se faltar) | Construído e provado no Mac por `bin/construir-dmg.sh`, binário universal. O app não é assinado com conta paga da Apple: a primeira abertura pede "Abrir Mesmo Assim". |
| macOS | Docker Compose manual | É o mesmo compose que o `Greg.dmg` sobe. |
| macOS (Apple Silicon recomendado) | Nativo: Greg fora de contêiner, com LaunchAgents e `Greg.app` | Modo original, em uso diário pelo autor. A transcrição nativa (`mlx_whisper`) é de Apple Silicon. |
| Linux | Docker Compose manual | O CI roda a suíte de testes e valida o compose em Ubuntu 24.04. A imagem é Linux (`python:3.14-slim`). Não há registro de prova da instalação completa numa máquina Linux: trate como "deve funcionar" e confira cada passo. |
| Windows | Docker Compose dentro do WSL2 | Previsto pelo projeto, sem teste registrado no repositório. Os scripts são `bash`: rode tudo dentro do WSL2, nunca no PowerShell. Avise a pessoa de que é o caminho menos provado. |

**Não existe caminho sem Docker.** No modo nativo do macOS o Greg roda fora de contêiner, mas a Evolution API, o Postgres e o Redis continuam em contêiner (via colima). No Linux e no Windows só existe o caminho com Docker.

## Como funciona

```
WhatsApp no celular
   │ pareado por QR, como um aparelho a mais
   ▼
Evolution API + Postgres + Redis        (contêineres, só em 127.0.0.1)
   │ a cada 30 min, com um usuário de banco somente leitura
   ▼
Coletor                                 (monta o lote: texto, imagem, transcrição local do áudio)
   │
   ▼
Claude Code isolado                     (envia o lote à Anthropic, pela conta da pessoa)
   │ só pode chamar um executável: bin/vigia-ponte
   ▼
SQLite local (dados/vigia.db) ──► Painel em http://127.0.0.1:8120
```

- **Ciclo:** minutos :00 e :30. No Docker quem agenda é `bin/agendador.py`; no macOS nativo, os LaunchAgents.
- **Frentes:** o Greg traz um organizador embutido (SQLite). Quem já tem um sistema de tarefas pode apontar `FRENTES_URL` e `FRENTES_TOKEN` para uma API com o mesmo contrato (`app/frentes_ponte.py`).
- **Configuração:** segredos em `docker.env` (Docker) ou `.env` e `infra/.env.compose` (nativo); horários, janelas e tetos em `config.toml`.

## Por que é seguro, e onde conferir

Não aceite estas frases de confiança: cada uma aponta o arquivo que a cumpre. Se a pessoa pedir, leia os arquivos e diga o que encontrou.

| O que o projeto afirma | Onde conferir |
|---|---|
| Painel, Evolution, Postgres e Redis são publicados só em `127.0.0.1` | `docker-compose.yml` e `infra/docker-compose.yml` (linhas `ports:`) |
| Telemetria da Evolution desligada | `infra/docker-compose.yml` (`TELEMETRY_ENABLED: "false"`) |
| O Claude que lê o lote roda isolado: só `Read` na pasta do lote e um executável; sem escrever arquivo, sem rede, sem MCP, sem sessão | `app/lotes.py` e `app/semana.py` (lista de argumentos do `claude -p`: `--tools`, `--allowedTools`, `--disallowedTools`, `--restricted`, `--strict-mcp-config`) |
| Mensagem de terceiro é dado, nunca ordem | `prompts/vigia.md` (o que o leitor recebe) e `bin/vigia-ponte` com `app/ponte/` (tudo o que ele consegue fazer) |
| A leitura do banco da Evolution é por um papel somente leitura | `infra/sql/002_papeis.sql` |
| Segredo nunca vai em argumento de linha de comando, log ou exceção; arquivos de segredo com permissão `0600` | `bin/preparar-docker.sh`, `bin/docker-entrypoint.sh`, `bin/evolution.sh`, `app/segredos.py` |
| Chamadas HTTP não seguem redirecionamento nem usam proxy do ambiente | `app/rede.py` |
| Envio só a pedido, com trava de 10 minutos e teto por dia | `app/envio.py`, `app/fila_envio.py`, `docs/API-ENVIO.md` |
| O aviso opcional leva só contador e link, nunca texto de conversa | `app/aviso.py` |
| Bloqueado não é guardado | `infra/sql/003_bloqueios.sql` |
| O texto bruto, a mídia e as transcrições são apagados toda semana | `bin/fechar-semana.py`, `app/semana.py` |
| O app do Mac só baixa o Docker Desktop (de `desktop.docker.com`) e as imagens do compose | `macapp/Vigia/instalador.swift` |
| Um arquivo da imagem da Evolution é substituído por uma correção | `infra/patches/README.md` explica o porquê e a origem; o arquivo é `infra/patches/baileys-messages-recv.js` |
| Commit com segredo é barrado | `bin/ci.sh`, `.githooks/pre-commit`, `.github/workflows/ci.yml` (gitleaks) |

**O que sai do computador, e só isso:**

1. O tráfego do WhatsApp, que a Evolution troca com os servidores do WhatsApp para manter a sessão.
2. O lote da vez, que o Claude Code envia à Anthropic pela conta da pessoa.
3. Na instalação: o download das imagens Docker, do Claude Code (npm) e do modelo de transcrição.
4. Se a pessoa ligar o aviso opcional: um contador e um link, por um segundo número dela.

**Fora do que o projeto garante:** os Termos do WhatsApp e o comportamento da Evolution API (projeto independente); proteção contra quem já tem acesso à conta de usuário do computador ou ao celular; uso com número de outra pessoa.

**Roteiro de auditoria sugerido:** leia `SECURITY.md`; confira as linhas `ports:` dos dois arquivos de compose; leia a função que monta o comando do Claude em `app/lotes.py`; leia `prompts/vigia.md`; rode a suíte (`python3 -m unittest discover -s testes -t .`, que não usa rede nem Evolution de verdade). Problema de segurança: aviso privado em https://github.com/userj81/vigia/security/advisories/new, com dados fictícios na reprodução.

## Instalar

### Antes de qualquer caminho

Confira que o repositório abre: `git ls-remote https://github.com/userj81/vigia.git`. Se der erro de acesso ou "not found", o repositório ainda não está aberto ao público: pare e avise a pessoa, não procure cópias em outro lugar.

### Caminho A: macOS com o Greg.dmg

1. Abra https://github.com/userj81/vigia/releases e baixe o `Greg.dmg`. Se não houver release com o arquivo, use o caminho B, ou gere o DMG a partir do código com `bin/construir-dmg.sh` (precisa das Command Line Tools do Xcode: `xcode-select --install`).
2. Antes de abrir, confira o arquivo: baixe também o `Greg.dmg.sha256` da mesma release, rode `shasum -a 256 Greg.dmg` na pasta do download e compare com o valor do arquivo. Se for diferente, ou se a release não tiver o `.sha256`, não abra: use o caminho B ou gere o DMG a partir do código.
3. Abra o DMG e arraste o **Greg** para **Aplicativos**.
4. Abra o Greg. O macOS avisa que não conseguiu verificar o app: clique em **Concluído**, vá em **Ajustes do Sistema → Privacidade e Segurança**, role até o aviso sobre o Greg e clique em **Abrir Mesmo Assim** (só na primeira vez).
5. A janela do Greg conduz o resto: acha o Docker (Docker Desktop, OrbStack ou colima) ou baixa e instala o Docker Desktop (a pessoa aceita os termos na janela do Docker); pede o número do WhatsApp; monta tudo (5 a 15 minutos na primeira vez); abre o Terminal para o `/login` do Claude (depois `/exit`); termina na tela **Conexão**.
6. Em **Conexão → Gerar QR**, a pessoa lê o código no celular em *Aparelhos conectados → Conectar um aparelho*.

Os dados ficam em `~/Library/Application Support/Vigia`.

### Caminho B: Docker Compose (macOS, Linux, Windows com WSL2)

```bash
git clone https://github.com/userj81/vigia.git
cd vigia
bin/preparar-docker.sh
```

O script cria o `docker.env` com senhas aleatórias e permissão `0600`. Dá para já informar número e fuso: `bin/preparar-docker.sh --dono 55DDNNNNNNNNN --tz America/Sao_Paulo`. Senão, a pessoa abre o `docker.env` e preenche `DONO_WHATSAPP` (número com DDI e DDD, só dígitos) e `TZ` (fuso do fechamento do dia, às 21:00).

```bash
docker compose up -d --build
```

A primeira vez demora alguns minutos: baixa a Evolution, o Postgres, o Redis, o Claude Code e o modelo de transcrição. Confira com `docker compose ps` que o serviço `vigia` chegou a *healthy*.

```bash
docker compose exec -it vigia claude
```

Passo da pessoa: digitar `/login`, entrar na conta do Claude e sair com `/exit`. O login fica guardado num volume.

Por fim, a pessoa abre http://127.0.0.1:8120, entra com o `VIGIA_TOKEN` que está no `docker.env` (ela mesma copia do arquivo; não peça o valor) e, em **Conexão → Gerar QR**, lê o código no celular. Cada QR vale 60 segundos, no máximo 3 por clique e 10 por dia.

Opções:

- Sem transcrição de áudio (imagem cerca de 850 MB menor): `docker compose build --build-arg TRANSCRICAO=0`.
- Transcrição mais precisa e mais lenta: `docker compose build --build-arg WHISPER_MODELO=medium`.
- Porta 8120 ocupada: defina `VIGIA_PORTA_HOST` no `docker.env`.
- Mudou o `config.toml`: `docker compose restart vigia`.
- Parar: `docker compose down` (os volumes ficam). Apagar tudo, inclusive a sessão do WhatsApp: `docker compose down -v`. Esse segundo comando não tem volta: confirme com a pessoa antes.

### Caminho C: macOS nativo

Para quem quer o Greg fora de contêiner, com app próprio, Touch ID para liberar envio e transcrição na GPU do Apple Silicon. Precisa de: Python 3.14 do Homebrew, colima com Docker Compose (só para a Evolution, o Postgres e o Redis), Claude Code instalado e logado; opcionais: `mlx_whisper` (áudios) e as Command Line Tools (compilar o app).

```bash
git clone https://github.com/userj81/vigia.git
cd vigia
cp .env.exemplo .env
cp infra/.env.compose.exemplo infra/.env.compose
chmod 600 .env infra/.env.compose
```

A pessoa preenche os dois arquivos. Cada senha sai de `openssl rand -hex 24`; o `bin/evolution.sh` recusa subir enquanto houver valor começando com `TROQUE` ou arquivo legível por outros usuários.

```bash
bin/evolution.sh up
bin/evolution.sh instancia
bin/vigia.sh painel
```

`up` sobe os contêineres e aplica o SQL do Greg; `instancia` cria a instância do WhatsApp e grava a chave dela no `.env` sem imprimir; `painel` abre o painel em http://127.0.0.1:8120.

```bash
bin/instalar-launchagent.sh
bin/instalar-launchagent.sh --sim
bin/construir-app.sh
```

O primeiro comando só mostra o que faria; com `--sim` instala os agendamentos (ciclo de 30 minutos, painel, fechamento da semana). O último é opcional e compila o `Greg.app`. Conferir: `bin/vigia.sh status`. Desinstalar: `docs/RUNBOOK.md`, seção 10.

## Se algo não subir

- **O painel não abre:** `docker compose ps` (o serviço `vigia` precisa estar *healthy*) e `docker compose logs vigia`. Porta 8120 ocupada por outro programa também impede.
- **O QR não aparece:** a Evolution ainda está iniciando. Esperar um minuto e clicar de novo.
- **Lê e não classifica:** falta o login do Claude (`docker compose exec -it vigia claude`, depois `/login`).
- **Conexão "aberta" e nada novo chega:** `docs/RUNBOOK.md`, seções 17 e 21.

Ao ler logs, não cole na conversa linhas com número de telefone ou texto de mensagem além do necessário.

## Depois de instalar

- A leitura acontece nos minutos :00 e :30; o botão **Ler agora**, em Conexão, adianta.
- O painel nunca marca mensagem como lida: o celular continua sendo o lugar da leitura.
- Grupos e contatos que a pessoa quiser fora: **Ajustes → conversas bloqueadas**.
- Quem usa responde pelo uso. Para uso pessoal, a LGPD não se aplica (art. 4º, I); usando para trabalho, a pessoa passa a ser a controladora dos dados de quem escreve para ela.

## Comunidade

O Greg é código aberto (MIT) e o time ouve sugestões de melhoria.

- **Sugestão ou problema:** abra uma issue em https://github.com/userj81/vigia/issues.
- **Edição no código:** pull requests são aceitos. Para mudança grande, abra uma issue antes: o projeto tem regras de segurança fixas (`CONTRIBUTING.md`) e mudança que as afrouxa não entra.
- **Problema de segurança:** aviso privado, nunca issue pública.

## Páginas do site

- https://oigreg.app/ : o que o Greg faz, com as telas e o filme de 30 segundos.
- https://oigreg.app/como-funciona.html : o caminho da mensagem, as classes e o ciclo.
- https://oigreg.app/instalar.html : instalação com Docker e nativa no macOS.
- https://oigreg.app/privacidade.html : as sete regras de privacidade, o que sai da máquina e quem responde pelo uso.
- https://oigreg.app/llms.txt : índice do site para assistentes de IA.