Pro11 min

Headless Agents in CI and Pipelines

Interactive sessions are for building. To put agents to work at scale you run them headless: no UI, driven by a single command, output captured as text or JSON. This is how you wire agents into CI, cron jobs, and scripts so they triage issues, fix flaky tests, or draft release notes while you sleep.

Step 1: Run a one-shot non-interactive task

Claude Code's print mode runs a prompt and exits. Pipe the prompt in, ask for JSON when a script needs to parse the result, and constrain the tools it may use.

ci - runner
# one prompt, no chat, structured output
$claude -p "summarize today's failing tests as JSON" --output-format json
{"failing": 3, "files": ["auth.test.ts", "cart.test.ts"]}
$

Step 2: Trigger it from a pipeline

Drop the headless call into a GitHub Actions workflow. A new issue labeled 'agent' can kick off a run that investigates and opens a draft PR, with the model and permissions pinned for repeatability.

.github/workflows/triage.yml
on:
  issues:
    types: [labeled]
jobs:
  triage:
    if: github.event.label.name == 'agent'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: |
          claude -p "Investigate issue #${{ github.event.issue.number }}, \
            propose a fix, open a draft PR." \
            --allowedTools "Read,Grep,Edit,Bash(git*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Step 3: Keep humans at the merge gate

Headless agents should produce drafts, not merges. Let them open PRs and post findings, but keep a person on the approve-and-merge step. Automation expands what gets done; review keeps it safe.

Pin everything for repeatability
In automation, pin the model, the allowed tools, and the permission mode. A headless run should be boring and deterministic, not a creative free-for-all with production access.
Claude Code headless and SDKFirst-party reference for print mode, output formats, allowed tools, and the agent SDK for embedding agents in your own tools.docs.claude.com

Hands-on tasks