agent-tui

agent-tui — официальный навык из Gemini CLI для программного управления терминальными интерфейсами и проверки интерактивного поведения. Его применяют для автоматизации CLI/TUI, регрессионного тестирования и инспекции приложений, которые нельзя надёжно проверить только чтением stdout. Важное ограничение указано прямо в SKILL.md: основной агент не должен вызывать этот навык напрямую для тестирования TUI; следует передать работу subagent с именем tui_tester. Сам tui_tester использует отдельный pseudo-terminal, видит символьную сетку экрана и может вводить текст, нажимать клавиши, ждать устойчивого состояния и снимать свежий screenshot. Модель работы замкнутая: сначала наблюдение, затем решение, одно действие, ожидание и повторная проверка. Экран TUI постоянно перерисовывается, поэтому старая координата или старый текст не считаются надёжным состоянием. Перед каждым действием нужно получить свежий screenshot, заново найти цель и убедиться, что интерфейс перестал загружаться или анимироваться. Для конкретного текста используется wait с проверкой, для исчезновения текста — ожидание его ухода, а для завершения перехода — wait --stable. Только после этого выполняются type или press. Успех подтверждается наблюдаемым состоянием, а не тем, что команда завершилась без ошибки. Для JSON-разбора доступен screenshot --format json, для обычной проверки — текстовый screenshot. Вызовы нельзя бездумно конвейеризировать: модальное окно или обновление интерфейса может перехватить следующую клавишу. После каждой операции состояние нужно считать недействительным и снять новый снимок. Если wait завершается по таймауту, нельзя сразу перезапускать или убивать сессию; сначала снимается screenshot, чтобы определить модальное окно, ошибку или потерю фокуса. Завершённые сессии нужно очищать через agent-tui kill, иначе оставшиеся процессы могут влиять на будущие проверки. На macOS у навыка есть отдельный workaround для фонового daemon: обычная daemonization может завершиться ошибкой Connection refused (os error 61). Daemon запускается вручную в изолированном tmux pseudo-terminal, но перезапускать его следует только если проверка sessions показывает, что он не работает. Для переподключения используется session_id, который возвращает agent-tui run; поле pid является только информацией о дочернем процессе и не подходит для reconnect. Если daemon упал и pseudo-terminal уничтожен, старую сессию нельзя оживить — создаётся новая. Перед тестированием изменённого Gemini CLI нужно собрать проект, потому что agent-tui запускает скомпилированные JavaScript-файлы. Для новых workspace trust-модалей используется GEMINI_CLI_TRUST_WORKSPACE=true; при изолированном тесте глобальные настройки выносятся в отдельный GEMINI_CLI_HOME. Skill рассчитан на macOS и Linux. Он не превращает TUI в постоянный DOM: экран остаётся изменчивым, поэтому надёжность обеспечивается короткими последовательностями observe → act → wait → verify и обязательным удалением сессий после проверки.