Definition
Headless mode
Headless mode is running an AI agent non-interactively, typically in a CI/CD pipeline or an automation script. Claude Code supports it with claude -p "task"; Codex supports it through codex exec and its Cloud API. There is no human in the loop: the agent executes and exits.
Why it matters
Headless is where an agent stops being a tool you drive and becomes part of a pipeline. It is also where approval prompts stop protecting you, so the guardrails have to be structural — sandbox policy and hooks rather than a human saying yes.
How each tool handles it
- Cursor
- CLI, SDK and Cloud Agents, with structured output.
- Claude Code
-
claude -p "prompt", plus web and managed agents;--output-format jsonfor structured output. - Codex
-
codex exec "prompt", withcodex exec --jsonfor structured output.
Frequently asked questions
How do you run Claude Code headless?
With claude -p "task". Adding --output-format json gives structured output a pipeline can parse, which is what makes it usable as a CI step rather than something a person reads.
Is headless mode safe to run unattended?
Only with structural guardrails, because there is nobody to approve anything. Sandbox policy decides what a command can reach and hooks enforce checks the agent cannot skip; both matter more here than in an interactive session.
How do you get machine-readable output?
Claude Code takes --output-format json and Codex takes codex exec --json. Without one of those a pipeline is parsing prose, which is the difference between a CI step that can branch on the result and one that can only log it.