Claude Code settings.json Guide — Permissions, Env Vars & Tools

When you first start using Claude Code, a natural question arises: "Where exactly should I save my settings?" You might want personal preferences like themes applied everywhere, team-wide permission rules committed to the repository, and experimental settings kept only for yourself. Claude Code resolves all three needs through a scope system — a way of defining how widely a setting applies. By the end of this guide you'll know precisely where to place each settings.json file, and what happens when the same setting appears in multiple scopes. Getting to the point of opening a settings file yourself takes about 10 minutes.

What you'll be able to do

• Locate your settings.json files (or know where to create them)
• Assign settings to the right scope for personal, team, or organisation use
• Open the settings interface with /config and change a value
• Understand which value wins when the same setting appears in multiple scopes

Prerequisites

• Claude Code must be installed. The active package name is @anthropic-ai/claude-code.
• You need access to a terminal (Terminal on macOS/Linux, Command Prompt or PowerShell on Windows). No prior coding experience is required.
• macOS, Linux, and Windows are all supported. On Windows, paths shown as ~/.claude correspond to %USERPROFILE%\.claude.

Quick term glossary

• Scope — the reach of a setting: just you, your project team, or the whole organisation.
• settings.json — a plain text file in JSON format ({ key: value }) that stores Claude Code configuration.
• Repository (repo) — a project folder managed by Git.
• Managed settings — configuration deployed centrally by an IT or DevOps team. Individual users cannot override them. Most individual users will never encounter this scope.
• gitignore — a list of files Git should not track. Files listed here are never uploaded to the shared repository.

Where are the settings files?

Claude Code stores settings in different locations depending on scope. Here is a quick reference.

• User settings: ~/.claude/settings.json — applies across all your projects. Good for themes, editor preferences, and anything you want everywhere.
• Project settings: .claude/settings.json inside your project folder — committed to Git, so every teammate gets the same settings. Use this for shared permission rules and MCP server addresses.
• Local settings: .claude/settings.local.json inside your project folder — not committed to Git. Perfect for personal experiments or machine-specific values that won't work for others.
• Managed settings: delivered via server, MDM, or registry by your organisation's IT team. Highest priority; cannot be overridden.

If a file doesn't exist yet, there's no need to worry. According to the official documentation, when Claude Code itself creates .claude/settings.local.json, it automatically adds the file to gitignore. If you create the file manually, add it to your gitignore yourself.

Step-by-step — opening settings with /config

1. Launch Claude Code in your terminal.

2. Inside the Claude Code interface, type the following command and press Enter.

   /config

   Success signal: A tabbed settings interface opens, showing status information and configuration options organised by tab.

3. To change a single value without opening the full interface, you can pass it directly. According to the official documentation, from v2.1.181 onwards you can write:

   /config verbose=true

   Replace verbose=true with the key and value you want to change, using the key=value format. Verify the exact key names inside the settings interface (/config) rather than guessing.

What happens when the same setting appears in multiple scopes?

Suppose your user settings set an option to true, and your project settings set the same option to false. Which value applies? According to the official documentation, a narrower scope overrides a broader one: Local overrides Project, Project overrides User. So the project-level false wins.

There is one important exception: permission rules do not override each other — they merge. Rules from all scopes are combined, so a team-wide allow list and your personal allow list both remain active at the same time.

Which settings belong in which scope?

• User scope: terminal themes, keyboard shortcuts, API keys and plugins you use across all projects.
• Project scope: shared permission rules, MCP server configuration, plugins the whole team should use — anything you commit to the repo.
• Local scope: settings you're testing before sharing, machine-specific values that won't work on teammates' machines.
• Managed scope: not configured by individuals. Reserved for IT/DevOps enforcing security policies or compliance requirements across the organisation.

Troubleshooting common sticking points

settings.local.json was accidentally committed to Git

This can happen when you create the file manually instead of letting Claude Code create it. Add the following line to your .gitignore file:

.claude/settings.local.json

The /config command doesn't appear or doesn't work

Your Claude Code installation may be out of date. Update to the latest version of the package through your terminal and try again. For the exact update command, refer to the on-screen guidance or check the official documentation at code.claude.com.

I can't tell which value is actually being applied

According to the official documentation, Claude Code includes a Verify active settings feature. Open the settings interface with /config and look for the relevant entry to see the value that is currently in effect. Checking the interface directly is the most reliable method.

Next step — standardising team settings

Think of your project's .claude/settings.json as a recipe card committed to the repository. When a teammate clones the repo, they immediately have the same permission rules and MCP server configuration as everyone else. Personal preferences — themes, shortcuts — live separately in each person's ~/.claude/settings.json, so they never conflict with shared team settings.

Subagent configuration — subagents being separate Claude instances that Claude Code can spin up for subtasks — follows the same scope structure. User-level subagent definitions go in ~/.claude/agents/; project-level definitions go in .claude/agents/.