# Update Config > Use this skill to configure the Claude Code harness via settings.json. Automated behaviors ("from now on when X", "each time X", "whenever X", "before/after X") require hooks configured in settings.json - the harness executes these, not Claude, so memory/preferences cannot fulfill them. Also use for: permissions ("allow X", "add permission", "move permission to"), env vars ("set X=Y"), hook troubleshooting, or any changes to settings.json/settings.local.json files. Examples: "allow npm commands", "add bq permission to global settings", "move permission to user settings", "set DEBUG=true", "when claude stops show X". For simple settings like theme/model, suggest the /config command. - Skill: `gabrielmoreira/update-config` (Agent Skill) - Install (CLI): `npx skillmds@latest add gabrielmoreira/update-config` - Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/update-config/raw - Safety review: pending (external: skill-scanner PASS, skillspector WARNING) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/gabrielmoreira/update-config --- # Update Config Skill Modify Claude Code configuration by updating settings.json files. ## When Hooks Are Required (Not Memory) If the user wants something to happen automatically in response to an EVENT, they need a **hook** configured in settings.json. Memory/preferences cannot trigger automated actions. **These require hooks:** - "Before compacting, ask me what to preserve" → PreCompact hook - "After writing files, run prettier" → PostToolUse hook with Write|Edit matcher - "When I run bash commands, log them" → PreToolUse hook with Bash matcher - "Always run tests after code changes" → PostToolUse hook **Hook events:** PreToolUse, PostToolUse, PreCompact, PostCompact, Stop, Notification, SessionStart ## CRITICAL: Read Before Write **Always read the existing settings file before making changes.** Merge new settings with existing ones - never replace the entire file. ## CRITICAL: Use AskUserQuestion for Ambiguity When the user's request is ambiguous, use AskUserQuestion to clarify: - Which settings file to modify (user/project/local) - Whether to add to existing arrays or replace them - Specific values when multiple options exist ## Decision: /config command vs Direct Edit **Suggest the `/config` slash command** for these simple settings: - `theme`, `editorMode`, `verbose`, `model` - `language`, `alwaysThinkingEnabled` - `permissions.defaultMode` **Edit settings.json directly** for: - Hooks (PreToolUse, PostToolUse, etc.) - Complex permission rules (allow/deny arrays) - Environment variables - MCP server configuration - Plugin configuration ## Workflow 1. **Clarify intent** - Ask if the request is ambiguous 2. **Read existing file** - Use Read tool on the target settings file 3. **Merge carefully** - Preserve existing settings, especially arrays 4. **Edit file** - Use Edit tool (if file doesn't exist, ask user to create it first) 5. **Confirm** - Tell user what was changed ## Merging Arrays (Important!) When adding to permission arrays or hook arrays, **merge with existing**, don't replace: **WRONG** (replaces existing permissions): ```json { "permissions": { "allow": ["Bash(npm *)"] } } ``` **RIGHT** (preserves existing + adds new): ```json { "permissions": { "allow": [ "Bash(git *)", // existing "Edit(.claude)", // existing "Bash(npm *)" // new ] } } ``` ## Settings File Locations Choose the appropriate file based on scope: | File | Scope | Git | Use For | |------|-------|-----|---------| | `~/.claude/settings.json` | Global | N/A | Personal preferences for all projects | | `.claude/settings.json` | Project | Commit | Team-wide hooks, permissions, plugins | | `.claude/settings.local.json` | Project | Gitignore | Personal overrides for this project | Settings load in order: user → project → local (later overrides earlier). ## Settings Schema Reference ### Permissions ```json { "permissions": { "allow": ["Bash(npm *)", "Edit(.claude)", "Read"], "deny": ["Bash(rm -rf *)"], "ask": ["Edit(//etc/*)"], "defaultMode": "default" | "plan" | "acceptEdits" | "dontAsk", "additionalDirectories": ["/extra/dir"] } } ``` **Permission Rule Syntax:** - Exact match: `"Bash(npm run test)"` - Prefix wildcard: `"Bash(git *)"` - matches `git`, `git status`, `git commit`, etc. - Tool only: `"Read"` - allows all Read operations ### Environment Variables ```json { "env": { "DEBUG": "true", "MY_API_KEY": "value" } } ``` ### Model & Agent ```json { "model": "sonnet", // or "fable", "opus", "haiku", full model ID "agent": "agent-name", "alwaysThinkingEnabled": true } ``` ### Attribution (Commits & PRs) ```json { "attribution": { "commit": "Custom commit trailer text", "pr": "Custom PR description text" } } ``` Set `commit` or `pr` to empty string `""` to hide that attribution. ### MCP Server Management ```json { "enableAllProjectMcpServers": true, "enabledMcpjsonServers": ["server1", "server2"], "disabledMcpjsonServers": ["blocked-server"] } ``` ### Plugins ```json { "enabledPlugins": { "formatter@anthropic-tools": true } } ``` Plugin syntax: `plugin-name@source` where source is `claude-code-marketplace`, `claude-plugins-official`, or `builtin`. ### Other Settings - `language`: Preferred response language (e.g., "japanese") - `cleanupPeriodDays`: Days to keep transcripts before automatic cleanup (default: 30; minimum 1) - `respectGitignore`: Whether to respect .gitignore (default: true) - `spinnerTipsEnabled`: Show tips in spinner - `timeFormat`: Clock format for times shown in the UI: "auto" (default), "12-hour", "24-hour", "24-hour-utc", or a strftime pattern such as "%H:%M" - `timeZone`: IANA time zone for times shown in the UI, e.g. "UTC" (default: system time zone) - `spinnerVerbs`: Customize spinner verbs (`{ "mode": "append" | "replace", "verbs": [...] }`) - `spinnerTipsOverride`: Override spinner tips (`{ "excludeDefault": true, "tips": ["Custom tip"] }`) - `syntaxHighlightingDisabled`: Disable diff highlighting ## Hooks Configuration Hooks run commands at specific points in Claude Code's lifecycle. ### Hook Structure ```json { "hooks": { "EVENT_NAME": [ { "matcher": "ToolName|OtherTool", "hooks": [ { "type": "command", "command": "your-command-here", "timeout": 60, "statusMessage": "Running..." } ] } ] } } ``` ### Hook Events | Event | Matcher | Purpose | |-------|---------|---------| | PermissionRequest | Tool name | Run before permission prompt | | PreToolUse | Tool name | Run before tool, can block | | PostToolUse | Tool name | Run after successful tool | | PostToolUseFailure | Tool name | Run after tool fails | | Notification | Notification type | Run on notifications | | Stop | - | Run when Claude stops (including clear, resume, compact) | | PreCompact | "manual"/"auto" | Before compaction | | PostCompact | "manual"/"auto" | After compaction (receives summary) | | UserPromptSubmit | - | When user submits | | SessionStart | - | When session starts | **Common tool matchers:** `Bash`, `Write`, `Edit`, `Read`, `Glob`, `Grep` ### Hook Types **1. Command Hook** - Runs a shell command: ```json { "type": "command", "command": "prettier --write $FILE", "timeout": 30 } ``` **2. Prompt Hook** - Evaluates a condition with LLM: ```json { "type": "prompt", "prompt": "Is this safe? $ARGUMENTS" } ``` Only available for tool events: PreToolUse, PostToolUse, PermissionRequest. **3. Agent Hook** - Runs an agent with tools: ```json { "type": "agent", "prompt": "Verify tests pass: $ARGUMENTS" } ``` Only available for tool events: PreToolUse, PostToolUse, PermissionRequest. ### Hook Input (stdin JSON) ```json { "session_id": "abc123", "tool_name": "Write", "tool_input": { "file_path": "/path/to/file.txt", "content": "..." }, "tool_response": { "success": true } // PostToolUse only } ``` ### Hook JSON Output Hooks can return JSON to control behavior: ```json { "systemMessage": "Warning shown to user in UI", "continue": false, "stopReason": "Message shown when blocking", "suppressOutput": false, "decision": "block", "reason": "Explanation for decision", "hookSpecificOutput": { "hookEventName": "PostToolUse", "additionalContext": "Context injected back to model" } } ``` **Fields:** - `systemMessage` - Display a message to the user (all hooks) - `continue` - Set to `false` to block/stop (default: true) - `stopReason` - Message shown when `continue` is false - `suppressOutput` - Hide stdout from transcript (default: false) - `decision` - "block" for PostToolUse/Stop/UserPromptSubmit hooks (deprecated for PreToolUse, use hookSpecificOutput.permissionDecision instead) - `reason` - Explanation for decision - `hookSpecificOutput` - Event-specific output (must include `hookEventName`): - `additionalContext` - Text injected into model context - `permissionDecision` - "allow", "deny", or "ask" (PreToolUse only) - `permissionDecisionReason` - Reason for the permission decision (PreToolUse only) - `updatedInput` - Modified tool input (PreToolUse only) ### Common Patterns **Auto-format after writes:** ```json { "hooks": { "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true" }] }] } } ``` **Log all bash commands:** ```json { "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt" }] }] } } ``` **Stop hook that displays message to user:** Command must output JSON with `systemMessage` field: ```bash # Example command that outputs: {"systemMessage": "Session complete!"} echo '{"systemMessage": "Session complete!"}' ``` **Run tests after code changes:** ```json { "hooks": { "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path // .tool_response.filePath' | grep -E '\\.(ts|js)$' && npm test || true" }] }] } } ``` ## Constructing a Hook (with verification) Given an event, matcher, target file, and desired behavior, follow this flow. Each step catches a different failure class — a hook that silently does nothing is worse than no hook. 1. **Dedup check.** Read the target file. If a hook already exists on the same event+matcher, show the existing command and ask: keep it, replace it, or add alongside. 2. **Construct the command for THIS project — don't assume.** The hook receives JSON on stdin. Build a command that: - Extracts any needed payload safely — use `jq -r` into a quoted variable or `{ read -r f; ... "$f"; }`, NOT unquoted `| xargs` (splits on spaces) - Invokes the underlying tool the way this project runs it (npx/bunx/yarn/pnpm? Makefile target? globally-installed?) - Skips inputs the tool doesn't handle (formatters often have `--ignore-unknown`; if not, guard by extension) - Stays RAW for now — no `|| true`, no stderr suppression. You'll wrap it after the pipe-test passes. 3. **Pipe-test the raw command.** Synthesize the stdin payload the hook will receive and pipe it directly: - `Pre|PostToolUse` on `Write|Edit`: `echo '{"tool_name":"Edit","tool_input":{"file_path":""}}' | ` - `Pre|PostToolUse` on `Bash`: `echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ` - `Stop`/`UserPromptSubmit`/`SessionStart`: most commands don't read stdin, so `echo '{}' | ` suffices Check exit code AND side effect (file actually formatted, test actually ran). If it fails you get a real error — fix (wrong package manager? tool not installed? jq path wrong?) and retest. Once it works, wrap with `2>/dev/null || true` (unless the user wants a blocking check). 4. **Write the JSON.** Merge into the target file (schema shape in the "Hook Structure" section above). If this creates `.claude/settings.local.json` for the first time, add it to .gitignore — the Write tool doesn't auto-gitignore it. 5. **Validate syntax + schema in one shot:** `jq -e '.hooks.[] | select(.matcher == "") | .hooks[] | select(.type == "command") | .command' ` Exit 0 + prints your command = correct. Exit 4 = matcher doesn't match. Exit 5 = malformed JSON or wrong nesting. A broken settings.json silently disables ALL settings from that file — fix any pre-existing malformation too. 6. **Prove the hook fires** — only for `Pre|PostToolUse` on a matcher you can trigger in-turn (`Write|Edit` via Edit, `Bash` via Bash). `Stop`/`UserPromptSubmit`/`SessionStart` fire outside this turn — skip to step 7. For a **formatter** on `PostToolUse`/`Write|Edit`: introduce a detectable violation via Edit (two consecutive blank lines, bad indentation, missing semicolon — something this formatter corrects; NOT trailing whitespace, Edit strips that before writing), re-read, confirm the hook **fixed** it. For **anything else**: temporarily prefix the command in settings.json with `echo "$(date) hook fired" >> /tmp/claude-hook-check.txt; `, trigger the matching tool (Edit for `Write|Edit`, a harmless `true` for `Bash`), read the sentinel file. **Always clean up** — revert the violation, strip the sentinel prefix — whether the proof passed or failed. **If proof fails but pipe-test passed and `jq -e` passed**: the settings watcher isn't watching `.claude/` — it only watches directories that had a settings file when this session started. The hook is written correctly. Tell the user to open `/hooks` once (reloads config) or restart — you can't do this yourself; `/hooks` is a user UI menu and opening it ends this turn. 7. **Handoff.** Tell the user the hook is live (or needs `/hooks`/restart per the watcher caveat). Point them at `/hooks` to review, edit, or disable it later. The UI only shows "Ran N hooks" if a hook errors or is slow — silent success is invisible by design. ## Example Workflows ### Adding a Hook User: "Format my code after Claude writes it" 1. **Clarify**: Which formatter? (prettier, gofmt, etc.) 2. **Read**: `.claude/settings.json` (or create if missing) 3. **Merge**: Add to existing hooks, don't replace 4. **Result**: ```json { "hooks": { "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true" }] }] } } ``` ### Adding Permissions User: "Allow npm commands without prompting" 1. **Read**: Existing permissions 2. **Merge**: Add `Bash(npm *)` to allow array 3. **Result**: Combined with existing allows ### Environment Variables User: "Set DEBUG=true" 1. **Decide**: User settings (global) or project settings? 2. **Read**: Target file 3. **Merge**: Add to env object ```json { "env": { "DEBUG": "true" } } ``` ## Common Mistakes to Avoid 1. **Replacing instead of merging** - Always preserve existing settings 2. **Wrong file** - Ask user if scope is unclear 3. **Invalid JSON** - Validate syntax after changes 4. **Forgetting to read first** - Always read before write ## Troubleshooting Hooks If a hook isn't running: 1. **Check the settings file** - Read ~/.claude/settings.json or .claude/settings.json 2. **Verify JSON syntax** - Invalid JSON silently fails 3. **Check the matcher** - Does it match the tool name? (e.g., "Bash", "Write", "Edit") 4. **Check hook type** - Is it "command", "prompt", or "agent"? 5. **Test the command** - Run the hook command manually to see if it works 6. **Use --debug** - Run `claude --debug` to see hook execution logs ## Full Settings JSON Schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "$schema": { "description": "JSON Schema reference for Claude Code settings", "type": "string" }, "apiKeyHelper": { "description": "Path to a script that outputs authentication values", "type": "string" }, "proxyAuthHelper": { "description": "Shell command that outputs a Proxy-Authorization header value (EAP)", "type": "string" }, "awsCredentialExport": { "description": "Path to a script that exports AWS credentials", "type": "string" }, "awsAuthRefresh": { "description": "Path to a script that refreshes AWS authentication", "type": "string" }, "gcpAuthRefresh": { "description": "Command to refresh GCP authentication (e.g., gcloud auth application-default login)", "type": "string" }, "processWrapper": { "description": "Corporate launcher argv prefix for the background-agent supervisor, the sessions and workers it hosts, and the other covered background processes listed in the Claude Code corporate-launcher documentation. Equivalent to the CLAUDE_CODE_PROCESS_WRAPPER environment variable, which takes precedence when set. Honored from managed settings, a --settings/SDK-supplied settings file, and user settings, in that precedence order; project and local settings are ignored.", "type": "string" }, "policyHelper": { "description": "Executable that computes managed settings at startup. Honored only from admin-controlled policy sources.", "type": "object", "properties": { "path": { "description": "Absolute path to the helper executable", "type": "string" }, "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 9007199254740991 }, "refreshIntervalMs": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "integer", "minimum": 60000, "maximum": 9007199254740991 } ] } }, "required": [ "path" ] }, "fileSuggestion": { "description": "Custom file suggestion configuration for @ mentions", "type": "object", "properties": { "type": { "type": "string", "const": "command" }, "command": { "type": "string" } }, "required": [ "type", "command" ] }, "respectGitignore": { "description": "Whether file picker should respect .gitignore files (default: true). Note: .ignore files are always respected.", "type": "boolean" }, "cleanupPeriodDays": { "description": "Number of days to retain chat transcripts before automatic cleanup (default: 30). Minimum 1. Use a large value for long retention; use --no-session-persistence to disable transcript writes entirely.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "desktopSessionCleanupPeriodDays": { "description": "Retention ceiling in days for session transcripts created or last written by a desktop-host surface (Claude Desktop, Cowork), which are otherwise exempt from the cleanupPeriodDays sweep. 0 (the default) means no ceiling: such transcripts are kept until deleted another way. Unlike cleanupPeriodDays, 0 is allowed because this setting never disables writes — it only bounds an exemption from deletion. The ceiling is a hard cap: it also bounds an active archive grace, so the grace window of a release marker never keeps files past the ceiling. Ignored when cleanupPeriodDays is managed by org policy. A ceiling at or below cleanupPeriodDays effectively disables the exemption: those transcripts age out on the regular cleanupPeriodDays schedule, so the effective retention is whichever of the two periods is longer.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "syncClaudeAiSkills": { "description": "Set to false to turn off syncing of the skills you have enabled on claude.ai. In your user settings (or managed settings): nothing more is downloaded, previously synced skills (~/.claude/skills/synced) can no longer be run, are hidden from every session started afterwards, and are moved to ~/.claude/skills/.trash at the next launch (deleted after cleanupPeriodDays; re-downloaded, not restored, if you re-enable). In .claude/settings.local.json or --settings: downloads stop and synced skills are blocked and hidden for sessions in that workspace or invocation only (nothing is moved). Not read from project settings (.claude/settings.json). Only false is honored — the feature is enabled server-side for your account, so setting true does not turn it on early. While it is on, synced skills are available in every session, re-synced every 10 minutes, and removed when you disable them on claude.ai. Only applies when signed in with your Claude account.", "type": "boolean" }, "syncClaudeAiPlugins": { "description": "Set to false to turn off syncing of the plugins you have enabled on claude.ai. In your user settings (or managed settings): nothing more is downloaded, previously synced plugins (~/.claude/plugins/synced) are hidden from every session started afterwards and moved to ~/.claude/plugins/.trash at the next launch (deleted after cleanupPeriodDays; re-downloaded, not restored, if you re-enable). In .claude/settings.local.json or --settings: downloads stop and synced plugins are hidden for sessions in that workspace or invocation only (nothing is moved). Not read from project settings (.claude/settings.json). Only false is honored — the feature is enabled server-side for your account, so setting true does not turn it on early. While it is on, synced plugins load in every session like plugins you installed yourself (a plugin you installed with the same name takes precedence), are re-synced at each launch, and are removed when you disable them on claude.ai. Only applies when signed in with your Claude account.", "type": "boolean" }, "skillListingMaxDescChars": { "description": "Per-skill description character cap in the skill listing sent to Claude (default: 1536). Descriptions longer than this are truncated. Raise to opt in to higher per-turn context cost.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "skillListingBudgetFraction": { "description": "Fraction of the context window (in characters) reserved for the skill listing sent to Claude (default: 0.01 = 1%). When the listing exceeds this, descriptions are shortened to fit. Raise to opt in to higher per-turn context cost.", "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "wslInheritsWindowsSettings": { "description": "When set to true in either admin-only Windows source — the HKLM SOFTWARE/Policies/ClaudeCode registry key or C:/Program Files/ClaudeCode/managed-settings.json — WSL reads managed settings from the full Windows policy chain (HKLM, C:/Program Files/ClaudeCode via DrvFs, HKCU) in addition to /etc/claude-code. Windows sources take priority. The flag is also required in HKCU itself for HKCU policy to apply on WSL (double opt-in: admin enables the chain, user confirms HKCU). On native Windows the flag has no effect.", "type": "boolean" }, "env": { "description": "Environment variables to set for Claude Code sessions", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "attribution": { "description": "Customize attribution text for commits and PRs. Each field defaults to the standard Claude Code attribution if not set.", "type": "object", "properties": { "commit": { "description": "Attribution text for git commits, including any trailers. Empty string hides attribution.", "type": "string" }, "pr": { "description": "Attribution text for pull request descriptions. Empty string hides attribution.", "type": "string" }, "sessionUrl": { "description": "Whether to append the claude.ai session link to commits and PRs created from web or Remote Control sessions (default: true). Set to false to omit the Claude-Session trailer and PR-body link.", "type": "boolean" } }, "additionalProperties": {} }, "includeCoAuthoredBy": { "description": "Deprecated: Use attribution instead. Whether to include Claude's co-authored by attribution in commits and PRs (defaults to true)", "type": "boolean" }, "includeGitInstructions": { "description": "Include built-in commit and PR workflow instructions in Claude's system prompt (default: true)", "type": "boolean" }, "permissions": { "description": "Tool usage permissions configuration", "type": "object", "properties": { "allow": { "description": "List of permission rules for allowed operations", "type": "array", "items": { "type": "string" } }, "deny": { "description": "List of permission rules for denied operations", "type": "array", "items": { "type": "string" } }, "ask": { "description": "List of permission rules that should always prompt for confirmation", "type": "array", "items": { "type": "string" } }, "defaultMode": { "description": "Default permission mode when Claude Code needs access ('manual' is accepted as an alias for 'default')", "type": "string", "enum": [ "acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "plan" ] }, "disableBypassPermissionsMode": { "description": "Disable the ability to bypass permission prompts", "type": "string", "enum": [ "disable" ] }, "blockReadsOutsideWorkingDirectories": { "description": "Refuse file-tool reads (Read, Grep, Glob, LSP) outside the working directories in every permission mode; true in any settings source wins. Also set when the user picks \"block\" on the one-time auto-mode prompt for a read outside the working directories.", "type": "boolean" }, "disableAutoMode": { "description": "Disable auto mode", "type": "string", "enum": [ "disable" ] }, "additionalDirectories": { "description": "Additional directories to include in the permission scope", "type": "array", "items": { "type": "string" } } }, "additionalProperties": {} }, "model": { "description": "Override the default model used by Claude Code", "type": "string" }, "fallbackModel": { "description": "Fallback model(s) tried in order when the primary model is overloaded or unavailable. Each element accepts a model name or alias; \"default\" expands to the default model. CLI --fallback-model takes precedence.", "type": "array", "items": { "type": "string" } }, "availableModels": { "description": "Allowlist of models that users can select. Accepts family aliases (\"opus\" allows any opus version), version prefixes (\"opus-4-5\" allows only that version), and full model IDs. If undefined, all models are available. If empty array, only the default model is available. Typically set in managed settings by enterprise administrators.", "type": "array", "items": { "type": "string" } }, "enforceAvailableModels": { "description": "When true and availableModels is a non-empty array, the Default model selection is also constrained: if the default model for the user tier is not in availableModels, Default resolves to the first allowed availableModels entry instead. Has no effect when availableModels is unset or an empty array. Typically set in managed settings by enterprise administrators.", "type": "boolean" }, "modelOverrides": { "description": "Override mapping from Anthropic model ID (e.g. \"claude-opus-4-6\") to provider-specific model ID (e.g. a Bedrock inference profile ARN). Typically set in managed settings by enterprise administrators.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "modelPicker": { "description": "Curate the /model picker: an ordered list of models with your own labels, independent of the built-in lineup and of Claude Code releases. availableModels still applies to these rows. Honored from managed, --settings/SDK, and user settings only (not from a project checkout); the highest-precedence of those that defines modelPicker wins outright (no merging across sources). Typically set in managed settings by enterprise administrators.", "type": "object", "properties": { "options": { "description": "Rows to show in the /model picker, in order.", "type": "array", "items": { "type": "object", "properties": { "model": { "description": "Model to select, taken verbatim: an alias (\"opus\"), an Anthropic model ID, or a provider-format ID (Vertex, Bedrock, gateway). Same values --model accepts.", "type": "string" }, "label": { "description": "Row title. Defaults to the model name.", "type": "string" }, "description": { "description": "Row subtitle. Defaults to a generic description.", "type": "string" }, "behavesAs": { "description": "For a model this version of Claude Code does not know: the ID of a model it does know (e.g. \"claude-opus-4-8\") whose client-side handling — prompt profile, capability and effort defaults — applies to it. Changes neither the row's label nor the model ID sent. Without it, a model-catalog row for a model this version does not know is not offered until Claude Code is updated.", "type": "string" } }, "required": [ "model" ] } }, "replaceBuiltInOptions": { "description": "When true, the picker shows only the Default row and these options — the built-in lineup, gateway-discovered models and ANTHROPIC_CUSTOM_MODEL_OPTION are hidden. When false or unset, these options are added after the built-in lineup.", "type": "boolean" } }, "required": [ "options" ] }, "modelPricing": { "description": "Price usage at your organization's contracted rates instead of list price. Affects every spend figure Claude Code reports — /cost, the status line, the SDK total_cost_usd, --max-budget-usd, and the OpenTelemetry cost metric and events — which remain USD estimates, not an invoice (the per-Mtok price labels in /model stay at list). \"overrides\" maps a model ID to its USD-per-million-token rates (input, output, cacheRead, cacheWrite — all four required, each 0 to 10000; cacheWrite prices both 5-minute and 1-hour cache writes). A matching row is charged exactly as written; fast-mode and US-data-residency surcharges are not added on top. A key Claude Code itself uses for a built-in model — its ID such as \"claude-sonnet-4-6\", or its first-party, Bedrock (any or no region prefix), Vertex or Foundry ID — covers every dated and provider form of that model; any other key — a gateway model alias, or a spelling Claude Code does not itself use — matches that model ID only (case-insensitive), and such an exact match wins over a built-in row. On Bedrock an application inference profile is matched by its backing model. An invalid row or multiplier is reported and skipped; the rest still apply. \"multiplier\" in (0, 1] scales every computed cost, overridden or not (0.85 = 85% of the price). Only honored from managed settings (server-managed, MDM / OS policy, or managed-settings.json), or — when none of those sets it — when supplied by a host application that manages the model provider; ignored in user, project, local and --settings sources.", "type": "object", "properties": { "multiplier": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "overrides": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "input": { "type": "number", "minimum": 0, "maximum": 10000 }, "output": { "type": "number", "minimum": 0, "maximum": 10000 }, "cacheRead": { "type": "number", "minimum": 0, "maximum": 10000 }, "cacheWrite": { "type": "number", "minimum": 0, "maximum": 10000 } }, "required": [ "input", "output", "cacheRead", "cacheWrite" ] } } } }, "enableAllProjectMcpServers": { "description": "Whether to automatically approve all MCP servers in the project", "type": "boolean" }, "enabledMcpjsonServers": { "description": "List of approved MCP servers from .mcp.json", "type": "array", "items": { "type": "string" } }, "disabledMcpjsonServers": { "description": "List of rejected MCP servers from .mcp.json", "type": "array", "items": { "type": "string" } }, "disableClaudeAiConnectors": { "description": "When true in any settings source, claude.ai MCP cloud connectors are not auto-fetched or connected. Only gates auto-fetched connectors — a claudeai-proxy server passed explicitly (e.g. via --mcp-config or the SDK mcpServers option) still follows the normal MCP config trust flow. Any-source-true wins: a project can opt out, but a project-level false cannot override a user-level true.", "type": "boolean" }, "skillOverrides": { "description": "Per-skill listing overrides keyed by skill name. \"name-only\" lists the skill without its description; \"user-invocable-only\" hides it from the model but keeps /name; \"off\" hides it from both. Absent = on.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": [ "on", "name-only", "user-invocable-only", "off" ] } }, "disableBundledSkills": { "description": "Disable the skills and workflows that ship with Claude Code: bundled skills and workflows are removed entirely; built-in slash commands stay typable but are hidden from the model. Plugins, .claude/skills/, and .claude/commands/ are unaffected. Equivalent to CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1.", "type": "boolean" }, "managedMcpServers": { "description": "MCP servers the organization provides to every user, keyed by server name, each with the .mcp.json entry shape; only \"http\" and \"sse\" servers are accepted (nothing that names a program to run, no ${VAR} references). Honored from managed settings only; users cannot remove them, deniedMcpServers still applies, and they need no allowedMcpServers entry. Not read in Claude Desktop's Code tab on a third-party deployment or in Cowork sessions, where Claude Desktop supplies and locks the session's MCP servers itself.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "allowedMcpServers": { "description": "Enterprise allowlist of the MCP servers users may use. Governs servers users add (user, project and local config, --mcp-config, agent frontmatter, plugins, claude.ai connectors); servers the organization itself delivers (managedMcpServers, and managed-mcp.json entries that use no ${VAR} expansion) are allowed without being listed; a managed-mcp.json entry that uses ${VAR} expansion is still checked against this list. If undefined, all servers are allowed. If empty array, users can use no servers of their own. Denylist takes precedence - if a server is on both lists, it is denied.", "type": "array", "items": { "type": "object", "properties": { "serverName": { "description": "Name of the MCP server that users are allowed to configure", "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" }, "serverCommand": { "description": "Command array [command, ...args] to match exactly for allowed stdio servers", "minItems": 1, "type": "array", "items": { "type": "string" } }, "serverUrl": { "description": "URL pattern with wildcard support (e.g., \"https://*.example.com/*\") for allowed remote MCP servers", "type": "string" } } } }, "deniedMcpServers": { "description": "Enterprise denylist of MCP servers that are explicitly blocked. If a server is on the denylist, it will be blocked across all scopes including enterprise. Denylist takes precedence over allowlist - if a server is on both lists, it is denied.", "type": "array", "items": { "type": "object", "properties": { "serverName": { "description": "Name of the MCP server that is explicitly blocked", "type": "string", "minLength": 1 }, "serverCommand": { "description": "Command array [command, ...args] to match exactly for blocked stdio servers", "minItems": 1, "type": "array", "items": { "type": "string" } }, "serverUrl": { "description": "URL pattern with wildcard support (e.g., \"https://*.example.com/*\") for blocked remote MCP servers", "type": "string" } } } }, "hooks": { "description": "Custom commands to run before/after tool executions", "type": "object", "propertyNames": { "type": "string", "enum": [ "PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PreModelSwitch", "PostModelSwitch", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "DirectoryAdded", "MessageDisplay" ] }, "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "matcher": { "description": "String pattern to match (e.g. tool names like \"Write\")", "type": "string" }, "hooks": { "description": "List of hooks to execute when the matcher matches", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Shell command hook type", "type": "string", "const": …(truncated)