Последние месяцы я всё чаще работаю с ИИ-агентами для кодинга: 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 «под капотом» уживаются четыре экосистемы:
-
Gemini CLI (
gemini --acp) — требуетGEMINI_API_KEYили авторизации через логин. -
Claude Code (
claude-agent-acp) — работает через Anthropic API ключ или подписку. -
Antigravity CLI (
agy acp) — фирменный движок, авторизуется через разовый вход по Google-аккаунту без необходимости держать браузер на сервере. -
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 | iexLinux / 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!
Источник: habr.com