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

> Understand the differences between .claude/settings.json and settings.local.json. Learn when to use shared team settings versus personal overrides in your project.

- Repository: [Shayan Rais/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice)
- Tags: best-practices
- Published: 2026-03-12

---

**The [`.claude/settings.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.json) file stores shared team configuration that is committed to version control, while [`.claude/settings.local.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.json) and [`.claude/settings.local.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-global-vs-project-settings.md) at lines 70-78, where priority 2 ([`.claude/settings.local.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.local.json)) sits above priority 3 ([`.claude/settings.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.json)).

## .claude/settings.json: Shared Team Configuration

The [`.claude/settings.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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

```json
{
  "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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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

```json
{
  "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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.local.json)
3. **Project-shared**: [`.claude/settings.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-global-vs-project-settings.md), a setting in [`.claude/settings.local.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.local.json) overrides the same key in [`.claude/settings.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.json), but command-line arguments override both.

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

```bash
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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.json)** to ensure consistent team behavior for critical safety settings like permissions and allowed models.
- **Never commit [`.claude/settings.local.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.json)** stores project-wide, version-controlled configuration that ensures consistent behavior across all team members.
- **[`.claude/settings.local.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.local.json)** provides git-ignored, personal overrides for individual developer preferences and temporary debugging.
- The **five-level hierarchy** gives [`settings.local.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/settings.local.json) precedence over [`settings.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.local.json) overriding any conflicting keys in [`.claude/settings.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.json) nor [`.claude/settings.local.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/settings.local.json) should contain sensitive credentials like API keys, passwords, or tokens. While [`settings.local.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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.