SpyBara
Go Premium

settings.md 2026-03-09 21:06 UTC to 2026-03-10 03:43 UTC

20 added, 11 removed.

2026
Tue 31 21:09 Mon 30 21:13 Sat 28 18:04 Fri 27 21:09 Thu 26 21:07 Wed 25 21:08 Tue 24 18:15 Mon 23 21:08 Sun 22 18:04 Sat 21 18:03 Fri 20 21:05 Thu 19 06:17 Wed 18 18:16 Tue 17 21:10 Mon 16 21:10 Sat 14 03:44 Fri 13 21:07 Thu 12 21:07 Wed 11 03:43 Tue 10 03:43 Mon 9 21:06 Sat 7 03:37 Fri 6 06:10 Thu 5 06:12 Wed 4 21:06 Sun 1 06:10

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

Scope Location Who it affects Shared with team?
Managed Server-managed settings, plist / registry, or system-level managed-settings.json All users on the machine Yes (deployed by IT)
User ~/.claude/ directory You, across all projects No
Project .claude/ in repository All collaborators on this repository Yes (committed to git)
Local .claude/settings.local.json You, in this repository only No (gitignored)

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:

Feature User location Project location Local location
Settings ~/.claude/settings.json .claude/settings.json .claude/settings.local.json
Subagents ~/.claude/agents/ .claude/agents/ —
MCP servers ~/.claude.json .mcp.json ~/.claude.json (per-project)
Plugins ~/.claude/settings.json .claude/settings.json .claude/settings.local.json
CLAUDE.md ~/.claude/CLAUDE.md CLAUDE.md or .claude/CLAUDE.md —

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 multiple delivery mechanisms for managed settings. All use the same JSON format and cannot be overridden by user or project settings:

    • Server-managed settings: delivered from Anthropic's servers via the Claude.ai admin console. See server-managed settings.
    • MDM/OS-level policies: delivered through native device management on macOS and Windows:
      • macOS: com.anthropic.claudecode managed preferences domain (deployed via configuration profiles in Jamf, Kandji, or other MDM tools)
      • Windows: HKLM\SOFTWARE\Policies\ClaudeCode registry key with a Settings value (REG_SZ or REG_EXPAND_SZ) containing JSON (deployed via Group Policy or Intune)
      • Windows (user-level): HKCU\SOFTWARE\Policies\ClaudeCode (lowest policy priority, only used when no admin-level source exists)
    • File-based: managed-settings.json and managed-mcp.json 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:

Key Description Example
apiKeyHelper Custom script, to be executed in /bin/sh, to generate an auth value. This value will be sent as X-Api-Key and Authorization: Bearer headers for model requests /bin/generate_temp_api_key.sh
cleanupPeriodDays Sessions inactive for longer than this period are deleted at startup. Setting to 0 immediately deletes all sessions. (default: 30 days) 20
companyAnnouncements Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. ["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]
env Environment variables that will be applied to every session {"FOO": "bar"}
attribution Customize attribution for git commits and pull requests. See Attribution settings {"commit": "🤖 Generated with Claude Code", "pr": ""}
includeCoAuthoredBy Deprecated: Use attribution instead. Whether to include the co-authored-by Claude byline in git commits and pull requests (default: true) false
includeGitInstructions Include built-in commit and PR workflow instructions in Claude's system prompt (default: true). Set to false to remove these instructions, for example when using your own git workflow skills. The CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS environment variable takes precedence over this setting when set false
permissions See table below for structure of permissions.
hooks Configure custom commands to run at lifecycle events. See hooks documentation for format See hooks
disableAllHooks Disable all hooks and any custom status line true
allowManagedHooksOnly (Managed settings only) Prevent loading of user, project, and plugin hooks. Only allows managed hooks and SDK hooks. See Hook configuration true
allowedHttpHookUrls Allowlist of URL patterns that HTTP hooks may target. Supports * as a wildcard. When set, hooks with non-matching URLs are blocked. Undefined = no restriction, empty array = block all HTTP hooks. Arrays merge across settings sources. See Hook configuration ["https://hooks.example.com/*"]
httpHookAllowedEnvVars Allowlist of environment variable names HTTP hooks may interpolate into headers. When set, each hook's effective allowedEnvVars is the intersection with this list. Undefined = no restriction. Arrays merge across settings sources. See Hook configuration ["MY_TOKEN", "HOOK_SECRET"]
allowManagedPermissionRulesOnly (Managed settings only) Prevent user and project settings from defining allow, ask, or deny permission rules. Only rules in managed settings apply. See Managed-only settings true
allowManagedMcpServersOnly (Managed settings only) Only allowedMcpServers from managed settings are respected. deniedMcpServers still merges from all sources. Users can still add MCP servers, but only the admin-defined allowlist applies. See Managed MCP configuration true
model Override the default model to use for Claude Code "claude-sonnet-4-6"
availableModels Restrict which models users can select via /model, --model, Config tool, or ANTHROPIC_MODEL. Does not affect the Default option. See Restrict model selection ["sonnet", "haiku"]
otelHeadersHelper Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically (see Dynamic headers) /bin/generate_otel_headers.sh
statusLine Configure a custom status line to display context. See statusLine documentation {"type": "command", "command": "~/.claude/statusline.sh"}
fileSuggestion Configure a custom script for @ file autocomplete. See File suggestion settings {"type": "command", "command": "~/.claude/file-suggestion.sh"}
respectGitignore Control whether the @ file picker respects .gitignore patterns. When true (default), files matching .gitignore patterns are excluded from suggestions false
outputStyle Configure an output style to adjust the system prompt. See output styles documentation "Explanatory"
forceLoginMethod Use claudeai to restrict login to Claude.ai accounts, console to restrict login to Claude Console (API usage billing) accounts claudeai
forceLoginOrgUUID Specify the UUID of an organization to automatically select it during login, bypassing the organization selection step. Requires forceLoginMethod to be set "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
enableAllProjectMcpServers Automatically approve all MCP servers defined in project .mcp.json files true
enabledMcpjsonServers List of specific MCP servers from .mcp.json files to approve ["memory", "github"]
disabledMcpjsonServers List of specific MCP servers from .mcp.json files to reject ["filesystem"]
allowedMcpServers When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See Managed MCP configuration [{ "serverName": "github" }]
deniedMcpServers When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including managed servers. Denylist takes precedence over allowlist. See Managed MCP configuration [{ "serverName": "filesystem" }]
strictKnownMarketplaces When set in managed-settings.json, allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See Managed marketplace restrictions [{ "source": "github", "repo": "acme-corp/plugins" }]
blockedMarketplaces (Managed settings only) Blocklist of marketplace sources. Blocked sources are checked before downloading, so they never touch the filesystem. See Managed marketplace restrictions [{ "source": "github", "repo": "untrusted/plugins" }]
pluginTrustMessage (Managed settings only) Custom message appended to the plugin trust warning shown before installation. Use this to add organization-specific context, for example to confirm that plugins from your internal marketplace are vetted. "All plugins from our marketplace are approved by IT"
awsAuthRefresh Custom script that modifies the .aws directory (see advanced credential configuration) aws sso login --profile myprofile
awsCredentialExport Custom script that outputs JSON with AWS credentials (see advanced credential configuration) /bin/generate_aws_grant.sh
alwaysThinkingEnabled Enable extended thinking by default for all sessions. Typically configured via the /config command rather than editing directly true
plansDirectory Customize where plan files are stored. Path is relative to project root. Default: ~/.claude/plans "./plans"
showTurnDuration Show turn duration messages after responses (e.g., "Cooked for 1m 6s"). Set to false to hide these messages true
spinnerVerbs Customize the action verbs shown in the spinner and turn duration messages. Set mode to "replace" to use only your verbs, or "append" to add them to the defaults {"mode": "append", "verbs": ["Pondering", "Crafting"]}
language Configure Claude's preferred response language (e.g., "japanese", "spanish", "french"). Claude will respond in this language by default "japanese"
autoUpdatesChannel Release channel to follow for updates. Use "stable" for a version that is typically about one week old and skips versions with major regressions, or "latest" (default) for the most recent release "stable"
spinnerTipsEnabled Show tips in the spinner while Claude is working. Set to false to disable tips (default: true) false
spinnerTipsOverride Override spinner tips with custom strings. tips: array of tip strings. excludeDefault: if true, only show custom tips; if false or absent, custom tips are merged with built-in tips { "excludeDefault": true, "tips": ["Use our internal tool X"] }
terminalProgressBarEnabled Enable the terminal progress bar that shows progress in supported terminals like Windows Terminal and iTerm2 (default: true) false
prefersReducedMotion Reduce or disable UI animations (spinners, shimmer, flash effects) for accessibility true
fastModePerSessionOptIn When true, fast mode does not persist across sessions. Each session starts with fast mode off, requiring users to enable it with /fast. The user's fast mode preference is still saved. See Require per-session opt-in true
teammateMode How agent team teammates display: auto (picks split panes in tmux or iTerm2, in-process otherwise), in-process, or tmux. See set up agent teams "in-process"

Permission settings

Keys Description Example
allow Array of permission rules to allow tool use. See Permission rule syntax below for pattern matching details [ "Bash(git diff *)" ]
ask Array of permission rules to ask for confirmation upon tool use. See Permission rule syntax below [ "Bash(git push *)" ]
deny Array of permission rules to deny tool use. Use this to exclude sensitive files from Claude Code access. See Permission rule syntax and Bash permission limitations [ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]
additionalDirectories Additional working directories that Claude has access to [ "../docs/" ]
defaultMode Default permission mode when opening Claude Code "acceptEdits"
disableBypassPermissionsMode Set to "disable" to prevent bypassPermissions mode from being activated. This disables the --dangerously-skip-permissions command-line flag. See managed settings "disable"

Permission rule syntax

Permission rules follow the format Tool or Tool(specifier). Rules are evaluated in order: deny rules first, then ask, then allow. The first matching rule wins.

Quick examples:

Rule Effect
Bash Matches all Bash commands
Bash(npm run *) Matches commands starting with npm run
Read(./.env) Matches reading the .env file
WebFetch(domain:example.com) Matches fetch requests to example.com

For the complete rule syntax reference, including wildcard behavior, tool-specific patterns for Read, Edit, WebFetch, MCP, and Agent rules, and security limitations of Bash patterns, see Permission rule syntax.

Sandbox settings

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

Keys Description Example
enabled Enable bash sandboxing (macOS, Linux, and WSL2). Default: false true
autoAllowBashIfSandboxed Auto-approve bash commands when sandboxed. Default: true true
excludedCommands Commands that should run outside of the sandbox ["git", "docker"]
allowUnsandboxedCommands Allow commands to run outside the sandbox via the dangerouslyDisableSandbox parameter. When set to false, the dangerouslyDisableSandbox escape hatch is completely disabled and all commands must run sandboxed (or be in excludedCommands). Useful for enterprise policies that require strict sandboxing. Default: true false
filesystem.allowWrite Additional paths where sandboxed commands can write. Arrays are merged across all settings scopes: user, project, and managed paths are combined, not replaced. Also merged with paths from Edit(...) allow permission rules. See path prefixes below. ["//tmp/build", "~/.kube"]
filesystem.denyWrite Paths where sandboxed commands cannot write. Arrays are merged across all settings scopes. Also merged with paths from Edit(...) deny permission rules. ["//etc", "//usr/local/bin"]
filesystem.denyRead Paths where sandboxed commands cannot read. Arrays are merged across all settings scopes. Also merged with paths from Read(...) deny permission rules. ["~/.aws/credentials"]
network.allowUnixSockets Unix socket paths accessible in sandbox (for SSH agents, etc.) ["~/.ssh/agent-socket"]
network.allowAllUnixSockets Allow all Unix socket connections in sandbox. Default: false true
network.allowLocalBinding Allow binding to localhost ports (macOS only). Default: false true
network.allowedDomains Array of domains to allow for outbound network traffic. Supports wildcards (e.g., *.example.com). ["github.com", "*.npmjs.org"]
network.allowManagedDomainsOnly (Managed settings only) Only allowedDomains and WebFetch(domain:...) allow rules from managed settings are respected. Domains from user, project, and local settings are ignored. Non-allowed domains are blocked automatically without prompting the user. Denied domains are still respected from all sources. Default: false true
network.httpProxyPort HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. 8080
network.socksProxyPort SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. 8081
enableWeakerNestedSandbox Enable weaker sandbox for unprivileged Docker environments (Linux and WSL2 only). Reduces security. Default: false true
enableWeakerNetworkIsolation (macOS only) Allow access to the system TLS trust service (com.apple.trustd.agent) in the sandbox. Required for Go-based tools like gh, gcloud, and terraform to verify TLS certificates when using httpProxyPort with a MITM proxy and custom CA. Reduces security by opening a potential data exfiltration path. Default: false true

Sandbox path prefixes

Paths in filesystem.allowWrite, filesystem.denyWrite, and filesystem.denyRead support these prefixes:

Prefix Meaning Example
// Absolute path from filesystem root //tmp/build becomes /tmp/build
~/ Relative to home directory ~/.kube becomes $HOME/.kube
/ Relative to the settings file's directory /build becomes $SETTINGS_DIR/build
./ or no prefix Relative path (resolved by sandbox runtime) ./output

Configuration example:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "filesystem": {
      "allowWrite": ["//tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  }
}

Filesystem and network restrictions can be configured in two ways that are merged together:

  • sandbox.filesystem settings (shown above): Control paths at the OS-level sandbox boundary. These restrictions apply to all subprocess commands (e.g., kubectl, terraform, npm), not just Claude's file tools.
  • Permission rules: Use Edit allow/deny rules to control Claude's file tool access, Read deny rules to block reads, and WebFetch allow/deny rules to control network domains. Paths from these rules are also merged into the sandbox configuration.

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
Keys Description
commit Attribution for git commits, including any trailers. Empty string hides commit attribution
pr Attribution for pull request descriptions. Empty string hides pull request attribution

Default commit attribution:

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

   Co-Authored-By: Claude Sonnet 4.6 <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

These settings control which hooks are allowed to run and what HTTP hooks can access. The allowManagedHooksOnly setting can only be configured in managed settings. The URL and env var allowlists can be set at any settings level and merge across sources.

Behavior when allowManagedHooksOnly is true:

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

Restrict HTTP hook URLs:

Limit which URLs HTTP hooks can target. Supports * as a wildcard for matching. When the array is defined, HTTP hooks targeting non-matching URLs are silently blocked.

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

Restrict HTTP hook environment variables:

Limit which environment variable names HTTP hooks can interpolate into header values. Each hook's effective allowedEnvVars is the intersection of its own list and this setting.

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

Settings precedence

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

  1. Managed settings (server-managed, MDM/OS-level policies, or managed settings)

    • Policies deployed by IT through server delivery, MDM configuration profiles, registry policies, or managed settings files
    • Cannot be overridden by any other level, including command line arguments
    • Within the managed tier, precedence is: server-managed > MDM/OS-level policies > managed-settings.json > HKCU registry (Windows only). Only one managed source is used; sources do not merge.

  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.

Verify active settings

Run /status inside Claude Code to see which settings sources are active and where they come from. The output shows each configuration layer (managed, user, project) along with its origin, such as Enterprise managed settings (remote), Enterprise managed settings (plist), Enterprise managed settings (HKLM), or Enterprise managed settings (file). If a settings file contains errors, /status reports the issue so you can fix it.

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 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)

  1. 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)

  1. 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)

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

Fields: package (required, supports scoped packages)

  1. 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)

  1. 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)

  1. 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:

Aspect strictKnownMarketplaces extraKnownMarketplaces
Purpose Organizational policy enforcement Team convenience
Settings file managed-settings.json only Any settings file
Behavior Blocks non-allowlisted additions Auto-installs missing marketplaces
When enforced Before network/filesystem operations After user trust prompt
Can be overridden No (highest precedence) Yes (by higher precedence settings)
Source format Direct source object Named marketplace with nested source
Use case Compliance, security restrictions Onboarding, standardization

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:

Variable Purpose
ANTHROPIC_API_KEY API key sent as X-Api-Key header, typically for the Claude SDK (for interactive usage, run /login)
ANTHROPIC_AUTH_TOKEN Custom value for the Authorization header (the value you set here will be prefixed with Bearer )
ANTHROPIC_CUSTOM_HEADERS Custom headers to add to requests (Name: Value format, newline-separated for multiple headers)
ANTHROPIC_DEFAULT_HAIKU_MODEL See Model configuration
ANTHROPIC_DEFAULT_OPUS_MODEL See Model configuration
ANTHROPIC_DEFAULT_SONNET_MODEL See Model configuration
ANTHROPIC_FOUNDRY_API_KEY API key for Microsoft Foundry authentication (see Microsoft Foundry)
ANTHROPIC_FOUNDRY_BASE_URL Full base URL for the Foundry resource (for example, https://my-resource.services.ai.azure.com/anthropic). Alternative to ANTHROPIC_FOUNDRY_RESOURCE (see Microsoft Foundry)
ANTHROPIC_FOUNDRY_RESOURCE Foundry resource name (for example, my-resource). Required if ANTHROPIC_FOUNDRY_BASE_URL is not set (see Microsoft Foundry)
ANTHROPIC_MODEL Name of the model setting to use (see Model Configuration)
ANTHROPIC_SMALL_FAST_MODEL [DEPRECATED] Name of Haiku-class model for background tasks
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION Override AWS region for the Haiku-class model when using Bedrock
AWS_BEARER_TOKEN_BEDROCK Bedrock API key for authentication (see Bedrock API keys)
BASH_DEFAULT_TIMEOUT_MS Default timeout for long-running bash commands
BASH_MAX_OUTPUT_LENGTH Maximum number of characters in bash outputs before they are middle-truncated
BASH_MAX_TIMEOUT_MS Maximum timeout the model can set for long-running bash commands
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE Set the percentage of context capacity (1-100) at which auto-compaction triggers. By default, auto-compaction triggers at approximately 95% capacity. Use lower values like 50 to compact earlier. Values above the default threshold have no effect. Applies to both main conversations and subagents. This percentage aligns with the context_window.used_percentage field available in status line
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR Return to the original working directory after each Bash command
CLAUDE_CODE_ACCOUNT_UUID Account UUID for the authenticated user. Used by SDK callers to provide account information synchronously, avoiding a race condition where early telemetry events lack account metadata. Requires CLAUDE_CODE_USER_EMAIL and CLAUDE_CODE_ORGANIZATION_UUID to also be set
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD Set to 1 to load CLAUDE.md files from directories specified with --add-dir. By default, additional directories do not load memory files 1
CLAUDE_CODE_API_KEY_HELPER_TTL_MS Interval in milliseconds at which credentials should be refreshed (when using apiKeyHelper)
CLAUDE_CODE_CLIENT_CERT Path to client certificate file for mTLS authentication
CLAUDE_CODE_CLIENT_KEY Path to client private key file for mTLS authentication
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE Passphrase for encrypted CLAUDE_CODE_CLIENT_KEY (optional)
CLAUDE_CODE_DISABLE_1M_CONTEXT Set to 1 to disable 1M context window support. When set, 1M model variants are unavailable in the model picker. Useful for enterprise environments with compliance requirements
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING Set to 1 to disable adaptive reasoning for Opus 4.6 and Sonnet 4.6. When disabled, these models fall back to the fixed thinking budget controlled by MAX_THINKING_TOKENS
CLAUDE_CODE_DISABLE_AUTO_MEMORY Set to 1 to disable auto memory. Set to 0 to force auto memory on during the gradual rollout. When disabled, Claude does not create or load auto memory files
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS Set to 1 to remove built-in commit and PR workflow instructions from Claude's system prompt. Useful when using your own git workflow skills. Takes precedence over the includeGitInstructions setting when set
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Set to 1 to disable all background task functionality, including the run_in_background parameter on Bash and subagent tools, auto-backgrounding, and the Ctrl+B shortcut
CLAUDE_CODE_DISABLE_CRON Set to 1 to disable scheduled tasks. The /loop skill and cron tools become unavailable and any already-scheduled tasks stop firing, including tasks that are already running mid-session
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS Set to 1 to disable Anthropic API-specific anthropic-beta headers. Use this if experiencing issues like "Unexpected value(s) for the anthropic-beta header" when using an LLM gateway with third-party providers
CLAUDE_CODE_DISABLE_FAST_MODE Set to 1 to disable fast mode
CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY Set to 1 to disable the "How is Claude doing?" session quality surveys. Also disabled when using third-party providers or when telemetry is disabled. See Session quality surveys
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC Equivalent of setting DISABLE_AUTOUPDATER, DISABLE_BUG_COMMAND, DISABLE_ERROR_REPORTING, and DISABLE_TELEMETRY
CLAUDE_CODE_DISABLE_TERMINAL_TITLE Set to 1 to disable automatic terminal title updates based on conversation context
CLAUDE_CODE_EFFORT_LEVEL Set the effort level for supported models. Values: low, medium, high. Lower effort is faster and cheaper, higher effort provides deeper reasoning. Supported on Opus 4.6 and Sonnet 4.6. See Adjust effort level
CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION Set to false to disable prompt suggestions (the "Prompt suggestions" toggle in /config). These are the grayed-out predictions that appear in your prompt input after Claude responds. See Prompt suggestions
CLAUDE_CODE_ENABLE_TASKS Set to false to temporarily revert to the previous TODO list instead of the task tracking system. Default: true. See Task list
CLAUDE_CODE_ENABLE_TELEMETRY Set to 1 to enable OpenTelemetry data collection for metrics and logging. Required before configuring OTel exporters. See Monitoring
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY Time in milliseconds to wait after the query loop becomes idle before automatically exiting. Useful for automated workflows and scripts using SDK mode
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS Set to 1 to enable agent teams. Agent teams are experimental and disabled by default
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS Override the default token limit for file reads. Useful when you need to read larger files in full
CLAUDE_CODE_HIDE_ACCOUNT_INFO Set to 1 to hide your email address and organization name from the Claude Code UI. Useful when streaming or recording
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL Skip auto-installation of IDE extensions
CLAUDE_CODE_MAX_OUTPUT_TOKENS Set the maximum number of output tokens for most requests. Default: 32,000. Maximum: 64,000. Increasing this value reduces the effective context window available before auto-compaction triggers.
CLAUDE_CODE_ORGANIZATION_UUID Organization UUID for the authenticated user. Used by SDK callers to provide account information synchronously. Requires CLAUDE_CODE_ACCOUNT_UUID and CLAUDE_CODE_USER_EMAIL to also be set
CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS Interval for refreshing dynamic OpenTelemetry headers in milliseconds (default: 1740000 / 29 minutes). See Dynamic headers
CLAUDE_CODE_PLAN_MODE_REQUIRED Auto-set to true on agent team teammates that require plan approval. Read-only: set by Claude Code when spawning teammates. See require plan approval
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS Timeout in milliseconds for git operations when installing or updating plugins (default: 120000). Increase this value for large repositories or slow network connections. See Git operations time out
CLAUDE_CODE_PROXY_RESOLVES_HOSTS Set to true to allow the proxy to perform DNS resolution instead of the caller. Opt-in for environments where the proxy should handle hostname resolution
CLAUDE_CODE_SHELL Override automatic shell detection. Useful when your login shell differs from your preferred working shell (for example, bash vs zsh)
CLAUDE_CODE_SHELL_PREFIX Command prefix to wrap all bash commands (for example, for logging or auditing). Example: /path/to/logger.sh will execute /path/to/logger.sh <command>
CLAUDE_CODE_SIMPLE Set to 1 to run with a minimal system prompt and only the Bash, file read, and file edit tools. Disables MCP tools, attachments, hooks, and CLAUDE.md files
CLAUDE_CODE_SKIP_BEDROCK_AUTH Skip AWS authentication for Bedrock (for example, when using an LLM gateway)
CLAUDE_CODE_SKIP_FOUNDRY_AUTH Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway)
CLAUDE_CODE_SKIP_VERTEX_AUTH Skip Google authentication for Vertex (for example, when using an LLM gateway)
CLAUDE_CODE_SUBAGENT_MODEL See Model configuration
CLAUDE_CODE_TASK_LIST_ID Share a task list across sessions. Set the same ID in multiple Claude Code instances to coordinate on a shared task list. See Task list
CLAUDE_CODE_TEAM_NAME Name of the agent team this teammate belongs to. Set automatically on agent team members
CLAUDE_CODE_TMPDIR Override the temp directory used for internal temp files. Claude Code appends /claude/ to this path. Default: /tmp on Unix/macOS, os.tmpdir() on Windows
CLAUDE_CODE_USER_EMAIL Email address for the authenticated user. Used by SDK callers to provide account information synchronously. Requires CLAUDE_CODE_ACCOUNT_UUID and CLAUDE_CODE_ORGANIZATION_UUID to also be set
CLAUDE_CODE_USE_BEDROCK Use Bedrock
CLAUDE_CODE_USE_FOUNDRY Use Microsoft Foundry
CLAUDE_CODE_USE_VERTEX Use Vertex
CLAUDE_CONFIG_DIR Customize where Claude Code stores its configuration and data files
DISABLE_AUTOUPDATER Set to 1 to disable automatic updates.
DISABLE_BUG_COMMAND Set to 1 to disable the /bug command
DISABLE_COST_WARNINGS Set to 1 to disable cost warning messages
DISABLE_ERROR_REPORTING Set to 1 to opt out of Sentry error reporting
DISABLE_INSTALLATION_CHECKS Set to 1 to disable installation warnings. Use only when manually managing the installation location, as this can mask issues with standard installations
DISABLE_NON_ESSENTIAL_MODEL_CALLS Set to 1 to disable model calls for non-critical paths like flavor text
DISABLE_PROMPT_CACHING Set to 1 to disable prompt caching for all models (takes precedence over per-model settings)
DISABLE_PROMPT_CACHING_HAIKU Set to 1 to disable prompt caching for Haiku models
DISABLE_PROMPT_CACHING_OPUS Set to 1 to disable prompt caching for Opus models
DISABLE_PROMPT_CACHING_SONNET Set to 1 to disable prompt caching for Sonnet models
DISABLE_TELEMETRY Set to 1 to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands)
ENABLE_CLAUDEAI_MCP_SERVERS Set to false to disable claude.ai MCP servers in Claude Code. Enabled by default for logged-in users
ENABLE_TOOL_SEARCH Controls MCP tool search. Values: auto (default, enables at 10% context), auto:N (custom threshold, e.g., auto:5 for 5%), true (always on), false (disabled)
FORCE_AUTOUPDATE_PLUGINS Set to true to force plugin auto-updates even when the main auto-updater is disabled via DISABLE_AUTOUPDATER
HTTP_PROXY Specify HTTP proxy server for network connections
HTTPS_PROXY Specify HTTPS proxy server for network connections
IS_DEMO Set to true to enable demo mode: hides email and organization from the UI, skips onboarding, and hides internal commands. Useful for streaming or recording sessions
MAX_MCP_OUTPUT_TOKENS Maximum number of tokens allowed in MCP tool responses. Claude Code displays a warning when output exceeds 10,000 tokens (default: 25000)
MAX_THINKING_TOKENS Override the extended thinking token budget. Thinking is enabled at max budget (31,999 tokens) by default. Use this to limit the budget (for example, MAX_THINKING_TOKENS=10000) or disable thinking entirely (MAX_THINKING_TOKENS=0). For Opus 4.6, thinking depth is controlled by effort level instead, and this variable is ignored unless set to 0 to disable thinking.
MCP_CLIENT_SECRET OAuth client secret for MCP servers that require pre-configured credentials. Avoids the interactive prompt when adding a server with --client-secret
MCP_OAUTH_CALLBACK_PORT Fixed port for the OAuth redirect callback, as an alternative to --callback-port when adding an MCP server with pre-configured credentials
MCP_TIMEOUT Timeout in milliseconds for MCP server startup
MCP_TOOL_TIMEOUT Timeout in milliseconds for MCP tool execution
NO_PROXY List of domains and IPs to which requests will be directly issued, bypassing proxy
SLASH_COMMAND_TOOL_CHAR_BUDGET Override the character budget for skill metadata shown to the Skill tool. The budget scales dynamically at 2% of the context window, with a fallback of 16,000 characters. Legacy name kept for backwards compatibility
USE_BUILTIN_RIPGREP Set to 0 to use system-installed rg instead of rg included with Claude Code
VERTEX_REGION_CLAUDE_3_5_HAIKU Override region for Claude 3.5 Haiku when using Vertex AI
VERTEX_REGION_CLAUDE_3_7_SONNET Override region for Claude 3.7 Sonnet when using Vertex AI
VERTEX_REGION_CLAUDE_4_0_OPUS Override region for Claude 4.0 Opus when using Vertex AI
VERTEX_REGION_CLAUDE_4_0_SONNET Override region for Claude 4.0 Sonnet when using Vertex AI
VERTEX_REGION_CLAUDE_4_1_OPUS Override region for Claude 4.1 Opus when using Vertex AI

Tools available to Claude

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

Tool Description Permission Required
Agent Spawns a subagent with its own context window to handle a task No
AskUserQuestion Asks multiple-choice questions to gather requirements or clarify ambiguity No
Bash Executes shell commands in your environment. See Bash tool behavior Yes
CronCreate Schedules a recurring or one-shot prompt within the current session (gone when Claude exits). See scheduled tasks No
CronDelete Cancels a scheduled task by ID No
CronList Lists all scheduled tasks in the session No
Edit Makes targeted edits to specific files Yes
EnterPlanMode Switches to plan mode to design an approach before coding No
EnterWorktree Creates an isolated git worktree and switches into it No
ExitPlanMode Presents a plan for approval and exits plan mode Yes
ExitWorktree Exits a worktree session and returns to the original directory No
Glob Finds files based on pattern matching No
Grep Searches for patterns in file contents No
ListMcpResourcesTool Lists resources exposed by connected MCP servers No
LSP Code intelligence via language servers. Reports type errors and warnings automatically after file edits. Also supports navigation operations: jump to definitions, find references, get type info, list symbols, find implementations, trace call hierarchies. Requires a code intelligence plugin and its language server binary No
NotebookEdit Modifies Jupyter notebook cells Yes
Read Reads the contents of files No
ReadMcpResourceTool Reads a specific MCP resource by URI No
Skill Executes a skill within the main conversation Yes
TaskCreate Creates a new task in the task list No
TaskGet Retrieves full details for a specific task No
TaskList Lists all tasks with their current status No
TaskOutput Retrieves output from a background task No
TaskStop Kills a running background task by ID No
TaskUpdate Updates task status, dependencies, details, or deletes tasks No
TodoWrite Manages the session task checklist. Available in non-interactive mode and the Agent SDK; interactive sessions use TaskCreate, TaskGet, TaskList, and TaskUpdate instead No
ToolSearch Searches for and loads deferred tools when tool search is enabled No
WebFetch Fetches content from a specified URL Yes
WebSearch Performs web searches Yes
Write Creates or overwrites files Yes

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

  • Permissions: permission system, rule syntax, tool-specific patterns, and managed policies
  • Authentication: set up user access to Claude Code
  • Troubleshooting: solutions for common configuration issues