D3 · Claude Code › Cluster 8 · Automation, MCP & Integrations

8.1 · Headless Mode & Scripting

claude -p for automation

CONCEPT -p turns Claude Code into a Unix filter

Add the -p (or --print) flag to any claude command and it runs non-interactively: it takes your prompt, does the work, prints a result, and exits. No TUI, no turn-by-turn chat. This is the headless mode that makes Claude Code scriptable — you can drop it into a shell pipeline, a package.json script, a git hook, or a CI job like any other command-line tool.

Because it reads stdin and writes stdout, headless mode composes with the rest of your toolchain. Pipe a build log in, redirect an explanation out:

🔑 The docs describe claude -p as running the same Agent SDK loop, tools, and context management that power the interactive CLI — just without the interactive shell. Everything you configure (CLAUDE.md, hooks, MCP servers) still loads unless you opt out with --bare.
Piped stdin is capped at 10 MB (as of v2.1.128). For larger inputs, write to a file and reference its path in the prompt instead of piping.

CONCEPT Structured output & pre-approved tools make it safe to script

Two flags make headless runs deterministic enough for automation:

FlagWhat it does
--output-format textDefault — plain text on stdout.
--output-format jsonOne JSON object with the answer in .result, plus session_id, usage, and total_cost_usd. Parse with jq.
--output-format stream-jsonNewline-delimited JSON events, streamed. Requires --verbose (and --include-partial-messages for token deltas).
--allowedTools "Bash,Read,Edit"Auto-approves those tools so the run doesn't block on a permission prompt. Accepts permission-rule syntax, e.g. Bash(git diff *).
--permission-mode acceptEditsSession-wide baseline instead of listing tools. dontAsk locks a run down to allow-listed + read-only commands.
--append-system-prompt "…"Adds instructions on top of the default prompt (use --system-prompt to fully replace it).
--continue / --resume <id>Continue the most recent conversation, or resume a captured session_id.
In an unattended run there's no human to answer a permission prompt. Pre-approve every tool the task needs with --allowedTools (or a permission mode), or the run aborts the first time Claude reaches for an un-allowed tool.

DIAGRAM How a headless call flows through a pipeline

flowchart TD STDIN["stdin (piped data)
e.g. git diff, build log"] --> CLI["claude -p 'prompt'
--allowedTools --output-format json"] CLI --> LOOP["Agent loop runs
tools auto-approved, no TUI"] LOOP --> Q{"--output-format?"} Q -->|"text (default)"| TXT["🟢 Plain text on stdout"] Q -->|"json"| JSON["🔵 {result, session_id,
total_cost_usd} → jq"] Q -->|"stream-json"| STREAM["🟠 NDJSON events
(needs --verbose)"] TXT --> OUT["> output.txt / exit code"] JSON --> OUT STREAM --> OUT classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef info fill:#cfe2ff,stroke:#0d6efd,color:#084298; classDef warn fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class TXT ok; class JSON info; class STREAM warn;

CODE Headless in a pipe, a script, and JSON parsing

Three real patterns straight from the docs: pipe a build error in, wire a linter into package.json, and capture a session id to resume.

# 1) Pipe stdin in, redirect the answer out — Claude as a filter
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

# 2) Run a task with pre-approved tools and get JSON back, then parse with jq
claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit" \
  --output-format json | jq -r '.result'

# 3) Capture the session id, then resume that exact conversation later
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

And as a project-local linter in package.json — piping the diff means Claude needs no Bash permission to read it:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. report filename:line then the issue. return nothing else.\""
  }
}

TRADE-OFFS Headless (-p) vs. interactive session

✅ Headless claude -p

  • Scriptable: pipes, CI jobs, cron, git hooks
  • Machine-readable output (--output-format json)
  • Deterministic surface via --allowedTools / --bare
  • Cost visible per run (total_cost_usd in JSON)

⚠️ Interactive CLI

  • Human answers permission prompts live
  • Better for exploration & back-and-forth
  • Full slash-command surface, tab completion
  • No unattended run — needs someone at the keyboard
Rule of thumb from the docs: CLI for interactive/one-off work, headless (SDK) for CI/CD and production automation. Many teams use both.

EXAM TRAPS

Trap: "Headless mode still pops permission prompts, so scripts hang." → In an unattended run there's nobody to answer. Pre-approve tools with --allowedTools or a permission mode (acceptEdits, dontAsk); otherwise the run aborts at the first un-allowed tool.
Trap: "--output-format stream-json just works." → It requires --verbose (and --include-partial-messages for text deltas). Plain json returns a single object with the answer in the .result field.
Trap: "Pipe as much data as you want into claude -p." → Piped stdin is capped at 10 MB. For bigger inputs, write to a file and reference the path in the prompt.
Trap: "-p and interactive are different products." → Same agent loop, tools, and context management. -p is the non-interactive interface to the same Claude Code, exposed through the Agent SDK CLI.

PRACTICE

Q1 · A cron job runs claude -p "fix failing tests" and stalls. Why, and what's the fix?

The task needs Bash/Edit, and with no human present the permission prompt has no one to answer, so the run aborts. Fix: pass --allowedTools "Bash,Read,Edit" (or a permission mode like acceptEdits / dontAsk) to pre-approve the tools.

Q2 · How do you get a script to read Claude's answer as a single machine-parseable value?

Use --output-format json; the answer is in the .result field of the returned object (alongside session_id and total_cost_usd). Extract it with jq -r '.result'. stream-json is for live token streaming and needs --verbose.

Q3 · You want a second headless call to continue the first one's context. How?

Capture the session_id from the first run's JSON output, then pass --resume "$session_id" on the next call (from the same project directory). --continue resumes the most recent conversation without needing the id.