AI Control — это локальный Telegram‑пульт, позволяющий управлять тремя популярными CLI‑агентами (Codex, Claude Code и Cursor) из любого места без открытия входящих портов и без отдельного серверного компонента.
Традиционный способ работы с AI‑ассистентами в терминале удобен, пока экран находится перед глазами. При удалённом доступе приходится использовать SSH‑клиенты на телефоне или ждать, когда агент запросит подтверждение. AI Control решает эту задачу, предоставляя единый Telegram‑интерфейс, где пользователь выбирает проект, агента, модель и место запуска (текущий checkout или отдельный Git worktree).
Бот работает на том же хосте, где находятся репозитории. Он получает обновления от Telegram через long‑polling, поэтому не требуется открывать публичные порты. Все исходники, базы SQLite и сессии хранятся локально, а передача текста и файлов происходит только через инфраструктуру Telegram без сквозного шифрования.
### Архитектура и процесс взаимодействия
1. Пользователь в чате выбирает проект, тип агента и модель.
2. Бот формирует задачу и отправляет её выбранному CLI‑агенту.
3. Агент исполняет шаги (чтение кода, редактирование, запуск тестов) и сообщает о каждом этапе через свой протокол.
4. При необходимости появляется запрос на подтверждение действия – пользователь отвечает в Telegram, после чего агент продолжает работу.
5. По завершении задачи бот отправляет короткий итог в виде карточки и, при желании, полный ответ в отдельном сообщении или файле.
### Три разных протокола
• **Codex** — взаимодействие через `codex app-server` по JSON‑RPC. Управляющие сообщения: `initialize`, `thread/start`, `turn/start`, `turn/interrupt`. Состояние этапов читается из событий `item/started` / `item/completed`, финальный ответ приходит в сообщении с фазой `final_answer`.
• **Claude Code** — двунаправленный поток JSON Lines (`--input-format=stream-json`, `--output-format=stream-json`). В тот же поток попадают запросы на разрешения и ответы на них. Если CLI‑версия не поддерживает потоковый режим, это отображается в `doctor`‑сообщении.
• **Cursor Agent** — поверх JSON‑RPC использует ACP (Agent Control Protocol) через stdio. Сессия сохраняется и может быть продолжена последующим сообщением.
### Два уровня контроля доступа
Для каждой задачи в `config.yaml` задаётся режим доступа к файловой системе:
- `read_only` — без записи;
- `project_only` — запись только внутри корня проекта (символьные ссылки разрешены только после подтверждения);
- `approved_paths` — проект + явно перечисленные каталоги;
- `full_access` — обычные права пользователя ОС (может быть задан только локально).
Режим хранится в отдельной таблице SQLite и привязывается к задаче. Переключить уже запущенную задачу из `full_access` в более ограниченный режим невозможно – необходимо создать новую задачу.
### Обработка запросов разрешения
В ручном режиме запрос привязывается к пользователю, задаче и идентификатору действия. После отправки ответа адаптер удаляет его из памяти, поэтому повторное нажатие кнопки не приводит к повторному разрешению. Кнопки «разрешить всё» в интерфейсе нет.
В автоматическом режиме Codex и Cursor получают параметры CLI без вмешательства, а адаптеры обрабатывают структурированные запросы. Для Claude Code адаптер проверяет собственную политику и принимает решение. Любой запрос, выходящий за пределы разрешённых путей, отклоняется и фиксируется в аудит‑логах.
### Worktree и управление процессами
Для каждой задачи создаётся отдельный Git worktree. Автоочистка не производится, чтобы не потерять незакоммиченные изменения – пользователь сам решает, объединять ветку или удалять её вручную.
Запуск дочерних процессов происходит без оболочки: в Unix процесс получает новую сессию и завершается вместе с группой, в Windows — создаётся отдельная группа процессов, завершаемая `taskkill /T`. Для WSL используется обёртка `wsl.exe` с указанием дистрибутива и каталога.
### Безопасность и хранение токенов
Токен Telegram‑бота берётся из переменной окружения, системного хранилища учётных данных или закрытого `secrets.json` в каталоге данных – он не попадает в SQLite‑файл. Журналы ротируются и маскируют потенциально чувствительные строки (токены, пароли, PEM‑ключи).
Важно помнить, что Telegram‑бот не использует сквозное шифрование, поэтому передавать пароли, ключи или профили браузера в чат не рекомендуется.
### Ограничения и сценарии использования
• После сбоя задача не привязывается к старому процессу – запускается новый процесс по сохранённому ID сессии.
• Вложения, отправленные во время активного шага, не добавляются автоматически в промпт.
• На Windows `taskkill /T` надёжно завершает обычные дочерние процессы, но не охватывает процессы, покинувшие группу; в планах – поддержка Job Object.
• Лимиты использования Claude Code и Cursor видны только через их собственные API; для Codex лимиты получаются через `/usage` у `app-server`.
### Итоги и дальнейшие шаги
AI Control доказал свою пригодность для личных репозиториев: задачи можно запускать и контролировать с телефона, изменения распределяются по отдельным worktree, а запросы подтверждения не требуют постоянного присутствия у терминала. Проект находится в репозитории [GitHub](https://github.com/Mi-Mih/ai_control) и готов к использованию в одиночных сценариях.
Если вы хотите обсудить внедрение подобного решения в ваш бизнес‑процесс или разобраться с интеграцией в существующую инфраструктуру, напишите нам. Мы поможем подобрать оптимальную архитектуру и настроить безопасный Telegram‑контроль для ваших AI‑агентов.