
Headless mode: running a coding agent from scripts and CI
In short: Headless mode runs a coding agent non-interactively from a script or CI job, with a prompt in, results out and permissions fixed in advance.
Headless mode runs a coding agent without an interactive session: you pass a prompt on the command line, the agent works with pre-approved tools, prints the result, optionally as JSON, and exits. In Claude Code this is the -p (print) flag, which the documentation, read in November 2026, calls non-interactive mode. It is how agents run inside shell scripts, cron jobs and CI pipelines.
Headless mode in plain words
It is the difference between chatting with a colleague and leaving them a written job ticket overnight, with clear limits on what they may touch.
How it works
Because nobody is there to approve actions, permissions are set in advance with --allowedTools or a permission mode such as dontAsk, which denies anything that would otherwise prompt.
Output comes as plain text, JSON with the result and session metadata, or streaming JSON, so other programs can consume it. Claude Code exits with code 0 on success and a non-zero code on failure, which lets a pipeline branch on the result.
For scripted calls the documentation recommends --bare, which skips auto-discovery of hooks, skills, plugins, MCP servers and CLAUDE.md.
Example
claude -p "Read the failing test output in ci.log, explain the root cause in five lines" \
--allowedTools "Read" \
--output-format json > diagnosis.json
A read-only diagnosis step in CI: it can look, it cannot change anything.
Where you'll meet it
- CI jobs that triage failures or review pull requests
- Scheduled maintenance: dependency updates, docs refresh, changelog drafts
- Claude Code GitHub Actions, which run Claude Code inside repository workflows
- Batch jobs that apply the same change across many repositories
What it changes for you
Headless agents turn one-off assistance into automation that runs without you. For developers, an agent becomes one more command in a script. My view: for platform teams, unattended runs need the strictest permissions, budgets and logs in the stack.
Headless mode vs interactive mode
Interactive mode keeps a person in the loop at every risky step. Headless mode moves all approval decisions into configuration before the run.
Common mistake
My view: giving a CI agent the same broad permissions you use on your laptop. A headless run reading untrusted input, such as issue text from strangers, with write access and secrets is a prompt-injection incident waiting for a date. The GitHub Actions integration, by default, only runs for users with write access to the repository.
Related terms
Claude Code · Permission modes · Prompt injection · Agent sandbox · Slash commands
Give an unattended agent only the tools and secrets that one job needs.


