Headless mode

Headless mode runs Claude Code without an interactive sessionWhat is session?A server-side record that tracks a logged-in user. The browser holds only a session ID in a cookie, and the server looks up the full data on each request. Ask AI for more. You pass a prompt, Claude processes it, and the result is printed to stdout:

claude -p "Explain the architecture of this project in 3 paragraphs"

This is the foundation for all automation. Because there's no interactive prompt, headless mode can run in scripts, cron jobs, CI pipelines, or anywhere you can execute a shell command.

Common headless patterns

Generate documentation:

claude -p "Generate API documentation for all routes in src/routes/"

Code review:

claude -p "Review the code in src/utils/parser.ts for bugs and edge cases"

Batch processing:

for file in src/components/*.tsx; do
  claude -p "Add JSDoc comments to all exported functions in $file"
done

Quick answers:

claude -p "What version of React does this project use?"

Piping input to Claude

Claude Code reads from stdin, so you can pipe any text into it:

# Explain an error log
cat error.log | claude -p "Explain this error and suggest a fix"

# Review a git diff
git diff main...HEAD | claude -p "Review these changes for bugs"

# Analyze a config file
cat nginx.conf | claude -p "Are there any security issues in this config?"

# Process command output
npm audit | claude -p "Summarize the critical vulnerabilities and suggest fixes"

This composability is one of Claude Code's strongest features. Anything that produces text output can be fed to Claude for analysis. You're combining the Unix philosophy of small, composable tools with AI-powered understanding.

Chaining commands

You can build multi-step pipelines:

# Find TODO comments and generate a prioritized task list
grep -r "TODO" src/ | claude -p "Organize these TODOs by priority and suggest
  which ones to tackle first"

# Get test failures and generate fixes
npm test 2>&1 | claude -p "Analyze these test failures and explain the root causes"

Structured output

For programmatic consumption, use --output-format to get structured responses:

claude -p "List all API endpoints in this project" --output-format json

The JSONWhat is json?A text format for exchanging data between systems. It uses key-value pairs and arrays, and every programming language can read and write it. Ask AI for more output format is essential when Claude Code is part of a larger automation pipelineWhat is pipeline?A sequence of automated steps (install, lint, test, build, deploy) that code passes through before reaching production. Ask AI for more. Instead of parsing free-text responses, you get structured data you can process with jq, Python, or any other tool.

# Extract specific fields from Claude's analysis
claude -p "Analyze the dependencies in package.json" \
  --output-format json | jq '.result'

The stream-json format streams JSON objects as they're generated, useful for real-time processing of long responses.

CI/CDWhat is ci/cd?Continuous Integration and Continuous Deployment - automated pipelines that test your code on every push and deploy it when tests pass. Ask AI for more integration

Claude Code can run in continuous integration pipelines. Here's a practical GitHub Actions example:

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

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

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

      - name: Review PR changes
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD)
          echo "$DIFF" | claude -p "Review this PR diff for bugs,
            security issues, and code quality problems. Be specific
            about file names and line numbers." \
            --output-format json > review.json

      - name: Post review comment
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          REVIEW=$(cat review.json | jq -r '.result')
          gh pr comment ${{ github.event.pull_request.number }} \
            --body "$REVIEW"

Key elements of a good CI integration:

• Fetch full git history (fetch-depth: 0) so Claude can see the diffWhat is diff?A comparison showing exactly which lines were added, removed, or changed between two versions of code. Ask AI for more against main
• Pipe the diff explicitly rather than relying on Claude to discover changes
• Use structured output for reliable parsing
• Post results back to the PR as a comment using gh
• Keep the APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. Ask AI for more key in secrets: never hardcode it

Other CI use cases

• Automated documentation updates: regenerate docs on every merge to main
• Changelog generation: summarize changes between releases
• MigrationWhat is migration?A versioned script that changes your database structure (add a column, create a table) so every developer and server stays in sync. Ask AI for more validation: review database migrations for safety issues
• DependencyWhat is dependency?A piece of code written by someone else that your project needs to work. Think of it as a building block you import instead of writing yourself. Ask AI for more analysis: flag risky dependency updates

MCPWhat is mcp?Model Context Protocol - a standard that lets AI tools connect to external services like databases, issue trackers, or APIs. Ask AI for more integration

MCP (Model Context ProtocolWhat is protocol?An agreed-upon set of rules for how two systems communicate, defining the format of messages and the expected sequence of exchanges. Ask AI for more) servers extend Claude Code with access to external tools and services. When an MCP server is configured, Claude can interact with APIs, databases, and services beyond your local filesystem.

Common MCP integrations include:

• GitHub: interact with issues, PRs, and repositories
• Linear: manage project tasks and sprints
• Sentry: analyze error monitoring data
• PostgreSQL: query databases directly

MCP turns Claude Code from a code-focused tool into a general-purpose development assistant that can reach into your entire development infrastructure. This is a deep topic covered in detail in a dedicated moduleWhat is module?A self-contained file of code with its own scope that explicitly exports values for other files to import, preventing name collisions. Ask AI for more.

Multi-turn automation

For complex automated tasks that require multiple steps, you can chain Claude Code calls in a script:

#!/bin/bash

# Step 1: Analyze the codebase
ANALYSIS=$(claude -p "Identify all deprecated API calls in src/" \
  --output-format json)

# Step 2: Generate a migration plan
echo "$ANALYSIS" | claude -p "Create a migration plan to replace
  these deprecated calls with their modern equivalents" \
  --output-format json > plan.json

# Step 3: Apply the migrations
claude -p "Execute the migration plan in plan.json - update each
  file listed with the recommended replacements" \
  --dangerously-skip-permissions

Each step builds on the output of the previous one. This pattern lets you automate complex, multi-step development tasks that would be tedious to do manually.

Tips for advanced usage

• Always test headless commands interactively first. Run the same prompt in a regular sessionWhat is session?A server-side record that tracks a logged-in user. The browser holds only a session ID in a cookie, and the server looks up the full data on each request. Ask AI for more to verify Claude understands the task before automating it.
• Use --output-format json in pipelines. Parsing natural language output is fragile; structured output is reliable.
• Set timeout limits in CI. Claude can take a while on large codebases. Add timeout guards to prevent hung pipelines.
• Version your automation scripts. CommitWhat is commit?A permanent snapshot of your staged changes saved in Git's history, identified by a unique hash and accompanied by a message describing what changed. Ask AI for more your Claude Code automation scripts alongside your code so the team can review and improve them.
• Combine with CLAUDE.md. Even in headless mode, Claude reads your CLAUDE.md. Use it to set conventions that apply to automated tasks too.