claude-code - 💡(How to fix) Fix [DOCS] Model configuration docs omit `/model` restart persistence and pin-source indicators [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/model-config

Section/Topic

Setting your model, Control the model users run on, and Checking your current model

Current Documentation

The docs currently say:

You can configure your model in several ways, listed in order of priority:

1. During session - Use /model <alias|name> to switch models mid-session
2. At startup - Launch with claude --model <alias|name>
3. Environment variable - Set ANTHROPIC_MODEL=<alias|name>
4. Settings - Configure permanently in your settings file using the model field.

And later:

The model setting is an initial selection, not enforcement. It sets which model is active when a session starts, but users can still open /model and pick Default, which resolves to the system default for their tier regardless of what model is set to.

And in Checking your current model:

You can see which model you're currently using in several ways:

1. In status line (if configured)
2. In /status, which also displays your account information.

The /model command reference also only says:

Select or change the AI model. For models that support it, use left/right arrows to adjust effort level. The change takes effect immediately without waiting for the current response to finish

What's Wrong or Missing?

Changelog v2.1.117 says: "Improved /model: selections now persist across restarts even when the project pins a different model, and the startup header shows when the active model comes from a project or managed-settings pin".

The current docs do not explain that a model chosen in /model can persist across restarts, including how that persisted choice interacts with a project-level model pin.

They also do not document the new startup-header indicator that tells users when the active model comes from a project pin or a managed-settings pin.

Because the docs currently describe startup model selection mainly in terms of CLI args, environment variables, and settings files, readers can reasonably infer that restart behavior is determined only by those sources. That is now outdated or at least incomplete for v2.1.117.

Suggested Improvement

Update model-config to add a short subsection that explains:

1. whether /model selections are session-only or persisted across restarts,
2. how persisted /model choices interact with shared project model settings and managed pins,
3. which source wins when Claude Code restarts, and
4. where users can see the source of the active model.

In Checking your current model, add the startup header as a documented place to confirm the active model and note that the header can indicate when the model comes from a project pin or managed-settings pin.

In the /model command reference, add a brief note that model selections persist across restarts in current versions.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.117

Exact changelog entry: Improved /model: selections now persist across restarts even when the project pins a different model, and the startup header shows when the active model comes from a project or managed-settings pin