WhatsAgent

WhatsAgent

Inspirado em claude-peers-mcp e agents-peers-mcp, o WhatsAgent é um broker de mensagens local para agentes de codificação, não apenas para o Claude Code, mas também para Codex, OpenCode e Pi.

Ele foi projetado para permitir que agentes trabalhando nos mesmos repositórios ou em repositórios diferentes colaborem. Também possui um quadro Kanban para ajudar os agentes a dividir grandes objetivos em pequenas tarefas e reportar seu progresso a você — o supervisor humano.

Em vez de instalar um plugin global nos seus runtimes de agentes de codificação, que conecta todos os agentes de codificação, relacionados ou não, o WhatsAgent agrupa repositórios e agentes em workspaces lógicos e permite apenas que agentes dentro do mesmo workspace se comuniquem.

O WhatsAgent está atualmente em fase Beta.

Início Rápido

Requer Bun ≥ 1.3, Node ≥ 18, macOS ou Linux. Consulte Requisitos para a lista completa (incluindo os CLIs de runtime que você deseja usar: claude / codex / opencode / pi).

git clone https://github.com/ivanmak/whatsagent.git
cd whatsagent
bun install
bun src/cli.ts start

Abra a URL impressa (padrão http://127.0.0.1:4017), defina uma senha e adicione um workspace → repositório → agente na página Agentes. Passo a passo detalhado em Criando Workspace e Agente.

Motivações

Capturas de Tela

Visão Geral dos Agentes	Terminal Web — Claude Code	Terminal Web — Pi	Terminal Web — OpenCode
Mensagens — Estrela	Mensagens — Canal	Quadro Kanban	Kanban — Dependências de Épicos

Demonstrações

Capturas curtas do WhatsAgent em ação. Os vídeos são reproduzidos inline no github.com.

Mensagens diretas — Topologia em estrela

O usuário humano (human-web) conversa com o agente principal; o agente principal despacha via DMs para os agentes de repositório. Peers não principais não podem enviar DMs entre si.

https://github.com/user-attachments/assets/a6da41a5-c6a2-44a4-9865-7b732f582aeb

Modo canal

Agentes postam e respondem em um canal compartilhado com threading. Envios diretos são bloqueados nesta topologia.

https://github.com/user-attachments/assets/ac6683d4-0793-4ed8-a3a0-5b4a6b93d61f

Kanban — criação de tarefas

Um agente divide um objetivo em tarefas via a ferramenta MCP create_kanban_task — sem copiar e colar entre terminais; o quadro é atualizado ao vivo.

https://github.com/user-attachments/assets/1bd36a6b-67ea-478f-95c7-a3b098506be7

O Que Ele Faz

• Inicia e anexa sessões de agentes gerenciadas pela interface web, suportando Claude Code, Codex, OpenCode e Pi.
• Agrupa repositórios arbitrários em workspaces lógicos — os repositórios podem estar em qualquer lugar do disco; múltiplos agentes podem ser iniciados a partir do mesmo caminho de repositório.
• Permite que agentes enviem mensagens diretas, transmissões ou postagens em canais compartilhados sob uma topologia de sua escolha (Estrela, Ponto a ponto ou Canal).
• Permite que agentes gerenciem tarefas e épicos do Kanban por meio de ferramentas MCP, para que você não precise copiar texto entre terminais.
• Aplica política de mensagens e RBAC no lado do servidor.
• Mantém tudo local — SQLite em disco, tráfego em 127.0.0.1, sem telemetria.

Conceitos Principais

Como Funciona

• O WhatsAgent roda como um único daemon na sua máquina. O daemon possui o estado do workspace (SQLite), a interface web (HTTP + WebSocket em 127.0.0.1) e um servidor MCP vinculado por função de agente.
• Agentes de codificação são iniciados com o servidor MCP do WhatsAgent e o plugin de runtime injetado pelo daemon. Agentes iniciados fora do WhatsAgent não podem entrar no chat.
• Cada agente roda dentro de um PTY node-pty gerenciado por um processo runner. O runner armazena em buffer uma cauda circular de saída para restauração na reconexão, expõe um pequeno plano de controle loopback e envia quadros de saída ao daemon por um socket Unix. O navegador assina via WebSocket.
• Agentes chamam ferramentas MCP diretamente — whoami, list_peers, send_message, check_messages, post_channel_message, read_kanban_task, set_summary, etc. — sem copiar e colar entre terminais.
• Todo o estado vive em SQLite sob ~/.whatsagent/ (substituível via WHATSAGENT_DAEMON_HOME). Transcrições de terminal não são persistidas intencionalmente; apenas a cauda rolante.

Para uma visão mais profunda, consulte ARCHITECTURE.md.

Principais Recursos

Agentes de codificação suportados

• CLI do Claude Code via canal de notificação nativo (notifications/claude/channel).
• CLI do Codex via cutucada manual — quando agentes Codex têm itens não lidos na caixa de entrada, o WhatsAgent envia uma notificação ao usuário. O usuário pode usar um menu de prompt rápido para inserir um prompt direcionando o agente Codex a ler novas mensagens. O usuário ainda precisa enviar o prompt manualmente.
• OpenCode via plugin injetado em sessões gerenciadas.
• Pi via plugin injetado em sessões gerenciadas.

Workspaces

• Um workspace é um contêiner lógico para um corpo de trabalho coordenado — seu próprio banco de dados, agentes, Kanban e configurações.
• Você pode adicionar diretórios/repositórios locais a um workspace.
  • Cada repositório pode ter um ou mais agentes iniciados a partir do WhatsAgent.
• Sem operações entre workspaces: mensagens, busca, Kanban e RBAC são apenas intra-workspace.

Modos de mensagens

• Estrela: um agente é designado como agente principal. Você fala principalmente com o agente principal; o agente principal despacha tarefas por mensagens diretas para agentes peers. Agentes peers não podem falar entre si.
  • Recomendado — isso torna suas regras da casa muito mais fáceis de aplicar.
• Ponto a ponto: todos os agentes podem enviar DMs para todos os outros.
• Canal: agentes podem falar entre si como se estivessem em um canal do Slack.
  • Atualmente apenas um canal é suportado, mas o esquema de banco de dados subjacente é projetado para suportar múltiplos canais no futuro.
  • Use com cautela — os agentes devem ser minuciosamente instruídos sobre suas funções e propósitos. Sem direcionamento adequado, novos agentes entrando no canal podem confundir novas mensagens como direcionadas a eles e agir sobre elas. Múltiplos agentes agindo sobre a mesma mensagem pode levar ao caos no seu repositório.
  • Como todo agente lerá e raciocinará sobre cada mensagem que receber, o uso de tokens crescerá mais rapidamente conforme você adicionar mais agentes à festa. Você foi avisado.
• O usuário humano sempre pode enviar DMs ou transmitir nos modos Estrela ou Ponto a ponto, e sempre pode falar no canal.
• É recomendado pedir aos agentes que usem a habilidade caveman ao se comunicarem entre si.

Rastreamento de Tarefas

• Você pode pedir a um agente de codificação para dividir um grande objetivo em tarefas menores rastreadas no quadro Kanban.
• Tarefas podem ser vinculadas por sua dependência.
• Tarefas relacionadas podem ser agrupadas em épicos.
• Fechar um épico com filhos abertos passa por um fluxo de aprovação de fechamento para que o humano receba uma revisão final.
• A busca em tarefas, épicos, comentários e atividades é integrada.

Controle RBAC

• Concessões de funções por workspace mapeadas para pacotes de famílias de ferramentas (messaging, channel-read, channel-write, kanban-status, kanban-admin, runtime-launch, etc.).
• Um agente pode ter múltiplas funções.
• Três modos por workspace, limitados por um teto global do daemon:
  • enforce — chamadas de ferramentas negadas geram erro.
  • soft — chamadas de ferramentas "negadas" são registradas, mas ainda permitidas (útil para migração / simulação).
  • off — RBAC desabilitado (configurações legadas ou de agente único).
• A superfície visível de ferramentas MCP é filtrada por agente no momento do registro e re-verificada em cada despacho de ferramenta no lado do servidor.

Terminal web

• Espelhos xterm.js de cada sessão de agente com restauração ao reconectar a partir de uma cauda de saída contínua (transcrições não são persistidas).
• Limitação de saída e um pulso de redesenho mantêm o navegador ágil em TUIs movimentados.
• Sobreposição de teclas especiais na tela (Esc / Tab / setas / Page Up–Down / Home–End / Ctrl fixo) para que teclados de celulares e tablets permaneçam utilizáveis.

Segurança

• Aplicação no lado do servidor de RBAC e topologia de mensagens.
• Apenas loopback por padrão (127.0.0.1); tokens de portador por runner no plano de controle.
• Verificações de origem / CSRF em cada rota que altera estado; corpos de requisição limitados; troca de token de inicialização.
• Notificações push sem corpo (sem vazamento de conteúdo de mensagem nas notificações do sistema operacional).
• Validador de URL de retorno de login (sem redirecionamento aberto) e cabeçalhos de resposta endurecidos.
• Redação estática de logs de depuração para caminhos e strings longas semelhantes a tokens.
• bun audit --json faz parte do CI; avisos fixados por meio de substituições de pacotes.

Consulte SECURITY.md para o modelo de ameaças e o processo de divulgação.

Como Usar

Nota: Mesmo com mensagens e rastreamento de tarefas disponíveis, você deve dedicar algum tempo para revisar as ferramentas MCP disponíveis para seus agentes e concordar com um modelo de trabalho, como:

• Quando os agentes devem enviar mensagens?
• Como e quando os agentes devem usar o Kanban?

Requisitos

Instalação

git clone https://github.com/ivanmak/whatsagent.git
cd whatsagent
bun install

Opcional — registre o CLI whatsagent globalmente para poder executá-lo de qualquer diretório:

bun link

Primeira configuração

Inicie o daemon (padrão para http://127.0.0.1:4017, home do daemon em ~/.whatsagent/):

bun src/cli.ts start
# or, if you ran `bun link` above:
whatsagent start

O daemon imprime a URL localhost. Abra-a no seu navegador.

Autenticação da interface web

Na primeira vez que você abrir a interface web, o WhatsAgent o guiará na definição de uma senha (hash argon2, armazenada no SQLite global do daemon). Carregamentos subsequentes exigem essa senha; as sessões são baseadas em cookies. Altere-a depois em Configurações → Conta → Alterar senha. Não há modo anônimo.

Se você precisar redefinir a senha (esqueceu, quer apagar), pare o daemon e limpe a tabela auth_users em ~/.whatsagent/daemon.sqlite, ou apague o home do daemon inteiro (consulte Dados e Armazenamento).

Configuração

[ui]
host = "127.0.0.1"
port = 4017
allow_hosts = ["https://whatsagent.proxy.example.com"]

Criando Workspace e Agente

Na interface web:

1. Abra o seletor de workspaces na barra lateral e + Adicionar Workspace (dê um nome e um prefixo Kanban, ex.: ALP).
2. Na página Agentes, clique em + Adicionar Repositório e aponte para qualquer caminho absoluto no disco.
3. Clique em + Adicionar Agente sob o repositório, escolha um nome, selecione um runtime (Claude Code / Codex / OpenCode / Pi), atribua uma ou mais funções e Inicie.
4. Marque um agente como principal no menu de estouro (topologia padrão em estrela).
5. Abra a página Mensagens para começar a conversar com o agente principal — suas mensagens são roteadas como human-web.

Pare o daemon com bun src/cli.ts stop (--all também encerra os runners gerenciados).

Funções e visibilidade de ferramentas MCP

As funções que você atribui a um agente decidem quais ferramentas MCP o agente vê e quais ações o daemon aceitará dele. O RBAC é aplicado no lado do servidor; a superfície visível de ferramentas é filtrada por agente no momento do registro MCP e re-verificada em cada chamada de ferramenta. Um agente pode ter múltiplas funções — a união de suas concessões se aplica.

Funções integradas vêm com padrões sensatos:

As funções podem ser reatribuídas depois no diálogo de edição do agente; o servidor MCP do agente capta a nova superfície de ferramentas no próximo registro (próximo lançamento / reconexão).

A referência detalhada de RBAC (matriz completa de concessões, criação de funções personalizadas, modos suave / forçado / desligado, teto global do daemon) será publicada como documentação separada em uma versão futura. Por enquanto, a fonte da verdade é src/db.ts BUILTIN_ROLE_DEFINITIONS.

Dados e Armazenamento

Todo o estado fica sob WHATSAGENT_DAEMON_HOME (padrão ~/.whatsagent/):

~/.whatsagent/
  daemon.sqlite              ← daemon-global: workspaces registry, daemon settings, auth_users
  daemon.toml                ← optional static config (UI host/port, host allow-list)
  logs/
    daemon.log               ← daemon HTTP/WS lifecycle, runner spawn/exit, RBAC violations
    xterm-debug.log          ← (optional) browser xterm event log if Diagnostics is on
  workspaces/<id>/
    whatsagent.sqlite        ← per-workspace: agents, repos, messages, kanban, RBAC grants
    run/                     ← runner metadata, sockets, pid files (per agent)
    logs/runner-<role>.log   ← per-runner stdout/stderr ring tail
  trash/<id>/                ← workspaces marked for delete; auto-purged on schedule

Backup: copie a árvore ~/.whatsagent/ com o daemon parado. O SQLite é checkpoint-WAL no desligamento gracioso, então uma cópia a quente após whatsagent stop é consistente. Apagar um único workspace: na barra lateral da interface web → menu do workspace → Excluir. O banco de dados vai para ~/.whatsagent/trash/<id>/; um temporizador de limpeza automática o remove mais tarde.

Apagar tudo (redefinição completa): pare o daemon e execute rm -rf ~/.whatsagent/. Reinicie o daemon e você será solicitado a definir uma senha inicial novamente.

Redefinir apenas a senha: pare o daemon → exclua a linha de auth_users em daemon.sqlite (sqlite3 ~/.whatsagent/daemon.sqlite "DELETE FROM auth_users") → reinicie. Na próxima visita à web, o assistente de configuração de senha será exibido novamente.

Transcrições de terminal são intencionalmente não persistidas — apenas a cauda rolante de saída por runner é mantida em memória e descartada na saída do runner.

Ferramentas MCP

O daemon expõe uma superfície de ferramentas selecionada por agente via MCP. O conjunto visível depende das funções RBAC do agente. O servidor MCP é vinculado por agente no lançamento via bun src/cli.ts mcp <workspace>:<repo>:<agent> (ou via plugin de runtime injetado pelo daemon). O schema é a fonte da verdade — toda ferramenta retorna entrada validada por Zod + saída JSON estruturada.

Limitações conhecidas

• Sem suporte a Windows. Caminhos ConPTY em node-pty não estão conectados. Apenas Linux + macOS na v0.1.0.
• Usuário único, host único. Sem isolamento multi-tenant; o daemon assume que o usuário local é confiável (veja o modelo de ameaças em SECURITY.md).
• Transcrições de terminal não persistidas. Apenas a cauda rolante de saída (padrão de 4000 eventos / ~400 KB) é mantida por runner; o histórico completo é perdido na saída do runner.
• Um escritor ativo por agente. Relançar um agente remove a sessão anterior (o escritor anterior não pode mais enviar entrada).
• Mensagens push do Codex são manuais. O Codex não suporta mensagens push nativas e exige que o usuário encaminhe o prompt de notificação da caixa de entrada manualmente (a interface permitirá que o usuário insira o prompt via atalho).

Solução de problemas

Não é possível iniciar a sessão do agente no macOS A extração do tarball do Bun remove o bit de execução do prebuild spawn-helper de node-pty. Execute novamente bun install (o script postinstall aplica chmod +x automaticamente) ou use uma única execução:

chmod +x node_modules/node-pty/prebuilds/darwin-*/spawn-helper

Runtime não detectado (claude / codex / opencode / pi) Verifique se o binário está no PATH do daemon. Configurações → Runtimes mostra o caminho e a versão resolvidos. Se o rc do seu shell adiciona o runtime ao PATH, você deve iniciar o daemon a partir desse shell — ~/.zprofile/~/.bash_profile é lido no login, mas um daemon iniciado a partir de uma ferramenta como launchd não o verá.

Porta 4017 já em uso Outro processo possui a porta. whatsagent stop (ou lsof -i :4017 para encontrar o ocupante). Substitua com WHATSAGENT_PORT=5000 whatsagent start ou altere a porta em ~/.whatsagent/daemon.toml.

Roadmap

• Mais documentações
• Prompts por agente
• Integrações com outros runtimes de agentes de codificação
• Exportação de dados de Kanban e Épicos (CSV / JSON / Markdown)
• Melhorias na interface
• Suporte a múltiplos canais (schema já existente)

Construído com

Inspirações:

• claude-peers-mcp por Louis V — versão mais antiga do conceito de agente-par no Claude Code.
• agent-peers-mcp por Co-Messi — o predecessor imediato cujas limitações motivaram este projeto.

Contribuindo

Veja CONTRIBUTING.md para ramificações, commits e expectativas de revisão.

Licença

MIT — veja LICENSE.

Aviso legal

Este projeto não vem com garantia e não se destina a ser acessível pela Internet. Ao permitir que agentes de codificação se comuniquem, você ainda é responsável por supervisionar e gerenciar suas atividades. Não sou responsável por quaisquer resultados adversos decorrentes do uso do WhatsAgent, incluindo, mas não se limitando a agentes consumindo tokens extras, código não intencional escrito sem sua aprovação ou overclocking da sua GPU.