Claude Code Headless Mode Guide

Run Claude Code headless mode with print mode, JSON output, tool permissions, CI checks, and scripted automation.

Headless Mode runs Claude Code from a command or script without a full interactive terminal session. It is useful for repeatable checks, CI experiments, pull request summaries, issue triage, and structured analysis where the input and output boundaries are clear.

Basic Print Mode

Use -p or --print for a non-interactive prompt:

claude -p "Summarize the changes in this repository and list test risks"

Keep prompts specific. A vague automation prompt across a large repository can consume unnecessary usage and produce noisy output.

Structured Output

For automation, choose an output format that your script can parse:

claude -p "Review this diff and return the top risks" \
  --output-format json

For long-running workflows, streaming output can be easier to monitor:

claude -p "Analyze this pull request" \
  --output-format stream-json \
  --verbose

Use --verbose while debugging. Avoid noisy verbose logs in production automation unless you need them for traceability.

Permissions For Headless Workflows

Headless workflows should use explicit tools and permission mode:

claude -p "Summarize this pull request without changing files" \
  --allowedTools "Read,Glob,Grep,LS,Bash(git diff:*)" \
  --permission-mode plan

Do not use broad permissions for scripts that run on every commit. Keep write access, package installation, deployment, and destructive shell commands behind review.

Good Use Cases

Summarize a pull request and identify test gaps.
Turn an issue into a reproducible investigation checklist.
Review docs for outdated commands or broken links.
Generate a release note draft from recent commits.
Run a fixed code-quality prompt in a controlled CI job.

Poor Use Cases

Avoid Headless Mode for unclear architecture decisions, risky migrations, payment/auth changes, and work that needs product discussion. Use an interactive session with Plan Mode first.

Cost And Reliability Checklist

Keep the prompt narrow.
Restrict the files and tools Claude Code can inspect.
Prefer read-only automation until the workflow is proven.
Log the exact command and output format.
Use /status in interactive setup to confirm the credential path before moving automation to CI.