The .claude/settings.local.json file is your personal, machine-specific configuration override for a single project. It lets you customize Claude Code's behavior for your local workspace without affecting your teammates, as it is automatically excluded from version control .

📁 Understanding the Configuration Hierarchy

Claude Code uses a layered system where more specific scopes override broader ones . Here is a comparison of the different configuration scopes:

Settings are applied with the following priority (highest to lowest): Managed > Command-line arguments > Local > Project > User . This means your settings.local.json will override settings in both the project's settings.json and your global user settings.

🛠️ How and When to Use It

You should create and edit a settings.local.json file in your project's .claude/ directory when you need settings that are specific to your workflow on that project.

Key Use Cases:

Personal Tool Permissions: Pre-approve specific commands (like git commit) to reduce permission prompts just for you .

Experiment Safely: Test new hooks or environment variables before proposing them to the team in the shared settings.json .

Machine-Specific Paths: Configure paths or credentials that differ on your machine .

Auto-approving MCP Servers: Some tools (like claude-flow) may generate this file to auto-approve specific local MCP servers for convenience .

📝 Common Configuration Example

Here are practical configurations you might add to your .claude/settings.local.json to reduce permission prompts: