Claude Code settings

Configure Claude Code with global and project-level settings, and environment variables.

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, which opens a tabbed Settings interface where you can view status information and modify configuration options.

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
• Enterprise deployments can also configure managed MCP servers that override user-configured servers. See Enterprise MCP configuration:
  • macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
  • Linux and WSL: /etc/claude-code/managed-mcp.json
  • Windows: C:\ProgramData\ClaudeCode\managed-mcp.json
• Other configuration is stored in ~/.claude.json. This file contains your preferences (theme, notification settings, editor mode), OAuth session, MCP server configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in .mcp.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"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

Available settings

settings.json supports a number of options:

Permission settings

Sandbox settings

Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See Sandboxing for details.

Filesystem and network restrictions are configured via Read, Edit, and WebFetch permission rules, not via these sandbox settings.

Configuration example:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)"
    ]
  }
}

Filesystem access is controlled via Read/Edit permissions:

• Read deny rules block file reads in sandbox
• Edit allow rules permit file writes (in addition to the defaults, e.g. the current working directory)
• Edit deny rules block writes within allowed paths

Network access is controlled via WebFetch permissions:

• WebFetch allow rules permit network domains
• WebFetch deny rules block network domains

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.

Plugin configuration

Claude Code supports a plugin system that lets you extend functionality with custom commands, agents, hooks, and MCP servers. Plugins are distributed through marketplaces and can be configured at both user and repository levels.

Plugin settings

Plugin-related settings in settings.json:

{
  "enabledPlugins": {
    "formatter@company-tools": true,
    "deployer@company-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": "github",
      "repo": "company/claude-plugins"
    }
  }
}

enabledPlugins

Controls which plugins are enabled. Format: "plugin-name@marketplace-name": true/false

Scopes:

• User settings (~/.claude/settings.json): Personal plugin preferences
• Project settings (.claude/settings.json): Project-specific plugins shared with team
• Local settings (.claude/settings.local.json): Per-machine overrides (not committed)

Example:

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

extraKnownMarketplaces

Defines additional marketplaces that should be made available for the repository. Typically used in repository-level settings to ensure team members have access to required plugin sources.

When a repository includes extraKnownMarketplaces:

1. Team members are prompted to install the marketplace when they trust the folder
2. Team members are then prompted to install plugins from that marketplace
3. Users can skip unwanted marketplaces or plugins (stored in user settings)
4. Installation respects trust boundaries and requires explicit consent

Example:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "company-org/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.company.com/security/plugins.git"
      }
    }
  }
}

Marketplace source types:

• github: GitHub repository (uses repo)
• git: Any git URL (uses url)
• directory: Local filesystem path (uses path, for development only)

Managing plugins

Use the /plugin command to manage plugins interactively:

• Browse available plugins from marketplaces
• Install/uninstall plugins
• Enable/disable plugins
• View plugin details (commands, agents, hooks provided)
• Add/remove marketplaces

Learn more about the plugin system in the plugins documentation.

Environment variables

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

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. Also see Tool-specific permission rules.

Bash tool behavior

The Bash tool executes shell commands with the following persistence behavior:

• Working directory persists: When Claude changes the working directory (e.g., cd /path/to/dir), subsequent Bash commands will execute in that directory. You can use CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 to reset to the project directory after each command.
• Environment variables do NOT persist: Environment variables set in one Bash command (e.g., export MY_VAR=value) are not available in subsequent Bash commands. Each Bash command runs in a fresh shell environment.

To make environment variables available in Bash commands, you have three options:

Option 1: Activate environment before starting Claude Code (simplest approach)

Activate your virtual environment in your terminal before launching Claude Code:

conda activate myenv
# or: source /path/to/venv/bin/activate
claude

This works for shell environments but environment variables set within Claude's Bash commands will not persist between commands.

Option 2: Set CLAUDE_ENV_FILE before starting Claude Code (persistent environment setup)

Export the path to a shell script containing your environment setup:

export CLAUDE_ENV_FILE=/path/to/env-setup.sh
claude

Where /path/to/env-setup.sh contains:

conda activate myenv
# or: source /path/to/venv/bin/activate
# or: export MY_VAR=value

Claude Code will source this file before each Bash command, making the environment persistent across all commands.

Option 3: Use a SessionStart hook (project-specific configuration)

Configure in .claude/settings.json:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""
      }]
    }]
  }
}

The hook writes to $CLAUDE_ENV_FILE, which is then sourced before each Bash command. This is ideal for team-shared project configurations.

See SessionStart hooks for more details on Option 3.

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

To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt