Headless Automation

Headless Automation Skill

Trigger

Use when you want Claude to work autonomously in CI/CD pipelines, pre-commit hooks, batch processing, or any automated workflow.

The Insight

From Anthropic's Claude Code best practices: "Use -p flag with prompts for CI/CD, pre-commit hooks, and infrastructure. Employ 'fanning out' for large migrations or 'pipelining' for data processing workflows."

Basic Headless Usage

The -p Flag

Run Claude with a prompt, get output, exit:

# Simple prompt
claude -p "Explain what this function does" < src/utils.ts

# With file context
claude -p "Review this PR for security issues" --files $(git diff --name-only main)

# Output to file
claude -p "Generate API documentation" > docs/api.md

Print Mode (--print)

Get raw output without interactive formatting:

claude -p "List all TODO comments" --print

Automation Patterns

Pattern 1: CI/CD Integration

GitHub Actions Example:

name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Review
        run: |
          claude -p "Review the changes in this PR. Focus on:
          - Security vulnerabilities
          - Performance issues
          - Code style violations

          Output as GitHub PR comment markdown." \
          --files $(git diff --name-only origin/main)

Pre-commit Hook:

#!/bin/bash
# .git/hooks/pre-commit

# Get staged files
FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx)$')

if [ -n "$FILES" ]; then
  claude -p "Check these files for obvious bugs or issues.
  Output only if problems found, otherwise output nothing." \
  --files $FILES

  if [ $? -ne 0 ]; then
    echo "Claude found issues. Please review."
    exit 1
  fi
fi

Pattern 2: Fan-Out for Large Migrations

Process many items in parallel:

#!/bin/bash
# migrate-all.sh

# Step 1: Generate task list
claude -p "List all files that need migration from API v1 to v2.
Output as plain file paths, one per line." --print > migration-tasks.txt

# Step 2: Process in parallel
cat migration-tasks.txt | xargs -P 4 -I {} bash -c '
  claude -p "Migrate this file from API v1 to v2.
  Apply changes directly." --files {}
'

# Step 3: Verify
claude -p "Verify all migrations completed successfully.
Check for any remaining v1 API usage."

Pattern 3: Pipeline Processing

Chain Claude operations:

#!/bin/bash
# data-pipeline.sh

# Stage 1: Extract
claude -p "Extract all API endpoint definitions from src/api/" \
  --print > /tmp/endpoints.json

# Stage 2: Transform
claude -p "Convert these endpoints to OpenAPI 3.0 format" \
  < /tmp/endpoints.json > /tmp/openapi.json

# Stage 3: Generate
claude -p "Generate TypeScript client from this OpenAPI spec" \
  < /tmp/openapi.json > src/generated/api-client.ts

Pattern 4: Batch Processing

#!/bin/bash
# process-batch.sh

# Process each item in a list
while IFS= read -r item; do
  claude -p "Process: $item" --print >> results.txt
done < items.txt

Pattern 5: Scheduled Tasks

Cron job for daily reports:

# crontab -e
0 9 * * * cd /path/to/project && claude -p "Generate daily code health report" > reports/$(date +%Y-%m-%d).md

Safe Automation Practices

Use Containers for Risky Operations

# Run in isolated Docker container
docker run --rm -v $(pwd):/workspace \
  claude-code -p "Refactor all deprecated API calls" \
  --dangerously-skip-permissions

Limit Scope

# Only touch specific directories
claude -p "Update imports" --files src/components/*.tsx

Dry Run First

# Preview changes without applying
claude -p "Show what changes would be made to migrate to React 18.
Don't make any changes, just list them."

Capture Output for Review

# Log all output
claude -p "Apply linting fixes" 2>&1 | tee automation.log

Useful Flags for Automation

Template: Migration Script

#!/bin/bash
set -e

TASK="Migrate from moment.js to date-fns"
PATTERN="*.ts *.tsx"

echo "=== Starting: $TASK ==="

# 1. Discover affected files
echo "Finding affected files..."
FILES=$(claude -p "List files using moment.js" --print)
echo "Found $(echo "$FILES" | wc -l) files"

# 2. Process each file
echo "$FILES" | while read -r file; do
  echo "Processing: $file"
  claude -p "Migrate $file from moment.js to date-fns.
  Preserve all functionality." --files "$file"
done

# 3. Verify
echo "Verifying migration..."
claude -p "Check for any remaining moment.js usage"

# 4. Run tests
echo "Running tests..."
npm test

echo "=== Complete: $TASK ==="