Intensivo Grátis 21–22/11Intensivo gratuito de 2 dias em Vibecoding (21–22/11 às 16:00 MSK) · Turma 3 começa 23/11Inscrever-se grátis →Turma 3 (23/11)
LançamentoCódigo / SDK · Pronto p/ usoHabr AI→ original

AcpGram permite controlar Claude Code, Codex e Gemini CLI diretamente pelo Telegram

Claude Code, Codex e Gemini CLI são assistentes de IA para programadores que funcionam apenas no terminal: você inicia a tarefa e precisa ficar ao lado da máquina. O AcpGram é um bot gratuito do Telegram que executa esses agentes no seu servidor e transforma o trabalho em uma conversa de chat. O andamento da tarefa aparece em uma única mensagem, e a edição de arquivos ou a execução de comandos são confirmadas por um botão no smartphone. Assim, é possível deixar o agente trabalhando enquanto você está em casa.

Processado por IA de Habr AI; editado por Hamidun News
AcpGram permite controlar Claude Code, Codex e Gemini CLI diretamente pelo Telegram
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
Dado-chave #1Funciona com Gemini CLI, Claude Code, Codex e Antigravity CLI
Quatro níveis de acesso para a equipeRead, Normal, Full e Admin
Dado-chave #3Node.js 24 sem dependências do npm, sessões em SQLite, licença MIT

Claude Code, Codex, Gemini CLI e Antigravity CLI são agentes de IA para programadores: eles leem o repositório, editam arquivos e executam comandos por conta própria. Todos funcionam no terminal, e isso é incômodo. Você inicia a tarefa e, depois, precisa ficar em frente ao monitor ou sair sem saber se o agente não travou em uma pergunta do tipo "posso executar este comando?"

O desenvolvedor com o apelido selesnow publicou o AcpGram, um gateway de código aberto que leva o controle desses agentes para o Telegram. O agente continua rodando no seu servidor doméstico ou de trabalho, e você acompanha o andamento e clica nos botões pelo chat no smartphone. O nome vem do protocolo ACP (Agent Client Protocol), na base de todo o projeto.

Como funciona: um protocolo no lugar de quatro interfaces

O ACP é uma forma de troca de mensagens entre um programa e um agente, no formato JSON-RPC, por meio dos fluxos padrão de entrada e saída. O AcpGram inicia o agente de console como subprocesso na sua máquina, comunica-se com ele por esse protocolo e exibe para você um chat familiar.

São suportados quatro mecanismos. O Gemini CLI (gemini --acp) e o Antigravity CLI (agy acp) entendem ACP de fábrica. Para Claude Code e OpenAI Codex, o autor usa pontes ACP leves separadas: claude-agent-acp e codex-acp. Para o usuário, a diferença fica oculta: trocar projetos, sessões e conceder permissões funciona da mesma forma, e o mecanismo pode ser alterado com o comando /engine. O modelo e o nível de raciocínio são escolhidos com /model, e a escolha é lembrada separadamente para cada usuário e cada mecanismo.

O projeto em si é escrito em Node.js 24 puro, sem uma única dependência do npm, e roda no Windows, no Linux e no macOS. Do ponto de vista de engenharia, isso é um ponto a favor: a cadeia de suprimentos é menor e há menos chance de um serviço com acesso ao seu código quebrar por causa de uma atualização de terceiros.

O que aparece no chat e como controlar o agente

Enquanto o agente trabalha, suas respostas, seus "pensamentos" e a lista de etapas (leitura de arquivos, execução de comandos, buscas, edições) são atualizados em um único rascunho de mensagem, e não em dezenas de respostas separadas. Ali também aparece o tempo de execução. Se o agente entrar em loop, o comando /stop o interrompe.

Ao final, chega um relatório estruturado, com títulos, listas, tabelas e destaque de código. Abaixo dele fica um registro retrátil das etapas. No rodapé são indicados o mecanismo, o modelo, o nível de raciocínio, os tokens e o tempo; no caso do Claude Code, também o custo real da requisição. Para quem acompanha os gastos com tokens, esse detalhe é útil: é possível ver quanto custou uma tarefa específica diretamente na conversa.

Quando o agente quer alterar um arquivo ou executar um script de shell, o bot envia botões inline: "Permitir", "Permitir nesta sessão" ou "Recusar". Segundo o autor, o sistema descarta opções que elevariam a sessão acima dos direitos do usuário atual.

Para comandos, há um modo multiusuário. Colegas são convidados por links de uso único (/invite), e o administrador define o nível de acesso: Read, Normal, Full ou Admin. Ele também atribui os mecanismos e modelos permitidos e acompanha os usuários ativos (/users, /active). Os níveis alteram a autonomia do agente: desde a análise segura do código até a aplicação automática de edições sem confirmações. Sessões, requisições, chamadas de ferramentas e tokens são gravados em um banco SQLite embutido (node:sqlite), por isso o histórico pode ser recuperado com /sessions mesmo após o bot ser reiniciado. Como efeito colateral, o projeto já traz um log de auditoria pronto.

Instalação e limitações

A instalação é feita com um único comando. No Windows, trata-se do script PowerShell install.ps1; no Linux e no macOS, do install.sh. Segundo o autor, o instalador verifica somas de controle e, se necessário, baixa um binário isolado do Node.js 24 sem privilégios de administrador. Em seguida, ele adiciona acpgram ao PATH e inicia o assistente acpgram setup, que verifica o token do bot, usa o seu ID do Telegram como administrador e ajuda a configurar as chaves de API.

Para que o bot sobreviva a reinicializações, ele é instalado como serviço com npm run service:install: no Windows é usado o NSSM, no Linux, o systemd --user, e no macOS, o launchd. Também há a opção com Docker Compose. Nela, os agentes enxergam apenas a pasta de projetos montada (PROJECTS_DIR), e sessões e configurações ficam em volumes persistentes. Se você permitir que o agente execute comandos no servidor, o contêiner limita o possível dano.

Algumas ressalvas são necessárias. Trata-se de um projeto pessoal de um único autor que, segundo ele, cresceu até se tornar uma ferramenta "bastante madura". O material não traz avaliações independentes nem auditoria de segurança. O bot tem acesso ao seu código e à shell de comandos, por isso os níveis Full e Admin devem ser concedidos com cautela. O token do bot e o ID do administrador devem ser guardados como segredos. Além disso, cada mecanismo exige autenticação própria: chave do Gemini, chave da Anthropic ou assinatura, login com conta Google para o Antigravity, token para o Codex. Tokens e assinaturas permanecem sob o seu controle.

A conclusão prática: se você já executa agentes em uma máquina dedicada ou em um VPS, o AcpGram permite não manter o terminal aberto e não perder pedidos de confirmação. O código está sob licença MIT, então pode ser lido, verificado e adaptado à sua equipe.

História

Perguntas frequentes sobre a notícia

Como funciona: um protocolo no lugar de quatro interfaces?

O ACP é uma forma de troca de mensagens entre um programa e um agente, no formato JSON-RPC, por meio dos fluxos padrão de entrada e saída. O AcpGram inicia o agente de console como subprocesso na sua máquina, comunica-se com ele por esse protocolo e exibe para você um chat familiar. São suportados quatro mecanismos. O Gemini CLI (gemini --acp) e o Antigravity CLI (agy acp) entendem ACP de fábrica. Para Claude Code e OpenAI Codex, o autor usa pontes ACP leves separadas: claude-agent-acp e codex-acp.

O que aparece no chat e como controlar o agente?

Enquanto o agente trabalha, suas respostas, seus "pensamentos" e a lista de etapas (leitura de arquivos, execução de comandos, buscas, edições) são atualizados em um único rascunho de mensagem, e não em dezenas de respostas separadas. Ali também aparece o tempo de execução. Se o agente entrar em loop, o comando /stop o interrompe. Ao final, chega um relatório estruturado, com títulos, listas, tabelas e destaque de código. Abaixo dele fica um registro retrátil das etapas.

O que se sabe sobre Instalação e limitações?

A instalação é feita com um único comando. No Windows, trata-se do script PowerShell install.ps1; no Linux e no macOS, do install.sh. Segundo o autor, o instalador verifica somas de controle e, se necessário, baixa um binário isolado do Node.js 24 sem privilégios de administrador. Em seguida, ele adiciona acpgram ao PATH e inicia o assistente acpgram setup, que verifica o token do bot, usa o seu ID do Telegram como administrador e ajuda a configurar as chaves de API.

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ Hands-On AI Engineering · Hamidun Academy

Build & Ship Production AI Agents Without Boilerplate Code

Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.

Start 72h Free Trial →Vibe-Coding Intensive
O que você acha?
Carregando comentários…