ai-control
Health Gecti
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 10 GitHub stars
Code Basarisiz
- rm -rf — Recursive force deletion command in .claude/settings.json
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
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.
ai-control
Русский · English
Автономная инфраструктура поверх 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-<uuid>: сессия A"]
rc --> projB["ccsession-<uuid>: сессия 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):
bin/ai-control-backup,ai-control-backup-init,ai-control-backup-restore-test- restic-бэкап в два S3 (см. runbook).
Общее:
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 не устанавливаются.
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi