Claude Code headless mode: run claude -p in scripts and pipelines

Before you start

You need Claude Code, a terminal and jq for the JSON examples. If permission rules are new to you, read the settings lesson first, because a headless run has no one to answer a prompt and the rules do all the deciding.

Anthropic's page for this is titled Run Claude Code programmatically. It calls claude -p the CLI form of the Agent SDK, which lesson 4 builds on. The flags below come from that page and from the CLI reference, read on 4 November 2026. The headless page was read again on 5 November.

Run a prompt, pipe data in, test the exit code

Non-interactive mode reads stdin, so Claude Code works like any command-line filter. This is Anthropic's example: a build log goes in and an explanation comes out as a file.

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

1. Run claude -p "What does the auth module do?". Claude Code prints the response and exits. -p is short for --print.
2. Pipe the build log in with the command above. Piped stdin is capped at 10MB, so write a bigger input to a file and name the path in the prompt.
3. Run echo $? right after. The exit code is 0 on success and non-zero when the run fails. An invalid flag is reported on stderr before the run starts.
4. Force a failure inside the run, for example by running without authentication. Claude Code prints the failure as the result on stdout, so a script should check the exit status before it trusts stdout.
5. Let Claude change files by naming tools: claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash".

Nobody is there to approve: tools, modes and prompts

In Claude Code v2.1.302 or later, a -p run with no permission mode set starts in Manual mode. A call that needs approval is denied unless an allow rule, a hook, a canUseTool callback or --permission-prompt-tool approves it. Decide in advance what may run.

For CI, Anthropic's permission modes page lists an exact allowlist with dontAsk. It denies everything that would prompt, and only the listed command and file reads run.

claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"

Output formats: text, json and stream-json

The default text output suits a human reading a terminal. A script wants json, which returns one object with the answer in result, the session_id, usage metadata, total_cost_usd and a per-model cost breakdown. Anthropic calls the cost a client-side estimate that can differ from your bill.

To get data in a shape you choose, add --json-schema with a JSON Schema. The checked data arrives in the structured_output field. An invalid schema stops the run with Error: --json-schema is not a valid JSON Schema, and the format keyword is read as a note and never enforced.

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

Continue a conversation without guessing which one

--continue loads the most recent conversation in the current directory. claude -p runs are skipped by a plain --continue, and claude -p --continue includes them. For anything that runs more than once, capture the ID from the JSON output and resume that exact session.

--resume also takes a session name or the absolute path of a session's .jsonl transcript. Claude Code finds an ID in any project on the machine, so the two commands can run from different directories. When you continue, total_cost_usd reports the whole conversation's spend, earlier runs included. --fork-session starts a new ID from an old conversation, and --no-session-persistence saves nothing at all.

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Make CI repeatable with --bare

A plain claude -p loads what an interactive session loads: hooks, skills, plugins, MCP servers, auto memory and CLAUDE.md, from the working directory and from ~/.claude. That is how a teammate's hook or a stray .mcp.json ends up in your CI job. Add --bare and Claude Code skips all of it, and Claude keeps the Bash, file read and file edit tools.

Bare mode never reads OAuth credentials or the system keychain. Set ANTHROPIC_API_KEY, or supply an apiKeyHelper in the --settings JSON. Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry still read their own credentials. Before v2.1.286 the limits held only partly, so check your version.

claude --bare -p "Summarize README.md" --allowedTools "Read"

Put it in a script, and give it limits

This script from the page pipes a pull request diff into Claude and asks for a security review. Save it as review.sh and run bash review.sh 123. The shell swaps "$1" for 123, and the review comes back as JSON with the text in result.

A script also needs ceilings. These are the ones the docs describe.

Versions matter too. Four releases since September changed what a -p run does, so check claude --version on the runner against them before you trust an old script.

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

• --max-turns limits agentic turns in print mode, and there is no limit by default.
• --max-budget-usd stops the run when the estimated spend reaches the amount. Subagent spend counts, and spend can pass the cap, so leave headroom.
• SIGTERM ends the run with exit code 143 and records no result for the turn in progress. Send SIGINT first, or call the SDK's interrupt(), to end the turn cleanly.
• After the answer, a run stays open for background work it started. Idle waiting stops after 10 minutes by default, and CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS changes the cap.
• A system/init event in stream-json output lists loaded plugins and MCP servers. A non-empty mcp_server_errors array means a server never loaded, so a CI gate can fail on it.

Why Claude Code's creator wants --bare in every script

Boris Cherny created Claude Code, and he made --bare tip 12 of a thread on X in March. Out of the box, claude -p and the TypeScript and Python SDKs search for local CLAUDE.md files, settings and MCP servers. The search is slow. A script usually wants to name what it loads instead, and he put the startup gain at up to ten times. He also called the old default a design oversight from when the team first built the SDK.

His post promised that a future version would flip the default to --bare. That has not happened yet. The headless page still calls it the recommended mode for scripts and a future default, so the flag is yours to add.

Add it to every CI call now. Your jobs keep the same behavior on the day the default flips. Until then, no teammate's hook or stray .mcp.json slips into the run.

A screenshot of X's own embed of the post, taken on 5 November 2026, with the time in UTC. X cuts the post short with Show more. Select it to open the post on X.

Common mistakes

• Using --bare with no API key. Bare mode skips the subscription login, so the run fails to authenticate until ANTHROPIC_API_KEY is set.
• Reading structured_output without checking it exists. A run that ends without valid structured output, for example because Claude declined, has no such field.
• Running claude -p in a repository you did not write. Without --bare it runs that project's hooks and connects its .mcp.json servers with no trust dialog. Start with --bare, or pass --setting-sources user.
• Relying on --continue in a shared directory. It picks the most recent conversation there, so a second job changes which one that is. Capture the session ID.
• Stopping a job with SIGTERM and expecting a result. The turn in progress is left unfinished.

Try it yourself

• Pipe git diff main into claude -p with --append-system-prompt set to a reviewer's brief. Run it once with text and once with json, and compare what a script could do with each.
• Write a shell snippet that runs a prompt with --output-format json, stops when the exit code is not 0, and prints .result and .total_cost_usd with jq.
• Run a prompt with --output-format stream-json --verbose and find the system/init event. List its plugins and MCP servers, then repeat with --bare and compare.
• Set --max-turns 3 on a task that needs more turns, and note what your script receives.

Next: Claude Code in GitHub Actions

Everything above gets harder on a CI runner, where nobody watches the run and secrets sit in its environment. The next lesson, Claude Code in GitHub Actions, sets up the official action and the secrets, permissions and cost limits around it.

Hooks run your own commands at set points of a session, and --bare skips them. The hooks lesson lists the events a hook can run on.

Frequently asked questions

Sources

1. Claude Code docs: Run Claude Code programmatically (read November 5, 2026)https://code.claude.com/docs/en/headless
2. Claude Code docs: CLI reference (read November 4, 2026)https://code.claude.com/docs/en/cli-reference
3. Claude Code docs: Permission modes (read November 4, 2026)https://code.claude.com/docs/en/permission-modes
4. Claude Code release v2.1.259 on GitHub (read November 5, 2026)https://github.com/anthropics/claude-code/releases/tag/v2.1.259
5. Claude Code release v2.1.286 on GitHub (read November 5, 2026)https://github.com/anthropics/claude-code/releases/tag/v2.1.286
6. Claude Code changelog (read November 5, 2026)https://code.claude.com/docs/en/changelog
7. Boris Cherny on X: use --bare to speed up SDK startup (read November 5, 2026)https://x.com/bcherny/status/2038454357088457168