Claude Code headless mode (-p): scripting batch jobs for your website

Headless mode is Claude Code without the conversation. You run claude -p with a prompt, Claude does the task, prints the result and exits. Anthropic now calls it non-interactive mode ("Formerly called headless mode"), and it is how you put Claude Code into a script, a scheduled job on a server or a build pipeline. For a website, it suits batch work you can describe precisely and check afterward: auditing every page for a missing meta description, explaining a failed build log, or producing a structured report on a folder of content.

The catch is that nobody is there to approve anything. A scripted run can't stop to ask whether it should edit a template or run a command, so what it may do has to be decided in advance, in flags and settings. This guide covers the flags that matter, safe permission choices, how billing works, and how to review batch output, as of October 2026. It is a developer-level topic. If nobody on your team runs scripts, the desktop app or a cloud session will serve you better.

What headless mode is for, and what it isn't

Anthropic's glossary describes non-interactive mode as running "a single prompt" and exiting, "Used for CI, scripts, and piping." It is a command-line feature. The desktop app is "interactive only," and Anthropic calls the CLI "the most complete surface for terminal-native work: scripting and the Agent SDK are CLI-only." Our Claude Code glossary defines the related terms.

If you want a check on every pull request, GitHub Actions wraps this same engine in your repository's pipeline. That route is covered in Claude Code in GitHub Actions for website QA.

The basic commands

These are Anthropic's own examples from its non-interactive mode documentation.

• Ask a question and print the answer: claude -p "What does the auth module do?"
• Pipe a file in and save the answer: cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt. Piped input is capped at 10 MB; for larger inputs, write a file and name it in the prompt.
• Get JSON back: claude -p "Summarize this project" --output-format json. The text is in the result field, and the payload includes total_cost_usd.
• Continue a conversation: run a first -p call, then claude -p "Now focus on the database queries" --continue, or capture the session ID from JSON output and pass it to --resume.

The output formats are text (the default), json and stream-json, which emits one JSON event per line as Claude works. To get data in a fixed shape, add --json-schema with a JSON Schema definition, and the answer arrives in a structured_output field. That is how you turn "audit these pages" into a file another script or spreadsheet can read reliably.

Bare mode: predictable runs

By default, a -p run discovers and loads hooks, skills, plugins, MCP servers, auto memory and CLAUDE.md, just like an interactive session. That makes results depend on whoever's machine runs the script. --bare skips all of that.

It also closes a real gap. Anthropic's docs say: "Without --bare, a -p session runs the hooks in a project's .claude/settings.json and connects the servers in its .mcp.json, even in a folder you've never trusted. A -p session shows no workspace trust dialog and no per-server approval prompt." Running claude -p inside a repository you just downloaded means running its hooks.

What changes in bare mode:

• Claude has the Bash, file read and file edit tools. Anything else you pass by flag: --settings, --mcp-config, --append-system-prompt, --agents or --plugin-dir.
• Bare mode "never reads OAuth credentials or the system keychain." You set ANTHROPIC_API_KEY with a key from the Claude Console, so usage bills to the API, not your subscription.
• Anthropic recommends it "for scripted and SDK calls," and says it "will become the default for -p in a future release."

Anthropic's minimal example: claude --bare -p "Summarize README.md" --allowedTools "Read"

Permissions for unattended runs

This is where most scripted mistakes start. Anthropic's docs warn that a run with no mode set "takes the built-in starting permission mode, which can be auto, so pass the one you want." The choices that matter in scripts:

--allowedTools uses permission rule syntax. Anthropic's commit example pre-approves only git read commands and the commit itself:

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 *)"

The space before each * matters. Without it, a rule can match longer commands than you meant.

Never use --dangerously-skip-permissions on a machine that can reach your real site. Anthropic says bypass mode "offers no protection against prompt injection or unintended actions" and is meant for isolated containers and VMs. Our guide to every permission mode covers the settings files, and our guide to hooks for website projects shows how to block risky commands with a hook that runs every time.

A worked batch job: missing meta descriptions

A hypothetical example, using only documented flags. The site's pages are Markdown files in a content/ folder of a git repository.

1. Branch first. Create a new git branch so every change is reviewable and reversible.
2. Run a read-only audit. claude -p "List every file in content/ whose front matter has no meta description. Return file paths only." --permission-mode dontAsk --output-format json. Check the list against a few files by hand.
3. Run the edit on a small sample. Ask Claude to write descriptions for five named files only, with --permission-mode acceptEdits and --max-turns set to a small number. Read the diff with git diff.
4. Check the second file, not just the first. When we rebuilt eseospace.com, one script replaced the wrong container, so new posts carried the template post's text. The first page looked fine. Look at several outputs.
5. Run the full batch, then run it again. Our house rule for every bulk edit: run on a copy, then twice on real files; the second run must change nothing. A second run that changes files means the job isn't stable.
6. Have a person review the diff and a sample of rendered pages before merging. A description written by Claude is a draft until someone checks it against the page.

The scripted pipeline that has published more than 300 articles on eseospace.com follows the same pattern: scripts do the repetitive work, a person approves what ships. Our eseospace.com rebuild case study describes it.

Cost, limits and accounts

• Which account pays. If ANTHROPIC_API_KEY is set, Claude Code uses it "instead of your Claude subscription." Bare mode always needs a key or a cloud provider's credentials. Without bare mode, -p can run on your subscription login.
• Subscription limits. Anthropic says advertised Pro and Max limits "assume ordinary, individual usage of Claude Code and the Agent SDK." Large unattended batches belong on API billing.
• Max API credits. The monthly API credits on Max (added 7 October 2026) can cover claude -p only when you run it with an API key from your linked Console organization. They don't cover interactive use.
• Caps. --max-turns limits agentic turns and exits with an error when reached. --max-budget-usd stops at an estimated spend, which can differ from your bill. For authoritative figures, use the Usage page in the Claude Console.
• Stopping a run. A -p run killed with SIGTERM exits with code 143 and leaves the turn unfinished.

Our guide to keeping Claude Code costs under control covers budgets across a team.

When a script outgrows the CLI

If you find yourself writing long shell scripts around claude -p, handling its JSON in another program, or wanting approval callbacks in your own interface, that is the Agent SDK's job. Anthropic's headless page calls -p "the Agent SDK via the CLI," and the SDK offers the same loop as Python and TypeScript libraries. Our guide to the Claude Agent SDK for business explains when that step makes sense.

Conclusion

Headless mode turns Claude Code into a command you can script: one prompt, one result, an exit code and, if you want it, structured JSON. That is ideal for repeatable website audits and narrow batch edits, provided you use bare mode, set the permission mode explicitly, pre-approve only what the job needs, cap turns, and treat every output as a draft a person reviews in git. If you want batch jobs or pipeline checks built for your site, our Claude Code development team can help. More guides are in our Claude Code Guide.

Frequently asked questions