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.

Last updated
By
Published
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.

On this page Why it mattersHow each tool does itQuestions

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

  1. The request

    The agent wants to edit a file

    The action needs approval.

  2. The prompt

    A prompt can reach you

    In Manual mode Claude Code asks, and you can answer questions and approve risky steps.

  3. The answer

    You approve or refuse

    A person is watching the run.

  4. 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

  1. The request

    The agent wants to edit a file

    The script did not allow it on the command line.

  2. The prompt

    Manual mode, nobody there

    claude -p starts in Manual mode on every plan.

  3. The decision

    Denied, and the run continues

    Anything that would prompt is denied, and the run carries on without it.

  4. 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.

Grant exact permissions on the command line, and read the JSON result, which lists permission_denials, instead of trusting the exit code alone. Source: Scripting guide, Claude Code 2.1.283, 2026-09-26.

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.

Does this page answer your questions?

One tap, no sign-in.

not at all fully

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.