Headless mode: what changes when there's no one to ask

In Claude Code

Headless mode (via -p) in Claude Code, short for --print, allows specifying --output-format with possible values of text (the default), json, stream-json; it works only when used with -p.

Eg: Running a single command with some prompt and the output in json:

claude -p "Summarise the changes on this branch" --output-format json

The most important part is the json wrapper, which contains following fields:

• subtype

• is_error

• stop_reason

• num_turns

• session_id

• total_cost_usd, split by model

• permission_denials — tools invocations, that were rejected due to lack of approval, each of them comes with its input

The most interesting of the above, is the last one. For instance, on 2.1.221 version running a not approved Write creates an entry in this array:

"permission_denials": [
  { "tool_name": "Write",
    "tool_use_id": "toolu_01XYC5xQwshpyu3ZC3EGwvMX",
    "tool_input": { "file_path": "/private/tmp/headless-check/cc-was-here.txt",
                    "content": "ok\n" } }
]

The same run in terms of the return value, was:

• subtype: success

• is_error: false

• exit code: 0

So, to make it work properly it would be better for a CI gate to examine this field, rather than the process exit status, like in an example below:

claude -p "$PROMPT" --output-format json > run.json
test "$(jq '.permission_denials | length' run.json)" -eq 0 || exit 1

Instead of that, we could define the set of tools in advance by using --allowedTools with an explicit list. For the most restrictive mode we can use --permission-mode dontAsk, which rejects everything not included in permissions.allow and the list of read-only commands (the docs call it useful for locked-down CI runs, and it's the closest thing to an honest "there's nobody here" mode).

For reproducibility we can use --bare flag, which doesn't pick up any context from the surrounding environment — skipping hooks, skills, plugins, MCP servers, automatic memory and CLAUDE.md. It also doesn't touch OAuth credentials and the keychain, so in order to use ANTHROPIC_API_KEY we need to set it in the environment. The context can be introduced on purpose with --settings, --mcp-config, --append-system-prompt and similar flags. This is a good option for scripting usage of Claude Code, it's also planned to become default for -p in the future.

If you plan to integrate it with some process supervisor, there are 2 more things worth knowing:

• --print skips the workspace trust prompt, and if any settings file fails validation during headless run, it is just ignored without any error message (see --help for -p for details)

• in case of SIGTERM being send to Claude Code by a supervising process, the turn is cancelled, Bash command tree is terminated and SessionEnd hooks are called; exit code is 143

Lastly, I've found that the permission_denials array contains info about only those approvals, that couldn't be obtained. For instance, for a file with a deny rule in place, if we try to read it, the result text says so plainly. But at the same time permission_denials is empty. So — as we can see — there are two ways that lead to the same result (or rather lack of it), and one of them does not leave a trace at all, so checking the output is always good.

In Codex CLI

It's worth noting that if you run codex in headless mode using subcommand codex exec it takes the value after prompt as an input. If you were to use -p flag with codex exec it sets --profile flag pointing to a config file (layered on top of user config) rather than printing the output.

Here's what a single run could look like, ignoring the git repo check:

codex exec --skip-git-repo-check "Summarise the changes on this branch" < /dev/null

As mentioned, it's the headless mode, so the standard output is the answer and the standard error is used for the status messages (you can see it by redirecting stdout to a file, you will only get the answer):

$ codex exec "Hey" 2> codex-status.txt > codex-answer.txt

If you were to run codex in this way any time it is launched it outputs a config header on stderr so you can be sure what configuration it uses. It contains information like the following:

OpenAI Codex v0.146.0
--------
workdir: /private/tmp/headless-check
model: gpt-5.6-terra
provider: openai
approval: never
sandbox: read-only
...

The default behaviour for codex exec is to run in a read-only sandbox, and the header is also where you see the approval policy that's actually in force — mine says "never". That means that there's no approver and there's nothing to be approved (in the read-only environment there are no files to change). To change this you need to run your code using flag --sandbox workspace-write. I would generally say that using danger-full-access is most reasonable when working in an already isolated environment like a docker image created for this purpose.

If you want to have structured output you can use --json flag which converts standard output into JSONL stream of events, there are thread.started, turn.started, turn.completed and turn.failed lifecycle events, and item.* events containing information about messages, commands and file changes.

There are also alternative ways if you're only interested in the final answer:

• -o <path> / --output-last-message <path> — the last message is saved to the file

• --output-schema <file> — the last message adheres to a JSON Schema specified in the file

If you want to run codex without using any of your setup you can use following flags:

• --ephemeral — no session files are being created on disk

• --ignore-user-config — user config from $CODEX_HOME/config.toml is ignored

• --ignore-rules — .rules files from both project and user directory are ignored

There are also 2 pitfalls to be aware of that might result in unexpected behaviour:

• If you run codex outside of a git repository it exits before making a call to the model with an error message saying that current directory isn't trusted and that it's needed to use --skip-git-repo-check flag, exit code is 1

• The standard input is being consumed by codex so if you were to run it like this:

$ codex exec "Summarise the changes on this branch"

You will see a notice on every run saying that it reads extra input. The input is being appended to the prompt as additional context so it's useful when you for example want to pipe diff to it to review it but if you don't want to do that make sure to redirect from /dev/null:

$ codex exec "Summarise the changes on this branch" < /dev/null

In Cursor

The cursor agent is a command-line binary called cursor-agent. It has a non-interactive flag -p / --print, which its own help says it's built for to be used in scripts and non-interactive scenarios, with access to every feature of the tool including file writes and shell. Here's an example of a single command asking the agent to summarise changes of a branch and running it with trust granted and JSON output format:

cursor-agent -p --trust "Summarise the changes on this branch" --output-format json

It supports three output formats, set via the --output-format flag:

• text

• json

• stream-json

you can set it to the latter and additionally pass --stream-partial-output to enable token-level deltas in the stream. If you were to use the tool with a host that doesn't support interactive authentication, you could pass --api-key or set the CURSOR_API_KEY environment variable.

Generally, the biggest source of confusion for new users is workspace trust — the agent doesn't work in non-trusted directories in print mode at all (rather than just being less capable), so it displays a message like this one:

⚠ Workspace Trust Required

  Cursor Agent can execute code and access files in this directory.
  Do you trust the contents of this directory?

    /private/tmp/headless-check

  To proceed, you can either:
    • Run 'agent' interactively to decide
    • Pass --trust, --yolo, or -f if you trust this directory

and then exits with an empty standard output and code 1. It's kinda annoying at first but actually makes sense — every CI run gets a fresh directory so it's not a single hurdle but rather a landscape; and --trust is the solution we have in mind, setting up workspace trust without asking is exactly what this flag is for. Be aware though that --yolo and -f do the same thing (in terms of letting you bypass the trust error) but they are permissions modes, so using them against a trust error you get a wall replaced with a highway.

The gotcha is that print mode really writes — I tested it in 2026.07.23-e383d2b with -p --trust and no --force, and for example made it create a file called cursor-was-here.txt containing the word ok, and it indeed created it on disk. So if you work with unattended agent in -p mode, assume it has write and shell capabilities from the very beginning, and if you want to have a real boundary, use a disposable clone, container or branch.

In Antigravity CLI

It's called agy, and the non-interactive version of it is agy -p (--print and --prompt are also valid aliases). The standard output stream is used to return an answer, while stderr is utilised for errors, displaying the run progress, and showing permission-related notices to ensure the returned answer remains pristine. For example:

answer=$(agy -p "Summarise the changes on this branch")

The output format can be controlled using the --output-format option, which accepts these values:

• text (default)

• json — emits a single envelope upon completion of the run

• stream-json — emits NDJSON events during the run

Here's an example of such an envelope:

{
  "conversation_id": "055a398f-db14-4c5f-abbb-1bf03f8120a7",
  "status": "SUCCESS",
  "response": "A git rebase rewrites the commit history…\n",
  "duration_seconds": 7.16,
  "num_turns": 1,
  "usage": {
    "input_tokens": 10415,
    "output_tokens": 657,
    "thinking_tokens": 616,
    "cache_read_tokens": 8113,
    "total_tokens": 11072
  }
}

The important thing is the status field which you should base your conditions on; it can take the following values:

• SUCCESS

• ERROR

• CANCELED

• INTERRUPTED

• INVALID

• WAITING

• RUNNING

When you need to enforce a certain structure of the response, you can use --json-schema flag and either provide an inline schema or point to a JSON file (or even pass the name of a primitive type like string).

Permissions is another crucial aspect worth examining. Let's say there's a tool that requires a permission it can't get; if you run it, it'll be "soft-denied", meaning the run won't exit with a non-zero code but will proceed with an stderr notice indicating which tool and how to allow it. By default all file I/O operations within the project are allowed, but shell commands default to Ask (they're not allowed by default in headless mode). The allow-list is based on a configuration file called ~/.gemini/antigravity-cli/settings.json, which contains an array of permissions.allow entries, like this:

{
  "permissions": {
    "allow": [
      "command(git)",
      "command(npm run (build|lint|test))",
      "write_file(src/)"
    ]
  }
}

This will allow using git, selected npm run scripts (build, lint and test), as well as writing files under a src directory.

The authentication is based on credentials that are cached once you've logged in at least once in a terminal. If you were to run the tool without a terminal (when it can't ask for the credentials), it'll throw an error instead of waiting indefinitely, which is the desired behaviour for overnight scheduled runs.

What's important to remember though, is that this soft-denial mechanism comes with a risk — the tool won't exit with a non-zero code but will display an stderr notice and return an answer on stdout. So make sure to check stderr, or at least to condition on status together with the produced artefact, not just on the exit code. A good illustration of how the tool works in this regard is that pointing --model at a nonexistent model results in it exiting with a non-zero code and setting the status to ERROR — it doesn't make any "smart" replacements.

The last thing worth keeping in mind is that print runs are limited by the --print-timeout flag which defaults to 5 minutes, so if you need more time to complete a substantial task, make sure to increase this value.

In Kimi Code CLI

The -p flag is short for --prompt and takes the prompt text as its value — so it's a valued flag, not a switch which needs to be placed before a raw string; it runs a single prompt and never starts the TUI. For example:

kimi -p "Summarise the changes on this branch" --output-format stream-json

which will run a single prompt asking you for a branch change summary with the streaming JSON output mode enabled: By default, Kimi uses the text output format (the text value for the --output-format flag). You can set it to stream-json instead, which is the only parseable output format available (no single-object JSON mode, so stream-json is the only reasonable choice); in this mode, the output has a form of one JSON object per line. When the model calls a tool, an assistant message carrying tool_calls is emitted first, and the matching tool message follows it. The reasoning itself is not included in the JSONL file.

In the default mode (text), the output is a transcript rather than just a single answer; for example, a one-word prompt of mine came back as • PONG on standard output, with the thinking and a To resume this session: ... notice on standard error. It seems reasonable to me to direct the assistant's messages to the standard output and everything else to the standard error, but it'd be good to trim the leading bullet anyway in such scenario.

The -p flag also disables the confirmation procedure so you can't ever get asked for a permission when using it. In this mode the "ordinary" tool calls run under the auto permission policy; if you define some deny rules, those are still applied — they're the only thing left standing.

You can't run Kimi with both --prompt and --yolo, --auto, or --plan flags; Kimi won't accept such combinations and will exit with an error.

To deny certain tools, you need to set up a [[permission.rules]] array in the config file (config.toml); they are being evaluated one by one in order and the first match wins. The rule is either a tool name or a tool name with an argument pattern: For example, if you don't want to run a recursive shell deletion or read an env file, you can create two deny rules:

[[permission.rules]]
decision = "deny"
pattern = "Bash(rm -rf*)"

[[permission.rules]]
decision = "deny"
pattern = "Read(.env)"

The thing is... The auto policy is the most permissive one, and on this harness it applies to the only tool that doesn't have a real OS-level sandbox as a backup — the blank cell in the sandbox row of the reference table. That means that the deny rules are all you have here, not a backup layer. Also, note that argument patterns can be defined only for built-in tools that have a concept of subject (so they can't be used with AgentSwarm, MCP tools, or your own custom tools) — if it comes to AgentSwarm, MCP tools and custom tools, you can only define rules based on tool names. Therefore, if you run Kimi with -p flag in an unattended manner, you should run it inside a container (or a virtual machine), which will replace the missing sandbox.