How to Configure Claude Code Settings

Claude Code settings control everything from permissions and tool access to themes and environment variables. Learn where files live, what you can configure, and how to set it up right.

Claude Code settings are configured through JSON files at three levels: global (~/.claude/settings.json), project (.claude/settings.json), and user-project (.claude/settings.local.json). They control permissions, model selection, tool access, MCP servers, themes, and more. More specific files override broader ones.

This guide maps out every settings file, where it lives, what you can configure in each, and how to set things up so Claude works the way you want without asking permission for every safe command.

What Can You Configure?

Claude Code settings control:

• Permissions: Which tools Claude can use without asking
• Model selection: Default AI model, effort levels, and model-specific settings
• Tool access: Allow, ask, or deny specific tools and commands
• Environment: Variables passed to Claude's sessions
• Display: Themes, spinner messages, status line, output style
• MCP servers: External tool integrations
• Hooks: Lifecycle event automation (PreToolUse, PostToolUse, etc.)
• Sandbox: Security restrictions for bash execution
• Plugins: Plugin marketplace and plugin management

Settings File Locations

Claude Code uses a hierarchy of settings files. More specific settings override broader ones.

Settings Precedence Order

When the same setting exists in multiple files, Claude Code applies them in this order (highest priority first):

1. Managed settings (IT deployed, system-wide)
2. Command line arguments
3. Local project settings (.claude/settings.local.json)
4. Shared project settings (.claude/settings.json)
5. User settings (~/.claude/settings.json)

How to Open Settings

The quickest way to view and edit settings is with the /config command:

/config

This opens a visual interface where you can modify settings, see current values, and access different configuration sections.

You can also edit the files directly. Create them if they don't exist:

# User settings (all projects)
nano ~/.claude/settings.json

# Project settings (shared)
nano .claude/settings.json

# Project settings (personal)
nano .claude/settings.local.json

Permission Settings

This is the most important section. Permissions control which tools Claude can use and whether it needs to ask first.

Basic Permission Structure

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run test)",
      "Read(./src/**)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env*)",
      "WebFetch"
    ]
  }
}

Rules are evaluated in order: deny first, then ask, then allow.

Permission Rule Syntax

Rules follow the format Tool or Tool(specifier):

Available Tools

Permission Modes

Set a default permission mode for all tools:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Options:

• default — Standard prompts for everything
• acceptEdits — Auto-accept file edits
• dontAsk — Auto-deny prompts (allowed tools still work)
• bypassPermissions — Skip all permission checks

Real Permission Example

Here's a practical setup for a web development project:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npm test *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read(./src/**)",
      "Read(./tests/**)",
      "Edit(./src/**)",
      "Edit(./tests/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm publish *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env*)",
      "Read(./secrets/**)",
      "Edit(./.env*)",
      "WebFetch"
    ],
    "defaultMode": "acceptEdits"
  }
}

Core Settings

Model Configuration

Claude Code supports model aliases (opus, sonnet, haiku, opusplan) or full model names. The latest models are Claude Opus 4.6 (claude-opus-4-6), Claude Sonnet 4.5 (claude-sonnet-4-5-20250929), and Claude Haiku 4.5 (claude-haiku-4-5-20251001).

{
  "model": "opus",
  "alwaysThinkingEnabled": true,
  "effortLevel": "high"
}

The opusplan alias uses Opus for plan mode and Sonnet for execution, giving you the best of both models automatically.

Or use environment variables:

export ANTHROPIC_MODEL="opus"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5-20250929"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"
export CLAUDE_CODE_EFFORT_LEVEL="high"
export MAX_THINKING_TOKENS=31999

Effort levels control Opus 4.6's adaptive reasoning: low (faster, cheaper), medium, and high (default, deepest reasoning). Set via the effortLevel setting, the CLAUDE_CODE_EFFORT_LEVEL environment variable, or the left/right arrow keys in the /model picker.

Display and UI

{
  "outputStyle": "Explanatory",
  "language": "english",
  "showTurnDuration": true,
  "spinnerTipsEnabled": true,
  "terminalProgressBarEnabled": true
}

To change the theme, run /theme in Claude Code.

Session Management

{
  "cleanupPeriodDays": 30,
  "autoUpdatesChannel": "stable"
}

Environment Variables

Claude Code supports many environment variables. Set them in your shell profile or in the env field of settings.

In Settings

{
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "true"
  }
}

Key Environment Variables

Disabling Features

# Disable telemetry
export DISABLE_TELEMETRY=1

# Disable error reporting
export DISABLE_ERROR_REPORTING=1

# Disable background tasks
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

# Disable cost warnings
export DISABLE_COST_WARNINGS=1

Sandbox Settings

The sandbox restricts what bash commands can do:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "allowLocalBinding": false
    }
  }
}

When autoAllowBashIfSandboxed is true and the sandbox is enabled, Claude can run bash commands without asking—because they're sandboxed anyway.

Hooks Configuration

Hooks let you run custom scripts automatically at key points in Claude's lifecycle. They are configured in your settings file.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/pre-bash.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/auto-lint.sh" }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/notify.sh" }
        ]
      }
    ]
  }
}

Available hook events:

• PreToolUse: Fires before Claude executes a tool. Can modify tool inputs or block execution.
• PostToolUse: Fires after a tool completes. Useful for running linters, formatters, or tests automatically.
• Notification: Fires when Claude needs your attention or completes a task.
• Stop: Fires when Claude finishes its response.
• SubagentStop: Fires when a subagent finishes.

MCP Server Configuration

MCP (Model Context Protocol) servers add external tools to Claude Code.

{
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["memory", "github"],
  "disabledMcpjsonServers": ["filesystem"],
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "memory" }
  ]
}

MCP servers are typically configured in .mcp.json in your project root or in ~/.claude.json globally.

Attribution Settings

Customize how Claude Code attributes its contributions:

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: Claude ",
    "pr": "Generated with Claude Code"
  }
}

Complete Example Configuration

Here's a comprehensive settings file you can adapt:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "effortLevel": "high",
  "language": "english",
  "outputStyle": "Explanatory",
  "showTurnDuration": true,
  "spinnerTipsEnabled": true,
  "autoUpdatesChannel": "stable",

  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Read(./src/**)",
      "Edit(./src/**)",
      "Write(./src/**)",
      "MultiEdit(./src/**)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env*)",
      "Read(./secrets/**)",
      "WebFetch"
    ],
    "defaultMode": "acceptEdits"
  },

  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  },

  "env": {
    "NODE_ENV": "development"
  },

  "cleanupPeriodDays": 30
}

Common Mistakes

1. Editing the wrong file: Changes to ~/.claude/settings.json apply everywhere. Changes to .claude/settings.json only apply to that project. Make sure you're editing the right one.
2. Invalid JSON: A missing comma or bracket breaks the entire file. Use a JSON validator or editor with syntax highlighting.
3. Overly permissive rules: "allow": ["Bash(**)"] is dangerous. Be specific about what you allow.
4. Forgetting wildcards: Bash(npm run build) only matches that exact command. Use Bash(npm run *) for all npm run commands.
5. Not checking settings into git: Project settings in .claude/settings.json should be version controlled so your team has consistent behavior.

FAQ

How do I reset all settings to defaults?

Delete or rename your settings files. Claude Code creates fresh defaults on next launch. Files are at ~/.claude/settings.json and ~/.claude.json.

Why isn't my setting taking effect?

Check the precedence order. A project-level setting overrides your user settings. Also verify your JSON is valid—any syntax error causes the entire file to be ignored.

Can I have different settings for different projects?

Yes. Create .claude/settings.json in each project directory. These override your user-level settings for that project only.

How do I see what settings are currently active?

Run /config to open the visual settings interface. Or check /status for key configuration info.

How do I make Claude stop asking about a specific command?

Add it to the allow list: "allow": ["Bash(your-command)"]. Use wildcards if needed: "Bash(npm run *)".

Related Guides

• How to Use CLAUDE.md Files — persistent memory for your projects
• How to Create Custom Agents — specialized AI subagents
• How to Use Slash Commands — including /config and /theme