Run Claude Code programmatically changedheadless
Nearest release: v2.1.305, published an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 20 Oct 2026 18:25 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+34added
Lines−32removed
From line
62
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits42to this page, all time
The whole hunk
from line 62, old and new numbered
/
from line 62
6262
6363Before v2.1.286, these limits held only partly: an interactive `--bare` session connected the MCP servers that a normal session would, every `--bare` session sent system reminders, and background tasks stayed available.
6464
65<Note>
66 `--bare` is the recommended mode for scripted and SDK calls, and will become the default for `-p` in a future release.
67</Note>
65> [!NOTE]
66>
67> `--bare` is the recommended mode for scripted and SDK calls, and will become the default for `-p` in a future release.
6868
6969### Background tasks at exit
7070
from line 116
116116
117117With `--output-format json`, the response payload includes `total_cost_usd` and a per-model cost breakdown, so scripted callers can track spend without consulting the [usage dashboard](/docs/en/costs). When you continue an earlier conversation with `--continue` or `--resume`, the run reports the conversation's whole total, [earlier runs' spend included](/docs/en/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls). Both figures are [client-side estimates](/docs/en/agent-sdk/cost-tracking) and can differ from your actual bill.
118118
119<Note>
120 Piped stdin is capped at 10MB. If you exceed the cap, Claude Code exits with a clear error and a non-zero status. To work with larger inputs, write the content to a file and reference the file path in your prompt instead of piping it.
121</Note>
119> [!NOTE]
120>
121> Piped stdin is capped at 10MB. If you exceed the cap, Claude Code exits with a clear error and a non-zero status. To work with larger inputs, write the content to a file and reference the file path in your prompt instead of piping it.
122122
123123If Claude Code can't read stdin, for example because the process that started it disconnected its end, Claude Code prints a warning to stderr and continues with the prompt from the command line.
124124
from line 164
164164
165165If the value isn't a valid JSON Schema, `claude` exits with `Error: --json-schema is not a valid JSON Schema` followed by the validator's diagnostic. Claude Code accepts schemas that use the `format` keyword, such as `"format": "email"`, but treats `format` as an annotation and doesn't enforce it.
166166
167<Tip>
168 Use a tool like [jq](https://jqlang.org/) to parse the response and extract specific fields:
167If a run ends without valid structured output, for example because Claude declined the request, the response has no `structured_output` field. Before your script uses `structured_output`, check that the field is present.
169168
170 ```bash theme={null}
171 # Extract the text result
172 claude -p "Summarize this project" --output-format json | jq -r '.result'
169> [!TIP]
170>
171> Use a tool like [jq](https://jqlang.org/) to parse the response and extract specific fields:
172>
173> ```bash theme={null}
174> # Extract the text result
175> claude -p "Summarize this project" --output-format json | jq -r '.result'
176>
177> # Extract structured output
178> claude -p "Extract function names from auth.py" \
179> --output-format json \
180> --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
181> | jq '.structured_output'
182> ```
173183
174 # Extract structured output
175 claude -p "Extract function names from auth.py" \
176 --output-format json \
177 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
178 | jq '.structured_output'
179 ```
180</Tip>
181
182184### Stream responses
183185
184186Use `--output-format stream-json` with `--verbose` and `--include-partial-messages` to receive tokens as they're generated. Each line is a JSON object representing an event:
from line 333
331333
332334With `--output-format stream-json`, denials appear as `permission_denied` system messages, and the final result message lists them in `permission_denials`.
333335
334<Note>
335 The `--permission-prompts` flag requires Claude Code v2.1.259 or later. Earlier versions reject it with an unknown-option error.
336</Note>
336> [!NOTE]
337>
338> The `--permission-prompts` flag requires Claude Code v2.1.259 or later. Earlier versions reject it with an unknown-option error.
337339
338340### Create a commit
339341
from line 348
346348
347349The `--allowedTools` flag uses [permission rule syntax](/docs/en/settings-reference#permission-rule-syntax). The trailing ` *` enables prefix matching, so `Bash(git diff *)` allows any command starting with `git diff`. The space before `*` is important: without it, `Bash(git diff*)` would also match `git diff-index`.
348350
349<Note>
350 Command support differs in `-p` mode:
351
352 * User-invoked [skills](/docs/en/skills) and custom commands work. Include `/skill-name` in the prompt string and Claude Code expands it before running.
353 * Built-in commands that only run in the terminal interface, such as `/login`, aren't available.
354 * `/model`, `/effort`, `/fast`, `/color`, and `/rename` accept the value as an argument, for example `/model sonnet`, and `/mcp` with no argument prints a text summary of server status. These forms follow each command's [availability notes](/docs/en/commands#all-commands).
355 * To change a setting, pass `key=value` to `/config`, for example `/config thinking=false`.
356 * `/output-style <style>` switches [output styles](/docs/en/output-styles) and `/output-style` alone lists them. Requires Claude Code v2.1.269 or later.
357</Note>
351> [!NOTE]
352>
353> Command support differs in `-p` mode:
354>
355> * User-invoked [skills](/docs/en/skills) and custom commands work. Include `/skill-name` in the prompt string and Claude Code expands it before running.
356> * Built-in commands that only run in the terminal interface, such as `/login`, aren't available.
357> * `/model`, `/effort`, `/fast`, `/color`, and `/rename` accept the value as an argument, for example `/model sonnet`, and `/mcp` with no argument prints a text summary of server status. These forms follow each command's [availability notes](/docs/en/commands#all-commands).
358> * To change a setting, pass `key=value` to `/config`, for example `/config thinking=false`.
359> * `/output-style <style>` switches [output styles](/docs/en/output-styles) and `/output-style` alone lists them. Requires Claude Code v2.1.269 or later.
358360
359361### Customize the system prompt
360362
No line in this hunk matches that.