claude -p: как запускать Claude Code в скриптах (headless)

claude -p: Claude Code в скриптах

claude -p выполняет один запрос без интерфейса, печатает ответ и завершается — так Claude Code встраивается в скрипты. С --output-format json результат можно разобрать, а режим разрешений нужно передавать всегда.

До сих пор Claude Code работал в диалоге: ты спрашиваешь, он отвечает, ты одобряешь. Но иногда нужен Claude без собеседника — в скрипте, по расписанию, в CI. Для этого есть .

Один запрос — один запуск

claude -p "В одном предложении: что делает этот репозиторий?"

Claude Code выполняет запрос, печатает ответ и завершается: с кодом 0, если всё прошло, и ненулевым при сбое. Он читает и stdin, поэтому скрипт может передать на вход, например, дифф:

git diff | claude -p "Найди в этом диффе очевидные ошибки" --permission-mode dontAsk

Ответ, который можно разобрать

С флагом --output-format json вместо текста приходит один JSON-объект:

{"type":"result","subtype":"success","is_error":false,"num_turns":2,"result":"…","session_id":"…","permission_denials":[]}

result — сам ответ;
is_error — была ли ошибка;
subtype — success или причина ранней остановки, например error_max_turns;
num_turns — сколько ходов понадобилось;
permission_denials — какие действия были отклонены.

Важно: если прогон остановился по лимиту, поля result нет вовсе. Поэтому сначала проверяй код выхода и is_error, и только потом бери ответ.

Режим — всегда явно

В скрипте некому ответить на вопрос о разрешении. Поэтому режим передают всегда: прогон, где его ничто не задаёт, может стартовать в режиме auto.

Три флага задают рамки:

--permission-mode dontAsk — отклоняет всё, что в сессии потребовало бы вопроса;
--allowedTools — перечисляет, что всё-таки можно, например "Bash(npm test *)";
--max-turns — ограничивает число ходов.

claude -p "Прогони тесты и скажи, сколько прошло" \
  --output-format json --permission-mode dontAsk \
  --allowedTools "Bash(npm test *)" --max-turns 3

Пробел перед * важен: Bash(npm test *) разрешает npm test с любыми аргументами, включая запуск без аргументов.

Мини-проверка

Скрипт вызывает claude -p и сразу берёт поле result из JSON. Иногда скрипт падает с ошибкой «result is undefined». Почему?

Осторожно

Запуск claude -p не показывает диалог доверия: он выполнит хуки из .claude/settings.json проекта и подключит серверы из .mcp.json даже в папке, которой ты никогда не доверял. Запуская Claude из скрипта в чужом репозитории, добавляй --setting-sources user — тогда настройки и MCP проекта не загрузятся. И помни: если задана переменная ANTHROPIC_API_KEY, такой запуск тратит этот ключ, а не твою подписку.

Практика в терминале

Запусти claude -p с запросом в кавычках, флагами --output-format json и --permission-mode dontAsk. Попробуй и без --permission-mode — тренажёр предупредит, чем это опасно.

Проверь себя

Отвечено 0/3

Режим:

Что делает claude -p "запрос"?

Почему в claude -p нужно всегда передавать --permission-mode?

Что проверить в JSON-ответе, прежде чем использовать поле result?

Вопросы и ответы по уроку

Что делает claude -p "запрос"?

-p — неинтерактивный запуск: один запрос, ответ, выход. Поэтому его можно вызывать из скриптов и CI.

Почему в claude -p нужно всегда передавать --permission-mode?

В скрипте никто не нажмёт «Да». Режим dontAsk отклоняет всё, что потребовало бы вопроса, а без режима прогон может начаться в auto.

Что проверить в JSON-ответе, прежде чем использовать поле result?

subtype бывает success или причиной ранней остановки, например error_max_turns, — тогда result отсутствует. Сначала проверь код выхода и is_error.

Скрипт вызывает claude -p и сразу берёт поле result из JSON. Иногда скрипт падает с ошибкой «result is undefined». Почему?

При ранней остановке subtype сообщает причину, например error_max_turns, а поля result в ответе нет. Код выхода и is_error говорят об этом раньше.