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
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.
- Nov 21, 2026A 16 GB Mac mini instead of a paid API: Qwen analyzes food photos in 20–40 seconds
- Nov 21, 2026Anthropic Heads to IPO on November 19 at a Valuation of Up to $1.45 Trillion, Revenue Up 13x
- Nov 21, 2026AWS and NVIDIA show how to split a coding agent's requests between Claude Opus 5.5 and Nemotron
- Nov 21, 2026Back-of-the-envelope math: splitting tasks across models cuts a contact center's bill from 207,000 ₽ to 23,000 ₽
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.
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.
The AI world, distilled — once a week
Seven stories that actually mattered, hand-picked. No noise, no reposts, no press releases.
Done! Check your inbox for a confirmation.