Antigravity Cli

Работа с Antigravity CLI (agy): плагины, аутентификация, песочница.

Метаданные навыка

Справочник: полный SKILL.md

Antigravity CLI (agy)

Руководство оператора по Antigravity CLI, вызываемому как agy. Все команды agy запускай через инструмент Hermes terminal; конфиг и логи смотри через read_file. Этот навык — справочник плюс процедуры: он не оборачивает сетевой API, поэтому аутентификация со стороны самого Hermes не нужна.

Когда использовать

• Установка, обновление или быстрая проверка бинарника agy
• Запуск неинтерактивных одноразовых вызовов agy --print / agy -p
• Отладка аутентификации, песочницы, прав доступа или состояния плагинов Antigravity
• Чтение настроек, привязок клавиш, диалогов или логов Antigravity

Ментальная модель

У Antigravity два слоя — держи их раздельно, иначе совет окажется неверным:

1. Команды shell-обёртки — agy help, agy install, agy plugin, agy update, agy changelog. Запускай их через инструмент terminal.
2. Интерактивные слэш-команды внутри сессии — /config, /permissions, /skills, /agents и т.д. Они существуют только внутри запущенной TUI-сессии agy, но не в shell-обёртке.

agy help показывает поверхность shell-обёртки, а НЕ слэш-команды внутри сессии.

Требования

• Бинарник agy в PATH. Проверь через инструмент terminal: command -v agy && agy --version.
• Навыку не нужны ни переменные окружения, ни API-ключи — Antigravity управляет своей аутентификацией сам через keyring ОС и вход в браузере (см. раздел «Аутентификация» ниже).

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

Каждую команду agy вызывай через инструмент terminal. Примеры:

terminal(command="agy --version")
terminal(command="agy help")
terminal(command="agy plugin list")
terminal(command="agy --print 'Summarize the repo in 3 bullets'", workdir="/path/to/project")

Для интерактивной многошаговой TUI-сессии запускай agy с pty=true (и tmux для захвата и наблюдения) — тот же приём, что в навыках codex / claude-code. Для разовых проверок и скриптовых промптов лучше брать agy --print (неинтерактивный режим).

Чтобы заглянуть в собственные файлы Antigravity, применяй read_file к путям из раздела «Основные пути» ниже — не делай cat через терминал.

Сценарии делегирования

agy — бэкенд кодового агента из того же семейства, что codex и claude-code, поэтому применимы те же формы делегирования. Берите их, когда передаёте Antigravity настоящую работу (фичи, правки, ревью, второе мнение), а не просто проверяете работоспособность.

Разовый запуск (предпочтителен для скриптовых промптов и второго мнения)

terminal(command="agy -p 'Review this diff for bugs and security issues' --model 'Gemini 3.1 Pro (High)'", workdir="/path/to/repo", timeout=300)

-p — неинтерактивный режим: промпт отрабатывает, и процесс завершается. Движок выбирается флагом --model (точные строки-названия смотрите в agy models, например 'Gemini 3.1 Pro (High)', 'Claude Opus 4.6 (Thinking)'). Дополнительные корни контекста добавляются повторяемым --add-dir.

Долгие и ограниченные прогоны (тесты, сборки, правки во многих файлах)

Уводите в фон с уведомлением по завершении — как в навыке codex:

terminal(command="agy -p 'Implement the change described in TASK.md and run the tests' --dangerously-skip-permissions", workdir="/path/to/repo", background=true, notify_on_complete=true)
# then: process(action="poll"/"log"/"wait", session_id=<id>)

Интерактивный многошаговый режим (PTY + tmux)

Для разговорной сессии запускайте agy -i (или голый agy) с pty=true и tmux для capture-pane / send-keys — ровно тот приём, что описан в навыках codex и claude-code. Позже возвращайтесь к разговору через --continue / -c либо конкретный --conversation <id>.

Параллельные экземпляры (веер по подзадачам и worktree)

Создайте по git worktree на задачу и запустите в каждом независимый agy -p в фоне, затем соберите результаты — тот же веер по worktree, каким навык codex чинит задачи пачками. Параллельность держите в пределах того, что переварят машина и ваши возможности по ревью.

Особенность вывода и ограничений (отличие от Claude Code)

• agy -p возвращает обычный текст — никакого --output-format json и никакого конверта результата с session_id, стоимостью и числом ходов. Разбирайте stdout напрямую, JSON-объекта не ждите.
• --max-turns не существует. Печатный прогон ограничивается флагом --print-timeout (по умолчанию 5m). Для долгих задач поднимайте: --print-timeout 20m. И согласуйте с timeout= у terminal, чтобы внешний вызов не оборвал прогон раньше времени.

Граница оркестрации

Antigravity — это исполняющий бэкенд для воркера или рецензент со стороны, деталь исполнения, которой владеет агент или профиль, ведущий задачу, а НЕ примитив оркестрации первого класса. Не выносите agy на канбан-доску отдельной карточкой и не делайте из него слой координации: маршрутизируйте работу через обычный граф задач, а назначенный воркер сам выберет, чем работать — agy, codex, claude-code или прямыми инструментами. Тянитесь к нему намеренно, только когда просит пользователь, когда воркер настроен его оборачивать или когда нужна перекрёстная проверка семейством Gemini чужого плана или диффа.

Основные пути

• Бинарник / точка входа: agy
• Каталог данных приложения: ~/.gemini/antigravity-cli/
• Файл настроек: ~/.gemini/antigravity-cli/settings.json
• Файл привязок клавиш: ~/.gemini/antigravity-cli/keybindings.json
• Логи: ~/.gemini/antigravity-cli/log/cli-*.log
• Диалоги: ~/.gemini/antigravity-cli/conversations/
• Артефакты brain: ~/.gemini/antigravity-cli/brain/
• История: ~/.gemini/antigravity-cli/history.jsonl
• Стейджинг плагинов: ~/.gemini/antigravity-cli/plugins/<plugin_name>/

Краткий справочник

Команды обёртки

• agy changelog
• agy help
• agy install
• agy plugin / agy plugins
• agy update

Полезные флаги

• --add-dir
• --continue / -c
• --conversation
• --dangerously-skip-permissions
• --print / -p
• --print-timeout
• --prompt
• --prompt-interactive / -i
• --sandbox
• --log-file
• --version

Подкоманды плагинов (agy plugin --help)

• list, import [source], install <target>, uninstall <name>, enable <name>, disable <name>, validate [path], link <mp> <target>, help

Флаги установки (agy install --help)

• --dir, --skip-aliases, --skip-path

Слэш-команды внутри сессии

• Управление диалогом: /resume (/switch), /rewind (/undo), /rename <name>, /clear, /fork, /reset, /new
• Настройки и инструменты: /config, /settings, /permissions, /model, /keybindings, /statusline, /tasks, /skills, /mcp, /open <path>, /usage, /logout, /agents
• Помощники промпта: @ — автодополнение путей, esc esc очищает промпт (когда нет потокового вывода), ! запускает команду терминала напрямую, ? открывает справку

Настройки и права доступа

Частые ключи настроек (settings.json)

• allowNonWorkspaceAccess
• colorScheme
• permissions.allow
• trustedWorkspaces

Режимы прав доступа

request-review, always-proceed, strict, proceed-in-sandbox.

Поведение песочницы

• enableTerminalSandbox — булев флаг в settings.json; по умолчанию false.
• Переопределения на старте (--sandbox, --dangerously-skip-permissions) могут перекрыть постоянные настройки для текущей сессии.

Поведение аутентификации

• Сначала CLI пробует защищённый keyring ОС.
• Если сохранённой сессии нет, переходит на вход через Google в браузере.
• Локально открывается браузер по умолчанию; по SSH печатается URL авторизации, и ожидается, что код авторизации вставят обратно.
• /logout удаляет сохранённые учётные данные.

Плагины

• Плагины размещаются в ~/.gemini/antigravity-cli/plugins/<plugin_name>/.
• Они могут включать навыки, агентов, правила, серверы MCP и хуки.
• Если agy plugin list не возвращает ни одного импортированного плагина — это допустимое пустое состояние.

Подводные камни

• agy help показывает команды обёртки, а не интерактивные слэш-команды.
• agy --version — безопасная неинтерактивная проверка версии; agy version интерактивна и может упасть без настоящего TTY.
• Первое место для поиска сбоев: ~/.gemini/antigravity-cli/log/cli-*.log (читать через read_file).
• Не путай постоянные настройки JSON с переопределениями на старте.
• ~/.gemini/antigravity-cli/bin/agentapi — тонкая обёртка над agy agentapi.
• В WSL токены хранятся в файлах, поэтому проблемы с аутентификацией — это, как правило, вопрос локальных файлов или состояния сессии, а не браузера.
• Идентичность рабочей области может зависеть от каталога запуска и маркера проекта .antigravitycli.

Проверка

Убедись, что установка реальная и рабочая — всё через инструмент terminal (файлы читай через read_file):

1. terminal(command="command -v agy")
2. terminal(command="agy --version")
3. terminal(command="agy help")
4. terminal(command="agy plugin list")
5. read_file для ~/.gemini/antigravity-cli/settings.json
6. read_file для последнего ~/.gemini/antigravity-cli/log/cli-*.log
7. При необходимости read_file для ~/.gemini/antigravity-cli/keybindings.json

• agy -p печатает только обычный текст — ни --output-format json, ни конверта результата. Не пытайтесь выковырять из него JSON-объект (в отличие от claude-code).
• Печатные прогоны ограничивайте флагом --print-timeout (по умолчанию 5m), а не --max-turns (у agy его нет).

Вспомогательные файлы

• references/cli-docs.md — краткие заметки из документации getting-started, usage и features.