This page covers system requirements, platform-specific installation details, updates, and uninstallation. For a guided walkthrough of your first session, see the quickstart. If you've never used a terminal before, see the terminal guide.

System requirements

Claude Code runs on the following platforms and configurations:

• Operating system:
  • macOS 13.0+
  • Windows 10 1809+ or Windows Server 2019+
  • Ubuntu 20.04+
  • Debian 10+
  • Alpine Linux 3.19+
• Hardware: 4 GB+ RAM, x64 or ARM64 processor
• Network: internet connection required. See network configuration.
• Shell: Bash, Zsh, PowerShell, or CMD. Native Windows setups require Git for Windows. WSL setups do not.
• Location: Anthropic supported countries

Additional dependencies

• ripgrep: usually included with Claude Code. If search fails, see search troubleshooting.

Install Claude Code

To install Claude Code, use one of the following methods:

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

brew install --cask claude-code

After installation completes, open a terminal in the project you want to work in and start Claude Code:

claude

If you encounter any issues during installation, see the troubleshooting guide.

Set up on Windows

You can run Claude Code natively on Windows or inside WSL. Pick based on where your projects are located and which features you need:

Option 1: Native Windows with Git Bash

Install Git for Windows, then run the install command from PowerShell or CMD. You do not need to run as Administrator.

Whether you install from PowerShell or CMD only affects which install command you run. Your prompt shows PS C:\Users\YourName> in PowerShell and C:\Users\YourName> without the PS in CMD. If you're new to the terminal, the terminal guide walks through each step.

After installation, launch claude from PowerShell, CMD, or Git Bash. Claude Code uses Git Bash internally to execute commands regardless of where you launched it. If Claude Code can't find your Git Bash installation, set the path in your settings.json file:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Claude Code can also run PowerShell natively on Windows as an opt-in preview. See PowerShell tool for setup and limitations.

Option 2: WSL

Open your WSL distribution and run the Linux installer from the install instructions above. You install and launch claude inside the WSL terminal, not from PowerShell or CMD.

Alpine Linux and musl-based distributions

The native installer on Alpine and other musl/uClibc-based distributions requires libgcc, libstdc++, and ripgrep. Install these using your distribution's package manager, then set USE_BUILTIN_RIPGREP=0.

This example installs the required packages on Alpine:

apk add libgcc libstdc++ ripgrep

Then set USE_BUILTIN_RIPGREP to 0 in your settings.json file:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

Verify your installation

After installing, confirm Claude Code is working:

claude --version

For a more detailed check of your installation and configuration, run claude doctor:

claude doctor

Authenticate

Claude Code requires a Pro, Max, Team, Enterprise, or Console account. The free Claude.ai plan does not include Claude Code access. You can also use Claude Code with a third-party API provider like Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.

After installing, log in by running claude and following the browser prompts. See Authentication for all account types and team setup options.

Update Claude Code

Native installations automatically update in the background. You can configure the release channel to control whether you receive updates immediately or on a delayed stable schedule, or disable auto-updates entirely. Homebrew installations require manual updates.

Auto-updates

Claude Code checks for updates on startup and periodically while running. Updates download and install in the background, then take effect the next time you start Claude Code.

Configure release channel

Control which release channel Claude Code follows for auto-updates and claude update with the autoUpdatesChannel setting:

• "latest", the default: receive new features as soon as they're released
• "stable": use a version that is typically about one week old, skipping releases with major regressions

Configure this via /config → Auto-update channel, or add it to your settings.json file:

{
  "autoUpdatesChannel": "stable"
}

For enterprise deployments, you can enforce a consistent release channel across your organization using managed settings.

Homebrew installations choose a channel by cask name instead of this setting: claude-code tracks stable and claude-code@latest tracks latest.

Disable auto-updates

Set DISABLE_AUTOUPDATER to "1" in the env key of your settings.json file:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Update manually

To apply an update immediately without waiting for the next background check, run:

claude update

Advanced installation options

These options are for version pinning, migrating from npm, and verifying binary integrity.

Install a specific version

The native installer accepts either a specific version number or a release channel (latest or stable). The channel you choose at install time becomes your default for auto-updates. See configure release channel for more information.

To install the latest version (default):

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

To install the stable version:

curl -fsSL https://claude.ai/install.sh | bash -s stable

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

To install a specific version number:

curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89

Deprecated npm installation

npm installation is deprecated. The native installer is faster, requires no dependencies, and auto-updates in the background. Use the native installation method when possible.

Migrate from npm to native

If you previously installed Claude Code with npm, switch to the native installer:

# Install the native binary
curl -fsSL https://claude.ai/install.sh | bash

# Remove the old npm installation
npm uninstall -g @anthropic-ai/claude-code

You can also run claude install from an existing npm installation to install the native binary alongside it, then remove the npm version.

Install with npm

If you need npm installation for compatibility reasons, you must have Node.js 18+ installed. Install the package globally:

npm install -g @anthropic-ai/claude-code

Binary integrity and code signing

Each release publishes a manifest.json containing SHA256 checksums for every platform binary. The manifest is signed with an Anthropic GPG key, so verifying the signature on the manifest transitively verifies every binary it lists.

Verify the manifest signature

Steps 1-3 require a POSIX shell with gpg and curl. On Windows, run them in Git Bash or WSL. Step 4 includes a PowerShell option.

curl -fsSL https://downloads.claude.ai/keys/claude-code.asc | gpg --import

gpg --fingerprint [email protected]

31DD DE24 DDFA B679 F42D  7BD2 BAA9 29FF 1A7E CACE

REPO=https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases
VERSION=2.1.89
curl -fsSLO "$REPO/$VERSION/manifest.json"
curl -fsSLO "$REPO/$VERSION/manifest.json.sig"

gpg --verify manifest.json.sig manifest.json

sha256sum claude

shasum -a 256 claude

(Get-FileHash claude.exe -Algorithm SHA256).Hash.ToLower()

Platform code signatures

In addition to the signed manifest, individual binaries carry platform-native code signatures where supported.

• macOS: signed by "Anthropic PBC" and notarized by Apple. Verify with codesign --verify --verbose ./claude.
• Windows: signed by "Anthropic, PBC". Verify with Get-AuthenticodeSignature .\claude.exe.
• Linux: use the manifest signature above to verify integrity. Linux binaries are not individually code-signed.

Uninstall Claude Code

To remove Claude Code, follow the instructions for your installation method.

Native installation

Remove the Claude Code binary and version files:

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Homebrew installation

Remove the Homebrew cask you installed. If you installed the stable cask:

brew uninstall --cask claude-code

If you installed the latest cask:

brew uninstall --cask claude-code@latest

npm

Remove the global npm package:

npm uninstall -g @anthropic-ai/claude-code

Remove configuration files

To remove Claude Code settings and cached data:

# Remove user settings and state
rm -rf ~/.claude
rm ~/.claude.json
Remove project-specific settings (run from your project directory)
rm -rf .claude
rm -f .mcp.json

# Remove user settings and state
Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force
Remove project-specific settings (run from your project directory)
Remove-Item -Path ".claude" -Recurse -Force
Remove-Item -Path ".mcp.json" -Force

Claude Code supports multiple authentication methods depending on your setup. Individual users can log in with a Claude.ai account, while teams can use Claude for Teams or Enterprise, the Claude Console, or a cloud provider like Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.

Log in to Claude Code

After installing Claude Code, run claude in your terminal. On first launch, Claude Code opens a browser window for you to log in.

If the browser doesn't open automatically, press c to copy the login URL to your clipboard, then paste it into your browser.

If your browser shows a login code instead of redirecting back after you sign in, paste it into the terminal at the Paste code here if prompted prompt.

You can authenticate with any of these account types:

• Claude Pro or Max subscription: log in with your Claude.ai account. Subscribe at claude.com/pricing.
• Claude for Teams or Enterprise: log in with the Claude.ai account your team admin invited you to.
• Claude Console: log in with your Console credentials. Your admin must have invited you first.
• Cloud providers: if your organization uses Amazon Bedrock, Google Vertex AI, or Microsoft Foundry, set the required environment variables before running claude. No browser login is needed.

To log out and re-authenticate, type /logout at the Claude Code prompt.

If you're having trouble logging in, see authentication troubleshooting.

Set up team authentication

For teams and organizations, you can configure Claude Code access in one of these ways:

• Claude for Teams or Enterprise, recommended for most teams
• Claude Console
• Amazon Bedrock
• Google Vertex AI
• Microsoft Foundry

Claude for Teams or Enterprise

Claude for Teams and Claude for Enterprise provide the best experience for organizations using Claude Code. Team members get access to both Claude Code and Claude on the web with centralized billing and team management.

• Claude for Teams: self-service plan with collaboration features, admin tools, and billing management. Best for smaller teams.
• Claude for Enterprise: adds SSO, domain capture, role-based permissions, compliance API, and managed policy settings for organization-wide Claude Code configurations. Best for larger organizations with security and compliance requirements.

Claude Console authentication

For organizations that prefer API-based billing, you can set up access through the Claude Console.

Cloud provider authentication

For teams using Amazon Bedrock, Google Vertex AI, or Microsoft Foundry:

Credential management

Claude Code securely manages your authentication credentials:

• Storage location: on macOS, credentials are stored in the encrypted macOS Keychain. On Linux and Windows, credentials are stored in ~/.claude/.credentials.json, or under $CLAUDE_CONFIG_DIR if that variable is set. On Linux, the file is written with mode 0600; on Windows, it inherits the access controls of your user profile directory.
• Supported authentication types: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.
• Custom credential scripts: the apiKeyHelper setting can be configured to run a shell script that returns an API key.
• Refresh intervals: by default, apiKeyHelper is called after 5 minutes or on HTTP 401 response. Set CLAUDE_CODE_API_KEY_HELPER_TTL_MS environment variable for custom refresh intervals.
• Slow helper notice: if apiKeyHelper takes longer than 10 seconds to return a key, Claude Code displays a warning notice in the prompt bar showing the elapsed time. If you see this notice regularly, check whether your credential script can be optimized.

apiKeyHelper, ANTHROPIC_API_KEY, and ANTHROPIC_AUTH_TOKEN apply to terminal CLI sessions only. Claude Desktop and remote sessions use OAuth exclusively and do not call apiKeyHelper or read API key environment variables.

Authentication precedence

When multiple credentials are present, Claude Code chooses one in this order:

1. Cloud provider credentials, when CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, or CLAUDE_CODE_USE_FOUNDRY is set. See third-party integrations for setup.
2. ANTHROPIC_AUTH_TOKEN environment variable. Sent as the Authorization: Bearer header. Use this when routing through an LLM gateway or proxy that authenticates with bearer tokens rather than Anthropic API keys.
3. ANTHROPIC_API_KEY environment variable. Sent as the X-Api-Key header. Use this for direct Anthropic API access with a key from the Claude Console. In interactive mode, you are prompted once to approve or decline the key, and your choice is remembered. To change it later, use the "Use custom API key" toggle in /config. In non-interactive mode (-p), the key is always used when present.
4. apiKeyHelper script output. Use this for dynamic or rotating credentials, such as short-lived tokens fetched from a vault.
5. CLAUDE_CODE_OAUTH_TOKEN environment variable. A long-lived OAuth token generated by claude setup-token. Use this for CI pipelines and scripts where browser login isn't available.
6. Subscription OAuth credentials from /login. This is the default for Claude Pro, Max, Team, and Enterprise users.

If you have an active Claude subscription but also have ANTHROPIC_API_KEY set in your environment, the API key takes precedence once approved. This can cause authentication failures if the key belongs to a disabled or expired organization. Run unset ANTHROPIC_API_KEY to fall back to your subscription, and check /status to confirm which method is active.

Claude Code on the Web always uses your subscription credentials. ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN in the sandbox environment do not override them.

Generate a long-lived token

For CI pipelines, scripts, or other environments where interactive browser login isn't available, generate a one-year OAuth token with claude setup-token:

claude setup-token

The command walks you through OAuth authorization and prints a token to the terminal. It does not save the token anywhere; copy it and set it as the CLAUDE_CODE_OAUTH_TOKEN environment variable wherever you want to authenticate:

export CLAUDE_CODE_OAUTH_TOKEN=your-token

This token authenticates with your Claude subscription and requires a Pro, Max, Team, or Enterprise plan. It is scoped to inference only and cannot establish Remote Control sessions.

Bare mode does not read CLAUDE_CODE_OAUTH_TOKEN. If your script passes --bare, authenticate with ANTHROPIC_API_KEY or an apiKeyHelper instead.

How we approach security

Security foundation

Your code's security is paramount. Claude Code is built with security at its core, developed according to Anthropic's comprehensive security program. Learn more and access resources (SOC 2 Type 2 report, ISO 27001 certificate, etc.) at Anthropic Trust Center.

Permission-based architecture

Claude Code uses strict read-only permissions by default. When additional actions are needed (editing files, running tests, executing commands), Claude Code requests explicit permission. Users control whether to approve actions once or allow them automatically.

We designed Claude Code to be transparent and secure. For example, we require approval for bash commands before executing them, giving you direct control. This approach enables users and organizations to configure permissions directly.

For detailed permission configuration, see Permissions.

Built-in protections

To mitigate risks in agentic systems:

• Sandboxed bash tool: Sandbox bash commands with filesystem and network isolation, reducing permission prompts while maintaining security. Enable with /sandbox to define boundaries where Claude Code can work autonomously
• Write access restriction: Claude Code can only write to the folder where it was started and its subfolders—it cannot modify files in parent directories without explicit permission. While Claude Code can read files outside the working directory (useful for accessing system libraries and dependencies), write operations are strictly confined to the project scope, creating a clear security boundary
• Prompt fatigue mitigation: Support for allowlisting frequently used safe commands per-user, per-codebase, or per-organization
• Accept Edits mode: Batch accept multiple edits while maintaining permission prompts for commands with side effects

User responsibility

Claude Code only has the permissions you grant it. You're responsible for reviewing proposed code and commands for safety before approval.

Protect against prompt injection

Prompt injection is a technique where an attacker attempts to override or manipulate an AI assistant's instructions by inserting malicious text. Claude Code includes several safeguards against these attacks:

Core protections

• Permission system: Sensitive operations require explicit approval
• Context-aware analysis: Detects potentially harmful instructions by analyzing the full request
• Input sanitization: Prevents command injection by processing user inputs
• Command blocklist: Blocks risky commands that fetch arbitrary content from the web like curl and wget by default. When explicitly allowed, be aware of permission pattern limitations

Privacy safeguards

We have implemented several safeguards to protect your data, including:

• Limited retention periods for sensitive information (see the Privacy Center to learn more)
• Restricted access to user session data
• User control over data training preferences. Consumer users can change their privacy settings at any time.

For full details, please review our Commercial Terms of Service (for Team, Enterprise, and API users) or Consumer Terms (for Free, Pro, and Max users) and Privacy Policy.

Additional safeguards

• Network request approval: Tools that make network requests require user approval by default
• Isolated context windows: Web fetch uses a separate context window to avoid injecting potentially malicious prompts
• Trust verification: First-time codebase runs and new MCP servers require trust verification
  • Note: Trust verification is disabled when running non-interactively with the -p flag
• Command injection detection: Suspicious bash commands require manual approval even if previously allowlisted
• Fail-closed matching: Unmatched commands default to requiring manual approval
• Natural language descriptions: Complex bash commands include explanations for user understanding
• Secure credential storage: API keys and tokens are encrypted. See Credential Management

Best practices for working with untrusted content:

1. Review suggested commands before approval
2. Avoid piping untrusted content directly to Claude
3. Verify proposed changes to critical files
4. Use virtual machines (VMs) to run scripts and make tool calls, especially when interacting with external web services
5. Report suspicious behavior with /feedback

MCP security

Claude Code allows users to configure Model Context Protocol (MCP) servers. The list of allowed MCP servers is configured in your source code, as part of Claude Code settings engineers check into source control.

We encourage either writing your own MCP servers or using MCP servers from providers that you trust. You are able to configure Claude Code permissions for MCP servers. Anthropic does not manage or audit any MCP servers.

IDE security

See VS Code security and privacy for more information on running Claude Code in an IDE.

Cloud execution security

When using Claude Code on the web, additional security controls are in place:

• Isolated virtual machines: Each cloud session runs in an isolated, Anthropic-managed VM
• Network access controls: Network access is limited by default and can be configured to be disabled or allow only specific domains
• Credential protection: Authentication is handled through a secure proxy that uses a scoped credential inside the sandbox, which is then translated to your actual GitHub authentication token
• Branch restrictions: Git push operations are restricted to the current working branch
• Audit logging: All operations in cloud environments are logged for compliance and audit purposes
• Automatic cleanup: Cloud environments are automatically terminated after session completion

For more details on cloud execution, see Claude Code on the web.

Remote Control sessions work differently: the web interface connects to a Claude Code process running on your local machine. All code execution and file access stays local, and the same data that flows during any local Claude Code session travels through the Anthropic API over TLS. No cloud VMs or sandboxing are involved. The connection uses multiple short-lived, narrowly scoped credentials, each limited to a specific purpose and expiring independently, to limit the blast radius of any single compromised credential.

Security best practices

Working with sensitive code

• Review all suggested changes before approval
• Use project-specific permission settings for sensitive repositories
• Consider using devcontainers for additional isolation
• Regularly audit your permission settings with /permissions

Team security

• Use managed settings to enforce organizational standards
• Share approved permission configurations through version control
• Train team members on security best practices
• Monitor Claude Code usage through OpenTelemetry metrics
• Audit or block settings changes during sessions with ConfigChange hooks

Reporting security issues

If you discover a security vulnerability in Claude Code:

1. Do not disclose it publicly
2. Report it through our HackerOne program
3. Include detailed reproduction steps
4. Allow time for us to address the issue before public disclosure

Related resources

• Sandboxing - Filesystem and network isolation for bash commands
• Permissions - Configure permissions and access controls
• Monitoring usage - Track and audit Claude Code activity
• Development containers - Secure, isolated environments
• Anthropic Trust Center - Security certifications and compliance

Server-managed settings allow administrators to centrally configure Claude Code through a web-based interface on Claude.ai. Claude Code clients automatically receive these settings when users authenticate with their organization credentials.

This approach is designed for organizations that do not have device management infrastructure in place, or need to manage settings for users on unmanaged devices.

Requirements

To use server-managed settings, you need:

• Claude for Teams or Claude for Enterprise plan
• Claude Code version 2.1.38 or later for Claude for Teams, or version 2.1.30 or later for Claude for Enterprise
• Network access to api.anthropic.com

Choose between server-managed and endpoint-managed settings

Claude Code supports two approaches for centralized configuration. Server-managed settings deliver configuration from Anthropic's servers. Endpoint-managed settings are deployed directly to devices through native OS policies (macOS managed preferences, Windows registry) or managed settings files.

If your devices are enrolled in an MDM or endpoint management solution, endpoint-managed settings provide stronger security guarantees because the settings file can be protected from user modification at the OS level.

Configure server-managed settings

{
  "permissions": {
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "/usr/local/bin/audit-edit.sh" }
        ]
      }
    ]
  }
}

{
  "autoMode": {
    "environment": [
      "Source control: github.example.com/acme-corp and all repos under it",
      "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",
      "Trusted internal domains: *.corp.example.com"
    ]
  }
}

Verify settings delivery

To confirm that settings are being applied, ask a user to restart Claude Code. If the configuration includes settings that trigger the security approval dialog, the user sees a prompt describing the managed settings on startup. You can also verify that managed permission rules are active by having a user run /permissions to view their effective permission rules.

Access control

The following roles can manage server-managed settings:

• Primary Owner
• Owner

Restrict access to trusted personnel, as settings changes apply to all users in the organization.

Managed-only settings

Most settings keys work in any scope. A handful of keys are only read from managed settings and have no effect when placed in user or project settings files. See managed-only settings for the full list. Any setting not on that list can still be placed in managed settings and takes the highest precedence.

Current limitations

Server-managed settings have the following limitations:

• Settings apply uniformly to all users in the organization. Per-group configurations are not yet supported.
• MCP server configurations cannot be distributed through server-managed settings.

Settings delivery

Settings precedence

Server-managed settings and endpoint-managed settings both occupy the highest tier in the Claude Code settings hierarchy. No other settings level can override them, including command line arguments.

Within the managed tier, the first source that delivers a non-empty configuration wins. Server-managed settings are checked first, then endpoint-managed settings. Sources do not merge: if server-managed settings deliver any keys at all, endpoint-managed settings are ignored entirely. If server-managed settings deliver nothing, endpoint-managed settings apply.

If you clear your server-managed configuration in the admin console with the intent of falling back to an endpoint-managed plist or registry policy, be aware that cached settings persist on client machines until the next successful fetch. Run /status to see which managed source is active.

Fetch and caching behavior

Claude Code fetches settings from Anthropic's servers at startup and polls for updates hourly during active sessions.

First launch without cached settings:

• Claude Code fetches settings asynchronously
• If the fetch fails, Claude Code continues without managed settings
• There is a brief window before settings load where restrictions are not yet enforced

Subsequent launches with cached settings:

• Cached settings apply immediately at startup
• Claude Code fetches fresh settings in the background
• Cached settings persist through network failures

Claude Code applies settings updates automatically without a restart, except for advanced settings like OpenTelemetry configuration, which require a full restart to take effect.

Enforce fail-closed startup

By default, if the remote settings fetch fails at startup, the CLI continues without managed settings. For environments where this brief unenforced window is unacceptable, set forceRemoteSettingsRefresh: true in your managed settings.

When this setting is active, the CLI blocks at startup until remote settings are freshly fetched. If the fetch fails, the CLI exits rather than proceeding without the policy. This setting self-perpetuates: once delivered from the server, it is also cached locally so that subsequent startups enforce the same behavior even before the first successful fetch of a new session.

To enable this, add the key to your managed settings configuration:

{
  "forceRemoteSettingsRefresh": true
}

Before enabling this setting, ensure your network policies allow connectivity to api.anthropic.com. If that endpoint is unreachable, the CLI exits at startup and users cannot start Claude Code.

Security approval dialogs

Certain settings that could pose security risks require explicit user approval before being applied:

• Shell command settings: settings that execute shell commands
• Custom environment variables: variables not in the known safe allowlist
• Hook configurations: any hook definition

When these settings are present, users see a security dialog explaining what is being configured. Users must approve to proceed. If a user rejects the settings, Claude Code exits.

Platform availability

Server-managed settings require a direct connection to api.anthropic.com and are not available when using third-party model providers:

• Amazon Bedrock
• Google Vertex AI
• Microsoft Foundry
• Custom API endpoints via ANTHROPIC_BASE_URL or LLM gateways

Audit logging

Audit log events for settings changes are available through the compliance API or audit log export. Contact your Anthropic account team for access.

Audit events include the type of action performed, the account and device that performed the action, and references to the previous and new values.

Security considerations

Server-managed settings provide centralized policy enforcement, but they operate as a client-side control. On unmanaged devices, users with admin or sudo access can modify the Claude Code binary, filesystem, or network configuration.

To detect runtime configuration changes, use ConfigChange hooks to log modifications or block unauthorized changes before they take effect.

For stronger enforcement guarantees, use endpoint-managed settings on devices enrolled in an MDM solution.

See also

Related pages for managing Claude Code configuration:

• Settings: complete configuration reference including all available settings
• Endpoint-managed settings: managed settings deployed to devices by IT
• Authentication: set up user access to Claude Code
• Security: security safeguards and best practices

Data policies

Data training policy

Consumer users (Free, Pro, and Max plans): We give you the choice to allow your data to be used to improve future Claude models. We will train new models using data from Free, Pro, and Max accounts when this setting is on (including when you use Claude Code from these accounts).

Commercial users: (Team and Enterprise plans, API, 3rd-party platforms, and Claude Gov) maintain existing policies: Anthropic does not train generative models using code or prompts sent to Claude Code under commercial terms, unless the customer has chosen to provide their data to us for model improvement (for example, the Developer Partner Program).

Development Partner Program

If you explicitly opt in to methods to provide us with materials to train on, such as via the Development Partner Program, we may use those materials provided to train our models. An organization admin can expressly opt-in to the Development Partner Program for their organization. Note that this program is available only for Anthropic first-party API, and not for Bedrock or Vertex users.

Feedback using the /feedback command

If you choose to send us feedback about Claude Code using the /feedback command, we may use your feedback to improve our products and services. Transcripts shared via /feedback are retained for 5 years.

Session quality surveys

When you see the "How is Claude doing this session?" prompt in Claude Code, responding to this survey (including selecting "Dismiss"), only your numeric rating (1, 2, 3, or dismiss) is recorded. We do not collect or store any conversation transcripts, inputs, outputs, or other session data as part of this survey. Unlike thumbs up/down feedback or /feedback reports, this session quality survey is a simple product satisfaction metric. Your responses to this survey do not impact your data training preferences and cannot be used to train our AI models.

To disable these surveys, set CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1. The survey is also disabled when DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set. To control frequency instead of disabling, set feedbackSurveyRate in your settings file to a probability between 0 and 1.

Data retention

Anthropic retains Claude Code data based on your account type and preferences.

Consumer users (Free, Pro, and Max plans):

• Users who allow data use for model improvement: 5-year retention period to support model development and safety improvements
• Users who don't allow data use for model improvement: 30-day retention period
• Privacy settings can be changed at any time at claude.ai/settings/data-privacy-controls.

Commercial users (Team, Enterprise, and API):

• Standard: 30-day retention period
• Zero data retention: available for Claude Code on Claude for Enterprise. ZDR is enabled on a per-organization basis; each new organization must have ZDR enabled separately by your account team
• Local caching: Claude Code clients store session transcripts locally in plaintext under ~/.claude/projects/ for 30 days by default to enable session resumption. Adjust the period with cleanupPeriodDays. See application data for what's stored and how to clear it.

You can delete individual Claude Code on the web sessions at any time. Deleting a session permanently removes the session's event data. For instructions on how to delete sessions, see Delete sessions.

Learn more about data retention practices in our Privacy Center.

For full details, please review our Commercial Terms of Service (for Team, Enterprise, and API users) or Consumer Terms (for Free, Pro, and Max users) and Privacy Policy.

Data access

For all first party users, you can learn more about what data is logged for local Claude Code and remote Claude Code. Remote Control sessions follow the local data flow since all execution happens on your machine. Note for remote Claude Code, Claude accesses the repository where you initiate your Claude Code session. Claude does not access repositories that you have connected but have not started a session in.

Local Claude Code: Data flow and dependencies

The diagram below shows how Claude Code connects to external services during installation and normal operation. Solid lines indicate required connections, while dashed lines represent optional or user-initiated data flows.

Claude Code is installed from NPM. Claude Code runs locally. In order to interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs. The data is encrypted in transit via TLS and is not encrypted at rest. Claude Code is compatible with most popular VPNs and LLM proxies.

Claude Code is built on Anthropic's APIs. For details regarding our API's security controls, including our API logging procedures, please refer to compliance artifacts offered in the Anthropic Trust Center.

Cloud execution: Data flow and dependencies

When using Claude Code on the web, sessions run in Anthropic-managed virtual machines instead of locally. In cloud environments:

• Code and data storage: Your repository is cloned to an isolated VM. Code and session data are subject to the retention and usage policies for your account type (see Data retention section above)
• Credentials: GitHub authentication is handled through a secure proxy; your GitHub credentials never enter the sandbox
• Network traffic: All outbound traffic goes through a security proxy for audit logging and abuse prevention
• Session data: Prompts, code changes, and outputs follow the same data policies as local Claude Code usage

For security details about cloud execution, see Security.

Telemetry services

Claude Code connects from users' machines to the Statsig service to log operational metrics such as latency, reliability, and usage patterns. This logging does not include any code or file paths. Data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the Statsig security documentation. To opt out of Statsig telemetry, set the DISABLE_TELEMETRY environment variable.

Claude Code connects from users' machines to Sentry for operational error logging. The data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the Sentry security documentation. To opt out of error logging, set the DISABLE_ERROR_REPORTING environment variable.

When users run the /feedback command, a copy of their full conversation history including code is sent to Anthropic. The data is encrypted in transit and at rest. Optionally, a Github issue is created in our public repository. To opt out, set the DISABLE_FEEDBACK_COMMAND environment variable to 1.

Default behaviors by API provider

By default, error reporting, telemetry, and bug reporting are disabled when using Bedrock, Vertex, or Foundry. Session quality surveys are the exception and appear regardless of provider. You can opt out of all non-essential traffic, including surveys, at once by setting CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. Here are the full default behaviors:

All environment variables can be checked into settings.json (see settings reference).

Zero Data Retention (ZDR) is available for Claude Code when used through Claude for Enterprise. When ZDR is enabled, prompts and model responses generated during Claude Code sessions are processed in real time and not stored by Anthropic after the response is returned, except where needed to comply with law or combat misuse.

ZDR on Claude for Enterprise gives enterprise customers the ability to use Claude Code with zero data retention and access administrative capabilities:

• Cost controls per user
• Analytics dashboard
• Server-managed settings
• Audit logs

ZDR for Claude Code on Claude for Enterprise applies only to Anthropic's direct platform. For Claude deployments on AWS Bedrock, Google Vertex AI, or Microsoft Foundry, refer to those platforms' data retention policies.

ZDR scope

ZDR covers Claude Code inference on Claude for Enterprise.

What ZDR covers

ZDR covers model inference calls made through Claude Code on Claude for Enterprise. When you use Claude Code in your terminal, the prompts you send and the responses Claude generates are not retained by Anthropic. This applies regardless of which Claude model is used.

What ZDR does not cover

ZDR does not extend to the following, even for organizations with ZDR enabled. These features follow standard data retention policies:

Features disabled under ZDR

When ZDR is enabled for a Claude Code organization on Claude for Enterprise, certain features that require storing prompts or completions are automatically disabled at the backend level:

These features are blocked in the backend regardless of client-side display. If you see a disabled feature in the Claude Code terminal during startup, attempting to use it returns an error indicating the organization's policies do not allow that action.

Future features may also be disabled if they require storing prompts or completions.

Data retention for policy violations

Even with ZDR enabled, Anthropic may retain data where required by law or to address Usage Policy violations. If a session is flagged for a policy violation, Anthropic may retain the associated inputs and outputs for up to 2 years, consistent with Anthropic's standard ZDR policy.

Request ZDR

To request ZDR for Claude Code on Claude for Enterprise, contact your Anthropic account team. Your account team will submit the request internally, and Anthropic will review and enable ZDR on your organization after confirming eligibility. All enablement actions are audit-logged.

If you are currently using ZDR for Claude Code via pay-as-you-go API keys, you can transition to Claude for Enterprise to gain access to administrative features while maintaining ZDR for Claude Code. Contact your account team to coordinate the migration.

Track Claude Code usage, costs, and tool activity across your organization by exporting telemetry data through OpenTelemetry (OTel). Claude Code exports metrics as time series data via the standard metrics protocol, events via the logs/events protocol, and optionally distributed traces via the traces protocol. Configure your metrics, logs, and traces backends to match your monitoring requirements.

Quick start

Configure OpenTelemetry using environment variables:

# 1. Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Choose exporters (both are optional - configure only what you need)
export OTEL_METRICS_EXPORTER=otlp       # Options: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp          # Options: otlp, console, none

# 3. Configure OTLP endpoint (for OTLP exporter)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Set authentication (if required)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. For debugging: reduce export intervals
export OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 seconds (default: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000     # 5 seconds (default: 5000ms)

# 6. Run Claude Code
claude

For full configuration options, see the OpenTelemetry specification.

Administrator configuration

Administrators can configure OpenTelemetry settings for all users through the managed settings file. This allows for centralized control of telemetry settings across an organization. See the settings precedence for more information about how settings are applied.

Example managed settings configuration:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

Configuration details

Common configuration variables

Metrics cardinality control

The following environment variables control which attributes are included in metrics to manage cardinality:

These variables help control the cardinality of metrics, which affects storage requirements and query performance in your metrics backend. Lower cardinality generally means better performance and lower storage costs but less granular data for analysis.

Traces (beta)

Distributed tracing exports spans that link each user prompt to the API requests and tool executions it triggers, so you can view a full request as a single trace in your tracing backend.

Tracing is off by default. To enable it, set both CLAUDE_CODE_ENABLE_TELEMETRY=1 and CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, then set OTEL_TRACES_EXPORTER to choose where spans are sent. Traces reuse the common OTLP configuration for endpoint, protocol, and headers.

Spans redact user prompt text, tool input details, and tool content by default. Set OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1, and OTEL_LOG_TOOL_CONTENT=1 to include them.

When tracing is active, Bash and PowerShell subprocesses automatically inherit a TRACEPARENT environment variable containing the W3C trace context of the active tool execution span. This lets any subprocess that reads TRACEPARENT parent its own spans under the same trace, enabling end-to-end distributed tracing through scripts and commands that Claude runs.

Dynamic headers

For enterprise environments that require dynamic authentication, you can configure a script to generate headers dynamically:

Settings configuration

Add to your .claude/settings.json:

{
  "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}

Script requirements

The script must output valid JSON with string key-value pairs representing HTTP headers:

#!/bin/bash
# Example: Multiple headers
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

Refresh behavior

The headers helper script runs at startup and periodically thereafter to support token refresh. By default, the script runs every 29 minutes. Customize the interval with the CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS environment variable.

Multi-team organization support

Organizations with multiple teams or departments can add custom attributes to distinguish between different groups using the OTEL_RESOURCE_ATTRIBUTES environment variable:

# Add custom attributes for team identification
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

These custom attributes will be included in all metrics and events, allowing you to:

• Filter metrics by team or department
• Track costs per cost center
• Create team-specific dashboards
• Set up alerts for specific teams

# ❌ Invalid - contains spaces
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Valid - use underscores or camelCase instead
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Valid - percent-encode special characters if needed
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

Example configurations

Set these environment variables before running claude. Each block shows a complete configuration for a different exporter or deployment scenario:

# Console debugging (1-second intervals)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

# Multiple exporters
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Different endpoints/backends for metrics and logs
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

# Metrics only (no events/logs)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Events/logs only (no metrics)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Available metrics and events

Standard attributes

All metrics and events share these standard attributes:

Events additionally include the following attributes. These are never attached to metrics because they would cause unbounded cardinality:

• prompt.id: UUID correlating a user prompt with all subsequent events until the next prompt. See Event correlation attributes.
• workspace.host_paths: host workspace directories selected in the desktop app, as a string array

Metrics

Claude Code exports the following metrics:

Metric details

Each metric includes the standard attributes listed above. Metrics with additional context-specific attributes are noted below.

Session counter

Incremented at the start of each session.

Attributes:

• All standard attributes

Lines of code counter

Incremented when code is added or removed.

Attributes:

• All standard attributes
• type: ("added", "removed")

Pull request counter

Incremented when creating pull requests via Claude Code.

Attributes:

• All standard attributes

Commit counter

Incremented when creating git commits via Claude Code.

Attributes:

• All standard attributes

Cost counter

Incremented after each API request.

Attributes:

• All standard attributes
• model: Model identifier (for example, "claude-sonnet-4-6")

Token counter

Incremented after each API request.

Attributes:

• All standard attributes
• type: ("input", "output", "cacheRead", "cacheCreation")
• model: Model identifier (for example, "claude-sonnet-4-6")

Code edit tool decision counter

Incremented when user accepts or rejects Edit, Write, or NotebookEdit tool usage.

Attributes:

• All standard attributes
• tool_name: Tool name ("Edit", "Write", "NotebookEdit")
• decision: User decision ("accept", "reject")
• source: Decision source - "config", "hook", "user_permanent", "user_temporary", "user_abort", or "user_reject"
• language: Programming language of the edited file, such as "TypeScript", "Python", "JavaScript", or "Markdown". Returns "unknown" for unrecognized file extensions.

Active time counter

Tracks actual time spent actively using Claude Code, excluding idle time. This metric is incremented during user interactions (typing, reading responses) and during CLI processing (tool execution, AI response generation).

Attributes:

• All standard attributes
• type: "user" for keyboard interactions, "cli" for tool execution and AI responses

Events

Claude Code exports the following events via OpenTelemetry logs/events (when OTEL_LOGS_EXPORTER is configured):

Event correlation attributes

When a user submits a prompt, Claude Code may make multiple API calls and run several tools. The prompt.id attribute lets you tie all of those events back to the single prompt that triggered them.

To trace all activity triggered by a single prompt, filter your events by a specific prompt.id value. This returns the user_prompt event, any api_request events, and any tool_result events that occurred while processing that prompt.

User prompt event

Logged when a user submits a prompt.

Event Name: claude_code.user_prompt

Attributes:

• All standard attributes
• event.name: "user_prompt"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• prompt_length: Length of the prompt
• prompt: Prompt content (redacted by default, enable with OTEL_LOG_USER_PROMPTS=1)

Tool result event

Logged when a tool completes execution.

Event Name: claude_code.tool_result

Attributes:

• All standard attributes
• event.name: "tool_result"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• tool_name: Name of the tool
• success: "true" or "false"
• duration_ms: Execution time in milliseconds
• error: Error message (if failed)
• decision_type: Either "accept" or "reject"
• decision_source: Decision source - "config", "hook", "user_permanent", "user_temporary", "user_abort", or "user_reject"
• tool_result_size_bytes: Size of the tool result in bytes
• mcp_server_scope: MCP server scope identifier (for MCP tools)
• tool_parameters (when OTEL_LOG_TOOL_DETAILS=1): JSON string containing tool-specific parameters:
  • For Bash tool: includes bash_command, full_command, timeout, description, dangerouslyDisableSandbox, and git_commit_id (the commit SHA, when a git commit command succeeds)
  • For MCP tools: includes mcp_server_name, mcp_tool_name
  • For Skill tool: includes skill_name
• tool_input (when OTEL_LOG_TOOL_DETAILS=1): JSON-serialized tool arguments. Individual values over 512 characters are truncated, and the full payload is bounded to ~4 K characters. Applies to all tools including MCP tools.

API request event

Logged for each API request to Claude.

Event Name: claude_code.api_request

Attributes:

• All standard attributes
• event.name: "api_request"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• model: Model used (for example, "claude-sonnet-4-6")
• cost_usd: Estimated cost in USD
• duration_ms: Request duration in milliseconds
• input_tokens: Number of input tokens
• output_tokens: Number of output tokens
• cache_read_tokens: Number of tokens read from cache
• cache_creation_tokens: Number of tokens used for cache creation
• speed: "fast" or "normal", indicating whether fast mode was active

API error event

Logged when an API request to Claude fails.

Event Name: claude_code.api_error

Attributes:

• All standard attributes
• event.name: "api_error"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• model: Model used (for example, "claude-sonnet-4-6")
• error: Error message
• status_code: HTTP status code as a string, or "undefined" for non-HTTP errors
• duration_ms: Request duration in milliseconds
• attempt: Total number of attempts made, including the initial request (1 means no retries occurred)
• speed: "fast" or "normal", indicating whether fast mode was active

Tool decision event

Logged when a tool permission decision is made (accept/reject).

Event Name: claude_code.tool_decision

Attributes:

• All standard attributes
• event.name: "tool_decision"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• tool_name: Name of the tool (for example, "Read", "Edit", "Write", "NotebookEdit")
• decision: Either "accept" or "reject"
• source: Decision source - "config", "hook", "user_permanent", "user_temporary", "user_abort", or "user_reject"

Plugin installed event

Logged when a plugin finishes installing, from both the claude plugin install CLI command and the interactive /plugin UI.

Event Name: claude_code.plugin_installed

Attributes:

• All standard attributes
• event.name: "plugin_installed"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• plugin.name: Name of the installed plugin
• plugin.version: Plugin version when declared in the marketplace entry
• marketplace.name: Marketplace the plugin was installed from
• marketplace.is_official: "true" if the marketplace is an official Anthropic marketplace, "false" otherwise
• install.trigger: "cli" or "ui"

Skill activated event

Logged when a skill is invoked.

Event Name: claude_code.skill_activated

Attributes:

• All standard attributes
• event.name: "skill_activated"
• event.timestamp: ISO 8601 timestamp
• event.sequence: monotonically increasing counter for ordering events within a session
• skill.name: Name of the skill
• skill.source: Where the skill was loaded from (for example, "bundled", "userSettings", "projectSettings", "plugin")
• plugin.name: Name of the owning plugin when the skill is provided by a plugin
• marketplace.name: Marketplace the owning plugin was installed from, when the skill is provided by a plugin

Interpret metrics and events data

The exported metrics and events support a range of analyses:

Usage monitoring

Cost monitoring

The claude_code.cost.usage metric helps with:

• Tracking usage trends across teams or individuals
• Identifying high-usage sessions for optimization

Alerting and segmentation

Common alerts to consider:

• Cost spikes
• Unusual token consumption
• High session volume from specific users

All metrics can be segmented by user.account_uuid, user.account_id, organization.id, session.id, model, and app.version.

Detect retry exhaustion

Claude Code retries failed API requests internally and emits a single claude_code.api_error event only after it gives up, so the event itself is the terminal signal for that request. Intermediate retry attempts are not logged as separate events.

The attempt attribute on the event records how many attempts were made in total. A value greater than CLAUDE_CODE_MAX_RETRIES (default 10) indicates the request exhausted all retries on a transient error. A lower value indicates a non-retryable error such as a 400 response.

To distinguish a session that recovered from one that stalled, group events by session.id and check whether a later api_request event exists after the error.

Event analysis

The event data provides detailed insights into Claude Code interactions:

Tool Usage Patterns: analyze tool result events to identify:

• Most frequently used tools
• Tool success rates
• Average tool execution times
• Error patterns by tool type

Performance Monitoring: track API request durations and tool execution times to identify performance bottlenecks.

Backend considerations

Your choice of metrics, logs, and traces backends determines the types of analyses you can perform:

For metrics

• Time series databases (for example, Prometheus): Rate calculations, aggregated metrics
• Columnar stores (for example, ClickHouse): Complex queries, unique user analysis
• Full-featured observability platforms (for example, Honeycomb, Datadog): Advanced querying, visualization, alerting

For events/logs

• Log aggregation systems (for example, Elasticsearch, Loki): Full-text search, log analysis
• Columnar stores (for example, ClickHouse): Structured event analysis
• Full-featured observability platforms (for example, Honeycomb, Datadog): Correlation between metrics and events

For traces

Choose a backend that supports distributed trace storage and span correlation:

• Distributed tracing systems (for example, Jaeger, Zipkin, Grafana Tempo): Span visualization, request waterfalls, latency analysis
• Full-featured observability platforms (for example, Honeycomb, Datadog): Trace search and correlation with metrics and logs

For organizations requiring Daily/Weekly/Monthly Active User (DAU/WAU/MAU) metrics, consider backends that support efficient unique value queries.

Service information

All metrics and events are exported with the following resource attributes:

• service.name: claude-code
• service.version: Current Claude Code version
• os.type: Operating system type (for example, linux, darwin, windows)
• os.version: Operating system version string
• host.arch: Host architecture (for example, amd64, arm64)
• wsl.version: WSL version number (only present when running on Windows Subsystem for Linux)
• Meter Name: com.anthropic.claude_code

ROI measurement resources

For a comprehensive guide on measuring return on investment for Claude Code, including telemetry setup, cost analysis, productivity metrics, and automated reporting, see the Claude Code ROI Measurement Guide. This repository provides ready-to-use Docker Compose configurations, Prometheus and OpenTelemetry setups, and templates for generating productivity reports integrated with tools like Linear.

Security and privacy

• Telemetry is opt-in and requires explicit configuration
• Raw file contents and code snippets are not included in metrics or events. Trace spans are a separate data path: see the OTEL_LOG_TOOL_CONTENT bullet below
• When authenticated via OAuth, user.email is included in telemetry attributes. If this is a concern for your organization, work with your telemetry backend to filter or redact this field
• User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set OTEL_LOG_USER_PROMPTS=1
• Tool input arguments and parameters are not logged by default. To include them, set OTEL_LOG_TOOL_DETAILS=1. When enabled, tool_result events include a tool_parameters attribute with Bash commands, MCP server and tool names, and skill names, plus a tool_input attribute with file paths, URLs, search patterns, and other arguments. Trace spans include the same tool_input attribute and input-derived attributes such as file_path. Individual values over 512 characters are truncated and the total is bounded to ~4 K characters, but the arguments may still contain sensitive values. Configure your telemetry backend to filter or redact these attributes as needed
• Tool input and output content is not logged in trace spans by default. To include it, set OTEL_LOG_TOOL_CONTENT=1. When enabled, span events include full tool input and output content truncated at 60 KB per span. This can include raw file contents from Read tool results and Bash command output. Configure your telemetry backend to filter or redact these attributes as needed

Monitor Claude Code on Amazon Bedrock

For detailed Claude Code usage monitoring guidance for Amazon Bedrock, see Claude Code Monitoring Implementation (Bedrock).

Claude Code charges by API token consumption. For subscription plan pricing (Pro, Max, Team, Enterprise), see claude.com/pricing. Per-developer costs vary widely based on model selection, codebase size, and usage patterns such as running multiple instances or automation.

Across enterprise deployments, the average cost is around $13 per developer per active day and $150-250 per developer per month, with costs remaining below $30 per active day for 90% of users. To estimate spend for your own team, start with a small pilot group and use the tracking tools below to establish a baseline before wider rollout.

This page covers how to track your costs, manage costs for teams, and reduce token usage.

Track your costs

Using the /cost command

The /cost command provides detailed token usage statistics for your current session:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    0 lines added, 0 lines removed

Managing costs for teams

When using Claude API, you can set workspace spend limits on the total Claude Code workspace spend. Admins can view cost and usage reporting in the Console.

On Bedrock, Vertex, and Foundry, Claude Code does not send metrics from your cloud. To get cost metrics, several large enterprises reported using LiteLLM, which is an open-source tool that helps companies track spend by key. This project is unaffiliated with Anthropic and has not been audited for security.

Rate limit recommendations

When setting up Claude Code for teams, consider these Token Per Minute (TPM) and Request Per Minute (RPM) per-user recommendations based on your organization size:

For example, if you have 200 users, you might request 20k TPM for each user, or 4 million total TPM (200*20,000 = 4 million).

The TPM per user decreases as team size grows because fewer users tend to use Claude Code concurrently in larger organizations. These rate limits apply at the organization level, not per individual user, which means individual users can temporarily consume more than their calculated share when others aren't actively using the service.

Agent team token costs

Agent teams spawn multiple Claude Code instances, each with its own context window. Token usage scales with the number of active teammates and how long each one runs.

To keep agent team costs manageable:

• Use Sonnet for teammates. It balances capability and cost for coordination tasks.
• Keep teams small. Each teammate runs its own context window, so token usage is roughly proportional to team size.
• Keep spawn prompts focused. Teammates load CLAUDE.md, MCP servers, and skills automatically, but everything in the spawn prompt adds to their context from the start.
• Clean up teams when work is done. Active teammates continue consuming tokens even if idle.
• Agent teams are disabled by default. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your settings.json or environment to enable them. See enable agent teams.

Reduce token usage

Token costs scale with context size: the more context Claude processes, the more tokens you use. Claude Code automatically optimizes costs through prompt caching (which reduces costs for repeated content like system prompts) and auto-compaction (which summarizes conversation history when approaching context limits).

The following strategies help you keep context small and reduce per-message costs.

Manage context proactively

Use /cost to check your current token usage, or configure your status line to display it continuously.

• Clear between tasks: Use /clear to start fresh when switching to unrelated work. Stale context wastes tokens on every subsequent message. Use /rename before clearing so you can easily find the session later, then /resume to return to it.
• Add custom compaction instructions: /compact Focus on code samples and API usage tells Claude what to preserve during summarization.

You can also customize compaction behavior in your CLAUDE.md:

# Compact instructions

When you are using compact, please focus on test output and code changes

Choose the right model

Sonnet handles most coding tasks well and costs less than Opus. Reserve Opus for complex architectural decisions or multi-step reasoning. Use /model to switch models mid-session, or set a default in /config. For simple subagent tasks, specify model: haiku in your subagent configuration.

Reduce MCP server overhead

MCP tool definitions are deferred by default, so only tool names enter context until Claude uses a specific tool. Run /context to see what's consuming space.

• Prefer CLI tools when available: Tools like gh, aws, gcloud, and sentry-cli are still more context-efficient than MCP servers because they don't add any per-tool listing. Claude can run CLI commands directly.
• Disable unused servers: Run /mcp to see configured servers and disable any you're not actively using.

Install code intelligence plugins for typed languages

Code intelligence plugins give Claude precise symbol navigation instead of text-based search, reducing unnecessary file reads when exploring unfamiliar code. A single "go to definition" call replaces what might otherwise be a grep followed by reading multiple candidate files. Installed language servers also report type errors automatically after edits, so Claude catches mistakes without running a compiler.

Offload processing to hooks and skills

Custom hooks can preprocess data before Claude sees it. Instead of Claude reading a 10,000-line log file to find errors, a hook can grep for ERROR and return only matching lines, reducing context from tens of thousands of tokens to hundreds.

A skill can give Claude domain knowledge so it doesn't have to explore. For example, a "codebase-overview" skill could describe your project's architecture, key directories, and naming conventions. When Claude invokes the skill, it gets this context immediately instead of spending tokens reading multiple files to understand the structure.

For example, this PreToolUse hook filters test output to show only failures:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')
If running tests, filter to show only failures
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100" echo "{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","updatedInput":{"command":"$filtered_cmd"}}}"
else echo "{}"
fi

Move instructions from CLAUDE.md to skills

Your CLAUDE.md file is loaded into context at session start. If it contains detailed instructions for specific workflows (like PR reviews or database migrations), those tokens are present even when you're doing unrelated work. Skills load on-demand only when invoked, so moving specialized instructions into skills keeps your base context smaller. Aim to keep CLAUDE.md under 200 lines by including only essentials.

Adjust extended thinking

Extended thinking is enabled by default because it significantly improves performance on complex planning and reasoning tasks. Thinking tokens are billed as output tokens, and the default budget can be tens of thousands of tokens per request depending on the model. For simpler tasks where deep reasoning isn't needed, you can reduce costs by lowering the effort level with /effort or in /model, disabling thinking in /config, or lowering the budget with MAX_THINKING_TOKENS=8000.

Delegate verbose operations to subagents

Running tests, fetching documentation, or processing log files can consume significant context. Delegate these to subagents so the verbose output stays in the subagent's context while only a summary returns to your main conversation.

Manage agent team costs

Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, because each teammate maintains its own context window and runs as a separate Claude instance. Keep team tasks small and self-contained to limit per-teammate token usage. See agent teams for details.

Write specific prompts

Vague requests like "improve this codebase" trigger broad scanning. Specific requests like "add input validation to the login function in auth.ts" let Claude work efficiently with minimal file reads.

Work efficiently on complex tasks

For longer or more complex work, these habits help avoid wasted tokens from going down the wrong path:

• Use plan mode for complex tasks: Press Shift+Tab to enter plan mode before implementation. Claude explores the codebase and proposes an approach for your approval, preventing expensive re-work when the initial direction is wrong.
• Course-correct early: If Claude starts heading the wrong direction, press Escape to stop immediately. Use /rewind or double-tap Escape to restore conversation and code to a previous checkpoint.
• Give verification targets: Include test cases, paste screenshots, or define expected output in your prompt. When Claude can verify its own work, it catches issues before you need to request fixes.
• Test incrementally: Write one file, test it, then continue. This catches issues early when they're cheap to fix.

Background token usage

Claude Code uses tokens for some background functionality even when idle:

• Conversation summarization: Background jobs that summarize previous conversations for the claude --resume feature
• Command processing: Some commands like /cost may generate requests to check status

These background processes consume a small amount of tokens (typically under $0.04 per session) even without active interaction.

Understanding changes in Claude Code behavior

Claude Code regularly receives updates that may change how features work, including cost reporting. Run claude --version to check your current version. For specific billing questions, contact Anthropic support through your Console account.

Claude Code provides analytics dashboards to help organizations understand developer usage patterns, track contribution metrics, and measure how Claude Code impacts engineering velocity. Access the dashboard for your plan:

Access analytics for Team and Enterprise

Navigate to claude.ai/analytics/claude-code. Admins and Owners can view the dashboard.

The Team and Enterprise dashboard includes:

• Usage metrics: lines of code accepted, suggestion accept rate, daily active users and sessions
• Contribution metrics: PRs and lines of code shipped with Claude Code assistance, with GitHub integration
• Leaderboard: top contributors ranked by Claude Code usage
• Data export: download contribution data as CSV for custom reporting

Enable contribution metrics

Usage and adoption data is available for all Claude for Teams and Claude for Enterprise accounts. Contribution metrics require additional setup to connect your GitHub organization.

You need the Owner role to configure analytics settings. A GitHub admin must install the GitHub app.

Data typically appears within 24 hours after enabling, with daily updates. If no data appears, you may see one of these messages:

• "GitHub app required": install the GitHub app to view contribution metrics
• "Data processing in progress": check back in a few days and confirm the GitHub app is installed if data doesn't appear

Contribution metrics support GitHub Cloud and GitHub Enterprise Server.

Review summary metrics

The dashboard displays these summary metrics at the top:

• PRs with CC: total count of merged pull requests that contain at least one line of code written with Claude Code
• Lines of code with CC: total lines of code across all merged PRs that were written with Claude Code assistance. Only "effective lines" are counted: lines with more than 3 characters after normalization, excluding empty lines and lines with only brackets or trivial punctuation.
• PRs with Claude Code (%): percentage of all merged PRs that contain Claude Code-assisted code
• Suggestion accept rate: percentage of times users accept Claude Code's code editing suggestions, including Edit, Write, and NotebookEdit tool usage
• Lines of code accepted: total lines of code written by Claude Code that users have accepted in their sessions. This excludes rejected suggestions and does not track subsequent deletions.

Explore the charts

The dashboard includes several charts to visualize trends over time.

Track adoption

The Adoption chart shows daily usage trends:

• users: daily active users
• sessions: number of active Claude Code sessions per day

Measure PRs per user

This chart displays individual developer activity over time:

• PRs per user: total number of PRs merged per day divided by daily active users
• users: daily active users

Use this to understand how individual productivity changes as Claude Code adoption increases.

View pull requests breakdown

The Pull requests chart shows a daily breakdown of merged PRs:

• PRs with CC: pull requests containing Claude Code-assisted code
• PRs without CC: pull requests without Claude Code-assisted code

Toggle to Lines of code view to see the same breakdown by lines of code rather than PR count.

Find top contributors

The Leaderboard shows the top 10 users ranked by contribution volume. Toggle between:

• Pull requests: shows PRs with Claude Code vs All PRs for each user
• Lines of code: shows lines with Claude Code vs All lines for each user

Click Export all users to download complete contribution data for all users as a CSV file. The export includes all users, not just the top 10 displayed.

PR attribution

When contribution metrics are enabled, Claude Code analyzes merged pull requests to determine which code was written with Claude Code assistance. This is done by matching Claude Code session activity against the code in each PR.

Tagging criteria

PRs are tagged as "with Claude Code" if they contain at least one line of code written during a Claude Code session. The system uses conservative matching: only code where there is high confidence in Claude Code's involvement is counted as assisted.

Attribution process

When a pull request is merged:

1. Added lines are extracted from the PR diff
2. Claude Code sessions that edited matching files within a time window are identified
3. PR lines are matched against Claude Code output using multiple strategies
4. Metrics are calculated for AI-assisted lines and total lines

Before comparison, lines are normalized: whitespace is trimmed, multiple spaces are collapsed, quotes are standardized, and text is converted to lowercase.

Merged pull requests containing Claude Code-assisted lines are labeled as claude-code-assisted in GitHub.

Time window

Sessions from 21 days before to 2 days after the PR merge date are considered for attribution matching.

Excluded files

Certain files are automatically excluded from analysis because they are auto-generated:

• Lock files: package-lock.json, yarn.lock, Cargo.lock, and similar
• Generated code: Protobuf outputs, build artifacts, minified files
• Build directories: dist/, build/, node_modules/, target/
• Test fixtures: snapshots, cassettes, mock data
• Lines over 1,000 characters, which are likely minified or generated

Attribution notes

Keep these additional details in mind when interpreting attribution data:

• Code substantially rewritten by developers, with more than 20% difference, is not attributed to Claude Code
• Sessions outside the 21-day window are not considered
• The algorithm does not consider the PR source or destination branch when performing attribution

Get the most from analytics

Use contribution metrics to demonstrate ROI, identify adoption patterns, and find team members who can help others get started.

Monitor adoption

Track the Adoption chart and user counts to identify:

• Active users who can share best practices
• Overall adoption trends across your organization
• Dips in usage that may indicate friction or issues

Measure ROI

Contribution metrics help answer "Is this tool worth the investment?" with data from your own codebase:

• Track changes in PRs per user over time as adoption increases
• Compare PRs and lines of code shipped with vs. without Claude Code
• Use alongside DORA metrics, sprint velocity, or other engineering KPIs to understand changes from adopting Claude Code

Identify power users

The Leaderboard helps you find team members with high Claude Code adoption who can:

• Share prompting techniques and workflows with the team
• Provide feedback on what's working well
• Help onboard new users

Access data programmatically

To query this data through GitHub, search for PRs labeled with claude-code-assisted.

Access analytics for API customers

API customers using the Claude Console can access analytics at platform.claude.com/claude-code. You need the UsageView permission to access the dashboard, which is granted to Developer, Billing, Admin, Owner, and Primary Owner roles.

The Console dashboard displays:

• Lines of code accepted: total lines of code written by Claude Code that users have accepted in their sessions. This excludes rejected suggestions and does not track subsequent deletions.
• Suggestion accept rate: percentage of times users accept code editing tool usage, including Edit, Write, and NotebookEdit tools.
• Activity: daily active users and sessions shown on a chart.
• Spend: daily API costs in dollars alongside user count.

View team insights

The team insights table shows per-user metrics:

• Members: all users who have authenticated to Claude Code. API key users display by key identifier, OAuth users display by email address.
• Spend this month: per-user total API costs for the current month.
• Lines this month: per-user total of accepted code lines for the current month.

Related resources

• Monitoring with OpenTelemetry: export real-time metrics and events to your observability stack
• Manage costs effectively: set spend limits and optimize token usage
• Permissions: configure roles and permissions

A plugin marketplace is a catalog that lets you distribute plugins to others. Marketplaces provide centralized discovery, version tracking, automatic updates, and support for multiple source types (git repositories, local paths, and more). This guide shows you how to create your own marketplace to share plugins with your team or community.

Looking to install plugins from an existing marketplace? See Discover and install prebuilt plugins.

Overview

Creating and distributing a marketplace involves:

1. Creating plugins: build one or more plugins with skills, agents, hooks, MCP servers, or LSP servers. This guide assumes you already have plugins to distribute; see Create plugins for details on how to create them.
2. Creating a marketplace file: define a marketplace.json that lists your plugins and where to find them (see Create the marketplace file).
3. Host the marketplace: push to GitHub, GitLab, or another git host (see Host and distribute marketplaces).
4. Share with users: users add your marketplace with /plugin marketplace add and install individual plugins (see Discover and install plugins).

Once your marketplace is live, you can update it by pushing changes to your repository. Users refresh their local copy with /plugin marketplace update.

Walkthrough: create a local marketplace

This example creates a marketplace with one plugin: a /quality-review skill for code reviews. You'll create the directory structure, add a skill, create the plugin manifest and marketplace catalog, then install and test it.

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

---
description: Review code for bugs, security, and performance
disable-model-invocation: true
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

{
  "name": "quality-review-plugin",
  "description": "Adds a /quality-review skill for quick code reviews",
  "version": "1.0.0"
}

{
  "name": "my-plugins",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a /quality-review skill for quick code reviews"
    }
  ]
}

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

/quality-review

To learn more about what plugins can do, including hooks, agents, MCP servers, and LSP servers, see Plugins.

Create the marketplace file

Create .claude-plugin/marketplace.json in your repository root. This file defines your marketplace's name, owner information, and a list of plugins with their sources.

Each plugin entry needs at minimum a name and source (where to fetch it from). See the full schema below for all available fields.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Marketplace schema

Required fields

Owner fields

Optional metadata

Plugin entries

Each plugin entry in the plugins array describes a plugin and where to find it. You can include any field from the plugin manifest schema (like description, version, author, commands, hooks, etc.), plus these marketplace-specific fields: source, category, tags, and strict.

Required fields

Optional plugin fields

Standard metadata fields:

Component configuration fields:

Plugin sources

Plugin sources tell Claude Code where to fetch each individual plugin listed in your marketplace. These are set in the source field of each plugin entry in marketplace.json.

Once a plugin is cloned or copied into the local machine, it is copied into the local versioned plugin cache at ~/.claude/plugins/cache.

Relative paths

For plugins in the same repository, use a path starting with ./:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

Paths resolve relative to the marketplace root, which is the directory containing .claude-plugin/. In the example above, ./plugins/my-plugin points to <repo>/plugins/my-plugin, even though marketplace.json lives at <repo>/.claude-plugin/marketplace.json. Do not use ../ to reference paths outside the marketplace root.

GitHub repositories

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

You can pin to a specific branch, tag, or commit:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Git repositories

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

You can pin to a specific branch, tag, or commit:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Git subdirectories

Use git-subdir to point to a plugin that lives inside a subdirectory of a git repository. Claude Code uses a sparse, partial clone to fetch only the subdirectory, minimizing bandwidth for large monorepos.

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

You can pin to a specific branch, tag, or commit:

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

The url field also accepts a GitHub shorthand (owner/repo) or SSH URLs ([email protected]:owner/repo.git).

npm packages

Plugins distributed as npm packages are installed using npm install. This works with any package on the public npm registry or a private registry your team hosts.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

To pin to a specific version, add the version field:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

To install from a private or internal registry, add the registry field:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

Advanced plugin entries

This example shows a plugin entry using many of the optional fields, including custom paths for commands, agents, hooks, and MCP servers:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "[email protected]"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

Key things to notice:

• commands and agents: You can specify multiple directories or individual files. Paths are relative to the plugin root.
• ${CLAUDE_PLUGIN_ROOT}: use this variable in hooks and MCP server configs to reference files within the plugin's installation directory. This is necessary because plugins are copied to a cache location when installed. For dependencies or state that should survive plugin updates, use ${CLAUDE_PLUGIN_DATA} instead.
• strict: false: Since this is set to false, the plugin doesn't need its own plugin.json. The marketplace entry defines everything. See Strict mode below.

Strict mode

The strict field controls whether plugin.json is the authority for component definitions (skills, agents, hooks, MCP servers, output styles).

When to use each mode:

• strict: true: the plugin has its own plugin.json and manages its own components. The marketplace entry can add extra skills or hooks on top. This is the default and works for most plugins.
• strict: false: the marketplace operator wants full control. The plugin repo provides raw files, and the marketplace entry defines which of those files are exposed as skills, agents, hooks, etc. Useful when the marketplace restructures or curates a plugin's components differently than the plugin author intended.

Host and distribute marketplaces

Host on GitHub (recommended)

GitHub provides the easiest distribution method:

1. Create a repository: Set up a new repository for your marketplace
2. Add marketplace file: Create .claude-plugin/marketplace.json with your plugin definitions
3. Share with teams: Users add your marketplace with /plugin marketplace add owner/repo

Benefits: Built-in version control, issue tracking, and team collaboration features.

Host on other git services

Any git hosting service works, such as GitLab, Bitbucket, and self-hosted servers. Users add with the full repository URL:

/plugin marketplace add https://gitlab.com/company/plugins.git

Private repositories

Claude Code supports installing plugins from private repositories. For manual installation and updates, Claude Code uses your existing git credential helpers. If git clone works for a private repository in your terminal, it works in Claude Code too. Common credential helpers include gh auth login for GitHub, macOS Keychain, and git-credential-store.

Background auto-updates run at startup without credential helpers, since interactive prompts would block Claude Code from starting. To enable auto-updates for private marketplaces, set the appropriate authentication token in your environment:

Set the token in your shell configuration (for example, .bashrc, .zshrc) or pass it when running Claude Code:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Test locally before distribution

Test your marketplace locally before sharing:

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

For the full range of add commands (GitHub, Git URLs, local paths, remote URLs), see Add marketplaces.

Require marketplaces for your team

You can configure your repository so team members are automatically prompted to install your marketplace when they trust the project folder. Add your marketplace to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

You can also specify which plugins should be enabled by default:

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

For full configuration options, see Plugin settings.

Pre-populate plugins for containers

For container images and CI environments, you can pre-populate a plugins directory at build time so Claude Code starts with marketplaces and plugins already available, without cloning anything at runtime. Set the CLAUDE_CODE_PLUGIN_SEED_DIR environment variable to point at this directory.

To layer multiple seed directories, separate paths with : on Unix or ; on Windows. Claude Code searches each directory in order, and the first seed that contains a given marketplace or plugin cache wins.

The seed directory mirrors the structure of ~/.claude/plugins:

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

To build a seed directory, run Claude Code once during image build, install the plugins you need, then copy the resulting ~/.claude/plugins directory into your image and point CLAUDE_CODE_PLUGIN_SEED_DIR at it.

To skip the copy step, set CLAUDE_CODE_PLUGIN_CACHE_DIR to your target seed path during the build so plugins install directly there:

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

Then set CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed in your container's runtime environment so Claude Code reads from the seed on startup.

At startup, Claude Code registers marketplaces found in the seed's known_marketplaces.json into the primary configuration, and uses plugin caches found under cache/ in place without re-cloning. This works in both interactive mode and non-interactive mode with the -p flag.

Behavior details:

• Read-only: the seed directory is never written to. Auto-updates are disabled for seed marketplaces since git pull would fail on a read-only filesystem.
• Seed entries take precedence: marketplaces declared in the seed overwrite any matching entries in the user's configuration on each startup. To opt out of a seed plugin, use /plugin disable rather than removing the marketplace.
• Path resolution: Claude Code locates marketplace content by probing $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ at runtime, not by trusting paths stored inside the seed's JSON. This means the seed works correctly even when mounted at a different path than where it was built.
• Mutation is blocked: running /plugin marketplace remove or /plugin marketplace update against a seed-managed marketplace fails with guidance to ask your administrator to update the seed image.
• Composes with settings: if extraKnownMarketplaces or enabledPlugins declare a marketplace that already exists in the seed, Claude Code uses the seed copy instead of cloning.

Managed marketplace restrictions

For organizations requiring strict control over plugin sources, administrators can restrict which plugin marketplaces users are allowed to add using the strictKnownMarketplaces setting in managed settings.

When strictKnownMarketplaces is configured in managed settings, the restriction behavior depends on the value:

Common configurations

Disable all marketplace additions:

{
  "strictKnownMarketplaces": []
}

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"
    }
  ]
}

Allow all marketplaces from an internal git server using regex pattern matching on the host. This is the recommended approach for GitHub Enterprise Server or self-hosted GitLab instances:

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

Allow filesystem-based marketplaces from a specific directory using regex pattern matching on the path:

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

Use ".*" as the pathPattern to allow any filesystem path while still controlling network sources with hostPattern.

How restrictions work

Restrictions are validated early in the plugin installation process, before any network requests or filesystem operations occur. This prevents unauthorized marketplace access attempts.

The allowlist uses exact matching for most source types. For a marketplace to be allowed, all specified fields must match exactly:

• For GitHub sources: repo is required, and ref or path must also match if specified in the allowlist
• For URL sources: the full URL must match exactly
• For hostPattern sources: the marketplace host is matched against the regex pattern
• For pathPattern sources: the marketplace's filesystem path is matched against the regex pattern

Because strictKnownMarketplaces is set in managed settings, individual users and project configurations cannot override these restrictions.

For complete configuration details including all supported source types and comparison with extraKnownMarketplaces, see the strictKnownMarketplaces reference.

Version resolution and release channels

Plugin versions determine cache paths and update detection. You can specify the version in the plugin manifest (plugin.json) or in the marketplace entry (marketplace.json).

Set up release channels

To support "stable" and "latest" release channels for your plugins, you can set up two marketplaces that point to different refs or SHAs of the same repo. You can then assign the two marketplaces to different user groups through managed settings.

Example

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

Assign channels to user groups

Assign each marketplace to the appropriate user group through managed settings. For example, the stable group receives:

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

The early-access group receives latest-tools instead:

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

Validation and testing

Test your marketplace before sharing.

Validate your marketplace JSON syntax:

claude plugin validate .

Or from within Claude Code:

/plugin validate .

Add the marketplace for testing:

/plugin marketplace add ./path/to/marketplace

Install a test plugin to verify everything works:

/plugin install test-plugin@marketplace-name

For complete plugin testing workflows, see Test your plugins locally. For technical troubleshooting, see Plugins reference.

Manage marketplaces from the CLI

Claude Code provides non-interactive claude plugin marketplace subcommands for scripting and automation. These are equivalent to the /plugin marketplace commands available inside an interactive session.

Plugin marketplace add

Add a marketplace from a GitHub repository, git URL, remote URL, or local path.

claude plugin marketplace add <source> [options]

Arguments:

• <source>: GitHub owner/repo shorthand, git URL, remote URL to a marketplace.json file, or local directory path. To pin to a branch or tag, append @ref to the GitHub shorthand or #ref to a git URL

Options:

Add a marketplace from GitHub using owner/repo shorthand:

claude plugin marketplace add acme-corp/claude-plugins

Pin to a specific branch or tag with @ref:

claude plugin marketplace add acme-corp/[email protected]

Add from a git URL on a non-GitHub host:

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

Add from a remote URL that serves the marketplace.json file directly:

claude plugin marketplace add https://example.com/marketplace.json

Add from a local directory for testing:

claude plugin marketplace add ./my-marketplace

Declare the marketplace at project scope so it is shared with your team via .claude/settings.json:

claude plugin marketplace add acme-corp/claude-plugins --scope project

For a monorepo, limit the checkout to the directories that contain plugin content:

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

Plugin marketplace list

List all configured marketplaces.

claude plugin marketplace list [options]

Options:

Plugin marketplace remove

Remove a configured marketplace. The alias rm is also accepted.

claude plugin marketplace remove <name>

Arguments:

• <name>: marketplace name to remove, as shown by claude plugin marketplace list. This is the name from marketplace.json, not the source you passed to add

Plugin marketplace update

Refresh marketplaces from their sources to retrieve new plugins and version changes.

claude plugin marketplace update [name]

Arguments:

• [name]: marketplace name to update, as shown by claude plugin marketplace list. Updates all marketplaces if omitted

Both remove and update fail when run against a seed-managed marketplace, which is read-only. When updating all marketplaces, seed-managed entries are skipped and other marketplaces still update. To change seed-provided plugins, ask your administrator to update the seed image. See Pre-populate plugins for containers.

Troubleshooting

Marketplace not loading

Symptoms: Can't add marketplace or see plugins from it

Solutions:

• Verify the marketplace URL is accessible
• Check that .claude-plugin/marketplace.json exists at the specified path
• Ensure JSON syntax is valid and frontmatter is well-formed using claude plugin validate or /plugin validate
• For private repositories, confirm you have access permissions

Marketplace validation errors

Run claude plugin validate . or /plugin validate . from your marketplace directory to check for issues. The validator checks plugin.json, skill/agent/command frontmatter, and hooks/hooks.json for syntax and schema errors. Common errors:

Warnings (non-blocking):

• Marketplace has no plugins defined: add at least one plugin to the plugins array
• No marketplace description provided: add metadata.description to help users understand your marketplace
• Plugin name "x" is not kebab-case: the plugin name contains uppercase letters, spaces, or special characters. Rename to lowercase letters, digits, and hyphens only (for example, my-plugin). Claude Code accepts other forms, but the Claude.ai marketplace sync rejects them.

Plugin installation failures

Symptoms: Marketplace appears but plugin installation fails

Solutions:

• Verify plugin source URLs are accessible
• Check that plugin directories contain required files
• For GitHub sources, ensure repositories are public or you have access
• Test plugin sources manually by cloning/downloading

Private repository authentication fails

Symptoms: Authentication errors when installing plugins from private repositories

Solutions:

For manual installation and updates:

• Verify you're authenticated with your git provider (for example, run gh auth status for GitHub)
• Check that your credential helper is configured correctly: git config --global credential.helper
• Try cloning the repository manually to verify your credentials work

For background auto-updates:

• Set the appropriate token in your environment: echo $GITHUB_TOKEN
• Check that the token has the required permissions (read access to the repository)
• For GitHub, ensure the token has the repo scope for private repositories
• For GitLab, ensure the token has at least read_repository scope
• Verify the token hasn't expired

Marketplace updates fail in offline environments

Symptoms: Marketplace git pull fails and Claude Code wipes the existing cache, causing plugins to become unavailable.

Cause: By default, when a git pull fails, Claude Code removes the stale clone and attempts to re-clone. In offline or airgapped environments, re-cloning fails the same way, leaving the marketplace directory empty.

Solution: Set CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 to keep the existing cache when the pull fails instead of wiping it:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

With this variable set, Claude Code retains the stale marketplace clone on git pull failure and continues using the last-known-good state. For fully offline deployments where the repository will never be reachable, use CLAUDE_CODE_PLUGIN_SEED_DIR to pre-populate the plugins directory at build time instead.

Git operations time out

Symptoms: Plugin installation or marketplace updates fail with a timeout error like "Git clone timed out after 120s" or "Git pull timed out after 120s".

Cause: Claude Code uses a 120-second timeout for all git operations, including cloning plugin repositories and pulling marketplace updates. Large repositories or slow network connections may exceed this limit.

Solution: Increase the timeout using the CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS environment variable. The value is in milliseconds:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutes

Plugins with relative paths fail in URL-based marketplaces

Symptoms: Added a marketplace via URL (such as https://example.com/marketplace.json), but plugins with relative path sources like "./plugins/my-plugin" fail to install with "path not found" errors.

Cause: URL-based marketplaces only download the marketplace.json file itself. They do not download plugin files from the server. Relative paths in the marketplace entry reference files on the remote server that were not downloaded.

Solutions:

• Use external sources: Change plugin entries to use GitHub, npm, or git URL sources instead of relative paths:

  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  

• Use a Git-based marketplace: Host your marketplace in a Git repository and add it with the git URL. Git-based marketplaces clone the entire repository, making relative paths work correctly.

Files not found after installation

Symptoms: Plugin installs but references to files fail, especially files outside the plugin directory

Cause: Plugins are copied to a cache directory rather than used in-place. Paths that reference files outside the plugin's directory (such as ../shared-utils) won't work because those files aren't copied.

Solutions: See Plugin caching and file resolution for workarounds including symlinks and directory restructuring.

For additional debugging tools and common issues, see Debugging and development tools.

See also

• Discover and install prebuilt plugins - Installing plugins from existing marketplaces
• Plugins - Creating your own plugins
• Plugins reference - Complete technical specifications and schemas
• Plugin settings - Plugin configuration options
• strictKnownMarketplaces reference - Managed marketplace restrictions