How to Configure Claude Code with settings.json

Claude Code reads JSON settings files that control the model it uses, environment variables it sees, and other defaults. Setting these once beats passing flags every time. This guide covers where the files live, how they merge, and the most useful keys.

What you need

• Claude Code installed
• A text editor
• About 10 minutes

Step 1: Know which file wins

Settings merge from broad to narrow, with the narrower file overriding the broader one when keys collide.

Step 2: Set your user defaults

Open your personal settings and set a default model and any environment variables you want every session to inherit. Create the file if it does not exist.

{
  "model": "claude-sonnet-4-5",
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "120000"
  },
  "includeCoAuthoredBy": true
}

Step 3: Add project-level settings

Put settings the whole team should share in the project file. A common choice is pinning the model so everyone gets consistent behavior on this codebase.

{
  "model": "claude-opus-4-1",
  "env": {
    "NODE_ENV": "development"
  }
}

Step 4: Validate the JSON

A trailing comma or stray quote silently breaks the file. Check it parses before you rely on it.

Result: your model and environment are set once and applied automatically, with project settings overriding personal ones and local settings overriding both.