Claude Code Headless Mode

Updated May 2026 · Automation & CI/CD

Claude Code is designed for interactive use, but its --print flag unlocks fully non-interactive automation. This page covers every headless pattern: CI pipelines, shell scripts, Docker containers, and batch processing — with working examples for each.

The Core Flag: --print (alias: -p)

By default, claude opens an interactive REPL. Add --print to get a single response to stdout and exit:

# Interactive (default) — opens a chat session
claude

# Non-interactive — prints response and exits
claude --print "What does this repo do?"
claude -p "List all exported functions in src/"

Key Flags Reference

Piping Input

Pass content to Claude via stdin — useful for code review and diff analysis:

# Pipe git diff for PR description
git diff HEAD~1 | claude --print "Write a concise PR description for these changes"

# Pipe a file for analysis
cat src/auth.ts | claude --print "Find security issues in this TypeScript file"

# Pipe from a heredoc
claude --print <<'EOF'
Review this SQL query for injection vulnerabilities:
SELECT * FROM users WHERE id = '$userId'
EOF

JSON Output Mode

Use --output-format json to get a machine-parseable response. Combine with jq to extract the text:

# Get structured response
claude --print --output-format json "List the top 3 bugs in src/" | jq -r '.result'

# Example JSON shape returned:
# {
#   "result": "1. Missing null check at line 42...",
#   "model": "claude-sonnet-4-6",
#   "input_tokens": 2341,
#   "output_tokens": 187
# }

GitHub Actions Integration

Add ANTHROPIC_API_KEY to your repository Secrets, then use Claude Code in a workflow step:

# .github/workflows/ai-review.yml
name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run AI review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff HEAD~1 | claude --print --no-color \
            "Review this diff. Focus on: bugs, security issues, missing error handling. \
             Output as markdown with a Verdict (PASS/NEEDS CHANGES) at the top." \
            | tee review.md

      - name: Post review as PR comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs')
            const body = fs.readFileSync('review.md', 'utf8')
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '## AI Code Review\n\n' + body
            })

Docker Container Setup

Run Claude Code in a Docker container — useful for isolated CI environments:

# Dockerfile
FROM node:20-slim
RUN npm install -g @anthropic-ai/claude-code
WORKDIR /workspace
ENTRYPOINT ["claude"]

# Build and run
docker build -t claude-code-runner .
docker run --rm \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  -v "$(pwd)":/workspace \
  claude-code-runner \
  --print --dangerously-skip-permissions \
  "Add JSDoc comments to all exported functions"

Shell Script Patterns

#!/usr/bin/env bash
# Nightly code health check
set -euo pipefail

export ANTHROPIC_API_KEY="$(cat ~/.anthropic-key)"

# Analyze each changed file
git diff --name-only HEAD~7 HEAD -- '*.py' | while read -r file; do
  echo "=== Reviewing $file ==="
  claude --print --model claude-haiku-4-5-20251001 \
    "In 3 sentences, summarize the quality of this file and flag any issues:" \
    "$(cat "$file")"
done

# Generate weekly changelog from commits
git log --oneline HEAD~7..HEAD \
  | claude --print "Convert these commits to a user-facing changelog. Group by: Features, Fixes, Other."

Batch Processing Files

#!/usr/bin/env bash
# Add type hints to all Python files in parallel
find . -name "*.py" -not -path "./.venv/*" | head -20 | while read -r f; do
  (
    echo "Adding type hints to $f"
    claude --print --auto-accept-edits \
      "Add Python type hints to all function signatures in this file. \
       Do not change logic. Only add annotations." \
      < "$f" > /dev/null
  ) &
done
wait
echo "Done"

Environment Variable Configuration

Cost Control in Automation

Frequently Asked Questions

→ Full CI/CD Workflow Guide

→ Claude Code Hooks — automate pre/post actions

← Back to Home