Claude Code Configuration: Project-Specific vs User-Specific Settings Explained

Claude Code uses a five-level configuration hierarchy where ~/.claude/settings.json (user-level) overrides .claude/settings.json (project-level), while .claude/settings.local.json provides temporary workstation-specific overrides that never touch version control.

Managing settings across different scopes is essential when working with Claude Code in team environments. According to the luongnv89/claude-howto repository, the tool reads configuration from a cascading priority system that lets you commit shared project defaults while keeping personal preferences private.

Understanding the Configuration Hierarchy

Claude Code evaluates settings through five distinct levels. When the same key appears in multiple files, the entry from the higher level takes precedence.

The hierarchy from highest to lowest priority:

1. Managed policy (organization-wide)
2. Managed drop-ins (managed-settings.d/)
3. User-level (~/.claude/settings.json)
4. Project-level (.claude/settings.json)
5. Local overrides (.claude/settings.local.json)

As documented in 02-memory/README.md lines 13-15, this structure ensures that individual developers can override team defaults without modifying committed files, while organizational policies remain enforceable at the top.

Project-Specific Configuration

Project-level settings live inside your repository at .claude/settings.json. Because this file is committed to Git, it provides a baseline configuration that every team member inherits when cloning the repository.

Creating the Project Configuration File

Create the directory and JSON file at your repository root:

mkdir -p .claude
cat > .claude/settings.json <<'EOF'
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/format-code.sh" }
        ]
      }
    ]
  },
  "agents": {
    "deploy": {
      "command": "scripts/deploy.sh",
      "description": "Deploy the app to staging"
    }
  },
  "permissionMode": "plan"
}
EOF
git add .claude/settings.json && git commit -m "Add project-wide Claude Code config"

What Belongs in Project Settings

Use this scope for team-wide standards that require consistency across all workstations:

• Shared hooks that enforce code style or security scans
• Project agents that implement deployment pipelines or testing workflows
• Default permission modes (e.g., plan for cautious teams)
• MCP server configurations in .mcp.json for common external tools

User-Specific Configuration

User-level settings reside at ~/.claude/settings.json and apply globally to every project you open with Claude Code. Because this file lives outside any repository, it remains private and travels with your user profile across machines.

Setting Global Defaults

Create or edit the file in your home directory:

mkdir -p ~/.claude
cat > ~/.claude/settings.json <<'EOF'
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/personal-format.sh" }
        ]
      }
    ]
  },
  "permissionMode": "auto",
  "autoMemoryDirectory": "/Users/alice/.claude/memory"
}
EOF

Override Behavior

Since user-level configuration outranks project-level, entries here replace any conflicting keys in the repository's .claude/settings.json. For example, if both files define a PreToolUse hook, Claude Code executes your personal version from ~/.claude/settings.json.

Important restriction: As noted in 02-memory/README.md lines 78-83, the autoMemoryDirectory setting can only be defined at the user level or in a local file. Attempts to set it in a project-level settings.json are silently ignored.

Local Overrides (Git-Ignored)

For temporary, machine-specific tweaks—such as API tokens or debug flags—create .claude/settings.local.json at the repository root. This file sits at the bottom of the precedence stack but is excluded from version control by convention.

cat > .claude/settings.local.json <<'EOF'
{
  "mcp": {
    "github": { "authToken": "ghp_XXXXXXXXXXXXXXXXXXXX" }
  }
}
EOF
echo ".claude/settings.local.json" >> .gitignore

Local overrides are ideal for secret tokens, personal API keys, or temporary path modifications that should not be shared with teammates.

Configuration Scope Comparison

File	Location	Git Tracked	Typical Contents
~/.claude/settings.json	User home	No	Personal hooks, autoMemoryDirectory, global permission mode
.claude/settings.json	Repository root	Yes	Team hooks, project agents, shared MCP defaults
.claude/settings.local.json	Repository root	No	Secret tokens, temporary debugging flags
.mcp.json	Repo or user home	Yes/No	MCP server URLs and command templates

Summary

• Project-specific configurations live at .claude/settings.json and define team-wide defaults that commit to version control.
• User-specific configurations reside at ~/.claude/settings.json and override project settings globally across all repositories.
• Local overrides use .claude/settings.local.json for temporary, workstation-specific tweaks that remain private.
• The autoMemoryDirectory setting is restricted to user-level or local files only.
• Precedence flows from managed policies down to local overrides, with higher levels winning conflicts.

Frequently Asked Questions

Can I use both project and user configurations simultaneously?

Yes. Claude Code merges settings from all levels, with higher-priority files overriding specific keys. You can define shared hooks at the project level while keeping personal formatting preferences in your user file. Both sets of configurations apply, with conflicts resolved according to the hierarchy documented in 02-memory/README.md.

Why is my autoMemoryDirectory setting being ignored?

The autoMemoryDirectory key can only be set in ~/.claude/settings.json or .claude/settings.local.json. As implemented in the source documentation (lines 78-83 of 02-memory/README.md), this restriction prevents projects from forcing specific memory locations on users' machines. Move the setting to your user-level file to activate it.

Should I commit .claude/settings.local.json to Git?

No. The .claude/settings.local.json file is designed for private, workstation-specific overrides such as API tokens and temporary debug flags. Always add this filename to .gitignore to prevent accidentally sharing secrets or machine-specific paths with your team.

How do MCP server configurations fit into this hierarchy?

MCP configurations follow similar scoping rules. Project-wide MCP servers belong in .mcp.json at the repository root (committed), while personal API keys belong in ~/.claude/.mcp.json (user-level). According to 05-mcp/README.md line 240, Claude Code respects the same precedence logic for MCP settings as it does for settings.json files.

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