Claude Code Headless Mode: Run It From Scripts and CI
Claude Code headless mode explained: claude -p, bare mode, allowed tools, JSON output, continuing runs and safe patterns for scheduled client automations.
Josh Pocock5 min read
AI Coding
Headless mode
Stride AI Academy
Claude Code headless mode runs Claude without the interactive interface: claude -p "your prompt" does the task and prints the result, so you can call it from scripts, scheduled jobs and CI. Add --allowedTools to pre-approve what it may do, --output-format json for structured results, and --bare for repeatable runs.
This guide covers the flags that matter, safe permission settings, structured output, continuing a run, and patterns for agency automations. Checked against Claude Code's headless docs, October 2026.
A headless run
- 1A script or schedule calls claude -p
- 2Claude does the taskOnly with the tools you allowed
- 3Output as text or JSONResult, cost estimate, session ID
- 4Your script uses itSaves, posts or checks the exit code
The basics
Add -p (or --print) to any claude command:
claude -p "What does the auth module do?"Claude Code exits with code 0 on success and non-zero on failure, so your scripts can branch on the result. It reads standard input, so you can pipe data in:
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txtPiped input is capped at 10MB. For bigger inputs, write a file and reference it in the prompt.
Think of headless mode as the CLI without the interactive terminal session. Run it from your project directory, like any other command. It suits any developer workflow where coding work has to run unattended, such as a CI job or a nightly script.
Bare mode for repeatable runs
By default, claude -p loads the same things an interactive session does: hooks, skills, MCP servers, CLAUDE.md and plugins from the folder and ~/.claude. Add --bare to skip all of that, so the run behaves the same on every machine:
claude --bare -p "Summarize README.md" --allowedTools "Read"Bare mode needs ANTHROPIC_API_KEY set, because it doesn't use your subscription login. Pass anything you need explicitly with flags such as --append-system-prompt, --settings and --mcp-config. The docs recommend bare mode for scripted calls and say it will become the default for -p in a future release.
One security note from the docs: without --bare, a -p run in a folder runs that project's hooks and connects its MCP servers with no trust prompt. Use --bare when running against repositories you don't control.
Permissions: what it's allowed to do
Nobody is there to approve actions, so decide up front:
--allowedToolspre-approves specific tools, for example--allowedTools "Read,Edit,Bash". You can narrow Bash to command prefixes, such as"Bash(git diff *),Bash(git log *)".--permission-mode dontAskdenies anything that would otherwise prompt, which suits locked-down CI.--permission-mode acceptEditslets it edit files and run common filesystem commands without asking.--permission-prompts nonemakes unattended runs deny anything unresolved instead of waiting, and tells Claude not to retry.
For client systems, start with the narrowest set that works: read-only tools for reports and reviews, editing only where the job needs it.
Structured output
Ask for JSON to get the result plus metadata:
claude -p "Summarize this project" --output-format jsonThe response has the text in result, a session_id, and a total_cost_usd estimate. To force a shape, add a JSON Schema:
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"]}'The structured data arrives in structured_output. For live progress, use --output-format stream-json.
Continue a run
Each -p call is a new conversation unless you continue one:
claude -p "Review this codebase for performance issues"
claude -p "Now focus on the database queries" --continueTo resume a specific conversation, capture its ID and pass --resume with it. That's useful when a scheduled job runs in steps.
Patterns for agency work
- A weekly client summary. A scheduled job asks Claude to summarise the week's commits and closed issues in a client's repository and saves the result for your report. Read-only tools only.
- A pre-merge review. Pipe a pull request diff into Claude with a review prompt, and post the result. The GitHub Action wraps this pattern for you (Claude Code with GitHub), and Claude Code review covers the built-in review commands.
- Log triage. Pipe yesterday's error log in and ask for the three most important issues.
- A typo or style check as an npm script, piping
git diff maininto a short prompt.
In every case: fixed prompt, narrow tools, structured output, and a person reviewing anything that changes code or reaches a client.
If you'd rather not keep your own machine or server running for scheduled jobs, Claude routines run the same kind of task on Anthropic's cloud.
Costs and limits
Each run uses model tokens. With an API key that's billed per token, and total_cost_usd in the JSON output lets your scripts track spend. Cap runs with --max-turns or --max-budget-usd, and add timeouts in your scheduler. See how much Claude Code costs.
Headless mode or the Agent SDK?
claude -p is the Agent SDK as a command-line tool. For scripts and CI it's usually enough. When you need tool approval callbacks, native message objects or an agent inside your own app, use the Python or TypeScript SDK (Agent SDK tutorial).
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls. Many of the free guides cover Claude Code setups.
FAQ
What is headless mode in Claude Code?
It's running Claude Code non-interactively with claude -p "prompt". Claude does the task and prints the result, so you can use it in scripts, scheduled jobs and CI. The docs describe it as the Agent SDK available from the command line.
Does headless mode use my subscription?
A normal claude -p run can use your signed-in session. Bare mode (--bare) doesn't read your login or keychain and needs ANTHROPIC_API_KEY set. For automations you run for clients, an API key is the cleaner choice.
How do I stop headless Claude from doing something unsafe?
Pre-approve only the tools it needs with --allowedTools, use --permission-mode dontAsk to deny anything else, run in --bare mode against repositories you don't control, and cap runs with --max-turns. Review any code changes before they merge.
Can I get JSON output from Claude Code?
Yes. Use --output-format json for the result plus metadata such as the session ID and cost estimate, and add --json-schema to get output in a shape you define, returned in the structured_output field.


