Claude Code Settings

Settings control how Claude Code behaves: which actions it may take, which model it uses, and which hooks and tools it loads. A handful of small files hold all of these choices. Knowing where they live lets you tune Claude Code for yourself, for a project, and for a whole team.

The Thermostat Idea

A house thermostat holds a temperature that every room follows. Settings files work the same way. A value written once applies automatically in every session that reads the file.

The Settings Files

File	Scope	Shared With the Team
~/.claude/settings.json	Every project on your computer	No
.claude/settings.json	One project	Yes, through version control
.claude/settings.local.json	One project, personal only	No

Priority when values clash:

   MOST SPECIFIC WINS
   local project file
         ↓
   shared project file
         ↓
   personal home file

Organizations can deploy managed settings that sit above every personal choice. Those policies enforce company rules.

The Settings Menu

Type /config inside a session to browse common options in a friendly menu. Changes saved there flow into the files described above. Direct file editing gives more control, and the menu gives more comfort.

A Sample Settings File

{
  "model": "sonnet",
  "permissions": {
    "allow": ["Bash(npm run test)"],
    "deny": ["Read(./.env)"],
    "defaultMode": "default"
  },
  "env": {
    "NODE_ENV": "development"
  }
}

Model names and available options change over time. Consult the official documentation or run /model to see what your account offers.

Common Settings

Setting	Controls
model	The default AI model for sessions
permissions	Allow and deny rules and the starting mode
env	Environment variables available to commands
hooks	Automatic commands at chosen events

Choosing Where to Save a Setting

Personal Preference

Put it in the home file. Your favorite model belongs here.

Team Standard

Put it in the shared project file. Safety rules and shared hooks belong here.

Private Project Tweak

Put it in the local project file. A test key for your own machine belongs here, and a line in .gitignore keeps the file out of version control.

Related Configuration Files

• CLAUDE.md holds instructions written in plain language.
• .mcp.json holds shared MCP server connections.
• .claude/commands/ holds custom slash commands.
• .claude/agents/ holds subagents.
• .claude/skills/ holds skills.

project-folder
 ├── CLAUDE.md
 ├── .mcp.json
 └── .claude
      ├── settings.json
      ├── settings.local.json
      ├── commands
      ├── agents
      └── skills

Good Practices

• Keep the JSON valid. A missing comma breaks the whole file.
• Commit the shared file and ignore the local file.
• Review settings after every Claude Code update.
• Avoid storing secrets inside settings files that enter version control.

Settings in Action

A team lead adds an allow rule for the test command and a deny rule for the secrets file, and commits the project file. Every teammate receives the same safety net after the next pull. One developer prefers a different default model and sets it in the personal home file. Neither choice disturbs the other. Layered files make that peaceful coexistence possible.

Reading a Settings Problem

Suppose a rule seems ignored. Check the three files in order, starting with the local project file, since the most specific file wins. Look for a stray character that breaks the JSON. Confirm that the rule spelling matches the tool name exactly. A managed policy from an organization may override personal choices, so ask your administrator when nothing else explains the behavior.

Key Points

• Three settings files cover personal, shared, and private needs.
• The most specific file wins when values clash.
• The /config command offers a friendly menu.
• Permissions, model, environment, and hooks are the most common settings.
• Related folders hold commands, agents, and skills.