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.

Configuration scopes

Claude Code uses a scope system to determine where configurations apply and who they're shared with. Understanding scopes helps you decide how to configure Claude Code for personal use, team collaboration, or enterprise deployment.

Available scopes

When to use each scope

Managed scope is for:

• Security policies that must be enforced organization-wide
• Compliance requirements that can't be overridden
• Standardized configurations deployed by IT/DevOps

User scope is best for:

• Personal preferences you want everywhere (themes, editor settings)
• Tools and plugins you use across all projects
• API keys and authentication (stored securely)

Project scope is best for:

• Team-shared settings (permissions, hooks, MCP servers)
• Plugins the whole team should have
• Standardizing tooling across collaborators

Local scope is best for:

• Personal overrides for a specific project
• Testing configurations before sharing with the team
• Machine-specific settings that won't work for others

How scopes interact

When the same setting is configured in multiple scopes, more specific scopes take precedence:

1. Managed (highest) - can't be overridden by anything
2. Command line arguments - temporary session overrides
3. Local - overrides project and user settings
4. Project - overrides user settings
5. User (lowest) - applies when nothing else specifies the setting

For example, if a permission is allowed in user settings but denied in project settings, the project setting takes precedence and the permission is blocked.

What uses scopes

Scopes apply to many Claude Code features:

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.

• Managed settings: For organizations that need centralized control, Claude Code supports managed-settings.json and managed-mcp.json files that can be deployed to system directories:

  • macOS: /Library/Application Support/ClaudeCode/
  • Linux and WSL: /etc/claude-code/
  • Windows: C:\Program Files\ClaudeCode\

  See Managed settings and Managed MCP configuration for details.

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

{
  "$schema": "https://json.schemastore.org/claude-code-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"
  },
  "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"
  ]
}

The $schema line in the example above points to the official JSON schema for Claude Code settings. Adding it to your settings.json enables autocomplete and inline validation in VS Code, Cursor, and any other editor that supports JSON schema validation.

Available settings

settings.json supports a number of options:

Permission settings

Permission rule syntax

Permission rules follow the format Tool or Tool(specifier). Understanding the syntax helps you write rules that match exactly what you intend.

Rule evaluation order

When multiple rules could match the same tool use, rules are evaluated in this order:

1. Deny rules are checked first
2. Ask rules are checked second
3. Allow rules are checked last

The first matching rule determines the behavior. This means deny rules always take precedence over allow rules, even if both match the same command.

Matching all uses of a tool

To match all uses of a tool, use just the tool name without parentheses:

Bash(*) is equivalent to Bash and matches all Bash commands. Both syntaxes can be used interchangeably.

Using specifiers for fine-grained control

Add a specifier in parentheses to match specific tool uses:

Wildcard patterns

Bash rules support glob patterns with *. Wildcards can appear at any position in the command, including at the beginning, middle, or end. The following configuration allows npm and git commit commands while blocking git push:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

The space before * matters: Bash(ls *) matches ls -la but not lsof, while Bash(ls*) matches both. The legacy :* suffix syntax (e.g., Bash(npm run:*)) is equivalent to * but is deprecated.

For detailed information about tool-specific permission patterns—including Read, Edit, WebFetch, MCP, Task rules, and Bash permission limitations—see Tool-specific permission rules.

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": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)"
    ]
  }
}

Filesystem and network restrictions use standard permission rules:

• Use Read deny rules to block Claude from reading specific files or directories
• Use Edit allow rules to let Claude write to directories beyond the current working directory
• Use Edit deny rules to block writes to specific paths
• Use WebFetch allow/deny rules to control which network domains Claude can access

Attribution settings

Claude Code adds attribution to git commits and pull requests. These are configured separately:

• Commits use git trailers (like Co-Authored-By) by default, which can be customized or disabled
• Pull request descriptions are plain text

Default commit attribution:

🤖 Generated with [Claude Code](https://claude.com/claude-code)

   Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Default pull request attribution:

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Example:

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": ""
  }
}

File suggestion settings

Configure a custom command for @ file path autocomplete. The built-in file suggestion uses fast filesystem traversal, but large monorepos may benefit from project-specific indexing such as a pre-built file index or custom tooling.

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

The command runs with the same environment variables as hooks, including CLAUDE_PROJECT_DIR. It receives JSON via stdin with a query field:

{"query": "src/comp"}

Output newline-separated file paths to stdout (currently limited to 15):

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

Example:

#!/bin/bash
query=$(cat | jq -r '.query')
your-repo-file-index --query "$query" | head -20

Hook configuration

Managed settings only: Controls which hooks are allowed to run. This setting can only be configured in managed settings and provides administrators with strict control over hook execution.

Behavior when allowManagedHooksOnly is true:

• Managed hooks and SDK hooks are loaded
• User hooks, project hooks, and plugin hooks are blocked

Configuration:

{
  "allowManagedHooksOnly": true
}

Settings precedence

Settings apply in order of precedence. From highest to lowest:

1. Managed settings (managed-settings.json)

   • Policies deployed by IT/DevOps to system directories
   • Cannot be overridden by user or project settings

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 organizational policies are always enforced while still allowing teams and individuals to customize their experience.

For example, if your user settings allow Bash(npm run *) but a project's shared settings deny it, the project setting takes precedence and the command is blocked.

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
• Skills: Custom prompts that can be invoked with /skill-name or loaded by Claude automatically
• MCP servers: Extend Claude Code with additional tools and integrations
• Precedence: Higher-level configurations (Managed) override lower-level ones (User/Project)
• Inheritance: Settings are merged, with more specific settings adding to or overriding broader ones

System prompt

Claude Code's internal system prompt is not published. To add custom instructions, use CLAUDE.md files or the --append-system-prompt flag.

Excluding sensitive files

To prevent Claude Code from accessing files containing sensitive information like API keys, secrets, and 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 are excluded from file discovery and search results, and read operations on these files are denied.

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 skills, 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@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": "github",
      "repo": "acme-corp/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": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.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)
• hostPattern: regex pattern to match marketplace hosts (uses hostPattern)

strictKnownMarketplaces

Managed settings only: Controls which plugin marketplaces users are allowed to add. This setting can only be configured in managed-settings.json and provides administrators with strict control over marketplace sources.

Managed settings file locations:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux and WSL: /etc/claude-code/managed-settings.json
• Windows: C:\Program Files\ClaudeCode\managed-settings.json

Key characteristics:

• Only available in managed settings (managed-settings.json)
• Cannot be overridden by user or project settings (highest precedence)
• Enforced BEFORE network/filesystem operations (blocked sources never execute)
• Uses exact matching for source specifications (including ref, path for git sources), except hostPattern, which uses regex matching

Allowlist behavior:

• undefined (default): No restrictions - users can add any marketplace
• Empty array []: Complete lockdown - users cannot add any new marketplaces
• List of sources: Users can only add marketplaces that match exactly

All supported source types:

The allowlist supports seven marketplace source types. Most sources use exact matching, while hostPattern uses regex matching against the marketplace host.

1. GitHub repositories:

{ "source": "github", "repo": "acme-corp/approved-plugins" }
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }

Fields: repo (required), ref (optional: branch/tag/SHA), path (optional: subdirectory)

2. Git repositories:

{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }

Fields: url (required), ref (optional: branch/tag/SHA), path (optional: subdirectory)

3. URL-based marketplaces:

{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

Fields: url (required), headers (optional: HTTP headers for authenticated access)

4. NPM packages:

{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

Fields: package (required, supports scoped packages)

5. File paths:

{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

Fields: path (required: absolute path to marketplace.json file)

6. Directory paths:

{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

Fields: path (required: absolute path to directory containing .claude-plugin/marketplace.json)

7. Host pattern matching:

{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }

Fields: hostPattern (required: regex pattern to match against the marketplace host)

Use host pattern matching when you want to allow all marketplaces from a specific host without enumerating each repository individually. This is useful for organizations with internal GitHub Enterprise or GitLab servers where developers create their own marketplaces.

Host extraction by source type:

• github: always matches against github.com
• git: extracts hostname from the URL (supports both HTTPS and SSH formats)
• url: extracts hostname from the URL
• npm, file, directory: not supported for host pattern matching

Configuration examples:

Example: allow specific marketplaces only:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    },
    {
      "source": "npm",
      "package": "@acme-corp/compliance-plugins"
    }
  ]
}

Example - Disable all marketplace additions:

{
  "strictKnownMarketplaces": []
}

Example: allow all marketplaces from an internal git server:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

Exact matching requirements:

Marketplace sources must match exactly for a user's addition to be allowed. For git-based sources (github and git), this includes all optional fields:

• The repo or url must match exactly
• The ref field must match exactly (or both be undefined)
• The path field must match exactly (or both be undefined)

Examples of sources that do NOT match:

// These are DIFFERENT sources:
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

// These are also DIFFERENT:
{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/plugins" }

Comparison with extraKnownMarketplaces:

Format difference:

strictKnownMarketplaces uses direct source objects:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}

extraKnownMarketplaces requires named marketplaces:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

Important notes:

• Restrictions are checked BEFORE any network requests or filesystem operations
• When blocked, users see clear error messages indicating the source is blocked by managed policy
• The restriction applies only to adding NEW marketplaces; previously installed marketplaces remain accessible
• Managed settings have the highest precedence and cannot be overridden

See Managed marketplace restrictions for user-facing documentation.

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 (for example, 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 (for example, 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 - Permission system overview and how allow/ask/deny rules interact
• Tool-specific permission rules - Detailed patterns for Bash, Read, Edit, WebFetch, MCP, and Task tools, including security limitations
• Managed settings - Managed policy configuration for organizations
• Troubleshooting - Solutions for common configuration issues