Claude Code headless draaien in 2026: een praktische automatiseringsgids

De headless-modus van Claude Code draait de agent niet-interactief: je geeft de vlag -p (of --print) mee met een prompt, Claude draait tot voltooiing, print het resultaat en sluit af — geen REPL, geen toetsenbord, niemand die aan een terminal zit te wachten. Die ene vlag verandert een interactieve programmeerassistent in een Unix-vriendelijk command-line-tool waar je in kunt pipen, dat je in een script kunt verpakken, met cron kunt inplannen of in een CI/CD-pijplijn kunt droppen. Deze gids behandelt hoe de headless-modus in 2026 werkt, welke vlaggen er echt toe doen, hoe je er parseerbare JSON uit krijgt, de permissie- en authenticatievalkuilen die onbeheerde runs stilletjes laten stuklopen, en de lessen uit het draaien van een headless Claude Code-pijplijn in productie.

Wat is de headless-modus van Claude Code?

De headless-modus is Claude Code die draait zonder zijn interactieve terminal-UI. Voeg -p (afkorting van --print) toe aan een willekeurig claude-commando en in plaats van de REPL te openen leest Claude de prompt, draait de volledige agent-lus (bestanden lezen, tools uitvoeren, code bewerken), print vervolgens het eindresultaat en sluit af met een statuscode. Het is dezelfde agent die het interactieve Claude Code aandrijft, alleen aangestuurd door een script in plaats van een mens. Vanaf 2026 leeft de functie onder de Agent SDK, die ook wordt geleverd als Python- en TypeScript-package als je callbacks en native message-objecten wilt in plaats van via de shell te werken.

claude -p "What does the auth module do?"

Omdat de niet-interactieve modus van stdin leest, combineert het net als elk ander CLI-tool. Je kunt een build-log er rechtstreeks in pipen en het antwoord eruit redirecten:

cat build-error.txt | claude -p "concisely explain the root cause of this build error" > cause.txt

Die combineerbaarheid (stdin erin, tekst of JSON eruit, een exit-code waarop je kunt vertakken) is de hele reden dat de headless-modus bestaat.

Hoe krijg je gestructureerde output die je kunt parsen

Platte tekst is prima voor een mens die een log leest, maar automatisering heeft structuur nodig. De vlag --output-format accepteert precies drie waarden: text (de standaard), json en stream-json. Het json-formaat is het werkpaard: het geeft het antwoord plus sessie-metadata terug in één object.

claude -p "Summarize this project" --output-format json | jq -r '.result'

De JSON-payload bevat result (de tekst), session_id, num_turns, is_error, duration_ms en, cruciaal voor iedereen die dit op schaal draait, total_cost_usd, een kostencijfer per aanroep zodat je je uitgaven kunt volgen zonder het dashboard te openen. Voor machinaal leesbare antwoorden die voldoen aan een vorm die jij definieert, combineer je --output-format json met --json-schema '{...}'; het gevalideerde object komt terug in een structured_output-veld. Gebruik stream-json met --verbose wanneer je tokens wilt renderen zodra ze binnenkomen. Parse het met jq en je hebt een betrouwbare programmatische interface.

Permissies: het onderdeel waar iedereen over struikelt

Een interactieve sessie vraagt om toestemming voordat het een shell-commando uitvoert of een bestand bewerkt. Een headless run heeft niemand om het aan te vragen, dus standaard weigert het de actie en kan het je pijplijn laten vastlopen. Je moet de toestemming vooraf verlenen. Het schoonste hulpmiddel is --allowedTools, een door komma's gescheiden toegestane lijst:

claude -p "Run the test suite and fix any failures" --allowedTools "Bash,Read,Edit"

Voor fijnere controle gebruikt de vlag permissie-regelsyntaxis, dus --allowedTools "Bash(git diff *)" staat alleen commando's toe die met git diff beginnen. Om een basislijn voor de hele run in te stellen in plaats van tools op te sommen, geef je een --permission-mode mee: acceptEdits laat Claude bestanden schrijven en veelvoorkomende bestandssysteemcommando's uitvoeren zonder te vragen, terwijl dontAsk alles weigert wat niet expliciet is toegestaan, wat de juiste keuze is voor een dichtgetimmerde CI-job. Het botte instrument, --dangerously-skip-permissions, keurt alles goed en zou alleen een wegwerpbare sandbox of container mogen raken, nooit een machine met inloggegevens of productietoegang.

Authenticatie: API-sleutel versus OAuth-token

Headless runs hebben inloggegevens nodig die geen browser-login vereisen, en er zijn twee eerlijke wegen. De eerste is ANTHROPIC_API_KEY, een sleutel uit de Anthropic Console die per token wordt afgerekend, de natuurlijke keuze voor CI-runners en pay-as-you-go-automatisering. De tweede laat je een bestaand abonnement hergebruiken: draai claude setup-token één keer, doorloop de OAuth-flow in een browser, en het print een token dat een jaar geldig is dat je exporteert als CLAUDE_CODE_OAUTH_TOKEN. Dat token is gekoppeld aan een Pro-, Max-, Team- of Enterprise-plan en beperkt tot alleen inferentie. Kies op basis van je facturatiemodel: gemeten API-gebruik voor piekbelasting in CI, het abonnementstoken voor een gestage always-on agent. Eén kanttekening voor gescripte aanroepen: de --bare-modus (die het automatisch ontdekken van hooks, skills en MCP-servers overslaat voor reproduceerbare runs) slaat ook OAuth over, dus onder --bare moet je ANTHROPIC_API_KEY aanleveren.

Claude Code draaien in CI/CD en op cron

Zodra een enkel commando niet-interactief werkt, is het inplannen ervan doodgewone DevOps. Een cron-regel die claude -p op een VPS draait, verandert de agent in een taak die uit zichzelf afgaat: logs triageren om 2 uur 's nachts, een changelog opstellen of lint op schema fixen. In een pijplijn verpak je de aanroep in een script dat een diff erin pipet en op de exit-code vertakt; Anthropic levert eerste-partij-integraties met GitHub Actions en GitLab CI/CD precies hiervoor. Twee vlaggen doen ertoe voor onbeheerde betrouwbaarheid. Voeg --bare toe zodat runs niet stilletjes erven welke hooks of MCP-servers er toevallig in de ~/.claude van een teamgenoot staan, zodat je op elke machine hetzelfde resultaat krijgt. En gebruik --continue of --resume <session_id> wanneer een job meerdere beurten nodig heeft die op elkaar voortbouwen, waarbij je de sessie-ID uit de JSON-output van de eerste aanroep vastlegt. Als je de machine zelf opzet, behandelt onze gids over je apps zelf hosten op een VPS de cron- en beveiligingsbasis die een ingeplande agent gezond houdt.

Vlag	Wat het doet	Wanneer je het nodig hebt
-p / --print	Niet-interactief draaien, resultaat printen, afsluiten	Elke headless run
--output-format json	Gestructureerd resultaat met kosten + sessie-metadata	Elke gescripte aanroeper
--json-schema	Output dwingen in een schema (structured_output)	Machinaal leesbare extractie
--allowedTools	Specifieke tools vooraf goedkeuren	Voorkomt dat de run vastloopt op prompts
--permission-mode	Sessiebrede basislijn (acceptEdits, dontAsk)	Dichtgetimmerde CI
--bare	Automatisch ontdekken overslaan voor reproduceerbare runs	CI- en SDK-aanroepen
--continue / --resume	Gesprekken over meerdere beurten heen	Toestand-behoudende jobs

Wat we leerden van het draaien van een headless content-engine

We gebruiken Claude Code headless zelf in productie: de pijplijn die hier bij TechRiseUps artikelen onderzoekt, schrijft en publiceert, draait als een ingeplande claude -p-job op onze eigen WaseerHost-infrastructuur, aangestuurd door een aangepaste skill in plaats van door een persoon aan het toetsenbord. Een paar lessen bleken standvastig die de documentatie slechts aanstipt.

Permissies zijn de belangrijkste oorzaak van een "vastgelopen" run: een job die lijkt te blijven hangen, is bijna altijd Claude die wacht op een goedkeuring die nooit komt, dus keur elke tool die de taak werkelijk nodig heeft vooraf goed en niets meer. Lees total_cost_usd uit de JSON bij elke aanroep en log het; onbeheerde agents hebben geen natuurlijk kostenplafond, en het cijfer per run is de enige goedkope manier om een taak te betrappen die uit de hand liep. Maak elke run idempotent, want een cron-job zal uiteindelijk twee keer afgaan of halverwege hervatten, en een agent die blind toevoegt maakt er een rommeltje van. En voor langlopende jobs die uitwaaieren met achtergrond-subagents, verhoog je de limiet voor bestandsdescriptors van het proces, want een headless agent die veel bestanden en sockets opent, kan stilletjes tegen de standaard ulimit aanlopen en vastlopen zonder duidelijke foutmelding. Geen van deze zijn exotisch; het is de saaie operationele hygiëne die een demo onderscheidt van een pijplijn die je vertrouwt om te draaien terwijl je slaapt.

Veelgestelde vragen

Wat is de headless-modus in Claude Code?

Het is Claude Code die niet-interactief draait via de vlag -p / --print. Claude leest een prompt, draait de volledige agent-lus, print het eindresultaat en sluit af, zonder interactieve terminal. Het is bedoeld voor scripts, pipes, cron-jobs en CI/CD in plaats van hands-on programmeren.

Hoe draai ik Claude Code headless zonder voor API-sleutels te betalen?

Genereer een op een abonnement gebaseerd token met claude setup-token en exporteer het vervolgens als CLAUDE_CODE_OAUTH_TOKEN. Het authenticeert tegen een Pro-, Max-, Team- of Enterprise-plan in plaats van gemeten API-facturatie. Merk op dat de --bare-modus OAuth omzeilt en nog steeds ANTHROPIC_API_KEY vereist.

Hoe voorkom ik dat Claude Code in de headless-modus om toestemming vraagt?

Keur tools vooraf goed met --allowedTools "Bash,Read,Edit", of stel een sessiebasislijn in met --permission-mode acceptEdits (of dontAsk voor dichtgetimmerde CI). Gebruik --dangerously-skip-permissions alleen binnen een wegwerpbare sandbox, nooit op een machine met echte inloggegevens.

Kan ik Claude Code headless vanuit Python draaien?

Ja. De headless-modus is onderdeel van de Agent SDK, die naast de claude -p-CLI als Python- en TypeScript-package wordt geleverd. Gebruik de SDK-packages wanneer je callbacks voor tool-goedkeuring, native message-objecten en gestructureerde outputs wilt zonder stdout te parsen.

Is de headless-modus hetzelfde als de Claude Agent SDK?

Het zijn twee voordeuren naar dezelfde engine. claude -p is de CLI-vorm van de Agent SDK — dezelfde tools, agent-lus en contextbeheer. De Python- en TypeScript-SDK-packages geven je vollere programmatische controle om agents in applicaties te bouwen.

Bronnen

• Claude Code Docs — Claude Code programmatisch draaien (headless): de -p/--print-vlag, --output-format, --bare, permissies, --continue/--resume en JSON-resultaatvelden.
• Claude Code Docs — Authenticatie: claude setup-token, CLAUDE_CODE_OAUTH_TOKEN en hoe abonnementstokens verschillen van ANTHROPIC_API_KEY.
• Claude Code Docs — GitHub Actions: eerste-partij-CI-integratie voor het draaien van de agent in pijplijnen.