Headless mode and the Agent SDK

Run Claude automatically in scripts and CI/CD pipelines

⏱ Est. ~6 min

01 · Read

Everything you've done with Claude Code so far has been interactive — you type, Claude responds, you approve. But what if you want Claude to run automatically? In a CI/CD pipeline that reviews every pull request? In a script that fixes lint errors every night?

Headless mode (claude -p) runs Claude without an interactive terminal. You give it a prompt, it does the work, and returns the result. No typing, no approval dialogs — just input and output.

This is how teams integrate Claude into automated workflows: code review bots, test fixers, doc generators, and more.

💡 Picture thisInteractive Claude is like having a conversation with a coworker at your desk. Headless Claude is like emailing them a task — you send a request, they do it, you get the result back. No back-and-forth needed.

Key points

claude -p runs Claude non-interactively (headless mode)
Great for scripts, CI/CD pipelines, and automation
No approval dialogs — pre-specify allowed tools
Output can be text, JSON, or streaming JSON

02 · Code example

Below are common headless mode patterns. The -p flag is what makes it non-interactive.

Basic headless usage

# Simple query
claude -p "Find all TODO comments in this project"

# With allowed tools (auto-approved, no prompts)
claude -p "Run tests and fix failures" \
  --allowedTools "Bash(npm test*),Read,Edit"

# Structured JSON output
claude -p "List all API endpoints" \
  --output-format json

The -p flag (short for 'print') makes Claude run non-interactively. --allowedTools pre-approves specific tools so Claude can work without permission prompts. --output-format json returns structured data instead of plain text — useful when another program needs to parse the result.

03 · Code example

Below is how teams use headless mode in a CI/CD pipeline — an automated code reviewer that runs on every pull request.

GitHub Actions — automated code review

# .github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Review PR
        run: |
          claude -p "Review the changes in this PR. \
            Focus on bugs, security, and performance." \
            --allowedTools "Read,Grep,Glob" \
            --output-format text

This GitHub Action runs Claude in headless mode on every pull request. It only allows read-only tools (Read, Grep, Glob), so Claude can analyze the code but can't change anything. The review output shows up in the CI log for the team to read.

04 · Read

For more complex automation, Anthropic provides the Agent SDK — Python and TypeScript libraries with Claude's tool support for building production agents.

The Agent SDK gives you programmatic control over everything: which tools are available, how results are handled, session management (resuming conversations), even MCP server connections. It's what powers the most sophisticated Claude Code integrations.

The CLI (claude -p) is great for simple automation. The Agent SDK is what you want when you need full programmatic control — custom error handling, streaming results, chaining multiple Claude calls, or building products on top of Claude's capabilities.

Key points

Agent SDK: Python and TypeScript libraries for production agents
Full programmatic control over tools, sessions, results
CLI (claude -p): simple automation and scripts
Agent SDK: complex applications and production systems
Session management: programmatically capture and resume conversations

05 · Code example

Below is a simple Agent SDK example in TypeScript that finds and fixes a bug programmatically.

Agent SDK — bug fixer

import { query } from '@anthropic-ai/claude-agent-sdk';

for await (const msg of query({
  prompt: "Find and fix the failing test in auth.test.ts",
  options: {
    allowedTools: ["Read", "Edit", "Bash"],
  }
})) {
  if (msg.result) {
    console.log('Fix applied:', msg.result);
  }
}

The Agent SDK gives you a streaming interface — you iterate over messages as Claude works. The allowedTools array controls what Claude can do. When Claude finishes, the result message contains a summary of what was done. This is how you build automated agents that can read, edit, and run commands.

06 · Quiz

Which flag makes Claude Code run non-interactively, with no interactive terminal?

claude --headless
claude --auto
claude -p
claude --batch

07 · Fill in the blank

To run Claude in a CI/CD pipeline without user interaction, use claude _____ "your prompt".

08 · Match

Match each automation method to its best use.

(This section is interactive — please enable JavaScript.)

Other lessons in this chapter

⚠ The full interactive experience needs JavaScript. Please enable it and reload.

※ This is an independent Traditional Chinese teaching project — not an official Anthropic product. Claude™ is a trademark of Anthropic, PBC.