buzz-cli e harness ACP: como o Buzz conversa com Claude Code, Codex e Goose?

Fala aí, beleza? A Block soltou o Buzz e a primeira pergunta de quem já tem um agente rodando no terminal é sempre a mesma: dá pra plugar o meu ali dentro?

A resposta curta é sim, e ela passa por duas peças diferentes que costumam ser confundidas

Uma é o buzz-cli, a interface de linha de comando pensada pra ser usada por agente, não por humano

A outra é o buzz-acp, o harness que faz a ponte entre o canal e o agente que você já usa (o Claude Code que você já paga, e cujo preço em reais a gente já destrinchou, entra aqui também)

Bora entender cada uma delas =)

O que é o Buzz e por que ele trata agente como membro

O Buzz é uma plataforma de comunicação open source da Block, a empresa do Jack Dorsey

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

Lançamento público em 21/07/2026, código aberto em github.com/block/buzz sob licença Apache 2.0, e construído em cima do protocolo Nostr

Até aí parece só mais um chat, né? A diferença mora na identidade

No Buzz não existe aquela conta centralizada com login e senha: cada participante recebe um par de chaves criptográficas próprio

E aqui vem o pulo do gato: isso vale pra humano E pra agente

O agente não é um bot pendurado na sua conta, ele é membro de primeira classe, com identidade própria e trilha de auditoria própria

Se você conhece assinatura de commit com GPG, a ideia de aproximação é essa: dá pra saber exatamente QUEM escreveu aquilo, e o agente responde pela chave dele, não pela sua

Como compilar e autenticar o buzz-cli

O caminho verificado hoje é compilar do fonte com Rust

1. Clone o repositório block/buzz e compile a crate em modo release:

cargo build --release

O binário resultante NÃO se chama buzz-cli, ele se chama buzz, e sai em ./target/release/buzz

O erro comum deste passo é procurar um executável com o nome da crate e achar que a build falhou

2. Exporte a sua chave privada Nostr na variável de ambiente que a CLI espera:

export BUZZ_PRIVATE_KEY="nsec1..."

É a chave privada mesmo, aquela nsec

O erro comum aqui é o clássico: colar isso num arquivo que vai pro Git

Tome cuidado! Chave privada em repositório é o tipo de coisa que estraga o dia

3. Rode o primeiro comando, e preste atenção na ordem dos argumentos:

buzz --format compact channels list

O --format compact é uma flag GLOBAL, então ela precisa vir ANTES do subcomando

O erro comum deste passo é escrever buzz channels list --format compact e não entender por que a flag não pegou

buzz-cli: por que JSON na saída muda o jogo pro agente

CLI normal é feita pra você ler

Coluna alinhada, cor no terminal, um "✓ done" bonitinho no final

O problema é que isso é um inferno pra um LLM: ele precisa interpretar texto humano e adivinhar se deu certo

O buzz-cli inverte a lógica: a resposta sai pronta pra máquina, não pro olho

Toda saída é JSON no stdout, e os erros saem em JSON no stderr

Ou seja, os dois canais não se misturam: dado vai num cano, erro vai no outro, ambos estruturados

Os códigos de saída como regra de decisão

Essa parte é MUITO massa e passa batido pra maioria

O buzz-cli define códigos de saída específicos, então o agente decide o que fazer sem ler uma linha de texto:

• 0 deu certo
• 1 erro do usuário
• 2 rede
• 3 auth
• 4 outro
• 5 conflito de escrita

Se liga no que isso permite: código 2 o agente pode tentar de novo, porque é rede

Código 3 não adianta insistir, é autenticação, tem coisa errada na chave

Código 5 é conflito de escrita, alguém mexeu antes, então a decisão é reler o estado e refazer

É decisão determinística em cima de um número, não achismo em cima de string

E a superfície MCP?

O buzz também expõe MCP, e a pergunta óbvia é se a CLI é redundante

Não é: a CLI espelha a superfície MCP e ainda estende ela

Além das mesmas primitivas, a CLI cobre operações de repo, upload e canvas, onde ela é a interface canônica

Como o buzz-acp conecta o seu agente ao canal

Agora a segunda peça

O buzz-acp é um harness ACP que vive dentro do próprio repositório do Buzz, como crate Rust em crates/buzz-acp

O fluxo completo é bem direto:

relay → menção com @ → prompt disparado no agente → resposta via buzz-cli

Traduzindo: o harness fica escutando o relay, alguém marca o agente com @ num canal, ele dispara aquilo como prompt pro agente local, e o agente responde usando o buzz-cli

O transporte: WebSocket de um lado, stdio do outro

São dois mundos diferentes conversando

Com o relay, o buzz-acp fala por WebSocket, com autenticação NIP-42

Com o agente local, ele fala por stdio, o velho stdin/stdout

É por isso que qualquer agente que fale ACP por stdio serve: o harness não precisa saber nada sobre o agente além de como escrever na entrada dele

A configuração

A configuração é por variável de ambiente, e cada variável tem uma flag de linha de comando equivalente

export BUZZ_ACP_AGENT_COMMAND="goose"
export BUZZ_ACP_AGENT_ARGS='-c,key="value"'

O BUZZ_ACP_AGENT_COMMAND (equivalente a --agent-command) aponta pro binário do agente

O BUZZ_ACP_AGENT_ARGS passa os argumentos separados por VÍRGULA, e não por espaço

O erro comum aqui é separar por espaço como você faria no shell normal

E tem um ponto de atenção que economiza uma hora de debug: BUZZ_RELAY_URL, BUZZ_PRIVATE_KEY e BUZZ_AUTH_TAG são injetadas automaticamente pelo buzz-acp no subprocesso do agente que ele gerencia

Você não precisa exportar essas três de novo pro agente, o harness faz isso

Claude Code, Codex e Goose no Buzz: o que muda em cada um

O denominador comum é o ACP, o Agent Client Protocol: JSON-RPC 2.0 rodando sobre stdin/stdout, criado pela Zed Industries e lançado em agosto de 2025, com a spec em agentclientprotocol.com

O que muda de agente pra agente é só quanto de adaptador você precisa no meio:

O Goose é o caminho mais curto por motivo óbvio: mesma casa

No Claude Code, a instalação do adaptador é o npm de sempre:

npm i @agentclientprotocol/claude-agent-acp

Atenção no nome do pacote: se você seguir tutorial antigo vai acabar no @zed-industries/..., que foi renomeado e está deprecated

No Codex, dá pra rodar sem instalar nada permanente:

CODEX_PATH=/caminho/para/codex npx -y @agentclientprotocol/codex-acp

E se a sua dúvida ainda é qual desses dois usar no dia a dia antes mesmo de plugar no Buzz, isso é outro papo: já rolou por aqui uma comparação entre Codex e Claude Code para programar

Vale plugar hoje? Limites conhecidos do buzz-acp e do buzz-cli

Agora a parte honesta, porque nem tudo que aparece em thread de lançamento já existe

O Cursor como runtime ACP de primeira classe no Buzz é issue ABERTA (a #2535), não é recurso entregue

Se você esperava plugar o Cursor hoje, ainda não é hoje

Tem também uma limitação reconhecida no buzz-acp: um servidor MCP por agente

A issue #2899 descreve o incômodo bem direto: isso força escolher entre o shell e qualquer servidor de domínio

Ou você dá o shell pro agente, ou dá o servidor MCP específico do seu contexto, não os dois

Dependendo do que você quer montar, isso pesa

E no buzz-cli, a saída em tabela é proposta na issue #2672, ainda não é recurso

O padrão continua sendo JSON, o que faz total sentido pro agente e é chatinho pra você ler no olho

Nada disso tem prazo, e eu não vou chutar nenhum: são issues abertas, ponto

Conclusão

No fim, dá pra guardar o post inteiro em duas frases

O buzz-cli é a BOCA do agente: JSON no stdout, erro em JSON no stderr, código de saída dizendo o que fazer

O buzz-acp é a PONTE: escuta a menção no canal, dispara o prompt no agente local por stdio e deixa a resposta voltar pela CLI

Quem já usa Goose, Claude Code ou Codex não precisa trocar de agente, precisa só falar ACP

O próximo passo concreto é bem curto: clona o block/buzz, roda o cargo build --release, exporta a BUZZ_PRIVATE_KEY e aponta o BUZZ_ACP_AGENT_COMMAND pro agente que já tá instalado na tua máquina

Depois é só marcar ele com @ num canal e ver a coisa acontecer 😀

até o próximo post!