What is headless mode? Claude Code, Codex, Cursor and Grok

Oct 30, 2026

Headless mode runs a coding agent from a script, with no chat UI. How claude -p, codex exec, the Cursor CLI and grok -p differ on permissions.

~~~

Headless mode runs a coding agent from a script or another program. You pass the prompt as an argument. There is no fullscreen chat and nobody to click Allow. The process prints a result and exits.

How headless mode works

A script starts the agent with a prompt and the permissions you already chose. The agent reads files and, if you allowed it, edits them and runs commands. Progress may go to the error stream. The final answer goes to standard output, so the next command in the pipeline can use it. The exit code tells the script whether the run failed.

The process runs on the machine where you started it, which might be your laptop or a CI runner. A cloud agent runs on the vendor’s machine instead. Slash commands belong to an interactive session. In a script you use flags instead.

Headless mode in each tool

	Claude Code	Codex	Cursor	Grok Build
Command	`claude -p` or `--print`	`codex exec`	`agent -p` or `--print`	`grok -p` or `--single`
Allow edits	`--allowedTools`, and other permission flags	`--sandbox workspace-write`	`--force` or `--yolo`	`--always-approve` for tool approvals
Default posture	Loads project hooks, skills, `CLAUDE.md` and MCP unless you pass `--bare`	Read-only sandbox	`--print` proposes changes and does not apply them	The same permissions and sandbox as the rest of Grok
Machine-readable output	`text`, `json`, `stream-json`	`--json` for JSON Lines on stdout	`text`, `json`, `stream-json`	`plain`, `json`, `streaming-json`
Needs a git repo	Not documented as a requirement	Yes, unless `--skip-git-repo-check`	Not documented as a requirement	Not documented as a requirement

Claude Code

claude -p "What does the auth module do?" runs one prompt and prints the response. Exit code 0 means success. A non-zero code means the run failed. An invalid flag is reported on stderr before the run starts. Some failures inside the run, such as missing authentication, are printed as the result on stdout.

By default, -p discovers hooks, skills, custom commands, subagents, plugins, MCP servers, auto memory and CLAUDE.md, including in a folder you have never trusted. There is no workspace trust dialog and no per-server approval prompt.

--bare skips that discovery so a script starts the same way on every machine. Bare mode does not read your subscription login. Set ANTHROPIC_API_KEY, or pass settings that supply a key. The docs recommend --bare for scripted calls, and say it will become the default for -p later.

--output-format is text (the default), json or stream-json. Add --json-schema with json when the caller needs a fixed shape. Piped stdin is capped at 10MB. For anything larger, write a file and name the path in the prompt.

--resume and --continue pick up an earlier session. claude -p can stay open after the turn if background work is still running.

See Run Claude Code programmatically.

OpenAI Codex

codex exec is non-interactive mode. The prompt is an argument. Progress streams to stderr. Only the final agent message goes to stdout, so you can pipe it.

The default sandbox is read-only. --sandbox workspace-write allows edits. --sandbox danger-full-access is the broader setting, and the docs say to use it only in a controlled environment such as an isolated CI runner. --full-auto is no longer supported. The replacement in the docs is --sandbox workspace-write, or --approve-for-me to route approvals through automatic review with the workspace-write sandbox.

--json turns stdout into JSON Lines, with events such as thread.started, turn.completed and item.*. -o writes the final message to a file and still prints it. --output-schema asks for a final response that matches a JSON Schema.

Codex refuses to run outside a git repository. --skip-git-repo-check overrides that. codex exec resume --last "fix the race you found" continues a previous run.

The docs say not to put OPENAI_API_KEY or CODEX_API_KEY in a job-level environment when the job checks out or runs repository-controlled code. Set the key only around the Codex invocation. For GitHub Actions, the docs prefer the Codex GitHub Action over installing the CLI yourself.

See Non-interactive mode.

Cursor

The Cursor CLI calls this print mode. agent -p "What does this codebase do?" prints a final answer. The default output format is text.

Without --force, the docs say changes are only proposed, not applied. --force (alias --yolo) lets the agent modify files without confirmation. --output-format json and stream-json are the structured formats. --stream-partial-output adds incremental deltas.

For a script, the install docs set CURSOR_API_KEY and then call agent -p. Images are passed by putting the file path in the prompt. The agent reads the file with its tools.

See Using Headless CLI.

Grok Build

grok -p "Explain this codebase" sends one prompt. --output-format is plain, json (one JSON object at the end) or streaming-json (one JSON event per line). --always-approve approves tool executions for that run. --model selects a model.

Headless sessions from --session-id, --resume or --continue are stored in ~/.grok/sessions. In scripts, the docs say to pass --no-auto-update so a background update check doesn’t run. You can also set auto_update = false under [cli] in ~/.grok/config.toml.

grok agent stdio is the ACP mode, for an editor or another client speaking JSON-RPC. That is a programming interface, not a one-shot prompt. Assistant text arrives as session/update chunks. session/prompt returns completion metadata, so a client that only waits for the prompt response can miss the answer.

See Headless and scripting.

Details checked against each vendor’s documentation in October 2026.

A real example

This asks for an explanation and writes it to a file. It does not need edit permission:

claude -p "Explain how post dates are rendered, in five lines" --allowedTools "Read" > post-dates.txt

The Codex form is read-only unless you change the sandbox. The final message is what lands in the file. Progress stays on stderr:

codex exec "Explain how post dates are rendered, in five lines" > post-dates.txt

Cursor’s print mode, without --force, is the question form:

agent -p "Explain how post dates are rendered, in five lines" > post-dates.txt

Grok, with updates suppressed and JSON at the end if a script will parse it:

grok --no-auto-update -p "Explain how post dates are rendered, in five lines" --output-format json > post-dates.json

To let the agent edit, the flags diverge. Codex needs --sandbox workspace-write. Cursor needs --force. Grok needs --always-approve if you don’t want an approval prompt. Claude Code needs the tools named in --allowedTools, or another permission setting you meant to allow. A script copied from one tool to another with the same words will either refuse to edit or approve more than you think.

When to use headless mode

Use it when a program should call the agent: a CI check, a nightly report, a pipeline that pipes a log in and a summary out. The prompt and the permissions are fixed before the process starts.

Use an interactive session when you still need to answer questions, change permission mode mid-task, or stop a wrong edit while it is happening. Use a cloud agent when the work should run on the vendor’s VM instead of on the runner you operate.

Pitfalls

Each tool’s default is a different amount of power. Codex exec is read-only until you opt into workspace-write. Cursor --print proposes edits and applies them only with --force. Claude Code -p will load and run project hooks and MCP servers even in a folder you have never trusted, unless you pass --bare. Grok will sit on an approval prompt unless the run is allowed to continue, with --always-approve or a sandbox you already set.

--bare fixes the “same script, different laptop” problem and drops your Claude subscription login. A CI job that worked on your machine because you were logged in fails until the API key is set.

Old Codex scripts that pass --full-auto are out of date. The current docs tell you to replace that flag.

Don’t export an API key for the whole CI job when the job runs code from the repo. Codex’s docs call that out for OPENAI_API_KEY and CODEX_API_KEY. A script the repo controls can read the environment.

Claude Code’s stdin pipe stops at 10MB. A big log has to be a file path in the prompt, not a pipe.

How to use Grok Build has a full headless section, including --no-auto-update, output formats and ACP.
The complete guide to Codex shows codex exec for a non-interactive task.
Run coding agents unattended is about the run nobody is watching, including a Cursor CLI script that needs --force to write files.
Use Claude Code and Codex from OpenCode shows claude -p and codex exec as the non-interactive calls those tools make.
CLI Tools Cabinet catalogs installed commands, including the agent CLIs, with examples and shell history. The tutorial shows an agent reading that catalog before it invents a command.

Permission modes: Permission modes decide what a coding agent can do without asking. The modes in Claude Code, Codex, Cursor and Grok Build, and what YOLO mode really skips.
Cloud agents: Cloud agents run a coding task on a remote machine instead of your laptop. How Claude Code, Codex, Cursor and Grok Bot start one, and what they cannot see.
Slash commands: Slash commands are the /name controls inside a coding agent session. How they work in Claude Code, Codex, Cursor and Grok Build, and how to add your own.

All AI glossary entries →

Follow @flaviocopes

Want me to talk about your product? You can sponsor this site.