Background tasks i headless mode | Kurs Claude AI

Background tasks

Background tasks to możliwość uruchamiania długich procesów w tle sesji - budowanie, testy czy serwer deweloperski nie blokują dalszej rozmowy.

Uwaga na nazwy, bo „tło” oznacza w Claude Code dwie różne rzeczy. Flaga claude --bg "opis zadania" (długa forma --background) uruchamia całą sesję jako agenta w tle i od razu oddaje terminal. Takie sesje podglądasz poleceniem claude agents w widoku agentów (agent view, research preview, czyli wersja testowa, od wersji 2.1.139). Z działającej sesji to samo robi komenda /background (alias /bg). Pojedyncze zadania w tle wewnątrz sesji uruchamiasz na trzy sposoby:

Poproś Claude: „uruchom serwer deweloperski w tle” - Claude wykona komendę Bash w tle i dostanie ID zadania
Skrót Ctrl+B: przenosi właśnie działającą komendę Bash albo subagenta do tła (w tmux naciśnij dwa razy)
Subagenci: od wersji 2.1.198 działają w tle domyślnie - delegowane zadania z natury nie blokują sesji

Output zadania trafia do pliku, a Claude czyta go na bieżąco narzędziem Read - stąd biorą się powiadomienia w stylu „testy przeszły” bez Twojego pytania. Podgląd wszystkiego, co biegnie w tle (shelle i subagenci): komenda /tasks (alias /bashes). Ile to kosztuje i ile limitu zostało, sprawdzasz w trakcie komendą /usage (aliasy /cost, /stats) - przy długich zadaniach w tle zaglądaj tam, zanim skończy się okno 5-godzinne.

Ile outputu komendy Bash lub PowerShell trafia do modelu wprost, reguluje ustawienie bashOutputMaxChars: zakres 4000-128 000 znaków, domyślnie 30 000. Reszta zostaje w pliku, z którego Claude czyta wybrane fragmenty. Ustawienie taskOutputMaxChars i narzędzie TaskOutput usunięto w wersji 2.1.277. Jeśli znasz je ze starszych poradników, dziś nic nie robią.

Zastosowania:

Uruchamianie serwera deweloperskiego w tle
Testy w tle podczas dalszej pracy
Monitorowanie logów
Długotrwałe budowanie projektu

Zabezpieczenia:

Komenda w tle ma limit czasu: 30 minut albo czas podany przez Claude, najwyżej 2 godziny (wymaga 2.1.285 lub nowszej). Po tym czasie Claude Code ją zatrzymuje
Zadanie w tle jest automatycznie przerywane, gdy jego output przekroczy 5 GB (z notką w stderr, dlaczego)
Zadania w tle sprzątają się przy wyjściu z sesji. Przeniesienie sesji do tła przez /background to nie wyjście: sesja i jej zadania działają dalej
Całą funkcję wyłączysz zmienną środowiskową: CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 (wyłącza też Ctrl+B i automatyczne przenoszenie do tła)

Headless mode (--print)

Uruchomienie Claude Code bez interaktywnej sesji. Prompt wchodzi, wynik wychodzi.

Uprawnienia: sesje interaktywne w terminalu i VS Code startują dziś w trybie auto na każdym planie (wymaga 2.1.284 lub nowszej). Inny tryb wpisany w permissions.defaultMode nadal ma pierwszeństwo.

claude -p startuje inaczej. W sesji, która pobiera od Anthropic flagi funkcji (feature flags), rusza w trybie default. Bez nich, czyli u dostawców zewnętrznych (Bedrock, Google Cloud, Foundry) albo z wyłączoną telemetrią, od wersji 2.1.285 rusza w trybie auto.

W skrypcie nikt nie odpowie na pytanie o pozwolenie, więc takie wywołania są odrzucane. Tryb ustaw jawnie: --permission-mode acceptEdits (zapis plików bez pytania), --permission-mode dontAsk z listą --allowedTools albo --permission-mode auto. Do tego reguły allow w settings.json albo izolowane środowisko (o tym niżej).

# Podstawowe
claude -p "Opisz ten projekt"

# Z modelem i zgodą na edycję plików
claude -p "Napraw bug w auth.ts" --model opus --permission-mode acceptEdits

# Z formatem wyjścia
claude -p "Opisz architekturę" --output-format json

Formaty wyjścia

Format	Opis	Użycie
`text`	Surowy tekst (domyślny)	Proste skrypty
`json`	Strukturalny JSON	Parsowanie wyników
`stream-json`	Zdarzenia w JSON Lines na bieżąco (pojedyncze tokeny dopiero z `--verbose --include-partial-messages`)	Przetwarzanie na żywo

Pipe + headless

# Analiza logów
cat error.log | claude -p "Znajdź przyczynę błędu"

# Review kodu
git diff | claude -p "Review tych zmian" --output-format json

# Automatyczne naprawianie testów (zgoda na edycję plików)
npm test 2>&1 | claude -p "Napraw padające testy" --permission-mode acceptEdits

Sesje w chmurze i poza terminalem

Stan na 1 października 2026: zadanie w tle nie musi już mieszkać w Twoim terminalu. Claude Code działa na pięciu powierzchniach - terminal, VS Code, JetBrains, aplikacja desktopowa i web (claude.ai/code) - i pozwala przenosić sesję między nimi:

claude --cloud "opis zadania" zakłada NOWĄ sesję w chmurze dla bieżącego repozytorium. Zadanie biegnie na maszynie wirtualnej Anthropic albo we własnym środowisku organizacji (self-hosted environment), a Ty możesz zamknąć laptopa. Istniejącej sesji z terminala do chmury nie przeniesiesz. Lokalną sesję wyślesz do chmury z aplikacji desktopowej (menu „Continue in”). Sesje w chmurze działają na planach Pro, Max i Team oraz w Enterprise z miejscami premium albo Chat + Claude Code. Podejrzysz je i poprowadzisz także w zakładce Code aplikacji mobilnej Claude.
claude --teleport ściąga sesję z chmury z powrotem do terminala. Przekazanie jest jednokierunkowe: z chmury do terminala, nie w obie strony naraz.
/desktop przenosi bieżącą sesję z terminala do aplikacji desktopowej (macOS i Windows x64), gdzie masz przegląd diffów i równoległe sesje z izolacją Git.

Terminal, IDE i aplikacja desktopowa dzielą CLAUDE.md, ustawienia i serwery MCP.

Sesja w chmurze startuje ze świeżego klona repozytorium. Dostaje CLAUDE.md z repo, a w sesji z jednym repozytorium także hooki i uprawnienia z .claude/settings.json oraz serwery z .mcp.json. Dostaje też ustawienia zarządzane organizacji oraz skille i konektory włączone na claude.ai.

Nie dostaje niczego, co jest tylko na Twoim komputerze (~/.claude.json, ~/.claude/CLAUDE.md). Serwer MCP dodany przez claude mcp add bez --scope project w chmurze więc nie zadziała: dodaj go z --scope project i zacommituj .mcp.json.

W sesjach chmurowych komendy /model, /effort, /color i /rename przyjmują tylko postać z argumentem (np. /effort high), bo suwaki i listy wyboru z terminala tam nie działają. /fast przełącza tam tryb szybki (wymaga 2.1.271 lub nowszej w środowisku sesji).

Kiedy to ma sens: długi refaktor albo migracja, którą chcesz zlecić na noc; praca z telefonu nad zadaniem, które wystartowałeś w biurze; zespół, który chce mieć sesje poza laptopami pracowników.

Integracja z GitHub Actions

claude-code-action (oficjalna)

Oficjalna GitHub Action od Anthropic. Reaguje na wzmianki @claude w issues i PR-ach albo wykonuje zadany prompt.

Najłatwiejsza ścieżka: w sesji Claude Code uruchom /install-github-app. Komenda instaluje aplikację Claude GitHub i zapisuje sekret w repozytorium: klucz API jako ANTHROPIC_API_KEY albo token subskrypcji jako CLAUDE_CODE_OAUTH_TOKEN. Potem wypycha gałąź z plikami workflow i otwiera w przeglądarce GitHub z pull requestem gotowym do utworzenia. Utwórz ten PR i scal go - dopiero wtedy @claude zacznie działać. Wymagania: uprawnienia admina repozytorium, repozytorium na github.com i GitHub CLI zalogowany przez gh auth login.

Ścieżka ręczna:

Krok 1: Zainstaluj aplikację github.com/apps/claude i dodaj w repozytorium jeden sekret (Settings → Secrets). Opcja pierwsza: ANTHROPIC_API_KEY, czyli klucz z Claude Console rozliczany za tokeny. Opcja druga: CLAUDE_CODE_OAUTH_TOKEN, czyli token subskrypcji Pro, Max, Team lub Enterprise z komendy claude setup-token. Token zużywa limit Twojego planu zamiast rozliczenia API.

Krok 2: Stwórz workflow .github/workflows/claude.yml (wzór z dokumentacji Anthropic, stan na 1 października 2026):

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

Blok permissions z id-token: write jest wymagany do domyślnego uwierzytelnienia aplikacją GitHub. Krok actions/checkout daje Claude lokalną kopię repozytorium. Warunek if sprawia, że runner (maszyna GitHub) nie startuje przy komentarzach bez @claude. Przy tokenie subskrypcji zamień linię anthropic_api_key na claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

Krok 3: Napisz @claude zrób review tego PR-a w komentarzu issue albo PR-a - Claude przeanalizuje kontekst i odpowie. Akcję uruchomi tylko osoba z prawem zapisu w repozytorium. Action sama wykrywa tryb: bez prompt reaguje na wzmianki, z parametrem prompt (np. na trigger pull_request) rusza automatycznie na każdym zdarzeniu. W trybie automatycznym wynik trafia domyślnie do logu workflow, nie do komentarza. Przy zwykłym prompcie tekstowym Claude nie ma też dostępu do powłoki ani API GitHuba, dopóki nie nadasz mu narzędzi przez --allowedTools w claude_args.

Nie chcesz utrzymywać pliku workflow? Na planach Team i Enterprise działa zarządzany Code Review (research preview). Włącza go właściciel organizacji w Claude (rola Owner). Recenzja rusza po otwarciu pull requesta, po każdym pushu albo tylko na żądanie, zależnie od ustawień repozytorium. Uwagi pojawiają się przy konkretnych liniach kodu.

Za recenzje płacisz osobno, z usage credits (płatnego zużycia ponad abonament), a nie z limitu planu. Według dokumentacji jedna recenzja kosztuje średnio $15-25 (stan na 1 października 2026). Ustawienie recenzji po każdym pushu mnoży ten koszt.

Code Review nie działa w organizacjach z włączonym Zero Data Retention (Anthropic nie przechowuje wtedy ich danych). Na planach innych niż Team i Enterprise diff przejrzysz lokalnie komendą /code-review.

Własny workflow headless

Prostsza droga: ta sama akcja anthropics/claude-code-action@v1 z wejściem prompt działa automatycznie na dowolnym zdarzeniu, także według harmonogramu (cron). Flagi CLI, np. --model czy --allowedTools, podajesz wtedy w claude_args. Własny skrypt z claude -p daje za to pełną kontrolę nad krokami:

name: Claude Analysis
on:
  push:
    branches: [main]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v7
        with:
          node-version: '22'
      - run: npm install -g @anthropic-ai/claude-code
      - name: Analyze codebase
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Przeanalizuj zmiany i wygeneruj raport" \
            --output-format json > report.json
      - uses: actions/upload-artifact@v7
        with:
          name: claude-report
          path: report.json

Wersje akcji pomocniczych są wyższe niż w starszych poradnikach. Wydania v4 działały na Node 20. GitHub zapowiedział usunięcie Node 20 z runnerów na 23 września 2026 i zaleca wersje działające na Node 24. Wartość node-version: '22' zostaje, bo paczka npm Claude Code wymaga Node.js 22 lub nowszego.

Pre-commit hooks z Claude

Automatyczne sprawdzanie kodu przed commitem. Kluczowy szczegół: model nie steruje kodem wyjścia procesu - prosisz o werdykt w ustalonym formacie, a decyzję podejmuje skrypt, parsując odpowiedź:

# .git/hooks/pre-commit
#!/bin/bash
WERDYKT=$(git diff --cached | claude -p \
  "Sprawdź te zmiany pod kątem bugów, sekretów w kodzie \
  i problemów bezpieczeństwa. Pierwsza linia odpowiedzi: \
  BLOKUJ albo OK. Potem krótkie uzasadnienie.")

if echo "$WERDYKT" | head -1 | grep -q "BLOKUJ"; then
  echo "$WERDYKT"
  echo "Claude Code znalazł problemy krytyczne. Popraw przed commitem."
  exit 1
fi

Częsty błąd: Używanie --dangerously-skip-permissions w środowisku produkcyjnym. Ta flaga włącza tryb bypassPermissions - jeden z sześciu trybów uprawnień z lekcji o hooks, skills i permissions. Wyłącza pytania o zgodę i klasyfikator auto mode, ale nie wszystko. Reguły deny dalej blokują, reguły ask dalej pytają, a rm i rmdir na krytycznych ścieżkach zawsze wymagają zgody. W trybie -p takie wywołania są odrzucane. Reguły allow w tym trybie nic nie zmieniają. Flaga zdejmuje prawie wszystkie hamulce, więc używaj jej TYLKO w izolowanych środowiskach CI/CD i kontenerach. Jeśli chcesz mniej pytań, ale z bezpiecznikiem, to właściwa droga to reguły allow w settings.json albo tryb auto - nie bypass.

Co już potrafisz

Siedem lekcji Modułu 4 za Tobą. Teraz potrafisz:

Zainstalować i skonfigurować Claude Code
Tworzyć CLAUDE.md z konwencjami projektu
Używać slash commands, flag i pipe w codziennej pracy
Konfigurować hooks, skills i permissions
Podłączać MCP Servers (GitHub, bazy danych, Slack)
Delegować zadania do subagentów
Uruchamiać background tasks, zlecać zadania sesjom w chmurze i integrować Claude Code z CI/CD

Chcesz automatyzować więcej? Dołącz do newslettera na czechu.blog - co tydzień nowe komendy Claude Code, gotowe konfiguracje CLAUDE.md i workflow dla developerów.

W ostatniej lekcji modułu - Tryb auto, dynamic workflows i agent teams - poznasz klasyfikator auto mode, orkiestrację dziesiątek subagentów skryptem workflow i eksperymentalne agent teams.

Ćwiczenie praktyczne: Skonfiguruj automatyczne code review:

Zaloguj GitHub CLI (gh auth login) i uruchom /install-github-app w sesji Claude Code (albo ręcznie: sekret ANTHROPIC_API_KEY lub CLAUDE_CODE_OAUTH_TOKEN + workflow z anthropics/claude-code-action@v1). Przy instalacji możesz dodać też workflow recenzji (claude-code-review.yml), który od wersji 2.1.229 publikuje uwagi bezpośrednio w pull requeście

Jeśli użyłeś /install-github-app, utwórz i scal przygotowany przez nią pull request z plikami workflow

Otwórz testowy PR i napisz w komentarzu: @claude zrób review tych zmian

Sprawdź odpowiedź Claude w wątku PR-a

Opcjonalnie: dodaj pre-commit hook z Claude Code