Claude Code Headless Mode: claude -p and CI

Claude Code Headless Mode

Claude Code headless mode usually means running Claude Code non-interactively with claude -p or --print. Use it for one-off scripts, CI summaries, GitHub issue triage, JSON output, and read-only audits where an interactive chat session would be too slow or hard to automate.

Quick Answer

Use claude -p when you want Claude Code to run once, produce output, and exit:

claude -p "Summarize the current git diff and list release risks"

For safer automation, set the output format, keep tool permissions narrow, and cap the run:

claude -p "Review this diff and return JSON risks" \
  --output-format json \
  --allowedTools "Read,Bash(git diff:*)" \
  --max-turns 3

What is Headless Mode

Headless mode allows you to use Claude Code programmatically without an interactive interface. Use the -p flag with a prompt to enable headless mode.

Basic Usage

claude -p "Analyze current project code quality and generate a report"

Common Parameters

• --output-format stream-json - Streaming JSON output
• --allowedTools - Specify allowed tools
• --max-turns - Limit how long the agent can continue
• --verbose - Verbose output for debugging

Use Cases

1. Issue Triage

Headless mode can support automation triggered by GitHub events:

claude -p "Analyze this GitHub Issue and add appropriate labels" \
  --allowedTools "Read,Bash(gh:*)"

2. Code Review

Subjective code review beyond traditional tool detection:

claude -p "Review the current git diff for bugs, regressions, and missing tests. Return findings with file paths and line references. Do not edit files." \
  --allowedTools "Read,Bash(git diff:*)"

For Claude Code review automation, keep the first pass read-only. Let Claude report evidence; apply fixes in a separate interactive session after you decide which findings are real.

3. Batch Processing

Handle large migrations or analysis tasks:

# Generate task list
claude -p "Generate list of files needing React to Vue migration"

# Process in loop
for file in $(cat migration-list.txt); do
  claude -p "Migrate $file from React to Vue" \
    --allowedTools "Edit,Bash(git commit:*)"
done

Important Notes

• Headless mode doesn't persist between sessions - must restart each time
• Use --verbose for debugging, disable in production
• Ensure stable network connection

Related: Multi-Claude Collaboration - Learn parallel collaboration workflows.