Zérvis

O assistente de voz que trabalha com você: atende o seu WhatsApp, pesquisa empresas,
conduz agentes de código e mostra tudo em holograma, no seu Linux.

Você fala; o Zé faz, pergunta antes do que tem efeito e avisa quando termina.
Com o Claude, o Codex ou um modelo que roda no seu próprio computador.

Um dia com o Zé · O que faz · Instalar no PC · Instalar numa VPS · Arquitetura · Código · Roteiro · Contribuir

Em desenvolvimento ativo, usado todo dia por quem o constrói. O que está pronto e o que
está em validação vem marcado em cada função; cada decisão tem o seu registro em
docs/adr.

Para quem é

Para gestores e consultores de automação e IA: quem atende clientes pelo WhatsApp, monta
integrações, fluxos e agentes para empresas, e quer um assistente que faça o trabalho pesado sem
misturar um cliente com outro. Serve também a quem só quer um assistente de voz de trabalho no
próprio Linux, com as mãos livres.

Um dia com o Zé

Tudo isto é pela voz: no microfone do PC, no navegador ou no celular bloqueado, pelo app Zé Voz.

O que o Zé faz

Voz em todo lugar

WhatsApp, como uma recepcionista

Pesquisa e dados de empresas

Oficina de código e integrações

Imersão: o Zé em holograma

Cérebros: os seus modelos, inclusive locais

O dia a dia

Por que é diferente

• Mãos livres de verdade. Ler, responder, pesquisar, delegar e aprovar, tudo pela voz, até com
  o celular no bolso. O que tem efeito sempre passa pelo seu "sim", e a frase da pergunta diz
  exatamente o que vai acontecer.
• O modelo pensa uma vez; o resto roda sem tokens. Ler o WhatsApp, buscar no arquivo, os
  avisos, o vigia e os fluxos do n8n rodam sem chamar o modelo. E, quando o plano aperta, o
  cérebro local responde de graça.
• Clientes separados de verdade. Conectores presos ao projeto pela pasta, sessões
  independentes: o n8n do cliente A nunca entra na sessão do cliente B.
• Seus dados ficam com você. Conversas, arquivo do WhatsApp, pesquisas e memória ficam nas
  suas pastas. Segredos em arquivos 0600, fora da conversa e do repositório.
• Fontes gratuitas e trocáveis. Buscador, leitor, CNPJ e imagens vêm de projetos abertos ou
  APIs públicas, cada um atrás de uma interface própria e com um vigia que avisa quando quebram.
• Falha fechada. Na dúvida, não envia, não aprova, não apaga, e diz por quê.

Como se compara

Hermes Agent (Nous Research, MIT) e OpenClaw (MIT) são assistentes generalistas excelentes, com
foco nos mensageiros. O Zérvis escolheu outro foco: voz, recepção do WhatsApp, pesquisa, oficina
de código e integração de sistemas de clientes, no Linux e na VPS. Comparação pela documentação
oficial de cada um, em outubro de 2026; detalhes na matriz comparativa.

Legenda: ● tem · ◐ parcial · — não tem.

Quando escolher cada um. OpenClaw, se o principal é falar com o assistente por muitos
mensageiros e apps de celular. Hermes, se você quer um generalista com centenas de modelos e
integração com IDE. Zérvis, se o seu trabalho é atender, pesquisar, conduzir agentes de código e
ligar sistemas de clientes, falando com ele, com cada cliente no seu lugar.

Arquitetura

O Zé é um serviço do seu usuário (zervis.service, systemd) com alguns processos ao lado,
cada um com um papel só. Tudo conversa pelo endereço local (127.0.0.1), com token; nada fica
aberto na rede.

Em números (05/11/2026)

Visão geral

flowchart TB
    subgraph rostos["Rostos: por onde você fala com o Zé"]
        mic["Microfone e caixa do PC<br>PipeWire"]
        nav["Navegador<br>painel + voz por WebSocket"]
        app["App Zé Voz<br>Android, tela bloqueada"]
        holo["Janela da Imersão<br>Chromium + câmera + mãos"]
    end

    subgraph servico["zervis.service (systemd do usuário)"]
        transp["Transportes<br>local · navegador · LiveKit"]
        voz["Voz<br>Ei Zé · VAD · fim de turno · fala"]
        nucleo["Núcleo<br>máquina de estados e laço"]
        cerebro["Cérebro<br>via rápida · Claude · Codex ·<br>OmniRoute · local · reserva"]
        mcp["Ferramentas MCP do Zé<br>jarvis · tempo · foco"]
        portal["Portal :8795<br>painel · API · login"]
        dominios["Domínios<br>oficina · pesquisa · memória · avisos ·<br>automações · foco · sistema · redes"]
    end

    subgraph filhos["Processos filhos (sobem e voltam sozinhos)"]
        imersivo["Servidor da Imersão :8794"]
        searx["SearXNG<br>buscador próprio"]
        aimem["ai-memory<br>memória longa"]
    end

    subgraph atend["zervis-atendimento (processo próprio)"]
        central["Central de Atendimento<br>API local com token"]
        wa["WaCalls (Go)<br>WhatsApp nativo"]
    end

    subgraph fora["Fora do Zé"]
        nuvem["Claude · Codex · Deepgram ·<br>ElevenLabs · Fish Audio"]
        ollama["Ollama :11434<br>Gemma 4 E4B"]
        agentes["Claude Code e Codex<br>sessões num terminal real"]
        clientes["Sistemas dos clientes<br>n8n · CRM · ERP (MCP)"]
        net["Internet pública<br>atrás da trava de rede"]
    end

    mic --> transp
    nav --> transp
    app --> transp
    transp <--> voz <--> nucleo
    nav <--> portal <--> nucleo
    holo <--> imersivo
    nucleo <--> cerebro <--> mcp --> dominios
    cerebro -.-> nuvem
    cerebro -.-> ollama
    dominios --> imersivo
    dominios --> searx --> net
    dominios --> aimem
    dominios --> agentes -- conectores do projeto --> clientes
    nucleo <-->|eventos| central <--> wa

Processos e portas

Um pedido por voz, do "Ei Zé" à resposta

sequenceDiagram
    autonumber
    actor V as Você
    participant A as Ativação e VAD<br>(na máquina)
    participant E as Escuta<br>Deepgram nova-3
    participant N as Núcleo
    participant R as Via rápida
    participant C as Cérebro
    participant F as Ferramentas MCP
    participant S as Fala

    V->>A: "Ei Zé" (o chamado nunca sai da máquina)
    A->>N: ATIVO → OUVINDO
    V->>E: o pedido, transcrito enquanto você fala
    E->>N: texto final, com o fim de turno pela entonação
    N->>R: PENSANDO
    alt conversa curta
        R-->>S: responde direto, com a persona enxuta
    else precisa de ferramenta
        R->>C: [completo]
        C->>F: chama a ferramenta (o passo aparece na barra de carregamento)
        opt tem efeito
            F->>V: CONFIRMANDO: "Envio para a Ana: amanhã às 10 eu ligo?"
            V->>F: "sim"
        end
        F-->>C: resultado
        C-->>S: resposta em streaming
    end
    S-->>V: FALANDO, frase a frase (outro "Ei Zé" interrompe)

A máquina de estados

stateDiagram-v2
    [*] --> INATIVO
    INATIVO --> ATIVO: um rosto conectou
    ATIVO --> OUVINDO: "Ei Zé"
    OUVINDO --> PENSANDO: fim da fala
    PENSANDO --> CONFIRMANDO: ação com efeito
    CONFIRMANDO --> PENSANDO: "sim" libera, "não" nega
    PENSANDO --> FALANDO: primeira frase pronta
    FALANDO --> OUVINDO: conversa contínua ou interrupção
    FALANDO --> ATIVO: "ok" ou silêncio
    ATIVO --> INATIVO: o último rosto saiu

Regras que viram teste: em INATIVO o microfone fica fechado; em FALANDO o que o microfone
ouve não é transcrito (só o chamado, para interromper); CONFIRMANDO só aceita "sim" ou "não", e
silêncio ou 40 s não fazem nada; uma fala por vez, e avisos só saem quando não há pedido em
andamento (docs/04-arquitetura.md).

O cérebro

As ferramentas

O cérebro do Claude roda o servidor dentro do próprio processo e o do Codex, por stdio: nenhuma
das ferramentas do Zé escuta numa porta. Cada chamada cai num destes níveis:

• Leitura passa sem perguntar: ler o WhatsApp, pesquisar, listar sessões, ver a tela.
• Efeito pergunta em voz alta, com a frase exata do que vai acontecer: enviar, delegar,
  agendar, cadastrar.
• Sistema segue a política de risco de cada ação do Omarchy: livre, confirmação falada,
  frase exata ou proibida.
• Apagar não existe como ferramenta: excluir é no painel, com você.

O código, pacote por pacote

Onde mora cada dado

• SQLite, um banco por área: atividade, consumo, conversas, sessões, atendimento, arquivo do
  WhatsApp, linha do tempo, vigia do n8n e uso das ferramentas. Migrações automáticas e busca de
  texto.
• Markdown: memória curta, skills, persona e a pasta do Zé que a Imersão mostra.
• JSON com escrita atômica: avisos, pendências, automações e os sinais da Imersão (estado,
  humor, onda, andamento, comandos da tela).
• Segredos em arquivos 0600, fora do banco, da conversa e do repositório.

Segurança, camada por camada

• Só local por padrão. Cada processo escuta em 127.0.0.1, com token criado a cada subida.
• Painel de fora com senha, código do autenticador (TOTP) e aparelhos lembrados. O app de
  voz recebe só uma chave de voz no pareamento, sem acesso ao painel.
• Trava de rede na pesquisa, nas imagens e nas capturas: só sai para endereços públicos da
  internet, nunca para a sua rede local.
• Atividade: tudo o que o Zé executou fica registrado, inclusive o que foi negado.
• O Zé melhora o próprio código numa cópia isolada, com testes, a sua aprovação e volta
  automática se a versão nova não subir.

Tecnologias

Créditos e licenças de cada um estão em THIRD_PARTY.md.

Princípios

• Uma linguagem por papel. Python no núcleo, no cérebro e na voz; Go no WhatsApp; Java no
  app de voz; JavaScript no painel e na Imersão. Só se reescreve noutra linguagem o que uma
  medição apontar como gargalo (ADR 0032).
• Fronteiras por processo. O que precisa ficar de pé sozinho roda à parte, com API local e
  token: a Central de Atendimento, o WaCalls, o buscador e a memória longa.
• Cérebro trocável. Claude, Codex, OmniRoute ou um modelo local atrás de uma interface só,
  com as mesmas ferramentas e a mesma aprovação.
• Os agentes fazem; o Zé conduz. As sessões são o Claude Code e o Codex de verdade, com as
  skills e os conectores do projeto (ADR 0037).
• O n8n executa; o Zé constrói e vigia (ADR 0038).
• Cada habilidade é nativa: um grupo de ferramentas, o autoconhecimento do Zé e uma decisão
  registrada.
• Uma essência que não muda. O que o Zé é e não deixa de ser está em
  docs/essencia.md: nenhuma mudança, nem a feita por ele mesmo, pode
  contrariá-la.

Instalar no PC

No terminal da sessão gráfica, como usuário comum, com Git, Make e curl instalados:

git clone https://github.com/gestordescomplicaa-web/zervis.git
cd zervis && deploy/instalar-pc.sh

O instalador prepara Python e dependências, os modelos de voz, os agentes de código e o Go
verificado para o WhatsApp. Instala o serviço do usuário, o atalho Zérvis no menu e o comando
zervis, e abre o painel na configuração inicial (http://127.0.0.1:8795/, só no próprio PC;
acesso por outros aparelhos se liga depois, no painel).

No Ubuntu 24.04, os pré-requisitos são sudo apt install git make curl xdg-utils pulseaudio-utils.
Sem as ferramentas de áudio, o instalador avisa; o painel e a conversa por texto continuam
funcionando. O controle completo da máquina é no Omarchy; outros Linux têm o controle reduzido.

Instalar numa VPS

Num Ubuntu 24.04 ou parecido, com um usuário comum (não root) e Git, Make e curl instalados:

git clone https://github.com/gestordescomplicaa-web/zervis.git
cd zervis && deploy/instalar-servidor.sh

O instalador prepara tudo, deixa o Zé rodando como serviço e termina com um endereço HTTPS e um
código de primeiro acesso: abra o endereço, crie a senha e ligue o código do autenticador, sem
túnel SSH. O passo a passo e o login do Claude e do Codex estão em docs/vps.md.

O comando zervis

Sem terminal, o mesmo update fica em Ajustes → Atualizações, no painel: o Zé procura uma vez
por dia, avisa quando há versão nova, mostra o que muda e atualiza num clique.

Desenvolver

Linux, Python 3.12 a 3.14, Node.js 22+ e uv:

uv sync
npm ci
make check                 # formatação, lint, tipos e testes
uv run python -m zervis    # sobe o Zé; o painel abre em http://127.0.0.1:8795/

Na primeira subida, o Zé baixa os modelos de som e a voz (Cadu, 63 MB), confere o SHA-256 de cada
um e abre a configuração inicial: perfil, acesso ao Claude (assinatura ou chave de API) e a chave
do Deepgram para a voz. Sem a palavra de ativação treinada, ele atende pelo painel e pelo
teclado. make instalar instala o serviço do systemd do usuário e o atalho "Zérvis" no menu de
aplicativos (PORTA=8796 make instalar para outra porta).

Numa VPS, sem tela e sem som, o Zé não oferece o que a máquina não tem.

Onde ficam os seus dados

Nada é enviado ao repositório nem a terceiros sem pedido explícito. Nenhum nome, fuso ou caminho de
alguém fica fixo no código: o que é seu vem da configuração. ZERVIS_PERFIL=<nome> usa outro
conjunto de pastas (zervis-<nome>); ZERVIS_RAIZ=<pasta> põe as três dentro de uma pasta só.

Documentação

Licença

AGPL-3.0-or-later. A voz usa o Piper
(GPL-3.0) e a voz Cadu (CC0); os demais componentes de terceiros e as licenças estão em
THIRD_PARTY.md.