When would you use Headless mode?

CI/CD pipeline code review: A GitHub Actions workflow runs on every pull request. It pipes the PR diff into Claude with a security-focused prompt and posts the JSON result as a PR comment, giving reviewers an automated first-pass analysis before any human looks at the code.

When would you use Headless mode?

Automated build-error diagnosis: A build script captures the stderr output of a failing compile or test run, then pipes it to Claude with a prompt asking for root cause, affected files, and the exact fix. The result is saved to a report file that engineers check after the pipeline fails.

When would you use Headless mode?

GitHub issue auto-labeling: A webhook fires whenever a new issue is opened in a repository. A small server pipes the issue body to Claude in headless mode and asks it to recommend labels. The server then calls the GitHub API to apply those labels automatically—no human triage needed for common issue types.

← ContentsClaude Code · advanced

Headless mode

Headless mode is a way to run Claude Code without any interactive terminal UI, so it can be driven entirely by scripts, automation tools, and CI/CD pipelines. You trigger it by passing the `-p` (or `--print`) flag with a prompt string on the command line. Claude executes the task, then writes its response to standard output—either as plain text or as structured JSON—and exits with a status code your script can check. Because there is no interactive session, you must explicitly grant any tool permissions upfront using flags like `--allowedTools` or `--permission-mode`. Without these, Claude will stop and wait for confirmation it will never receive, causing the process to hang. Headless mode is intentionally stateless between separate invocations; if you need multi-turn continuity, you must pass a `--resume <session_id>` flag referencing a prior session. Headless mode is also the foundation of the Claude Agent SDK, which wraps the same execution engine in Python and TypeScript objects so you can embed autonomous coding agents directly in applications, orchestrate multiple agents in parallel, and parse structured output without shelling out manually.

When you’d use it

◆CI/CD pipeline code review — A GitHub Actions workflow runs on every pull request. It pipes the PR diff into Claude with a security-focused prompt and posts the JSON result as a PR comment, giving reviewers an automated first-pass analysis before any human looks at the code.
◆Automated build-error diagnosis — A build script captures the stderr output of a failing compile or test run, then pipes it to Claude with a prompt asking for root cause, affected files, and the exact fix. The result is saved to a report file that engineers check after the pipeline fails.
◆GitHub issue auto-labeling — A webhook fires whenever a new issue is opened in a repository. A small server pipes the issue body to Claude in headless mode and asks it to recommend labels. The server then calls the GitHub API to apply those labels automatically—no human triage needed for common issue types.
◆Scheduled codebase health checks — A nightly cron job runs Claude in headless mode against the main branch, asking it to flag stale TODOs, outdated dependency comments, and misleading variable names. Results are written to a Markdown file and committed back to a maintenance branch.
◆Parallel multi-agent PR review — Three Claude instances are launched concurrently via the Agent SDK—one focused on logic correctness, one on security vulnerabilities, and one on performance. Their JSON outputs are aggregated into a single structured report, covering concerns that would take a single reviewer much longer to catch.

What changed recently

◆2026-06-15 — Agent SDK credit system launches for subscription plans. Claude -p and Agent SDK usage on Pro, Max, Team, and Enterprise plans now draws from a new monthly per-user Agent SDK credit pool, separate from interactive usage limits. API/Console users continue on pay-as-you-go billing and are unaffected.
◆2026-03-25 — Auto mode released with documented permission-dropping behavior on entry. When --permission-mode auto is activated, rules granting blanket shell access, wildcarded script interpreters, and package-manager run commands are automatically removed to reduce autonomous execution risk. Documented in the Claude Code auto mode engineering post.
◆2025-01 — Claude Code v2.1.128 introduced a 10 MB cap on piped stdin in headless mode, with a clear error message and non-zero exit code on overflow. The same release improved MCP server startup in headless/SDK mode: the pre-wait now overlaps with server startup rather than blocking before the first turn, reducing latency by up to 2 seconds with slow MCP servers.
◆2025-01 — stream-json output now includes plugin load failures in the init.plugin_errors field, covering --plugin-dir failures and dependency demotions, enabling scripts to fail fast on missing plugins.

This is the short version

The full chapter has three worked examples, the common pitfalls, and the workflow that makes it pay — plus the other 84 features, kept current.

Get Claude Master — $97 →