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.
From a headless command to output a script can use
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 this establishes: This run establishes that the script can read a total cost without parsing free text, since the json format makes it available as a structured field.
What this does not establish: It does not establish that this cost corresponds to the deployment pipeline's overall spending, since other steps in the pipeline can incur costs that have nothing to do with this call to Claude Code.
The three most common miscalibrations
- Too broad The json format now exposes the costs of every tool used in the deployment pipeline, not just this call to Claude Code.
- Too narrow This run proves nothing at all, since only one call was observed in a single pipeline.
- Off target This run shows that the deployment pipeline now finishes faster than before this call to Claude Code was added.
- 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.
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.
Every datable claim in this lesson links here to the public text behind it. A source that does not open proves nothing.
- Claude Code, headless mode, output formats and the --bare flag accessed on 2026-09-02
- Claude Code, tools reference, run_in_background and the automatic switch to a background task accessed on 2026-09-02
- Claude Code, permission modes: claude -p starts in default accessed on 2026-10-24
- Claude Code changelog: background command limit in unattended sessions accessed on 2026-10-24
- Claude Code changelog 2.1.325: MCP tasks waiting for an answer and pointer to /tasks accessed on 2026-11-14
- Claude Code, command-line reference: --bare, --tools and --strict-mcp-config flags accessed on 2026-11-16
- Claude Code changelog 2.1.319: claude -p exits with code 1 in auto mode when actions are refused accessed on 2026-11-16