Headless Claude Code in CI/CD: Automated PR Reviews, Security Audits & Code Migration

Most teams interact with Claude Code through interactive terminal prompts. But one of its most potent architectural primitives is Headless Mode (-p / --print).

In headless mode, Claude Code accepts a prompt via command-line arguments or standard input, executes reasoning and tool calls without rendering an interactive TUI, streams or returns the result, and terminates with standard process exit codes.

This makes Claude Code fully embeddable inside GitHub Actions, GitLab CI, cron jobs, and custom deployment pipelines.

Here is how we integrate headless Claude Code into enterprise CI/CD workflows.

---

1. The Headless Invocation Primitive

To invoke Claude headlessly from a shell script:

# Basic headless execution
claude -p "Audit src/lib/auth.ts for timing attack vulnerabilities"

# Streaming output directly to a file
claude -p "Summarize all changes between git tags v1.2.0 and v1.3.0" > RELEASE_NOTES.md

You can also pipe standard input directly into Claude:

# Pipe git diff directly into Claude's prompt
git diff origin/main...HEAD | claude -p "Review this git diff for POPIA data protection compliance. Return JSON only with keys: passed (boolean), violations (array)."

---

2. Automated Pull Request Code Review Workflow

Below is a production-tested GitHub Actions workflow that executes Claude Code on every incoming Pull Request, reviews code modifications, checks for security regressions, and posts actionable markdown review comments directly back to the PR.

# .github/workflows/claude-pr-review.yml
name: Claude Code Automated PR Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

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

      - name: Run Headless Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # Extract changed files diff
          DIFF_CONTENT=$(git diff origin/${{ github.base_ref }}...HEAD)
          
          # Run Claude headlessly with strict reviewer persona
          REVIEW_OUTPUT=$(claude -p "You are a Principal Software Engineer. Review this git diff:
          
          $DIFF_CONTENT
          
          Provide a concise technical review focusing exclusively on:
          1. Security flaws, injection risks, and secret exposure
          2. Unhandled edge cases and null pointer regressions
          3. Performance bottlenecks and unindexed database queries
          
          If code is clean, say 'LGTM'. Otherwise, specify file:line and exact fix.")
          
          # Save to environment file for next step
          echo "$REVIEW_OUTPUT" > review.md

      - name: Post PR Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `### 🤖 Claude Code Automated Engineering Review\n\n${review}`
            });

---

3. Automated Weekly Technical Debt Migrations

Beyond passive code review, headless Claude Code can proactively execute codebase refactoring sprints on a scheduled cron trigger.

For example, automatically updating deprecated API endpoints or migrating legacy React components:

#!/usr/bin/env bash
# run-migration.sh - Scheduled migration runner

set -euo pipefail

git checkout -b chore/migrate-to-fetch
claude -p "Search for all instances of axios in /src. Migrate each call to native fetch with AbortSignal timeouts. Run npm test. Commit changes if tests pass."

if git diff --quiet origin/main; then
  echo "No changes needed."
else
  git push origin chore/migrate-to-fetch
  gh pr create --title "Automated Migration: Axios to Native Fetch" --body "Automated refactor generated and verified by Claude Code."
fi

---

4. Cost Safeguards in Automated Pipelines

When embedding LLM agents in CI, strict guardrails are necessary to avoid run-away token expenditure:

• Set Max Turns: Use flags to limit autonomous tool-use iterations.
• Diff Thresholding: Skip AI reviews on oversized PRs (e.g., lockfile updates or generated documentation assets).
• Fast Models for Triage: Use claude-3-5-haiku for routine formatting checks and elevate to claude-3-7-sonnet only for complex architectural reviews.

Headless automation bridges the gap between ad-hoc local development and continuous quality assurance.