ai-control

agent
Security Audit
Fail
Health Pass
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 10 GitHub stars
Code Fail
  • rm -rf — Recursive force deletion command in .claude/settings.json
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Autonomous infrastructure over Claude Code: phone-dispatched remote sessions + a fleet of background agents (event spool, budgets, cross-machine handoff, deterministic canon rollout via PRs). Zero-dep, user-level.

README.md

ai-control

Русский · English

shellcheck
license: MIT

Автономная инфраструктура поверх Claude Code: control-плоскость в Telegram, которая (1) раздаёт с телефона удалённые Claude-сессии по всем твоим проектам - включая возврат в любую прошлую сессию по её имени - и (2) держит парк фоновых агентов - с событийной очередью, бюджетами, кросс-машинным handoff, независимой приёмкой результата.

Связанный проект claude-toolkit содержит правила, роли и навыки. Обновление выполняется вручную через SHA-pinned AI sync; harvest сохраняет обратную доставку брифов.

[!NOTE]
Ядро (remote-control) стоит поверх фичи claude remote-control - на момент написания в статусе research preview. Нужен Claude Code CLI ≥ 2.1.51 и логин через Claude-подписку (claude /login); API-ключи Anthropic для remote-control не работают.


Два слоя

Система росла двумя слоями, каждый самодостаточен и ставится одним install.sh.

flowchart TB
    phone["📱 Телефон<br/>(приложение Claude / Telegram)"]

    subgraph host["Хост: macOS (launchd) или Linux VM (systemd --user)"]
      direction TB
      subgraph L1["Слой 1 - сессии из бота"]
        menu["/sessions в Telegram<br/>проекты → сессии по именам"]
        rc["ai-rc up/down/new<br/>транзиентный юнит на сессию"]
        menu --> rc
      end
      subgraph L2["Слой 2 - автономный агентный слой (Linux)"]
        recon["reconciler<br/>event-spool + бюджеты"]
        tgbot["tgbot<br/>дашборд + /new /task /limits"]
        takeover["takeover<br/>Mac → VM handoff"]
        harvest["acceptor + harvester<br/>приёмка + правила ролей"]
      end
    end

    toolkit["claude-toolkit<br/>правила + навыки"]

    phone <--> tgbot
    tgbot --> menu
    rc --> projA["ccsession-&lt;uuid&gt;: сессия A"]
    rc --> projB["ccsession-&lt;uuid&gt;: сессия B"]
  • Слой 1 - сессии из бота (Linux; на macOS доступен CLI, но без транзиентных юнитов). В Telegram /sessions: проекты -> сессии проекта под их собственными именами -> поднять, положить, создать новую. Поднятая сессия живёт транзиентным systemd-юнитом и появляется в приложении Claude Code. Доступ к любому репо и к любой прошлой сессии без SSH и ручного cd.
  • Слой 2 - автономный агентный слой (Linux/systemd на VM). Фоновые агенты под надзором reconciler'а: событийная очередь, контур задач /new с телефона (worktree, карточки, приёмка тапом), бюджеты по запускам, circuit breaker, кросс-машинный takeover, независимая ролевая приёмка, harvester операторских поправок.

Оба слоя - stdlib Python + shell, ноль внешних зависимостей, только пользовательские юниты (никакого sudo, никаких системных сервисов), идемпотентная установка/снос.


Слой 1 - сессии из бота

Claude Code умеет открывать сессию для удалённого управления, к ней подключаешься с телефона. Но сам по себе он этого не закрывает: чтобы попасть в нужный репозиторий, надо физически сесть за машину, cd в проект и запустить claude --remote-control. А чтобы вернуться во вчерашний разговор - ещё и вспомнить, какой именно из десятков это был.

ai-control закрывает оба зазора одним экраном в Telegram:

  • /sessions -> список проектов из ~/.ai-control/projects.yaml;
  • проект -> его сессии под теми же именами, что видны в Cursor (/rename пишет имя в транскрипт, бот читает оттуда же), у поднятых - кружок;
  • тап по сессии -> ▶ поднять / ⏹ положить; отдельной кнопкой - ➕ новая сессия.

Поднятая сессия появляется в приложении Claude Code, и дальше работа идёт там. На хосте она живёт транзиентным systemd-юнитом ccsession-<uuid>: переживает выход вызывающего, получает cgroup и потолок памяти, гасится по имени. Никакой постоянно живущей сессии-диспетчера и никакого tmux в схеме больше нет.

Что это даёт: доступ к любому проекту и к любой прошлой сессии за два тапа, без заранее открытых сессий, с реестром проектов в одном файле. Восстановление прошлой сессии в мост - отдельный трюк: --resume без промпта выходит всегда, а без pty процесс отрабатывает промпт и завершается, не подключившись. Разбор - в контракте этапа.

Как выглядит с телефона:

Ты (в Telegram)  - /sessions
Бот              - [ai-control] [проект 1] [проект 2] ...
Ты               - проект 1
Бот              - ➕ новая сессия
                   ● control-v2      ← поднята
                     сессия 1
                     LLM start
Ты               - сессия 1 -> ▶ поднять
Ты               - открываешь Claude Code, выбираешь "сессия 1" - ты внутри

То же с машины, если бот недоступен:

ai-rc sessions <проект> --porcelain   # uuid, имя, поднята ли
ai-rc up <проект> <uuid>              # поднять
ai-rc new <проект>                    # новая пустая
ai-rc down <uuid>                     # положить
ai-rc live                            # что поднято сейчас
ai-rc reap [--dry-run]                # погасить зомби: юнит жив, а мост снесен

Зомби заводится, когда карточку сессии архивируют в браузере: CLI сносит мост, а
процесс остается жить - сессия выглядит работающей, хотя достучаться до нее уже
нельзя. Руками звать не нужно: жнец висит вторым ExecStart в юните watchdog и
проходит раз в две минуты. Команда пригодится, чтобы посмотреть глазами -
--dry-run только докладывает, ничего не гася.


Слой 2 - автономный агентный слой

Поверх диспетчера - парк фоновых агентов, которые продолжают миссию, когда ты вышел из сессии. Живёт на Linux (нужны transient-юниты и cgroups от systemd --user). Спроектирован по state-machine контракту: у каждого агента разведены spec (что делать), control (armed/budget/latch) и reconciler (кто приводит факт к желаемому).

reconciler + event-spool

Ядро автономии. Durable spool событий (at-least-once с producer-идемпотентностью по update_id), executor в headless-режиме, бюджет по запускам (агент не жжёт бесконечно), fail-closed на неизвестных отказах (событие нельзя терять). Разбор в дизайне этапа 4.

Контур задач V2 - /new с телефона

Поверх spool'а - полный жизненный цикл задачи без открытой сессии: /new <проект> <текст> в Telegram рождает задачу из шаблона со строгим поясом прав (fail-closed: нет валидного шаблона - нет задачи), агент работает в git-worktree проекта и заявляет о готовности; карточка приёмки прилетает в личку, тап "принять" мержит ветку в проект, уборка и архив - автоматически. Одиннадцать этапов V2.0-V2.10, каждый со своим SDD-контрактом и adversarial-аудитом:

  • Scale-to-zero и память. Executor гаснет на пустом inbox, reconciler будит по событию (V2.0); worktree и пояса прав per-agent (V2.1); тред-память задачи переживает прогоны (V2.2).
  • Вопросы и подтверждения - durable-исход прогона, не смерть задачи: агент спрашивает (ai-agent-ask) или упирается в гейт прав, карточка с кнопками уезжает в TG, ответ тапом/reply-ем возвращается ровно один раз (V2.3-V2.6).
  • Приёмка - durable FSM requested -> accepted -> integrated -> cleaned -> archived с фиксацией SHA заявки (V2.7a, V2.7b); расписание как источник событий (V2.8); поправки человека по ходу задачи дистиллируются в правила проекта (V2.9).
  • У агента нет git. Три круга аудита нашли три независимых способа исполнить код агента до человеческой приёмки через git-механизмы (хуки, флаги вроде git log --output=, clean-фильтры, fsmonitor) - глушить их по одному оказалось невыигрываемой гонкой. Git отобран целиком: коммитит рантайм, после заявки о готовности (V2.10).

tgbot - дашборд парка

Long-poll Telegram-бот (getUpdates, не webhook - webhooks режет DPI в ряде сетей). Команды /agents, /agent <name>, /new <проект> <текст> (родить задачу), /task <name> <текст> (событие существующему агенту), /menu и /limits (остатки подписочных лимитов Claude/Codex/Kimi Code); карточки вопросов и приёмки - с inline-кнопками, ответ тапом или reply-ем. Приватные чаты + whitelist по from.id; весь вывод агентов - недоверенные данные, эскейпится и шлётся как <pre>.

takeover - кросс-машинный handoff

Перенос живой миссии Mac -> VM не переносом транскрипта (фундаментально небезопасно - утащил бы чужой контекст), а fresh brief-seeded сессией: новый агент поднимается на VM с самодостаточным брифом от base-commit. Дизайн этапа 5.

acceptor + harvester - приёмка и обратный поток

Acceptor (этап 7) - ролевой судья артефактов в независимом контексте (deterministic / role-review / both), с corpus-runner и confusion-matrix для калибровки. Harvester (этап 7b) - операторские правки (revise/reject) превращаются в кандидаты правил ролей: collect -> propose -> digest -> approve.

limits-digest - дайджест лимитов LLM

Каждые 15 минут снимает остаток подписочных лимитов Claude/Codex/Kimi Code (метаданные квоты, не inference - саму квоту не тратит) и шлёт панель в Telegram только при изменении цифр (дедуп по сигнатуре процентов/статусов, время сброса не считается изменением). Runbook.

Веб-интерфейс задач

Первая версия показывает вопросы и готовые результаты: текстовые ответы, разрешённые approve/reject, повтор доставки сохранённого ответа и принятие либо отклонение результата. Вход защищён паролем и TOTP; web process работает под отдельным UID через узкий owner broker. Установка требует настройки отдельного пользователя, HTTPS и локального enrollment. Расширенное управление парком остаётся следующим этапом.


Резервные копии (опционально)

Модуль ai-control-backup: клиентски-шифрованный дедуплицированный бэкап произвольных путей в два независимых S3-репозитория через restic. Ставится флагом --with-backup (Linux).

  • Клиентское шифрование - провайдер видит только шифртекст, поэтому бэкап можно держать у хостинга, которому не доверяешь plaintext.
  • Два независимых провайдера - два backup (не copy); падение или бан одного не мешает второму, восстановление возможно из любого.
  • Дедуп + zstd-сжатие - на текстовых данных обычно 5-10x экономии.
  • systemd-таймер (ежедневно) + restore-drill - непроверенный бэкап не считается бэкапом.

Пути, URL репозиториев и креды - в ~/.config/ai-control/backup-env (вне git, chmod 600); в скриптах ничего машино-специфичного. Настройка и восстановление - в docs/runbook-backup.md.

Инженерные решения и верификация

Что делает это не "скриптами на коленке":

  • Транзакционная безопасность. Durable event-spool, recovery задач, no-clobber на чужие файлы и containment записи в пределах проекта. Доказывается fault-injection тестами, а не "на бумаге".
  • Автономность с тормозами. Бюджеты по запускам, circuit breaker с durable-защёлкой, kill-switch. Автономный агент не может уйти в разнос молча.
  • Состязательная верификация. Каждый крупный слой проходит несколько раундов adversarial-ревью второй моделью (другой класс ошибок, чем у основного агента); каждая находка закрывается фиксом плюс регресс-тестом. Стек этапов накопил десятки закрытых blocker'ов.
  • Модель угроз явная. Доверенная VM, durable-state наш, канон из нашего git-зеркала; границы (TOCTOU под flock, symlink-родители, secret-handling) отработаны и задокументированы, остаточные риски приняты письменно.
  • Ноль зависимостей, user-level. Только stdlib Python + shell, только пользовательские launchd/systemd-юниты, идемпотентные install/uninstall.

Дизайн-доки по этапам - в docs/; архитектура обоих слоёв (со схемой контура задач V2) - docs/architecture.md.


Требования

  • Linux с systemd --user (Ubuntu 22.04+, Debian 12+) - оба слоя. На macOS доступен CLI (ai-rc sessions/up/down), но держатель сессий - транзиентный systemd-юнит, поэтому подъём сессий там не работает.
  • Claude Code CLI ≥ 2.1.51, залогинен через claude /login (Claude-подписка).
  • yq от mikefarah, v4 - brew install yq (macOS); на Linux бинарник с GitHub releases (пакет yq из apt - другой проект). install.sh проверит версию.
  • Linux: включённый lingering (loginctl enable-linger $USER), иначе user-сервисы гибнут при logout. install.sh проверит и предупредит.

Ручная оценка уровня модели

ai-agent-model-advice --public-text-file ./public-task.txt --task ./docs/task.md — отдельная opt-in команда. Она передает только явно указанный публичный файл доверенному Jev helper, а затем добавляет fenced JSON-квитанцию в Markdown-задачу. Ввод ограничен 4000 символами и 16 KiB. Helper задается абсолютным CONTROL_JEV_HELPER в ~/.config/ai-control/env или окружении процесса; рядом с ним должен лежать неизмененный jev-executor-questions.json с закрепленным SHA-256. CONTROL_JEV_CHEAP_MODEL, CONTROL_JEV_STANDARD_MODEL и CONTROL_JEV_DEEP_MODEL задают необязательные сопоставления со slug моделей Codex; без них команда сохраняет только уровень.

Это ручная рекомендация: команда не запускает исполнителя и не меняет текущую модель. --risk и --current-model подавляют вызов и кандидат; clarify также не предлагает модель. Квитанция добавляется только в существующий обычный .md-файл. Повторный запуск — новый явный вызов и может снова обратиться к helper. Не используй рекомендацию для задач с секретами, доступом к production или иными чувствительными рисками: оценка не подтверждает их отсутствие. Контракт: model-advice.

Быстрый старт

git clone https://github.com/dewil/claude-control.git ai-control
cd ai-control
./install.sh
$EDITOR ~/.ai-control/projects.yaml   # вписать свои проекты

Готово. Управление сессиями живёт в Telegram-боте: /sessions -> проект -> сессия -> поднять; бот, reconciler и limits-digest поднимаются тем же install.sh при наличии ~/.config/ai-control/env с нужными переменными (см. runbook'и в docs/). Без бота те же действия доступны с машины: ai-rc sessions <проект> --porcelain, ai-rc up <проект> <uuid>.

Правишь сам репо - ставь ./install.sh --link (скрипты в ~/.local/bin/ станут симлинками на bin/, git pull сразу обновляет рабочий код).

Безопасность

  • projects.yaml - доверенный файл. ai-rc парсит пути через yq как данные, без shell-интерполяции, валидирует имя проекта; содержимое под твоим контролем. Не редактируй его по запросу LLM из чата.
  • Бот не запускает ничего сам. Тап уходит в ai-rc up/down/new; имя проекта и короткий id сессии из callback_data отбиваются строгой формой до вызова, в shell не попадают. Доступ - приватный чат плюс whitelist по from.id.
  • Поднятые сессии наследуют твои ~/.claude/settings.json. ai-rc ничего не пробрасывает поверх - если стоит bypassPermissions, удалённая сессия молча сделает что попросят. Хочешь иначе - добавь в проект .claude/settings.local.json с явным allow-списком.
  • prompt-injection. Текст из README, имён веток и чужих файлов - данные, не инструкции. Имя сессии приходит из транскрипта и тоже считается данными: в кнопку и карточку оно уходит экранированным, а в командную строку - через %q.
  • Агентный слой - приватные чаты + whitelist в Telegram, бюджеты и circuit breaker против разгона, секреты только в env-файлах (не в репо/чате).
  • Task-агенты (V2) не имеют git. Работают в worktree со строгим поясом прав из шаблона (fail-closed: нет валидного шаблона - задача не заводится); коммитит рантайм, в default-ветку проекта результат попадает только после явной приёмки человеком.

Структура

Слой 1 (сессии):

  • bin/ai-rc - sessions --porcelain, up, new, down, live: список сессий с именами и подъём транзиентным юнитом.
  • bin/ai-agent-tgbot - экран /sessions (он же дашборд агентов, см. слой 2).
  • bin/ai-control-session, ai-control-watchdog, ai-control-project-watchdog - legacy-диспетчер на вечной control-сессии и tmux. Установщик их больше не включает и снимает с уже установленных машин; файлы оставлены для отката.

Слой 2 (агентный):

  • bin/ai-agent-reconciler - reconciler автономных агентов.

  • bin/ai-agent-run, ai-agent-io, ai-agent-session - исполнение/spool/сессии агентов.

  • bin/ai-agent-tgbot - Telegram-дашборд (/agents, /new, /task, /limits, карточки вопросов и приёмки).
    Ответив реплаем один раз, дальше можно писать (или наговаривать) просто в чат: адресат запоминается на 30 минут и продолжение уходит в ту же сессию. Молчание тут намеренное - если запомненного адресата нет или его инкарнация сменилась, сообщение обрабатывается как раньше, а не подхватывается наугад.
    Голосовой ответ владельца бот расшифровывает локально (GigaAM, transcribe-meeting; переопределяется AI_AGENT_VOICE_ASR) и дальше ведет его теми же путями, что печатную реплику - reply на карточку агента попадает в ту же сессию. Расшифровку он показывает ответным сообщением: распознавание ошибается, и человек должен видеть, что получил агент.
    Режим voice отправляет итог голосом: синтез делает bin/voice-report этого же репозитория (путь резолвится рядом с ботом, переопределяется AI_AGENT_VOICE_SYNTH), доставка - своя. Текст доходит всегда: выключен тумблер, нет синтезатора или упала отправка файла - уходит обычное сообщение, вместе с привязкой ответа к агенту.

    Голос из сессий - канал в одну сторону. Слово "сессия" в этом разделе означает живую сессию АГЕНТА в tmux: reply доезжает до нее через mission-inbox и tmux send-keys. У сессий слоя 1 (ccsession-<uuid>, глаголы ai-rc) обратного канала нет вовсе - юнит поднимается голым script, stdin /dev/null, pty держит сам script. Итог голосом такая сессия шлет флагом --session <имя>; reply на него получает внятный отказ с названием сессии, а не совет про карточку задачи. Промпт пишется внутри самой сессии. Решение владельца 24.08.2026: так и оставить, пока не появится машинный канал ввода.

    Как итог представляется. Карточка в Telegram подписывается именем сессии (иначе все итоги приходят одинаковым "Итог работы" и подряд неразличимы), а сама озвучка открывается отбивкой Новое сообщение. Сессия <имя>. - при автовоспроизведении карточку никто не видит, телефон в кармане. Имя берется из транскрипта (custom-title), а не из юнита: переименованная сессия должна называться так же, как в браузере. Латиница перед синтезом транслитерируется - русский Silero ее не произносит вовсе, на месте имени была пауза; подпись карточки и роутинг при этом работают с исходным именем.

    Сессия ждет ответа - сигнал в бота. bin/ai-agent-waiting-hook - хук Notification в ~/.claude/settings.json: Claude Code дергает его, когда сессия ждет ввода или уперлась в запрос разрешения. Без него молчащая сессия неотличима от работающей, и вопрос мог стоять часами. В сообщение идут имя сессии (из транскрипта, как у голоса), хвост вопроса, кнопка Сессии и ссылка вида https://claude.ai/code/session_<id> - она открывает ту же сессию в приложении Claude. Идентификатор берется из строки моста v2 session URL в debug-логе: признак якорен на формат строки, потому что CLI пишет в тот же файл содержимое работы, и голая подстрока cse_ подменялась текстом самой сессии (поймано на живых данных). Превью ссылки отключается флагом notify --no-preview - карточка занимает пол-экрана телефона. Повтор по одной сессии - не чаще раза в 30 минут (AI_AGENT_WAITING_QUIET_S); терминальные сессии игнорируются, они и так перед глазами.

    Кто зовет озвучку. bin/ai-agent-voice-hook - хук Stop в ~/.claude/settings.json: сессия договорила ответ, хук берет его и шлет голосом. Без него транспорт есть, а зовущего нет - голос приходит только оттуда, где команду набрали руками. Четыре фильтра, каждый нужен: тумблер выключен - молчим; ответ короче 400 знаков - это "готово" и уточнения, слушать нечего; с прошлой озвучки этой сессии меньше 5 минут - телефон не радио; сессия без юнита ccsession-* (локальный терминал, агент) - не наш случай. Отправка уходит отвязанным процессом: хук не ждет синтез. Причины отказа - ~/.cache/voice-hook.log, наружу хук молчит всегда.

    Озвучка под тумблером - кнопка Голос: вкл/выкл во втором ряду клавиатуры, состояние прямо в подписи (в дороге видно режим, не нажимая). Режим общий для всех сессий, живет в ~/.ai-control/tgbot.voice.json, по умолчанию ВЫКЛЮЧЕН. Входящий голос расшифровывается всегда независимо от тумблера: распознавание локальное, а реплай голосом нужен и в текстовом режиме.

  • bin/ai-agent-done, ai-agent-ask, ai-agent-answer, ai-agent-permit - протокол задачи V2: заявка "готово", вопрос из прогона, доверенный писатель ответов, гейт подтверждений.

  • bin/ai-agent-limits-digest - дайджест лимитов LLM.

  • bin/ai-agent-harvest, ai-agent-review, ai-agent-checkrun - приёмка/ревью/проверки.

  • bin/ai-rc-takeover, ai-rc-agent - кросс-машинный takeover.

Опциональный модуль (--with-backup):

Общее:

  • launchd/ / systemd/ - шаблоны юнитов; install.sh их рендерит.
  • examples/ - стартовые projects.yaml, CLAUDE.md, settings.local.json.
  • docs/ - architecture.md, дизайн-доки этапов, runbook'и (limits-digest), troubleshooting.
  • tests/ - offline-тесты компонентов агентного слоя.
  • install.sh / uninstall.sh; что именно ставится и снимается - в scripts.manifest, общем на оба скрипта (модуль бэкапа - scripts.manifest.backup).

Принципы

  • Идемпотентность - install.sh гоняется повторно; projects.yaml, CLAUDE.md, логи не трогаются.
  • Runtime отдельно от репо - код где удобно (~/Work/ai-control/), данные в ~/.ai-control/.
  • Только user-level супервизор - launchd user agent / systemctl --user, никакого sudo.
  • Никакой магии в надзоре - watchdog читает лог и пинает супервизор; всё видно глазами в ~/.ai-control/*.log.

Удалить

./uninstall.sh           # снять агентов, удалить скрипты из ~/.local/bin/
./uninstall.sh --purge   # дополнительно снести ~/.ai-control/

Лицензия

MIT. Бери, дорабатывай, используй у себя - оставь copyright-уведомление в производных копиях.

Сессии Codex из Telegram

«Сессии → проект» открывает Codex. Кнопка «➕ Codex» создаёт отдельный диалог, который продолжается через подключённый клиент Codex. «Claude» открывает прежнее управление Claude. Новые сессии наследуют актуальные model и effort эффективного config общего сервера для проекта; карточка показывает известные значения API. Настройки Mac или текущего диалога не копируются. Мобильная приёмка остаётся незавершённой. Реестр проектов общий. Установка и диагностика: runbook-codex-sessions.md.

Фоновые задачи Codex

ai-rc agent new-task --engine codex --name task-example --project example --text 'Задача' создаёт отдельную event/drain задачу в worktree. В Telegram: /new --engine codex example Задача. Модель и effort наследуются от Codex; вопросы, приёмка и отмена используют общую TASK-процедуру. Без --engine codex используется Claude. Требования, ограничения и восстановление: runbook-codex-tasks.md.

Canonical migration установленной версии: runbook-ai-control-names.md. Legacy aliases не устанавливаются.

Reviews (0)

No results found