From 1455ed39dc6b4b9611f6dd9a541ba00eeac75520 Mon Sep 17 00:00:00 2001 From: Shayan Rais Date: Mon, 1 Jun 2026 00:13:28 +0500 Subject: [PATCH] docs(settings): document workflow settings, Opus 4.8, and auto-mode env var - Bump version to v2.1.158 - Add disableWorkflows, workflowKeywordTriggerEnabled, ultracode (session-only) to General Settings - Add teammateDefaultModel (Global config) and pluginSuggestionMarketplaces (Plugin settings) - Update opus alias + effortLevel/XHigh notes for Opus 4.8 (latest on Anthropic API, defaults to high effort, supports xhigh) - Add CLAUDE_CODE_DISABLE_WORKFLOWS and CLAUDE_CODE_ENABLE_AUTO_MODE env vars - Remove stale "not yet on official page" note from allowAllClaudeAiMcps - Refresh Quick Reference example with new workflow keys Co-Authored-By: Claude --- best-practice/claude-settings.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/best-practice/claude-settings.md b/best-practice/claude-settings.md index 7eafc09..42b595a 100644 --- a/best-practice/claude-settings.md +++ b/best-practice/claude-settings.md @@ -1,9 +1,9 @@ # Settings Best Practice -![Last Updated](https://img.shields.io/badge/Last_Updated-May%2025%2C%202026%204%3A28%20PM%20PKT-white?style=flat&labelColor=555) ![Version](https://img.shields.io/badge/Claude_Code-v2.1.150-blue?style=flat&labelColor=555)
+![Last Updated](https://img.shields.io/badge/Last_Updated-Jun%2001%2C%202026%2012%3A03%20AM%20PKT-white?style=flat&labelColor=555) ![Version](https://img.shields.io/badge/Claude_Code-v2.1.158-blue?style=flat&labelColor=555)
[![Implemented](https://img.shields.io/badge/Implemented-2ea44f?style=flat)](../.claude/settings.json) -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). +A comprehensive guide to all available configuration options in Claude Code's `settings.json` files. As of v2.1.158, Claude Code exposes **80+ settings** and **180+ environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts). @@ -106,6 +106,9 @@ Within the managed tier, precedence is: server-managed > MDM/OS-level policies > | `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` | +| `disableWorkflows` | boolean | `false` | Set to `true` to disable [dynamic workflows](https://code.claude.com/docs/en/workflows) (`/workflows`) and the bundled workflow slash commands. Can be set at any scope. Equivalent to the `CLAUDE_CODE_DISABLE_WORKFLOWS` env var. Workflows were introduced in v2.1.154 | +| `workflowKeywordTriggerEnabled` | boolean | `true` | Whether typing the word "workflow" in a prompt can trigger a dynamic workflow. Set to `false` to require explicit `/workflows` invocation. Appears in `/config` (v2.1.157) | +| `ultracode` | boolean | - | **(Session-only — not persisted)** When `true`, the harness authors and runs a workflow for every substantive task by default, maximizing thoroughness regardless of token cost. Appears in the official "Available settings" list but is session-scoped: set via `/effort ultracode`, `--settings`, or the SDK rather than written to `settings.json` (v2.1.154) | | `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:** @@ -371,7 +374,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)* | +| `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 | ### MCP Server Matching (Managed Settings) @@ -480,6 +483,7 @@ Configure Claude Code plugins and marketplaces. | `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 | +| `pluginSuggestionMarketplaces` | array | Managed only | Allowlist of marketplace names whose plugins may appear as contextual install suggestions during a session. Restricts which marketplaces can surface "you might want this plugin" prompts (v2.1.152) | | `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)* | @@ -529,7 +533,7 @@ Configure Claude Code plugins and marketplaces. |-------|-------------| | `"default"` | Recommended for your account type | | `"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 | +| `"opus"` | Latest Opus model (Claude Opus 4.8 on the Anthropic API as of v2.1.154; 4.6 on Bedrock/Vertex/Foundry). Also the fast-mode default since v2.1.142. Opus 4.8 defaults to `high` effort and supports `/effort xhigh` | | `"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) | @@ -550,7 +554,7 @@ Map Anthropic model IDs to provider-specific model IDs for Bedrock, Vertex, or F | Key | Type | Default | Description | |-----|------|---------|-------------| -| `effortLevel` | string | - | Persist the effort level across sessions. Accepts `"low"`, `"medium"`, `"high"`, or `"xhigh"` (Opus 4.7 only, v2.1.111). Written automatically when you run `/effort low`, `/effort medium`, `/effort high`, or `/effort xhigh`. Supported on Opus 4.6, Sonnet 4.6, and Opus 4.7. Unsupported levels fall back to the highest supported level on the active model | +| `effortLevel` | string | - | Persist the effort level across sessions. Accepts `"low"`, `"medium"`, `"high"`, or `"xhigh"` (Opus 4.7 and 4.8, v2.1.111). Written automatically when you run `/effort low`, `/effort medium`, `/effort high`, or `/effort xhigh`. Supported on Opus 4.6, Sonnet 4.6, Opus 4.7, and Opus 4.8 (defaults to `high`). Unsupported levels fall back to the highest supported level on the active model | | `modelOverrides` | object | - | Map model picker entries to provider-specific IDs (e.g., Bedrock inference profile ARNs). Each key is a model picker entry name, each value is the provider model ID | **Example:** @@ -570,7 +574,7 @@ The `/model` command exposes an **effort level** control that adjusts how much r | Effort Level | Description | |-------------|-------------| | Max | Maximum reasoning depth, Opus 4.6 only | -| XHigh | Extended high reasoning depth, Opus 4.7 only (default on Opus 4.7 across all plans, v2.1.111) | +| XHigh | Extended high reasoning depth, Opus 4.7 and 4.8 (default on Opus 4.7 across all plans, v2.1.111; on Opus 4.8 it is available but the default is `high`, v2.1.154) | | High (default on Opus 4.6/Sonnet 4.6) | Full reasoning depth, best for complex tasks | | Medium | Balanced reasoning, good for everyday tasks | | Low | Minimal reasoning, fastest responses | @@ -580,7 +584,7 @@ The `/model` command exposes an **effort level** control that adjusts how much r 2. Or run `/model` → select a model → use **← →** arrow keys to adjust 3. The setting persists via the `effortLevel` key in `settings.json` -**Note:** Effort level is available for Opus 4.6, Sonnet 4.6, and Opus 4.7 on Max and Team plans. The default was changed from High to Medium in v2.1.68, then changed back to **High** for API-key, Bedrock/Vertex/Foundry, Team, and Enterprise users in v2.1.94. In v2.1.117, the default was also raised from `medium` to `high` for Pro/Max subscribers on Opus 4.6 and Sonnet 4.6, bringing all tiers into alignment on `high`. v2.1.111 introduced **`xhigh`** (Opus 4.7 only) and made it the default effort level on Opus 4.7 across all plans. As of v2.1.75, 1M context window for Opus 4.6 is available by default on Max, Team, and Enterprise plans. +**Note:** Effort level is available for Opus 4.6, Sonnet 4.6, Opus 4.7, and Opus 4.8 on Max and Team plans. The default was changed from High to Medium in v2.1.68, then changed back to **High** for API-key, Bedrock/Vertex/Foundry, Team, and Enterprise users in v2.1.94. In v2.1.117, the default was also raised from `medium` to `high` for Pro/Max subscribers on Opus 4.6 and Sonnet 4.6, bringing all tiers into alignment on `high`. v2.1.111 introduced **`xhigh`** (Opus 4.7 only at the time) and made it the default effort level on Opus 4.7 across all plans. **v2.1.154** added **Opus 4.8** as the latest Opus on the Anthropic API; it supports `xhigh` but defaults to `high`. As of v2.1.75, 1M context window for Opus 4.6 is available by default on Max, Team, and Enterprise plans. **Effort env propagation:** Inside skill files, use `${CLAUDE_EFFORT}` to reference the current effort level (v2.1.120). As of v2.1.133, the same `$CLAUDE_EFFORT` variable is also injected into the environment of Bash tool subprocesses and hook handlers, so shell scripts and hook commands can adapt their behavior based on the active effort tier without reading a separate config file. @@ -636,6 +640,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 | `false` | Prepend Claude's previous response as `#`-commented context when you open the external editor with `Ctrl+G`. Set to `true` to enable | +| `teammateDefaultModel` | string | `null` | Default model for [agent-team](https://code.claude.com/docs/en/agent-teams) teammates when the lead dispatches them. `null` inherits the lead's model. Listed under "Global config settings" on the official settings page | ### Workspace & Teams @@ -869,6 +874,8 @@ Set environment variables for all Claude Code sessions. | `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)* | +| `CLAUDE_CODE_DISABLE_WORKFLOWS` | Set to `1` to disable [dynamic workflows](https://code.claude.com/docs/en/workflows) (`/workflows`) and the bundled workflow slash commands. Env-var equivalent of the `disableWorkflows` setting | +| `CLAUDE_CODE_ENABLE_AUTO_MODE` | Set to `1` to enable [auto mode](https://code.claude.com/docs/en/permissions#auto-mode) on Bedrock/Vertex/Foundry for Opus 4.7 and Opus 4.8 (v2.1.158). On the Anthropic API auto mode is available without this flag *(in v2.1.158 changelog, not yet on official 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)* | @@ -1089,6 +1096,8 @@ Set environment variables for all Claude Code sessions. "maxSkillDescriptionChars": 1536, "skillListingBudgetFraction": 0.01, "disableAgentView": false, + "disableWorkflows": false, + "workflowKeywordTriggerEnabled": true, "syntaxHighlightingDisabled": false, "worktree": { @@ -1183,7 +1192,8 @@ Set environment variables for all Claude Code sessions. "env": { "NODE_ENV": "development", "CLAUDE_CODE_EFFORT_LEVEL": "medium", - "ANTHROPIC_BEDROCK_SERVICE_TIER": "priority" + "ANTHROPIC_BEDROCK_SERVICE_TIER": "priority", + "CLAUDE_CODE_ENABLE_AUTO_MODE": "1" } } ```