Claude Code Headless: Running claude -p in CI Without It Hanging (2026 Field Log)

Quick Answer (2026): Claude Code runs headless with claude -p "your prompt", which executes non-interactively, prints the result, and exits. There is no permission prompt in this mode, so you have to pre-authorize tools with --allowed-tools and a --permission-mode, or the run refuses to touch anything. Add --output-format json to get the response plus token usage and cost in one blob, and --max-turns so an agentic loop cannot run away inside CI. After three weeks of wiring this into a real pipeline, that is the whole trick: pre-authorize, bound the turns, read the JSON.

I write when something breaks. What broke this time: I dropped claude -p "summarize the diff" into a GitHub Actions step, watched it hang for the full timeout, and got nothing back. In the terminal that same command works. In CI it sat there waiting for a permission prompt that no human was ever going to answer. That failure is the entire lesson of headless mode, so this log is built around it.

What headless mode actually is

claude -p (long form --print) is Claude Code with the interactive shell removed. It takes one prompt, runs the agent loop, prints the final response to stdout, and exits with a status code. The headless docs call it print mode, and it is the same engine that powers the SDK and the official GitHub Action underneath.

The plainest version:

claude -p "List every TODO comment in src/ and group them by file"

You can pipe context in on stdin, which is how most of my real uses look:

git diff --staged | claude -p "Write a one-paragraph commit message for this diff"

That second one is genuinely useful and completely safe, because it only reads what you piped and writes text back. The trouble starts the moment the prompt implies a tool.

The permission wall nobody warns you about

Interactive Claude Code asks before it edits a file or runs a command. Headless Claude Code cannot ask, because nobody is there. So the default posture is to refuse anything that needs a permission it does not already have. My hung CI job was Claude waiting, forever, for an approval that headless mode structurally cannot request.

The fix is to grant the tools up front:

claude -p "Run the test suite and tell me what failed" \
  --allowed-tools "Bash(npm test:*)" \
  --permission-mode acceptEdits \
  --max-turns 6 \
  --output-format json

Three of those flags matter:

• --allowed-tools is an explicit allowlist. Bash(npm test:*) lets it run npm test and nothing else shell-shaped. This is the same matcher grammar as the interactive allow list I wrote about in my permissions field log, and in headless mode it stops being optional.
• --permission-mode acceptEdits tells it to stop asking about file edits. In a locked-down CI container some teams go further with a bypass mode, but I keep acceptEdits and a tight allowlist rather than opening the whole door.
• --max-turns 6 is the seatbelt. Without it, an agentic loop that keeps deciding it needs one more step will happily burn your entire runner budget. Six is enough for the small jobs I give it and cheap to cap.

Read the JSON, not the vibes

--output-format json is the flag that turned headless from a toy into something I trust. Instead of loose text, you get a structured object with the result, the number of turns, and the token usage and dollar cost of the run:

claude -p "Summarize CHANGELOG.md in 5 bullets" --output-format json \
  | jq '{result, cost: .total_cost_usd, turns: .num_turns}'

That is how I keep an eye on spend without guessing. claude code cost is a top search for a reason, and the honest answer for automation is: stop eyeballing it, log total_cost_usd from every headless run and sum it. There is also --output-format stream-json if you want to consume events as they happen, which matters for anything long enough that you want a progress signal.

The three headless jobs I actually kept

1. Commit-message drafts. git diff --staged | claude -p on a git alias. Zero tools, zero risk, saves me a sentence of thinking fifty times a day.
2. A PR summary step in CI. Reads the diff, writes a plain-language summary into the job output. Allowlist is read-only, --max-turns 3, JSON output logged for cost. This is the one that hung until I pre-authorized it.
3. A nightly "what looks broken" pass. Runs the test suite headless, and if it fails, drafts a short triage note. --allowed-tools "Bash(npm test:*)", --max-turns 6. It does not fix anything. Headless code that edits and pushes on its own is a footgun I am not ready to hold.

The two I ripped back out

• A headless job that auto-committed formatting fixes. It worked until the week it "fixed" a file into a broken state and pushed it while I was asleep. Now formatting is a PostToolUse hook in my interactive sessions, not an autonomous headless push. Let the agent draft; let a human merge.
• A giant single prompt doing five things. Splitting it into three small claude -p calls, each with its own tight allowlist and turn cap, was cheaper, faster, and far easier to debug when one step misbehaved. Small headless jobs beat one clever one.

If you wire in exactly one thing

Put --max-turns and --allowed-tools on every headless invocation, and log total_cost_usd from the JSON. The CLI reference has the full flag list, but those three are what stand between "a useful CI step" and "a runner that hangs, then bills you." Pre-authorize, bound the turns, read the JSON. That is the field log.