DevOps
Claude Code Headless Mode for CI/CD Pipelines
August 20269 min read
Headless mode, also called print mode, is Claude Code invoked with the -p flag and a prompt instead of an interactive chat. It processes the prompt, prints its output to standard out, and exits with a status code. That makes it a normal command-line program you can call from scripts, pre-commit hooks, and CI/CD pipelines.
Invoke claude -p with your prompt as a pipeline step, provide an API key through a secret exposed as an environment variable, and add an output format such as JSON so the result is easy to parse. Restrict the tools it may use and branch on the exit code to pass or fail the stage. Keep the run inside an isolated environment.
Parsing free-form text is brittle and breaks whenever the phrasing changes. Asking for JSON gives you a structured object with the result and metadata such as token usage, which you can log, assert on, or feed into another step. It makes the agent a reliable, machine-readable stage rather than a source of loose prose.
Only inside a sandbox. Skipping approvals in an unsandboxed environment gives a single manipulated prompt the same reach as the credentials in the job, so a prompt-injection instruction hidden in the code it reads could act freely. If you must skip prompts for automation, do it in a container or virtual machine with no standing access to production.
The best fits are repetitive, well-scoped jobs that are easy to describe and cheap to verify. Examples include pull-request checks that flag missing tests or leftover debug code, pre-commit hooks that catch issues before CI, and scheduled jobs such as drafting a changelog or summarising overnight test failures.
Key Takeaway
Claude Code headless mode runs the agent non-interactively with the claude -p command, printing a result and exiting instead of opening a chat. It is how you wire Claude into CI/CD pipelines, pre-commit hooks, and scripts: pass a prompt, restrict its tools and permissions, read structured JSON output, and act on the exit code.
Most people meet Claude Code as an interactive terminal chat: you type, it works, you approve. That loop is great for exploratory coding and useless for automation, because a CI runner has nobody to answer its prompts. To put an agent inside a pipeline you need it to run once, do the job, and get out of the way.
Headless mode is that non-interactive path. You invoke Claude Code with a prompt and a set of flags, it runs to completion without a conversation, and it reports back in a form a script can parse. This guide covers the core command, how to control what it is allowed to do, and how to run it safely in CI without leaving the door wide open.
Headless mode, also called print mode, is Claude Code invoked with the -p flag and a prompt. Instead of starting an interactive session it processes the prompt, emits its output to standard out, and exits with a status code. That makes it a normal command-line program you can pipe into, redirect, and call from any script or job.
A few properties make it suited to automation rather than day-to-day chat:
The simplest invocation passes a prompt string after -p. For automation you almost always add an output format, because parsing free-form text is brittle. Ask for JSON and you get a structured object with the result and metadata such as token usage that you can log or assert on.
A minimal CI invocation that restricts tools and returns JSON looks like this:
claude -p "Review the staged diff and fail if any TODO is left" \
--output-format json \
--allowedTools "Read,Grep,Glob" \
--permission-mode plan \
--max-turns 12Always pin an explicit tool allowlist in headless runs. In a script there is nobody to approve a risky action, so an unrestricted agent either stalls waiting for input or, worse, is free to do anything its prompt leads to. Naming the exact tools it may use turns the run into a predictable, bounded step.
Inside a pipeline, headless Claude Code is just another step that either succeeds or fails. The pattern is the same across CI systems: authenticate, run the command with tight permissions, and branch on the result.
A non-interactive agent is exactly as dangerous as the permissions you hand it, because there is no human in the loop to catch a bad step. The whole safety model rests on scoping the run down to the minimum it needs and running it somewhere it cannot do lasting harm.
In practice that means combining a strict tool allowlist with an isolated environment. A CI runner is already ephemeral, which helps, but a job that clones your repo and holds a real API key is still worth sandboxing, so a prompt-injected instruction hidden in the code it reads cannot reach further than the runner.
Never run headless mode with permission checks fully bypassed against anything you care about. Skipping approvals in an unsandboxed environment gives a single manipulated prompt the same reach as the credentials in the job. If you must skip prompts for automation, do it inside a container or virtual machine with no standing access to production.
Once Claude Code is a command, the useful jobs are the repetitive ones that are easy to describe and cheap to verify.
Headless mode is the seam between Claude Code and the rest of your toolchain. Reach for claude -p whenever you want the agent to run once and report back, pin its tools and permissions tightly, read the JSON instead of scraping text, and keep every unattended run inside a sandbox. Do that and an agent becomes just another dependable step in the pipeline.