The user is asking about "AutoCoder" and how to enable permissions for Claude to do things like web searches. They may be referring to Claude Code.

Find information about:
1. How to enable/configure permissions in Claude Code for web searches and other tools
2. The settings files and permission formats (like Bash(command:*), WebFetch, WebSearch permissions)
3. How to configure "always allow" permissions

Focus on practical configuration steps.


I'll help you understand how to enable permissions in Claude Code for web searches and other tools. Let me fetch the official Claude Code documentation.


WebFetch

Prompt: permissions settings configuration allow deny ask


# null

# Claude Code Documentation Map

This is a comprehensive map of all Claude Code documentation pages with their headings, designed for easy navigation by LLMs.

> **Note:** This file is auto-generated by GitHub Actions. Do not edit manually.
> Last updated: 2025-11-06 00:10:13 UTC

## Document Structure

This map uses a hierarchical structure:

* **##** marks documentation groups (e.g., 'Getting started')
* **###** marks individual documentation pages
* **Nested bullets** show the heading structure within each page
* Each page title links to the full documentation

## Getting started

### [overview](https://code.claude.com/docs/en/overview.md)

* Get started in 30 seconds
* What Claude Code does for you
* Why developers love Claude Code
* Next steps
* Additional resources

### [quickstart](https://code.claude.com/docs/en/quickstart.md)

* Before you begin
* Step 1: Install Claude Code
* Step 2: Log in to your account
* Step 3: Start your first session
* Step 4: Ask your first question
* Step 5: Make your first code change
* Step 6: Use Git with Claude Code
* Step 7: Fix a bug or add a feature
* Step 8: Test out other common workflows
* Essential commands
* Pro tips for beginners
* What's next?
* Getting help

### [common-workflows](https://code.claude.com/docs/en/common-workflows.md)

* Understand new codebases
  * Get a quick codebase overview
  * Find relevant code
* Fix bugs efficiently
* Refactor code
* Use specialized subagents
* Use Plan Mode for safe code analysis
  * When to use Plan Mode
  * How to use Plan Mode
  * Example: Planning a complex refactor
  * Configure Plan Mode as default
* Work with tests
* Create pull requests
* Handle documentation
* Work with images
* Reference files and directories
* Use extended thinking
* Resume previous conversations
* Run parallel Claude Code sessions with Git worktrees
* Use Claude as a unix-style utility
  * Add Claude to your verification process
  * Pipe in, pipe out
  * Control output format
* Create custom slash commands
  * Create project-specific commands
  * Add command arguments with \$ARGUMENTS
  * Create personal slash commands
* Ask Claude about its capabilities
  * Example questions
* Next steps

### [claude-code-on-the-web](https://code.claude.com/docs/en/claude-code-on-the-web.md)

* What is Claude Code on the web?
* Who can use Claude Code on the web?
* Getting started
* How it works
* Moving tasks between web and terminal
  * From web to terminal
* Cloud environment
  * Default image
    * Checking available tools
    * Language-specific setups
  * Environment configuration
  * Dependency management
    * Local vs remote execution
    * Persisting environment variables
* Network access and security
  * Network policy
    * GitHub proxy
    * Security proxy
  * Access levels
  * Default allowed domains
    * Anthropic Services
    * Version Control
    * Container Registries
    * Cloud Platforms
    * Package Managers - JavaScript/Node
    * Package Managers - Python
    * Package Managers - Ruby
    * Package Managers - Rust
    * Package Managers - Go
    * Package Managers - JVM
    * Package Managers - Other Languages
    * Linux Distributions
    * Development Tools & Platforms
    * Cloud Services & Monitoring
    * Content Delivery & Mirrors
    * Schema & Configuration
  * Security best practices for customized network access
* Security and isolation
* Pricing and rate limits
* Limitations
* Best practices
* Related resources

## Build with Claude Code

### [sub-agents](https://code.claude.com/docs/en/sub-agents.md)

* What are subagents?
* Key benefits
* Quick start
* Subagent configuration
  * File locations
  * Plugin agents
  * CLI-based configuration
  * File format
    * Configuration fields
  * Model selection
  * Available tools
* Managing subagents
  * Using the /agents command (Recommended)
  * Direct file management
* Using subagents effectively
  * Automatic delegation
  * Explicit invocation
* Built-in subagents
  * Plan subagent
* Example subagents
  * Code reviewer
  * Debugger
  * Data scientist
* Best practices
* Advanced usage
  * Chaining subagents
  * Dynamic subagent selection
  * Resumable subagents
* Performance considerations
* Related documentation

### [plugins](https://code.claude.com/docs/en/plugins.md)

* Quickstart
  * Prerequisites
  * Create your first plugin
* Hello Command
  * Plugin structure overview
  * Install and manage plugins
    * Prerequisites
    * Add marketplaces
    * Install plugins
      * Via interactive menu (recommended for discovery)
      * Via direct commands (for quick installation)
    * Verify installation
  * Set up team plugin workflows
  * Develop more complex plugins
    * Add Skills to your plugin
    * Organize complex plugins
    * Test your plugins locally
    * Debug plugin issues
    * Share your plugins
  * Next steps
    * For plugin users
    * For plugin developers
    * For team leads and administrators
  * See also

### [skills](https://code.claude.com/docs/en/skills.md)

* Prerequisites
* What are Agent Skills?
* Create a Skill
  * Personal Skills
  * Project Skills
  * Plugin Skills
* Write SKILL.md
* Add supporting files
* Restrict tool access with allowed-tools
* View available Skills
* Test a Skill
* Debug a Skill
  * Make description specific
  * Verify file path
  * Check YAML syntax
  * View errors
* Share Skills with your team
  * Step 1: Add Skill to your project
  * Step 2: Commit to git
  * Step 3: Team members get Skills automatically
* Update a Skill
* Remove a Skill
* Best practices
  * Keep Skills focused
  * Write clear descriptions
  * Test with your team
  * Document Skill versions
* Troubleshooting
  * Claude doesn't use my Skill
  * Skill has errors
  * Multiple Skills conflict
* Examples
  * Simple Skill (single file)
  * Skill with tool permissions
  * Multi-file Skill
* Next steps

### [output-styles](https://code.claude.com/docs/en/output-styles.md)

* Built-in output styles
* How output styles work
* Change your output style
* Create a custom output style
* Comparisons to related features
  * Output Styles vs. CLAUDE.md vs. --append-system-prompt
  * Output Styles vs. [Agents](/en/sub-agents)
  * Output Styles vs. [Custom Slash Commands](/en/slash-commands)

### [hooks-guide](https://code.claude.com/docs/en/hooks-guide.md)

* Hook Events Overview
* Quickstart
  * Prerequisites
  * Step 1: Open hooks configuration
  * Step 2: Add a matcher
  * Step 3: Add the hook
  * Step 4: Save your configuration
  * Step 5: Verify your hook
  * Step 6: Test your hook
* More Examples
  * Code Formatting Hook
  * Markdown Formatting Hook
  * Custom Notification Hook
  * File Protection Hook
* Learn more

### [headless](https://code.claude.com/docs/en/headless.md)

* Overview
* Basic usage
* Configuration Options
* Multi-turn conversations
* Output Formats
  * Text Output (Default)
  * JSON Output
  * Streaming JSON Output
* Input Formats
  * Text Input (Default)
  * Streaming JSON Input
* Agent Integration Examples
  * SRE Incident Response Bot
  * Automated Security Review
  * Multi-turn Legal Assistant
* Best Practices
* Related Resources

### [github-actions](https://code.claude.com/docs/en/github-actions.md)

* Why use Claude Code GitHub Actions?
* What can Claude do?
  * Claude Code Action
* Setup
* Quick setup
* Manual setup
* Upgrading from Beta
  * Essential changes
  * Breaking Changes Reference
  * Before and After Example
* Example use cases
  * Basic workflow
  * Using slash commands
  * Custom automation with prompts
  * Common use cases
* Best practices
  * CLAUDE.md configuration
  * Security considerations
  * Optimizing performance
  * CI costs
* Configuration examples
* Using with AWS Bedrock & Google Vertex AI
  * Prerequisites
    * For Google Cloud Vertex AI:
    * For AWS Bedrock:
* Troubleshooting
  * Claude not responding to @claude commands
  * CI not running on Claude's commits
  * Authentication errors
* Advanced configuration
  * Action parameters
    * Using claude\_args
  * Alternative integration methods
  * Customizing Claude's behavior

### [gitlab-ci-cd](https://code.claude.com/docs/en/gitlab-ci-cd.md)

* Why use Claude Code with GitLab?
* How it works
* What can Claude do?
* Setup
  * Quick setup
  * Manual setup (recommended for production)
* Example use cases
  * Turn issues into MRs
  * Get implementation help
  * Fix bugs quickly
* Using with AWS Bedrock & Google Vertex AI
* Configuration examples
  * Basic .gitlab-ci.yml (Claude API)
  * AWS Bedrock job example (OIDC)
  * Google Vertex AI job example (Workload Identity Federation)
* Best practices
  * CLAUDE.md configuration
  * Security considerations
  * Optimizing performance
  * CI costs
* Security and governance
* Troubleshooting
  * Claude not responding to @claude commands
  * Job can't write comments or open MRs
  * Authentication errors
* Advanced configuration
  * Common parameters and variables
  * Customizing Claude's behavior

### [mcp](https://code.claude.com/docs/en/mcp.md)

* What you can do with MCP
* Popular MCP servers
* Installing MCP servers
  * Option 1: Add a remote HTTP server
  * Option 2: Add a remote SSE server
  * Option 3: Add a local stdio server
  * Managing your servers
  * Plugin-provided MCP servers
* MCP installation scopes
  * Local scope
  * Project scope
  * User scope
  * Choosing the right scope
  * Scope hierarchy and precedence
  * Environment variable expansion in `.mcp.json`
* Practical examples
  * Example: Monitor errors with Sentry
  * Example: Connect to GitHub for code reviews
  * Example: Query your PostgreSQL database
* Authenticate with remote MCP servers
* Add MCP servers from JSON configuration
* Import MCP servers from Claude Desktop
* Use Claude Code as an MCP server
* MCP output limits and warnings
* Use MCP resources
  * Reference MCP resources
* Use MCP prompts as slash commands
  * Execute MCP prompts
* Managed MCP configuration
  * Setting up enterprise MCP configuration
  * Restricting MCP servers with allowlists and denylists

### [migration-guide](https://code.claude.com/docs/en/migration-guide.md)

* Overview
* What's Changed
* Migration Steps
  * For TypeScript/JavaScript Projects
  * For Python Projects
* Breaking changes
  * Python: ClaudeCodeOptions renamed to ClaudeAgentOptions
  * System prompt no longer default
  * Settings Sources No Longer Loaded by Default
* Why the Rename?
* Getting Help
* Next Steps

### [troubleshooting](https://code.claude.com/docs/en/troubleshooting.md)

* Common installation issues
  * Windows installation issues: errors in WSL
  * Linux and Mac installation issues: permission or command not found errors
    * Recommended solution: Native Claude Code installation
* Permissions and authentication
  * Repeated permission prompts
  * Authentication issues
* Performance and stability
  * High CPU or memory usage
  * Command hangs or freezes
  * Search and discovery issues
  * Slow or incomplete search results on WSL
* IDE integration issues
  * JetBrains IDE not detected on WSL2
    * WSL2 networking modes
  * Reporting Windows IDE integration issues (both native and WSL)
  * ESC key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals
* Markdown formatting issues
  * Missing language tags in code blocks
  * Inconsistent spacing and formatting
  * Best practices for markdown generation
* Getting more help

## Deployment

### [third-party-integrations](https://code.claude.com/docs/en/third-party-integrations.md)

* Provider comparison
* Cloud providers
* Corporate infrastructure
* Configuration overview
  * Using Bedrock with corporate proxy
  * Using Bedrock with LLM Gateway
  * Using Vertex AI with corporate proxy
  * Using Vertex AI with LLM Gateway
  * Authentication configuration
* Choosing the right deployment configuration
  * Direct provider access
  * Corporate proxy
  * LLM Gateway
* Debugging
* Best practices for organizations
  * 1. Invest in documentation and memory
  * 2. Simplify deployment
  * 3. Start with guided usage
  * 4. Configure security policies
  * 5. Leverage MCP for integrations
* Next steps

### [amazon-bedrock](https://code.claude.com/docs/en/amazon-bedrock.md)

* Prerequisites
* Setup
  * 1. Submit use case details
  * 2. Configure AWS credentials
    * Advanced credential configuration
      * Example configuration
      * Configuration settings explained
  * 3. Configure Claude Code
  * 4. Model configuration
  * 5. Output token configuration
* IAM configuration
* Troubleshooting
* Additional resources

### [google-vertex-ai](https://code.claude.com/docs/en/google-vertex-ai.md)

* Prerequisites
* Region Configuration
* Setup
  * 1. Enable Vertex AI API
  * 2. Request model access
  * 3. Configure GCP credentials
  * 4. Configure Claude Code
  * 5. Model configuration
* IAM configuration
* 1M token context window
* Troubleshooting
* Additional resources

### [network-config](https://code.claude.com/docs/en/network-config.md)

* Proxy configuration
  * Environment variables
  * Basic authentication
* Custom CA certificates
* mTLS authentication
* Network access requirements
* Additional resources

### [llm-gateway](https://code.claude.com/docs/en/llm-gateway.md)

* LiteLLM configuration
  * Prerequisites
  * Basic LiteLLM setup
    * Authentication methods
      * Static API key
      * Dynamic API key with helper
    * Unified endpoint (recommended)
    * Provider-specific pass-through endpoints (alternative)
      * Claude API through LiteLLM
      * Amazon Bedrock through LiteLLM
      * Google Vertex AI through LiteLLM
  * Model selection
* Additional resources

### [devcontainer](https://code.claude.com/docs/en/devcontainer.md)

* Key features
* Getting started in 4 steps
* Configuration breakdown
* Security features
* Customization options
* Example use cases
  * Secure client work
  * Team onboarding
  * Consistent CI/CD environments
* Related resources

### [sandboxing](https://code.claude.com/docs/en/sandboxing.md)

* Overview
* Why sandboxing matters
* How it works
  * Filesystem isolation
  * Network isolation
  * OS-level enforcement
* Getting started
  * Enable sandboxing
  * Configure sandboxing
* Security benefits
  * Protection against prompt injection
  * Reduced attack surface
  * Transparent operation
* Security Limitations
* Advanced usage
  * Custom proxy configuration
  * Integration with existing security tools
* Best practices
* Open source
* Limitations
* See also

## Administration

### [setup](https://code.claude.com/docs/en/setup.md)

* System requirements
  * Additional dependencies
* Standard installation
* Windows setup
* Alternative installation methods
  * Native installation options
  * NPM installation
* Running on AWS or GCP
* Update Claude Code
  * Auto updates
  * Update manually

### [iam](https://code.claude.com/docs/en/iam.md)

* Authentication methods
  * Claude API authentication
  * Cloud provider authentication
* Access control and permissions
  * Permission system
  * Configuring permissions
    * Permission modes
    * Working directories
    * Tool-specific permission rules
  * Additional permission control with hooks
  * Managed policy settings
  * Settings precedence
* Credential management

### [security](https://code.claude.com/docs/en/security.md)

* How we approach security
  * Security foundation
  * Permission-based architecture
  * Built-in protections
  * User responsibility
* Protect against prompt injection
  * Core protections
  * Privacy safeguards
  * Additional safeguards
* MCP security
* IDE security
* Cloud execution security
* Security best practices
  * Working with sensitive code
  * Team security
  * Reporting security issues
* Related resources

### [data-usage](https://code.claude.com/docs/en/data-usage.md)

* Data policies
  * Data training policy
  * Development Partner Program
  * Feedback using the `/bug` command
  * Session quality surveys
  * Data retention
* Data flow and dependencies
  * Cloud execution
* Telemetry services
* Default behaviors by API provider

### [monitoring-usage](https://code.claude.com/docs/en/monitoring-usage.md)

* Quick Start
* Administrator Configuration
* Configuration Details
  * Common Configuration Variables
  * Metrics Cardinality Control
  * Dynamic Headers
    * Settings Configuration
    * Script Requirements
    * Important Limitations
  * Multi-Team Organization Support
  * Example Configurations
* Available Metrics and Events
  * Standard Attributes
  * Metrics
  * Metric Details
    * Session Counter
    * Lines of Code Counter
    * Pull Request Counter
    * Commit Counter
    * Cost Counter
    * Token Counter
    * Code Edit Tool Decision Counter
    * Active Time Counter
  * Events
    * User Prompt Event
    * Tool Result Event
    * API Request Event
    * API Error Event
    * Tool Decision Event
* Interpreting Metrics and Events Data
  * Usage Monitoring
  * Cost Monitoring
  * Alerting and Segmentation
  * Event Analysis
* Backend Considerations
  * For Metrics:
  * For Events/Logs:
* Service Information
* ROI Measurement Resources
* Security/Privacy Considerations
* Monitoring Claude Code on Amazon Bedrock

### [costs](https://code.claude.com/docs/en/costs.md)

* Track your costs
  * Using the `/cost` command
  * Additional tracking options
* Managing costs for teams
  * Rate limit recommendations
* Reduce token usage
* Background token usage
* Tracking version changes and updates
  * Current version information
  * Understanding changes in Claude Code behavior
  * When cost reporting changes

### [analytics](https://code.claude.com/docs/en/analytics.md)

* Access analytics
  * Required roles
* Available metrics
  * Lines of code accepted
  * Suggestion accept rate
  * Activity
  * Spend
  * Team insights
* Using analytics effectively
  * Monitor adoption
  * Measure productivity
* Related resources

### [plugin-marketplaces](https://code.claude.com/docs/en/plugin-marketplaces.md)

* Overview
  * Prerequisites
* Add and use marketplaces
  * Add GitHub marketplaces
  * Add Git repositories
  * Add local marketplaces for development
  * Install plugins from marketplaces
  * Verify marketplace installation
* Configure team marketplaces
* Create your own marketplace
  * Prerequisites for marketplace creation
  * Create the marketplace file
  * Marketplace schema
    * Required fields
    * Optional metadata
  * Plugin entries
    * Optional plugin fields
  * Plugin sources
    * Relative paths
    * GitHub repositories
    * Git repositories
    * Advanced plugin entries
* Host and distribute marketplaces
  * Host on GitHub (recommended)
  * Host on other git services
  * Use local marketplaces for development
* Manage marketplace operations
  * List known marketplaces
  * Update marketplace metadata
  * Remove a marketplace
* Troubleshooting marketplaces
  * Common marketplace issues
    * Marketplace not loading
    * Plugin installation failures
  * Validation and testing
* Next steps
  * For marketplace users
  * For marketplace creators
  * For organizations
* See also

## Configuration

### [settings](https://code.claude.com/docs/en/settings.md)

* Settings files
  * Available settings
  * Permission settings
  * Sandbox settings
  * Settings precedence
  * Key points about the configuration system
  * System prompt availability
  * Excluding sensitive files
* Subagent configuration
* Plugin configuration
  * Plugin settings
    * `enabledPlugins`
    * `extraKnownMarketplaces`
  * Managing plugins
* Environment variables
* Tools available to Claude
  * Extending tools with hooks
* See also

### [vs-code](https://code.claude.com/docs/en/vs-code.md)

* VS Code Extension (Beta)
  * Features
  * Requirements
  * Installation
  * How It Works
  * Using Third-Party Providers (Vertex and Bedrock)
    * Environment Variables
  * Not Yet Implemented
* Security Considerations
* Legacy CLI Integration
* Troubleshooting
  * Extension Not Installing
  * Legacy Integration Not Working

### [jetbrains](https://code.claude.com/docs/en/jetbrains.md)

* Supported IDEs
* Features
* Installation
  * Marketplace Installation
* Usage
  * From Your IDE
  * From External Terminals
* Configuration
  * Claude Code Settings
  * Plugin Settings
    * General Settings
    * ESC Key Configuration
* Special Configurations
  * Remote Development
  * WSL Configuration
* Troubleshooting
  * Plugin Not Working
  * IDE Not Detected
  * Command Not Found
* Security Considerations

### [terminal-config](https://code.claude.com/docs/en/terminal-config.md)

* Themes and appearance
* Line breaks
  * Set up Shift+Enter (VS Code or iTerm2):
  * Set up Option+Enter (VS Code, iTerm2 or macOS Terminal.app):
* Notification setup
  * iTerm 2 system notifications
  * Custom notification hooks
* Handling large inputs
* Vim Mode

### [model-config](https://code.claude.com/docs/en/model-config.md)

* Available models
  * Model aliases
  * Setting your model
* Special model behavior
  * `default` model setting
  * `opusplan` model setting
  * Extended context with \[1m]
* Checking your current model
* Environment variables
  * Prompt caching configuration

### [memory](https://code.claude.com/docs/en/memory.md)

* Determine memory type
* CLAUDE.md imports
* How Claude looks up memories
* Quickly add memories with the `#` shortcut
* Directly edit memories with `/memory`
* Set up project memory
* Organization-level memory management
* Memory best practices

### [statusline](https://code.claude.com/docs/en/statusline.md)

* Create a custom status line
* How it Works
* JSON Input Structure
* Example Scripts
  * Simple Status Line
  * Git-Aware Status Line
  * Python Example
  * Node.js Example
  * Helper Function Approach
* Tips
* Troubleshooting

## Reference

### [cli-reference](https://code.claude.com/docs/en/cli-reference.md)

* CLI commands
* CLI flags
  * Agents flag format
  * System prompt flags
* See also

### [interactive-mode](https://code.claude.com/docs/en/interactive-mode.md)

* Keyboard shortcuts
  * General controls
  * Multiline input
  * Quick commands
* Vim editor mode
  * Mode switching
  * Navigation (NORMAL mode)
  * Editing (NORMAL mode)
* Command history
  * Reverse search with Ctrl+R
* Background bash commands
  * How backgrounding works
  * Bash mode with `!` prefix
* See also

### [slash-commands](https://code.claude.com/docs/en/slash-commands.md)

* Built-in slash commands
* Custom slash commands
  * Syntax
    * Parameters
  * Command types
    * Project commands
    * Personal commands
  * Features
    * Namespacing
    * Arguments
      * All arguments with `$ARGUMENTS`
      * Individual arguments with `$1`, `$2`, etc.
    * Bash command execution
    * File references
    * Thinking mode
  * Frontmatter
* Plugin commands
  * How plugin commands work
  * Plugin command structure
  * Invocation patterns
* MCP slash commands
  * Command format
  * Features
    * Dynamic discovery
    * Arguments
    * Naming conventions
  * Managing MCP connections
  * MCP permissions and wildcards
* `SlashCommand` tool
  * `SlashCommand` tool supported commands
  * Disable `SlashCommand` tool
  * Disable specific commands only
  * `SlashCommand` permission rules
  * Character budget limit
* Skills vs slash commands
  * Use slash commands for
  * Use Skills for
  * Key differences
  * Example comparison
  * When to use each
* See also

### [checkpointing](https://code.claude.com/docs/en/checkpointing.md)

* How checkpoints work
  * Automatic tracking
  * Rewinding changes
* Common use cases
* Limitations
  * Bash command changes not tracked
  * External changes not tracked
  * Not a replacement for version control
* See also

### [hooks](https://code.claude.com/docs/en/hooks.md)

* Configuration
  * Structure
  * Project-Specific Hook Scripts
  * Plugin hooks
* Prompt-Based Hooks
  * How prompt-based hooks work
  * Configuration
  * Response schema
  * Supported hook events
  * Example: Intelligent Stop hook
  * Example: SubagentStop with custom logic
  * Comparison with bash command hooks
  * Best practices
* Hook Events
  * PreToolUse
  * PermissionRequest
  * PostToolUse
  * Notification
  * UserPromptSubmit
  * Stop
  * SubagentStop
  * PreCompact
  * SessionStart
    * Persisting environment variables
  * SessionEnd
* Hook Input
  * PreToolUse Input
  * PermissionRequest
  * PostToolUse Input
  * Notification Input
  * UserPromptSubmit Input
  * Stop and SubagentStop Input
  * PreCompact Input
  * SessionStart Input
  * SessionEnd Input
* Hook Output
  * Simple: Exit Code
    * Exit Code 2 Behavior
  * Advanced: JSON Output
    * Common JSON Fields
    * `PreToolUse` Decision Control
    * `PermissionRequest` Decision Control
    * `PostToolUse` Decision Control
    * `UserPromptSubmit` Decision Control
    * `Stop`/`SubagentStop` Decision Control
    * `SessionStart` Decision Control
    * `SessionEnd` Decision Control
    * Exit Code Example: Bash Command Validation
    * JSON Output Example: UserPromptSubmit to Add Context and Validation
    * JSON Output Example: PreToolUse with Approval
* Working with MCP Tools
  * MCP Tool Naming
  * Configuring Hooks for MCP Tools
* Examples
* Security Considerations
  * Disclaimer
  * Security Best Practices
  * Configuration Safety
* Hook Execution Details
* Debugging
  * Basic Troubleshooting
  * Advanced Debugging
  * Debug Output Example

### [plugins-reference](https://code.claude.com/docs/en/plugins-reference.md)

* Plugin components reference
  * Commands
  * Agents
  * Skills
  * Hooks
  * MCP servers
* Plugin manifest schema
  * Complete schema
  * Required fields
  * Metadata fields
  * Component path fields
  * Path behavior rules
  * Environment variables
* Plugin directory structure
  * Standard plugin layout
  * File locations reference
* Debugging and development tools
  * Debugging commands
  * Common issues
* Distribution and versioning reference
  * Version management

## Resources

### [legal-and-compliance](https://code.claude.com/docs/en/legal-and-compliance.md)

* Legal agreements
  * License
  * Commercial agreements
* Compliance
  * Healthcare compliance (BAA)
* Security and trust
  * Trust and safety
  * Security vulnerability reporting

---

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


Now let me fetch the settings documentation which covers permissions configuration:


Prompt: permissions allow deny ask configuration format WebSearch WebFetch Bash


Prompt: permissions access control allow deny ask configuration tool-specific rules


# Claude Code settings

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

Claude Code offers a variety of settings to configure its behavior to meet your needs. You can configure Claude Code by running the `/config` command when using the interactive REPL, which opens a tabbed Settings interface where you can view status information and modify configuration options.

## Configuration scopes

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

### Available scopes

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

### When to use each scope

**Managed scope** is for:

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

**User scope** is best for:

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

**Project scope** is best for:

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

**Local scope** is best for:

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

### How scopes interact

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

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

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

### What uses scopes

Scopes apply to many Claude Code features:

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

***

## Settings files

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

* **User settings** are defined in `~/.claude/settings.json` and apply to all
  projects.
* **Project settings** are saved in your project directory:
  * `.claude/settings.json` for settings that are checked into source control and shared with your team
  * `.claude/settings.local.json` for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore `.claude/settings.local.json` when it is created.
* **Managed settings**: For organizations that need centralized control, Claude Code supports `managed-settings.json` and `managed-mcp.json` files that can be deployed to system directories:

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

  <Note>
    These are system-wide paths (not user home directories like `~/Library/...`) that require administrator privileges. They are designed to be deployed by IT administrators.
  </Note>

  See [Managed settings](/en/iam#managed-settings) and [Managed MCP configuration](/en/mcp#managed-mcp-configuration) for details.

  <Note>
    Managed deployments can also restrict **plugin marketplace additions** using
    `strictKnownMarketplaces`. For more information, see [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions).
  </Note>
* **Other configuration** is stored in `~/.claude.json`. This file contains your preferences (theme, notification settings, editor mode), OAuth session, [MCP server](/en/mcp) configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in `.mcp.json`.

```JSON Example settings.json theme={null}
{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}
```

### Available settings

`settings.json` supports a number of options:

| Key                          | Description                                                                                | Example                                                                 |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- |
| `apiKeyHelper`               | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests                                                                                | `/bin/generate_temp_api_key.sh`                                         |
| `cleanupPeriodDays`          | Sessions inactive for longer than this period are deleted at startup. Setting to `0` immediately deletes all sessions. (default: 30 days)                                                                                | `20`                                                                    |
| `companyAnnouncements`       | Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random.                                                                                | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |
| `env`                        | Environment variables that will be applied to every session                                                                                | `{"FOO": "bar"}`                                                        |
| `attribution`                | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings)                                                                                | `{"commit": "🤖 Generated with Claude Code", "pr": ""}`                 |
| `includeCoAuthoredBy`        | **Deprecated**: Use `attribution` instead. Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`)                                                                                | `false`                                                                 |
| `permissions`                | See table below for structure of permissions.                                                                                |                                                                         |
| `hooks`                      | Configure custom commands to run before or after tool executions. See [hooks documentation](/en/hooks)                                                                                | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}`                 |
| `disableAllHooks`            | Disable all [hooks](/en/hooks)                                                                                | `true`                                                                  |
| `allowManagedHooksOnly`      | (Managed settings only) Prevent loading of user, project, and plugin hooks. Only allows managed hooks and SDK hooks. See [Hook configuration](#hook-configuration)                                                                                | `true`                                                                  |
| `model`                      | Override the default model to use for Claude Code                                                                                | `"claude-sonnet-4-5-20250929"`                                          |
| `otelHeadersHelper`          | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically (see [Dynamic headers](/en/monitoring-usage#dynamic-headers))                                                                                | `/bin/generate_otel_headers.sh`                                         |
| `statusLine`                 | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline)                                                                                | `{"type": "command", "command": "~/.claude/statusline.sh"}`             |
| `fileSuggestion`             | Configure a custom script for `@` file autocomplete. See [File suggestion settings](#file-suggestion-settings)                                                                                | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}`        |
| `respectGitignore`           | Control whether the `@` file picker respects `.gitignore` patterns. When `true` (default), files matching `.gitignore` patterns are excluded from suggestions                                                                                | `false`                                                                 |
| `outputStyle`                | Configure an output style to adjust the system prompt. See [output styles documentation](/en/output-styles)                                                                                | `"Explanatory"`                                                         |
| `forceLoginMethod`           | Use `claudeai` to restrict login to Claude.ai accounts, `console` to restrict login to Claude Console (API usage billing) accounts                                                                                | `claudeai`                                                              |
| `forceLoginOrgUUID`          | Specify the UUID of an organization to automatically select it during login, bypassing the organization selection step. Requires `forceLoginMethod` to be set                                                                                | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`                                |
| `enableAllProjectMcpServers` | Automatically approve all MCP servers defined in project `.mcp.json` files                                                                                | `true`                                                                  |
| `enabledMcpjsonServers`      | List of specific MCP servers from `.mcp.json` files to approve                                                                                | `["memory", "github"]`                                                  |
| `disabledMcpjsonServers`     | List of specific MCP servers from `.mcp.json` files to reject                                                                                | `["filesystem"]`                                                        |
| `allowedMcpServers`          | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration)                      | `[{ "serverName": "github" }]`                                          |
| `deniedMcpServers`           | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including managed servers. Denylist takes precedence over allowlist. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration)                           | `[{ "serverName": "filesystem" }]`                                      |
| `strictKnownMarketplaces`    | When set in managed-settings.json, allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]`                 |
| `awsAuthRefresh`             | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration))                                                                                | `aws sso login --profile myprofile`                                     |
| `awsCredentialExport`        | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration))                                                                                | `/bin/generate_aws_grant.sh`                                            |
| `alwaysThinkingEnabled`      | Enable [extended thinking](/en/common-workflows#use-extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly                                                                                | `true`                                                                  |
| `language`                   | Configure Claude's preferred response language (e.g., `"japanese"`, `"spanish"`, `"french"`). Claude will respond in this language by default                                                                                | `"japanese"`                                                            |

### Permission settings

| Keys                           | Description                                                                                | Example                                                                |
| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |
| `allow`                        | Array of [permission rules](/en/iam#configuring-permissions) to allow tool use. **Note:** Bash rules use prefix matching, not regex                                                                                | `[ "Bash(git diff:*)" ]`                                               |
| `ask`                          | Array of [permission rules](/en/iam#configuring-permissions) to ask for confirmation upon tool use.                                                                                | `[ "Bash(git push:*)" ]`                                               |
| `deny`                         | Array of [permission rules](/en/iam#configuring-permissions) to deny tool use. Use this to also exclude sensitive files from Claude Code access. **Note:** Bash patterns are prefix matches and can be bypassed (see [Bash permission limitations](/en/iam#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |
| `additionalDirectories`        | Additional [working directories](/en/iam#working-directories) that Claude has access to                                                                                | `[ "../docs/" ]`                                                       |
| `defaultMode`                  | Default [permission mode](/en/iam#permission-modes) when opening Claude Code                                                                                | `"acceptEdits"`                                                        |
| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed settings](/en/iam#managed-settings)                                                                                | `"disable"`                                                            |

### Sandbox settings

Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See [Sandboxing](/en/sandboxing) for details.

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

| Keys                        | Description                                                                                | Example                   |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------ |
| `enabled`                   | Enable bash sandboxing (macOS/Linux only). Default: false                                                                                | `true`                    |
| `autoAllowBashIfSandboxed`  | Auto-approve bash commands when sandboxed. Default: true                                                                                | `true`                    |
| `excludedCommands`          | Commands that should run outside of the sandbox                                                                                | `["git", "docker"]`       |
| `allowUnsandboxedCommands`  | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false`                   |
| `network.allowUnixSockets`  | Unix socket paths accessible in sandbox (for SSH agents, etc.)                                                                                | `["~/.ssh/agent-socket"]` |
| `network.allowLocalBinding` | Allow binding to localhost ports (macOS only). Default: false                                                                                | `true`                    |
| `network.httpProxyPort`     | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy.                                                                                | `8080`                    |
| `network.socksProxyPort`    | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy.                                                                                | `8081`                    |
| `enableWeakerNestedSandbox` | Enable weaker sandbox for unprivileged Docker environments (Linux only). **Reduces security.** Default: false                                                                                | `true`                    |

**Configuration example:**

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

**Filesystem and network restrictions** use standard permission rules:

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

### Attribution settings

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

* Commits use [git trailers](https://git-scm.com/docs/git-interpret-trailers) (like `Co-Authored-By`) by default,  which can be customized or disabled
* Pull request descriptions are plain text

| Keys     | Description                                                                                |
| :------- | :----------------------------------------------------------------------------------------- |
| `commit` | Attribution for git commits, including any trailers. Empty string hides commit attribution |
| `pr`     | Attribution for pull request descriptions. Empty string hides pull request attribution     |

**Default commit attribution:**

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

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

**Default pull request attribution:**

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

**Example:**

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

<Note>
  The `attribution` setting takes precedence over the deprecated `includeCoAuthoredBy` setting. To hide all attribution, set `commit` and `pr` to empty strings.
</Note>

### File suggestion settings

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

```json  theme={null}
{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}
```

The command runs with the same environment variables as [hooks](/en/hooks), including `CLAUDE_PROJECT_DIR`. It receives JSON via stdin with a `query` field:

```json  theme={null}
{"query": "src/comp"}
```

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

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

**Example:**

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

### Hook configuration

**Managed settings only**: Controls which hooks are allowed to run. This setting can only be configured in [managed settings](#settings-files) and provides administrators with strict control over hook execution.

**Behavior when `allowManagedHooksOnly` is `true`:**

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

**Configuration:**

```json  theme={null}
{
  "allowManagedHooksOnly": true
}
```

### Settings precedence

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

1. **Managed settings** (`managed-settings.json`)
   * Policies deployed by IT/DevOps to system directories
   * Cannot be overridden by user or project settings

2. **Command line arguments**
   * Temporary overrides for a specific session

3. **Local project settings** (`.claude/settings.local.json`)
   * Personal project-specific settings

4. **Shared project settings** (`.claude/settings.json`)
   * Team-shared project settings in source control

5. **User settings** (`~/.claude/settings.json`)
   * Personal global settings

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

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

### Key points about the configuration system

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

### System prompt

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

### Excluding sensitive files

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

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

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

## Subagent configuration

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

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

Subagent files define specialized AI assistants with custom prompts and tool permissions. Learn more about creating and using subagents in the [subagents documentation](/en/sub-agents).

## Plugin configuration

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

### Plugin settings

Plugin-related settings in `settings.json`:

```json  theme={null}
{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": "github",
      "repo": "acme-corp/claude-plugins"
    }
  }
}
```

#### `enabledPlugins`

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

**Scopes**:

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

**Example**:

```json  theme={null}
{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}
```

#### `extraKnownMarketplaces`

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

**When a repository includes `extraKnownMarketplaces`**:

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

**Example**:

```json  theme={null}
{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}
```

**Marketplace source types**:

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

#### `strictKnownMarketplaces`

**Managed settings only**: Controls which plugin marketplaces users are allowed to add. This setting can only be configured in [`managed-settings.json`](/en/iam#managed-settings) and provides administrators with strict control over marketplace sources.

**Managed settings file locations**:

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

**Key characteristics**:

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

**Allowlist behavior**:

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

**All supported source types**:

The allowlist supports six marketplace source types. Each source must match exactly for a user's marketplace addition to be allowed.

1. **GitHub repositories**:

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

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

2. **Git repositories**:

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

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

3. **URL-based marketplaces**:

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

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

4. **NPM packages**:

```json  theme={null}
{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }
```

Fields: `package` (required, supports scoped packages)

5. **File paths**:

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

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

6. **Directory paths**:

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

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

**Configuration examples**:

Example - Allow specific marketplaces only:

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

Example - Disable all marketplace additions:

```json  theme={null}
{
  "strictKnownMarketplaces": []
}
```

**Exact matching requirements**:

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

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

Examples of sources that **do NOT match**:

```json  theme={null}
// These are DIFFERENT sources:
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

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

**Comparison with `extraKnownMarketplaces`**:

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

**Format difference**:

`strictKnownMarketplaces` uses direct source objects:

```json  theme={null}
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}
```

`extraKnownMarketplaces` requires named marketplaces:

```json  theme={null}
{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}
```

**Important notes**:

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

See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) for user-facing documentation.

### Managing plugins

Use the `/plugin` command to manage plugins interactively:

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

Learn more about the plugin system in the [plugins documentation](/en/plugins).

## Environment variables

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

<Note>
  All environment variables can also be configured in [`settings.json`](#available-settings). This is useful as a way to automatically set environment variables for each session, or to roll out a set of environment variables for your whole team or organization.
</Note>

| Variable                                      | Purpose                                                                                |
| :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ANTHROPIC_API_KEY`                           | API key sent as `X-Api-Key` header, typically for the Claude SDK (for interactive usage, run `/login`)                                                                                |
| `ANTHROPIC_AUTH_TOKEN`                        | Custom value for the `Authorization` header (the value you set here will be prefixed with `Bearer `)                                                                                |
| `ANTHROPIC_CUSTOM_HEADERS`                    | Custom headers you want to add to the request (in `Name: Value` format)                                                                                |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL`               | See [Model configuration](/en/model-config#environment-variables)                                                                                |
| `ANTHROPIC_DEFAULT_OPUS_MODEL`                | See [Model configuration](/en/model-config#environment-variables)                                                                                |
| `ANTHROPIC_DEFAULT_SONNET_MODEL`              | See [Model configuration](/en/model-config#environment-variables)                                                                                |
| `ANTHROPIC_FOUNDRY_API_KEY`                   | API key for Microsoft Foundry authentication (see [Microsoft Foundry](/en/microsoft-foundry))                                                                                |
| `ANTHROPIC_MODEL`                             | Name of the model setting to use (see [Model Configuration](/en/model-config#environment-variables))                                                                                |
| `ANTHROPIC_SMALL_FAST_MODEL`                  | \[DEPRECATED] Name of [Haiku-class model for background tasks](/en/costs)                                                                                |
| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION`       | Override AWS region for the Haiku-class model when using Bedrock                                                                                |
| `AWS_BEARER_TOKEN_BEDROCK`                    | Bedrock API key for authentication (see [Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/))                                                                                |
| `BASH_DEFAULT_TIMEOUT_MS`                     | Default timeout for long-running bash commands                                                                                |
| `BASH_MAX_OUTPUT_LENGTH`                      | Maximum number of characters in bash outputs before they are middle-truncated                                                                                |
| `BASH_MAX_TIMEOUT_MS`                         | Maximum timeout the model can set for long-running bash commands                                                                                |
| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR`    | Return to the original working directory after each Bash command                                                                                |
| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS`           | Interval in milliseconds at which credentials should be refreshed (when using `apiKeyHelper`)                                                                                |
| `CLAUDE_CODE_CLIENT_CERT`                     | Path to client certificate file for mTLS authentication                                                                                |
| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`           | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional)                                                                                |
| `CLAUDE_CODE_CLIENT_KEY`                      | Path to client private key file for mTLS authentication                                                                                |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`      | Set to `1` to disable Anthropic API-specific `anthropic-beta` headers. Use this if experiencing issues like "Unexpected value(s) for the `anthropic-beta` header" when using an LLM gateway with third-party providers                                                                                |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`    | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY`                                                                                |
| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE`          | Set to `1` to disable automatic terminal title updates based on conversation context                                                                                |
| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS`     | Override the default token limit for file reads. Useful when you need to read larger files in full                                                                                |
| `CLAUDE_CODE_HIDE_ACCOUNT_INFO`               | Set to `1` to hide your email address and organization name from the Claude Code UI. Useful when streaming or recording                                                                                |
| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`           | Skip auto-installation of IDE extensions                                                                                |
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS`               | Set the maximum number of output tokens for most requests                                                                                |
| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic OpenTelemetry headers in milliseconds (default: 1740000 / 29 minutes). See [Dynamic headers](/en/monitoring-usage#dynamic-headers)                                                                                |
| `CLAUDE_CODE_SHELL`                           | Override automatic shell detection. Useful when your login shell differs from your preferred working shell (for example, `bash` vs `zsh`)                                                                                |
| `CLAUDE_CODE_SHELL_PREFIX`                    | Command prefix to wrap all bash commands (for example, for logging or auditing). Example: `/path/to/logger.sh` will execute `/path/to/logger.sh <command>`                                                                                |
| `CLAUDE_CODE_SKIP_BEDROCK_AUTH`               | Skip AWS authentication for Bedrock (for example, when using an LLM gateway)                                                                                |
| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH`               | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway)                                                                                |
| `CLAUDE_CODE_SKIP_VERTEX_AUTH`                | Skip Google authentication for Vertex (for example, when using an LLM gateway)                                                                                |
| `CLAUDE_CODE_SUBAGENT_MODEL`                  | See [Model configuration](/en/model-config)                                                                                |
| `CLAUDE_CODE_USE_BEDROCK`                     | Use [Bedrock](/en/amazon-bedrock)                                                                                |
| `CLAUDE_CODE_USE_FOUNDRY`                     | Use [Microsoft Foundry](/en/microsoft-foundry)                                                                                |
| `CLAUDE_CODE_USE_VERTEX`                      | Use [Vertex](/en/google-vertex-ai)                                                                                |
| `CLAUDE_CONFIG_DIR`                           | Customize where Claude Code stores its configuration and data files                                                                                |
| `DISABLE_AUTOUPDATER`                         | Set to `1` to disable automatic updates.                                                                                |
| `DISABLE_BUG_COMMAND`                         | Set to `1` to disable the `/bug` command                                                                                |
| `DISABLE_COST_WARNINGS`                       | Set to `1` to disable cost warning messages                                                                                |
| `DISABLE_ERROR_REPORTING`                     | Set to `1` to opt out of Sentry error reporting                                                                                |
| `DISABLE_NON_ESSENTIAL_MODEL_CALLS`           | Set to `1` to disable model calls for non-critical paths like flavor text                                                                                |
| `DISABLE_PROMPT_CACHING`                      | Set to `1` to disable prompt caching for all models (takes precedence over per-model settings)                                                                                |
| `DISABLE_PROMPT_CACHING_HAIKU`                | Set to `1` to disable prompt caching for Haiku models                                                                                |
| `DISABLE_PROMPT_CACHING_OPUS`                 | Set to `1` to disable prompt caching for Opus models                                                                                |
| `DISABLE_PROMPT_CACHING_SONNET`               | Set to `1` to disable prompt caching for Sonnet models                                                                                |
| `DISABLE_TELEMETRY`                           | Set to `1` to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands)                                                                                |
| `HTTP_PROXY`                                  | Specify HTTP proxy server for network connections                                                                                |
| `HTTPS_PROXY`                                 | Specify HTTPS proxy server for network connections                                                                                |
| `MAX_MCP_OUTPUT_TOKENS`                       | Maximum number of tokens allowed in MCP tool responses. Claude Code displays a warning when output exceeds 10,000 tokens (default: 25000)                                                                                |
| `MAX_THINKING_TOKENS`                         | Enable [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) and set the token budget for the thinking process. Extended thinking improves performance on complex reasoning and coding tasks but impacts [prompt caching efficiency](https://docs.claude.com/en/docs/build-with-claude/prompt-caching#caching-with-thinking-blocks). Disabled by default. |
| `MCP_TIMEOUT`                                 | Timeout in milliseconds for MCP server startup                                                                                |
| `MCP_TOOL_TIMEOUT`                            | Timeout in milliseconds for MCP tool execution                                                                                |
| `NO_PROXY`                                    | List of domains and IPs to which requests will be directly issued, bypassing proxy                                                                                |
| `SLASH_COMMAND_TOOL_CHAR_BUDGET`              | Maximum number of characters for slash command metadata shown to [SlashCommand tool](/en/slash-commands#slashcommand-tool) (default: 15000)                                                                                |
| `USE_BUILTIN_RIPGREP`                         | Set to `0` to use system-installed `rg` instead of `rg` included with Claude Code                                                                                |
| `VERTEX_REGION_CLAUDE_3_5_HAIKU`              | Override region for Claude 3.5 Haiku when using Vertex AI                                                                                |
| `VERTEX_REGION_CLAUDE_3_7_SONNET`             | Override region for Claude 3.7 Sonnet when using Vertex AI                                                                                |
| `VERTEX_REGION_CLAUDE_4_0_OPUS`               | Override region for Claude 4.0 Opus when using Vertex AI                                                                                |
| `VERTEX_REGION_CLAUDE_4_0_SONNET`             | Override region for Claude 4.0 Sonnet when using Vertex AI                                                                                |
| `VERTEX_REGION_CLAUDE_4_1_OPUS`               | Override region for Claude 4.1 Opus when using Vertex AI                                                                                |

## Tools available to Claude

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

| Tool                | Description                                                                                | Permission Required |
| :------------------ | :------------------------------------------------------------------------------------------------ | :------------------ |
| **AskUserQuestion** | Asks the user multiple choice questions to gather information or clarify ambiguity                | No                  |
| **Bash**            | Executes shell commands in your environment (see [Bash tool behavior](#bash-tool-behavior) below) | Yes                 |
| **BashOutput**      | Retrieves output from a background bash shell                                                     | No                  |
| **Edit**            | Makes targeted edits to specific files                                                            | Yes                 |
| **ExitPlanMode**    | Prompts the user to exit plan mode and start coding                                               | Yes                 |
| **Glob**            | Finds files based on pattern matching                                                             | No                  |
| **Grep**            | Searches for patterns in file contents                                                            | No                  |
| **KillShell**       | Kills a running background bash shell by its ID                                                   | No                  |
| **NotebookEdit**    | Modifies Jupyter notebook cells                                                                   | Yes                 |
| **Read**            | Reads the contents of files                                                                       | No                  |
| **Skill**           | Executes a skill within the main conversation                                                     | Yes                 |
| **SlashCommand**    | Runs a [custom slash command](/en/slash-commands#slashcommand-tool)                               | Yes                 |
| **Task**            | Runs a sub-agent to handle complex, multi-step tasks                                              | No                  |
| **TodoWrite**       | Creates and manages structured task lists                                                         | No                  |
| **WebFetch**        | Fetches content from a specified URL                                                              | Yes                 |
| **WebSearch**       | Performs web searches with domain filtering                                                       | Yes                 |
| **Write**           | Creates or overwrites files                                                                       | Yes                 |

Permission rules can be configured using `/allowed-tools` or in [permission settings](/en/settings#available-settings). Also see [Tool-specific permission rules](/en/iam#tool-specific-permission-rules).

### Bash tool behavior

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

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

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

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

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

```bash  theme={null}
conda activate myenv
# or: source /path/to/venv/bin/activate
claude
```

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

**Option 2: Set CLAUDE\_ENV\_FILE before starting Claude Code** (persistent environment setup)

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

```bash  theme={null}
export CLAUDE_ENV_FILE=/path/to/env-setup.sh
claude
```

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

```bash  theme={null}
conda activate myenv
# or: source /path/to/venv/bin/activate
# or: export MY_VAR=value
```

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

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

Configure in `.claude/settings.json`:

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

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

See [SessionStart hooks](/en/hooks#persisting-environment-variables) for more details on Option 3.

### Extending tools with hooks

You can run custom commands before or after any tool executes using
[Claude Code hooks](/en/hooks-guide).

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

## See also

* [Identity and Access Management](/en/iam#configuring-permissions) - Learn about Claude Code's permission system
* [IAM and access control](/en/iam#managed-settings) - Managed policy configuration
* [Troubleshooting](/en/troubleshooting#auto-updater-issues) - Solutions for common configuration issues

---

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


# Identity and Access Management

> Learn how to configure user authentication, authorization, and access controls for Claude Code in your organization.

## Authentication methods

Setting up Claude Code requires access to Anthropic models. For teams, you can set up Claude Code access in one of four ways:

* Claude API via the Claude Console
* Amazon Bedrock
* Microsoft Foundry
* Google Vertex AI

### Claude API authentication

**To set up Claude Code access for your team via Claude API:**

1. Use your existing Claude Console account or create a new Claude Console account
2. You can add users through either method below:
   * Bulk invite users from within the Console (Console -> Settings -> Members -> Invite)
   * [Set up SSO](https://support.claude.com/en/articles/10280258-setting-up-single-sign-on-on-the-api-console)
3. When inviting users, they need one of the following roles:
   * "Claude Code" role means users can only create Claude Code API keys
   * "Developer" role means users can create any kind of API key
4. Each invited user needs to complete these steps:
   * Accept the Console invite
   * [Check system requirements](/en/setup#system-requirements)
   * [Install Claude Code](/en/setup#installation)
   * Login with Console account credentials

### Cloud provider authentication

**To set up Claude Code access for your team via Bedrock, Vertex, or Azure:**

1. Follow the [Bedrock docs](/en/amazon-bedrock), [Vertex docs](/en/google-vertex-ai), or [Microsoft Foundry docs](/en/microsoft-foundry)
2. Distribute the environment variables and instructions for generating cloud credentials to your users. Read more about how to [manage configuration here](/en/settings).
3. Users can [install Claude Code](/en/setup#installation)

## Access control and permissions

We support fine-grained permissions so that you're able to specify exactly what the agent is allowed to do (e.g. run tests, run linter) and what it is not allowed to do (e.g. update cloud infrastructure). These permission settings can be checked into version control and distributed to all developers in your organization, as well as customized by individual developers.

### Permission system

Claude Code uses a tiered permission system to balance power and safety:

| Tool Type         | Example              | Approval Required | "Yes, don't ask again" Behavior               |
| :---------------- | :------------------- | :---------------- | :-------------------------------------------- |
| Read-only         | File reads, LS, Grep | No                | N/A                                           |
| Bash Commands     | Shell execution      | Yes               | Permanently per project directory and command |
| File Modification | Edit/write files     | Yes               | Until session end                             |

### Configuring permissions

You can view & manage Claude Code's tool permissions with `/permissions`. This UI lists all permission rules and the settings.json file they are sourced from.

* **Allow** rules will allow Claude Code to use the specified tool without further manual approval.
* **Ask** rules will ask the user for confirmation whenever Claude Code tries to use the specified tool. Ask rules take precedence over allow rules.
* **Deny** rules will prevent Claude Code from using the specified tool. Deny rules take precedence over allow and ask rules.
* **Additional directories** extend Claude's file access to directories beyond the initial working directory.
* **Default mode** controls Claude's permission behavior when encountering new requests.

Permission rules use the format: `Tool` or `Tool(optional-specifier)`

A rule that is just the tool name matches any use of that tool. For example, adding `Bash` to the list of allow rules would allow Claude Code to use the Bash tool without requiring user approval.

#### Permission modes

Claude Code supports several permission modes that can be set as the `defaultMode` in [settings files](/en/settings#settings-files):

| Mode                | Description                                                                                |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------ |
| `default`           | Standard behavior - prompts for permission on first use of each tool                                                      |
| `acceptEdits`       | Automatically accepts file edit permissions for the session                                                               |
| `plan`              | Plan Mode - Claude can analyze but not modify files or execute commands                                                   |
| `dontAsk`           | Auto-denies tools unless pre-approved via `/permissions` or [`permissions.allow`](/en/settings#permission-settings) rules |
| `bypassPermissions` | Skips all permission prompts (requires safe environment - see warning below)                                              |

#### Working directories

By default, Claude has access to files in the directory where it was launched. You can extend this access:

* **During startup**: Use `--add-dir <path>` CLI argument
* **During session**: Use `/add-dir` slash command
* **Persistent configuration**: Add to `additionalDirectories` in [settings files](/en/settings#settings-files)

Files in additional directories follow the same permission rules as the original working directory - they become readable without prompts, and file editing permissions follow the current permission mode.

#### Tool-specific permission rules

Some tools support more fine-grained permission controls:

**Bash**

Bash permission rules support both prefix matching with `:*` and wildcard matching with `*`:

* `Bash(npm run build)` Matches the exact Bash command `npm run build`
* `Bash(npm run test:*)` Matches Bash commands starting with `npm run test`
* `Bash(npm *)` Matches any command starting with `npm ` (e.g., `npm install`, `npm run build`)
* `Bash(* install)` Matches any command ending with ` install` (e.g., `npm install`, `yarn install`)
* `Bash(git * main)` Matches commands like `git checkout main`, `git merge main`

<Tip>
  Claude Code is aware of shell operators (like `&&`) so a prefix match rule like `Bash(safe-cmd:*)` won't give it permission to run the command `safe-cmd && other-cmd`
</Tip>

<Warning>
  Important limitations of Bash permission patterns:

  1. The `:*` wildcard only works at the end of a pattern for prefix matching
  2. The `*` wildcard can appear at any position and matches any sequence of characters
  3. Patterns like `Bash(curl http://github.com/:*)` can be bypassed in many ways:
     * Options before URL: `curl -X GET http://github.com/...` won't match
     * Different protocol: `curl https://github.com/...` won't match
     * Redirects: `curl -L http://bit.ly/xyz` (redirects to github)
     * Variables: `URL=http://github.com && curl $URL` won't match
     * Extra spaces: `curl  http://github.com` won't match

  For more reliable URL filtering, consider:

  * Using the WebFetch tool with `WebFetch(domain:github.com)` permission
  * Instructing Claude Code about your allowed curl patterns via CLAUDE.md
  * Using hooks for custom permission validation
</Warning>

**Read & Edit**

`Edit` rules apply to all built-in tools that edit files. Claude will make a best-effort attempt to apply `Read` rules to all built-in tools that read files like Grep, Glob, and LS.

Read & Edit rules both follow the [gitignore](https://git-scm.com/docs/gitignore) specification with four distinct pattern types:

| Pattern            | Meaning                                | Example                          | Matches                            |
| ------------------ | -------------------------------------- | -------------------------------- | ---------------------------------- |
| `//path`           | **Absolute** path from filesystem root | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**`          |
| `~/path`           | Path from **home** directory           | `Read(~/Documents/*.pdf)`        | `/Users/alice/Documents/*.pdf`     |
| `/path`            | Path **relative to settings file**     | `Edit(/src/**/*.ts)`             | `<settings file path>/src/**/*.ts` |
| `path` or `./path` | Path **relative to current directory** | `Read(*.env)`                    | `<cwd>/*.env`                      |

<Warning>
  A pattern like `/Users/alice/file` is NOT an absolute path - it's relative to your settings file! Use `//Users/alice/file` for absolute paths.
</Warning>

* `Edit(/docs/**)` - Edits in `<project>/docs/` (NOT `/docs/`!)
* `Read(~/.zshrc)` - Reads your home directory's `.zshrc`
* `Edit(//tmp/scratch.txt)` - Edits the absolute path `/tmp/scratch.txt`
* `Read(src/**)` - Reads from `<current-directory>/src/`

**WebFetch**

* `WebFetch(domain:example.com)` Matches fetch requests to example.com

**MCP**

* `mcp__puppeteer` Matches any tool provided by the `puppeteer` server (name configured in Claude Code)
* `mcp__puppeteer__*` Wildcard syntax that also matches all tools from the `puppeteer` server
* `mcp__puppeteer__puppeteer_navigate` Matches the `puppeteer_navigate` tool provided by the `puppeteer` server

**Task (Subagents)**

Use `Task(AgentName)` rules to control which [subagents](/en/sub-agents) Claude can use:

* `Task(Explore)` Matches the Explore subagent
* `Task(Plan)` Matches the Plan subagent
* `Task(Verify)` Matches the Verify subagent

Add these rules to the `deny` array in your [settings](/en/settings#permission-settings) or use the `--disallowedTools` CLI flag to disable specific agents. For example, to disable the Explore agent:

```json  theme={null}
{
  "permissions": {
    "deny": ["Task(Explore)"]
  }
}
```

### Additional permission control with hooks

[Claude Code hooks](/en/hooks-guide) provide a way to register custom shell commands to perform permission evaluation at runtime. When Claude Code makes a tool call, PreToolUse hooks run before the permission system runs, and the hook output can determine whether to approve or deny the tool call in place of the permission system.

### Managed settings

For organizations that need centralized control over Claude Code configuration, administrators can deploy `managed-settings.json` files to [system directories](/en/settings#settings-files). These policy files follow the same format as regular settings files and cannot be overridden by user or project settings.

### Settings precedence

When multiple settings sources exist, they are applied in the following order (highest to lowest precedence):

1. Managed settings (`managed-settings.json`)
2. Command line arguments
3. Local project settings (`.claude/settings.local.json`)
4. Shared project settings (`.claude/settings.json`)
5. User settings (`~/.claude/settings.json`)

This hierarchy ensures that organizational policies are always enforced while still allowing flexibility at the project and user levels where appropriate.

## Credential management

Claude Code securely manages your authentication credentials:

* **Storage location**: On macOS, API keys, OAuth tokens, and other credentials are stored in the encrypted macOS Keychain.
* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.
* **Custom credential scripts**: The [`apiKeyHelper`](/en/settings#available-settings) 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.

---

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