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:
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.CONCEPT Structured output & pre-approved tools make it safe to script
Two flags make headless runs deterministic enough for automation:
| Flag | What it does |
|---|---|
--output-format text | Default — plain text on stdout. |
--output-format json | One JSON object with the answer in .result, plus session_id, usage, and total_cost_usd. Parse with jq. |
--output-format stream-json | Newline-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 acceptEdits | Session-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. |
--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
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_usdin 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
EXAM TRAPS
--allowedTools or a permission mode
(acceptEdits, dontAsk); otherwise the run aborts at the first un-allowed tool.--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.claude -p." → Piped stdin is
capped at 10 MB. For bigger inputs, write to a file and reference the path in the prompt.-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.