How to Configure Claude Code: Settings, Permissions, and Environment Variables

73% of engineering teams now use AI coding tools daily, a 32-point jump from 41% a year earlier, according to the Pragmatic Engineer Survey of 15,000 developers in February 2026. But adoption speed has outpaced configuration literacy. Claude Code ships with over 125 settings spread across five distinct scopes, and most teams never move past the defaults. The gap between "it works" and "it works well" is almost always a configuration problem.

The scope system determines where a setting is defined, who it affects, and whether it travels with the project. Here is how the five scopes rank, from highest precedence to lowest:

A managed policy set by your IT team cannot be overridden by any lower scope. A local setting overrides the project and user scopes. CLI flags override everything except managed policies.

The merge behavior is the critical detail most developers miss. For scalar settings like model or effortLevel, the highest-precedence scope wins outright. For array settings like permissions.allow and permissions.deny, values concatenate and deduplicate across all scopes. This means a deny rule in your project settings works alongside an allow rule in your user settings. They don't replace each other.

Most settings hot-reload when you save the file. Permissions, hooks, API key helpers, and credential configuration all take effect immediately without restarting. Model changes are the exception: switch models mid-session with the /model command, or restart Claude Code entirely.

In practice, most developers start with user-scope settings for their personal model preference and effort level. When joining a team project, the project-scope settings layer on shared permission rules and hooks. The local scope handles anything personal that should vary per project, like API keys for a staging environment or a different default model for a cost-sensitive prototype.

Each scope maps to a specific file path. Knowing which file to edit is half the configuration battle, because editing the wrong file means your change either gets overridden silently or doesn't apply where you expect.

User scope:
  ~/.claude/settings.json            Personal defaults for all projects
  ~/.claude/CLAUDE.md                Personal memory and instructions
  ~/.claude/agents/                  Custom subagent definitions

Project scope (committed to git):
  .claude/settings.json              Team-shared settings
  .claude/CLAUDE.md                  Project memory and instructions
  .claude/agents/                    Project subagent definitions
  .mcp.json                          MCP server configuration

Local scope (gitignored):
  .claude/settings.local.json        Personal project-specific overrides

Managed scope (system-level):
  macOS: /Library/Application Support/ClaudeCode/
  Linux: /etc/claude-code/
  Windows: C:\Program Files\ClaudeCode\

A basic settings.json looks like this:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",
  "effortLevel": "high",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  },
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

The $schema field enables autocomplete in VS Code, Cursor, and other JSON-aware editors. It validates your configuration against the official schema, catching typos before they silently break your setup.

The CLAUDE.md files at each scope provide natural language instructions that Claude Code reads at session start. User-scope CLAUDE.md contains personal preferences and global guidelines. Project-scope CLAUDE.md holds project-specific context like directory structure, coding conventions, and team processes. These files complement settings.json by giving Claude Code context rather than structured configuration rules.

Enterprise administrators get a drop-in directory at managed-settings.d/. Any .json file placed there merges into managed settings alphabetically: 10-telemetry.json loads before 20-security.json. Scalar values from later files override earlier ones. Arrays concatenate and deduplicate. This lets IT teams compose policies from independent modules without maintaining one monolithic file.

On Windows, user-scope paths map to %USERPROFILE%\.claude\. The managed scope uses C:\Program Files\ClaudeCode\ on v2.1.75 and later. Legacy installs on Windows used C:\ProgramData\ClaudeCode\, which is no longer the default path.

The permission system controls which tools Claude Code can run without asking. Three arrays define the rules: allow for automatic execution, deny for blocked operations, and ask for actions that require your confirmation each time.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

Each rule follows the pattern ToolName(argument_pattern). The * wildcard matches any string, and ** matches across directory boundaries. Bash(npm run test *) allows any npm test command. Read(./secrets/**) matches files at any depth inside the secrets directory.

The ask array is useful for operations you want Claude Code to attempt but with your explicit confirmation each time. This works well for commands like database migrations, deployment scripts, or force-pushes where you want visibility into every execution without a hard block.

When rules conflict across scopes, deny wins. If your user settings allow Bash(curl *) but your project settings deny it, the deny takes effect. This design is intentional: project maintainers can enforce security boundaries that individual developers cannot bypass from their personal settings.

A practical team pattern puts common build and test commands in the project's .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npx jest *)",
      "Bash(git log *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(git push *)",
      "Bash(git reset --hard *)"
    ]
  }
}

This lets Claude Code run builds, tests, and read-only git commands without interrupting you for approval. It blocks access to environment secrets and prevents destructive git operations. Individual developers can then layer personal rules on top through .claude/settings.local.json without changing the team baseline.

Enterprise teams with stricter requirements can set allowManagedPermissionRulesOnly: true in managed settings. This ignores all user and project permission rules entirely, locking configuration to IT-deployed policies. Combined with allowManagedHooksOnly, this gives administrators complete control over what Claude Code can execute across the organization.

Give your Claude Code agents persistent file storage

Fast.io's MCP endpoint lets agents read, write, and share files across sessions, with auto-indexing for semantic search and RAG. Starts with a 14-day free trial.

Start 14-Day Trial

Environment variables offer another configuration layer, especially useful for authentication, model routing, and feature toggles. You can set them in your shell before launching claude, or persist them in the env field of any settings.json file.

{
  "env": {
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "CLAUDE_CODE_DEBUG_LOG_LEVEL": "verbose"
  }
}

Shell-set variables take precedence over values from the env field. This makes shell variables useful for quick session-level overrides, while the env field handles persistent defaults you don't want to set every time you open a terminal.

A common pattern for build-heavy projects: set BASH_DEFAULT_TIMEOUT_MS to 600000 in your project's .claude/settings.json so that long Webpack or Gradle builds don't get killed at the default 2-minute mark. Keep the value in the project scope rather than your user settings, because timeout requirements vary by repo. A React monorepo with a 4-minute production build needs a different timeout than a small CLI tool that compiles in seconds.

Sharing configuration across a development team is where Claude Code's scope system pays off. The project scope (.claude/settings.json) travels with your repository, so every collaborator gets the same permission rules, model defaults, and hooks as soon as they clone. Personal preferences stay in .claude/settings.local.json, which is gitignored by default. This split means teams agree on security boundaries while each developer keeps their own model and effort preferences.

A practical pattern for onboarding: add a SessionStart hook to .claude/settings.json that prints a checklist of required environment variables. New developers cloning the repo get immediate feedback about missing API keys instead of hitting cryptic errors mid-session. Combined with deny rules that block .env reads, this keeps secrets out of Claude Code's context while making sure the developer has them configured in their shell.

For Claude Cowork setups where agents produce artifacts that humans review, keeping shared configuration in the project scope means every team member and every agent session starts with identical permission boundaries. The local scope then handles per-developer preferences like model selection or custom hooks for personal linting tools. This layered approach scales from a two-person team to an enterprise deployment without requiring everyone to maintain identical dotfiles.

{
  "availableModels": ["sonnet", "haiku"],
  "model": "claude-sonnet-4-6"
}