Claude Code Headless Mode CI: Production Pipeline Guide

Running Claude Code as a scriptable pipeline participant is one of the most consequential configuration decisions an architect makes. Claude code headless mode CI integration turns an interactive coding assistant into a deterministic pipeline step: pass the -p flag, specify a prompt, and Claude Code executes, writes its response to stdout, and exits with a machine-readable exit code. That primitive is small; the production patterns built on top of it are not.

In this post, we cover the flag mechanics, CLAUDE.md authoring for unattended runs, GitHub Actions wiring, hook integration, structured output parsing, and the Domain 3 exam mechanics that surface repeatedly in CCAR-F scenario questions.

What is Claude Code headless mode and how does the -p flag work?

Headless mode runs Claude Code without an interactive terminal session. The -p flag (long form: --print) accepts a prompt string, processes it against the repository, and prints the response to stdout. The process exits with code 0 on success and a non-zero code on any error or tool failure.

claude -p "Review changed files for SQL injection vulnerabilities. Output JSON." \
  --output-format json \
  --allowedTools "Read,Bash(git diff HEAD~1)" \
  --max-turns 5

Three flags compose into the minimal safe CI invocation:

Without --max-turns, a poorly scoped prompt can trigger an extended agentic loop that exhausts budget and times out the pipeline step. Setting a ceiling is the simplest fail-fast mechanism available.

Why run Claude Code in CI rather than static analysis tools?

Static analysis tools check code against fixed rules. Claude Code applies contextual judgment: it can identify a subtle authentication bypass that no regex covers, or flag a test that mocks the wrong layer. The cost is API tokens and added latency per run.

When we scope invocations narrowly, the trade-off becomes manageable: only changed files, only one concern per invocation, and a low --max-turns ceiling. This keeps per-run cost proportionate and exit latency under 30 seconds for most pull-request contexts.

The Claude Code Configuration & Workflows domain of CCAR-F tests exactly this reasoning: given a scenario, which scoping decision produces a pipeline that is both useful and safe?

How should CLAUDE.md be written for CI agents?

CLAUDE.md is the primary lever for encoding agent behaviour at the repository level. In an interactive session, the agent can ask clarifying questions. In headless mode, it cannot. The CLAUDE.md must answer in advance every question the agent would otherwise raise.

A CI-targeted block covers four concerns: the exact JSON schema the downstream step expects, scope limits on which directories are in-bounds, the precise testing commands that prove a change is safe, and naming conventions the agent should recognise.

## CI Mode (headless)

When invoked non-interactively:
- Output valid JSON matching `.claude/ci-schema.json`. No prose before or after.
- Do not edit files unless the prompt explicitly requests it.
- Run tests with `npm test -- --passWithNoTests` and include exit code in output.
- Flag any path outside `src/` or `tests/` as out-of-scope and skip it.

Per the three-level configuration hierarchy, project-level CLAUDE.md takes precedence over user-level configuration. In CI, there is no user-level configuration on the runner. Anything that must apply in automated runs lives in the project file, committed to the repository.

This has a direct version control implication: the CI behaviour of the agent is reviewable, diffable, and auditable in the same pull request that changes the prompts or schema.

What does a production GitHub Actions workflow look like?

A minimal read-only review job, safe to run on every pull request:

name: Claude Code Security Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  security-review:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run headless review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "$(cat .claude/prompts/security-review.md)" \
            --output-format json \
            --allowedTools "Read,Bash(git diff HEAD~1)" \
            --max-turns 8 \
            > review.json
      - name: Gate on high-severity findings
        run: |
          COUNT=$(jq '[.findings[] | select(.severity == "high")] | length' review.json)
          [ "$COUNT" -gt 0 ] && echo "::error::$COUNT high-severity findings" && exit 1 || true
      - name: Upload review artefact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: security-review
          path: review.json

The --allowedTools list here grants Read and one scoped Bash subcommand, nothing else. The agent cannot write files, install packages, or call external services. Scoping tools to this level of specificity is the primary safety lever in unattended runs.

How do hooks enforce compliance in headless mode?

Hooks run in headless mode identically to interactive mode. A PostToolUse hook fires on every matching tool call whether a human is watching or not. This makes hooks the correct layer for requirements that must hold unconditionally: stripping credentials from tool results before they enter the context window, asserting that every file write touches only allowed paths, or emitting a structured audit log entry.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/redact_secrets.py"}]
      }
    ]
  }
}

The hooks vs prompts decision framework articulates the core distinction: a prompt asks the model to behave correctly; a hook enforces behaviour programmatically regardless of model output. In unattended CI runs, enforcement is the appropriate layer.

For the PostToolUse hooks for data normalisation pattern specifically, the hook receives the tool result before it re-enters the context window. This is the correct interception point for secret redaction: the Bash command has already run, but the output has not yet been appended to conversation history.

What structured output patterns make CI parsing reliable?

Telling Claude Code to output JSON is necessary but not sufficient. The agent may include prose before the JSON block or wrap the object in a markdown fence. Three complementary patterns make parsing deterministic:

Embedding a schema in the prompt body acts as a contract the model enforces on its own output, as covered in Prompt Engineering & Structured Output. A minimal example:

{
  "type": "object",
  "required": ["findings", "recommendation"],
  "properties": {
    "findings": {"type": "array"},
    "recommendation": {"type": "string", "enum": ["pass", "fail", "warn"]}
  }
}

How does multi-step pipeline design work for large codebases?

A single headless invocation that covers an entire large repository is usually the wrong design. Context grows with the codebase, token cost scales accordingly, and a single failure aborts the entire review.

The better pattern fans the work out per file, then synthesises in a second pass:

#!/usr/bin/env bash
set -euo pipefail
CHANGED=$(git diff --name-only HEAD~1 | grep '\.py$')
for file in $CHANGED; do
  claude -p "Review $file for style guide adherence. Output JSON." \
    --output-format json --allowedTools "Read" --max-turns 3 \
    >> per_file_results.jsonl
done
claude -p "Summarise these per-file results into one overall assessment. Output JSON." \
  --output-format json --allowedTools "Read(.claude/)" --max-turns 3 \
  < per_file_results.jsonl

Isolate each file's review so context does not bleed across files, then synthesise in a second pass with fresh context. Partial failures are recoverable because each file produces an independent result appended to the JSONL stream. The same logic underpins the per-file and cross-file pass pattern: narrow per-invocation scope so one bad file cannot invalidate the whole pipeline run.

What does the CCAR-F exam test about headless and CI configuration?

Domain 3, Claude Code Configuration and Workflows, carries 20% of the CCAR-F exam weight, equal to Domain 4. All five domain weights per the official exam guide:

Headless mode scenarios surface in Domain 3 items because they test the same reasoning pattern the exam rewards throughout: deterministic over probabilistic, proportionate scope, root-cause tracing. A candidate who understands why --allowedTools is preferable to --dangerouslySkipPermissions in a shared-runner environment, and why hooks are preferable to prompts for compliance enforcement, will answer these items correctly without needing to memorise CLI syntax.

Our CCAR-F concept library maps all 30 task statements to atomic concepts. Domain 3 concepts cover the three-level configuration hierarchy, hook implementation patterns, and version control implications of committing CLAUDE.md files to the repository. Practise with scenario-based questions to build the decision-making muscle, not just familiarity with flags.

What safety controls apply in unattended headless runs?

Four controls compose into a layered posture for CI:

1. --allowedTools allowlist - enumerate the minimum tools needed; anything not listed is refused automatically
2. --max-turns ceiling - prevents runaway loops; 5 to 10 turns is typical for review tasks
3. PostToolUse hooks - programmatic enforcement that holds regardless of model output
4. Scoped API key - a key dedicated to the CI pipeline, separate from developer keys, so usage anomalies appear clearly in the Anthropic console

Avoid --dangerouslySkipPermissions except in fully ephemeral environments where each run starts from a clean container image and the --allowedTools list is already tight. Even there, the allowlist approach is preferable: it documents intent in the invocation itself, survives image updates, and produces a cleaner audit trail.