[DOCS] /model command persists to ~/.claude.json and bleeds across all projects/sessions

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://docs.anthropic.com/en/docs/claude-code/slash-commands

Section/Topic

/model slash command — scope and persistence

Current Documentation

The /model slash command is documented (or implied) to change the model for the current session. There is no warning that it writes the change persistently to ~/.claude.json, nor that the change applies machine-wide to every project and every future Claude Code session that does not have a project-scoped "model" override in its .claude/settings.json.

What's Wrong or Missing?

The /model slash command is documented (or implied) to change the model for the current session. There is no warning that it writes the change persistently to ~/.claude.json, nor that the change applies machine-wide to every project and every future Claude Code session that does not have a project-scoped "model" override in its .claude/settings.json.

Suggested Improvement

Document explicitly:

1. /model writes the selected model to ~/.claude.json (user-scope settings) — it is NOT session-scoped.
2. The change persists across sessions and applies to every project on the machine.
3. To scope a model choice to a single project, set "model" in that project's .claude/settings.json — project-scope overrides user-scope.
4. Recommend a warning in the /model UI itself: "This change applies machine-wide. Use .claude/settings.json for per-project locking."

Real-world impact: I run multiple role-based Claude Code sessions concurrently across two different projects (one needing Opus, one fine with Sonnet). Using /model in a standalone session of Project B silently downgraded all of Project A's running sessions to Sonnet mid-work, with no indication anywhere that this had happened. Took several hours to identify the root cause because the docs gave no hint that /model had global side effects.

Impact

High - Prevents users from using a feature

Additional Context

prevents the ability to set by-session , session-specific model.