Claude Code in CI: headless runs that are safe and parseable
How to run Claude Code in pipelines: print mode, restricting tools, schema-validated output, independent review passes and batch jobs, with a diagram.
In 30 seconds
Print mode (claude -p) runs without a human — so permissions must be tight.
--tools limits which tools exist; --allowedTools only skips prompts for the ones listed.
Ask for schema-validated output your pipeline can parse, and treat truncation as failure.
Review with a separate pass that sees only the diff and the requirements.
No human approves anything in CI, so the job gets exactly the tools it needs and returns output your pipeline can validate.
Why CI is different
In an interactive session, a developer watches and approves risky actions. In a pipeline nobody does. That changes the design: the job should be able to do exactly its task and nothing more, and its output must be machine-checkable.
Restrict, don't just pre-approve
Two flags are easy to confuse. --tools restricts which built-in tools are available at all. --allowedTools lets listed tools run without asking, but does not remove other tools. For a lint-fixing job, allow file reading and editing plus one vetted lint command, and deny other shell commands. Bypassing permission prompts "so the job never stalls" is the classic wrong answer, as is handing the job production credentials it does not need.
Output a pipeline can trust
claude -p "Review this diff against our checklist" \
--tools "Read,Grep" \
--json-schema '{"type":"object","properties":{"findings":{"type":"array"}}}'
Schema-validated JSON lets the next step post comments or fail the build reliably. Still validate it, and treat a cut-off response as an error rather than a short review.
Independent review
A model reviewing code in the same context that wrote it tends to share its assumptions. A second pass with fresh context — given only the diff, the requirements and relevant files — catches more. For large changes, focused passes per concern (security, correctness) followed by a verification pass improve both recall and precision.
Bulk jobs
Overnight work over thousands of items fits the Message Batches API: cheaper, asynchronous, and paired with per-item status so a failure costs one retry, not a restart. Retry transient errors with backoff and park items that keep failing in a queue a person checks in the morning.
Part of Domain 3: Claude Code Configuration & Workflows (20% of the exam). Explanations are our own, checked against Anthropic's documentation on November 22, 2026.
Common traps
Trap
Why it fails
Do this instead
Bypassing all permission checks in CI
Unlimited blast radius with no human watching
Restrict tools; deny the rest
Using --allowedTools to restrict tools
It pre-approves; other tools still exist
Use --tools to restrict availability
Assuming JSON is complete
Truncated output breaks the pipeline later
Validate against the schema and check the stop reason
Check yourself
Two original practice questions on this lesson. Try them before opening the answers.
Check yourself 1
Scenario: Claude Code for continuous integration
You want Claude Code to review pull requests automatically in CI and post structured findings. Which invocation style fits?
A. An interactive session that a developer opens and supervises for each pull request
B. Headless mode with every permission prompt bypassed, so the CI job never stops to ask
C. Headless claude -p, --tools limited to the review tools, and --json-schema for findings
D. Headless claude -p with --allowedTools listing the review tools, so no other tool exists
Show answer and explanation
Answer: C. Print mode (claude -p) runs without a human. --tools restricts which built-in tools are available, and --json-schema returns validated output in the shape your pipeline parses. --allowedTools only lets the listed tools run without prompting; it does not remove other tools. Interactive sessions do not scale in CI, and bypassing permission checks widens the blast radius.
Check yourself 2
Scenario: Claude Code for continuous integration
In a CI job, Claude Code must fix lint errors but must not run arbitrary shell commands. Which configuration choices fit? Choose two.
A. Allow only file reading and editing plus one vetted lint command
B. Bypass permission prompts entirely so the unattended job can never stall
C. Give the job broad credentials in case a fix needs other services
D. Deny all other shell commands through enforced permission rules
E. Tell Claude in the prompt to run nothing except the linter
Show answer and explanation
Answer: A and D. In automation nobody approves actions, so permissions must be tight — exactly the tools and the specific, vetted command the job needs — with every other shell command denied. Bypassing permission checks or granting broad credentials widens the blast radius, and a prompt instruction is not enforcement.