16 KiB
16 KiB
Documentation Index
Fetch the complete documentation index at: https://vineetagarwal-code-claude-code.mintlify.app/llms.txt Use this file to discover all available pages before exploring further.
Settings
Configure Claude Code behavior through JSON settings files at the user, project, and managed levels.
Claude Code reads settings from JSON files at multiple scopes. Settings merge from lowest to highest priority, so more specific scopes override broader ones.
Settings files
**Location:** `~/.claude/settings.json`Applies to every Claude Code session you run, across all projects. This is where you set personal preferences like your preferred model, theme, and cleanup policy.
```json theme={null}
{
"model": "claude-opus-4-5",
"cleanupPeriodDays": 30,
"permissions": {
"defaultMode": "acceptEdits"
}
}
```
Checked into source control. Use this for settings that should apply to everyone working on the project — permission rules, hook configurations, MCP servers, and environment variables.
```json theme={null}
{
"permissions": {
"allow": ["Bash(npm run *)", "Bash(git *)"],
"deny": ["Bash(rm -rf *)"]
},
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [{ "type": "command", "command": "npm run lint" }]
}
]
}
}
```
Not checked into source control (automatically added to `.gitignore`). Use this for personal overrides within a specific project — your own permission preferences or environment variables that shouldn't be shared.
```json theme={null}
{
"permissions": {
"defaultMode": "bypassPermissions"
}
}
```
Set by administrators via MDM, registry (Windows), plist (macOS), or a managed settings file. Managed settings take highest priority and cannot be overridden by users or projects.
See [Managed settings](#managed-settings-enterprise) below for details.
Opening settings
Run /config inside any Claude Code session to open the settings UI. This opens the Config tab of the settings panel, where you can browse and edit the currently active settings for each scope.
You can also edit the JSON files directly. Claude Code reloads settings automatically when it detects file changes.
Settings precedence
Settings merge from lowest to highest priority. Later sources override earlier ones for scalar values; arrays are concatenated and deduplicated.
Plugin defaults → User settings → Project settings → Local settings → Managed (policy) settings
Settings reference
**Type:** `string` | **Scope:** AnyOverride the default model used by Claude Code. Accepts any model ID supported by your configured provider.
```json theme={null}
{ "model": "claude-opus-4-5" }
```
Controls which tools Claude can use and in what mode. See [Permissions](/concepts/permissions) for full documentation on rule syntax.
| Field | Type | Description |
| ------------------------------ | ----------- | ----------------------------------------------------------------------------------------- |
| `allow` | `string[]` | Rules for operations Claude may perform without asking |
| `deny` | `string[]` | Rules for operations Claude is always blocked from |
| `ask` | `string[]` | Rules for operations that always prompt for confirmation |
| `defaultMode` | `string` | Default permission mode: `"default"`, `"acceptEdits"`, `"plan"`, or `"bypassPermissions"` |
| `disableBypassPermissionsMode` | `"disable"` | Prevent users from entering bypass permissions mode |
| `additionalDirectories` | `string[]` | Extra directories Claude may access |
```json theme={null}
{
"permissions": {
"defaultMode": "acceptEdits",
"allow": ["Bash(npm run *)", "Bash(git log *)"],
"deny": ["Bash(curl *)"]
}
}
```
Run custom shell commands before or after tool executions. See [Hooks](/guides/hooks) for full documentation.
Supported hook events: `PreToolUse`, `PostToolUse`, `Notification`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Stop`, `SubagentStop`, `PreCompact`, `PostCompact`.
```json theme={null}
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [{ "type": "command", "command": "prettier --write $CLAUDE_FILE_PATHS" }]
}
]
}
}
```
Number of days to retain chat transcripts. Setting to `0` disables session persistence entirely — no transcripts are written and existing ones are deleted at startup.
```json theme={null}
{ "cleanupPeriodDays": 7 }
```
Environment variables to inject into every Claude Code session. Values are coerced to strings.
```json theme={null}
{
"env": {
"NODE_ENV": "development",
"MY_API_URL": "https://api.example.com"
}
}
```
Enterprise allowlist of models users can select. Accepts family aliases (`"opus"` allows any Opus version), version prefixes, or full model IDs. If `undefined`, all models are available. If an empty array, only the default model is available.
```json theme={null}
{ "availableModels": ["claude-opus-4-5", "claude-sonnet-4"] }
```
Enterprise allowlist and denylist for MCP servers. Each entry must have exactly one of `serverName`, `serverCommand`, or `serverUrl`. The denylist takes precedence — if a server matches both lists, it is blocked.
```json theme={null}
{
"allowedMcpServers": [
{ "serverName": "my-db-server" },
{ "serverUrl": "https://mcp.example.com/*" }
],
"deniedMcpServers": [
{ "serverCommand": ["npx", "malicious-server"] }
]
}
```
Configuration for `--worktree` flag behavior.
| Field | Type | Description |
| -------------------- | ---------- | --------------------------------------------------------------------------------- |
| `symlinkDirectories` | `string[]` | Directories to symlink from the main repo into worktrees (e.g., `"node_modules"`) |
| `sparsePaths` | `string[]` | Paths to check out in sparse mode, for faster worktrees in large monorepos |
```json theme={null}
{
"worktree": {
"symlinkDirectories": ["node_modules", ".cache"],
"sparsePaths": ["src/", "packages/my-service/"]
}
}
```
Customize the attribution text Claude appends to commits and pull request descriptions.
| Field | Type | Description |
| -------- | -------- | -------------------------------------------------------------------------------- |
| `commit` | `string` | Attribution text (including any git trailers). Empty string removes attribution. |
| `pr` | `string` | Attribution text for PR descriptions. Empty string removes attribution. |
```json theme={null}
{
"attribution": {
"commit": "Co-Authored-By: Claude <noreply@anthropic.com>",
"pr": ""
}
}
```
Preferred language for Claude responses and voice dictation. Accepts plain language names.
```json theme={null}
{ "language": "japanese" }
```
Sandbox configuration for isolating Claude's tool executions. Contact your administrator for sandbox setup details.
When `false`, extended thinking is disabled. When absent or `true`, thinking is enabled automatically for models that support it.
```json theme={null}
{ "alwaysThinkingEnabled": false }
```
Persisted effort level for models that support adjustable thinking budgets.
```json theme={null}
{ "effortLevel": "high" }
```
Enable or disable auto-memory for this project. When `false`, Claude does not read from or write to the auto-memory directory.
```json theme={null}
{ "autoMemoryEnabled": false }
```
Custom path for auto-memory storage. Supports `~/` for home directory expansion. Ignored if set in project settings (`.claude/settings.json`) for security reasons. Defaults to `~/.claude/projects/<sanitized-cwd>/memory/`.
```json theme={null}
{ "autoMemoryDirectory": "~/my-memory-store" }
```
Glob patterns or absolute paths of `CLAUDE.md` files to exclude from loading. Patterns are matched against absolute paths using picomatch. Only applies to User, Project, and Local memory types — Managed files cannot be excluded.
```json theme={null}
{
"claudeMdExcludes": [
"/home/user/monorepo/vendor/CLAUDE.md",
"**/third-party/.claude/rules/**"
]
}
```
Set to `true` to disable all hook and `statusLine` execution.
```json theme={null}
{ "disableAllHooks": true }
```
Whether the file picker respects `.gitignore` files. `.ignore` files are always respected regardless of this setting.
```json theme={null}
{ "respectGitignore": false }
```
Default shell for `!` commands in the input box.
```json theme={null}
{ "defaultShell": "powershell" }
```
Force a specific login method. Use `"claudeai"` for Claude Pro/Max accounts, or `"console"` for Anthropic Console billing.
```json theme={null}
{ "forceLoginMethod": "console" }
```
Path to a script that outputs authentication values. The script is called to retrieve credentials dynamically instead of reading a static API key.
```json theme={null}
{ "apiKeyHelper": "/usr/local/bin/get-claude-key.sh" }
```
Disable syntax highlighting in diffs.
```json theme={null}
{ "syntaxHighlightingDisabled": true }
```
Reduce or disable animations (spinner shimmer, flash effects, etc.) for accessibility.
```json theme={null}
{ "prefersReducedMotion": true }
```
Managed settings (enterprise)
Administrators can push settings to all users via platform-native mechanisms. Managed settings take precedence over all user and project settings.
Deploy a plist file to `/Library/Preferences/` or via MDM (Jamf, Kandji, etc.) targeting `com.anthropic.claudecode`. Write settings to the `HKLM\Software\Anthropic\Claude Code` registry key (machine-wide) or `HKCU\Software\Anthropic\Claude Code` (per-user, lower priority than HKLM). Place a `managed-settings.json` file at the platform-specific managed path. For drop-in configuration fragments, create a `managed-settings.d/` directory alongside it. Files in that directory are sorted alphabetically and merged on top of the base file — later filenames win.```
managed-settings.json # base settings (lowest precedence)
managed-settings.d/
10-security.json # merged first
20-model-policy.json # merged second (wins over 10-)
```
This convention matches systemd/sudoers drop-ins: independent teams can ship policy fragments without coordinating edits to a single file.
The following managed-only settings lock down user customization surfaces:
| Setting | Description |
|---|---|
allowManagedHooksOnly |
When true, only hooks defined in managed settings run. User, project, and local hooks are ignored. |
allowManagedPermissionRulesOnly |
When true, only permission rules from managed settings are respected. |
allowManagedMcpServersOnly |
When true, the allowedMcpServers allowlist is only read from managed settings. |
strictPluginOnlyCustomization |
Lock specific customization surfaces ("skills", "agents", "hooks", "mcp") to plugin-only sources. Pass true to lock all four, or an array of surface names. |
JSON schema
Add $schema to your settings file for editor autocompletion and validation:
{
"$schema": "https://schemas.anthropic.com/claude-code/settings.json"
}
Built with Mintlify.