Claude Code w trybie headless i CI. Flaga -p, wynik w JSON i Claude w GitHub Actions
Jak uruchomić Claude Code bez rozmowy, w skrypcie albo w pipeline. Flaga -p, formaty wyniku, dozwolone narzędzia, tryb --bare i oficjalna akcja do GitHub Actions.
Część przewodnikaClaude Code. Kompletny przewodnik od instalacji po własne skille i pluginy
W tym tekście
W skrócie
Flaga -p uruchamia Claude Code bez okna rozmowy, więc da się go wpiąć w skrypt, harmonogram albo pipeline. Wynik można dostać jako tekst, JSON albo strumień JSON, a listę narzędzi, których Claude może użyć bez pytania, podaje się flagą --allowedTools. Do GitHub Actions służy oficjalna akcja anthropics/claude-code-action, którą najprościej zainstalować poleceniem /install-github-app.
Build w nocy się wywrócił, a rano ktoś musi przeczytać długi log, żeby znaleźć jedną przyczynę. Ten sam log można przepuścić przez Claude Code jednym poleceniem w skrypcie i rano mieć gotowe wyjaśnienie w pliku. Tak wygląda Claude Code w trybie headless.
To tekst głównie dla programistów i osób, które utrzymują serwery albo CI. Należy do przewodnika po Claude Code. Flagi sprawdziliśmy w dokumentacji Anthropic o uruchamianiu z poziomu skryptów i o GitHub Actions, stan na 10 listopada 2026.
Co to jest tryb headless w Claude Code
Flaga -p, w pełnej wersji --print, uruchamia Claude Code bez interaktywnej sesji. Claude dostaje polecenie, pracuje, wypisuje wynik i kończy. Kod wyjścia to 0 przy sukcesie i inna liczba przy błędzie, więc skrypt może na tej podstawie zdecydować, co dalej.
claude -p "Co robi moduł logowania w tym projekcie?"
cat build-error.txt | claude -p "wyjaśnij krótko przyczynę tego błędu" > wyjasnienie.txtTryb -p czyta też standardowe wejście, więc działa jak każde inne narzędzie w potoku. Rozmowę można kontynuować flagą --continue albo --resume z identyfikatorem sesji.
Formaty wyniku
Format wybiera się flagą --output-format.
| Format | Co dostajecie |
|---|---|
text | Sam tekst odpowiedzi, domyślnie |
json | Wynik w polu result plus identyfikator sesji i metadane |
stream-json | Zdarzenia w kolejnych liniach JSON, na bieżąco |
Gdy wynik ma mieć stały kształt, dodajcie --json-schema ze schematem JSON. Dane trafią wtedy do pola structured_output. Jeśli Claude odmówi albo przerwie pracę, tego pola nie będzie, więc skrypt musi to sprawdzić, zanim go użyje.
claude -p "Wypisz nazwy głównych funkcji z auth.py" \
--output-format json \
--json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
| jq '.structured_output'Uprawnienia, gdy nikt nie klika zgody
W trybie -p nikt nie odpowie na pytanie o zgodę. Od wersji 2.1.302 taki przebieg startuje w trybie Manual, więc wywołanie, które wymaga zgody, zostanie odrzucone. Narzędzia dopuszcza się flagą --allowedTools, w tej samej składni co reguły uprawnień.
claude -p "Przejrzyj zmiany w stagingu i zrób commit z dobrym opisem" \
--allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"Spacja przed gwiazdką ma znaczenie. Bash(git diff *) pasuje do poleceń zaczynających się od git diff, a bez spacji pasowałoby też git diff-index. Zamiast listy narzędzi można ustawić tryb flagą --permission-mode. acceptEdits pozwala zmieniać pliki, dontAsk odrzuca wszystko, o co trzeba by pytać, a auto oddaje ocenę klasyfikatorowi. Więcej o regułach w tekście o uprawnieniach Claude Code.
Do CI dokumentacja zaleca flagę --bare. Claude Code nie wczytuje wtedy hooków, skilli, wtyczek, serwerów MCP, automatycznej pamięci ani CLAUDE.md, więc wynik nie zależy od tego, co leży na danej maszynie. Przy API Anthropic potrzebny jest wtedy klucz w zmiennej ANTHROPIC_API_KEY, bo logowanie z subskrypcji w tym trybie nie działa.
To ważne z jeszcze jednego powodu. Bez --bare przebieg -p uruchamia hooki z .claude/settings.json i łączy serwery z .mcp.json nawet w folderze, któremu nigdy nie zaufaliście. Przy cudzym repozytorium zawsze używajcie --bare albo najpierw przeczytajcie jego folder .claude. Dwie kolejne flagi ograniczają koszty. --max-turns ogranicza liczbę kroków, a --max-budget-usd zatrzymuje pracę, gdy szacowany wydatek na API dojdzie do podanej kwoty.
Claude Code w GitHub Actions
Oficjalna akcja to anthropics/claude-code-action. Najprościej zainstalować ją poleceniem /install-github-app w Claude Code, uruchomionym w folderze repozytorium. Działa tylko z repozytoriami na github.com, wymaga zainstalowanego i zalogowanego GitHub CLI oraz uprawnień administratora repozytorium.
Polecenie instaluje aplikację Claude na GitHubie, zapisuje sekret i przygotowuje pull request z plikiem workflow. Sekret to ANTHROPIC_API_KEY z kluczem API albo CLAUDE_CODE_OAUTH_TOKEN z subskrypcji. Token tworzy się poleceniem claude setup-token, a według dokumentacji działa na planach Pro, Max, Ultra, Team i Enterprise.
Po scaleniu wystarczy napisać @claude w komentarzu do zgłoszenia albo pull requesta. Taki workflow wygląda mniej więcej tak.
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 }}Gdy w workflow jest pole prompt, akcja działa bez wzmianki, na przykład według harmonogramu cron. Flagi CLI, takie jak --max-turns czy --allowedTools, przekazuje się w polu claude_args. Uruchomić Claude może tylko osoba z prawem zapisu do repozytorium, a boty są odrzucane, chyba że je dopiszecie.
Bez --bare polecenie claude -p ładuje też hooki projektu i serwery MCP z pliku .mcp.json, nawet w folderze, któremu nikt nie zaufał. Dlatego w CI zaczynamy od --bare.
Kiedy to ma sens w małej firmie
Firma, która ma jedną stronę i jednego wykonawcę, zwykle tego nie potrzebuje. Tryb headless przydaje się tam, gdzie kod żyje w repozytorium i ktoś regularnie przegląda zmiany. Dobre pierwsze zadania to wyjaśnianie błędów z nocnego builda, przegląd pull requestów i cotygodniowy raport z commitów, wszystko z narzędziami tylko do odczytu.
Zacznijcie od jednego polecenia claude -p z --bare i listą narzędzi tylko do odczytu, a uprawnienia do zapisu dodawajcie dopiero, gdy wynik się sprawdzi. Jeśli chcecie wiedzieć, które procesy w Waszej firmie da się tak zautomatyzować, zamówcie bezpłatny audyt AI.
Dokumentacja do tematu
Co chcecie zmienić w swojej firmie?
Zostawcie numer. Porozmawiamy o Waszym procesie i sprawdzimy, czy możemy pomóc. Pierwsza rozmowa jest bezpłatna.
Usługa, o której jest ten tekst
Automatyzacja i AI / OCRAutomatyzacja przepisywania dokumentów, OCR i reguły sprawdzania, a dane zostają u Was.