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 original 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.

// .claude/settings.json  (committed — shared with your team)
{
  "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
  }
}

Verifying Your Configuration

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

Key Settings Reference

Setup Checklist