Bot Mode

O Bot Mode transforma os seus perfis do Hermes em um elenco de Bots com nome. Cada Bot tem o próprio papel, modelo, memória, skills e avatar; os Bots rodam rotinas recorrentes, deliberam juntos em conversas de grupo e mandam mensagem uns para os outros. Monte um Bot especialista uma vez e ele fica ali para sempre, a um clique de distância.

O Bot Mode vem embutido no aplicativo desktop e está ligado por padrão — não precisa instalar nada. Ele aparece como uma aba Bots ao lado de Sessions na barra lateral esquerda, com um painel Routines encaixado ao lado da conversa enquanto a aba Bots estiver ativa.

Um Bot é um perfil

Não há primitivo novo para aprender: um Bot é um perfil do Hermes — configuração, memória, skills, credenciais e histórico de conversa isolados em ~/.hermes/profiles/<name>/. O Bot Mode é uma interface sobre esse primitivo, então tudo que você faz nele também é visível pela CLI: hermes -p <bot> chat abre o mesmo agente, e as rotinas dos Bots aparecem em hermes cron list. Sem remendos no núcleo, sem daemons em segundo plano, sem armazenamento extra.

O painel de Bots

O elenco mostra uma linha por perfil de agente: avatar, prévia da última mensagem e horário.

• Clique em um Bot para cair na conversa dele — todo Bot tem uma conversa Bot Chat canônica e permanente, criada (e fixada) no instante em que o Bot nasce.
• Ativos agora — uma faixa de presença acima do elenco mostra todo Bot que está trabalhando: o perfil ocupado no gateway mais qualquer Bot que escreveu nos últimos 90 segundos. Cada chip abre a conversa daquele Bot. A faixa nunca reordena o elenco e some quando a frota está ociosa.
• Busca filtra o elenco conforme você digita.
• Esconder um Bot — clique com o botão direito em uma linha → Hide Bot para tirar do elenco e da faixa de ativos um Bot que você não usa. Esconder é só visual: as @menções continuam resolvendo, as participações em conversas de grupo ficam intactas e as rotinas seguem rodando. Assim que pelo menos um Bot está escondido, aparece um botão de olho no cabeçalho do painel — clique nele para revelar os Bots escondidos, apagados no lugar, e depois clique com o botão direito → Unhide Bot para trazer um de volta. Bots escondidos nunca mostram aviso, mas acumulam atividade não lida em silêncio e o olho ganha um pontinho para você saber que aconteceu algo. O estado de escondido fica nos metadados do perfil do Bot, então ele acompanha o Bot em todo desktop conectado àquele backend.

A Bot Chat canônica é uma conversa para sempre

Digitar /new (ou /reset) dentro da conversa canônica de um Bot bifurcaria a relação em uma sessão de rascunho — a única coisa que o Bot Mode promete que nunca acontece. O compositor redireciona para /compact: contexto de trabalho novo, mesma conversa. Sessões comuns no mesmo perfil mantêm o /new livre.

Criar um Bot

Aperte New Agent no elenco. O caminho rápido tem três campos — Name, Title, Description — e o Bot existe em segundos, apresentando-se na primeira mensagem da sua nova Bot Chat.

Um botão Advanced abre toda a superfície de capacidades:

• Clonar de um perfil existente — comece a partir da configuração, das skills, do SOUL e da memória de outro Bot, ou escolha Fresh profile para começar do zero.
• Create empty — pule por completo as skills empacotadas e tenha um perfil mínimo.
• Fixar modelo e provedor — dê ao Bot um modelo próprio. Qualquer par provedor/modelo que o Hermes conheça funciona, e Bots diferentes podem rodar em modelos diferentes lado a lado. Deixe em branco para herdar do perfil de lançamento.
• SOUL.md personalizado — a persona e as instruções permanentes do Bot.
• Habilitação por skill, por conjunto de ferramentas e por servidor MCP — marque exatamente as capacidades de que este especialista precisa.
• Chaves compartilhadas — por padrão, o Bot novo compartilha um único pool de OAuth/token com o perfil principal, para que uma renovação de credencial não invalide a outra. (Gateways mais antigos copiam as credenciais em vez disso — ainda funciona, só fica bifurcado.)

Escolher em qual máquina ele mora ("Create on")

Com mais de uma conexão registrada em Settings → Connections, o diálogo New Agent ganha um seletor Create on. Escolha um dispositivo e o perfil é criado no backend daquela máquina — a sua janela nunca troca de gateway. O Bot novo aparece então no elenco como um Bot de Conexões (com um identificador @name-device quando o nome existe em várias máquinas), e conversar com ele roteia para a máquina dele.

Com uma conexão só (o caso comum), o seletor fica escondido e o Bot é criado na máquina à qual você está conectado — exatamente o comportamento antigo.

Observações sobre criação remota:

• A origem do clone é um perfil da máquina de destino (o default dela) — uma máquina remota não tem os seus perfis locais para clonar.
• A aba Capabilities ao vivo se fixa no backend da máquina de destino, então skills, ferramentas e servidores MCP que você configurar durante a criação vão parar na máquina onde o Bot vai morar. (Versões mais antigas do desktop recaem em listas de Skills/Tools/MCP preparadas para destinos remotos; ambas leem o catálogo da máquina de destino.)
• Cancelar o diálogo descarta o rascunho de perfil na máquina em que ele foi criado.

Edit Profile (botão direito em um Bot) reabre a mesma superfície no perfil vivo a qualquer momento: avatar, título, descrição, modelo fixado, skills, conjuntos de ferramentas, servidores MCP e o SOUL.md inteiro.

Duplicate (botão direito) faz um clone completo de um Bot — configuração, skills, SOUL.md, memória e aparência. Delete Profile remove um em definitivo, atrás da mesma confirmação destrutiva que o menu de perfis do desktop usa; o perfil padrão não pode ser apagado.

Avatares

Todo Bot ganha um rosto:

• Rostos de blob (padrão) — um rosto de corpo mole determinístico, desenhado a partir do nome do Bot: mesmo nome, mesmo rosto, para sempre. Enquanto você digita um nome em New Agent, o rosto acompanha ao vivo; aperte Randomize para sortear de novo, Lock face para manter o que você gostou mesmo se o nome mudar, ou fixe uma das seis silhuetas (redonda, orgânica, quadrada, tocos, nuvem, sol) enquanto todo o resto continua vindo do nome.
• Rostos geométricos — as clássicas 7 formas × 10 cores, com olhos que piscam e varrem enquanto o Bot trabalha.
• Uma imagem enviada — qualquer figura que você queira.
• Um retrato gerado por IA — quando há um backend de imagem configurado, gerado ali mesmo (isso usa o RPC padrão image.generate e funciona tanto em gateways locais quanto remotos).
• Um pet de pixel — um companheiro da galeria petdex que pula ao lado do avatar enquanto o Bot está ocupado. Rode hermes pets em um terminal para explorar a galeria.

A aparência, o título e a descrição de um Bot ficam nos metadados do perfil no backend, então o mesmo Bot aparece igual em todo desktop conectado àquele backend.

Rotinas

O painel Routines prende tarefas recorrentes ao Bot que as executa — "resuma minha caixa de entrada toda manhã" fica ao lado do Bot responsável por isso. O painel encaixa ao lado da conversa só enquanto a aba Bots estiver ativa e sai de cena quando você volta para Sessions (versões mais antigas do desktop o mantêm sempre visível). Um seletor estruturado monta o agendamento (primeiro a frequência, depois só o detalhe que importa), com um campo Advanced expondo a string bruta de agendamento do Hermes.

As rotinas são simples jobs de cron do Hermes com o prefixo de espaço de nomes [bot:<name>] <routine> — elas também aparecem em hermes cron list e na página de Cron do núcleo. As execuções caem no histórico de conversa do próprio Bot, então o resultado fica exatamente onde você falaria com aquele Bot de qualquer jeito.

Grupos e conversas de grupo

Clique com o botão direito em um Bot local → Manage groups para adicioná-lo ou removê-lo de quantas conversas de grupo quiser. Escolha grupos existentes de forma independente ou crie um ali mesmo. A participação local fica nos metadados do perfil sincronizados pelo backend, então ela acompanha aquele perfil entre desktops; perfis antigos com um grupo legado continuam funcionando. Bots de Conexões entram pelo seletor New Group Chat e permanecem qualificados pela origem no estado compartilhado da sala.

As salas seguem os seus gateways, não um Desktop. A transcrição recente, os membros, a foto e o nome de cada sala são espelhados nos metadados de perfil compartilhados de todo gateway ao qual o seu Desktop está conectado, com versionamento por gateway para que dois Desktops escrevendo ao mesmo tempo façam mesclagem em vez de sobrescrever um ao outro. Abra o Hermes Desktop em outra máquina contra o mesmo gateway (rede local, Tailscale, onde for) e a sala aparece com o histórico dela; clientes só de gateway também a veem. As salas carregam uma identidade interna durável, então renomear uma muda só o nome exibido em todo lugar, dissolver uma a remove em definitivo em todo cliente — até nos que estavam offline na hora — e recriar um grupo de mesmo nome começa uma sala genuinamente nova. Se um gateway morre ou é removido, nada se perde: todo Desktop conectado guarda a sala inteira localmente e a semeia de novo em qualquer gateway ao qual se reconecte. (O registro completo de orquestração fica no armazenamento local de cada Desktop; o espelho compartilhado é uma projeção limitada do histórico recente.)

Os grupos são linhas independentes no mesmo elenco ordenado por atividade dos DMs de Bot. Um Bot mantém uma linha de DM mesmo pertencendo a vários grupos, enquanto todo grupo ganha a própria linha de sala com contagem de membros, prévia da última mensagem, horário e estado de "precisa de você".

Open chat em qualquer linha de grupo (2 a 6 Bots) abre uma sala compartilhada onde o grupo todo se coordena:

• A sua mensagem dispara até três rodadas em série de turnos dos membros. Os Bots @mencionados respondem (todo mundo responde quando ninguém é mencionado); cada Bot responde de forma breve ou passa a vez, e a sala se aquieta quando uma rodada inteira fica em silêncio.
• Os Bots puxam uns aos outros com @name e escalam decisões de verdade para você com @user — a linha do grupo mostra um selo de needs you quando isso acontece.
• Limites rígidos (10 mensagens por envio, 3 rodadas) impedem que as salas girem em falso.
• Cada membro mantém a própria sessão persistente Group: <name>, então o contexto da sala sobrevive como em qualquer outra conversa.
• Nem todo Bot responde a toda mensagem. Falar é escolha de cada membro — um Bot responde só quando tem algo novo a acrescentar e passa a vez no resto; @mencionar membros específicos limita a rodada a eles. Espere que falem os membros a quem você se dirigiu (ou quem tiver o que dizer) e que o resto fique quieto.
• As salas podem atravessar máquinas. O seletor New Group Chat senta Bots de qualquer conexão registrada; os turnos de cada membro rodam na máquina dele, na sessão Group: <name> de lá. Membros de outras máquinas levam um selo de dispositivo (dixie · Mac Mini) na sala e nas transcrições dos outros membros, e o identificador desambiguado @name-device funciona nas menções da sala — assim, agentes de mesmo nome em duas máquinas nunca se confundem.

Mensagens entre bots

Os Bots mandam mensagem uns para os outros com atribuição, e você pode repassar trabalho de qualquer conversa:

• @menções — digite @researcher have a look at this em qualquer conversa e o autocompletar de @ do compositor ajuda a escolher o Bot certo; no envio, a menção é resolvida contra o elenco vivo e o Bot ativo é informado exatamente de quem você quis dizer (perfil, nome amigável e dispositivo, no caso de Bots de outra conexão). O Bot então compõe a própria mensagem e a envia com message_agent — o seu texto nunca é encaminhado literalmente, e a resposta volta atribuída àquele agente. Um endereço de e-mail ou um @ desconhecido passa intocado. Bots em outras máquinas conectadas são alcançáveis do mesmo jeito: o Desktop retransmite a mensagem pelo socket daquela conexão (veja Bots entre máquinas, abaixo).
• Bots renomeados mantêm as tags em dia — dê a um Bot um nome amigável (o lápis no cabeçalho da conversa dele, ou hermes profile rename) e ele passa a ser marcável por esse nome: um Bot intitulado Research Buddy atende por @research-buddy (e @researchbuddy), tanto em conversas comuns quanto em salas de grupo. O autocompletar de @ do compositor oferece a tag renomeada e também casa quando você digita o nome antigo do perfil, que continua resolvendo.
• Mensagens diretas — toda Bot Chat carrega a ferramenta message_agent: um Bot manda mensagem a um colega chamando message_agent(target="researcher", message="…"). A ferramenta valida o destino contra o elenco vivo, prefixa automaticamente a atribuição Message from 🤖 <sender> (@<sender>): do remetente e entrega na Bot Chat canônica do colega. A entrega é dispare e esqueça: o remetente recebe uma confirmação, termina o turno dele, e a resposta chega depois como uma notificação de conclusão em segundo plano. A mensagem viaja como parâmetro de verdade (nada é interpretado pelo shell — aspas, $(...) e crases chegam literais), e o Bot compõe a própria mensagem em vez de repassar as suas palavras. O elenco de colegas — nomes e papéis vindos do título/descrição de cada perfil — faz parte do prompt de sistema de toda Bot Chat, então os Bots sabem quem faz o quê antes de escolher um destinatário. A ferramenta existe somente em sessões canônicas de Bot Chat em instalações gerenciadas pelo Bot Mode; conversas comuns, sessões de membro em salas de grupo e sessões de CLI nunca a veem.

O backend ensina o protocolo de mensagens à sessão canônica de Bot Chat de cada Bot automaticamente na hora de montar o prompt — inclusive quando um colega a abre sem interface pela CLI. Só a Bot Chat canônica recebe a seção do protocolo; as suas sessões comuns e o seu SOUL.md ficam intocados. Isso é controlado por agent.bot_mode_protocol no config.yaml (padrão: ligado):

agent:
  bot_mode_protocol: true   # injeta o protocolo de mensagens entre bots nas Bot Chats canônicas

observação

A entrega entre bots é por invocação: o Bot que recebe pega a mensagem na próxima vez que rodar. Interromper um Bot ao vivo no meio de uma conversa é trabalho futuro.

Turnos que falham repetem com segurança

Um turno de entrega que falha é repetido no máximo uma vez, e só quando a repetição pode de fato ajudar. Falhas transitórias (runtime de destino offline, tempo esgotado na entrega, limite de taxa ou erro de servidor do provedor) rodam de novo a mesma sessão de Bot Chat, sem mudança. Uma falha por estouro de contexto também roda de novo a mesma sessão — o turno repetido compacta a transcrição acima do limite pela passagem padrão de compressão de contexto antes de chamar o modelo, então a repetição cabe onde a original não coube. Falhas de autenticação, de cota e de configuração nunca são repetidas sozinhas: uma segunda tentativa não as conserta e só queima cota, então a falha é mostrada na hora. Um turno repetido nunca começa uma sessão nova — o histórico e o contexto da sua Bot Chat ficam intactos.

Quando uma entrega falha: motivos tipados

Um turno de bot ou uma entrega de relay que falha carrega um código reason legível por máquina ao lado do texto de erro humano, de ponta a ponta: o gateway de destino classifica a falha (provider_auth_or_access, provider_quota_limit, provider_rate_limit, provider_server_error, context_overflow, missing_config, model_unavailable, runtime_offline, queued_expired, delivery_timeout, target_busy, unknown), o Desktop a encaminha, e a notificação de conclusão do agente remetente vem marcada com [reason: <code>] antes do texto de erro. Um agente que chama pode ramificar pelo código — "entre de novo" versus "tente mais tarde" — em vez de interpretar a prosa do provedor. O selo de "precisa de atenção" do Desktop usa os mesmos códigos.

Mensagens entre máquinas conectadas (o relay do Desktop)

Todo gateway que você registra em Settings → Connections — local, URL remota, SSH, Hermes Cloud, docker — é uma linha persistente que o Desktop mantém aberta, e o Bot Mode usa essas linhas para mensagens automaticamente. Sem configuração extra:

• Os elencos se propagam sozinhos. Enquanto o Desktop roda, ele periodicamente conta a cada gateway conectado quais agentes moram nas outras conexões. O elenco de colegas de toda Bot Chat passa a listá-los ("Teammates on OTHER connected machines"), com nomes, papéis e em qual máquina estão — e o elenco se atualiza quando agentes aparecem, somem ou são renomeados (época de capacidade).
• O message_agent chega neles direto. Um Bot no seu notebook manda mensagem ao agente na nuvem com message_agent(target="moxie", …) exatamente como faria com um colega local. Se o mesmo identificador existe em várias máquinas, desambigue com target="moxie@<connection>" (o erro da ferramenta diz ao Bot as formas exatas). A entrega vai pelo Desktop: o gateway remetente enfileira a mensagem, o Desktop a retransmite ao gateway da conexão de destino, o Bot de destino roda um turno na Bot Chat canônica dele, e a resposta volta ao remetente como a mesma notificação de conclusão em segundo plano que os DMs locais usam.
• O Desktop é o carteiro. A entrega entre conexões funciona enquanto um Desktop que conhece as duas conexões estiver rodando (ele guarda os sockets e as credenciais — os gateways nunca veem a autenticação um do outro). Se o Desktop for fechado no meio de uma entrega, o Bot remetente é avisado de que a resposta não chegou, em vez de ficar pendurado. Para mensagens sempre ativas de máquina para máquina, sem Desktop no meio, registre um peer (hermes peer, abaixo) — as duas rotas convivem.

DMs iniciados por bots entre máquinas (hermes peer)

Bots em uma máquina podem mandar mensagem a Bots no gateway de outra máquina sem nenhum desktop no meio. Registre o outro gateway como um peer (a URL do servidor de API dele + a API_SERVER_KEY):

hermes peer add spark --url http://spark.lan:8377 --key <API_SERVER_KEY>
hermes peer list
hermes peer dm spark < /tmp/dm.txt        # corpo da mensagem vindo de um arquivo (nada interpretado pelo shell)
hermes peer dm spark/researcher < /tmp/dm.txt   # perfil nomeado em um peer multiplexado

O hermes peer dm entrega na Bot Chat canônica do agente remoto pelo servidor de API que o peer já tem, roda um turno de agente lá e imprime a resposta na saída padrão — o gêmeo exato, entre máquinas, do comando local hermes -p <bot> chat.

Uma vez que um peer está registrado, o protocolo de mensagens ensinado a toda Bot Chat (agent.bot_mode_protocol) passa a incluir automaticamente o elenco de peers, e o message_agent aceita destinos de peer direto — message_agent(target="spark/researcher", …), ou target="spark" para o agente principal do peer — então os seus bots aprendem sozinhos que há colegas em outras máquinas e como alcançá-los. Registrar ou remover um peer atualiza o protocolo de cada Bot Chat na próxima mensagem dela (época de capacidade).

Requisitos: a máquina do peer roda a plataforma de gateway api_server com uma API_SERVER_KEY forte; a alcançabilidade é problema da sua rede (LAN, Tailscale, VPN). A chave é uma credencial e mora em ~/.hermes/.env como HERMES_PEER_<NAME>_KEY; nomes e URLs de peer moram no config.yaml, em bot_peers.

Bots entre máquinas

Quando você registra vários backends em Settings → Connections — o runtime local, gateways remotos, hosts SSH, instâncias do Hermes Cloud — o elenco mostra os Bots de toda origem conectada, de forma persistente: origens SSH são inventariadas sem disparar nada na máquina remota, e máquinas momentaneamente inalcançáveis mantêm as últimas linhas conhecidas em vez de sumir. Quando o mesmo nome de perfil existe em várias origens, os identificadores desambiguam como @name-device (por exemplo, @research-homelab). As conversas, sessões, memória e rotinas de um Bot moram na máquina dona do perfil.

Clicar em um Bot de Conexões não pula a sua janela para aquela máquina — fique na sua conversa e faça @mention nele, sente-o em uma conversa de grupo, ou crie agentes novos nele direto com o seletor Create on. Agentes na nuvem e locais dividem um elenco só assim: registre a sua instância do Hermes Cloud e o seu desktop (digamos, por Tailscale ou SSH) e os Bots deles podem mandar mensagem uns aos outros e sentar nas mesmas salas, com o trabalho de cada agente rodando na máquina dele. DMs entre bots por essas máquinas passam pelo relay do Desktop automaticamente (veja Mensagens entre máquinas conectadas, acima).

Veja Conectar o Desktop a Muitas Instâncias do Hermes para o guia completo de várias conexões.

Desligar

O Bot Mode é um plugin de desktop empacotado. Desligue-o em Settings → Plugins → Bots — o elenco, o painel Routines e o middleware do compositor se desregistram ao vivo, sem precisar reiniciar. Os seus perfis, sessões e jobs de cron ficam intocados de todo jeito; o Bot Mode nunca é dono dos seus dados, ele só os desenha.

Há também uma preferência para esconder as Bot Chats canônicas da lista de sessões da barra lateral comum, de modo que elas apareçam só dentro do painel Bots. (Isso usa a flag de sessão escondida do núcleo; em gateways mais antigos, as conversas simplesmente continuam visíveis.)

Paridade com a CLI

Como os Bots são perfis, tudo tem um equivalente no terminal:

No Bot Mode	Em um shell
Conversar com um Bot	hermes -p <bot> chat
Arquivos, skills e memória de um Bot	~/.hermes/profiles/<bot>/
Rotinas	hermes cron list (jobs chamados [bot:<name>] …)
Criar / inspecionar perfis	hermes profile create, hermes profile list

Veja Perfis para o primitivo por baixo e Comandos de Perfil para a referência completa da CLI.

---