From f7290ff2c44d082d86c947c16a5aaf8aaabb8644 Mon Sep 17 00:00:00 2001 From: Shayan Rais Date: Sun, 26 Apr 2026 15:42:48 +0500 Subject: [PATCH] Document v2.1.119 settings, env vars, and behavior changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Settings additions: - prUrlTemplate (Attribution): URL template for the PR badge in commit attribution — supports self-hosted GitLab/Bitbucket/GitHub Enterprise - voice (object): full structure with enabled/mode/autoSubmit; mark legacy voiceEnabled as DEPRECATED alias Behavior updates: - auto permission mode: rewrite per official docs — drop the removed --enable-auto-mode flag, note inclusion in the default Shift+Tab cycle since v2.1.111 - blockedMarketplaces: note v2.1.119 enforcement of hostPattern/pathPattern matchers before any download touches the filesystem Env var additions: - CLAUDE_CODE_HIDE_CWD: hides CWD in startup logo banner (v2.1.119) CLI / docs additions: - claude plugin tag: marketplace plugin version tagging subcommand (v2.1.118) - MCP OAuth callout: RFC 9728 protected-resource discovery, no manual apiKeyHelper/headersHelper needed for compliant servers (v2.1.111) - Quick Reference example updated with prUrlTemplate Bump Last Updated badge and version header to v2.1.119. Co-Authored-By: Claude --- best-practice/claude-settings.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/best-practice/claude-settings.md b/best-practice/claude-settings.md index ef068d7..02a6b56 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-Apr%2024%2C%202026%2012%3A27%20AM%20PKT-white?style=flat&labelColor=555) ![Version](https://img.shields.io/badge/Claude_Code-v2.1.118-blue?style=flat&labelColor=555)
+![Last Updated](https://img.shields.io/badge/Last_Updated-Apr%2026%2C%202026%201%3A10%20PM%20PKT-white?style=flat&labelColor=555) ![Version](https://img.shields.io/badge/Claude_Code-v2.1.119-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.118, Claude Code exposes **60+ settings** and **175+ 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.119, Claude Code exposes **60+ settings** and **175+ environment variables** (use the `"env"` field in `settings.json` to avoid wrapper scripts). @@ -78,7 +78,8 @@ Within the managed tier, precedence is: server-managed > MDM/OS-level policies > | `fastModePerSessionOptIn` | boolean | `false` | Require users to opt in to fast mode each session | | `defaultShell` | string | `"bash"` | Default shell for input-box `!` commands. Accepts `"bash"` (default) or `"powershell"`. Setting `"powershell"` routes interactive `!` commands through PowerShell on Windows. Requires `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` (v2.1.84) | | `includeGitInstructions` | boolean | `true` | Include built-in commit and PR workflow instructions and the git status snapshot in Claude's system prompt. The `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` environment variable takes precedence over this setting when set | -| `voiceEnabled` | boolean | - | Enable push-to-talk voice dictation. Written automatically when you run `/voice`. Requires a Claude.ai account | +| `voice` | object | - | Voice dictation configuration. Object with three fields: `enabled` (boolean — push-to-talk on/off), `mode` (string — `"hold"` for hold-to-talk or `"tap"` for tap-to-toggle), and `autoSubmit` (boolean — submit transcript immediately when dictation ends). Written automatically when you run `/voice`. Requires a Claude.ai account (v2.1.118 expanded structure) | +| `voiceEnabled` | boolean | - | **DEPRECATED** — legacy alias for `voice.enabled`. Use the `voice` object instead to get `mode` and `autoSubmit` controls | | `showClearContextOnPlanAccept` | boolean | `false` | Show the "clear context" option on the plan accept screen. Set to `true` to restore the option (hidden by default since v2.1.81) | | `viewMode` | string | - | Default transcript view mode on startup: `"default"`, `"verbose"`, or `"focus"`. Overrides the sticky Ctrl+O selection when set | | `disableDeepLinkRegistration` | string | - | Set to `"disable"` to prevent Claude Code from registering the `claude-cli://` protocol handler with the operating system on startup. Deep links let external tools open a Claude Code session with a pre-filled prompt via `claude-cli://open?q=...`. The `q` parameter supports multi-line prompts using URL-encoded newlines (`%0A`). Useful in environments where protocol handler registration is restricted or managed separately | @@ -147,6 +148,7 @@ Customize attribution messages for git commits and pull requests. |-----|------|---------|-------------| | `attribution.commit` | string | Co-authored-by | Git commit attribution (supports trailers) | | `attribution.pr` | string | Generated message | Pull request description attribution | +| `prUrlTemplate` | string | - | URL template that controls how the "PR" badge in commit attribution links to the pull request UI. Supports placeholders for the repo host, owner, repo, and PR number. Useful for self-hosted GitLab/Bitbucket/GitHub Enterprise instances where the default `https://github.com/...` URL does not apply (v2.1.119) | | `includeCoAuthoredBy` | boolean | `true` | **DEPRECATED** - Use `attribution` instead | **Example:** @@ -244,7 +246,7 @@ Control what tools and operations Claude can perform. | `"acceptEdits"` | Auto-accept file edits without asking | | `"dontAsk"` | Auto-denies tools unless pre-approved via `/permissions` or `permissions.allow` rules | | `"bypassPermissions"` | Skip all permission checks (dangerous) | -| `"auto"` | Background classifier replaces manual prompts (`--enable-auto-mode`). Research preview — requires Team plan + Sonnet/Opus 4.6. Classifier auto-approves read-only and file edits; sends everything else through a safety check. Falls back to prompting after 3 consecutive or 20 total blocks. Configure with `autoMode` setting | +| `"auto"` | Auto-approves tool calls with background safety checks that verify actions align with your request. Research preview. Classifier auto-approves read-only and file edits; sends everything else through a safety check. Falls back to prompting after 3 consecutive or 20 total blocks. In the default `Shift+Tab` permission-mode cycle since v2.1.111 (the `--enable-auto-mode` flag was removed in v2.1.111 — start in this mode with `--permission-mode auto`). Configure with the `autoMode` setting | | `"plan"` | Read-only exploration mode | ### Tool Permission Syntax @@ -325,6 +327,8 @@ For the official hooks reference, see the [Claude Code Hooks Documentation](http Configure Model Context Protocol servers for extended capabilities. +> **OAuth (v2.1.111):** MCP servers that authenticate via OAuth follow [RFC 9728](https://datatracker.ietf.org/doc/rfc9728/) for protected-resource metadata discovery. Compliant servers expose authorization endpoints under `/.well-known/oauth-protected-resource`, and Claude Code completes the OAuth flow automatically — no manual `apiKeyHelper` or `headersHelper` script required for spec-conformant servers. + ### MCP Settings | Key | Type | Scope | Description | @@ -427,7 +431,7 @@ Configure Claude Code plugins and marketplaces. | `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)* | -| `blockedMarketplaces` | array | Managed only | Block specific plugin marketplaces | +| `blockedMarketplaces` | array | Managed only | Block specific plugin marketplaces. Each entry can match by source string, `hostPattern`, or `pathPattern` — as of v2.1.119 the `hostPattern` and `pathPattern` matchers are correctly enforced before any download touches the filesystem, so blocked marketplaces never reach disk | | `pluginTrustMessage` | string | Managed only | Custom message displayed when prompting users to trust plugins | **Marketplace source types:** `github`, `git`, `directory`, `hostPattern`, `settings`, `url`, `npm`, `file`. Use `source: 'settings'` to declare a small set of plugins inline without setting up a hosted marketplace repository. @@ -870,6 +874,7 @@ Set environment variables for all Claude Code sessions. | `CLAUDE_CODE_SCROLL_SPEED` | Mouse wheel scroll multiplier for fullscreen rendering. Increase for faster scrolling, decrease for finer control | | `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | Set to `1` to disable virtual scrolling in fullscreen rendering and render every message in the transcript. Use if scrolling in fullscreen mode shows blank regions where messages should appear | | `CLAUDE_CODE_DISABLE_MOUSE` | Set to `1` to disable mouse tracking in fullscreen rendering. Useful when mouse events interfere with terminal multiplexers or accessibility tools | +| `CLAUDE_CODE_HIDE_CWD` | Set to `1` to hide the current working directory in the Claude Code startup logo banner. Useful in screen recordings, demos, or shared sessions where the CWD path leaks information about the host or project layout (v2.1.119) | | `CLAUDE_CODE_ACCESSIBILITY` | Set to `1` to keep native terminal cursor visible for screen readers and accessibility tools | | `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | Set to `0` to disable syntax highlighting in diff output | | `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip automatic IDE extension installation (`1` to skip) | @@ -932,6 +937,7 @@ Set environment variables for all Claude Code sessions. | `/mcp` | Manage MCP servers | | `/hooks` | View configured hooks | | `/plugin` | Manage plugins | +| `claude plugin tag` | Tag a plugin version in a marketplace for distribution. Run from the marketplace repo with the plugin name and version (v2.1.118) | | `/keybindings` | Configure custom keyboard shortcuts | | `/skills` | View and manage skills | | `/permissions` | View and manage permission rules | @@ -1010,6 +1016,7 @@ Set environment variables for all Claude Code sessions. "commit": "Generated with Claude Code", "pr": "" }, + "prUrlTemplate": "https://gitlab.example.com/{owner}/{repo}/-/merge_requests/{number}", "statusLine": { "type": "command",