> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/jackdog668/claude-code/llms.txt
> Use this file to discover all available pages before exploring further.
# Settings
> Configure Claude Code behavior through settings files, the claude config command, CLI flags, and environment variables.
Claude Code reads configuration from a layered set of settings sources. Each source overrides the previous one, giving you fine-grained control from user-wide defaults down to per-project and runtime overrides.
## Settings hierarchy
Settings are loaded from five sources, in order of increasing precedence:
| Source | Location | Description |
| ----------------- | ----------------------------- | --------------------------------------------------- |
| `userSettings` | `~/.claude/settings.json` | Global settings for all projects |
| `projectSettings` | `.claude/settings.json` | Shared project settings (commit to version control) |
| `localSettings` | `.claude/settings.local.json` | Project-local settings (gitignored) |
| `flagSettings` | `--settings` CLI flag | Settings passed at launch |
| `policySettings` | `managed-settings.json` | Enterprise-managed settings (always applied) |
Later sources override earlier ones. `policySettings` and `flagSettings` are always included regardless of the `--setting-sources` flag.
`policySettings` (managed settings) always take precedence and cannot be overridden by users. Enterprise administrators use this to enforce organization-wide policy.
### Settings file format
Settings files are JSON. You can add the JSON Schema reference for editor autocompletion:
```json settings.json theme={null}
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"model": "claude-opus-4-5",
"permissions": {
"defaultMode": "acceptEdits"
}
}
```
## The `claude config` command
Run `/config` inside a Claude Code session to open the interactive settings UI. This opens the **Config** tab of the settings panel where you can view and edit all settings interactively.
## Key settings
Override the default model used by Claude Code.
```json theme={null}
{ "model": "claude-opus-4-5" }
```
Configure tool permission rules. See the [Permissions](/configuration/permissions) page for full details.
```json theme={null}
{
"permissions": {
"defaultMode": "acceptEdits",
"allow": ["Bash(git:*)", "FileEdit"],
"deny": ["Bash(rm -rf:*)"]
}
}
```
Sub-fields:
* `allow` — permission rules for automatically allowed operations
* `deny` — permission rules for automatically denied operations
* `ask` — permission rules that always prompt for confirmation
* `defaultMode` — default permission mode (`default`, `acceptEdits`, `bypassPermissions`, `dontAsk`, `plan`)
* `disableBypassPermissionsMode` — set to `"disable"` to prevent bypass mode
* `additionalDirectories` — additional directories to include in the permission scope
Environment variables to inject into every Claude Code session.
```json theme={null}
{
"env": {
"NODE_ENV": "development",
"MY_API_KEY": "..."
}
}
```
Custom shell commands to run before or after tool executions. See the hooks documentation for the full schema.
```json theme={null}
{
"hooks": {
"PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "echo running bash" }] }]
}
}
```
Number of days to retain chat transcripts. Defaults to 30. Setting to `0` disables session persistence entirely — no transcripts are written and existing ones are deleted at startup.
```json theme={null}
{ "cleanupPeriodDays": 7 }
```
Whether to include Claude's co-authored-by attribution in commits and pull requests. Defaults to `true`. Deprecated — use `attribution` instead.
Customize attribution text for commits and PRs.
```json theme={null}
{
"attribution": {
"commit": "Co-authored-by: Claude ",
"pr": ""
}
}
```
Set either field to an empty string to hide attribution for that context.
Include built-in commit and PR workflow instructions in Claude's system prompt. Defaults to `true`.
Preferred language for Claude responses and voice dictation, e.g. `"japanese"` or `"spanish"`.
```json theme={null}
{ "language": "japanese" }
```
Controls the output style for assistant responses.
```json theme={null}
{ "outputStyle": "concise" }
```
Default shell for input-box `!` commands. Accepts `"bash"` or `"powershell"`. Defaults to `"bash"` on all platforms.
```json theme={null}
{ "defaultShell": "bash" }
```
Set to `true` to disable syntax highlighting in diffs.
When `false`, extended thinking is disabled. When absent or `true`, thinking is enabled automatically for supported models.
Persisted effort level for supported models. Accepts `"low"`, `"medium"`, or `"high"`.
```json theme={null}
{ "effortLevel": "high" }
```
Whether the file picker respects `.gitignore` files. Defaults to `true`. Note that `.ignore` files are always respected regardless of this setting.
Path to a script that outputs authentication values for the Claude API.
```json theme={null}
{ "apiKeyHelper": "/usr/local/bin/my-auth-helper" }
```
When `true`, disables all hooks and `statusLine` execution.
Sandbox runtime configuration. See [Permissions — Sandbox mode](/configuration/permissions#sandbox-mode) for details.
Git worktree configuration for the `--worktree` flag.
```json theme={null}
{
"worktree": {
"symlinkDirectories": ["node_modules", ".cache"],
"sparsePaths": ["packages/my-app"]
}
}
```
* `symlinkDirectories` — directories to symlink from the main repository into worktrees to avoid disk bloat.
* `sparsePaths` — directories to include when creating worktrees via `git sparse-checkout` (cone mode).
## The `--settings` flag
Pass settings at launch time without editing a file. You can provide either a path to a JSON file or an inline JSON string.
```bash settings file path theme={null}
claude --settings /path/to/my-settings.json
```
```bash inline JSON theme={null}
claude --settings '{"model":"claude-opus-4-5","permissions":{"defaultMode":"acceptEdits"}}'
```
Settings supplied via `--settings` are loaded as `flagSettings` and override user, project, and local settings, but are overridden by policy settings.
## The `--setting-sources` flag
By default, Claude Code loads user, project, and local settings. Use `--setting-sources` to restrict which file-based sources are loaded. `policySettings` and `flagSettings` are always included.
```bash theme={null}
# Load only user settings (skip project and local)
claude --setting-sources user
# Load user and project settings only (skip local)
claude --setting-sources user,project
# Load no file-based settings (only policy and flag)
claude --setting-sources ""
```
Valid source names: `user`, `project`, `local`.
## Environment variable overrides
Some behaviors can be controlled through environment variables. Variables relevant to settings:
| Variable | Description |
| ----------------------------------- | -------------------------------------------------------------------------- |
| `CLAUDE_CONFIG_DIR` | Override the Claude configuration home directory (defaults to `~/.claude`) |
| `CLAUDE_CODE_USE_SANDBOX` | Enable the sandbox runtime for Bash tool execution |
| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | Disable loading skills from managed (policy) settings |
## MDM / managed settings
Enterprise administrators can deploy settings through two mechanisms:
Place a `managed-settings.json` file in the platform-specific managed path. This file provides organization-wide defaults.
Place additional `.json` files in the `managed-settings.d/` drop-in directory. Files are merged in alphabetical order. Later files take precedence, following the systemd/sudoers convention — separate teams can ship independent policy fragments (e.g. `10-otel.json`, `20-security.json`) without coordinating edits to a single file.
Both the base file and drop-in files are merged together before being applied as `policySettings`. Managed settings always take final precedence over all user-editable sources.
Managed settings cannot be overridden by users. Settings such as `allowManagedPermissionRulesOnly`, `allowManagedHooksOnly`, and `disableBypassPermissionsMode` are only effective when placed in managed settings.
### Enterprise-only settings
The following settings are intended for managed settings and enterprise administrators:
| Setting | Description |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `availableModels` | Allowlist of models users can select. If empty array, only the default model is available. |
| `allowedMcpServers` | Enterprise allowlist of MCP servers. If empty array, no servers are allowed. |
| `deniedMcpServers` | Enterprise denylist of MCP servers. Denylist takes precedence over allowlist. |
| `allowManagedHooksOnly` | When `true`, only hooks from managed settings run. |
| `allowManagedPermissionRulesOnly` | When `true`, only permission rules from managed settings are respected. |
| `allowManagedMcpServersOnly` | When `true`, `allowedMcpServers` is only read from managed settings. |
| `strictPluginOnlyCustomization` | Restrict customization surfaces to plugins only. Accepts `true` (all surfaces) or an array of surface names: `"skills"`, `"agents"`, `"hooks"`, `"mcp"`. |
| `disableBypassPermissionsMode` | Set to `"disable"` to prevent users from entering bypass permissions mode. |
| `forceLoginMethod` | Force a login method: `"claudeai"` for Claude Pro/Max, `"console"` for Console billing. |
| `forceLoginOrgUUID` | Organization UUID to include in OAuth login. |
| `skipWebFetchPreflight` | Skip the WebFetch blocklist check for restrictive enterprise network environments. |
| `strictKnownMarketplaces` | Allowlist of permitted marketplace sources. |
| `blockedMarketplaces` | Blocklist of forbidden marketplace sources. |