What
At startup Claude Code reads settings passed on the command line. It used to load only the --settings flag. It now also loads the --managed-settings payload, and runs this step when either one is given.
Programs using the SDK, which lets code drive Claude Code, pass Options.managedSettings, which becomes --managed-settings.
Why
Managed settings passed this way now take effect in this startup path. Before, they were accepted but not applied there.
Names in the bundle--settings
The entry above is what we published on the day. These lines were added later, as Anthropic's own pages caught up, and they sit beside the original rather than replacing it.
Added since
A small documentation edit on Week 20 · May 11–15, 2026 touched a line naming --settings after this was published.
<div><code>claude agents</code> gained dispatch flags (`--add-dir`, `--settings`, `--mcp-config`, `--plugin-dir`, `--permission-mode`, `--model`, `--effort`, `--dangerously-skip-permissions`) to configure background sessions, and `claude a…whats-new/2026-w20 see the edit
Confirmed since
Anthropic's documentation has since written up --settings, on Error reference.
The file you passed to [`--settings`](/docs/en/cli-reference#cli-flags) is larger than 2 MiB, so `claude` exits with code 1 at startup instead of loading it. Before v2.1.214, Claude Code read the file with no size check, and a multi-gigaby…errors see the edit
One source agreesOne thing we can check says the same as this entry.
Anthropic's documentation agrees
Anthropic's documentation has since written up --settings, on Error reference.