headless-mode

Headless Mode

Run Claude Code programmatically for automation, CI/CD, and scripting.

Quick Reference

Core Concept

The -p (or --print) flag runs Claude Code non-interactively. All CLI options work with -p, enabling automated workflows without human interaction.

claude -p "Explain what this project does"

Essential Flags

Output Formats

Text (Default)

Plain text output for simple tasks:

claude -p "Summarize auth.py"

JSON (Structured)

Get metadata with response:

claude -p "Analyze this code" --output-format json

Returns:

{
  "result": "Analysis text...",
  "session_id": "abc123",
  "usage": { "input_tokens": 100, "output_tokens": 50 }
}

Stream JSON (Real-time)

Newline-delimited JSON for streaming:

claude -p "Generate report" --output-format stream-json

Tool Auto-Approval

Basic Approval

Allow specific tools without prompting:

claude -p "Fix the failing tests" --allowedTools "Bash,Read,Edit"

Granular Bash Commands

Restrict to specific bash patterns:

claude -p "Create a commit for staged changes" \
  --allowedTools "Bash(git diff:*),Bash(git log:*),Bash(git commit:*)"

Skip All Permissions (Dangerous)

Use only in trusted, sandboxed environments:

claude -p "Deploy to staging" --dangerously-skip-permissions

Session Management

Continue Last Session

claude -p "Review this codebase"
claude -p "Focus on the database layer" --continue
claude -p "Summarize findings" --continue

Resume Specific Session

# Capture session ID
session_id=$(claude -p "Start review" --output-format json | jq -r '.session_id')

# Later: resume that session
claude -p "Continue the review" --resume "$session_id"

Fork a Session

Create a new branch from an existing session:

claude -p "Try alternative approach" --resume $SESSION_ID --fork-session

System Prompt Customization

Append Instructions

Keep default behavior, add context:

claude -p "Review this PR" \
  --append-system-prompt "Focus on security vulnerabilities"

Replace System Prompt

Full control over Claude's behavior:

claude -p "Analyze code" \
  --system-prompt "You are a security auditor. Only report vulnerabilities."

Load from File

claude -p "Review code" --system-prompt-file ./prompts/security-review.txt

Structured Output (JSON Schema)

Force output to match a schema:

claude -p "Extract function names from utils.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Response includes structured_output field:

{
  "result": "...",
  "structured_output": {
    "functions": ["parseDate", "formatCurrency", "validateEmail"]
  }
}

Common Patterns

Code Review

gh pr diff "$PR_NUMBER" | claude -p \
  "Review this PR for bugs and improvements" \
  --output-format json

Test Fixing

claude -p "Run tests and fix failures" \
  --allowedTools "Bash,Read,Edit" \
  --max-turns 10

Documentation Generation

claude -p "Generate API documentation for src/api/" \
  --allowedTools "Read,Glob,Grep,Write"

Batch Processing

for file in src/*.ts; do
  claude -p "Add JSDoc comments to $file" \
    --allowedTools "Read,Edit"
done

Key Differences from Interactive Mode

Reference Files

Troubleshooting

No Output

Check if Claude is waiting for permission:

claude -p "query" --verbose

Add --allowedTools or --dangerously-skip-permissions.

JSON Parsing Errors

Use jq to extract fields:

claude -p "query" --output-format json | jq -r '.result'

Session Not Found

Sessions are directory-specific. Run from the same directory or use --session-id with a UUID.

Best Practices

1. Use JSON output for automation - easier to parse
2. Limit tools to only what's needed - security first
3. Set max-turns for predictable execution time
4. Capture session IDs for multi-turn workflows
5. Use --append-system-prompt to add context without losing defaults