Headless Mode and CI/CD - FAQ

Claude Code's headless mode lets you run AI tasks directly in your CI/CD pipelines without human interaction. With the -p flag, you launch prompts in a single command, retrieve the output as text, JSON, or streaming, and automate complete workflows in GitHub Actions or GitLab CI. This FAQ guide answers practical questions for integrating Claude Code into your automation chains.

Claude Code's headless mode is a non-interactive execution mode that allows you to use the AI agent from the command line without a graphical terminal. This mode is the foundational building block for integrating Claude Code into any continuous integration and deployment pipeline.

more than 60% of teams using Claude Code in enterprise leverage headless mode for at least one CI/CD workflow. The -p flag transforms Claude Code into a scriptable tool, capable of processing a prompt and returning a result usable by other tools.

How to launch Claude Code in a single command with the -p flag?

Use the -p flag followed by your prompt in quotes to run Claude Code without an interactive interface.

The -p flag (for print) sends a single prompt to Claude Code and displays the response directly on standard output. This mode disables all user interaction, making it compatible with shell scripts, CI/CD pipelines, and cron jobs.

$ claude -p "Explain the main() function in src/index.ts"

The command returns the result in plain text by default. The process terminates automatically after the response, with an exit code of 0 on success. The average response time is 3 to 15 seconds depending on prompt complexity.

To go further on available options, check out the complete headless mode command reference which details each flag.

Key takeaway: the -p flag turns Claude Code into a standard Unix command, compatible with pipes and shell redirections.

How to integrate Claude Code into GitHub Actions?

Add a step in your YAML workflow that installs Claude Code and runs a prompt with the -p flag.

The integration relies on three elements: installing Claude Code via npm, configuring the API key as a GitHub secret, and calling it in headless mode. Here is a working workflow:

name: Claude Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g @anthropic-ai/claude-code
      - name: Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Review the changes in this PR and list potential bugs" \
            --output-format json > review.json

This workflow runs on each pull request in approximately 30 seconds for an average-sized PR (less than 500 modified lines). You can check the tips for optimizing your headless pipelines to reduce execution times.

For managing permissions and security of your API tokens in a CI context, always store the key in the repository secrets and never in the source code.

Key takeaway: a complete GitHub Actions integration requires Node.js 22+, the npm package, and an API key as a secret - three lines of configuration are enough.

What output formats are available in headless mode?

Claude Code offers three output formats in headless mode: text, json, and stream-json.

The default format is text, which returns the raw response on stdout. The json format wraps the response in a structured object with metadata. The stream-json format sends tokens one by one in JSON Lines (NDJSON) format, ideal for real-time processing.

# Text format (default)
$ claude -p "Summarize this file" --output-format text

# Structured JSON format
$ claude -p "List the TODOs" --output-format json

# Streaming JSON Lines format
$ claude -p "Generate the docs" --output-format stream-json

The json format returns an object containing the fields result, model, usage, and cost_usd. In practice, 85% of CI/CD integrations use the json format to parse the result with jq or a Python script.

# Extract only the result with jq
$ claude -p "Analyze this code" --output-format json | jq -r '.result'

To understand how to leverage these formats in programmatic multi-turn sessions, check out the dedicated headless mode guide.

Key takeaway: choose text for quick debugging, json for programmatic integration, and stream-json for real-time feedback.

How to create programmatic multi-turn sessions?

Use the --session-id flag combined with -p to maintain context between multiple successive calls.

A multi-turn session allows you to chain multiple prompts while preserving conversation history. Claude Code stores the context server-side and automatically reloads it with each call using the same session identifier.

# First call: analyze the code
$ claude -p "Analyze the files in src/" --session-id my-review-001

# Second call: previous context is preserved
$ claude -p "What bugs did you find in the previous analysis?" \
    --session-id my-review-001

# Third call: request a fix
$ claude -p "Fix the most critical bug" --session-id my-review-001

Each session persists for 24 hours by default. The maximum context size is 200,000 tokens (approximately 150,000 words). In practice, a 5-turn session consumes on average 15,000 to 40,000 tokens.

Concretely, multi-turn sessions are useful for multi-step workflows: analysis > correction > verification. You will find additional examples in the headless mode cheatsheet with ready-to-copy scripts.

The session mechanism also works in GitHub Actions by passing the --session-id between workflow steps. Generate a unique identifier per execution with ${{ github.run_id }}.

Key takeaway: the --session-id flag transforms isolated calls into a continuous conversation, ideal for multi-step pipelines.

How to parse Claude Code's JSON output in a script?

Combine the --output-format json flag with a parsing tool like jq to extract structured data.

Claude Code's JSON output follows a stable schema with the main fields result (the text response), model (the model used), usage (tokens consumed), and cost_usd (call cost). This schema has been documented since Claude Code version 1.0.

# Extract the text result
$ claude -p "Summarize this PR" --output-format json | jq -r '.result'

# Extract the call cost
$ claude -p "Analyze this code" --output-format json | jq '.cost_usd'

# Check the number of tokens used
$ claude -p "Document this function" --output-format json \
    | jq '.usage.total_tokens'

In Python, parsing is straightforward:

import subprocess
import json

result = subprocess.run(
    ["claude", "-p", "List the modified files", "--output-format", "json"],
    capture_output=True, text=True
)
data = json.loads(result.stdout)
print(f"Response: {data['result']}")
print(f"Cost: {data['cost_usd']}$")

For developers discovering the Claude Code command line, the installation and first launch FAQ covers the technical prerequisites. The JSON structure is identical whether you run Claude Code locally or in a Docker container.

Key takeaway: the JSON output follows a stable schema - use jq in bash or json.loads() in Python to extract result, usage, and cost_usd.

What are the advanced CI/CD use cases with Claude Code?

Advanced use cases include automated code review, test generation, automated documentation, and security vulnerability detection.

teams that automate code review with Claude Code reduce review time by 40% on average. Here are the five most common use cases in 2026:

Concretely, a unit test generation pipeline looks like this:

$ claude -p "Generate unit tests for functions without coverage \
    in src/utils/" --output-format json \
    --max-turns 5 | jq -r '.result' > tests/generated.test.ts

To understand how Claude Code reasons about your source code, check out the article on agentic coding and its principles. Advanced workflows often combine headless mode with the CLAUDE.md memory system to provide project context with each execution.

Key takeaway: automated code review and test generation are the two most profitable CI/CD use cases, with measurable ROI from the first week.

How to handle errors and return codes in headless mode?

Check the process exit code: 0 indicates success, any other code signals an error.

Claude Code in headless mode follows standard Unix conventions for return codes. Code 0 means the prompt was processed successfully. Code 1 signals a generic error (invalid prompt, network error). Code 2 indicates an authentication error (missing or invalid API key).

$ claude -p "Analyze this file" --output-format json
if [ $? -eq 0 ]; then
    echo "Success"
else
    echo "Error code: $?"
    exit 1
fi

In a GitHub Actions pipeline, use continue-on-error: true if you want the workflow to continue despite a Claude Code error. In practice, the error rate in production is under 2% for well-formulated prompts.

For the json format, the error field is present in the response in case of failure. Systematically test for this field before processing the result. The essential slash commands include useful debug options for diagnosing recurring errors.

Key takeaway: always handle the return code in your scripts - an unchecked $? can mask silent errors in your pipeline.

How to limit API costs in a CI/CD pipeline?

Configure the --max-turns flag and monitor the cost_usd field of the JSON output to control your budget.

Each headless mode call consumes billed tokens. A code review prompt on 200 lines costs on average between $0.02 and $0.08 with Claude Sonnet 4.6. The --max-turns flag limits the number of agent iterations, which caps consumption.

# Limit to 3 turns maximum
$ claude -p "Refactor src/utils.ts" --max-turns 3 --output-format json

# Extract the cost for monitoring
$ claude -p "Review this PR" --output-format json | jq '.cost_usd'

Here is how to budget your pipelines:

• A code review per PR costs between $0.02 and $0.08 (Sonnet 4.6)
• Test generation costs between $0.05 and $0.15 per file
• A complete security analysis costs between $0.10 and $0.30
• Cumulatively, a project with 50 PRs/week represents about $5 to $15/week

SFEIR Institute recommends centralizing cost monitoring in a dashboard. Aggregate the cost_usd values from each execution into a CSV file or database to track the trend.

To deepen configuration and best practices, discover the Claude Code training from SFEIR. In one day, you will practice CI/CD integration with concrete labs and learn to optimize your prompts to reduce token consumption by 30 to 50%.

Key takeaway: use --max-turns to cap costs and monitor cost_usd in each JSON response for precise budget tracking.

How to use Claude Code in headless mode with Docker?

Run Claude Code in a Docker container by passing the API key as an environment variable.

Running in Docker guarantees a reproducible environment for your CI/CD pipelines. The Node.js 22 Alpine image weighs approximately 180 MB, and installing Claude Code adds approximately 45 MB.

FROM node:22-alpine
RUN npm install -g @anthropic-ai/claude-code
WORKDIR /app
COPY . .
ENTRYPOINT ["claude", "-p"]

$ docker build -t claude-ci .
$ docker run -e ANTHROPIC_API_KEY="sk-..." claude-ci "Analyze the code in /app/src"

This approach isolates Claude Code from the host system. Each execution starts in a clean environment, eliminating cache or residual dependency issues. The image build time is approximately 25 seconds.

For teams getting started with containerizing their AI tools, the AI-Augmented Developer training from SFEIR covers AI tool integration in DevOps workflows over two days, with hands-on exercises on Docker and CI pipelines.

Check out the complete headless mode guide for advanced Docker configuration options, including volume mounting and cache management.

Key takeaway: Docker + Claude Code in headless mode = reproducible environment; pass the API key via -e and mount your source code as a volume.

Can you combine headless mode with the CLAUDE.md file?

Yes, Claude Code automatically loads the CLAUDE.md file from the current directory, even in headless mode.

The CLAUDE.md file is a project memory mechanism that provides persistent context to Claude Code. In headless mode, this file is read with each call if it is present in the working directory. This allows you to standardize project instructions for all CI/CD calls.

# CLAUDE.md (at the project root)
- Code convention: strict TypeScript, ESLint Airbnb
- Tests: Vitest, minimum 80% coverage
- Never modify files in /config/production/

# Claude Code will automatically read CLAUDE.md
$ cd /my-project && claude -p "Generate tests for src/auth.ts"

In practice, teams that use CLAUDE.md in CI/CD get results that are 35% more consistent with their code standards. You will find configuration details in the CLAUDE.md memory system FAQ.

The CLAUDE.md file also supports security instructions. Add directives like "Never expose secrets" or "Do not modify production files" to secure your automated pipelines.

Key takeaway: place a CLAUDE.md file at the root of your repo so that each headless execution automatically respects your project conventions.

How to automate code review on every pull request?

Create a GitHub Actions workflow triggered on the pull_request event that runs Claude Code on the diff.

The automated review analyzes the PR diff and produces a structured comment. The average execution time is 30 to 60 seconds for a PR of less than 500 lines.

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g @anthropic-ai/claude-code
      - name: Review PR
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD)
          echo "$DIFF" | claude -p "Analyze this diff and list: \
            1. Potential bugs \
            2. Security issues \
            3. Improvement suggestions" \
            --output-format json | jq -r '.result' > review.md
      - name: Post Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## AI Review\n${review}`
            });

This workflow uses fetch-depth: 0 to access the full diff history. Adapt the prompt to your conventions by referencing the rules in your CLAUDE.md.

Explore conversations with Claude Code to learn how to formulate effective review prompts that maximize feedback relevance.

Key takeaway: automate code review with a 30-line YAML workflow - the diff is passed via pipe and the result is posted as a PR comment.

What are the technical prerequisites for headless mode?

Headless mode requires Node.js 18 or higher, the @anthropic-ai/claude-code npm package, and a valid Anthropic API key.

Here is the complete list of prerequisites as of February 2026:

• Node.js: version 18+ (recommended: Node.js 22 LTS)
• npm: version 9+ (included with Node.js 18+)
• Claude Code: latest stable version (v2.x in February 2026)
• API key: ANTHROPIC_API_KEY environment variable
• Operating system: Linux, macOS, or Windows (WSL2)
• Minimum RAM: 512 MB available
• Network: outbound HTTPS access to api.anthropic.com

# Check prerequisites
$ node --version    # v22.x.x expected
$ npm --version     # 10.x.x expected
$ claude --version  # v2.x.x expected

The installation and first launch FAQ details the complete procedure, including special cases like installation behind an enterprise proxy. Full installation takes less than 2 minutes on a standard connection.

For developers who want to go further, the AI-Augmented Developer - Advanced training from SFEIR (1 day) dives deep into CI/CD architectures with integrated AI, prompt tuning for pipelines, and advanced monitoring strategies.

Key takeaway: Node.js 22 + npm + Anthropic API key - check these three elements before any CI/CD integration.

How to secure the API key in a CI/CD environment?

Store the API key exclusively in your CI platform's secret manager (GitHub Secrets, GitLab CI Variables, AWS Secrets Manager).

The Anthropic API key (ANTHROPIC_API_KEY) grants access to your account and your quota. In headless mode, it must be injected as an environment variable without ever appearing in the source code, logs, or build artifacts.

# GitHub Actions - key stored in repo secrets
env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

# GitLab CI - key defined in Settings > CI/CD > Variables
variables:
  ANTHROPIC_API_KEY: $CI_ANTHROPIC_KEY

15% of secret leaks in CI/CD come from unfiltered logs. Enable automatic secret masking in your platform and add --quiet to Claude Code commands to limit log verbosity.

For a complete view of security best practices with Claude Code, check out the permissions and security FAQ. The security rules defined in your CLAUDE.md also apply in headless mode.

Key takeaway: never store an API key in plain text in the code - use your CI platform's native secrets and enable masking in the logs.

Are there rate limiting constraints in headless mode?

The Anthropic API applies rate limits that vary by plan: 50 requests/minute for the free plan, up to 4,000 requests/minute for Enterprise plans.

In headless mode within a CI/CD pipeline, you can hit these limits if multiple jobs run in parallel. rate limiting is applied at the API key level, not at the machine or container level.

Implement a retry mechanism with exponential backoff to handle 429 (Too Many Requests) errors:

MAX_RETRIES=3
for i in $(seq 1 $MAX_RETRIES); do
    claude -p "Review this code" --output-format json && break
    echo "Rate limited, retry $i/$MAX_RETRIES..."
    sleep $((2 ** i))
done

In practice, a project with 50 PRs per week and 3 CI jobs per PR consumes approximately 150 requests per week, well within the Pro plan limits. Find more optimization tips in the headless mode tips.

Key takeaway: monitor your quotas via the Anthropic dashboard and implement retry with exponential backoff to absorb CI/CD load spikes.