Claude Code умеет работать без чата: одна команда claude -p делает задачу и печатает результат. Это превращает агента в кирпичик для скриптов, пайпов и CI. Разберём флаги, JSON-вывод и права для автоматизации.
Обычно Claude Code — это интерактивный чат в терминале: ты пишешь, агент отвечает, ты подтверждаешь действия. Но у него есть второй режим — headless (без «головы», то есть без интерфейса диалога). В нём ты даёшь одну задачу через флаг, агент её делает и сразу выходит, напечатав результат. Это и есть мост между «поболтать с ИИ» и «встроить ИИ в скрипт»: cron-задача, pre-commit хук, шаг в CI — везде, где нужен разовый вызов без человека за клавиатурой.
Что узнаешь из гайда
-pjqЧасть 1 · Понятие
Главное
Headless — это запуск без чата: claude -p "задача" делает одну задачу и печатает ответ. Сессия не висит, это разовый вызов для скриптов.
Расшифруем по словам. Headless дословно — «безголовый», то есть программа работает без своего интерфейса. Для Claude Code это значит: нет диалога, нет ожидания твоих ответов. Флаг -p (полная форма --print, от «print» — печать) включает этот режим: агент берёт задачу, выполняет и пишет результат в стандартный вывод (stdout — это то, что обычно появляется в терминале и что можно перенаправить в файл или другую команду).
Зачем это нужно. Интерактивный чат хорош, когда ты сидишь и думаешь вместе с агентом. Но если задача повторяемая («каждое утро собери сводку по логам», «на каждый коммит проверь стиль») — сидеть и подтверждать руками глупо. Headless даёт ровно одно: запустить задачу без человека и забрать результат программно.
| Режим | Как идёт | Для чего |
|---|---|---|
| Интерактивный | Диалог, подтверждения | Совместная работа над задачей |
| Headless (-p) | Одна задача → ответ → выход | Скрипты, cron, CI, пайпы |
Часть 2 · Старт
Главное
Минимум — это claude -p "задача". Все обычные флаги работают и в этом режиме, включая --continue для продолжения прошлого разговора.
Самая короткая форма — задача строкой после -p. Агент выполнит и напечатает ответ:
# Одна задача — один ответ в stdout
claude -p "перечисли все API-эндпоинты в этом проекте"
# Результат можно сразу перенаправить в файл
claude -p "сделай краткое README по проекту" > README.draft.mdВ headless доступны те же флаги, что и в чате. Полезные: --continue продолжает прошлый разговор (контекст не теряется между вызовами), --allowedTools заранее разрешает инструменты, --output-format задаёт формат ответа. Про контекст между сессиями подробнее — в гайде про память между сессиями.
Часть 3 · Формат
Главное
Для скрипта нужен предсказуемый формат. Флаг --output-format json отдаёт структурированный JSON, из которого результат достаёшь через jq.
Простой текст в ответе тяжело разбирать программно: он каждый раз разный. JSON — это строгий формат, у которого всегда одни и те же поля. Просишь его флагом, а нужное значение вытаскиваешь утилитой jq (парсер JSON для терминала):
# Получаем структурированный JSON вместо простого текста
claude -p "Summarize this project" --output-format json
# Достаём только текст результата через jq (-r — без кавычек)
claude -p "Summarize this project" --output-format json | jq -r '.result'Для длинных ответов есть --output-format stream-json: результат приходит потоком по мере генерации, а не одним куском в конце. Это удобно, когда задача большая и хочется показывать прогресс или обрабатывать события на лету.
Важно
Если парсишь вывод в скрипте — всегда бери --output-format json и тяни поле .result, а не обычный текст. Текстовый формат для людей: его структура может меняться, и скрипт сломается. JSON — это контракт, на него можно опереться.
Часть 4 · Сборка
Главная сила headless — пайп. Пайп (символ |) передаёт вывод одной команды на вход другой. Можно скормить Claude файл, лог или вывод любой утилиты, и он обработает их без копипаста в чат:
# Передаём содержимое файла с ошибкой сборки прямо в Claude
cat build-error.txt | claude -p 'кратко объясни корневую причину этой ошибки сборки' > output.txt
# Цепочка: лог → Claude → файл
cat logs.txt | claude -p "выдели только повторяющиеся ошибки"Дальше из этих вызовов собирается обычный bash-скрипт. Вот пример ежедневной сводки, которую можно повесить на cron (планировщик задач):
#!/usr/bin/env bash
# Собираем коммиты за сутки и просим Claude сделать сводку
git log --since="1 day ago" --oneline \
| claude -p "сделай короткую сводку изменений за день для команды" \
--output-format json \
| jq -r '.result' > daily-summary.mdHeadless — это кирпичик. Из него собирают скрипты, хуки и пайплайны.
Коротко
| скармливает Claude файл, лог или вывод команды без копипаста.--output-format json + jq.Часть 5 · Безопасность
Главное
В headless нет человека, который подтвердит действие. Поэтому права задаются заранее флагами: --allowedTools и --permission-mode.
В интерактиве ты подтверждаешь опасные действия вручную. В скрипте подтверждать некому, поэтому либо агент спотыкается о каждый запрос, либо ему заранее очерчивают границы. Делается это двумя флагами:
# Разрешаем только нужные инструменты — остальное недоступно
claude -p "прогони тесты и почини падающие" --allowedTools "Bash(npm test:*)" "Edit"
# Для предсказуемых правок (линт, формат) — режим, который пишет файлы без вопросов
claude -p "примени фиксы линтера" --permission-mode acceptEditsКогда не надо
Не запускай в CI режим, который обходит проверки прав полностью, на ветке с доступом к секретам и проду. Headless опасен именно тем, что никто не остановит агента в моменте. Узкий --allowedTools под конкретную задачу всегда лучше широкого «разреши всё». Разбор прав целиком — в гайде про безопасность и права.
Где headless окупается
Типовые задачи: автоген changelog по коммитам, разбор логов CI, фикс линта на pre-commit, ночная сводка по проекту. Везде, где задача повторяема и узкая, headless экономит время. Где нужно думать вместе — оставайся в чате.
Коротко
-p запускает задачу без чата и печатает результат в stdout.--output-format json + jq — для машинного разбора ответа.--allowedTools, а не обход проверок на проде.Вопросы
Headless — это запуск Claude Code без интерактивного чата: команда claude -p "задача" выполняет одну задачу и сразу печатает результат в терминал. Флаг -p (он же --print) переводит агента в неинтерактивный режим, удобный для скриптов, пайпов и CI-пайплайнов. Сессия не остаётся открытой — это разовый вызов, который можно встроить в любую автоматизацию.
Без флага claude открывает интерактивный чат, где ты ведёшь диалог и подтверждаешь действия. С флагом -p агент получает задачу как аргумент или через пайп, делает её и выходит, печатая ответ в stdout. Это разница между «сесть и поговорить» и «дать одно поручение и забрать результат» — второе встраивается в скрипты и cron.
Добавь флаг --output-format json: claude -p "задача" --output-format json вернёт JSON, который удобно парсить программно. Дальше результат вытаскивают через jq, например claude -p "..." --output-format json | jq -r '.result'. Есть и --output-format stream-json для потоковой обработки длинных ответов по мере генерации.
Безопасно при явном ограничении прав: в headless нет человека, который подтверждает действия, поэтому права задаются заранее. Флаг --allowedTools разрешает только нужные инструменты, --permission-mode acceptEdits даёт писать файлы без вопросов для предсказуемых задач вроде линт-фиксов. Никогда не вешай в CI режим, обходящий проверки полностью, на ветку с доступом к секретам и проду.
Читать дальше
Прикладной материал, разборы и рабочие приёмы — то, чем пользуюсь сам, без воды. Залетай, там самое полезное.
Зайти в Telegram