Headless-режим Claude Code: -p, CI и GitHub Action
Скриптуйте Claude Code как Unix-инструмент: одноразовые промпты через claude -p, файлы по pipe, парсинг JSON на выходе, возобновление сессий по id, --bare для CI и @claude GitHub Action, собирающая фичу из issue, — straight из собственного разбора Anthropic.
Коротко
- claude -p "prompt" выполняется один раз и печатает результат — без интерактивной сессии. Компонуется как любой Unix-инструмент: pipe на входе, pipe на выходе, цепочки в скриптах и шагах CI.
- --output-format json возвращает результат плюс session_id, затраты и метаданные; stream-json выдаёт события с разделением по строкам для потребителей в реальном времени. Парсите jq-ом и надстраивайте своё.
- Headless стартует без правок и деструктивных разрешений. Выдайте ровно необходимое через --allowedTools "Bash(git diff *),Edit" — синтаксис правил разрешений, совпадение по префиксу.
- @claude GitHub Action — это headless с фронтендом: отметьте @claude в issue или PR, и он читает код, создаёт PR и коммиты, отвечает на вопросы и ревьюит изменения — на ваших собственных GitHub-раннерах.
Building headless automation with Claude Code | Code w/ Claude
Канал: Anthropic20:59
Headless mode — official documentation
Официальная документация: code.claude.com/docs
Claude Code GitHub Action — official docs
Официальная документация: code.claude.com/docs
Флаги, лимиты и поведение на этой странице сверены с официальной документацией по headless; доклад выше — собственный разбор Anthropic и визуальный источник скриншотов.
Скриншоты принадлежат их авторам и снабжены прямыми ссылками на точные таймкоды. Кадры спикера и зала не используются.
Запускаем Claude Code headless, шаг за шагом
Часть 1 — Основы headless
- 1
Что такое headless-режим
Headless-режим — это Claude Code без интерактивного UI: тот же агент, управляемый программно. Anthropic подаёт его как простой строительный блок для агентных приложений — используйте как Unix-инструмент в скриптах и пайплайнах, для CI-автоматизации, удалённых сред или как движок за веб-чатом.
Формулировка самого Anthropic: SDK — это программный доступ к Claude Code в headless-средах.Смотреть на 2:10 - 2
Одноразовые промпты через claude -p
Флаг -p (--print) выполняет один промпт и завершается: claude -p "Write me a function that calculates the Fibonacci sequence". Ничего не остаётся открытым — вы получаете вывод в stdout и код выхода, который могут проверять ваши скрипты. Права на запись выдавайте заранее через --allowedTools.
Одноразовый запрос: claude -p генерирует функцию Фибоначчи и выходит — ни TUI, ни уточняющих вопросов.Смотреть на 3:30 - 3
Пайпите файлы прямо в Claude
Stdin работает как у любого CLI-инструмента: cat app.log | claude -p "summarize the most common error logs". В демо Anthropic 2000 строк лога на входе превращаются в понятный человекам свод ошибок — тот же трюк подходит для падений сборки, стек-трейсов и экспортов. Пайп stdin ограничен 10 МБ.
cat плюс символ pipe плюс claude -p: две тысячи строк лога становятся диагнозом в три предложения.Смотреть на 3:55 - 4
Расшифруйте вывод, который ненавидите читать
Тот же приём превращает враждебный вывод в ответы: ifconfig | claude -p "what interfaces do I have configured? don't include lo". Всё, что печатает команда, — состояние сети, ошибки компилятора, планы terraform — можно прогнать через Claude ради человекочитаемой сводки.
ifconfig, пропущенный через claude -p: каждый интерфейс объяснён, loopback исключён по просьбе.Смотреть на 4:15 - 5
Получите структурированный JSON
Добавьте --output-format json — и ответ станет парсируемым объектом: текст результата, session_id, длительность и total_cost_usd. Живым потребителям — --output-format stream-json: события построчно, по мере появления; последняя строка и есть итоговый результат.
JSON-режим: один блоб с результатом, id сессии на будущее возобновление и стоимостью прогона.Смотреть на 4:35
Часть 2 — Скриптуем по-инженерному
- 6
Выдавайте инструменты осознанно
Headless стартует без правок и деструктивных разрешений. --allowedTools заранее одобряет то, что нужно задаче, по синтаксису правил разрешений: --allowedTools "Bash(npm run build),Bash(npm test:*),Write". MCP-инструменты заносятся в allow-лист так же — выдавайте самый узкий набор, которым работа делается.
Глубокое погружение в SDK: права инструментов, режимы структурированного вывода и кастомные системные промпты — на одном слайде.Смотреть на 11:00 - 7
Держите контекст между запусками
JSON-режим возвращает session_id — передайте его обратно с --resume "$session_id", чтобы продолжить то же состояние диалога из следующего запуска или другого процесса. Так и строятся интерактивные продукты поверх: пользователь говорит, Claude отвечает, вы сохраняете сессию к следующему ходу.
- 8
Разрешения без человека рядом
Если заранее не угадать, какие инструменты понадобятся Claude, --permission-prompt-tool перекладывает решения об одобрении на MCP-сервер в рантайме — тот спрашивает ваш сервис (или пользователя через ваше приложение), пропускать ли каждое действие, вместо того чтобы перечислять всё заранее.
- 9
Для CI берите --bare
--bare пропускает автопоиск hooks, skills, кастомных команд, субагентов, плагинов, MCP-серверов и CLAUDE.md ради максимально быстрого старта — рекомендован для скриптов и CI и готовится стать дефолтом для -p. Требует ANTHROPIC_API_KEY; контекст передаётся явно флагами.
Часть 3 — @claude GitHub Action
- 10
Знакомьтесь: @claude GitHub Action
GitHub Action — это headless с фронтендом поверх SDK. Отметьте @claude в любом PR или issue, и он сможет читать ваш код, создавать PR, докидывать коммиты в существующие, отвечать на вопросы и ревьюить изменения — на уже имеющихся у вас GitHub-раннерах, так что нянчить инфраструктуру не придётся.
Контракт Action: отметь @claude, опиши, что нужно, — и он поработает над репозиторием на твоих раннерах.Смотреть на 17:10 - 11
Назначьте issue Клоду
В живой демонстрации Anthropic комментарий "@claude please implement this feature and comment on it" заставил бота ответить планом со скоупом — маркированным списком того, что он построит, — и лишь затем создать ветку, коммиты и pull request; всё отслеживается в логах Action.
Комментарий @claude в настоящем issue: Claude отвечает планом со скоупом, не тронув ни строчки кода.Смотреть на 7:50 - 12
Установите на свой репозиторий
Результат — чек-лист реализации на issue: фичи добавлены, тудушки закрыты. Чтобы добиться этого, откройте Claude Code в репозитории и выполните /install-github-action: интерактивный флоу откроет PR с workflow YAML, дальше — настроить API-ключи как секреты репозитория и вмержить.
Готовый прогон: чек-лист реализации со всеми фичами, которые Action добавила в демо-приложение.Смотреть на 13:30
Headless vs интерактивный vs SDK vs GitHub Action
Четыре способа управлять одним и тем же агентом — выбирайте по тому, кто (или что) спрашивает:
- 1Интерактивный CLI — сессия в TUI: запросы разрешений, plan-режим, /команды. Лучше всего для человека, который ведёт задачу прямо сейчас.
- 2Headless claude -p — один программный выстрел: stdin и stdout, коды выхода, без UI. Для скриптов, cron-задач и быстрых вопросов из других инструментов.
- 3Agent SDK — та же headless-мощь в виде типизированной библиотеки: многоходовые сессии, кастомные инструменты, стриминг. Когда Claude — компонент внутри вашего приложения.
- 4@claude GitHub Action — headless на событийной модели GitHub: issue, PR и ревью на ваших раннерах. Для автоматизации в масштабе репозитория, которую может запустить вся команда.
- 5--bare headless — урезанный старт для CI: без CLAUDE.md, hooks, skills, плагинов и автопоиска MCP, контекст явно флагами, самый быстрый холодный старт.
Доступ к модели и система разрешений у них общие — правило, выданное headless, действует везде, потому дисциплина с --allowedTools так важна.
Headless капризничает? Скорая помощь
Пять headless-специфичных граблей и как с ними обходиться:
- 1Скрипт завершается раньше Claude. Проверяйте код выхода: 0 — успех, всё остальное — провал. SIGTERM выходит с 143 и оставляет ход незаконченным — если нужно прервать посреди хода, завершайте через SIGINT или interrupt() из SDK.
- 2Пайп-вход тихо обрезается. Stdin ограничен 10 МБ — более крупные данные пишите в файл и ссылайтесь на путь в промпте.
- 3"--bg rejected" или ошибка --cloud. Флаги интерактивного режима к -p не применяются: --bg отклоняется сразу, а --cloud требует session id для постановки сообщения в очередь, а не описания задачи.
- 4Прогон CI игнорирует ваши CLAUDE.md и hooks. Это --bare делает свою работу: пропускает автопоиск. Передавайте контекст явно через --settings, --mcp-config, --agents или --plugin-dir.
- 5Фоновые bash-задачи умирают на середине. Фоновые шеллы убиваются примерно через 5 секунд после получения результата; субагенты и workflow держат процесс до лимита в 10 минут простоя. В CI ждите их явно.
Во всех прочих случаях добавьте --verbose и читайте события stream-json — system/init называет реально загруженные модель, инструменты и MCP-серверы.