Settings & Configuration

Why bother with settings?

Out of the box, Claude Code makes sensible choices — but your project may need something different. Maybe you want Claude to always use a specific model for cost reasons, prevent it from ever touching production credentials, or auto-inject environment variables from a shared CI profile. That's what settings.json is for.

Configuration scopes

Settings are read from four places. Higher entries in the table override lower ones — so a local setting beats a project setting, which beats a user setting.

Anatomy of settings.json

Below is an example for an inventory REST API project using Node.js. It fixes the model, restricts shell commands, and injects two env vars that Claude will see in every session.

{
  "model": "claude-opus-4-5",

  "permissions": {
    "allow": [
      "Read(*)",
      "Write(src/**)",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Write(.env*)"
    ]
  },

  "env": {
    "NODE_ENV": "development",
    "API_VERSION": "v2"
  }
}

Model selection

The model key accepts any Anthropic model identifier. Set it at the user level to apply globally, or at the project level to pin a specific model for that repository.

// ~/.claude/settings.json  (user-level — your global default)
{
  "model": "claude-haiku-3-5"   // faster + cheaper for exploratory work
}

// .claude/settings.json  (project-level — overrides global default)
{
  "model": "claude-opus-4-5"    // highest quality for the production API
}

Permission rules

Each rule is a string with a tool name plus an optional glob pattern in parentheses. Rules live under three lists:

{
  "permissions": {
    "allow": [
      "Read(*)",             // read any file
      "Write(src/**)",       // write only inside src/
      "Bash(npm run *)",     // any npm script
      "Bash(git *)"          // any git command
    ],
    "deny": [
      "Bash(rm -rf *)",      // never delete recursively
      "Write(.env*)"         // never touch env files
    ],
    "ask": [
      "Write(package.json)"  // pause before editing deps
    ]
  }
}

Environment variables

Any key-value pair under env is visible to Claude in the shell environment during your session. Use this for non-secret configuration that should be consistent across the team.

{
  "env": {
    "NODE_ENV": "development",
    "API_BASE_URL": "http://localhost:3001",
    "LOG_LEVEL": "debug"
  }
}

Network proxy

If your organization routes outbound traffic through an HTTP proxy, tell Claude Code the port number. All requests to the Anthropic API will be sent via the proxy.

// ~/.claude/settings.json  (user-level — applies everywhere)
{
  "network": {
    "httpProxyPort": 8080
  }
}

Worked example: project + local settings together

The classic pattern is to commit a shared settings.json for the team and keep a private settings.local.json for your own overrides. Here's how a developer named Priya would set it up on her laptop:

{
  "model": "claude-opus-4-5",
  "permissions": {
    "allow": [
      "Read(*)",
      "Write(src/**)",
      "Bash(npm run *)",
      "Bash(git *)"
    ],
    "deny": [
      "Write(.env*)",
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

{
  "model": "claude-haiku-3-5",
  "env": {
    "PRIYA_LAPTOP": "true",
    "LOG_LEVEL": "verbose"
  },
  "network": {
    "httpProxyPort": 3128
  }
}

What happens: Priya's local override swaps the model to haiku (cheaper for quick experiments) and adds her personal proxy. The team-wide permission rules and NODE_ENV still apply from settings.json because the local file only overrides the keys it defines.

Verifying your configuration

Two slash commands let you inspect the merged configuration at any time.

Key settings reference

Before you continue

• settings.json controls model, permissions, env vars, proxy, and hooks.
• Precedence: Managed → Local → Project → User — higher scopes win.
• Commit shared project settings; keep secrets in settings.local.json.
• Use /config and /status to inspect the merged configuration.
• Next lesson: Permission Modes — controlling what Claude Code can read, write, and execute.

What's Next

Configuration is dialled in. Next: Permission Modes — controlling exactly what Claude Code is allowed to read, write, and execute.