Headless Mode & the Agent SDK

Everything you've learned about interactive Claude Code — the agentic loop, permission modes, CLAUDE.md, tools — is still true in headless mode. The only thing that changes is the interface. Interactive mode gives you a live terminal where you steer, approve, and watch. Headless mode (claude -p) gives you a single shot: it takes a query, runs the full agent loop through the SDK, prints the result to stdout, and exits. No prompts, no UI, no waiting for you.

That one change unlocks a whole category of uses:

• Scripts — wrap Claude in a shell script and call it like any other CLI tool.
• Pipelines — pipe logs, diffs, or data into it and pipe its output onward.
• CI/CD — run it as a build step that reviews code, generates files, or triages failures.
• Fan-out — loop it across hundreds of files, each in its own isolated run.
• The Agent SDK — claude -p is the headless entry point; the Agent SDK is the full programmatic layer for building custom agentic workflows with complete control over orchestration, tool access, and permissions.

The mental shift is this: in interactive mode you are the verification loop and the approval authority. In headless mode there is no human in the loop — so you replace yourself with flags. Budgets replace your judgment about cost, turn limits replace your patience, allow/deny rules replace your Accept clicks, and output formats replace your eyes reading the screen. The rest of this lesson is those flags.

The core command is simple:

claude -p "explain what the auth middleware does"

This starts a non-interactive session in the current directory, runs the agent, prints the answer, and exits. --print is the long form of -p.

Piping stdin. The real power of headless mode is composing it with other Unix tools. Anything you pipe in becomes context for the query:

tail -200 app.log | claude -p "find anomalies in these log lines"

Here the last 200 log lines are fed to Claude as input, and it analyzes them. You can pipe in git diffs, command output, JSON, CSV — whatever you can produce on the command line.

The file gotcha — this trips everyone up. In interactive mode you can say "look at config.ts" and Claude will go read it with a tool. In print mode, files mentioned in your prompt are NOT auto-read. A one-shot headless run won't necessarily go fetch files just because you named them. You have two reliable ways to get file contents into the run:

1. Pipe the file in as stdin: cat config.ts | claude -p "review this".
2. Use an @ mention to embed the file explicitly: claude -p "review @config.ts".

If you forget this, Claude answers from the prompt text alone and you get a vague or hallucinated response. When in doubt, pipe it or @-mention it.

Combining with other invocation flags. Print mode composes with the session flags you already know — for example, continue the most recent conversation non-interactively:

claude -c -p "now write the tests for that change"

Note that -p/SDK sessions don't show up in the /resume picker, but they are still real sessions and remain resumable by ID.

When a script consumes Claude's output, you rarely want prose — you want something parseable. The --output-format flag controls the shape of what lands on stdout:

# Parse a single structured response with jq
claude -p --output-format json "list the exported functions in @api.ts" | jq .

# Stream events as they happen
claude -p --output-format stream-json "refactor the parser"

Validated structured output with --json-schema. Output-format json gives you valid JSON, but not necessarily JSON in the exact shape your program expects. When you need the output to conform to a specific contract — fixed field names, types, required keys — pass a JSON Schema and Claude's output is validated against it. This is the headless feature that makes Claude safe to wire directly into typed code.

claude -p --json-schema '{
  "type": "object",
  "properties": {
    "severity": { "type": "string", "enum": ["low", "medium", "high"] },
    "summary":  { "type": "string" },
    "files":    { "type": "array", "items": { "type": "string" } }
  },
  "required": ["severity", "summary"]
}' "triage the failing test and report severity, a summary, and affected files"

Now your downstream code can rely on .severity being one of three strings and .summary always being present. Both --json-schema and --output-format's structured modes are print-mode features — they're meant for the automation path, not interactive chatting.

In interactive mode, you are the brake: you watch the cost, you get bored and hit Esc, you click Accept or deny. Headless runs have none of that, so you install the brakes as flags. There are two budget controls and two safety controls.

Budget controls — cap the spend and the work:

claude -p --max-budget-usd 5.00 --max-turns 8 "refactor the date utils and add tests"

Think of --max-budget-usd as a financial circuit breaker and --max-turns as a runaway-loop guard. A misunderstood task that keeps trying could otherwise burn money or spin forever; these flags make the worst case bounded.

Safety controls — decide what runs without a human:

• --allowedTools lists exactly which tools (and command patterns) may run without prompting, using permission-rule syntax.
• --permission-mode dontAsk makes the run auto-deny anything not in an allow rule — there is no human to prompt, so an unlisted action becomes a denial rather than a hang.

Together they are the standard recipe for safe CI automation:

claude -p \
  --permission-mode dontAsk \
  --allowedTools "Read" "Bash(npm test)" "Bash(git diff *)" \
  --max-budget-usd 2.00 --max-turns 6 \
  "run the tests and summarize any failures"

This says: you may read files, run the test suite, and inspect diffs — nothing else, and if you try anything else it's denied; stop at $2 or 6 turns. That is a run you can leave unattended in a pipeline. dontAsk is the headless counterpart to interactive prompting; reserve the far more dangerous bypassPermissions (= --dangerously-skip-permissions) for throwaway containers.

Headless runs often need a specific persona or set of rules: "you are a terse code reviewer," "output only valid SQL," "never explain, just fix." Claude Code lets you shape the system prompt — but there's a sharp safety distinction between appending and replacing.

The rule: almost always use --append-system-prompt. The default system prompt is what teaches Claude how to use its tools correctly and what keeps its safety behavior intact. When you replace it with --system-prompt, you throw all of that away — Claude may misuse tools, ignore guardrails, or behave unpredictably, because you've deleted the instructions that made it work well.

# SAFE: add your rules on top of the defaults
claude -p --append-system-prompt "You are a strict reviewer. Flag any unhandled error path." \
  "review @handler.ts"

# DANGEROUS: replaces everything, including tool/safety guidance
claude -p --system-prompt "You only output JSON." "..."

Use the *-file variants when the prompt is long enough to live in version control rather than inline in a script. Reach for the replacing --system-prompt only in the rare case where you genuinely want a blank-slate model with no Claude Code behavior — and you've accepted that you're giving up the safety and tool scaffolding.

The signature headless workflow is fan-out: run claude -p once per item in a list — one file, one module, one ticket — each in its own isolated, bounded run. Because each invocation is a fresh session, the work parallelizes cleanly and one item's context never pollutes another's.

for f in $(cat files-to-migrate.txt); do
  claude -p "migrate $f to the new logging API" \
    --allowedTools "Edit" "Bash(git commit *)" \
    --permission-mode dontAsk \
    --max-turns 4
done

Notice the discipline: every iteration is scoped (only Edit and git commit are allowed), strict (dontAsk denies anything else), and bounded (--max-turns 4). Scoping the allowed tools tightly per loop is what makes mass automation safe — a single run can only do the narrow job you gave it.

--bare for fast, minimal startup. When you're spawning many quick runs, the full startup cost — loading hooks, skills, plugins, MCP servers, auto-memory, and CLAUDE.md — adds up. --bare strips all of that:

claude --bare -p "format this JSON"

In bare mode Claude skips hooks/skills/plugins/MCP/auto-memory/CLAUDE.md and exposes only Bash, Read, and Edit. It sets the CLAUDE_CODE_SIMPLE environment variable so your environment can detect it. Use --bare for fast, self-contained transformations where the project's full context would just be overhead — and don't use it when the task genuinely needs your CLAUDE.md conventions, MCP tools, or skills (it strips exactly those). Note also that claude setup-token does not work in --bare mode.

Two things to internalize before you build automation on top of headless mode.

The separate credit pool (effective June 15, 2026). Starting June 15, 2026, Agent SDK and claude -p usage on a subscription draws from a separate monthly Agent SDK credit pool, distinct from your interactive usage limits. In plain terms: your scripted/headless runs are metered apart from your hands-on terminal sessions. This is exactly why the budget flags matter — --max-budget-usd and --max-turns keep a fan-out loop or a chatty CI job from draining that pool unexpectedly. Plan your automation's cost against this separate bucket, not your interactive allowance. (And remember Claude Code overall requires a paid plan — Pro, Max, Team Premium, Enterprise, or Console; it is not on the free tier.)

From -p to the Agent SDK. claude -p is the headless entry point — great for shell scripts and pipelines. When you outgrow a one-line invocation and need to build a real custom agent — programmatic orchestration, fine-grained tool access, custom permission handling, multi-step control flow — you move up to the Agent SDK. The SDK gives you full control over the agentic loop in code while reusing the same output formats (text/json/stream-json) you learned here.

A simple rule for choosing:

• One query, from a script or pipeline → claude -p with the flags from this lesson.
• A custom agent with its own orchestration, tools, and permission logic → the Agent SDK.

Either way, the headless habits are the same: pipe or @-mention your inputs, pick an output format, bound the run with budgets, scope tools tightly, and append (never replace) the system prompt.