Headless Claude Code and CI/CD pipelines

The short answer

The -p (print) flag runs Claude Code non-interactively: it takes a prompt, does the work and prints the result, which is essential in scripts and CI where nobody can answer prompts. Combine it with --output-format json for machine-readable results, or use the official GitHub Action to let Claude respond to @claude in issues and PRs.

Interactive vs headless

Normally Claude Code is a conversation. In automation there's no human to type or approve, so you run it headless with -p:

claude -p "Summarise the changes in the last 5 commits"

Classic CI bug: a pipeline runs claude "Analyse this PR" and hangs forever. Why? Without -p, it's waiting for interactive input. Add -p.

Structured output for scripts

claude -p "List security issues in src/ as JSON" --output-format json

JSON output lets other programs parse results: post inline PR comments, fail a build, update a dashboard. You can also pipe data in:

cat error.log | claude -p "Explain the root cause of this error"

Control what headless Claude may do with flags like --allowedTools, and keep permissions tight: CI environments often have powerful credentials.

The Claude Code GitHub Action

Anthropic's official GitHub Action brings Claude into your repo workflow. Mention @claude in an issue or PR comment and it can analyse code, answer questions, implement changes and open pull requests. The quickest setup from inside Claude Code is:

/install-github-app

This walks you through installing the GitHub app and adding the required secret. You can also write workflows that run automatically, e.g. reviewing every new PR.

CI best practices

Use a fresh instance for review. The same session that wrote code is less likely to question its own decisions.
Re-reviews should report only new or unresolved issues: pass prior findings in so you don't spam duplicate comments.
Put testing standards in CLAUDE.md so CI-generated tests are meaningful, not boilerplate.
Match the API to the urgency: blocking checks run synchronously; overnight bulk jobs can use cheaper batch processing via the API.

Check yourself

Three quick questions to check it stuck.

Ask the tutor

Stuck on something in this lesson? Ask the AI tutor. It answers from this lesson and points you to others that help. Answers are written by AI and can be wrong. Do not include personal details, passwords or company secrets.

Frequently asked

How do I run Claude Code non-interactively?

Use the -p (print) flag, for example claude -p "your prompt". It runs the task, prints the result and exits, which suits scripts and CI pipelines.

Why does Claude Code hang in my CI pipeline?

It is probably running in interactive mode waiting for input. Add the -p flag so it runs headless and exits when done.

How do I set up Claude Code with GitHub Actions?

Run /install-github-app inside Claude Code to install the GitHub app and configure secrets, or add Anthropic's official Claude Code GitHub Action to a workflow manually.