claude -p: headless mode turns the agent into infrastructure
Most developers meet Claude Code as a conversation: you type, it edits, you approve, repeat. But the most consequential flag in the whole CLI costs one letter. claude -p "fix the failing test in tests/auth_test.py" runs the full agent loop (read, edit, execute, verify) exactly once, with no TUI and no human present, then prints the result and exits with a status code. At that point Claude Code stops being an assistant and starts being a Unix program. And Unix programs are what infrastructure is made of.
The distinction matters more than it sounds. Interactive sessions scale with your attention, which is fixed. Headless runs scale with your compute budget, which is negotiable.
The building blocks
Headless mode is a small surface, and every piece earns its place:
-pfor one-shot runs. Prompt in, result out, exit code for your pipeline. It composes with pipes too:cat build.log | claude -p "diagnose this failure"turns the agent into a shell filter.--output-format json. Instead of prose on stdout you get a structured envelope: final result, turn count, cost, session id. Your CI step can parse it, log the spend, and fail the job on error instead of grepping prose.--allowedToolspinning. The one people skip, and shouldn't.--allowedTools "Read,Grep,Glob,Bash(npm test:*)"grants read access and test execution, nothing else: no edits, no pushes, no network calls. In an unattended run, the tool list is the security model.--max-turns. A hard ceiling on the loop. Skip it and a confused agent will grind through your token budget chasing a problem it cannot solve.
Issue-to-PR and PR review
The GitHub Action wraps headless mode so you are not hand-rolling YAML around a CLI. Two workflows carry most of the value. Issue-to-PR: mention the agent on an issue and it checks out the repo on a runner, works the task, and opens a pull request. Automated review: trigger it on pull requests and it reads the diff and leaves comments. That's a first pass that never skips a PR, sitting in front of the human reviewer, the pattern I argued for in AI code review.
Notice what both share: the agent's output is a pull request, never a push. Proposal and merge stay separated. CI still runs, a human still clicks the button. That single structural choice turns "autonomous agent in production" into "very fast contributor with zero commit rights."
Cron-grade chores
Headless mode turns "things the team never gets to" into a nightly batch job with a dollar cost instead of a morale cost.
Once the agent is a program, you can schedule it. Nightly dependency-bump attempts that only open a PR when the suite passes. Doc-drift checks that compare the README against the CLI's actual flags. Weekly triage that labels and deduplicates new issues. Every job follows the same recipe: narrow prompt, pinned tools, turn cap, PR as the only output. Gemini CLI is converging on the same CI story, and both slot into the larger picture I sketched in AI in DevOps: agents as pipeline stages, not pair programmers.
The failure modes are real
Unattended agents fail differently than scripts. Headless runs are nondeterministic: the same prompt can produce a real fix on Monday and a plausible-looking non-fix on Wednesday, and nobody is watching to smell the difference, so the gates have to do the smelling instead of a person. If a chore PR does not pass tests, lint, and review, it does not merge. And a run that cannot satisfy its gates should fail loudly, not open noise. Budget is the other trap: an agent stuck in a retry loop is a money printer running in reverse. Cap turns, cap spend per job, alert on anomalies.
Start with one chore you already resent: flaky-test triage, changelog drafting, dependency bumps. Give it read-plus-test tools, a turn cap, and PR-only output. If after a month you are merging most of its PRs, add a second job. If you are closing most of them, tighten the prompt or kill the job. That is the real gift of -p: the agent finally competes on infrastructure's terms, measured and replaceable.