Последние месяцы я всё чаще работаю с ИИ‑агентами для кодинга: Gemini CLI, Claude Code, Codex и Antigravity. Они невероятно хороши в решении сложных задач, но у них есть одно фундаментальное неудобство — они привязаны к терминалу. Запустил задачу, сидишь жди, а отойти от монитора или проверить код со смартфона, находясь в дороге, до недавнего времени было проблематично.

Хотелось получить ту же свободу, что дает расширение Claude Code для VS Code, но прямо в мессенджере — чтобы агент шуршал по кодовой базе на домашнем или рабочем сервере, пока я занимаюсь своими делами, а я мог в любой момент глянуть прогресс или одобрить критический шаг.

Так родился AcpGram — открытый Telegram‑шлюз, который запускает консольных агентов в качестве подпроцессов и позволяет управлять ими через привычный чат. Проект написан на чистом Node.js 24 без единой npm‑зависимости, работает на Windows, Linux и macOS и уже полностью готов к использованию.

Архитектура: почему именно ACP?

В основе проекта лежит Agent Client Protocol (ACP) — протокол взаимодействия на базе JSON‑RPC поверх стандартных потоков ввода‑вывода (stdin/stdout).

Поскольку разные вендоры поставляют свои CLI‑утилиты по‑разному (Gemini и Antigravity поддерживают ACP «из коробки», а для Claude Code и OpenAI Codex написаны специальные легкие ACP‑мосты), AcpGram предоставляет единый унифицированный интерфейс для абсолютно разных движков.

Вам не нужно переучиваться под синтаксис каждого инструмента: логика работы, переключение проектов, сессий и выдача разрешений везде устроена одинаково.

Главные фичи, которые делают работу комфортной

  • Интерактивный стриминг в черновик (Draft): Забыли про бесконечные портянки сообщений. Ответы агента, его «мысли», список выполняемых шагов (чтение файлов, запуск команд, поиск, правки) и затраченное время обновляются в реальном времени прямо в черновике сообщения Telegram. Если агент зациклился — есть удобная кнопка остановки (/stop).

  • Богатый финальный ответ и Work Log: По окончании работы вы получаете структурированный отчет с заголовками, списками, таблицами и подсветкой кода. Под ним прячется сворачиваемый лог шагов, а в футере отображается служебная информация: движок, модель, уровень рассуждений, токены, реальная стоимость (для Claude Code) и время выполнения.

  • Интерактивные разрешения (Permissions): Когда агент хочет изменить файл или выполнить шел‑скрипт, бот присылает инлайн‑кнопки: «Разрешить», «Разрешить на эту сессию» или «Отклонить». При этом система безопасности умно отсекает опасные опции, не позволяя поднять сессию выше прав текущего пользователя.

  • Многопользовательский режим (Team access): Вы можете пригласить в бота коллег через одноразовые ссылки. Главный админ управляет уровнями доступа (от режима «Только чтение» до полного автопилота), назначает разрешенные движки и модели, а также видит активных пользователей.

  • Аудит и персистентность: Все сессии, запросы, вызовы инструментов и токены пишутся во встроенную SQLite‑базу (node:sqlite). Сессию можно в любой момент возобновить командой /sessions даже после перезагрузки бота.

Поддерживаемые движки и уровни доступа

В AcpGram «под капотом» уживаются четыре экосистемы:

  1. Gemini CLI (gemini --acp) — требует GEMINI_API_KEY или авторизации через логин.

  2. Claude Code (claude-agent-acp) — работает через Anthropic API ключ или подписку.

  3. Antigravity CLI (agy acp) — фирменный движок, авторизуется через разовый вход по Google‑аккаунту без необходимости держать браузер на сервере.

  4. OpenAI Codex (codex-acp) — через официальный CLI и токен.

В зависимости от выданного уровня доступа (Read, Normal, Full, Admin), бот на лету регулирует автономность агента: от безопасного анализа кода до автоматического применения правок без подтверждений.

Полный арсенал команд бота

Управлять процессом разработки в чате предельно просто:

  • /start — приветственный экран, отображающий текущий движок, модель, уровень доступа и выбранный проект.

  • /project [имя или путь] — выбор рабочей папки (с поддержкой поиска по имени, путей вроде ~/projects/web и быстрого переключения по недавним проектам).

  • /engine [gemini|claude|agy|codex] — переключение между доступными ИИ‑движками.

  • /model — выбор конкретной модели и настройка уровня рассуждений (effort / thought_level); выбор запоминается персонально для каждого пользователя и движка.

  • /new — принудительный сброс и старт новой сессии.

  • /sessions — просмотр и возобновление прошлых диалогов в текущем проекте.

  • /stop — экстренная остановка текущего запроса.

  • /close / /exit — завершение сессии и выгрузка процесса агента из памяти.

  • /users, /active, /invite — административные команды для управления командой, инвайтами и мониторинга активных сессий.

Установка и быстрый старт

Благодаря тому, что проект написан на чистом Node.js 24 и не тащит за собой горы сторонних зависимостей, развертывание занимает ровно одну минуту.

Установка одной командой

Windows (PowerShell):

PowerShell

irm https://raw.githubusercontent.com/selesnow/acpgram/main/install.ps1 | iex

Linux / macOS:

Bash

curl -fsSL https://raw.githubusercontent.com/selesnow/acpgram/main/install.sh | bash

Установщик проверяет контрольные суммы, при необходимости скачивает изолированный официальный бинарник Node.js 24 (права администратора не требуются), добавляет команду acpgram в PATH и запускает интерактивный мастер настройки (acpgram setup), который проверит токен бота через getMe, подхватит ваш Telegram ID как администратора и поможет прописать API‑ключи.

Работа в качестве системной службы

Чтобы бот не падал и поднимался вместе с системой, его можно запустить как фоновый сервис одной командой:

  • Windows: npm run service:install (используется NSSM).

  • Linux: npm run service:install (через systemd --user).

  • macOS: npm run service:install (через launchd).

Вариант с Docker

Если вы предпочитаете контейнеризацию, в репозитории есть готовый docker-compose.up:

Bash

cp .env.example .env     # Укажите TELEGRAM_BOT_TOKEN, ALLOWED_USER_ID и ключи
docker compose up -d --build

В докере агенты изолированно видят только примонтированную директорию проектов (PROJECTS_DIR), а сессии и настройки сохраняются в персистентных томах.

Заключение

AcpGram задумывался как личный инструмент для «убийства рутины» и контроля кодинг‑агентов на лету, но получился вполне зрелым шлюзом, которым удобно пользоваться как в одиночку, так и небольшой командой.

Код полностью открыт, распространяется под лицензией MIT. Посмотреть исходники, изучить тесты и заглянуть вглубь архитектуры можно на GitHub:

🔗 GitHub‑репозиторий AcpGram

Буду рад вашим отзывам, идеям, баг‑репортам и Pull Request'ам. Если проект показался вам полезным — буду признателен за звезду на GitHub!