tui-use: как дать ИИ доступ к интерактивным терминальным приложениям — VogueTech

Что нового

tui-use — это утилита, которая позволяет AI-агентам управлять интерактивными терминальными программами, а не только запускать разовые shell-команды.

Ключевые новшества по сравнению с привычным «агент запускает bash и читает stdout»:

Полноценная работа с TUI и REPL, а не только с batch-скриптами:
- Python, Node, psql, redis-cli и любые другие REPL.
- Интерактивные генераторы проектов (npm create, cargo new, create-react-app и подобные «мастера» с вопросами).
- Полноэкранные TUI-приложения: vim, lazygit, htop, fzf и т.п.
- Интерактивные сессии по SSH, а не только единичные команды.
Работа через PTY с полноценной эмуляцией терминала:
- Используется headless-эмулятор @xterm/headless.
- ANSI-последовательности, перемещение курсора, очистка экрана — всё обрабатывается корректно.
- Агент получает не «сырые байты», а уже собранный снимок экрана в виде чистого текста.
Модель «снимков экрана» вместо стриминга байтов:
- Взаимодействие описано как простой цикл: «прочитать экран → решить, что напечатать → отправить клавиши → снова прочитать».
- Нет асинхронных потоков, догадок по тайм-аутам и склейки частичного вывода.
Подсветка выбранных элементов:
- Каждый снимок экрана содержит поле highlights.
- В нём перечислены области с инверсным видео — стандартный способ выделения активных пунктов в TUI.
- Агент может понять, какой пункт меню, вкладка или кнопка сейчас активны, не гадая по позиции курсора.
Расширенная поддержка клавиш:
- Отправка текста, Enter, Ctrl+C, стрелок, функциональных клавиш и других спецклавиш.
- Полный список доступен через команду tui-use keys.
Интеграция с Claude Code и другими AI-агентами:
- Есть отдельный плагин для Claude Code.
- Подходит для Claude Code, Cursor, Codex, Gemini CLI, OpenCode и других кодовых агентов.

Ограничения на старте:

Цвета и большинство стилей TUI теряются — агент видит только текст и инверсные выделения.
Поддержка только Unix-подобных систем (macOS, Linux). Windows пока не работает, планируется поддержка через ConPTY.

Как это работает

tui-use строится вокруг фонового демона, который управляет PTY-сессиями и эмулирует терминал.

Схема взаимодействия:

CLI (tui-use) — точка входа для человека или AI-агента.
Демон — фоновый процесс, который создаёт и ведёт PTY-сессии.
Целевая программа — любая терминальная утилита, например vim или htop.
Эмулятор терминала — @xterm/headless, который принимает ANSI-последовательности и поддерживает:
- цвета и стили (для внутренних нужд),
- перемещение курсора,
- очистку экрана,
- альтернативный буфер для полноэкранных программ.

Пайплайн рендера:

Целевая программа пишет в PTY ANSI-последовательности.
@xterm/headless рендерит это в состояние виртуального экрана терминала.
Демон отдаёт наружу:
- screen — содержимое экрана в виде чистого текста без цветов и форматирования;
- highlights — участки с инверсным видео (выбранные элементы);
- title — заголовок окна;
- is_fullscreen — флаг использования альтернативного буфера (полноэкранный режим).

Агент работает не с потоком байтов, а с «полароидом» — готовым снимком экрана. Это упрощает логику: не нужно угадывать, закончился ли вывод, и собирать картину из фрагментов.

Демон управляется отдельными командами:

tui-use daemon status   # Проверить, запущен ли демон
tui-use daemon stop     # Остановить демон
tui-use daemon restart  # Перезапустить демон

Что это значит для вас

tui-use полезен в первую очередь тем, кто уже использует AI-агентов для разработки, DevOps и администрирования, но упирается в ограничения обычного CLI-доступа.

Где инструмент особенно полезен

Интерактивные REPL-сессии под управлением ИИ

Если вы даёте Claude Code, Cursor или другому агенту доступ к shell, он обычно может только запускать отдельные команды. Как только вы открываете python, node, psql или redis-cli, всё ломается: утилита ждёт ввода, агент не понимает, что на экране и что нужно ввести дальше.

tui-use позволяет агенту:

открыть REPL и оставаться в нём столько, сколько нужно;
читать вывод как текстовый экран;
отправлять команды и анализировать ответ в цикле.

Это удобно для задач вроде:

отладки кода в интерактивном Python;
экспериментов с базой через psql без промежуточного REST-API;
работы с Redis через redis-cli.

Интерактивные генераторы и установщики

Большинство современных CLI-генераторов проектов и установщиков задают вопросы перед тем, как что-то сделать: npm create, cargo new, create-react-app и десятки им подобных.

tui-use позволяет агенту:

увидеть вопросы на экране;
понять, какой пункт меню сейчас выбран (через highlights);
нажать стрелки и Enter, чтобы пройти мастер до конца.

Это полезно, если вы хотите, чтобы агент сам поднимал новые проекты, конфигурировал окружение или запускал установщики, не ожидая от вас ручного ввода.

Работа с базами данных через родные CLI

Вместо того чтобы писать отдельный API или ORM-слой для агента, можно дать ему доступ к psql или mysql через tui-use.

Агент сможет:

подключаться к базе;
выполнять запросы;
проверять схемы таблиц;
листать вывод с помощью прокрутки.

Это подходит для внутренних админ-задач, миграций, быстрых проверок данных.

SSH и удалённые интерактивные программы

Обычная схема «агент выполняет одну SSH-команду и отключается» подходит только для простых задач. Но если на удалённой машине нужно:

запустить htop и посмотреть, что происходит;
открыть vim для правки файла;
управлять интерактивным сервисом или TUI-панелью;

tui-use позволяет агенту держать SSH-сессию и продолжать работать с интерактивными программами на другом конце.

Полноэкранные TUI-приложения

Инструменты вроде vim, lazygit, htop, fzf и других TUI-программ изначально не рассчитаны на сценарное управление.

С tui-use агент:

видит текущий экран этих программ в виде текста;
понимает, какие элементы выделены (через highlights);
может нажимать нужные клавиши, как человек.

Это открывает сценарии вроде:

полуавтоматического редактирования файлов через vim под управлением агента;
управления git-историей через lazygit;
анализа системных метрик через htop.

Где инструмент не поможет

Графические приложения вне терминала

tui-use не работает с GUI: браузеры, полноценные IDE, десктопные приложения. Только то, что можно открыть в терминале.

Сценарии, где важны цвета и детальное форматирование

Экран, который видит агент, — это чистый текст. Цвета и большинство стилей отбрасываются. Если ваш рабочий процесс опирается на цветовую кодировку (например, сложные цветные логи), агент этого не увидит.

Windows без WSL

tui-use требует Unix PTY (macOS или Linux). Поддержка Windows через ConPTY заявлена как план, но сейчас не работает. На Windows можно использовать WSL, но это уже отдельная настройка.

Доступность из России

tui-use распространяется через npm и GitHub. Для установки может понадобиться доступ к этим ресурсам. Если у вас ограничен доступ к npm или GitHub, вероятно, потребуется VPN или локальные зеркала.

Место на рынке

tui-use решает конкретную задачу: дать AI-агентам доступ к интерактивным терминальным программам через PTY и эмуляцию терминала.

Ближайшая аналогия, которую автор прямо упоминает, — BrowserUse, но для терминала:

BrowserUse даёт агентам управление браузером.
tui-use даёт агентам управление терминальными TUI и REPL.

Продукт хорошо сочетается с уже существующими AI-инструментами для разработки:

Claude Code — есть готовый плагин и отдельный skill для интеграционных тестов.
Cursor, Codex, Gemini CLI, OpenCode — tui-use можно использовать как внешний CLI-инструмент, через который агенты получают доступ к TUI.

Прямых численных сравнений с другими решениями в исходном описании нет: нет указаний на скорость относительно других инструментов, объём контекста, стоимость или потребление ресурсов. Фокус продукта — именно на расширении зоны ответственности агентов за счёт PTY и TUI, а не на производительности или цене.

Установка

tui-use распространяется как npm-пакет и как исходный код на GitHub.

Установка из npm (рекомендуется)

npm install -g tui-use

Установка из исходников

git clone https://github.com/onesuper/tui-use.git
cd tui-use
npm install
npm run build
npm link

Требования к сборке

Обычно установщик пытается скачать готовый бинарник под вашу платформу. Если подходящего бинарника нет, он пересобирает проект из исходников. Для этого нужны инструменты сборки.

Если автоматическая пересборка не удалась, установите:

macOS:

xcode-select --install

Linux (Debian/Ubuntu):

sudo apt-get install build-essential python3 g++

Windows:

Пока не поддерживается. Поддержка через ConPTY запланирована.

Как запустить

tui-use предоставляет CLI-интерфейс для управления сессиями.

Основные команды

Запуск программы:

tui-use start <cmd>                    # Запустить программу

tui-use start --cwd <dir> <cmd>        # Запустить в конкретной директории

tui-use start --cwd <dir> "<cmd> -flags"  # Обернуть команду в кавычки, чтобы передать флаги (например, git rebase -i)

tui-use start --label <name> <cmd>     # Запустить с меткой

tui-use start --cols <n> --rows <n> <cmd>  # Задать размер терминала (по умолчанию 120x30)

Работа с сессией:

tui-use use <session_id>               # Переключиться на сессию

tui-use type <text>                    # Напечатать текст

tui-use type "<text>\n"                 # Напечатать текст и Enter

tui-use type "<text>\t"                 # Напечатать текст и Tab

tui-use paste "<text>\n<text>\n"        # Многострочный ввод (каждая строка + Enter)

tui-use press <key>                    # Нажать клавишу

tui-use snapshot                       # Получить текущий экран

tui-use snapshot --format json         # Экран в формате JSON

tui-use scrollup <n>                   # Прокрутка к старому выводу

tui-use scrolldown <n>                 # Прокрутка к более новому выводу

tui-use find <pattern>                 # Поиск по экрану (regex)

tui-use wait                           # Ждать изменения экрана

tui-use wait <ms>                      # Ждать с тайм-аутом (по умолчанию 3000 мс)

tui-use wait --text <pattern>          # Ждать, пока на экране не появится шаблон

tui-use wait --format json             # Вывод wait в JSON

tui-use list                           # Список всех сессий

tui-use use <session_id>               # Переключиться на сессию

tui-use info                           # Детали текущей сессии

tui-use rename <label>                 # Переименовать сессию

tui-use kill                           # Убить текущую сессию

Команды для демона:

tui-use daemon status   # Проверить, запущен ли демон

tui-use daemon stop     # Остановить демон

tui-use daemon restart  # Перезапустить демон

Пример: запуск и взаимодействие

git clone <repo_url>
cd tui-use
npm install
npm run build
npm link

# Попробовать

tui-use start python3 examples/ask.py

tui-use wait

tui-use type " Alice "

tui-use press enter

tui-use wait

tui-use kill

Интеграция с Claude Code

tui-use поставляется с плагином для Claude Code. Важно: сам плагин содержит только описания навыков, а реальную работу с PTY выполняет установленный CLI-инструмент. Поэтому сначала нужно установить CLI по инструкции выше.

Установка плагина из self-hosted marketplace

Шаг 1. Добавить marketplace:

/plugin marketplace add onesuper/tui-use

Шаг 2. Установить плагин:

/plugin install tui-use@tui-use

Шаг 3. Перезагрузить плагины:

/reload-plugins

Интеграционные тесты

В поставку входит skill для запуска полного набора интеграционных тестов через Claude Code.

Команда для запуска в Claude Code:

/tui-use-integration-test

Claude выполнит тесты по порядку и вернёт статус PASS/FAIL для каждого. При ошибке вы увидите реальный вывод экрана.

Ограничения и проблемы

Ограничения

Потеря цветовой информации

Поле screen содержит только чистый текст.
Цвета и большинство форматирования удаляются.
Выделенные элементы и активные пункты фиксируются в highlights через детекцию инверсного видео.
Заголовок окна и полноэкранный режим доступны через поля title и is_fullscreen.

Поддержка только Unix PTY

Работает на macOS и Linux.
Windows пока не поддерживается.
Поддержка через ConPTY заявлена как план.

Типичные проблемы при установке

Если автоматическая пересборка бинарника не удалась:

Проверьте, что установлены инструменты сборки (см. раздел «Установка» выше).
Для macOS — xcode-select --install.
Для Linux — build-essential, python3, g++.

После установки зависимостей перезапустите установку tui-use.

Лицензия

tui-use распространяется под лицензией MIT. Это значит, что вы можете использовать инструмент в коммерческих и некоммерческих проектах, модифицировать код и встраивать его в свои продукты при соблюдении условий MIT-лицензии.