.claude/settings.json vs settings.local.json: Key Differences and When to Use Each

The .claude/settings.json file stores shared team configuration that is committed to version control, while .claude/settings.local.json contains personal developer overrides that remain git-ignored and take precedence within the project scope.

Claude Code supports a sophisticated five-level configuration hierarchy that allows both collaborative consistency and individual flexibility. Understanding the difference between .claude/settings.json and .claude/settings.local.json is essential for teams using the shanraisshan/claude-code-best-practice repository to manage AI coding workflows without configuration conflicts.

Understanding the Configuration Hierarchy

Claude Code reads settings from a five-level override chain: command-line arguments → project-local → project-shared → user-local → user-global. Within the project scope, the two configuration files serve distinct purposes in this hierarchy.

The precedence is documented in the Settings Precedence table within reports/claude-global-vs-project-settings.md at lines 70-78, where priority 2 (.claude/settings.local.json) sits above priority 3 (.claude/settings.json).

.claude/settings.json: Shared Team Configuration

The .claude/settings.json file lives in your project root under the .claude/ directory and represents the project-wide baseline that every team member shares.

When to Use settings.json

Use this file for any configuration that should be committed to version control and enforced across the entire team:

• Default model selection (e.g., "model": "opus")
• Project-wide permissions defining allowed tool uses and file access patterns
• Hook configurations for pre-tool validation scripts
• MCP server allow-lists for external integrations
• UI preferences that ensure consistent behavior across workstations

Because this file is version-controlled, changes appear in pull requests and CI checks, guaranteeing that all contributors operate from the same baseline configuration.

Example settings.json Configuration

{
  "model": "opus",
  "permissions": {
    "allow": [
      "Edit(*)",
      "Write(*)",
      "Bash(git *)",
      "WebFetch(domain:*)"
    ],
    "deny": [
      "Read(.env)",
      "Read(./secrets/**)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      { "type": "command", "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py" }
    ]
  }
}

.claude/settings.local.json: Personal Developer Overrides

The .claude/settings.local.json file resides in the same .claude/ directory but is git-ignored by default, allowing each developer to maintain personal customizations without polluting the shared repository.

When to Use settings.local.json

Use this file for per-developer tweaks that must never be committed upstream:

• Disabling noisy hooks on specific workstations: "disableAllHooks": true
• Enabling local sandbox mode for experimental development: "sandbox": { "enabled": true }
• Temporary permission rules for debugging specific issues
• Experimental flags or feature toggles not ready for team-wide adoption
• Personal UI customizations that differ from team standards

Since the file is listed in .claude/.gitignore, each developer maintains a different set of overrides without affecting colleagues or generating dirty working trees.

Example settings.local.json Configuration

{
  "disableAllHooks": true,
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["git"]
  },
  "permissions": {
    "allow": [
      "Bash(git status)"
    ]
  }
}

How the Override Chain Works

When Claude Code loads configuration, it merges settings from multiple sources using last-write-wins semantics within each scope. The complete hierarchy is:

1. Command-line flags (highest priority)
2. Project-local: .claude/settings.local.json
3. Project-shared: .claude/settings.json
4. User-local: ~/.claude/settings.local.json
5. User-global: ~/.claude/settings.json (lowest priority)

As documented in reports/claude-global-vs-project-settings.md, a setting in .claude/settings.local.json overrides the same key in .claude/settings.json, but command-line arguments override both.

To inspect the effective configuration for your current project, run:

claude --config dump

This outputs the merged configuration with all project-local overrides applied, allowing you to verify which file is controlling specific settings.

Best Practices for Managing Both Files

• Commit .claude/settings.json to ensure consistent team behavior for critical safety settings like permissions and allowed models.
• Never commit .claude/settings.local.json; verify it is listed in .claude/.gitignore to prevent accidental pushes of personal API keys or experimental flags.
• Document team conventions in the repository README, explaining which settings belong in the shared file versus personal overrides.
• Use settings.local.json for temporary debugging rather than modifying the shared configuration, ensuring your experiments do not disrupt CI/CD pipelines or other developers.

Summary

• .claude/settings.json stores project-wide, version-controlled configuration that ensures consistent behavior across all team members.
• .claude/settings.local.json provides git-ignored, personal overrides for individual developer preferences and temporary debugging.
• The five-level hierarchy gives settings.local.json precedence over settings.json within the project scope, while both yield to command-line arguments.
• Use shared settings for models, permissions, and hooks; use local settings for personal sandboxes, disabled hooks, and experimental features.

Frequently Asked Questions

Can I use both files simultaneously in the same project?

Yes. Claude Code automatically merges both files, with .claude/settings.local.json overriding any conflicting keys in .claude/settings.json. This allows teams to maintain shared baselines while individual developers apply personal customizations without modifying committed files.

What happens if I accidentally commit settings.local.json to the repository?

If .claude/settings.local.json is committed, it effectively becomes part of the shared configuration, forcing all team members to inherit your personal overrides. This can break CI/CD pipelines or force unwanted experimental flags on other developers. You should immediately remove the file from version control, add it to .claude/.gitignore, and commit the ignore file instead.

How do I check which configuration file is currently controlling a specific setting?

Run claude --config dump in your terminal. This command outputs the fully merged configuration with all overrides applied, allowing you to see the effective values for models, permissions, hooks, and other settings. If a value differs from what is in the shared settings.json, it is likely being overridden by your local file or a user-level configuration.

Should API keys or sensitive credentials ever be stored in either file?

No. Neither .claude/settings.json nor .claude/settings.local.json should contain sensitive credentials like API keys, passwords, or tokens. While settings.local.json is git-ignored and technically safer for personal data, Claude Code is designed to use environment variables or secure credential stores for sensitive information. Use these JSON files only for behavioral configuration, not secrets management.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}