Skip to content
Mastering Claude

Home / Everyday moves

Everyday moves9 minApplication

Headless mode, output styles 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, a shape a script can read without parsing free text. 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. The official documentation recommends it for scripted calls and notes it could become the default value for -p in a future version. This speed gain has a trade off nothing on screen points out: bare mode never reads OAuth credentials or the system keychain, so it does not rely on the subscription login, and a script using it must set the ANTHROPIC_API_KEY variable in its environment to authenticate with the Anthropic API.

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.

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 for three families of commands that stay blocking until the end, those starting with sleep, those containing git, and commands too compound to be analysed by the safety mechanism. Combining both moves, headless mode for input and output, background task for duration, makes a script capable of driving Claude Code without ever waiting stuck in front of a terminal. The session identifier that --output-format json explicitly returns is the same one picked up by every quick terminal move with --resume.

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
  • The -p flag triggers headless mode, without an interactive interface, for a scripted use of Claude Code.
  • --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.
  • run_in_background immediately returns a task identifier and lets a long command keep running while the conversation continues.
  • A command that reaches its timeout automatically switches to a background task, unless it starts with sleep, contains git, or is too compound to be analysed.
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.