Headless Mode & CI/CD

Claude Code doesn't need you watching

Everything so far has been interactive: you type, Claude responds, you approve. That's the normal mode.

But Claude Code also runs without you. You pipe in a prompt, it does the work, and pipes out the result. No chat, no approval prompts, no human in the loop.

This is how Claude Code becomes part of your build pipeline.

Headless mode in action

The `-p` flag: pipe mode

The key flag is -p. It makes Claude Code non-interactive:

# Basic: prompt as argument
claude -p "list all TODO comments in this project"

# Pipe stdin: feed data to Claude
cat error.log | claude -p "summarize the errors and suggest fixes"

# Pipe output: capture the result
claude -p "generate a changelog from recent commits" > CHANGELOG.md

# Chain: one Claude call feeds another
git diff | claude -p "review this diff" | claude -p "format as markdown table"

Key differences from interactive mode: no approval prompts, no tool permission dialogs, output goes to stdout, errors to stderr. Exit code 0 on success, non-zero on failure. You can script around it like any other Unix tool.

CI/CD integration

GitHub Actions

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

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Review PR
        run: |
          git diff origin/main...HEAD | claude -p "Review this diff for bugs, 
          security issues, and style violations. Be concise." > review.md
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - name: Post review
        run: gh pr comment ${{ github.event.number }} --body-file review.md

Pre-commit hook

#!/bin/bash
# .git/hooks/pre-commit
git diff --cached | claude -p --model haiku \
  "Check this diff for: hardcoded secrets, console.log statements, 
   TODO comments. Reply 'PASS' if clean, or list issues." | \
  grep -q "PASS" || { echo "Review failed. Fix issues first."; exit 1; }

Automated test analysis

# Run tests, feed failures to Claude
npm test 2>&1 | claude -p "Analyze these test results. 
  For each failure, explain the likely cause and suggest a fix."

Model selection for headless

Use the --model flag to match the model to the job:

# Haiku for fast, cheap tasks (linting, formatting checks)
claude -p --model haiku "check this file for style issues"

# Sonnet for standard tasks (code review, analysis)
git diff | claude -p --model sonnet "review this diff"

# Opus for complex tasks (architecture review, security audit)
claude -p --model opus "audit this codebase for security vulnerabilities"

Haiku for high-volume automated checks. Sonnet for standard CI tasks. Opus only when the stakes justify the cost. A full CI pipeline with 2 Haiku calls and 1 Sonnet call typically runs under $0.05.

Chaining Claude calls in a CI pipeline

Practical examples

Generate release notes

git log v1.2.0..HEAD --oneline | claude -p \
  "Generate release notes from these commits. Group by: Features, Fixes, Other. 
   Write for end users, not developers." > release-notes.md

Automated documentation

claude -p "Read all TypeScript files in src/api/ and generate 
  API documentation in Markdown format" > docs/api-reference.md

Nightly codebase health check

claude -p "Analyze this project for: dead code, unused dependencies, 
  files over 500 lines, missing tests for public functions. 
  Output as a checklist." | tee health-report.md

Security: don't skip this section

Headless mode runs with whatever API key is in the environment. In CI:

Use secrets management. Never hardcode API keys in workflow files.
Scope permissions. Use project-level API keys with limited access.
Review outputs. Automated Claude output should be reviewed before merging or deploying.
Watch your costs. Automated pipelines can spend fast. Use Haiku for high-frequency checks, set spend alerts in the Anthropic console.

Patterns