Skip to content
Mastering Claude

The course175 lessons

Home / Everyday moves

Everyday moves9 minApplication

Headless mode, output formats and background tasks

Headless mode runs Claude Code without an interactive interface using -p, --output-format determines whether the output stays plain text or becomes a JSON object a script can use, with the total cost included, and run_in_background lets a long command keep running without blocking the conversation.

Headless mode runs Claude Code without an interactive interface, in a single command that returns its result and stops. The -p flag (or --print) triggers this mode, with a prompt given as an argument.

claude -p "Summarise the files changed in this repository" --output-format json

Three output formats for three uses

The --output-format parameter accepts three values. text, the default value, returns a natural language answer meant for a human. json returns a single structured object, with the result, the session identifier and the total cost in dollars along with a breakdown by model. stream-json returns the same information as JSON Lines, one object per line, useful when a program wants to react before the run has fully finished. A --bare flag skips the automatic discovery of hooks, skills, custom commands, sub-agents, plugins, MCP servers, automatic memory and CLAUDE.md files at startup, which speeds up the launch, and the official documentation recommends it for scripted calls. Trade-off: bare mode never reads OAuth credentials or the system keychain, so a script using it must set the ANTHROPIC_API_KEY variable to authenticate with the Anthropic API.

A minimal call when --bare is ruled out

On a subscription, --bare is no use, since it does not read the login. You then remove the sources one by one, with flags that claude --help lists in version 2.1.325:

claude -p "Reply with one word" --output-format json \
  --system-prompt "Reply in one word." --tools "" \
  --strict-mcp-config --disable-slash-commands --no-session-persistence

The default system prompt is replaced, the built-in tools are removed, skills and commands are disabled and the session is not saved. The help does not say that these flags ignore CLAUDE.md files: only --bare says so. Measure: compare the input_tokens and cache_creation_input_tokens fields of the usage object between the default call and the minimal call.

Letting a long command run without blocking

A long command launched through Claude Code's Bash tool can request run_in_background: true rather than waiting for it to finish. The tool then immediately returns a task identifier, the command keeps running in the background, and its output is read back afterwards with the Read tool. The Ctrl+B shortcut while a command is running makes the same switch by hand, and the /tasks command lists and stops running tasks.

Tasks exposed by MCP servers also go through /tasks. Since version 2.1.325, Claude is told when one of these tasks is waiting for your answer, and it can point you to /tasks to see it and reply.

This switch also happens on its own: a command that reaches its timeout without having finished automatically moves to a background task rather than being cut off outright, except when it starts with sleep. The CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 variable and --bare mode disable the switch: the command then stops at its timeout (tools reference, read again on 2026-11-16). The session identifier that --output-format json returns is the same one picked up by every quick terminal move with --resume.

What headless mode changes in October 2026

Since October 2026, claude -p and the Agent SDK with no permission mode configured start in default mode: a call that needs approval is refused there, unless an allow rule, a hook or the --permission-prompt-tool option grants it. A script that edits files must therefore pass --permission-mode or carry a rule. Also, the background command time limit now applies only in unattended sessions (-p, SDK, CI, cloud): a terminal, desktop or VS Code session no longer has a limit.

The exit code follows these refusals. In auto mode, when the actions of claude -p are refused because no safety check is available, the command exits with code 1, in text output as in JSON (changelog, version 2.1.319); it used to exit with 0. A script that tests the exit code now sees the failure, where an older script could believe it had succeeded.

Figure 1

From a headless command to output a script can use

01
Entering headless mode
The -p flag sends a prompt to Claude Code without opening an interactive interface.
02
Non interactive run
Claude Code handles the request on its own, without waiting for a human response between steps.
03
Chosen output
The --output-format parameter determines whether the result comes out as text, as a single JSON object, or as streamed JSON Lines.
04
Script reads the result
An external program picks up the structured output, with the total cost and the session identifier, without parsing free text.
05
Long command as a background task
If a step takes too long, run_in_background lets it keep running while the script stays free for what comes next.
The sequence shows how a request sent in headless mode goes through a non interactive run to a structured output a script can read, with a possible switch to a background task if a step takes too long.
Calibrate it yourself

A developer runs claude -p with --output-format json in a deployment pipeline, and the pipeline's script picks up the total_cost_usd field from the result to add it to the cost dashboard.

Write, in one sentence, what this situation establishes, and in one sentence what it does not establish.

What to remember
  • A claude -p script with no configured mode starts in default and has any call needing approval refused: pass --permission-mode or a rule.
  • --output-format json returns a single object carrying the result, the session identifier and the total cost in dollars with its breakdown by model.
  • --bare skips the automatic discovery of hooks, skills and context files at startup, a speed gain recommended for scripted calls, but it never reads OAuth credentials or the keychain, so ANTHROPIC_API_KEY becomes necessary; on a subscription, a minimal call is assembled by hand with --system-prompt, --tools and --strict-mcp-config.
  • run_in_background immediately returns a task identifier and lets a long command keep running; a command that reaches its timeout switches to a background task on its own, unless it starts with sleep, and CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 or --bare disable the switch. An MCP task waiting for your answer is flagged to Claude, which can point you to /tasks.
  • In auto mode, claude -p exits with code 1 when its actions are refused because no safety check is available: test the exit code in your scripts.
Do this now

From your terminal, run claude -p "a random word" --output-format json on a folder containing no sensitive data, and spot the session_id and total_cost_usd fields in the output.

Check the source

Every datable claim in this lesson links here to the public text behind it. A source that does not open proves nothing.