Claude Code headless: noční běhy bez dohledu (2026)

Claude Code headless znamená spustit agenta bez okna a bez tebe u klávesnice: z cronu, z CI nebo na vzdáleném stroji. Zadáš úkol večer, ráno čteš výsledek. Jenže noční běh má dvě typické slabiny. První je, že agent narazí na přetížené API (chyby 429 a 529) a skončí v půlce. Druhá je, že mu nikdo nehlídá limit a ráno máš na účtu překvapení. Claude Code má na obojí vlastní přepínače a poslední verze 2.1.305 k nim přidala další.

V tomhle návodu si projdeme, jak headless režim nastavit, co dělá CLAUDE_CODE_RETRY_WATCHDOG, které stropy nastavit a na co si dát pozor z hlediska bezpečnosti. Všechno vychází z oficiální dokumentace a changelogu ke dni 21. 10. 2026.

Pro koho vývojáře a týmy, které chtějí nechat agenta pracovat na pozadí (refaktor, migrace, generování testů, kontrola PR).

01Claude Code headless: základ s claude -p

Headless režim se zapíná přepínačem -p (nebo --print). Claude Code pak nespustí interaktivní okno, vykoná zadání, vypíše výsledek a skončí:

claude -p "Najdi a oprav chybu v auth.py" --allowedTools "Read,Edit,Bash"

Podle dokumentaci k programatickému spouštění (ověřeno 21. 10. 2026) končí běh s kódem 0 při úspěchu a nenulovým kódem při selhání. Tvůj skript nebo CI job tak může na výsledek reagovat obyčejným if. Vstup lze poslat i rourou, třeba cat build-error.txt | claude -p "vysvětli příčinu chyby".

Pro skripty a CI dokumentace doporučuje přidat --bare. Ten přeskočí automatické načítání hooků, skillů, pluginů, MCP serverů, auto memory i souboru CLAUDE.md, takže běh vypadá na každém stroji stejně. Počítej s jednou změnou: bare režim nečte přihlášení z předplatného, takže potřebuješ ANTHROPIC_API_KEY. Přesně to ale u nočních jobů většinou chceš, protože pak vidíš spotřebu v API a neukrajuješ z limitu svého osobního plánu. Jak se liší cena plánů a API, najdeš v článku Kolik stojí Claude Code 2026.

02Jak nastavit Claude Code headless na noční běh

Takhle vypadá minimální a rozumná konfigurace. Každý krok má svůj důvod.

export CLAUDE_CODE_RETRY_WATCHDOG=1

#!/usr/bin/env bash
# noční job: kontrola závislostí, výsledek do logu
export CLAUDE_CODE_RETRY_WATCHDOG=1
export CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=1800000   # max 30 min čekání na jeden požadavek
claude --bare -p "Projdi package.json a navrhni bezpečné aktualizace závislostí" \
  --allowedTools "Read,Bash" \
  --max-turns 40 --max-budget-usd 5 \
  --output-format json > "logs/$(date +%F).json"

03Retry watchdog: co dělá a co ne

Bez watchdogu zkusí Claude Code neúspěšný požadavek podle CLAUDE_CODE_MAX_RETRIES (výchozí hodnota je 10, od verze 2.1.186 s horním limitem 15). To je dobré pro interaktivní práci, ale ne pro noc, kdy API občas trpí přetížením.

Watchdog (vyžaduje verzi 2.1.186 nebo novější) mění pravidla takto:

• 429 a 529 opakuje bez konce. Prodleva mezi pokusy roste až na 5 minut, případně do času resetu limitu, pokud ho odpověď uvádí. Relace, která narazí na usage limit, tedy vyčká zbytek okna.
• Okamžitě selže u vyčerpaného rozpočtu. Od verze 2.1.239 běh skončí hned, když standardní požadavek dostane 429 s hlášením o spend limitu nebo vyčerpaných kreditech. Dřív by čekal donekonečna.
• Víc pokusů u ostatních přechodných chyb. Od verze 2.1.199 zvyšuje výchozí počet pokusů u serverových chyb, timeoutů a přerušených spojení na 300, což dokumentace odhaduje na zhruba tři hodiny odkládání.

Watchdog tedy nezaručí, že úkol dopadne dobře. Zaručuje jen, že krátký výpadek nebo přetížení API nezabije celý noční běh. Pokud se agent zacyklí logikou, watchdog to nezachrání. Na to slouží --max-turns a rozpočet.

04Stropy pro Claude Code headless: tabulka proměnných

Čekání „do nekonečna" se dá omezit. Tohle jsou proměnné, které se v posledních verzích přidaly:

Poslední proměnná má podle dokumentace omezení: kontroluje jen session nebo týdenní limit předplatného claude.ai, když se nepoužívají kredity, a neběží při nastaveném CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. Bez hodnoty v povoleném rozsahu se kontrola neprovádí vůbec. Pokud jedeš na API klíči, ji nepotřebuješ.

Dobré vědět: proměnné CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS a CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS, které ladí prodlevy u chyby 529, nemají při CLAUDE_CODE_RETRY_WATCHDOG=1 žádný účinek. Obojí nekombinuj v domnění, že se sečtou.

05Bezpečnost: co headless spustí bez ptaní

Na tohle se zapomíná. Podle dokumentace běh claude -p bez --bare spouští hooky z .claude/settings.json projektu a připojuje servery z jeho .mcp.json, a to i ve složce, které jsi nikdy nedůvěřoval. V -p se neukáže žádný dialog důvěry ani schvalování MCP serveru. Pokud tedy noční job klonuje cizí repozitář, můžeš si spustit cizí kód.

Praktická pravidla:

1. Pro cizí nebo neověřený kód používej --bare a konfiguraci předávej explicitně (--settings, --mcp-config).
2. Dej agentovi jen nástroje, které potřebuje, a běž v izolovaném prostředí. K tomu se hodí náš návod, jak sandboxovat AI agenta v produkci.
3. Kontrolu nebezpečných příkazů přesuň do hooků, které ji vynutí i bez člověka: viz Claude Code hooks pro automatizaci.

Ještě dvě drobnosti z dokumentace. Když proces zastavíš signálem SIGTERM, Claude Code skončí s kódem 143 a rozpracované kolo nechá nedokončené. A běh po dokončení hlavní práce čeká na úlohy na pozadí maximálně 10 minut nečinnosti, což se dá změnit proměnnou CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS.

06Co zkontrolovat ráno: jak poznat, že noc dopadla

Noční job je tak dobrý, jak dobrý je jeho ranní report. Opírej se jen o signály, které Claude Code dokumentuje:

• Návratový kód. Nula znamená úspěch, nenulový kód selhání. Kód 143 značí, že proces někdo ukončil signálem SIGTERM, třeba plánovač po překročení časového limitu.
• Chyba po --max-turns. Pokud agent narazil na strop kol, běh skončí chybou. Úkol tedy nedoběhl a výsledek nelze brát jako hotový.
• total_cost_usd ve výstupu JSON. Ukládej ho do logu a sleduj trend. Když se jedna noc najednou vymkne, víš, že se agent zacyklil nebo že se zadání rozrostlo.
• Výsledek mimo model. Nejspolehlivější kontrola není to, co o sobě agent napíše, ale to, co ověříš sám: testy, lint, diff. Do skriptu proto přidej vlastní kontrolu po skončení.

Jednoduchý obal kolem příkazu z předchozí sekce může vypadat takto:

if claude --bare -p "$PROMPT" --max-turns 40 --max-budget-usd 5 --output-format json > "$LOG"; then
  npm test || echo "Testy po nočním běhu selhaly" >> "$LOG.alert"
else
  echo "Claude Code skončil s chybou ($?)" >> "$LOG.alert"
fi

Takový skript nic nepředpokládá. Ráno ti stačí otevřít soubor s příponou .alert a víš, jestli se máš na noční práci vůbec dívat. Pokud běh nechceš řešit sám, stejný vzor můžeš nasadit do týmového CI a výsledek posílat do chatu.

07Kdy noční běh nedává smysl

Headless režim se hodí na úkoly s jasným kritériem hotovo: testy projdou, lint je čistý, report je vygenerovaný. Nehodí se na nejasná zadání typu „vylepši architekturu", kde agent bez zpětné vazby buď zbytečně utratí, nebo udělá změny, které ráno nechceš vracet. Víc nezávislých úkolů pak odděl do vlastních pracovních stromů, jak ukazuje playbook s git worktrees.

Jedno upozornění k aktuálnosti: proměnné z tabulky jsou nové a názvy i chování se mohou měnit. Před nasazením zkontroluj seznam proměnných prostředí a changelog (poslední ověřená verze 2.1.306, 21. 10. 2026).

08Časté otázky