Claude Code settings

Claude Code offers a variety of settings to configure its behavior to meet your needs. You can configure Claude Code by running the /config command when using the interactive REPL.

​

Settings files

The settings.json file is our official mechanism for configuring Claude Code through hierarchical settings:

• User settings are defined in ~/.claude/settings.json and apply to all projects.
• Project settings are saved in your project directory:
  • .claude/settings.json for settings that are checked into source control and shared with your team
  • .claude/settings.local.json for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore .claude/settings.local.json when it is created.
• For enterprise deployments of Claude Code, we also support enterprise managed policy settings. These take precedence over user and project settings. System administrators can deploy policies to:
  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux and WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\ProgramData\ClaudeCode\managed-settings.json

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

​

Available settings

settings.json supports a number of options:

​

Permission settings

​

Settings precedence

Settings are applied in order of precedence (highest to lowest):

1. Enterprise managed policies (managed-settings.json)

   • Deployed by IT/DevOps
   • Cannot be overridden

2. Command line arguments

   • Temporary overrides for a specific session

3. Local project settings (.claude/settings.local.json)

   • Personal project-specific settings

4. Shared project settings (.claude/settings.json)

   • Team-shared project settings in source control

5. User settings (~/.claude/settings.json)

   • Personal global settings

This hierarchy ensures that enterprise security policies are always enforced while still allowing teams and individuals to customize their experience.

​

Key points about the configuration system

• Memory files (CLAUDE.md): Contain instructions and context that Claude loads at startup
• Settings files (JSON): Configure permissions, environment variables, and tool behavior
• Slash commands: Custom commands that can be invoked during a session with /command-name
• MCP servers: Extend Claude Code with additional tools and integrations
• Precedence: Higher-level configurations (Enterprise) override lower-level ones (User/Project)
• Inheritance: Settings are merged, with more specific settings adding to or overriding broader ones

​

System prompt availability

​

Excluding sensitive files

To prevent Claude Code from accessing files containing sensitive information (e.g., API keys, secrets, environment files), use the permissions.deny setting in your .claude/settings.json file:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

This replaces the deprecated ignorePatterns configuration. Files matching these patterns will be completely invisible to Claude Code, preventing any accidental exposure of sensitive data.

​

Subagent configuration

Claude Code supports custom AI subagents that can be configured at both user and project levels. These subagents are stored as Markdown files with YAML frontmatter:

• User subagents: ~/.claude/agents/ - Available across all your projects
• Project subagents: .claude/agents/ - Specific to your project and can be shared with your team

Subagent files define specialized AI assistants with custom prompts and tool permissions. Learn more about creating and using subagents in the subagents documentation.

​

Environment variables

Claude Code supports the following environment variables to control its behavior:

​

Configuration options

To manage your configurations, use the following commands:

• List settings: claude config list
• See a setting: claude config get <key>
• Change a setting: claude config set <key> <value>
• Push to a setting (for lists): claude config add <key> <value>
• Remove from a setting (for lists): claude config remove <key> <value>

By default config changes your project configuration. To manage your global configuration, use the --global (or -g) flag.

​

Global configuration

To set a global configuration, use claude config set -g <key> <value>:

​

Tools available to Claude

Claude Code has access to a set of powerful tools that help it understand and modify your codebase:

Permission rules can be configured using /allowed-tools or in permission settings.

​

Extending tools with hooks

You can run custom commands before or after any tool executes using Claude Code hooks.

For example, you could automatically run a Python formatter after Claude modifies Python files, or prevent modifications to production configuration files by blocking Write operations to certain paths.

​

See also

• Identity and Access Management - Learn about Claude Code’s permission system
• IAM and access control - Enterprise policy management
• Troubleshooting - Solutions for common configuration issues