Reference

Settings reference

Complete reference for Claude Code settings.json: 5 precedence levels (managed, CLI, local, project, global), permissions, MCP servers, and enterprise examples.

The 5 configuration levels

Claude Code resolves its final configuration by merging five sources, from highest to lowest priority. When an option is set at multiple levels, the value from the highest level always wins.

PrioritySourceFile / mechanismUser can override
1. ManagedOrganization (admin)Deployed via Anthropic dashboardNo
2. CLICommand lineclaude --model opusYes (intentional)
3. Project localDeveloper.claude/settings.local.jsonYes
4. Project sharedTeam.claude/settings.jsonYes
5. GlobalUser~/.claude/settings.jsonYes

Level 1: Managed settings

Managed settings are deployed by an Anthropic organization admin from the dashboard. They apply to all members regardless of their local configuration.

Typical use cases:

  • Enforce a specific model across the team
  • Block tools considered risky (Bash, WebFetch)
  • Force an enterprise proxy via customApiUrl

Users cannot override managed settings, even with a CLI flag or a local file.

Level 2: CLI arguments

Flags passed directly to the claude command have the second-highest priority. They are useful for one-off sessions without touching any config files.

# Use Opus for this session only
claude --model claude-opus-4-5


# Disable a tool for this invocation
claude --disallowedTools Bash


# Point to a different config file
claude --settings /path/to/settings.json

Levels 3 to 5: Configuration files

The three remaining levels correspond to JSON files. They are merged at the start of each session.

LevelFileRecommended use
Project local.claude/settings.local.jsonPersonal preferences on a project (gitignored)
Project shared.claude/settings.jsonTeam conventions, committed to Git
Global~/.claude/settings.jsonPersonal preferences, across all projects

Annotated full structure

{
  // Default model for all sessions
  "model": "claude-sonnet-4-6",


  // Enable Extended Thinking
  "alwaysThinkingEnabled": false,


  // Automatic context compaction
  "autoCompact": true,


  // API provider (anthropic by default)
  "apiProvider": "anthropic",


  // Custom API URL (proxies, bedrock, vertex)
  "customApiUrl": "https://api.anthropic.com",


  // Global per-tool permissions
  "permissions": {
    "allow": ["Bash(git:*)", "Read"],
    "deny": ["Bash(rm -rf:*)"]
  },


  // Allowed tools list
  "allowedTools": ["Read", "Write", "Bash", "Glob", "Grep"],


  // Disabled tools list
  "disabledTools": [],


  // Environment variables injected into every session
  "env": {
    "NODE_ENV": "development",
    "MY_VAR": "value"
  },


  // MCP server configuration
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"],
      "env": {}
    }
  }
}

Option: model

The default Claude model for all sessions.

ValueDescription
claude-haiku-4-5Fast and affordable, 90% of Sonnet's capabilities
claude-sonnet-4-6Best quality/cost balance (recommended)
claude-opus-4-6Deepest reasoning, slower
{
  "model": "claude-sonnet-4-6"
}

Can be overridden in-session with /model or via --model in the CLI.

Option: alwaysThinkingEnabled

Enables Extended Thinking by default. Claude reserves tokens for internal reasoning before responding.

{
  "alwaysThinkingEnabled": true
}
  • Default: false
  • In-session toggle: Alt+T (Windows/Linux) or Option+T (macOS)
  • Budget: controlled by MAX_THINKING_TOKENS (environment variable)

Option: autoCompact

Automatically compacts context when the token window approaches the limit. Claude generates a summary of previous exchanges.

{
  "autoCompact": true
}
  • Default: true
  • Manual: /compact command in-session

Option: permissions

Fine-grained per-tool authorization control. Two lists: allow (explicit authorizations) and deny (restrictions).

Permission syntax

Tool(filter)
ExampleMeaning
"Read"Allow all file reads
"Bash(git:*)"Allow all git commands
"Bash(npm run:*)"Allow all npm scripts
"Bash(rm -rf:*)"Allow rm -rf (or deny it if in deny list)
"Write(src/**)"Allow writing in src/ only
"WebFetch"Allow outgoing HTTP requests
{
  "permissions": {
    "allow": [
      "Read",
      "Bash(git:*)",
      "Bash(npm run:*)",
      "Bash(npm test:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "WebFetch"
    ]
  }
}

Option: allowedTools

Whitelist of tools that Claude Code can use. If set, only listed tools are available.

Available tools

ToolDescription
ReadRead files
WriteWrite files
EditPartial file modification
MultiEditMultiple modifications in one operation
BashExecute shell commands
GlobSearch files by pattern
GrepSearch content within files
LSList directories
WebFetchHTTP requests
WebSearchWeb search
TaskLaunch sub-agents (agentic mode)
TodoReadRead the task list
TodoWriteWrite to the task list
NotebookReadRead Jupyter notebooks
NotebookEditEdit Jupyter notebooks
{
  "allowedTools": ["Read", "Bash", "Glob", "Grep"]
}

Option: disabledTools

List of explicitly disabled tools (blacklist). Complements allowedTools.

{
  "disabledTools": ["WebFetch", "WebSearch"]
}

Option: env

Environment variables automatically injected into all Claude Code sessions and any subprocesses they launch.

{
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://localhost/myapp",
    "LOG_LEVEL": "debug"
  }
}

Option: apiProvider

API provider to use. Useful for enterprise proxies or deployments via Amazon Bedrock / Google Vertex.

ValueDescription
"anthropic"Direct Anthropic API (default)
"bedrock"Amazon Bedrock (requires AWS credentials)
"vertex"Google Vertex AI
{
  "apiProvider": "anthropic",
  "customApiUrl": "https://my-proxy.company.com/anthropic"
}

Option: customApiUrl

Custom base URL for API calls. Useful for enterprise proxies, gateways, or self-hosted deployments.

{
  "customApiUrl": "https://api-proxy.my-company.com"
}

The API key (ANTHROPIC_API_KEY) is still required even with a custom URL.

Option: effortLevel

Controls the cognitive effort Claude allocates to each response. Useful for tuning the speed/quality trade-off without switching models.

ValueBehavior
"low"Fast responses, less reasoning
"medium"Default balance
"high"Deep reasoning, slower
{
  "effortLevel": "medium"
}

Can be overridden in-session or via --effort-level in the CLI.

Option: attribution

Customizes or removes the Co-Authored-By lines that Claude adds to commits and pull requests.

{
  "attribution": {
    "commit": "Co-Authored-By: Claude <claude@anthropic.com>",
    "pr": false
  }
}
FieldTypeDescription
attribution.commitstring or falseLine appended to commit messages. false to disable
attribution.prstring or falseLine appended to PR descriptions. false to disable

Option: worktree

Configuration for Git repositories using worktrees. Particularly useful in monorepos.

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".next", "dist"],
    "sparsePaths": ["packages/my-service/**", "shared/**"]
  }
}
FieldTypeDescription
worktree.symlinkDirectoriesstring[]Directories to symlink between worktrees (avoids duplicating node_modules)
worktree.sparsePathsstring[]Patterns for sparse-checkout (partial checkout on large monorepos)

Option: sandbox

Enables sandbox mode to isolate Claude's executions in a controlled environment.

{
  "sandbox": {
    "enabled": true
  }
}

When sandboxing is active, Bash commands run in a restricted environment with no network access and no writes outside the project directory.

Option: autoMode

Customizes the permission classifier used in auto mode. Adjusts the threshold at which Claude asks for confirmation before executing an action.

{
  "autoMode": {
    "permissionLevel": "default"
  }
}
ValueBehavior
"default"Standard behavior (asks for risky actions)
"strict"Asks for confirmation on any write action
"relaxed"Fewer interruptions, more autonomy

Option: companyAnnouncements

Displays a custom message at the start of each session. Useful for broadcasting instructions or reminders to the whole team via the committed settings.json.

{
  "companyAnnouncements": "Reminder: this project runs on Node 22. Run 'nvm use' before starting."
}

The message appears once in the terminal when Claude Code launches.

Option: mcpServers

MCP server configuration. Each entry is a named MCP server.

MCP server structure

{
  "mcpServers": {
    "<mcp-name>": {
      "command": "<executable>",
      "args": ["<arg1>", "<arg2>"],
      "env": {
        "VAR": "value"
      },
      "transport": "stdio"
    }
  }
}
FieldTypeRequiredDescription
commandstringYes (stdio)Command to start the server
argsstring[]NoArguments passed to the command
envobjectNoEnvironment variables for the MCP process
transportstringNo"stdio" (default) or "sse"
urlstringYes (SSE)SSE server URL (if transport: "sse")

MCP configuration examples

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projects",
        "/tmp"
      ]
    },


    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
      }
    },


    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/mydb"
      ]
    },


    "my-sse-api": {
      "transport": "sse",
      "url": "https://my-server.com/mcp"
    }
  }
}

Enterprise configuration

Managed settings let an administrator enforce configuration across the entire organization. Here are the most common use cases.

Enforce a model across the team

// Managed settings (deployed via the Anthropic dashboard)
{
  "model": "claude-sonnet-4-5",
  "effortLevel": "medium"
}

Developers can still choose a different model via --model in the CLI, unless that option is locked by the admin.

Block dangerous commands

// Managed settings
{
  "permissions": {
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(curl:*)",
      "WebFetch"
    ]
  }
}

Enforce attribution in commits

// Managed settings
{
  "attribution": {
    "commit": "Co-Authored-By: Claude <claude@anthropic.com>",
    "pr": "Generated with assistance from Claude Code"
  }
}

Force an enterprise proxy

// Managed settings
{
  "apiProvider": "anthropic",
  "customApiUrl": "https://api-gateway.my-company.com/anthropic"
}

All calls to the Anthropic API will route through the proxy, regardless of the developer's local config file.

Broadcast instructions to the team

// .claude/settings.json (committed to the repo)
{
  "companyAnnouncements": "Sprint 14 in progress. Main branch: main. No merges without 2 reviews."
}

Complete configuration examples

Solo developer setup

// ~/.claude/settings.json
{
  "model": "claude-sonnet-4-6",
  "alwaysThinkingEnabled": false,
  "autoCompact": true,
  "permissions": {
    "allow": ["Read", "Write", "Bash(git:*)", "Bash(npm:*)"],
    "deny": ["Bash(sudo:*)"]
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"]
    }
  }
}

Team setup (committed to the repo)

// .claude/settings.json
{
  "model": "claude-sonnet-4-6",
  "allowedTools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
  "permissions": {
    "deny": ["Bash(rm -rf:*)", "Bash(sudo:*)", "WebFetch"]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    }
  }
}

Secure setup (read-only)

// For audits or sensitive environments
{
  "allowedTools": ["Read", "Glob", "Grep", "LS"],
  "permissions": {
    "deny": ["Write", "Edit", "Bash", "WebFetch", "WebSearch"]
  }
}

Next steps

Previous

CLI reference

Next

Claude Code environment variables: official docs (API_KEY, BASE_URL)