Local Overrides (settings.local.json)
Relevant source files
The following files were used as context for generating this wiki page:The settings.local.json file provides a mechanism for developers to apply personal overrides to the project's shared Claude Code configuration (.claude/settings.json). This file is intentionally excluded from version control, allowing individual team members to customize their environment, such as enabling debug features or altering hook behaviors, without affecting the configuration for the rest of the team.
This local override system is a key part of maintaining a consistent team-wide base configuration while still allowing for individual developer flexibility. It is one of two primary local override files, the other being CLAUDE.local.md for project memory.
Sources: README.md:60-61, README.md:521-522, .claude/.gitignore
Configuration Loading Hierarchy
Claude Code loads configuration in a specific order, with local settings taking precedence over project-wide settings. When a session starts, Claude first loads the base .claude/settings.json file. It then checks for the existence of .claude/settings.local.json. If found, its contents are merged with the base configuration, with any conflicting keys from the local file overwriting those from the project file.
Sources: README.md:60-61, README.md:111-112
The following diagram illustrates this configuration loading and override process.
This diagram represents the logical flow of configuration based on the file's purpose as "Personal overrides". Sources: README.md:60-61
Version Control
The settings.local.json file is explicitly ignored by Git to prevent personal configurations from being committed to the shared repository. This is crucial for ensuring that individual preferences or temporary debugging settings do not become part of the project's standard configuration.
Sources: README.md:60-61, README.md:521-522
The exclusion is defined in the .claude/.gitignore file.
# .claude/.gitignore
# Personal settings overrides
settings.local.json
# Personal project memory
CLAUDE.local.md
Sources: .claude/.gitignore
Comparison with Other Local Files
The Claude Code configuration system includes multiple files for both project-wide and personal settings. The settings.local.json file is specifically for overriding hooks, environment variables, and permissions defined in .claude/settings.json. This is distinct from CLAUDE.local.md, which is used for personal notes and overrides to the main project memory file, CLAUDE.md.
Sources: README.md:54, README.md:60, README.md:108, README.md:522
The table below summarizes the relationship between project-wide files and their personal, git-ignored counterparts.
| File Type | Project-wide (Committed) | Personal Override (Git-ignored) | Purpose |
|---|---|---|---|
| Settings | .claude/settings.json | .claude/settings.local.json | Configures hooks, environment, permissions, and plugins. |
| Memory | CLAUDE.md or .claude/CLAUDE.md | CLAUDE.local.md | Provides persistent project context, rules, and guidelines. |
Sources: README.md:54-61, README.md:108-112, README.md:521-522, CLAUDE.md, .claude/.gitignore
Summary
The settings.local.json file is a powerful feature for personalizing the Claude Code development experience. By providing a structured way to override shared project settings, it allows developers to tailor the AI assistant's behavior to their specific needs and workflows without disrupting the standardized environment for the team. Its exclusion from version control is a key design choice that separates personal preference from project-level configuration.
Sources: README.md:60-61, .claude/.gitignore