### Анализ репозитория Shellwright
Shellwright — это открытый инструмент, разработанный на TypeScript и JavaScript (с использованием Node.js), который представляет собой сервер на основе протокола MCP (Model-Context-Protocol). Его основная цель — предоставить AI-агентам (таким как те, что интегрированы в Claude Code, Cursor, VS Code или другие LLM-driven инструменты) возможность управлять терминалом, выполнять команды, захватывать скриншоты и записывать анимированные GIF-файлы. По сути, это аналог Playwright, но для командной строки: он позволяет AI "играть" с терминалом, как с браузером, автоматизируя задачи в shell-окружении.
Проект лицензирован под MIT, что делает его бесплатным для личного и коммерческого использования. Репозиторий содержит исходный код, примеры использования, документацию и демо-скрипты (например, на Python для тестирования). Основные файлы: `dist/index.js` после сборки, темы для рендеринга (one-dark, dracula и т.д.), а также инструменты для логирования и тестирования.
#### Как это работает
Shellwright запускается как сервер (либо через stdio, либо HTTP), который экспонирует набор инструментов (tools) в формате MCP. Эти инструменты позволяют AI-агенту взаимодействовать с псевдотерминалами (PTY — pseudo-terminals) в реальном времени. Вот пошаговый механизм:
1. **Запуск сервера**:
- Команда: `npx @dwmkerr/shellwright` (для быстрого старта) или локальная сборка через `npm run build`.
- Сервер может работать в HTTP-режиме (`--http`), слушая на порту (по умолчанию 7498), или в stdio-режиме для локальных интеграций.
- Конфигурация через флаги или переменные окружения: размер терминала (cols/rows), тема цветов, шрифт, временная директория для файлов и т.д.
2. **Создание сессии PTY**:
- AI вызывает инструмент `shell_start` с параметрами (например, командой "bash -i" для запуска интерактивной оболочки).
- Сервер спавнит PTY с указанными размерами (по умолчанию 120x40), запускает команду и возвращает `shell_session_id` для дальнейшей работы.
- Можно запускать несколько сессий параллельно.
3. **Отправка ввода и чтение вывода**:
- `shell_send`: Отправляет keystrokes (символы, включая Enter) в терминал с опциональной задержкой (для симуляции ввода).
- `shell_read`: Читает текущий буфер терминала (текст с ANSI-кодами или очищенный). Это позволяет AI видеть вывод команд в реальном времени.
4. **Захват медиа**:
- `shell_screenshot`: Захватывает скриншот терминала в формате PNG (основной), SVG, ANSI или TXT. Буфер преобразуется в SVG с применением темы (например, one-dark), затем в PNG с помощью библиотеки вроде sharp.
- `shell_record_start/stop`: Запускает/останавливает запись GIF (с FPS, по умолчанию 10). Кадры — это PNG-снимки, дубликаты удаляются для оптимизации размера. Файлы хранятся во временной директории (`/tmp/shellwright` по умолчанию).
5. **Экспорт и очистка**:
- Сервер возвращает `download_url` для файлов (например, `
http://localhost:7498/download/...`), которые можно скачать через curl или браузер.
- `shell_stop`: Завершает сессию, удаляет временные файлы.
6. **Интеграция с AI**:
- Сервер регистрируется в AI-клиенте (например, в Claude: `claude mcp add ...` или в настройках VS Code/Cursor).
- AI-агент (LLM) использует ReAct-подход: анализирует задачу, вызывает инструменты последовательно (например, start → send → screenshot → stop).
- Логирование: Опционально пишет JSONL-файл с вызовами для отладки.
Технически: Использует `child_process` Node.js для PTY, рендерит ANSI в изображения через CSS-темы. Нет зависимости от внешних сервисов, всё локально. Подходит для задач вроде автоматизации скриптов, тестирования CLI, создания туториалов с GIF или отладки (AI может запустить команду, увидеть ошибку на "скриншоте" и скорректировать).
#### Примеры использования
- **Простой скриншот**: Пользователь говорит AI: "Запусти htop и покажи скриншот". AI вызывает `shell_start("htop")`, затем `shell_screenshot` — возвращает URL PNG.
- **Запись GIF**: "Открой Vim, напиши текст и запиши GIF". AI: start bash → send "vim" → send keystrokes → record_start → действия → record_stop.
- **Автоматизация**: В демо-скрипте: `python demo/demo.py -- "Run ls and screenshot"` — сервер запускает HTTP, AI выполняет и возвращает файл.
### Сравнение с обычным запросом к Gemini CLI
Gemini CLI — это официальный open-source инструмент от Google (устанавливается через `npm install -g @google/gemini-cli`), который предоставляет прямой доступ к моделям Gemini AI (включая Gemini 3 Pro) прямо из терминала. Он использует ReAct-цикл (reason-and-act: модель размышляет, затем действует через инструменты) и поддерживает встроенные инструменты (чтение/запись файлов, выполнение команд, поиск и т.д.), а также внешние MCP-сервера. Это универсальный AI-агент для кодирования, отладки, генерации контента и автоматизации, но с фокусом на текстовой взаимодействии.
#### Обычный запрос к Gemini CLI
- **Как работает**: Вы вводите команду вроде `gemini "Напиши shell-скрипт для листинга файлов"` или `gemini "Отладь этот код"`. Модель анализирует запрос, может использовать встроенные инструменты (например, `read_file` для чтения кода, `execute_command` для запуска простых команд), и возвращает текстовый ответ (скрипт, объяснение, исправления). Всё происходит в одном цикле: prompt → reasoning → action (если нужно) → response.
- **Преимущества**: Простота, скорость, нет нужды в дополнительных серверах. Подходит для генерации кода, объяснений, исследований (может искать в вебе через инструменты). Бесплатный доступ с лимитами, или через API-ключ для продвинутых моделей.
- **Ограничения**: Взаимодействие преимущественно текстовое. Если нужно запустить команду и увидеть визуальный вывод (скриншот терминала, GIF), Gemini CLI не захватывает это нативно — он может выполнить `ls` и показать текст, но не рендерит "как в терминале". Для сложных интерактивных задач (типа редактирования в Vim с визуальной отладкой) модель полагается на симуляцию, а не реальное выполнение с захватом.
#### Сравнение с Shellwright
| Аспект | Shellwright | Обычный запрос к Gemini CLI |
|--------|-------------|-----------------------------|
| **Фокус** | Специализирован на терминальной автоматизации: реальное выполнение команд в PTY, захват визуалов (скриншоты, GIF). Интегрируется как MCP-сервер в AI-агенты. | Универсальный AI-запрос: генерация текста/кода, простые действия через встроенные инструменты. Не фокусируется на визуальном терминале. |
| **Взаимодействие** | Агентное и интерактивное: AI может итеративно отправлять команды, читать буфер, корректировать на основе вывода/скриншотов. Идеально для тестирования, туториалов, отладки CLI. | Одношаговое или простое цикличное: Запрос → Ответ. Для сложного — использует ReAct, но без глубокого контроля над терминалом (текст только). |
| **Визуалы** | Да: Скриншоты (PNG/SVG), GIF-записи с темами и оптимизацией. | Нет: Только текст. Для визуалов нужно вручную запускать внешние инструменты. |
| **Интеграция** | Как сервер для AI (включая Gemini CLI! — можно добавить Shellwright как MCP в Gemini). Требует запуска сервера. | Самостоятельный CLI, но может использовать внешние MCP (например, Shellwright для расширения). |
| **Сложность установки** | Нужно npx или сборка + регистрация в AI-клиенте. | Простая: npm install, затем `gemini <prompt>`. |
| **Применение** | Для задач, где нужен "живой" терминал (автоматизация скриптов с верификацией, запись демо). Более мощный для agentic AI. | Для быстрых запросов (генерация скрипта, объяснение). Менее подходит для визуальной/интерактивной отладки. |
| **Пример** | AI: "Запусти ls, скриншот" → Реальный PTY, PNG-файл. | `gemini "Запусти ls и покажи"` → Текст вывода ls (если в контексте), но без скриншота. |
**Вывод**: Shellwright — это расширение для AI-агентов, делающее их "руками" в терминале, с визуальным фидбеком. Обычный запрос к Gemini CLI — это "мозги" без рук: быстро генерирует идеи/код, но не выполняет/визуализирует в реальном терминале. Если интегрировать Shellwright в Gemini CLI как MCP-сервер, вы получите комбо: Gemini размышляет и использует Shellwright для действий. Для простых задач Gemini CLI хватит, но для продвинутой автоматизации Shellwright добавляет глубину.
.jpg)
Либо это мои провайдеры блокировку начали, но я не в Рашке.