docs(settings): add 7 keys (allowAllClaudeAiMcps, disableAgentView, strictPluginOnlyCustomization, maxSkillDescriptionChars, skillListingBudgetFraction, claudeMd, syntaxHighlightingDisabled); fix externalEditorContext default+desc and opus/sonnet aliases; bump to v2.1.150
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Shayan Rais
@@ -1,9 +1,9 @@
|
||||
# Settings Best Practice
|
||||
|
||||
 <br>
|
||||
 <br>
|
||||
[](../.claude/settings.json)
|
||||
|
||||
A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of v2.1.145, Claude Code exposes **80+ settings** and **180+ environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts).
|
||||
A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of v2.1.150, Claude Code exposes **80+ settings** and **180+ environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts).
|
||||
|
||||
<table width="100%">
|
||||
<tr>
|
||||
@@ -79,6 +79,7 @@ Within the managed tier, precedence is: server-managed > MDM/OS-level policies >
|
||||
| `agent` | string | - | Set the default agent for the main conversation. Value is the agent name from `.claude/agents/`. Also available via `--agent` CLI flag |
|
||||
| `language` | string | `"english"` | Claude's preferred response language. Also sets the voice dictation language and the terminal tab title (v2.1.121) |
|
||||
| `claudeMdExcludes` | array | - | Glob patterns or absolute paths of `CLAUDE.md` files to skip when loading [memory](https://code.claude.com/docs/en/memory). Patterns match against absolute file paths. Only applies to user, project, and local memory; managed policy files cannot be excluded. Example: `["**/vendor/**/CLAUDE.md"]` |
|
||||
| `claudeMd` | string | - | **(Managed only)** CLAUDE.md-style instructions injected as organization-managed [memory](https://code.claude.com/docs/en/memory). Only honored when set in managed or policy settings; ignored in user, project, and local settings. Example: `"Always run make lint before committing."` |
|
||||
| `cleanupPeriodDays` | number | `30` | Age cutoff for the startup cleanup sweep (minimum 1). Inactive session transcripts and orphaned subagent worktrees are deleted; as of v2.1.117 the sweep also covers `~/.claude/tasks/`, `~/.claude/shell-snapshots/`, and `~/.claude/backups/`. Setting to `0` is rejected with a validation error. To disable transcript writes in non-interactive mode (`-p`), use `--no-session-persistence` or `persistSession: false` SDK option |
|
||||
| `autoUpdatesChannel` | string | `"latest"` | Release channel: `"stable"` or `"latest"` |
|
||||
| `minimumVersion` | string | - | Prevent the auto-updater from downgrading below a specific version. Automatically set when switching to the stable channel and choosing to stay on the current version until stable catches up. Used with `autoUpdatesChannel` |
|
||||
@@ -96,12 +97,15 @@ Within the managed tier, precedence is: server-managed > MDM/OS-level policies >
|
||||
| `showThinkingSummaries` | boolean | `false` | Show extended thinking summaries in interactive sessions. When unset or `false` (default in interactive mode), thinking blocks are redacted by the API and shown as a collapsed stub. Redaction only changes what you see, not what the model generates — to reduce thinking spend, lower the budget or disable thinking instead. Non-interactive mode (`-p`) and SDK callers always receive summaries regardless of this setting |
|
||||
| `disableSkillShellExecution` | boolean | `false` | Disable inline shell execution for `` !`...` `` and `` ```! `` blocks in skills and custom commands from user, project, plugin, or additional-directory sources. Commands are replaced with `[shell command execution disabled by policy]` instead of being run. Bundled and managed skills are not affected (v2.1.91) |
|
||||
| `skillOverrides` | string | - | Control automatic skill invocation behavior. Values: `"off"` (skills are not invoked at all), `"user-invocable-only"` (only skills the user explicitly invokes via `/skill-name` run; auto-discovery via skill descriptions is disabled), `"name-only"` (skills are matched by exact name only; description-based auto-discovery is disabled). Use to keep a tighter rein on which skills the model loads or runs (v2.1.129) |
|
||||
| `maxSkillDescriptionChars` | number | `1536` | Per-skill character cap on the combined `description` and `when_to_use` text in the [skill listing](https://code.claude.com/docs/en/skills) Claude sees each turn. Text longer than this is truncated (v2.1.105) |
|
||||
| `skillListingBudgetFraction` | number | `0.01` | Fraction of the model's context window reserved for the [skill listing](https://code.claude.com/docs/en/skills) Claude sees each turn (`0.01` = 1%). When the listing exceeds the budget, descriptions for the least-used skills are collapsed to bare names so Claude can still invoke them but won't see why (v2.1.105) |
|
||||
| `forceRemoteSettingsRefresh` | boolean | `false` | **(Managed only)** Block CLI startup until remote managed settings are freshly fetched. If the fetch fails, the CLI exits (fail-closed). Use in enterprise environments where policy enforcement must be up-to-date before any session begins (v2.1.92) |
|
||||
| `wslInheritsWindowsSettings` | boolean | `false` | **(Windows managed settings only)** When `true`, Claude Code on WSL reads managed settings from the Windows policy chain (HKLM registry + `C:\Program Files\ClaudeCode\managed-settings.json`) in addition to `/etc/claude-code`, with Windows sources taking priority. Only honored when set in the HKLM registry key or `C:\Program Files\ClaudeCode\managed-settings.json`, both of which require Windows admin to write. For HKCU policy to also apply on WSL, the flag must additionally be set in HKCU itself. Has no effect on native Windows (v2.1.118) |
|
||||
| `tui` | string | `"default"` | Rendering mode: `"fullscreen"` or `"default"`. Set via `/tui fullscreen` for flicker-free alt-screen rendering (v2.1.110) |
|
||||
| `awaySummaryEnabled` | boolean | `true` | Generate an "away summary" (idle-session recap) when the user returns after being away. Set to `false` to opt out. Pairs with the `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` env var (v2.1.110) |
|
||||
| `skillOverrides` | object | - | Per-skill visibility overrides keyed by skill name. Value is `"on"` (full), `"name-only"` (visible but not auto-described), `"user-invocable-only"` (hidden from model discovery but still slash-invocable), or `"off"` (fully hidden). Example: `{"legacy-context": "name-only", "deploy": "off"}` (v2.1.129) |
|
||||
| `disableRemoteControl` | boolean | `false` | Disable [Remote Control](https://code.claude.com/docs/en/remote-control): blocks `claude remote-control`, the `--remote-control` flag, auto-start, and the in-session toggle. Typically placed in managed settings for per-device MDM enforcement, but works from any scope (v2.1.128) |
|
||||
| `disableAgentView` | boolean | `false` | Set to `true` to turn off [background agents and agent view](https://code.claude.com/docs/en/agent-view): `claude agents`, `--bg`, `/background`, and the on-demand supervisor. Can be set at any scope but typically placed in managed settings. Equivalent to setting the `CLAUDE_CODE_DISABLE_AGENT_VIEW` env var to `1` |
|
||||
| `feedbackSurveyRate` | number | - | Probability (0–1) that the session quality survey appears when eligible. Enterprise admins can control how often the survey is shown. Example: `0.05` = 5% of eligible sessions |
|
||||
|
||||
**Example:**
|
||||
@@ -367,6 +371,7 @@ Configure Model Context Protocol servers for extended capabilities.
|
||||
| `allowManagedMcpServersOnly` | boolean | Managed only | Only allow MCP servers explicitly listed in managed allowlist |
|
||||
| `channelsEnabled` | boolean | Managed only | Allow [channels](https://code.claude.com/docs/en/channels) for Team and Enterprise users. When unset or `false`, channel message delivery is blocked regardless of `--channels` flag |
|
||||
| `allowedChannelPlugins` | array | Managed only | Allowlist of channel plugins that may push messages. Replaces the default Anthropic allowlist when set. Undefined = fall back to the default, empty array = block all channel plugins. Requires `channelsEnabled: true`. Each entry is an object with `marketplace` and `plugin` fields (v2.1.84) |
|
||||
| `allowAllClaudeAiMcps` | boolean | Managed only | Load claude.ai cloud MCP connectors alongside `managed-mcp.json`. When enabled, claude.ai-hosted MCP connectors are made available in addition to admin-deployed managed MCP servers *(in v2.1.150 changelog, not yet on official settings page)* |
|
||||
|
||||
### MCP Server Matching (Managed Settings)
|
||||
|
||||
@@ -474,6 +479,7 @@ Configure Claude Code plugins and marketplaces.
|
||||
| `enabledPlugins` | object | Any | Enable/disable specific plugins |
|
||||
| `extraKnownMarketplaces` | object | Project | Add custom plugin marketplaces (team sharing via `.claude/settings.json`) |
|
||||
| `strictKnownMarketplaces` | array | Managed only | Allowlist of permitted marketplaces |
|
||||
| `strictPluginOnlyCustomization` | boolean \| array | Managed only | Block skills, agents, hooks, and MCP servers from user and project sources, so they can only come from plugins or managed settings. `true` locks all four surfaces; an array such as `["skills", "hooks"]` locks only the named ones |
|
||||
| `skippedMarketplaces` | array | Any | Marketplaces user declined to install *(in JSON schema, not on official settings page)* |
|
||||
| `skippedPlugins` | array | Any | Plugins user declined to install *(in JSON schema, not on official settings page)* |
|
||||
| `pluginConfigs` | object | Any | Per-plugin MCP server configs (keyed by `plugin@marketplace`) *(in JSON schema, not on official settings page)* |
|
||||
@@ -522,8 +528,8 @@ Configure Claude Code plugins and marketplaces.
|
||||
| Alias | Description |
|
||||
|-------|-------------|
|
||||
| `"default"` | Recommended for your account type |
|
||||
| `"sonnet"` | Latest Sonnet model (Claude Sonnet 4.6) |
|
||||
| `"opus"` | Latest Opus model (Claude Opus 4.6) |
|
||||
| `"sonnet"` | Latest Sonnet model (Claude Sonnet 4.6 on the Anthropic API; 4.5 on third-party providers) |
|
||||
| `"opus"` | Latest Opus model (Claude Opus 4.7 on the Anthropic API; 4.6 on Bedrock/Vertex/Foundry). Also the fast-mode default since v2.1.142 |
|
||||
| `"haiku"` | Fast Haiku model |
|
||||
| `"sonnet[1m]"` | Sonnet with 1M token context |
|
||||
| `"opus[1m]"` | Opus with 1M token context (default on Max, Team, and Enterprise since v2.1.75) |
|
||||
@@ -610,6 +616,7 @@ Configure via `env` key:
|
||||
| `spinnerTipsOverride` | object | - | Custom spinner tips with `tips` (string array) and optional `excludeDefault` (boolean). When `excludeDefault` is `true`, only custom tips show; when `false` or absent, custom tips merge with built-in tips. As of v2.1.121, `excludeDefault: true` also suppresses time-based spinner tips |
|
||||
| `respectGitignore` | boolean | `true` | Respect .gitignore in file picker |
|
||||
| `prefersReducedMotion` | boolean | `false` | Reduce animations and motion effects in the UI |
|
||||
| `syntaxHighlightingDisabled` | boolean | `false` | Disable syntax highlighting in diffs, code blocks, and file previews. Distinct from the `CLAUDE_CODE_SYNTAX_HIGHLIGHT` env var, which only governs diff output |
|
||||
| `fileSuggestion` | object | - | Custom file suggestion command (see File Suggestion Configuration below) |
|
||||
| `autoScrollEnabled` | boolean | `true` | Auto-scroll the conversation in fullscreen mode. Set to `false` to disable automatic scrolling (v2.1.110). Versions before v2.1.119 stored this in `~/.claude.json` |
|
||||
| `editorMode` | string | `"normal"` | Key binding mode for the input prompt: `"normal"` or `"vim"`. Appears in `/config` as **Editor mode**. Versions before v2.1.119 stored this in `~/.claude.json` |
|
||||
@@ -628,7 +635,7 @@ These IDE-related preferences are stored in `~/.claude.json`, **not** `settings.
|
||||
|-----|------|---------|-------------|
|
||||
| `autoConnectIde` | boolean | `false` | Automatically connect to a running IDE when Claude Code starts from an external terminal. Appears in `/config` as **Auto-connect to IDE (external terminal)** when running outside a VS Code or JetBrains terminal |
|
||||
| `autoInstallIdeExtension` | boolean | `true` | Automatically install the Claude Code IDE extension when running from a VS Code terminal. Appears in `/config` as **Auto-install IDE extension**. Can also be disabled via `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` env var |
|
||||
| `externalEditorContext` | boolean | `true` | Include additional context about the external editor when available. Set to `false` to disable |
|
||||
| `externalEditorContext` | boolean | `false` | Prepend Claude's previous response as `#`-commented context when you open the external editor with `Ctrl+G`. Set to `true` to enable |
|
||||
|
||||
### Workspace & Teams
|
||||
|
||||
@@ -861,6 +868,7 @@ Set environment variables for all Claude Code sessions.
|
||||
| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Override the context window size Claude Code assumes for the active model. Only takes effect when `DISABLE_COMPACT` is also set. Use when routing to a model through `ANTHROPIC_BASE_URL` whose context window does not match the built-in size for its name |
|
||||
| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Keep cwd between bash calls (`1` to enable) |
|
||||
| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Disable background tasks (`1` to disable) |
|
||||
| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | Set to `1` to turn off background agents and agent view (`claude agents`, `--bg`, `/background`, on-demand supervisor). Env-var equivalent of the `disableAgentView` setting *(referenced on official settings page; not listed on the env-vars page)* |
|
||||
| `ENABLE_TOOL_SEARCH` | MCP tool search threshold (e.g., `auto:5`) |
|
||||
| `ENABLE_PROMPT_CACHING_1H` | Opt into 1-hour prompt cache TTL. Replaces the deprecated `ENABLE_PROMPT_CACHING_1H_BEDROCK` *(in v2.1.108 changelog, not yet on official env-vars page)* |
|
||||
| `FORCE_PROMPT_CACHING_5M` | Force 5-minute prompt cache TTL *(in v2.1.108 changelog, not yet on official env-vars page)* |
|
||||
@@ -1078,6 +1086,10 @@ Set environment variables for all Claude Code sessions.
|
||||
"plansDirectory": "./plans",
|
||||
"claudeMdExcludes": ["**/vendor/**/CLAUDE.md"],
|
||||
"effortLevel": "xhigh",
|
||||
"maxSkillDescriptionChars": 1536,
|
||||
"skillListingBudgetFraction": 0.01,
|
||||
"disableAgentView": false,
|
||||
"syntaxHighlightingDisabled": false,
|
||||
|
||||
"worktree": {
|
||||
"symlinkDirectories": ["node_modules"],
|
||||
|
||||
Reference in New Issue
Block a user