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.
What headless mode is
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:
- It is stateless by default: each run starts fresh, so a pipeline step is reproducible and does not depend on a prior conversation.
- It is scriptable: you can pass the prompt inline or on standard input and capture everything it prints.
- It is composable: the exit code tells the surrounding job whether the step passed, so you can gate a build on it.
The core command and output formats
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.
Wire it into CI/CD
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.
- Provide credentials through a secret, typically an API key exposed to the job as an environment variable, never hard-coded in the workflow.
- Give the step a narrow, well-defined job such as reviewing a diff, drafting release notes, or triaging a failing test, rather than an open-ended goal.
- Capture the JSON output and use the exit code to pass or fail the stage, so the agent becomes a real gate and not just advisory noise.
- Set limits such as a maximum number of turns, so a confused run stops instead of looping and burning budget.
Guard the blast radius
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.
Practical automation ideas
Once Claude Code is a command, the useful jobs are the repetitive ones that are easy to describe and cheap to verify.
- Pull-request checks that read a diff and flag missing tests, leftover debug code, or undocumented public APIs.
- Pre-commit hooks that run the agent locally in print mode to catch obvious issues before they ever reach CI.
- Scheduled maintenance jobs, such as drafting a changelog from merged commits or summarising overnight test failures.
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.

