What is headless mode?
Headless mode is running a coding agent without an interactive session, usually from a script, a git hook, a cron job or a CI step. Claude Code uses claude -p, Codex uses codex exec and Cursor’s CLI has print mode (-p). Nobody is there to answer a prompt, so permissions, output format and the check on the result have to be set on the command line.
- In Polish
- Tryb headless
- First set up at
- Level 4, free guide
- Also searched as
- non-interactive mode, print mode, agent in CI
$59.99 once for 12 months of access. Nothing renews on its own. 30-day refund on a first purchase.
Why it matters.
A headless run has nobody to approve anything: claude -p starts in Manual mode (auto mode on third-party providers or with telemetry off, from v2.1.285), so pass --permission-mode dontAsk to deny whatever would prompt on every provider, and codex exec refuses a command that needs approval. So the allowlist is the policy, and the script, not the agent, has to check the result. A nightly job can “succeed” for a week while writing nothing, because every edit was denied and the script only checked that the process exited.
The same edit, with and without a person
An edit the agent has not been allowed to make: in an interactive session, and in claude -p from a script.
- A person decides
- What runs
- What you can rely on
Interactive session You answer
-
The request
The agent wants to edit a file
The action needs approval.
-
The prompt
A prompt can reach you
In Manual mode Claude Code asks, and you can answer questions and approve risky steps.
-
The answer
You approve or refuse
A person is watching the run.
-
What you can rely on
Your decision
The edit lands only if you said yes. In auto mode a classifier makes that call instead.
`claude -p` from a script Nobody to answer
-
The request
The agent wants to edit a file
The script did not allow it on the command line.
-
The prompt
Manual mode, nobody there
claude -pstarts in Manual mode on every plan. -
The decision
Denied, and the run continues
Anything that would prompt is denied, and the run carries on without it.
-
What you can rely on
Only what the script checks
A cron job “succeeded” for a week while writing nothing: it checked that the process exited, not the result.
How each tool does it.
Cursor, Claude Code and Codex each name this their own way. Each note carries the date it was checked.
Cursor
Print mode (-p, --print) in the Cursor CLI, whose command is agent (Cursor CLI docs, checked 2026-10-12), documented for GitHub Actions. Its machine-readable output options were not re-verified.
Feature matrix (Cursor docs), 2026-08-28
Claude Code
claude -p runs one task and exits, in Manual mode with nobody to approve; --output-format json returns one result object and --json-schema a validated one.
-p skips the workspace trust dialog, but the project’s hooks, its env block and every server in .mcp.json still load and run, so pass permissions on the command line. The exit code is 0 on success and non-zero when the run fails, including when --max-turns is reached.
Scripting guide, Claude Code 2.1.283, 2026-09-26
Codex
codex exec (alias e) prints the final message to stdout and never asks for approval; --json gives JSONL events and --output-schema FILE a schema-checked answer.
A command that needs approval outside the sandbox is refused. With no sandbox flag Codex can read the repository and run read-only commands but cannot edit; --sandbox workspace-write allows edits with network access off. Outside a Git repository it exits 1 unless you pass --skip-git-repo-check.
codex exec guide, Codex 0.157.1, 2026-10-03
Questions about headless mode.
How do you run Claude Code headless?
With claude -p "task". Add --output-format json so the script can branch on the result, and --json-schema when the answer must match a shape. A claude -p session starts in Manual mode, so list exactly what the job may do, for example --permission-mode dontAsk --allowedTools "Bash(npm test *)".
How do you get machine-readable output?
Claude Code takes --output-format json or stream-json, and --json-schema. Codex takes --json for JSONL events, --output-schema FILE for a schema-shaped final answer and -o FILE for the final message only. Cursor’s output options were not re-verified.
Is it safe to run headless over any repository?
No. claude -p skips the workspace trust dialog, yet the repository’s hooks and .mcp.json servers still load and run. Never run it over code you did not write while a secret is in the environment, for example a pull request from a fork. Start such runs with --bare --setting-sources "" --strict-mcp-config.
Keep reading.
The guides that go deeper, and the terms and comparisons next to this one.
In the docs
Does this page answer your questions?
One tap, no sign-in.
What are you here for?
What is holding you back?
How does it read?
Thanks. If you left an email, Michał will reply.
Answering your questions?
One tap each. Close whenever you like.
no sign-in
Read the guides in the same words.
Open every guide with the Toolkit. Each term is defined once here, and the guides use it the same way.
$59.99 once for 12 months of access. Nothing renews on its own. 30-day refund on a first purchase.
Michał replies, not a bot. The address is used for this reply only.