Skip to content
Developer Toolkit Developer Toolkit Cursor & Claude Code | Developer Toolkit

Configuration & Settings

Learn to configure Claude Code for your workflow, from managing permissions and authentication to setting up project-specific configurations. This guide covers both personal preferences and team-wide settings.

Configuration Hierarchy

Section titled “Configuration Hierarchy”

Claude Code uses a hierarchical configuration system that allows flexibility while maintaining consistency:

Settings Precedence (Highest to Lowest)

  1. Enterprise Policies - Managed by IT administrators
  2. Command Line Arguments - Override for specific sessions
  3. Local Project Settings - .claude/settings.local.json
  4. Shared Project Settings - .claude/settings.json
  5. User Settings - ~/.claude/settings.json

Quick Configuration

Section titled “Quick Configuration”

  1. Interactive configuration

    Terminal window
    claude /config

  2. List current settings

    Terminal window
    claude config list

  3. Set a specific value

    Terminal window
    claude config set model claude-sonnet-4
    claude config set autoUpdates false --global

  4. View a setting

    Terminal window
    claude config get model

Settings Files

Section titled “Settings Files”

User Settings

Section titled “User Settings”

Global preferences that apply to all projects:

~/.claude/settings.json
// ~/.claude/settings.json
{
"model": "claude-opus-4",
"theme": "dark",
"autoUpdates": true,
"env": {
  "EDITOR": "code",
  "NODE_ENV": "development"
},
"permissions": {
  "defaultMode": "acceptEdits",
  "allow": [
    "Edit",
    "Bash(git:*)",
    "Bash(npm run:*)"
  ]
}
}

Project Settings

Section titled “Project Settings”

Team-shared configuration checked into version control:

.claude/settings.json
// .claude/settings.json
{
"model": "claude-sonnet-4",
"maxTurns": 20,
"allowedTools": [
  "Edit",
  "View",
  "Bash(npm:*)",
  "mcp__github__*"
],
"env": {
  "API_ENDPOINT": "https://staging.api.company.com"
},
"permissions": {
  "additionalDirectories": [
    "../shared-lib",
    "../api-contracts"
  ]
},
"hooks": {
  "PreToolUse": {
    "Edit": "npm run lint-staged"
  }
}
}

Local Project Settings

Section titled “Local Project Settings”

Personal overrides not checked into version control:

.claude/settings.local.json
// .claude/settings.local.json
{
"env": {
  "API_KEY": "your-personal-dev-key"
},
"permissions": {
  "defaultMode": "bypassPermissions"
}
}

Permission Management

Section titled “Permission Management”

Permission Modes

Section titled “Permission Modes”

Standard behavior - prompts for permission on first use of each tool:

Terminal window
claude --permission-mode default

Good for: New projects, unfamiliar codebases

Managing Allowed Tools

Section titled “Managing Allowed Tools”

  1. Interactive management

    Terminal window
    claude /permissions

  2. Allow specific tools

    {
      "permissions": {
        "allow": [
          "Edit",                    // All file edits
          "Bash(git:*)",            // All git commands
          "Bash(npm run test:*)",   // Specific npm scripts
          "Read(~/.zshrc)",         // Read specific files
          "mcp__github__*"          // All GitHub MCP tools
        ]
      }
    }

  3. Deny dangerous operations

    {
      "permissions": {
        "deny": [
          "Bash(rm -rf:*)",         // Prevent deletions
          "Bash(curl:*)",           // Block external requests
          "Edit(/etc/**)"           // Protect system files
        ]
      }
    }

Tool-Specific Rules

Section titled “Tool-Specific Rules”

Permission Rule Patterns

ToolPatternExample
BashBash(command:*)Bash(npm run:*)
EditEdit(path/pattern)Edit(src/**)
ReadRead(path/pattern)Read(~/.ssh/*)
WebFetchWebFetch(domain:example.com)WebFetch(domain:api.company.com)
MCPmcp__server__toolmcp__github__create_issue

Environment Variables

Section titled “Environment Variables”

Configuration via Settings

Section titled “Configuration via Settings”

Set environment variables that persist across sessions:

{
"env": {
  // Development settings
  "NODE_ENV": "development",
  "DEBUG": "app:*",


  // API configuration
  "API_BASE_URL": "https://staging.api.com",
  "TIMEOUT": "30000",


  // Tool configuration
  "EDITOR": "code",
  "PAGER": "less"
}
}

Runtime Environment Variables

Section titled “Runtime Environment Variables”

Override settings for specific sessions:

Terminal window
# Authentication
export ANTHROPIC_API_KEY="sk-ant-..."
export ANTHROPIC_AUTH_TOKEN="Bearer token..."


# Model selection
export ANTHROPIC_MODEL="claude-opus-4"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-3"


# Proxy configuration
export HTTPS_PROXY="https://proxy.company.com:8080"
export NODE_TLS_REJECT_UNAUTHORIZED=0  # Self-signed certs


# Behavior tweaks
export BASH_MAX_TIMEOUT_MS=300000  # 5 minutes
export DISABLE_PROMPT_CACHING=1
export DISABLE_INTERLEAVED_THINKING=1

Model Configuration

Section titled “Model Configuration”

Selecting Models

Section titled “Selecting Models”
{
  "model": "claude-opus-4",
  "smallFastModel": "claude-haiku-3"
}

Working Directories

Section titled “Working Directories”

Extend Claude’s file access beyond the launch directory:

  1. During startup

    Terminal window
    claude --add-dir ../backend ../shared

  2. During session

    Terminal window
    /add-dir ../documentation

  3. Persistent configuration

    {
      "permissions": {
        "additionalDirectories": [
          "../api",
          "../shared-components",
          "~/templates"
        ]
      }
    }

Enterprise Configuration

Section titled “Enterprise Configuration”

Managed Policy Settings

Section titled “Managed Policy Settings”

IT administrators can enforce organization-wide settings:

managed-settings.json
// /etc/claude-code/managed-settings.json (Linux/WSL)
// /Library/Application Support/ClaudeCode/managed-settings.json (macOS)
// C:\ProgramData\ClaudeCode\managed-settings.json (Windows)


{
"permissions": {
  "deny": [
    "Bash(rm -rf:*)",
    "WebFetch(domain:competitor.com)"
  ],
  "disableBypassPermissionsMode": "disable"
},
"env": {
  "CORPORATE_PROXY": "proxy.company.com:8080",
  "CLAUDE_CODE_ENABLE_TELEMETRY": "0"
},
"forceLoginMethod": "console",
"model": "claude-sonnet-4"
}

API Key Management

Section titled “API Key Management”

For enterprise deployments with rotating credentials:

  1. Create key helper script

    ~/bin/get-api-key.sh
    #!/bin/bash
    # Fetch from vault
    vault kv get -field=api_key secret/claude-code
    

    # Or from AWS Secrets Manager
    aws secretsmanager get-secret-value \
      --secret-id claude-code-api-key \
      --query SecretString --output text

  2. Configure Claude Code

    {
      "apiKeyHelper": "~/bin/get-api-key.sh"
    }

  3. Set refresh interval

    Terminal window
    export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000  # 1 hour

Advanced Settings

Section titled “Advanced Settings”

Hooks Configuration

Section titled “Hooks Configuration”

Automate workflows with pre/post tool hooks:

{
"hooks": {
  "PreToolUse": {
    "Edit": "npm run pre-edit-checks",
    "Bash": "echo 'Executing: $COMMAND'"
  },
  "PostToolUse": {
    "Edit": "npm run format",
    "MultiEdit": "git add -A"
  }
}
}

Custom Slash Commands

Section titled “Custom Slash Commands”

Create reusable commands in .claude/commands/:

.claude/commands/test-component.md
---
name: test-component
description: Run tests for a React component
---


npm test -- --testNamePattern="$ARGUMENTS" --coverage

MCP Server Configuration

Section titled “MCP Server Configuration”

Configure Model Context Protocol servers:

.mcp.json
{
"mcpServers": {
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  },
  "postgres": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-postgres",
      "postgresql://localhost/mydb"
    ]
  }
}
}

Troubleshooting Configuration

Section titled “Troubleshooting Configuration”

Common Issues

Section titled “Common Issues”

Check precedence order:

Terminal window
# View effective settings
claude config list


# Check which file is being used
claude config get model -v

Best Practices

Section titled “Best Practices”

Configuration Tips

  1. Start with defaults - Only override what you need
  2. Use project settings - Share common configurations with your team
  3. Keep secrets local - Use .claude/settings.local.json for API keys
  4. Document custom settings - Add comments in your CLAUDE.md
  5. Review permissions regularly - Audit allowed tools periodically
  6. Use environment variables - For temporary overrides
  7. Leverage hooks - Automate repetitive tasks
  8. Test configurations - Verify settings work across team members

Next Steps

Section titled “Next Steps”
Initialize Your First Project Create a CLAUDE.md file and set up project context
IDE Integration Connect Claude Code with your favorite editor

Configuration Reference

Section titled “Configuration Reference”
SettingTypeScopeDescription
modelstringAllPrimary model selection
autoUpdatesbooleanGlobalEnable auto-updates
themestringGlobalUI theme (dark/light)
permissionsobjectAllPermission rules
envobjectAllEnvironment variables
hooksobjectAllTool execution hooks
allowedToolsarrayAllPermitted tools list
additionalDirectoriesarrayAllExtra working directories
cleanupPeriodDaysnumberAllChat history retention