Claude Code headless mode: claude -p for scripts and CI
Run Claude Code headless with claude -p: piping input, JSON and schema output, auto-approving tools, bare mode for CI, unattended runs, and resuming sessions.
Some of the most useful places to run Claude Code have nobody watching: a build script that explains failures, a nightly job that updates dependency pins, a pre-merge check that reads a diff. Headless mode is how you run it there.
This guide covers claude -p from Anthropic's headless documentation, checked on 16 November 2026. Anthropic describes it as the command-line form of the Agent SDK; the Python and TypeScript SDKs give finer control.
The basics
Add -p (or --print) to run non-interactively:
claude -p "What does the auth module do?"
It exits with code 0 on success and non-zero on failure, so scripts can branch on it. It reads stdin, so it works in pipes:
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
Piped input is capped at 10MB; for larger inputs, write a file and name it in the prompt.
Bare mode for CI
Without extra flags, claude -p loads everything an interactive session would: hooks, skills, subagents, plugins, MCP servers, auto memory, and CLAUDE.md, from the project and from ~/.claude. On a CI runner, or a teammate's machine, that means results depend on whatever happens to be configured.
--bare skips all of that:
claude --bare -p "Summarize README.md" --allowedTools "Read"
Anthropic recommends bare mode for scripted calls and says it will become the default for -p. Two things to know:
- Auth. Bare mode never reads OAuth credentials or the keychain. Set
ANTHROPIC_API_KEY, or provide anapiKeyHelperin--settings. - Load only what you pass. Add context with flags:
--append-system-prompt,--settings,--mcp-config,--agents,--plugin-dir. Hooks don't run in bare mode at all, so don't use it for a run that needs them.
A related warning from the documentation: without --bare, a -p run in a folder you've never trusted still runs that project's hooks and connects its MCP servers, with no trust dialog.
Approve tools
In a Manual-mode -p run, any call that needs approval is denied unless something approves it. Two ways to grant access:
List specific tools with permission rule syntax:
claude -p "Look at my staged changes and create an appropriate commit" \
--allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
Set a baseline mode: acceptEdits for file changes, dontAsk for locked-down CI that denies anything not pre-approved, or auto for a classifier that reviews each action.
For runs where nobody can answer a prompt, add --permission-prompts none, and anything that would wait for a person is denied instead:
claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none
Rule syntax and modes are covered in Claude Code permissions.
Structured output
--output-format json returns the result, the session ID, and metadata, including total_cost_usd:
claude -p "Summarize this project" --output-format json | jq -r '.result'
Add --json-schema to get output in a fixed shape, in the structured_output field:
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"]}'
If the run ends without valid structured output, for example because Claude declined, the field is missing, so check before using it. For real-time output, use --output-format stream-json.
Useful patterns
A project-specific linter, in package.json:
{
"scripts": {
"lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
}
}
A security review of a pull request:
gh pr diff "$1" | claude -p \
--append-system-prompt "You are a security engineer. Review for vulnerabilities." \
--output-format json
Multi-step conversations, continuing the last one or a specific one:
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"
Skills work in -p mode: include /skill-name in the prompt.
Before running unattended
Anthropic's best practices list five questions for any run nobody is watching: does it know what done looks like, can it check its own work, what is it allowed to touch, what stops it (such as --max-turns), and who approves the result. See Claude Code best practices. For running inside GitHub workflows, see Claude Code GitHub Actions.
What a script doesn't know
A headless run in bare mode deliberately loads nothing from the project, and even a normal run only knows what the repository says. A decision made in a planning meeting or a Slack thread reaches neither.
Where Lockstep fits
Lockstep keeps approved decisions in a record Claude Code can query over MCP. Decisions are captured from PRDs, Slack, and pull requests and become binding when their owner approves them. Interactive Claude Code sessions are briefed automatically at start; for a scripted run, you'd pass Lockstep's MCP server explicitly, and its token currently comes from an interactive lockstep login, so check the token lifetime before relying on it in CI.
See how it works.
Sources checked 16 November 2026
Related reading
For permission rules used in --allowedTools, see Claude Code permissions. For settings files and --settings, see Claude Code settings.json. To watch cost and context interactively, see Claude Code status line. For embedding the agent in an application instead, see Claude Agent SDK vs Claude Code.
Frequently asked questions
- What is Claude Code headless mode?
- Running Claude Code non-interactively with -p (or --print): claude -p "prompt". It reads stdin, prints the response, and exits with code 0 on success and non-zero on failure, so scripts and CI can use it like any command-line tool. Anthropic documents it as the CLI form of the Agent SDK.
- How do I authenticate Claude Code in headless mode?
- A normal claude -p run uses your existing login. In bare mode, Claude Code never reads OAuth credentials or the keychain, so set ANTHROPIC_API_KEY in the environment, or supply an apiKeyHelper in --settings. Cloud providers read their own credentials.
- What is --bare in Claude Code?
- A flag that skips auto-discovery of hooks, skills, commands, subagents, plugins, MCP servers, auto memory, and CLAUDE.md, so a run gives the same result on every machine. Anthropic recommends it for scripted calls and says it will become the default for -p.
- How do I get JSON output from Claude Code?
- Pass --output-format json for the result, session ID, and metadata, including total_cost_usd. Add --json-schema with a JSON Schema to get output matching that schema in the structured_output field; check the field exists before using it.
- How do I approve tools in a headless run?
- List them with --allowedTools, using permission rule syntax such as "Bash(git diff *),Read", or set a baseline with --permission-mode, such as acceptEdits, dontAsk, or auto. In a Manual-mode -p run, a call that needs approval is denied unless something approves it.
Keep reading