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
  1. Co to jest tryb headless w Claude Code
  2. Formaty wyniku
  3. Uprawnienia, gdy nikt nie klika zgody
  4. Claude Code w GitHub Actions
  5. Kiedy to ma sens w małej firmie

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.

bash
claude -p "Co robi moduł logowania w tym projekcie?"
cat build-error.txt | claude -p "wyjaśnij krótko przyczynę tego błędu" > wyjasnienie.txt

Tryb -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.

FormatCo dostajecie
textSam tekst odpowiedzi, domyślnie
jsonWynik w polu result plus identyfikator sesji i metadane
stream-jsonZdarzenia 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.

bash
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ń.

bash
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.

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 }}

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.

Kiedy najlepiej zadzwonić?
Administrator: Oleksandr Bondarenko (BondSoft)Polityka prywatnościRegulamin
Szczegóły prawne

Administratorem danych jest Oleksandr Bondarenko, prowadzący działalność gospodarczą pod firmą Oleksandr Bondarenko Software Solutions (BondSoft), ul. Jana Heweliusza 11, 80-890 Gdańsk, NIP 5833576264, e-mail: office@bondsoft.pl.

Dane przetwarzamy wyłącznie w celu kontaktu w sprawie Twojego zapytania i przedstawienia oferty — na podstawie Twojej zgody (art. 6 ust. 1 lit. a RODO oraz art. 398 ustawy Prawo komunikacji elektronicznej) oraz naszego prawnie uzasadnionego interesu polegającego na obsłudze zapytania (art. 6 ust. 1 lit. f RODO).

Podanie danych jest dobrowolne, ale niezbędne do kontaktu zwrotnego. Zgodę możesz wycofać w każdej chwili, pisząc na office@bondsoft.pl — nie wpływa to na zgodność z prawem przetwarzania sprzed wycofania.

Masz prawo dostępu do danych, ich sprostowania, usunięcia, ograniczenia przetwarzania, przenoszenia oraz wniesienia skargi do Prezesa Urzędu Ochrony Danych Osobowych.

Pełna informacja: Polityka prywatności.

Napiszcie e-mail

Usługa, o której jest ten tekst

Automatyzacja i AI / OCR

Automatyzacja przepisywania dokumentów, OCR i reguły sprawdzania, a dane zostają u Was.