Free Intensive Nov 21–22Free 2-day hands-on Vibecoding Intensive on Nov 21–22 at 16:00 MSK (Sat–Sun) · Live Cohort 3 starts Nov 23Join Free →Cohort 3 (Nov 23)
ReleaseCode / SDK · ActionableHabr AI→ original

AcpGram Lets You Control Claude Code, Codex, and Gemini CLI Directly from Telegram

Claude Code, Codex, and Gemini CLI are AI coding assistants that only run in the terminal: you start a task and then have to sit next to it. AcpGram is a free Telegram bot that runs them on your server and turns the work into a chat. A task's progress appears in a single message, and you approve file edits or command runs with a button on your phone. That way, you can leave the agent working at home.

AI-processed from Habr AI; edited by Hamidun News
AcpGram Lets You Control Claude Code, Codex, and Gemini CLI Directly from Telegram
Source: Habr AI. Collage: Hamidun News.
Listen to article
Article Fact Sheet & Key Figures
ParameterDetails
Primary sourceHabr AI ↗
Editor-in-Chief
Key metric #1Works with Gemini CLI, Claude Code, Codex, and Antigravity CLI
Four access levels for teamsRead, Normal, Full, Admin
Key metric #3Node.js 24 with no npm dependencies, sessions stored in SQLite, MIT license

Claude Code, Codex, Gemini CLI, and Antigravity CLI are AI agents for programmers: they read the repository, edit files, and run commands on their own. All of them run in the terminal, which is inconvenient. You start a task, and then either sit at the monitor or walk away and have no idea whether the agent is stuck on the question "may I run this command?"

Developer selesnow has released AcpGram, an open gateway that moves control of these agents into Telegram. The agent keeps running on your home or work server, and you monitor it and press buttons in a chat on your phone. The name comes from ACP (Agent Client Protocol), which the whole project is built on.

How It Works: One Protocol Instead of Four Interfaces

ACP is a way for a program and an agent to exchange messages in JSON-RPC format over standard input-output streams. AcpGram launches the console agent as a subprocess on your machine and communicates with it over this protocol, while presenting a familiar chat interface to the user.

Four engines are supported. Gemini CLI (gemini --acp) and Antigravity CLI (agy acp) understand ACP out of the box. For Claude Code and OpenAI Codex, the author uses separate lightweight ACP bridges, claude-agent-acp and codex-acp. For the user, the difference is hidden: switching projects, sessions, and granting permissions work the same way, and you can change engines with the /engine command. The model and reasoning level are selected via /model, and the choice is remembered separately for each user and engine.

The project itself is written in plain Node.js 24 with not a single npm dependency and runs on Windows, Linux, and macOS. From an engineering standpoint, this is a plus: there is a smaller supply chain to vet, and less chance that a service with access to your code breaks because of someone else's update.

What You See in the Chat and How to Control the Agent

While the agent works, its replies, its "thoughts," and its list of steps (reading files, running commands, searching, edits) update in a single draft message rather than arriving as dozens of separate messages. The execution time is shown there too. If the agent gets stuck in a loop, /stop halts it.

When it finishes, a structured report arrives with headings, lists, tables, and syntax-highlighted code. Beneath it is a collapsible log of steps. The footer lists the engine, model, reasoning level, tokens, and time, and for Claude Code also the actual cost of the request. For anyone tracking token spend, this is a useful detail: you can see what a specific task cost, right in the conversation.

When the agent wants to modify a file or run a shell script, the bot sends inline buttons: "Allow," "Allow for this session," or "Deny." According to the author, the system filters out any options that would raise the session above the current user's permissions.

A multi-user mode is available for teams. Colleagues are invited with one-time links (/invite), and an administrator sets the access level: Read, Normal, Full, or Admin. The admin also assigns the permitted engines and models and monitors active users (/users, /active). The levels change how autonomous the agent is, from safe code analysis to automatically applying edits without confirmation. Sessions, requests, tool calls, and tokens are written to a built-in SQLite database (node:sqlite), so you can bring back history with /sessions even after the bot restarts. A side effect is a ready-made audit log.

Installation and Limitations

Installation takes a single command. On Windows it is the PowerShell script install.ps1; on Linux and macOS it is install.sh. According to the author, the installer verifies checksums and, if needed, downloads an isolated Node.js 24 binary without administrator rights. It then adds acpgram to the PATH and launches the acpgram setup wizard, which checks the bot token, picks up your Telegram ID as the administrator, and helps you enter API keys.

To keep the bot running through reboots, you install it as a service with npm run service:install: NSSM on Windows, systemd --user on Linux, and launchd on macOS. A Docker Compose option is also available. There, the agents see only the mounted projects folder (PROJECTS_DIR), while sessions and settings live in persistent volumes. If you let the agent run commands on a server, the container limits possible damage.

Caveats are needed. This is a personal project by a single author, which, in his words, has grown into a "fairly mature" tool. The material contains no independent reviews or security audit. The bot gets access to your code and your shell, so the Full and Admin levels should be granted carefully. Store the bot token and the administrator ID as secrets. In addition, each engine requires its own authentication: a Gemini key, an Anthropic key or subscription, Google account sign-in for Antigravity, and a token for Codex. Tokens and subscriptions remain on your side.

The practical takeaway: if you already run agents on a dedicated machine or VPS, AcpGram lets you avoid keeping a terminal open and avoid missing confirmation requests. The code is open under the MIT license, so you can read it, audit it, and adapt it for your team.

Story

Key Questions Answered

How It Works: One Protocol Instead of Four Interfaces?

ACP is a way for a program and an agent to exchange messages in JSON-RPC format over standard input-output streams. AcpGram launches the console agent as a subprocess on your machine and communicates with it over this protocol, while presenting a familiar chat interface to the user. Four engines are supported. Gemini CLI (gemini --acp) and Antigravity CLI (agy acp) understand ACP out of the box. For Claude Code and OpenAI Codex, the author uses separate lightweight ACP bridges, claude-agent-acp and codex-acp.

What You See in the Chat and How to Control the Agent?

While the agent works, its replies, its "thoughts," and its list of steps (reading files, running commands, searching, edits) update in a single draft message rather than arriving as dozens of separate messages. The execution time is shown there too. If the agent gets stuck in a loop, /stop halts it. When it finishes, a structured report arrives with headings, lists, tables, and syntax-highlighted code. Beneath it is a collapsible log of steps.

What are the key details on Installation and Limitations?

Installation takes a single command. On Windows it is the PowerShell script install.ps1; on Linux and macOS it is install.sh. According to the author, the installer verifies checksums and, if needed, downloads an isolated Node.js 24 binary without administrator rights. It then adds acpgram to the PATH and launches the acpgram setup wizard, which checks the bot token, picks up your Telegram ID as the administrator, and helps you enter API keys.

ZK
Zhemal Khamidun — CPO at Alpina Digital, product manager of AlpinaGPT. Building AI products since 2019. Hamidun News is a pet project that grew into a production aggregator with 6,000+ readers.
✦ 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
What do you think?
Loading comments…