Claude Code в режимі headless і CI. Прапорець -p, результат у JSON і Claude в GitHub Actions

Як запустити Claude Code без розмови, у скрипті чи пайплайні. Прапорець -p, формати результату, дозволені інструменти, режим --bare і офіційна дія для GitHub Actions.

Частина посібникаClaude Code, повний посібник. Від встановлення до власних скілів і плагінів

У цьому тексті
  1. Що таке режим headless у Claude Code
  2. Формати результату
  3. Дозволи, коли ніхто не натискає згоду
  4. Claude Code в GitHub Actions
  5. Коли це має сенс для малої фірми

Коротко

Прапорець -p запускає Claude Code без вікна розмови, тож його можна вбудувати в скрипт, розклад або пайплайн. Результат буває текстом, JSON або потоком JSON, а список інструментів, якими Claude може користуватися без питання, задають прапорцем --allowedTools. Для GitHub Actions є офіційна дія anthropics/claude-code-action, яку найпростіше встановити командою /install-github-app.

Нічна збірка впала, і зранку хтось мусить читати довгий лог, щоб знайти одну причину. Той самий лог можна пропустити через Claude Code одним рядком у скрипті, і зранку пояснення вже лежатиме у файлі. Так виглядає Claude Code в режимі headless.

Цей текст переважно для програмістів і тих, хто доглядає сервери чи CI. Він входить до путівника по Claude Code. Прапорці ми звірили з документацією Anthropic про запуск зі скриптів і про GitHub Actions, станом на 10 листопада 2026.

Що таке режим headless у Claude Code

Прапорець -p, повна форма --print, запускає Claude Code без інтерактивної сесії. Claude отримує завдання, працює, виводить результат і завершується. Код виходу 0 означає успіх, інше число означає помилку, тож скрипт може на цьому будувати логіку.

bash
claude -p "Що робить модуль входу в цьому проєкті?"
cat build-error.txt | claude -p "коротко поясни причину цієї помилки збірки" > poiasnennia.txt

Режим -p читає й стандартний вхід, тож працює як будь-який інший інструмент у конвеєрі. Розмову можна продовжити прапорцем --continue або --resume з ідентифікатором сесії.

Формати результату

Формат задають прапорцем --output-format.

ФорматЩо ви отримуєте
textЛише текст відповіді, типово
jsonВідповідь у полі result, ідентифікатор сесії й метадані
stream-jsonПодії окремими рядками JSON, у реальному часі

Коли результат має мати сталу форму, додайте --json-schema зі схемою JSON. Дані тоді потраплять у поле structured_output. Якщо Claude відмовиться або зупиниться раніше, цього поля не буде, тож скрипт має його перевірити.

bash
claude -p "Випиши назви головних функцій з auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

Дозволи, коли ніхто не натискає згоду

У режимі -p ніхто не відповість на запит дозволу. Починаючи з версії 2.1.302 такий запуск стартує в режимі Manual, тож виклик, що потребує згоди, буде відхилено. Інструменти дозволяють прапорцем --allowedTools у тому самому синтаксисі, що й правила дозволів.

bash
claude -p "Переглянь зміни в staging і зроби коміт з нормальним описом" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

Пробіл перед зірочкою важливий. Bash(git diff *) підходить до команд, що починаються з git diff, а без пробілу підійшла б і git diff-index. Замість списку інструментів можна задати режим прапорцем --permission-mode. acceptEdits дозволяє змінювати файли, dontAsk відхиляє все, про що довелося б питати, а auto передає оцінку класифікатору. Про правила ми пишемо в тексті про дозволи Claude Code.

Для CI документація радить прапорець --bare. Тоді Claude Code не завантажує хуків, скілів, плагінів, серверів MCP, автоматичної пам'яті й CLAUDE.md, тож результат не залежить від того, що лежить на конкретній машині. Для API Anthropic потрібен ключ у змінній ANTHROPIC_API_KEY, бо вхід через підписку в цьому режимі не працює.

Це важливо ще з однієї причини. Без --bare запуск -p виконує хуки з .claude/settings.json і підключає сервери з .mcp.json навіть у папці, якій ви ніколи не довіряли. З чужим репозиторієм завжди використовуйте --bare або спершу прочитайте його папку .claude. Ще два прапорці стримують витрати. --max-turns обмежує кількість кроків, а --max-budget-usd зупиняє роботу, коли оцінені витрати на API дійдуть до вказаної суми.

Claude Code в GitHub Actions

Офіційна дія це anthropics/claude-code-action. Найпростіше встановити її командою /install-github-app у Claude Code, запущеному в папці репозиторію. Вона працює лише з репозиторіями на github.com, потребує встановленого й залогіненого GitHub CLI і прав адміністратора репозиторію.

Команда встановлює застосунок Claude на GitHub, зберігає секрет і готує pull request з файлом workflow. Секрет це ANTHROPIC_API_KEY з ключем API або CLAUDE_CODE_OAUTH_TOKEN з підписки. Токен створюють командою claude setup-token, і за документацією він працює на планах Pro, Max, Ultra, Team і Enterprise.

Після злиття досить написати @claude у коментарі до задачі або pull request. Workflow виглядає приблизно так.

yaml
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Якщо у workflow є поле prompt, дія працює без згадки, наприклад за розкладом cron. Прапорці CLI, як-от --max-turns чи --allowedTools, передають у полі claude_args. Запустити Claude може лише людина з правом запису в репозиторій, а ботів відхиляють, якщо ви їх не дописали.

Без --bare команда claude -p завантажує ще й хуки проєкту та сервери MCP з файлу .mcp.json, навіть у теці, якій ніхто не довіряв. Тому в CI ми починаємо з --bare.

Коли це має сенс для малої фірми

Фірмі з одним сайтом і одним підрядником це зазвичай не потрібно. Режим headless корисний там, де код живе в репозиторії і хтось регулярно переглядає зміни. Добрі перші задачі це пояснення помилок нічної збірки, перегляд pull request і щотижневий звіт про коміти, усе з інструментами лише для читання.

Почніть з однієї команди claude -p з --bare і інструментами лише для читання, а права на запис додавайте, коли результат себе виправдає. Якщо хочете знати, які процеси у вашій фірмі можна так автоматизувати, замовте безкоштовний аудит AI.

Документація до теми

Що хочете змінити у своїй фірмі?

Залиште номер. Поговоримо про ваш процес і перевіримо, чи можемо допомогти. Перша розмова безкоштовна.

Коли зручно зателефонувати?
Адміністратор: Oleksandr Bondarenko (BondSoft)Політика конфіденційностіРегламент
Юридичні деталі

Адміністратором даних є Oleksandr Bondarenko, що веде господарську діяльність під фірмою Oleksandr Bondarenko Software Solutions (BondSoft), ul. Jana Heweliusza 11, 80-890 Gdańsk, NIP 5833576264, e-mail: office@bondsoft.pl.

Дані обробляємо виключно з метою контакту у справі вашого запиту та надання пропозиції — на підставі вашої згоди (ст. 6 ч. 1 п. a RODO та ст. 398 закону Prawo komunikacji elektronicznej) і нашого правомірного інтересу, що полягає в опрацюванні запиту (ст. 6 ч. 1 п. f RODO).

Надання даних добровільне, але необхідне для зворотного контакту. Згоду можете відкликати будь-коли, написавши на office@bondsoft.pl — це не впливає на законність обробки до відкликання.

Ви маєте право на доступ до даних, їх виправлення, видалення, обмеження обробки, перенесення, а також на скаргу до Голови Управління охорони персональних даних.

Повна інформація: Політика конфіденційності.

Напишіть на пошту

Послуга, про яку цей текст

Автоматизація та AI / OCR

Автоматизація переписування документів, OCR і правила перевірки, а дані лишаються у вас.