Domain 3 · Claude Code Configuration

Headless mode & CI/CD

Claude Code isn't just an interactive chat — it can run non-interactively in a pipeline. The -p (print) flag runs one prompt and exits; --output-format json gives a machine-parseable result; and each run is an isolated session. That's how teams wire Claude into automated PR reviews, test generation, and triage.

-p / --print--output-format json session isolationCI/CD exit codes

Explain like I'm 10

Normally you chat with Claude back and forth. Headless mode is like leaving it a note: "do exactly this one job, write your answer on this card, and stop." No conversation, no waiting for you. A robot assembly line (the CI pipeline) drops a note for every new code change — "review this" — and Claude fills in the card. The line reads the card and decides: pass or block.

Interactive vs headless

	Interactive	Headless (`-p`)
Who's there	a human, chatting turn by turn	nobody — a script or CI runner
Runs	open-ended session	one prompt, then exits
Output	rendered in the terminal	`text` or `json` for parsing
State	persists across the session	isolated per run (fresh each time)

Build a CI command

Toggle the flags and see the command — and what the pipeline does with it:

output format

task

permission mode

Why session isolation matters in CI

Every pipeline run starts with a clean context — no leftover state from the last PR. That's a feature: it makes runs reproducible and stops one job's context from leaking into another. It also means each run must be given everything it needs up front (the diff, the standards, the task), because it remembers nothing from before. Pair headless runs with a committed CLAUDE.md so every automated run inherits the same team conventions.

Exam trap: for CI you want --output-format json so the pipeline can parse the result and set an exit status — plain text is for humans. Use read-only / plan permissions for review jobs (they shouldn't mutate the repo), and reserve write permissions for jobs that are meant to change files. "Just run interactive Claude in CI" is a wrong answer — there's no human to answer its prompts.

Takeaways: -p runs Claude Code headless (one prompt, then exits); --output-format json makes the result machine-parseable for the pipeline; each run is an isolated session (fresh context, reproducible). Give review jobs read-only permissions, feed each run everything it needs up front, and lean on committed CLAUDE.md for shared standards.

Curated companion: Claude Code — Headless / SDK · GitHub Actions.