Grok

Делегируй написание кода xAI Grok Build CLI (фичи, PR).

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

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

Grok Build CLI — руководство по оркестрации в Hermes

Делегируй задачи по написанию кода Grok Build — автономному агенту xAI для работы в терминале, команда grok — через терминал Hermes. Grok умеет читать файлы, писать код, выполнять команды оболочки, запускать субагенты и управлять git-процессами. Три режима запуска: интерактивный TUI, headless (-p) и ACP-агент поверх JSON-RPC.

Это третий в семействе codex и claude-code. Паттерн оркестрации практически идентичен — для одиночных задач предпочитай headless -p, для интерактивных сессий используй PTY.

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

• Разработка новых фич
• Рефакторинг
• Ревью PR
• Массовое исправление задач
• Любая задача, где ты бы взял Codex или Claude Code, но хочешь Grok

Требования

• Установка (рекомендуется): npm install -g @xai-official/grok
  • Официальный установщик curl -fsSL https://x.ai/cli/install.sh | bash тоже работает, но хост x.ai заблокирован Cloudflare в ряде сред. Путь через npm обходит эту зависимость.
• Авторизация через SuperGrok / X Premium+ (основной способ):
  • Выполни grok login один раз — откроется браузер для OAuth, токен сохранится в ~/.grok/auth.json. Используется подписка SuperGrok или X Premium+ (без поштучного выставления счёта через API).
  • Проверить состояние авторизации: посмотри на наличие ~/.grok/auth.json или запусти дешёвый smoke-тест: grok --no-auto-update -p "Say ok."
  • В TUI: /logout — выйти, /login (или перезапуск) — войти снова.
• Git-репозиторий не нужен — в отличие от Codex, Grok спокойно работает за пределами git-директории (удобно для разовых задач).
• Совместим с Claude Code / AGENTS.md без какой-либо настройки — Grok автоматически читает CLAUDE.md, .claude/ (навыки, агенты, MCP, хуки, правила) и семейство AGENTS.md. Существующий контекст проекта подхватывается сразу.

Запасной вариант через API-ключ (не основной для этого пользователя): Grok поддерживает переменную окружения XAI_API_KEY для оплаты по факту использования через api.x.ai. Прибегай к этому только если grok login / авторизация SuperGrok недоступны. Основной сценарий — через подписку (grok login).

Два режима оркестрации

Режим 1: Headless (-p) — неинтерактивный (ПРЕДПОЧТИТЕЛЬНЫЙ)

Выполняет одиночную задачу, выводит результат и завершается. Без PTY, без диалоговых окон. Самый чистый способ интеграции — аналог claude -p и codex exec.

terminal(command="grok --no-auto-update -p 'Add a dark mode toggle to settings'", workdir="/path/to/project", timeout=180)

В любой автоматизации всегда передавай --no-auto-update, чтобы пропустить фоновую проверку обновлений.

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

• Одиночные задачи (исправить баг, добавить фичу, провести рефакторинг)
• Автоматизация CI/CD и скрипты
• Разбор структурированного вывода через --output-format json
• Любая задача без многоходового диалога

Режим 2: Интерактивный PTY — многоходовые TUI-сессии

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

# Launch in a tmux session for capture-pane monitoring
terminal(command="tmux new-session -d -s grok-work -x 140 -y 40")
terminal(command="tmux send-keys -t grok-work 'cd /path/to/project && grok' Enter")

# Wait for startup, then send a task
terminal(command="sleep 5 && tmux send-keys -t grok-work 'Refactor the auth module to use JWT' Enter")

# Monitor progress
terminal(command="sleep 15 && tmux capture-pane -t grok-work -p -S -50")

# Exit when done
terminal(command="tmux send-keys -t grok-work '/quit' Enter && sleep 1 && tmux kill-session -t grok-work")

Совет для headless с выводом в строку: если нужен TUI-подобный вывод без захвата полного экрана (например, для чистых логов), добавь --no-alt-screen. Но для чистой автоматизации headless -p всё равно предпочтительнее TUI.

Детальный разбор headless

Основные флаги

Форматы вывода

• plain — читаемый текст (по умолчанию)
• json — один JSON-объект по завершении (удобно для разбора результата)
• streaming-json — JSON-события, разделённые переносом строки, в реальном времени

# Structured result for parsing
terminal(command="grok --no-auto-update -p 'List all TODO comments in src/' --output-format json", workdir="/project", timeout=120)

# Auto-approve for autonomous building
terminal(command="grok --no-auto-update --always-approve -p 'Refactor the database layer and run the tests'", workdir="/project", timeout=300)

Фоновый режим (длительные задачи)

# Start headless in background
terminal(command="grok --no-auto-update --always-approve -p 'Refactor the auth module'", workdir="/project", background=true, notify_on_complete=true)
# Returns session_id

# Monitor
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

# Kill if needed
process(action="kill", session_id="<id>")

Для интерактивной (TUI) фоновой сессии используй pty=true + tmux и мониторь через tmux capture-pane — точно так же, как в навыках claude-code / codex.

Продолжение сессий

Сессии идентифицируются по UUID, а не по имени. --session-id присваивает новый UUID новому запуску (сессию он не возобновляет); --resume принимает UUID существующей сессии (без значения — возобновляет самую свежую).

# Start a session with a self-assigned UUID (must be a valid, unused UUID)
SID=$(uuidgen)
terminal(command="grok --no-auto-update -s $SID -p 'Start refactoring the database layer' --always-approve", workdir="/project", timeout=240)

# Resume that exact session later by its UUID
terminal(command="grok --no-auto-update -r $SID -p 'Now add connection pooling' --always-approve", workdir="/project", timeout=180)

# Or just continue the most recent session in this directory (no UUID needed)
terminal(command="grok --no-auto-update -c -p 'What did you change last time?'", workdir="/project", timeout=60)

Паттерн «только чтение → заметка в Markdown»

Чтобы Grok проанализировал локальные артефакты и вернул чистую markdown-заметку (для Obsidian или репозитория) без каких-либо изменений:

1. Сначала подготовь стабильные входные файлы инструментами Hermes (read_file, write_file). Сохрани только нужный контекст во временный файл — не скармливай сырые пути.
2. Запусти Grok headless без --always-approve, чтобы он не мог ничего записать автоматически; в промпте требуй markdown only, no preamble.
3. Stdout Grok сохрани напрямую в нужный файл через write_file().

grok --no-auto-update -p "Read ~/.hermes/cache/scratch/current.md and ~/.hermes/cache/scratch/inventory.md. Produce markdown only, no preamble. Output a clean note titled 'Cleanup Review'." --output-format plain

Подводный камень (такой же, как в Claude Code): при переработке документов расплывчатый промпт «rewrite this» может вернуть сводку изменений вместо полного файла. Решение: передай файл явно и потребуй Return ONLY the full revised markdown document. No intro, no explanation, no code fences. Start immediately with '# Title'. Перед перезаписью целевого файла проверь первые строки через read_file().

Паттерны ревью PR

Быстрое ревью (headless)

terminal(command="cd /path/to/repo && git diff main...feature-branch | grok --no-auto-update -p 'Review this diff for bugs, security issues, and style problems. Be thorough.'", timeout=120)

Ревью через клон во временную директорию (безопасно, репозиторий не трогается)

terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && grok --no-auto-update -p 'Review the changes vs origin/main. Check bugs, security, race conditions, missing tests.'", pty=true, timeout=300)

Опубликовать ревью

terminal(command="gh pr comment 42 --body '<review text>'", workdir="/path/to/repo")

Параллельное исправление задач через worktree

# Create worktrees
terminal(command="git worktree add -b fix/issue-78 ~/.hermes/cache/scratch/issue-78 main", workdir="~/project")
terminal(command="git worktree add -b fix/issue-99 ~/.hermes/cache/scratch/issue-99 main", workdir="~/project")

# Launch Grok headless in each (background)
terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #78: <description>. Commit when done.'", workdir="~/.hermes/cache/scratch/issue-78", background=true, notify_on_complete=true)
terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #99: <description>. Commit when done.'", workdir="~/.hermes/cache/scratch/issue-99", background=true, notify_on_complete=true)

# Monitor
process(action="list")

# After completion: push and open PRs
terminal(command="cd ~/.hermes/cache/scratch/issue-78 && git push -u origin fix/issue-78")
terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")

# Cleanup
terminal(command="git worktree remove ~/.hermes/cache/scratch/issue-78", workdir="~/project")

Полезные подкоманды и команды TUI

Слеш-команды TUI (только в интерактивном режиме): /model <name>, /always-approve, /plan, /context, /compact, /resume, /sessions, /fork, /usage, /quit. Shift+Tab переключает режимы сессии (в том числе Plan mode, который блокирует инструменты записи, кроме файла плана сессии).

Конфигурация (~/.grok/config.toml)

[cli]
auto_update = false          # skip background update checks persistently

[ui]
permission_mode = "ask"      # or "always-approve" to skip tool prompts by default

[models]
default = "grok-build-0.1"

Глобальные настройки храни в ~/.grok/config.toml (не в проектном .grok/config.toml). permission_mode заменяет устаревшие ключи approval_mode / yolo = true.

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

1. Авторизация требует подписки. grok login работает только при наличии SuperGrok или X Premium+. Если вход не удался или отсутствует ~/.grok/auth.json — сначала проверь, активна ли подписка, и только потом переходи к XAI_API_KEY.
2. Не путай xAI-авторизацию Hermes с авторизацией CLI grok. x_search в Hermes использует собственный xAI OAuth; у standalone-CLI grok отдельный токен в ~/.grok/auth.json. Работающий x_search не означает, что grok авторизован.
3. В автоматизации всегда передавай --no-auto-update — иначе Grok будет обращаться к серверу за обновлениями (а x.ai / storage.googleapis.com могут быть недоступны).
4. Предпочитай установку через npm вместо curl — npm install -g @xai-official/grok обходит хост x.ai, закрытый Cloudflare.
5. --always-approve — переключатель автономной сборки. Без него headless-запуски могут зависнуть в ожидании подтверждения инструментов. Намеренно опускай его при задачах только на чтение — ревью и аудит, — чтобы Grok не мог изменить файлы.
6. Headless -p пропускает диалоги TUI; TUI требует pty=true (+ tmux для мониторинга) — так же, как Claude Code.
7. Используй --no-alt-screen, если запускаешь TUI в строке и полноэкранный захват портит вывод.
8. Git-репозиторий не нужен, но для PR/commit-процессов он всё равно потребуется — для разовых задач с коммитами используй mktemp -d && git init.
9. Убирай tmux-сессии через tmux kill-session -t <name> по завершении.

Правила для агентов Hermes

1. Предпочитай headless -p для одиночных задач — самая чистая интеграция, структурированный вывод через --output-format json.
2. Всегда задавай workdir (или --cwd), чтобы Grok работал в нужном проекте.
3. Передавай --no-auto-update в каждом автоматическом вызове.
4. --always-approve — только когда Grok должен писать автономно; для ревью и аудита только на чтение его опускай.
5. Фоновые длительные задачи запускай с background=true, notify_on_complete=true и следи за ними через инструмент process.
6. Для многоходовых интерактивных сессий используй tmux и мониторь через tmux capture-pane -t <session> -p -S -50.
7. Проверяй авторизацию перед использованием — убедись в наличии ~/.grok/auth.json или запусти дешёвый smoke-тест grok -p "Say ok."; не рассчитывай, что xAI-авторизация Hermes распространяется на grok.
8. Сообщай пользователю о результатах — кратко опиши, что Grok изменил и что осталось сделать.