Headless Mode Skill | Agent Skills

Headless Mode

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

Quick Reference

| Mode | Command | Use Case | |------|---------|----------| | CLI (simple) | claude -p "prompt" | One-shot tasks, scripts | | CLI (structured) | claude -p "prompt" --output-format json | Parsing responses | | TypeScript SDK | @anthropic-ai/claude-code | Full programmatic control | | Python SDK | claude-code-sdk | Python automation |

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

| Flag | Purpose | Example | |------|---------|---------| | -p, --print | Run non-interactively | claude -p "query" | | --output-format | Response format | json, stream-json, text | | --allowedTools | Auto-approve tools | "Bash,Read,Edit" | | --max-turns | Limit agent turns | --max-turns 5 | | --continue | Continue last session | claude -p "..." --continue | | --resume | Resume specific session | --resume $SESSION_ID |

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

| Feature | Interactive | Headless (-p) | |---------|-------------|-----------------| | Slash commands | Available | Not available | | Permission prompts | Interactive | Auto-approve or skip | | Output | Formatted | Raw text/JSON | | Session | Persistent | One-shot (unless --continue) |

Reference Files

| File | Contents | |------|----------| | CLI-FLAGS.md | Complete CLI flag reference | | SDK.md | TypeScript and Python SDK usage | | EXAMPLES.md | Practical automation examples |

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

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

Agent Skills: Headless Mode

Skill Files