ai-control-pool/private/projects/-Users-marcus-hinz-claude-projects-ai-control/f7704328-4eb4-4f0f-bf42-da68abab401d/subagents/agent-a556d2e38a847bf6e.jsonl

{"parentUuid":null,"isSidechain":true,"promptId":"463e84b3-536f-432f-b32a-4fdae6dbed7a","agentId":"a556d2e38a847bf6e","type":"user","message":{"role":"user","content":"Claude Code CLI. I registered a stdio MCP server by writing it directly (not via `claude mcp add`) into `$CLAUDE_CONFIG_DIR/.claude.json` under `mcpServers.aicontrol` = {type:stdio, command, args:[\"--mcp-panel\"]}. I also put `\"mcp__aicontrol__write_panel\"` into `permissions.allow` in `$CLAUDE_CONFIG_DIR/settings.json`. The server loads and the tool is available, but calling the tool STILL shows an interactive permission/approval prompt.\n\nAnswer precisely:\n\n1. For a user-scope MCP server written directly into `.claude.json` (not added via `claude mcp add`), is there a SEPARATE one-time \"trust / approve this MCP server\" gate that is NOT satisfied by `permissions.allow`? If so, what exact config key/value pre-approves the SERVER itself (e.g. a per-server approved/trusted flag, `enabledMcpjsonServers`, `enableAllProjectMcpServers`, or something in `.claude.json`), and in which file?\n\n2. Is `permissions.allow` even read from `$CLAUDE_CONFIG_DIR/settings.json` (user scope), or must MCP-tool allow rules live somewhere else (project `.claude/settings.json`, `.claude/settings.local.json`, or a managed-settings file)? What is the precedence, and is there a known case where a user-scope allow rule for an `mcp__server__tool` is ignored?\n\n3. Does the running `claude` process need a full restart to pick up BOTH the new `.claude.json` server entry and the `permissions.allow` change, or is one of them hot-reloaded? If the terminal/session was already open when the files were written, what exactly must be restarted?\n\n4. Is the exact allow-string right when the server was NOT added via `claude mcp add`? Confirm the mangling uses the `mcpServers` object KEY (`aicontrol`) → `mcp__aicontrol__write_panel`, and that there is no additional prefix for user-scope servers.\n\n5. Concretely: what is the minimal set of file entries (exact keys, files) so that a directly-written user-scope stdio MCP server's single tool runs with ZERO prompts on a fresh session? Note any version differences."},"uuid":"6a941e6d-0421-448c-92bc-d8d40e01930b","timestamp":"2026-07-11T09:47:24.422Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"6a941e6d-0421-448c-92bc-d8d40e01930b","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4M6LnXcGFNNefL32Kc","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"","signature":"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"}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":10,"cache_creation_input_tokens":13556,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":13556,"ephemeral_1h_input_tokens":0},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011Ccv4M57NU2ucHVfQJMPe7","attributionAgent":"claude-code-guide","type":"assistant","uuid":"a67e5756-f552-493c-9404-1f34f416fbcc","timestamp":"2026-07-11T09:47:29.558Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"a67e5756-f552-493c-9404-1f34f416fbcc","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4M6LnXcGFNNefL32Kc","type":"message","role":"assistant","content":[{"type":"text","text":"I need to fetch the Claude Code documentation to answer these precisely rather than guess at configuration internals that may have changed. Let me get the current docs."}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":10,"cache_creation_input_tokens":13556,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":13556,"ephemeral_1h_input_tokens":0},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011Ccv4M57NU2ucHVfQJMPe7","attributionAgent":"claude-code-guide","type":"assistant","uuid":"dafa9131-456e-49b1-8783-d3c1e53d6ed4","timestamp":"2026-07-11T09:47:30.141Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"dafa9131-456e-49b1-8783-d3c1e53d6ed4","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4M6LnXcGFNNefL32Kc","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01Jpn4YmQ9TMVMPYEKuVh7QN","name":"WebFetch","input":{"url":"https://code.claude.com/docs/en/claude_code_docs_map.md","prompt":"MCP server configuration, .claude.json, permissions, user-scope vs project-scope, trust gates, permission strings for MCP tools"},"caller":{"type":"direct"}}],"stop_reason":"tool_use","stop_sequence":null,"stop_details":null,"usage":{"input_tokens":10,"cache_creation_input_tokens":13556,"cache_read_input_tokens":0,"output_tokens":502,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":13556},"inference_geo":"not_available","iterations":[{"input_tokens":10,"output_tokens":502,"cache_read_input_tokens":0,"cache_creation_input_tokens":13556,"cache_creation":{"ephemeral_5m_input_tokens":13556,"ephemeral_1h_input_tokens":0},"type":"message"}],"speed":"standard"},"diagnostics":null},"requestId":"req_011Ccv4M57NU2ucHVfQJMPe7","attributionAgent":"claude-code-guide","type":"assistant","uuid":"482730bf-691c-493d-b299-63dd9a469a8a","timestamp":"2026-07-11T09:47:31.091Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"482730bf-691c-493d-b299-63dd9a469a8a","isSidechain":true,"promptId":"463e84b3-536f-432f-b32a-4fdae6dbed7a","agentId":"a556d2e38a847bf6e","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01Jpn4YmQ9TMVMPYEKuVh7QN","type":"tool_result","content":"<persisted-output>\nOutput too large (96.9KB). Full output saved to: /Users/marcus.hinz/.config/ai-control/pools/private/projects/-Users-marcus-hinz-claude-projects-ai-control/f7704328-4eb4-4f0f-bf42-da68abab401d/tool-results/toolu_01Jpn4YmQ9TMVMPYEKuVh7QN.txt\n\nPreview (first 2KB):\n> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Claude code docs map\n\n# Claude Code Documentation Map\n\nThis is a comprehensive map of all Claude Code documentation pages with their headings, designed for easy navigation by LLMs.\n\n> **Note:** This file is auto-generated by GitHub Actions. Do not edit manually.\n> Last updated: 2026-07-11 03:53:52 UTC\n\n## Document Structure\n\nThis map uses a hierarchical structure:\n\n* **##** marks documentation groups (e.g., 'Getting started')\n* **###** marks individual documentation pages\n* **Nested bullets** show the heading structure within each page\n* Each page title links to the full documentation\n\n## Getting started\n\n### [overview](https://code.claude.com/docs/en/overview.md)\n\n* Get started\n* What you can do\n* Use Claude Code everywhere\n* Next steps\n\n### [quickstart](https://code.claude.com/docs/en/quickstart.md)\n\n* Before you begin\n* Step 1: Install Claude Code\n* Step 2: Log in to your account\n* Step 3: Start your first session\n* Step 4: Ask your first question\n* Step 5: Make your first code change\n* Step 6: Use Git with Claude Code\n* Step 7: Fix a bug or add a feature\n* Step 8: Test out other common workflows\n* Essential commands\n* Pro tips for beginners\n* What's next?\n* Getting help\n\n### [changelog](https://code.claude.com/docs/en/changelog.md)\n\n* (No headings found)\n\n## Core concepts\n\n### [how-claude-code-works](https://code.claude.com/docs/en/how-claude-code-works.md)\n\n* The agentic loop\n  * Models\n  * Tools\n* What Claude can access\n* Environments and interfaces\n  * Execution environments\n  * Interfaces\n* Work with sessions\n  * Work across branches\n  * Resume or fork sessions\n  * The context window\n    * When context fills up\n    * Manage context with skills and subagents\n* Stay safe with checkpoints and permissions\n  * Undo changes with checkpoints\n  * Control what Claude can do\n...\n</persisted-output>"}]},"uuid":"22abdd21-ff9f-4aac-9b70-c4bbfca3755d","timestamp":"2026-07-11T09:47:31.740Z","toolUseResult":{"bytes":99186,"code":200,"codeText":"OK","result":"> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Claude code docs map\n\n# Claude Code Documentation Map\n\nThis is a comprehensive map of all Claude Code documentation pages with their headings, designed for easy navigation by LLMs.\n\n> **Note:** This file is auto-generated by GitHub Actions. Do not edit manually.\n> Last updated: 2026-07-11 03:53:52 UTC\n\n## Document Structure\n\nThis map uses a hierarchical structure:\n\n* **##** marks documentation groups (e.g., 'Getting started')\n* **###** marks individual documentation pages\n* **Nested bullets** show the heading structure within each page\n* Each page title links to the full documentation\n\n## Getting started\n\n### [overview](https://code.claude.com/docs/en/overview.md)\n\n* Get started\n* What you can do\n* Use Claude Code everywhere\n* Next steps\n\n### [quickstart](https://code.claude.com/docs/en/quickstart.md)\n\n* Before you begin\n* Step 1: Install Claude Code\n* Step 2: Log in to your account\n* Step 3: Start your first session\n* Step 4: Ask your first question\n* Step 5: Make your first code change\n* Step 6: Use Git with Claude Code\n* Step 7: Fix a bug or add a feature\n* Step 8: Test out other common workflows\n* Essential commands\n* Pro tips for beginners\n* What's next?\n* Getting help\n\n### [changelog](https://code.claude.com/docs/en/changelog.md)\n\n* (No headings found)\n\n## Core concepts\n\n### [how-claude-code-works](https://code.claude.com/docs/en/how-claude-code-works.md)\n\n* The agentic loop\n  * Models\n  * Tools\n* What Claude can access\n* Environments and interfaces\n  * Execution environments\n  * Interfaces\n* Work with sessions\n  * Work across branches\n  * Resume or fork sessions\n  * The context window\n    * When context fills up\n    * Manage context with skills and subagents\n* Stay safe with checkpoints and permissions\n  * Undo changes with checkpoints\n  * Control what Claude can do\n* Work effectively with Claude Code\n  * Ask Claude Code for help\n  * It's a conversation\n    * Interrupt and steer\n  * Be specific upfront\n  * Give Claude something to verify against\n  * Explore before implementing\n  * Delegate, don't dictate\n* What's next\n\n### [features-overview](https://code.claude.com/docs/en/features-overview.md)\n\n* Overview\n* Match features to your goal\n  * Build your setup over time\n  * Compare similar features\n  * Understand how features layer\n  * Combine features\n* Understand context costs\n  * Context cost by feature\n  * Understand how features load\n* Learn more\n\n### [claude-directory](https://code.claude.com/docs/en/claude-directory.md)\n\n* Explore the directory\n* What's not shown\n* Choose the right file\n* File reference\n* Troubleshoot configuration\n* Application data\n  * Cleaned up automatically\n  * Kept until you delete them\n  * Plaintext storage\n  * Clear local data\n* Related resources\n\n### [context-window](https://code.claude.com/docs/en/context-window.md)\n\n* What the timeline shows\n* What survives compaction\n* When your context fills up\n* Check your own session\n* Related resources\n\n### [prompt-caching](https://code.claude.com/docs/en/prompt-caching.md)\n\n* How the cache is organized\n  * Where the cache lives\n* Actions that invalidate the cache\n  * Switching models\n  * Changing effort level\n  * Turning on fast mode\n  * Connecting or disconnecting an MCP server\n  * Enabling or disabling a plugin\n  * Denying an entire tool\n  * Compacting the conversation\n  * Upgrading Claude Code\n* Actions that keep the cache\n  * Editing files in your repository\n  * Editing CLAUDE.md mid-session\n  * Changing output style\n  * Changing permission mode\n  * Invoking skills and commands\n  * Running `/recap`\n  * Rewinding the conversation\n* Cache lifetime\n  * On a Claude subscription\n  * On an API key or third-party provider\n  * Override the TTL\n* Cache scope\n* Check cache performance\n* Subagents and the cache\n* Disable prompt caching\n* Related resources\n\n## Use Claude Code\n\n### [memory](https://code.claude.com/docs/en/memory.md)\n\n* CLAUDE.md vs auto memory\n* CLAUDE.md files\n  * When to add to CLAUDE.md\n  * Choose where to put CLAUDE.md files\n  * Set up a project CLAUDE.md\n  * Write effective instructions\n  * Import additional files\n  * AGENTS.md\n  * How CLAUDE.md files load\n    * Load from additional directories\n  * Organize rules with `.claude/rules/`\n    * Set up rules\n    * Path-specific rules\n    * Share rules across projects with symlinks\n    * User-level rules\n  * Manage CLAUDE.md for large teams\n    * Deploy organization-wide CLAUDE.md\n    * Exclude specific CLAUDE.md files\n* Auto memory\n  * Enable or disable auto memory\n  * Storage location\n  * How it works\n  * Audit and edit your memory\n* View and edit with `/memory`\n* Troubleshoot memory issues\n  * Claude isn't following my CLAUDE.md\n  * I don't know what auto memory saved\n  * My CLAUDE.md is too large\n  * Instructions seem lost after `/compact`\n* Related resources\n\n### [permission-modes](https://code.claude.com/docs/en/permission-modes.md)\n\n* Available modes\n* Switch permission modes\n* Auto-approve file edits with acceptEdits mode\n* Analyze before you edit with plan mode\n  * Review and approve a plan\n  * Set plan mode as the default\n* Eliminate permission prompts with auto mode\n  * Enable auto mode on Bedrock, Agent Platform, or Foundry\n  * What the classifier blocks by default\n  * Boundaries you state in conversation\n  * When auto mode falls back\n* Allow only pre-approved tools with dontAsk mode\n* Skip all checks with bypassPermissions mode\n* Protected paths\n* See also\n\n### [sessions](https://code.claude.com/docs/en/sessions.md)\n\n* Resume a session\n  * Where the session picker looks\n* Name your sessions\n* Use the session picker\n* Branch a session\n* Manage context within a session\n* Export and locate session data\n  * Access conversations from scripts\n  * Where transcripts are stored\n* See also\n\n### [common-workflows](https://code.claude.com/docs/en/common-workflows.md)\n\n* Prompt recipes\n  * Understand new codebases\n    * Get a quick codebase overview\n    * Find relevant code\n  * Fix bugs efficiently\n  * Refactor code\n  * Work with tests\n  * Create pull requests\n  * Handle documentation\n  * Work in notes and non-code folders\n  * Work with images\n  * Reference files and directories\n  * Run Claude on a schedule\n  * Ask Claude about its capabilities\n    * Example questions\n* Resume previous conversations\n* Run parallel sessions with worktrees\n* Plan before editing\n* Delegate research to subagents\n* Pipe Claude into scripts\n* Next steps\n\n### [prompt-library](https://code.claude.com/docs/en/prompt-library.md)\n\n* What makes these prompts work\n* Where these come from\n* Related resources\n\n### [best-practices](https://code.claude.com/docs/en/best-practices.md)\n\n* Give Claude a way to verify its work\n* Explore first, then plan, then code\n* Provide specific context in your prompts\n  * Provide rich content\n* Configure your environment\n  * Write an effective CLAUDE.md\n  * Configure permissions\n  * Use CLI tools\n  * Connect MCP servers\n  * Set up hooks\n  * Create skills\n  * Create custom subagents\n  * Install plugins\n* Communicate effectively\n  * Ask codebase questions\n  * Let Claude interview you\n* Manage your session\n  * Course-correct early and often\n  * Manage context aggressively\n  * Use subagents for investigation\n  * Rewind with checkpoints\n  * Resume conversations\n* Automate and scale\n  * Run non-interactive mode\n  * Run multiple Claude sessions\n  * Fan out across files\n  * Run autonomously with auto mode\n  * Add an adversarial review step\n* Avoid common failure patterns\n* Develop your intuition\n* Related resources\n\n### Platforms and integrations > Claude Code on the web\n\n#### [web-quickstart](https://code.claude.com/docs/en/web-quickstart.md)\n\n* How sessions run\n* Compare ways to run Claude Code\n* Connect GitHub and create an environment\n  * Connect from your terminal\n* Start a task\n* Pre-fill sessions\n* Review and iterate\n* Troubleshoot setup\n  * No repositories appear after connecting GitHub\n  * The page only shows a GitHub login button\n  * \"Not available for the selected organization\"\n  * `/web-setup` shows \"No commands match\" or \"Unknown command\"\n  * \"Could not create a cloud environment\" or \"No cloud environment available\" when using `--cloud` or ultraplan\n  * Setup script failed\n  * New sessions hang or time out during setup\n  * Session keeps running after closing the tab\n* Next steps\n\n#### [claude-code-on-the-web](https://code.claude.com/docs/en/claude-code-on-the-web.md)\n\n* GitHub authentication options\n* The cloud environment\n  * What's available in cloud sessions\n  * Installed tools\n  * Work with GitHub issues and pull requests\n  * Link output back to the session\n  * Run tests, start services, and add packages\n  * Resource limits\n  * Configure your environment\n* Setup scripts\n  * Environment caching\n  * Setup scripts vs. SessionStart hooks\n  * Install dependencies with a SessionStart hook\n* Network access\n  * Access levels\n  * Allow specific domains\n  * GitHub proxy\n  * Security proxy\n  * Default allowed domains\n* Move tasks between web and terminal\n  * From terminal to web\n    * Tips for cloud tasks\n    * Send local repositories without GitHub\n  * From web to terminal\n    * Teleport requirements\n    * `--teleport` is unavailable\n* Work with sessions\n  * Manage context\n  * Review changes\n  * Share sessions\n    * Share from an Enterprise or Team account\n    * Share from a Max or Pro account\n  * Archive sessions\n  * Delete sessions\n* Auto-fix pull requests\n  * How Claude responds to PR activity\n* Security and isolation\n* Troubleshooting\n  * Session creation failed\n  * Remote Control session expired or access denied\n  * Environment expired\n* Limitations\n* Related resources\n\n#### [routines](https://code.claude.com/docs/en/routines.md)\n\n* Example use cases\n* Create a routine\n  * Create from the web\n  * Create from the CLI\n* Configure triggers\n  * Add a schedule trigger\n    * Schedule a one-off run\n  * Add an API trigger\n    * Trigger a routine\n    * API reference\n  * Add a GitHub trigger\n    * Supported events\n    * Filter pull requests\n    * How sessions map to events\n* Manage routines\n  * View and interact with runs\n  * Edit and control routines\n  * Repositories and branch permissions\n  * Connectors\n  * Environments and network access\n* Usage and limits\n* Troubleshooting\n  * `/schedule` shows \"No commands match\" or \"Unknown command\"\n  * \"Routines are disabled by your organization's policy\"\n* Related resources\n\n#### [ultraplan](https://code.claude.com/docs/en/ultraplan.md)\n\n* Launch ultraplan from the CLI\n* Review and revise the plan in your browser\n* Choose where to execute\n  * Execute on the web\n  * Send the plan back to your terminal\n* Related resources\n\n#### [ultrareview](https://code.claude.com/docs/en/ultrareview.md)\n\n* Run ultrareview from the CLI\n* Pricing and free runs\n* Track a running review\n* Run ultrareview non-interactively\n* How ultrareview compares to /code-review and /review\n* Related resources\n\n### Platforms and integrations > Claude Code on desktop\n\n#### [desktop-quickstart](https://code.claude.com/docs/en/desktop-quickstart.md)\n\n* Install\n* Start your first session\n* Now what?\n* Coming from the CLI?\n* What's next\n\n#### [desktop](https://code.claude.com/docs/en/desktop.md)\n\n* Start a session\n* Work with code\n  * Use the prompt box\n  * Add files and context to prompts\n  * Choose a permission mode\n  * Preview your app\n  * Browse external sites\n    * Approve Claude's actions on a site\n    * Choose between the Browser and the Chrome extension\n    * Restrict external browsing for your organization\n  * Review changes with diff view\n  * Review your code\n  * Monitor pull request status\n* Arrange your workspace\n  * Run commands in the terminal\n  * Open and edit files\n  * Open files in other apps\n  * Switch view modes\n  * Keyboard shortcuts\n  * Check usage\n* Let Claude use your computer\n  * When computer use applies\n  * Enable computer use\n  * App permissions\n* Manage sessions\n  * Work in parallel with sessions\n  * Ask a side question without derailing the session\n  * Watch background tasks\n  * Run long-running tasks remotely\n  * Continue in another surface\n  * Sessions from Dispatch\n* Extend Claude Code\n  * Connect external tools\n  * Use skills\n  * Install plugins\n  * Configure preview servers\n    * Auto-verify changes\n    * Configuration fields\n      * When to use `program` vs `runtimeExecutable`\n    * Port conflicts\n    * Examples\n* Environment configuration\n  * Local sessions\n  * Cloud sessions\n  * SSH sessions\n    * Pre-configure SSH connections for your team\n    * Restrict which SSH hosts users can connect to\n* Enterprise configuration\n  * Admin console controls\n  * Managed settings\n  * Device management policies\n  * Authentication and SSO\n  * Data handling\n  * Deployment\n* Coming from the CLI?\n  * CLI flag equivalents\n  * Shared configuration\n  * Feature comparison\n  * What's not available in Desktop\n* Troubleshooting\n  * Check your version\n  * 403 or authentication errors in the Code tab\n  * Blank or stuck screen on launch\n  * \"Failed to load session\"\n  * Session not finding installed tools\n  * Git and Git LFS errors\n  * MCP servers not working on Windows\n  * App won't quit\n  * Windows-specific issues\n  * \"Branch doesn't exist yet\" when opening in CLI\n  * Still stuck?\n\n#### [desktop-linux](https://code.claude.com/docs/en/desktop-linux.md)\n\n* Requirements\n* Install\n  * Install from a downloaded file\n* Update\n* Uninstall\n* Troubleshoot\n  * Unable to locate package claude-desktop\n* What's not in the Linux beta yet\n\n#### [desktop-scheduled-tasks](https://code.claude.com/docs/en/desktop-scheduled-tasks.md)\n\n* Compare scheduling options\n* Create a scheduled task\n* Schedule options\n* How scheduled tasks run\n* Missed runs\n* Permissions for scheduled tasks\n* Manage scheduled tasks\n* Related resources\n\n### Platforms and integrations > Code review & CI/CD\n\n#### [security-guidance](https://code.claude.com/docs/en/security-guidance.md)\n\n* Prerequisites\n* Install the plugin\n  * Enable in cloud sessions and shared repositories\n* What the plugin checks\n  * On each file edit\n  * At the end of each turn\n  * On each commit or push Claude makes\n  * Review independence and limits\n* Add your own rules\n  * Add guidance for the model-backed reviews\n  * Add custom per-edit patterns\n  * Rule file lookup locations\n* Usage cost\n* Disable or uninstall\n* How the plugin integrates with Claude Code\n* How this fits with other security tools\n* Troubleshooting\n* Related resources\n\n#### [code-review](https://code.claude.com/docs/en/code-review.md)\n\n* How reviews work\n  * Severity levels\n  * Rate and reply to findings\n  * Check run output\n  * What Code Review checks\n* Set up Code Review\n* Manually trigger reviews\n* Customize reviews\n  * CLAUDE.md\n  * REVIEW\\.md\n    * What you can tune\n    * Example\n    * Keep it focused\n* View usage\n* Pricing\n* Troubleshooting\n  * Retrigger a failed or timed-out review\n  * Review didn't run and the PR shows a spend-cap message\n  * Find issues that aren't showing as inline comments\n* Review a diff locally\n* Related resources\n\n#### [github-actions](https://code.claude.com/docs/en/github-actions.md)\n\n* Why use Claude Code GitHub Actions?\n* What can Claude do?\n  * Claude Code Action\n* Setup\n* Quick setup\n* Manual setup\n* Upgrading from Beta\n  * Essential changes\n  * Breaking Changes Reference\n  * Before and After Example\n* Example use cases\n  * Basic workflow\n  * Using skills\n  * Custom automation with prompts\n  * Common use cases\n* Best practices\n  * CLAUDE.md configuration\n  * Security considerations\n  * Optimizing performance\n  * CI costs\n* Configuration examples\n* Using with Amazon Bedrock and Google Cloud\n  * Prerequisites\n    * For Google Cloud's Agent Platform:\n    * For Amazon Bedrock:\n* Troubleshooting\n  * Claude not responding to @claude commands\n  * CI not running on Claude's commits\n  * Authentication errors\n* Advanced configuration\n  * Action parameters\n    * Pass CLI arguments\n  * Alternative integration methods\n  * Customizing Claude's behavior\n\n#### [github-enterprise-server](https://code.claude.com/docs/en/github-enterprise-server.md)\n\n* What works with GitHub Enterprise Server\n* Admin setup\n  * GitHub App permissions\n  * Manual setup\n  * Network requirements\n* Developer workflow\n  * Teleport sessions to your terminal\n* Plugin marketplaces on GHES\n  * Add a GHES marketplace\n  * Pre-register GHES marketplaces with managed settings\n  * Allowlist GHES marketplaces in managed settings\n* Limitations\n* Troubleshooting\n  * Web session fails to clone repository\n  * Marketplace add fails with a policy error\n  * Marketplace add on claude.ai fails with a GitHub access error\n  * GHES instance not reachable\n* Related resources\n\n#### [gitlab-ci-cd](https://code.claude.com/docs/en/gitlab-ci-cd.md)\n\n* Why use Claude Code with GitLab?\n* How it works\n* What can Claude do?\n* Setup\n  * Quick setup\n  * Manual setup (recommended for production)\n* Example use cases\n  * Turn issues into MRs\n  * Get implementation help\n  * Fix bugs quickly\n* Using with Amazon Bedrock and Google Cloud\n* Configuration examples\n  * Basic .gitlab-ci.yml (Claude API)\n  * Amazon Bedrock job example (OIDC)\n  * Agent Platform job example (Workload Identity Federation)\n* Best practices\n  * CLAUDE.md configuration\n  * Security considerations\n  * Optimizing performance\n  * CI costs\n* Security and governance\n* Troubleshooting\n  * Claude not responding to @claude commands\n  * Job can't write comments or open MRs\n  * Authentication errors\n* Advanced configuration\n  * Common parameters and variables\n  * Customizing Claude's behavior\n\n## Platforms and integrations\n\n### [platforms](https://code.claude.com/docs/en/platforms.md)\n\n* Where to run Claude Code\n* Connect your tools\n* Work when you are away from your terminal\n* Related resources\n  * Platforms\n  * Integrations\n  * Remote access\n\n### [remote-control](https://code.claude.com/docs/en/remote-control.md)\n\n* Requirements\n* Start a Remote Control session\n  * Check connection status\n  * Connect from another device\n  * Enable Remote Control for all sessions\n* Connection and security\n* Trusted Devices\n  * Enable Trusted Devices for your organization\n  * What members see\n  * Manage enrolled devices\n* Remote Control vs Claude Code on the web\n* Mobile push notifications\n* Limitations\n* Troubleshooting\n  * \"Remote Control requires a claude.ai subscription\"\n  * \"Remote Control requires a full-scope login token\"\n  * \"Unable to determine your organization for Remote Control eligibility\"\n  * \"Remote Control is not yet enabled for your account\"\n  * \"Couldn't verify Remote Control eligibility\"\n  * \"Remote Control is only available when using Claude via api.anthropic.com\"\n  * \"Remote Control is disabled by your organization's policy\"\n  * \"Remote credentials fetch failed\"\n  * \"Couldn't reconnect to your Remote Control session\"\n  * \"Your organization requires Trusted Devices for Remote Control, but this device is not enrolled\"\n  * \"session expired for trusted-device check\"\n* Choose the right approach\n* Related resources\n\n### [chrome](https://code.claude.com/docs/en/chrome.md)\n\n* Capabilities\n* Prerequisites\n* Get started in the CLI\n  * Enable Chrome by default\n  * Manage site permissions\n  * Browser tools in plan mode\n* Example workflows\n  * Test a local web application\n  * Debug with console logs\n  * Automate form filling\n  * Draft content in Google Docs\n  * Extract data from web pages\n  * Run multi-site workflows\n  * Record a demo GIF\n* Troubleshooting\n  * Extension not detected\n  * Browser not responding\n  * Connection drops during long sessions\n  * Windows-specific issues\n  * Common error messages\n* See also\n\n### [computer-use](https://code.claude.com/docs/en/computer-use.md)\n\n* What you can do with computer use\n* When computer use applies\n* Enable computer use\n* Approve apps per session\n* How Claude works on your screen\n  * One session at a time\n  * Apps are hidden while Claude works\n  * Screenshots are downscaled automatically\n  * Stop at any time\n* Safety and the trust boundary\n* Example workflows\n  * Validate a native build\n  * Reproduce a layout bug\n  * Test a simulator flow\n* Differences from the Desktop app\n* Troubleshooting\n  * \"Computer use is in use by another Claude session\"\n  * macOS permissions prompt keeps reappearing\n  * `computer-use` doesn't appear in `/mcp`\n* See also\n\n### [vs-code](https://code.claude.com/docs/en/vs-code.md)\n\n* Prerequisites\n* Install the extension\n* Get started\n* Use the prompt box\n  * Reference files and folders\n  * Resume past conversations\n  * Resume cloud sessions from Claude.ai\n  * Check account and usage\n* Customize your workflow\n  * Choose where Claude lives\n  * Run multiple conversations\n  * Switch to terminal mode\n* Manage plugins\n  * Install plugins\n  * Manage marketplaces\n* Automate browser tasks with Chrome\n* VS Code commands and shortcuts\n  * Launch a VS Code tab from other tools\n* Configure settings\n  * Extension settings\n* VS Code extension vs. Claude Code CLI\n  * Rewind with checkpoints\n  * Run CLI in VS Code\n  * Switch between extension and CLI\n  * Include terminal output in prompts\n  * Monitor background processes\n  * Connect to external tools with MCP\n* Work with git\n  * Create commits and pull requests\n  * Use git worktrees for parallel tasks\n* Use third-party providers\n* Security and privacy\n  * The built-in IDE MCP server\n* Fix common issues\n  * Extension won't install\n  * Spark icon not visible\n  * Cmd+Esc does nothing on macOS\n  * Claude Code never responds\n* Uninstall the extension\n* Next steps\n\n### [jetbrains](https://code.claude.com/docs/en/jetbrains.md)\n\n* Supported IDEs\n* Features\n* Installation\n* Usage\n  * From your IDE\n  * From external terminals\n* Configuration\n  * Claude Code settings\n  * Plugin settings\n    * General settings\n    * ESC key configuration\n* Special configurations\n  * Remote development\n  * WSL configuration\n    * Allow WSL2 traffic through Windows Firewall\n    * Switch WSL2 to mirrored networking\n* Troubleshooting\n  * Plugin not working\n  * IDE not detected\n  * Command not found\n* Security considerations\n\n### [slack](https://code.claude.com/docs/en/slack.md)\n\n* Use cases\n* Prerequisites\n* Setting up Claude Code in Slack\n* How it works\n  * Automatic detection\n  * Context gathering\n  * Session flow\n* User interface elements\n  * App Home\n  * Message actions\n  * Repository selection\n* Access and permissions\n  * User-level access\n  * Workspace-level access\n  * Channel-based access control\n* What's accessible where\n* Best practices\n  * Writing effective requests\n  * When to use Slack vs. web\n* Troubleshooting\n  * \"Claude Code is not enabled for your account\"\n  * Sessions not starting\n  * Repository not showing\n  * Wrong repository selected\n  * Authentication errors\n  * Session expiration\n* Current limitations\n* Related resources\n\n## Agents and parallel work\n\n### [agents](https://code.claude.com/docs/en/agents.md)\n\n* Choose an approach\n* Check on running work\n* Learn more\n\n### [sub-agents](https://code.claude.com/docs/en/sub-agents.md)\n\n* Built-in subagents\n* Quickstart: create your first subagent\n* Configure subagents\n  * Choose the subagent scope\n  * Write subagent files\n    * Supported frontmatter fields\n  * Choose a model\n  * Control subagent capabilities\n    * Available tools\n    * Restrict which subagents can be spawned\n    * Scope MCP servers to a subagent\n    * Permission modes\n    * Preload skills into subagents\n    * Enable persistent memory\n      * Persistent memory tips\n    * Conditional rules with hooks\n    * Disable specific subagents\n  * Define hooks for subagents\n    * Hooks in subagent frontmatter\n    * Project-level hooks for subagent events\n* Work with subagents\n  * Understand automatic delegation\n  * Invoke subagents explicitly\n  * Run subagents in foreground or background\n  * API errors in subagents\n  * Common patterns\n    * Isolate high-volume operations\n    * Run parallel research\n    * Chain subagents\n  * Choose between subagents and main conversation\n  * Spawn nested subagents\n  * Manage subagent context\n    * What loads at startup\n    * Resume subagents\n    * Auto-compaction\n* Fork the current conversation\n  * Observe and steer running forks\n  * How forks differ from named subagents\n  * Limitations\n* Example subagents\n  * Code reviewer\n  * Debugger\n  * Data scientist\n  * Database query validator\n* Next steps\n\n### [agent-view](https://code.claude.com/docs/en/agent-view.md)\n\n* Quick start\n* Monitor sessions with agent view\n  * Read session state\n  * Row summaries\n  * Pull request status\n  * Peek and reply\n  * Attach to a session\n  * Organize the list\n  * Filter sessions\n  * Keyboard shortcuts\n* Dispatch new agents\n  * From agent view\n    * Dispatch to a specific directory\n  * From inside a session\n  * From your shell\n    * Run a shell command\n  * How file edits are isolated\n  * Set the model\n  * Permission mode, model, and effort\n  * Settings, plugins, and MCP servers\n* Manage sessions from the shell\n* How background sessions are hosted\n  * The supervisor process\n  * Where state is stored\n  * Turn off agent view\n* Troubleshooting\n  * `claude agents` lists subagents instead of opening agent view\n  * Agent view opens with no sessions\n  * Backgrounding shows a `Background this session?` dialog\n  * Prompt rejected as too short\n  * Sessions show as failed after shutdown\n  * Opening a session says the conversation is already open\n  * A session fails before starting with a `possibly low memory` note\n  * Agent view says the background service did not respond\n  * Dispatch fails with `Could not resolve authentication method`\n  * Background sessions can't read Desktop, Documents, or Downloads on macOS\n  * Background sessions can't reach local-network hosts on macOS\n  * A session is slow to respond after attaching\n  * `.claude/worktrees/` is filling up\n* Limitations\n* Related resources\n* Version history\n\n### [agent-teams](https://code.claude.com/docs/en/agent-teams.md)\n\n* When to use agent teams\n  * Compare with subagents\n* Enable agent teams\n* Start your first agent team\n* Control your agent team\n  * Choose a display mode\n  * Specify teammates and models\n  * Require plan approval for teammates\n  * Talk to teammates directly\n  * Assign and claim tasks\n  * Shut down teammates\n  * Enforce quality gates with hooks\n* How agent teams work\n  * How Claude starts agent teams\n  * Architecture\n  * Use subagent definitions for teammates\n  * Permissions\n  * Context and communication\n  * Token usage\n* Use case examples\n  * Run a parallel code review\n  * Investigate with competing hypotheses\n* Best practices\n  * Give teammates enough context\n  * Choose an appropriate team size\n  * Size tasks appropriately\n  * Wait for teammates to finish\n  * Start with research and review\n  * Avoid file conflicts\n  * Monitor and steer\n* Troubleshooting\n  * Teammates not appearing\n  * Too many permission prompts\n  * Teammates stopping on errors\n  * Lead shuts down before work is done\n  * Orphaned tmux sessions\n* Limitations\n* Next steps\n\n### [workflows](https://code.claude.com/docs/en/workflows.md)\n\n* When to use a workflow\n* Run a bundled workflow\n  * Bundled workflows\n  * Watch the run\n* Have Claude write a workflow\n  * Ask for a workflow in your prompt\n  * Let Claude decide with ultracode\n  * Approve the plan before it runs\n  * Save the workflow for reuse\n  * Pass input to a saved workflow\n* Example workflow prompts\n  * Audit many files for the same issue\n  * Keep fixing until a check passes\n  * Migrate many files in parallel\n  * Review every changed file and write one summary\n  * Research a topic across many sources\n  * Find issues until the list stops growing\n  * What the saved script looks like\n* How a workflow runs\n  * Behavior and limits\n* Manage runs\n  * Resume after a pause\n  * Cost\n  * Set a size guideline\n  * Turn workflows off\n* Related resources\n\n### [worktrees](https://code.claude.com/docs/en/worktrees.md)\n\n* Start Claude in a worktree\n  * Choose the base branch\n* Copy gitignored files into worktrees\n* Isolate subagents with worktrees\n* Clean up worktrees\n* Manage worktrees manually\n* Non-git version control\n* See also\n\n## MCP\n\n### [mcp-quickstart](https://code.claude.com/docs/en/mcp-quickstart.md)\n\n* Before you begin\n* Add and verify a server\n* Where servers are saved\n  * Find your configuration on disk\n* Change server scope\n  * Use a server in all your projects\n  * Share a server with your team\n* Additional MCP server examples\n  * Add a local server\n  * Connect a server that requires sign-in\n* Edit .mcp.json directly\n* Connect from other surfaces\n* Troubleshooting\n* Next steps\n\n### [mcp](https://code.claude.com/docs/en/mcp.md)\n\n* What you can do with MCP\n* Find and build MCP servers\n* Installing MCP servers\n  * Option 1: Add a remote HTTP server\n  * Option 2: Add a remote SSE server\n  * Option 3: Add a local stdio server\n  * Option 4: Add a remote WebSocket server\n  * Managing your servers\n  * Dynamic tool updates\n  * Automatic reconnection\n  * Push messages with channels\n  * Plugin-provided MCP servers\n* MCP installation scopes\n  * Local scope\n  * Project scope\n  * User scope\n  * Scope hierarchy and precedence\n  * Environment variable expansion in `.mcp.json`\n* Practical examples\n  * Example: Monitor errors with Sentry\n  * Example: Connect to GitHub for code reviews\n  * Example: Query your PostgreSQL database\n* Authenticate with remote MCP servers\n  * Authenticate from the command line\n  * Use a fixed OAuth callback port\n  * Use pre-configured OAuth credentials\n  * Override OAuth metadata discovery\n  * Restrict OAuth scopes\n  * Use dynamic headers for custom authentication\n* Add MCP servers from JSON configuration\n* Import MCP servers from Claude Desktop\n* Use MCP servers from claude.ai\n  * Disable claude.ai connectors\n* Use Claude Code as an MCP server\n* MCP output limits and warnings\n  * Raise the limit for a specific tool\n* Tool input schemas with a root-level combinator\n* Require approval for a specific tool\n* Respond to MCP elicitation requests\n* Use MCP resources\n  * Reference MCP resources\n* Scale with MCP tool search\n  * How it works\n  * For MCP server authors\n  * Configure tool search\n  * Exempt a server from deferral\n* Use MCP prompts as commands\n  * Execute MCP prompts\n* Managed MCP configuration\n\n## Skills\n\n### [skills](https://code.claude.com/docs/en/skills.md)\n\n* Bundled skills\n  * Run and verify your app\n* Getting started\n  * Create your first skill\n  * Where skills live\n    * Live change detection\n    * Automatic discovery from parent and nested directories\n    * Skills from additional directories\n* Configure skills\n  * Types of skill content\n  * Frontmatter reference\n    * How a skill gets its command name\n    * Available string substitutions\n  * Add supporting files\n  * Control who invokes a skill\n  * Skill content lifecycle\n  * Pre-approve tools for a skill\n  * Pass arguments to skills\n* Advanced patterns\n  * Inject dynamic context\n  * Run skills in a subagent\n    * Example: Research skill using Explore agent\n  * Restrict Claude's skill access\n  * Override skill visibility from settings\n* Evaluate and iterate on a skill\n  * Run evals with skill-creator\n* Share skills\n  * Generate visual output\n* Troubleshooting\n  * Skill not triggering\n  * Skill triggers too often\n  * Skill descriptions are cut short\n* Related resources\n\n## Plugins\n\n### [discover-plugins](https://code.claude.com/docs/en/discover-plugins.md)\n\n* How marketplaces work\n* Official Anthropic marketplace\n  * Code intelligence\n    * What Claude gains from code intelligence plugins\n  * External integrations\n  * Automatic security review\n  * Development workflows\n  * Output styles\n* Community marketplace\n* Try it: add the demo marketplace\n* Add marketplaces\n  * Add from GitHub\n  * Add from other Git hosts\n  * Add from local paths\n  * Add from remote URLs\n* Install plugins\n* Manage installed plugins\n  * Apply plugin changes without restarting\n* Manage marketplaces\n  * Use the interactive interface\n  * Use CLI commands\n  * Configure auto-updates\n* Configure team marketplaces\n* Security\n* Troubleshooting\n  * /plugin command not recognized\n  * Common issues\n  * Code intelligence issues\n* Next steps\n\n### [plugins](https://code.claude.com/docs/en/plugins.md)\n\n* When to use plugins vs standalone configuration\n* Quickstart\n  * Prerequisites\n  * Create your first plugin\n* Develop a plugin in your skills directory\n* Plugin structure overview\n* Develop more complex plugins\n  * Add Skills to your plugin\n  * Add LSP servers to your plugin\n  * Add background monitors to your plugin\n  * Ship default settings with your plugin\n  * Organize complex plugins\n  * Test your plugins locally\n  * Debug plugin issues\n  * Share your plugins\n  * Submit your plugin to the community marketplace\n* Convert existing configurations to plugins\n  * Migration steps\n  * What changes when migrating\n* Next steps\n  * For plugin users\n  * For plugin developers\n\n## Artifacts\n\n### [artifacts](https://code.claude.com/docs/en/artifacts.md)\n\n* When to use an artifact\n  * What an artifact is not\n* Create an artifact\n* Update an artifact\n* Share an artifact\n* What you can build\n  * Walk through a change\n  * Compare alternatives\n  * Tune with interactive controls\n  * Bring the result back to your session\n  * Track work in progress\n* Improve the visual design\n* Page constraints\n* Availability\n* Disable artifacts\n* Manage artifacts for your organization\n  * Enable or disable artifacts\n  * Set a retention policy\n  * Review the audit log\n  * Allowlist the viewer domain\n  * List and delete artifacts with the Compliance API\n* Related resources\n\n## Automation\n\n### [hooks-guide](https://code.claude.com/docs/en/hooks-guide.md)\n\n* Set up your first hook\n* What you can automate\n  * Get notified when Claude needs input\n  * Auto-format code after edits\n  * Block edits to protected files\n  * Re-inject context after compaction\n  * Audit configuration changes\n  * Reload environment when directory or files change\n  * Auto-approve specific permission prompts\n* How hooks work\n  * Combine results from multiple hooks\n  * Read input and return output\n    * Hook input\n    * Hook output\n    * Structured JSON output\n  * Filter hooks with matchers\n    * Filter by tool name and arguments with the `if` field\n  * Configure hook location\n* Prompt-based hooks\n* Agent-based hooks\n* HTTP hooks\n* Limitations and troubleshooting\n  * Limitations\n  * Hooks and permission modes\n  * Hook not firing\n  * Hook error in output\n  * `/hooks` shows no hooks configured\n  * Stop hook hits the block cap\n  * JSON validation failed\n  * Debug techniques\n* Learn more\n\n### [channels](https://code.claude.com/docs/en/channels.md)\n\n* Supported channels\n* Quickstart\n* Security\n* Enterprise controls\n  * Enable channels for your organization\n  * Restrict which channel plugins can run\n* Research preview\n* How channels compare\n* Next steps\n\n### [scheduled-tasks](https://code.claude.com/docs/en/scheduled-tasks.md)\n\n* Compare scheduling options\n* Run a prompt repeatedly with /loop\n  * Run on a fixed interval\n  * Let Claude choose the interval\n  * Run the built-in maintenance prompt\n  * Customize the default prompt with loop.md\n  * Stop a loop\n* Set a one-time reminder\n* Manage scheduled tasks\n* How scheduled tasks run\n  * Jitter\n  * Seven-day expiry\n* Cron expression reference\n* Disable scheduled tasks\n* Limitations\n\n### [goal](https://code.claude.com/docs/en/goal.md)\n\n* Compare ways to keep a session running\n* Use `/goal`\n  * Set a goal\n  * Write an effective condition\n  * Check status\n  * Clear a goal\n  * Resume with an active goal\n  * Run non-interactively\n* How evaluation works\n* Requirements\n* See also\n\n### [headless](https://code.claude.com/docs/en/headless.md)\n\n* Basic usage\n  * Start faster with bare mode\n  * Background tasks at exit\n* Examples\n  * Pipe data through Claude\n  * Add Claude to a build script\n  * Get structured output\n  * Stream responses\n  * Auto-approve tools\n  * Create a commit\n  * Customize the system prompt\n  * Continue conversations\n* Next steps\n\n### [deep-links](https://code.claude.com/docs/en/deep-links.md)\n\n* How it works\n  * What a launched session shows\n* Build a link\n  * Choose between `cwd` and `repo`\n* Examples\n  * Embed a link in a runbook\n  * Open a link from the shell\n* Registration and supported platforms\n* Open a VS Code tab instead of a terminal\n* Troubleshooting\n  * Clicking the link does nothing\n  * The link renders as plain text instead of being clickable\n  * The session opens in my home directory instead of the repo\n  * The link opens the wrong terminal\n* Learn more\n\n## Guides\n\n### [large-codebases](https://code.claude.com/docs/en/large-codebases.md)\n\n* What this guide covers\n  * Settings on this page\n  * The example monorepo\n* Choose where to start Claude\n* Layer CLAUDE.md files by directory\n  * Choose between per-directory CLAUDE.md and path-scoped rules\n  * Exclude irrelevant CLAUDE.md files\n* Reduce what Claude reads\n  * Block reads of generated and vendored code\n  * Reduce file reads with code intelligence\n* Scope worktrees and file access\n  * Check out only the directories you need\n  * Grant access across packages or repositories\n* Add per-directory skills\n  * Keep skills discoverable\n* Centralize conventions when layering stops scaling\n  * Recommend the right plugin at session start\n* Put it together\n* Scope and plan changes that span packages\n* Next steps\n\n## Troubleshooting\n\n### [troubleshoot-install](https://code.claude.com/docs/en/troubleshoot-install.md)\n\n* Find your error\n* Run diagnostic checks\n  * Check network connectivity\n  * Verify your PATH\n  * Check for conflicting installations\n  * Check directory permissions\n  * Verify the binary works\n* Common installation issues\n  * Install script returns HTML instead of a shell script\n  * `command not found: claude` after installation\n  * `curl: (56) Failure writing output to destination`\n  * Homebrew cask unavailable or outdated\n  * TLS or SSL connection errors\n  * `Failed to fetch version from downloads.claude.ai`\n  * Wrong install command on Windows\n  * `The process cannot access the file` during Windows install\n  * Install killed on low-memory Linux servers\n  * Install hangs in Docker\n  * Claude Desktop overrides the `claude` command on Windows\n  * Claude Code on Windows requires either Git for Windows (for bash) or PowerShell\n  * Claude Code does not support 32-bit Windows\n  * Linux musl or glibc binary mismatch\n  * `Illegal instruction`\n  * `dyld: cannot load` on macOS\n  * `Exec format error` on WSL1\n  * npm install errors in WSL\n  * Permission errors during installation\n  * Native binary not found after npm install\n* Login and authentication\n  * Reset your login\n  * OAuth error: Invalid code\n  * 403 Forbidden after login\n  * This organization has been disabled with an active subscription\n  * OAuth login fails in WSL2, SSH, or containers\n  * Not logged in or token expired\n  * Bedrock, Agent Platform, or Foundry credentials not loading\n* Still stuck\n\n### [troubleshooting](https://code.claude.com/docs/en/troubleshooting.md)\n\n* Performance and stability\n  * High CPU or memory usage\n  * Auto-compaction stops with a thrashing error\n  * Command hangs or freezes\n  * Garbled or corrupted text in an editor's integrated terminal\n  * Search and discovery issues\n  * Slow or incomplete search results on WSL\n* Get more help\n\n### [debug-your-config](https://code.claude.com/docs/en/debug-your-config.md)\n\n* See what loaded into context\n* Check resolved settings\n* Check MCP servers\n* Check hooks\n* Test against a clean configuration\n* Check common causes\n* Related resources\n\n### [errors](https://code.claude.com/docs/en/errors.md)\n\n* Find your error\n* Automatic retries\n* Server errors\n  * API Error: 500 Internal server error\n  * API Error: Repeated 529 Overloaded errors\n  * Request timed out\n  * The response above may be incomplete\n  * Auto mode cannot determine the safety of an action\n  * Agent terminated early due to an API error\n* Usage limits\n  * You've hit your session limit\n  * Usage credits required for 1M context\n  * Server is temporarily limiting requests\n  * Request rejected (429)\n  * Credit balance is too low\n* Authentication errors\n  * Not logged in\n  * Could not resolve authentication method\n  * Invalid API key\n  * This organization has been disabled\n  * Your organization has disabled API key authentication\n  * Your organization has disabled Claude subscription access\n  * Routines are disabled by your organization's policy\n  * Remote Control requires the Anthropic API\n  * OAuth token revoked or expired\n  * OAuth scope requirement\n  * AWS credentials expired or invalid\n  * AWS authentication failed\n* Network and connection errors\n  * Unable to connect to API\n  * SSL certificate errors\n  * Host not allowed in a cloud session\n  * Couldn't reconnect to your Remote Control session\n* Request errors\n  * Prompt is too long\n  * Error during compaction: Conversation too long\n  * Request too large\n  * Image was too large\n  * Unable to resize image\n  * PDF errors\n  * Extra inputs are not permitted\n  * There's an issue with the selected model\n  * Model is not a recognized model id\n  * Claude Opus is not available with the Claude Pro plan\n  * Model is restricted by your organization's settings\n  * thinking.type.enabled is not supported for this model\n  * Thinking budget exceeds output limit\n  * Tool use or thinking block mismatch\n  * Usage Policy refusal\n  * Safety measures flagged a cybersecurity topic\n* Installation errors\n  * Installation was killed before it could finish\n  * The connection dropped while downloading the update\n* Command-line errors\n  * Conflict between --bg and --print\n  * The --json-schema value is not a valid JSON Schema\n  * Could not import a server from Claude Desktop\n* Plugin errors\n  * Marketplace is registered from an untrusted source\n* Configuration warnings\n  * Workspace has not been trusted\n* Responses seem lower quality than usual\n* Report an error\n\n## Setup and access\n\n### [admin-setup](https://code.claude.com/docs/en/admin-setup.md)\n\n* Choose your API provider\n* Decide how settings reach devices\n* Decide what to enforce\n* Set up usage visibility\n* Review data handling\n* Verify and onboard\n* Next steps\n\n### [setup](https://code.claude.com/docs/en/setup.md)\n\n* System requirements\n  * Additional dependencies\n* Install Claude Code\n  * Set up on Windows\n  * Alpine Linux and musl-based distributions\n* Verify your installation\n* Authenticate\n* Update Claude Code\n  * Auto-updates\n  * Configure release channel\n  * Pin a minimum version\n  * Disable auto-updates\n  * Update manually\n* Advanced installation options\n  * Install a specific version\n  * Install with Linux package managers\n  * Install with npm\n  * Binary integrity and code signing\n    * Verify the manifest signature\n    * Platform code signatures\n* Uninstall Claude Code\n  * Native installation\n  * Homebrew installation\n  * WinGet installation\n  * apt / dnf / apk\n  * npm\n  * Remove configuration files\n\n### [authentication](https://code.claude.com/docs/en/authentication.md)\n\n* Log in to Claude Code\n* Set up team authentication\n  * Claude for Teams or Enterprise\n  * Claude Console authentication\n  * Cloud provider authentication\n* Credential management\n  * Renew an expiring login\n  * Authentication precedence\n  * Generate a long-lived token\n\n### [server-managed-settings](https://code.claude.com/docs/en/server-managed-settings.md)\n\n* Requirements\n* Choose between server-managed and endpoint-managed settings\n* Configure server-managed settings\n  * Verify settings delivery\n  * Access control\n  * Managed-only settings\n  * Current limitations\n* Settings delivery\n  * Settings precedence\n  * Fetch and caching behavior\n  * Invalid entries in delivered settings\n  * Enforce fail-closed startup\n  * Security approval dialogs\n* Platform availability\n* Audit logging\n* Security considerations\n* See also\n\n### [managed-mcp](https://code.claude.com/docs/en/managed-mcp.md)\n\n* Choose a pattern\n* Exclusive control with managed-mcp.json\n  * Authenticate with per-user credentials\n  * Validate the configuration\n  * Disable MCP entirely\n  * Allow claude.ai connectors alongside the managed set\n* Policy-based control with allowlists and denylists\n  * Match servers by URL, command, or name\n  * How a server is evaluated\n  * Example configuration\n  * Restrict the allowlist to managed settings only\n* How restrictions appear to users\n* Monitor MCP usage\n* Configuration summary\n* Related resources\n\n### [auto-mode-config](https://code.claude.com/docs/en/auto-mode-config.md)\n\n* Where the classifier reads configuration\n* Define trusted infrastructure\n* Override the block and allow rules\n* Route all shell commands through the classifier\n* Inspect the defaults and your effective config\n* Review denials\n* See also\n\n## Deployment\n\n### [third-party-integrations](https://code.claude.com/docs/en/third-party-integrations.md)\n\n* Compare deployment options\n* Configure proxies and gateways\n  * Amazon Bedrock\n  * Microsoft Foundry\n  * Google Cloud's Agent Platform\n* Best practices for organizations\n  * Invest in documentation and memory\n  * Simplify deployment\n  * Start with guided usage\n  * Pin model versions for cloud providers\n  * Configure security policies\n  * Leverage MCP for integrations\n* Next steps\n\n### [feature-availability](https://code.claude.com/docs/en/feature-availability.md)\n\n* Availability by model provider\n  * Features available on every provider\n  * Features that require a Claude subscription\n  * CLI capabilities that vary by provider\n  * Admin and analytics\n  * Summary by provider\n* Availability by subscription plan\n* Model availability\n* Related resources\n\n### [amazon-bedrock](https://code.claude.com/docs/en/amazon-bedrock.md)\n\n* Prerequisites\n* Sign in with Bedrock\n* Set up manually\n  * 1. Submit use case details\n  * 2. Configure AWS credentials\n    * Advanced credential configuration\n      * Example configuration\n      * Configuration settings explained\n  * 3. Configure Claude Code\n  * 4. Pin model versions\n    * Map each model version to an inference profile\n* Startup model checks\n* IAM configuration\n* 1M token context window\n* Service tiers\n* AWS Guardrails\n* Use the Mantle endpoint\n  * Enable Mantle\n  * Select a Mantle model\n  * Run Mantle alongside the Invoke API\n  * Route Mantle through a gateway\n  * Mantle environment variables\n* Troubleshooting\n  * Authentication loop with SSO and corporate proxies\n  * Region issues\n  * Zero token counts in /context\n  * Mantle endpoint errors\n* Additional resources\n\n### [claude-platform-on-aws](https://code.claude.com/docs/en/claude-platform-on-aws.md)\n\n* Prerequisites\n* Setup\n  * 1. Configure AWS credentials\n  * 2. Configure Claude Code\n  * 3. Pin model versions\n* Use the Agent SDK\n* Route through a corporate proxy\n* Troubleshooting\n  * `403 Forbidden` or `AccessDenied` on every request\n  * Requests fail with a missing-workspace error\n  * Requests still go to `api.anthropic.com`\n* Additional resources\n\n### [google-vertex-ai](https://code.claude.com/docs/en/google-vertex-ai.md)\n\n* Prerequisites\n* Sign in with Agent Platform\n* Region configuration\n* Set up manually\n  * 1. Enable Agent Platform API\n  * 2. Request model access\n  * 3. Configure GCP credentials\n    * Advanced credential configuration\n  * 4. Configure Claude Code\n  * 5. Pin model versions\n* Startup model checks\n* IAM configuration\n* 1M token context window\n* Troubleshooting\n* Additional resources\n\n### [microsoft-foundry](https://code.claude.com/docs/en/microsoft-foundry.md)\n\n* Prerequisites\n* Setup\n  * 1. Provision Microsoft Foundry resource\n  * 2. Configure Azure credentials\n  * 3. Configure Claude Code\n  * 4. Pin model versions\n  * 5. Run Claude Code\n* Azure RBAC configuration\n* Troubleshooting\n* Additional resources\n\n### [network-config](https://code.claude.com/docs/en/network-config.md)\n\n* Proxy configuration\n  * Environment variables\n  * Basic authentication\n* CA certificate store\n* Custom CA certificates\n* mTLS authentication\n* Network access requirements\n* Additional resources\n\n### [devcontainer](https://code.claude.com/docs/en/devcontainer.md)\n\n* Add Claude Code to your dev container\n* Persist authentication and settings across rebuilds\n* Enforce organization policy\n* Restrict network egress\n* Run without permission prompts\n* Try the reference container\n* Next steps\n\n### Gateways > Claude apps gateway\n\n#### [claude-apps-gateway-config](https://code.claude.com/docs/en/claude-apps-gateway-config.md)\n\n* File structure\n* Secret expansion\n* Required sections\n  * `listen`\n  * `oidc`\n  * `session`\n  * `store`\n  * `upstreams`\n    * Anthropic API\n    * Amazon Bedrock\n    * Claude Platform on AWS\n    * Google Cloud Agent Platform\n    * Microsoft Foundry\n    * Multiple upstreams\n* Optional sections\n  * `admin`\n  * `enforcement`\n  * `models`\n  * `managed`\n    * What goes in `cli`\n    * Precedence with other managed sources\n  * `telemetry`\n  * HTTP tuning\n* Complete example\n* Client-side managed settings\n* Related\n\n#### [claude-apps-gateway-spend-limits](https://code.claude.com/docs/en/claude-apps-gateway-spend-limits.md)\n\n* Set a cap\n  * Authenticate to the admin API\n* How enforcement works\n  * Postgres availability\n* Admin API reference\n  * `/effective`\n  * `/audit`\n  * Pagination\n* Data lifecycle\n* Related\n\n#### [claude-apps-gateway-deploy](https://code.claude.com/docs/en/claude-apps-gateway-deploy.md)\n\n* Identity provider setup\n* Deployment\n  * Container image\n  * Kubernetes\n  * Cloud Run\n  * Push the gateway URL to developer machines\n* Operations\n  * Logs\n  * Health\n  * Outage behavior\n  * JWT secret rotation\n  * Postgres\n  * Upgrades\n* Security\n  * Data flow\n  * Threat model summary\n  * User-code brute-force resistance\n  * Compliance posture\n* Troubleshooting\n* Related\n\n#### [claude-apps-gateway-on-gcp](https://code.claude.com/docs/en/claude-apps-gateway-on-gcp.md)\n\n* What you'll build\n* Prerequisites\n* Deploy the gateway\n* Terraform reference\n* Troubleshooting\n* Next steps\n\n### Gateways > Other gateways\n\n#### [llm-gateway-connect](https://code.claude.com/docs/en/llm-gateway-connect.md)\n\n* Check for an existing configuration\n* Configure Claude Code yourself\n  * Set the credential variable\n  * Set the base URL and credential\n    * Set as shell environment variables\n    * Set in a settings file\n  * Verify the connection\n    * Confirm in Claude Code\n  * How the credential variable maps to a header\n  * Conflicts with an existing login\n* Configure each surface\n  * VS Code extension\n  * Desktop app\n  * GitHub Actions\n  * Agent SDK\n  * Slack, web, and Remote Control\n* Additional configuration\n  * Send additional headers\n  * Add gateway models to the model picker\n  * Rotate credentials with apiKeyHelper\n  * Route to a cloud provider through a gateway\n    * Amazon Bedrock\n    * Google Cloud's Agent Platform\n    * Microsoft Foundry\n    * Claude Platform on AWS\n* Troubleshoot gateway errors\n* Related resources\n\n#### [llm-gateway-rollout](https://code.claude.com/docs/en/llm-gateway-rollout.md)\n\n* Prerequisites\n  * Gateway requirements\n* Rollout steps\n  * Confirm the gateway routes your models\n  * Issue developer credentials\n  * Test Claude Code against the gateway\n  * Distribute the configuration\n    * What to distribute\n    * Distribute through managed settings\n    * Hand developers the values to set themselves\n  * Verify the rollout\n* Maintain the gateway\n* Related resources\n\n#### [llm-gateway-protocol](https://code.claude.com/docs/en/llm-gateway-protocol.md)\n\n* API formats\n  * Foundry and Claude Platform on AWS\n  * Optional endpoints and startup traffic\n  * Streaming\n  * Format mismatch with the upstream\n* Request headers\n  * Forward as open lists\n* System prompt attribution block\n* Feature pass-through\n  * Automatic retry and error forwarding\n  * Disable pre-release capabilities\n* Model discovery\n  * When discovery runs\n  * Request and response\n  * Picker entries and caching\n* Related resources\n\n## Gateways\n\n### [gateways](https://code.claude.com/docs/en/gateways.md)\n\n* How a gateway works\n* Choose a gateway\n  * Claude apps gateway\n  * Other gateways\n* Subscriptions and gateways\n* Configure separately from the gateway\n* Next steps\n\n## Usage and costs\n\n### [monitoring-usage](https://code.claude.com/docs/en/monitoring-usage.md)\n\n* Quick start\n* Administrator configuration\n* Configuration details\n  * Common configuration variables\n  * mTLS authentication\n  * Metrics cardinality control\n  * Traces (beta)\n    * Span hierarchy\n    * Span attributes\n  * Dynamic headers\n    * Settings configuration\n    * Script requirements\n    * Refresh behavior\n  * Multi-team organization support\n  * Example configurations\n* Available metrics and events\n  * Standard attributes\n  * Metrics\n  * Metric details\n    * Session counter\n    * Lines of code counter\n    * Pull request counter\n    * Commit counter\n    * Cost counter\n    * Token counter\n    * Code edit tool decision counter\n    * Active time counter\n  * Events\n    * Event correlation attributes\n    * User prompt event\n    * Assistant response event\n    * Tool result event\n    * API request event\n    * API error event\n    * API refusal event\n    * API request body event\n    * API response body event\n    * Tool decision event\n    * Permission mode changed event\n    * Auth event\n    * MCP server connection event\n    * Internal error event\n    * Plugin installed event\n    * Plugin loaded event\n    * Skill activated event\n    * At mention event\n    * API retries exhausted event\n    * Hook registered event\n    * Hook execution start event\n    * Hook execution complete event\n    * Hook plugin metrics event\n    * Compaction event\n    * Feedback survey event\n* Interpret metrics and events data\n  * Usage monitoring\n  * Cost monitoring\n  * Alerting and segmentation\n  * Detect retry exhaustion\n  * Event analysis\n* Audit security events\n  * Attribute actions to users\n  * Audit MCP activity\n  * Map security questions to events\n  * Send events to a SIEM\n* Backend considerations\n  * For metrics\n  * For events/logs\n  * For traces\n* Service information\n* ROI measurement resources\n* Security and privacy\n* Monitor Claude Code on Amazon Bedrock\n\n### [costs](https://code.claude.com/docs/en/costs.md)\n\n* Track your costs\n  * Using the `/usage` command\n* Managing costs for teams\n  * Rate limit recommendations\n  * Agent team token costs\n* Reduce token usage\n  * Manage context proactively\n  * Choose the right model\n  * Reduce MCP server overhead\n  * Install code intelligence plugins for typed languages\n  * Offload processing to hooks and skills\n  * Move instructions from CLAUDE.md to skills\n  * Adjust extended thinking\n  * Delegate verbose operations to subagents\n  * Manage agent team costs\n  * Write specific prompts\n  * Work efficiently on complex tasks\n* Background token usage\n* Understanding changes in Claude Code behavior\n\n### [analytics](https://code.claude.com/docs/en/analytics.md)\n\n* Access analytics for Team and Enterprise\n  * Enable contribution metrics\n  * Review summary metrics\n  * Explore the charts\n    * Track adoption\n    * Measure PRs per user\n    * View pull requests breakdown\n    * Find top contributors\n  * PR attribution\n    * Tagging criteria\n    * Attribution process\n    * Time window\n    * Excluded files\n    * Attribution notes\n  * Get the most from analytics\n    * Monitor adoption\n    * Measure ROI\n    * Identify power users\n    * Access data programmatically\n* Access analytics for API customers\n  * View team insights\n* Related resources\n\n## Plugin distribution\n\n### [plugin-marketplaces](https://code.claude.com/docs/en/plugin-marketplaces.md)\n\n* Overview\n* Walkthrough: create a local marketplace\n* Create the marketplace file\n* Marketplace schema\n  * Required fields\n  * Owner fields\n  * Optional fields\n* Plugin entries\n  * Required fields\n  * Optional plugin fields\n* Plugin sources\n  * Relative paths\n  * GitHub repositories\n  * Git repositories\n  * Git subdirectories\n  * npm packages\n  * Advanced plugin entries\n  * Strict mode\n* Host and distribute marketplaces\n  * Host on GitHub (recommended)\n  * Host on other git services\n  * Private repositories\n  * Test locally before distribution\n  * Require marketplaces for your team\n  * Pre-populate plugins for containers\n  * Managed marketplace restrictions\n    * Common configurations\n    * How restrictions work\n  * Version resolution and release channels\n    * Set up release channels\n      * Example\n      * Assign channels to user groups\n    * Pin dependency versions\n  * Rename or remove a plugin\n* Validation and testing\n* Manage marketplaces from the CLI\n  * Plugin marketplace add\n  * Plugin marketplace list\n  * Plugin marketplace remove\n  * Plugin marketplace update\n* Troubleshooting\n  * Marketplace not loading\n  * Marketplace validation errors\n  * Plugin installation failures\n  * Private repository authentication fails\n  * Marketplace updates fail in offline environments\n  * Git operations time out\n  * Plugins with relative paths fail in URL-based marketplaces\n  * Files not found after installation\n* See also\n\n### [plugin-dependencies](https://code.claude.com/docs/en/plugin-dependencies.md)\n\n* Why constrain dependency versions\n* Declare a dependency with a version constraint\n* Depend on a plugin from another marketplace\n* Tag plugin releases for version resolution\n* How constraints interact\n* Enable or disable a plugin with dependencies\n* Remove orphaned auto-installed dependencies\n* Resolve dependency errors\n* See also\n\n### [plugin-hints](https://code.claude.com/docs/en/plugin-hints.md)\n\n* How it works\n* Emit the hint\n* Choose where to emit\n* What the user sees\n* Hint format\n* Requirements\n* Get your plugin into the official marketplace\n* See also\n\n### [plugin-relevance](https://code.claude.com/docs/en/plugin-relevance.md)\n\n* How it works\n* Add relevance to a plugin entry\n* Field reference\n  * `relevance`\n  * `relevance.signals`\n* Enable suggestions in managed settings\n* What the user sees\n* Validate your marketplace\n* See also\n\n## Security and data\n\n### [security](https://code.claude.com/docs/en/security.md)\n\n* How we approach security\n  * Security foundation\n  * Permission-based architecture\n  * Built-in protections\n  * User responsibility\n* Protect against prompt injection\n  * Core protections\n  * Privacy safeguards\n  * Additional safeguards\n* MCP security\n* IDE security\n* Cloud execution security\n* Security best practices\n  * Working with sensitive code\n  * Team security\n  * Reporting security issues\n* Related resources\n\n### [data-usage](https://code.claude.com/docs/en/data-usage.md)\n\n* Data policies\n  * Data training policy\n  * Development Partner Program\n  * Feedback using the `/feedback` command\n  * Session quality surveys\n  * Data retention\n* Data access\n* Local Claude Code: Data flow and dependencies\n  * Cloud execution: Data flow and dependencies\n* Telemetry services\n* Default behaviors by API provider\n  * WebFetch domain safety check\n\n### [zero-data-retention](https://code.claude.com/docs/en/zero-data-retention.md)\n\n* ZDR scope\n  * What ZDR covers\n  * What ZDR does not cover\n* Features disabled under ZDR\n  * Model availability under ZDR\n* Data retention for policy violations\n* Request ZDR\n\n## Adoption\n\n### [communications-kit](https://code.claude.com/docs/en/communications-kit.md)\n\n* Launch communications\n  * Before you send\n  * The announcement\n  * Executive sponsor variant\n  * Pilot group variant\n  * Champion recruitment DM\n* Tips and tricks campaign\n  * Get started\n  * Project memory\n  * Control and safety\n  * Connect your tools\n  * Automate your workflows\n  * Day-to-day development\n  * Share and scale\n  * Security and admin\n* Quick reference\n  * FAQ responses\n  * Prompt templates\n\n### [champion-kit](https://code.claude.com/docs/en/champion-kit.md)\n\n* The champion role\n  * What this should cost you\n* Share what you discover\n  * What is worth sharing\n  * Where to share it\n  * The format that works\n* Be the person people ask\n  * Answer with a prompt rather than an explanation\n  * Point at the feature rather than the documentation\n  * Questions you are likely to hear\n* Grow the circle\n  * Patterns that tend to work\n  * Thirty-day playbook\n  * When someone wants to go deeper\n* Respond to common concerns\n* Quick-reference sheet\n\n## Settings and permissions\n\n### [settings](https://code.claude.com/docs/en/settings.md)\n\n* Configuration scopes\n  * Available scopes\n  * When to use each scope\n  * How scopes interact\n  * What uses scopes\n* Settings files\n  * When edits take effect\n  * Invalid entries in managed settings\n  * Available settings\n  * Global config settings\n  * Worktree settings\n  * Permission settings\n  * Permission rule syntax\n  * Sandbox settings\n    * Sandbox path prefixes\n  * Attribution settings\n  * File suggestion settings\n  * Footer link badges\n  * Hook configuration\n  * Compute managed settings with a policy helper\n  * Settings precedence\n  * Verify active settings\n  * Key points about the configuration system\n  * System prompt\n  * Exclude sensitive files\n* Subagent configuration\n* Plugin configuration\n  * Plugin settings\n    * `enabledPlugins`\n    * `extraKnownMarketplaces`\n    * `strictKnownMarketplaces`\n    * `strictPluginOnlyCustomization`\n  * Manage plugins\n* Environment variables\n* Tools available to Claude\n* See also\n\n### [permissions](https://code.claude.com/docs/en/permissions.md)\n\n* Permission system\n* Manage permissions\n* Permission modes\n* Permission rule syntax\n  * Match all uses of a tool\n  * Use specifiers for fine-grained control\n  * Match by input parameter\n  * Wildcard patterns\n  * Tool name wildcards\n* Tool-specific permission rules\n  * Bash\n    * Compound commands\n    * Process wrappers\n    * Read-only commands\n  * PowerShell\n  * Read and Edit\n  * WebFetch\n  * MCP\n  * Agent (subagents)\n  * Cd\n* Extend permissions with hooks\n* Working directories\n  * Additional directories grant file access, not configuration\n* How permissions interact with sandboxing\n* Managed settings\n  * Managed-only settings\n* Settings precedence\n* Project allow rules and workspace trust\n* Example configurations\n* See also\n\n### [sandbox-environments](https://code.claude.com/docs/en/sandbox-environments.md)\n\n* Compare sandboxing approaches\n* Choose an approach\n  * How isolation relates to permission modes\n* Sandboxed Bash tool\n* Sandbox runtime\n* Dev containers\n* Custom container\n* Virtual machine\n* Claude Code on the web\n* Enforce isolation across an organization\n* See also\n\n### [sandboxing](https://code.claude.com/docs/en/sandboxing.md)\n\n* Get started\n  * Set up Linux and WSL2\n  * Sandbox modes\n* Configure sandboxing\n  * Protect credentials\n    * Mask environment variables\n* How sandboxing works\n  * Filesystem isolation\n  * Network isolation\n  * OS-level enforcement\n* How sandboxing relates to permissions and permission modes\n  * Permission rules\n  * Permission modes\n* Configure the sandbox for your organization\n  * Enforce sandboxing with managed settings\n  * Keep developers from widening the policy\n  * Custom proxy configuration\n* Troubleshooting\n* Limitations\n  * Security limitations\n  * Platform and tool compatibility\n  * Scope\n* See also\n\n## Model and responses\n\n### [model-config](https://code.claude.com/docs/en/model-config.md)\n\n* Available models\n  * Model aliases\n  * Work with Fable 5\n  * Setting your model\n* Restrict model selection\n  * Surface coverage\n  * Default model behavior\n  * Enforce the allowlist for the Default model\n  * Control the model users run on\n  * Merge behavior\n  * Mantle model IDs\n  * Organization model restrictions\n* Organization default model\n* Organization effort limits\n* Special model behavior\n  * `default` model setting\n  * `opusplan` model setting\n  * Fallback model chains\n  * Automatic model fallback\n    * Check what triggered fallback\n    * Ask before switching\n    * Enable fallback on Bedrock, Agent Platform, and Foundry\n    * Security research and biology workloads\n  * Adjust effort level\n    * Choose an effort level\n    * Use ultrathink for one-off deep reasoning\n    * Set the effort level\n    * Adaptive reasoning and fixed thinking budgets\n  * Extended thinking\n  * Extended context\n    * Sonnet 5 context window\n* Checking your current model\n* Add a custom model option\n* Environment variables\n  * Pin models for third-party deployments\n  * Customize pinned model display and capabilities\n  * Override model IDs per version\n  * Prompt caching configuration\n\n### [fast-mode](https://code.claude.com/docs/en/fast-mode.md)\n\n* Toggle fast mode\n* Understand the cost tradeoff\n* Decide when to use fast mode\n  * Fast mode vs effort level\n* Requirements\n  * Enable fast mode for your organization\n  * Require per-session opt-in\n* Handle rate limits\n* Research preview\n* See also\n\n### [advisor](https://code.claude.com/docs/en/advisor.md)\n\n* When to use the advisor\n* Enable the advisor\n  * Use the `/advisor` command\n  * Set `advisorModel` in settings\n  * Use the `--advisor` flag\n* Choose an advisor model\n  * Common model pairings\n* When Claude consults the advisor\n* What you see during a session\n* Cost\n* Impact on prompt caching\n* Requirements\n* Turn the advisor off\n* Compare with related features\n* See also\n\n### [output-styles](https://code.claude.com/docs/en/output-styles.md)\n\n* Built-in output styles\n* Change your output style\n* Create a custom output style\n  * Frontmatter\n* How output styles work\n* Comparisons to related features\n* Related resources\n\n## Interface\n\n### [terminal-config](https://code.claude.com/docs/en/terminal-config.md)\n\n* Enter multiline prompts\n* Enable Option key shortcuts on macOS\n* Get a terminal bell or notification\n  * Play a sound with a Notification hook\n* Configure tmux\n* Match the color theme\n  * Create a custom theme\n    * Text and accent colors\n    * Status colors\n    * Input box and mode indicators\n    * Diff rendering\n    * Fullscreen mode\n    * Usage meter and speaker labels\n    * Shimmer variants and subagent colors\n* Switch to fullscreen rendering\n* Paste large content\n* Edit prompts with Vim keybindings\n* Related resources\n\n### [fullscreen](https://code.claude.com/docs/en/fullscreen.md)\n\n* Enable fullscreen rendering\n* What changes\n* Use the mouse\n* Scroll the conversation\n  * Auto-follow\n  * Mouse wheel scrolling\n  * Scroll in the JetBrains IDE terminal\n* Search and review the conversation\n* Clear the conversation\n* Use with tmux\n* Keep native text selection\n* Research preview\n\n### [voice-dictation](https://code.claude.com/docs/en/voice-dictation.md)\n\n* Requirements\n* Enable voice dictation\n* Hold to record\n* Tap to record and send\n* Change the dictation language\n* Rebind the dictation key\n* Troubleshooting\n  * Terminal not listed in macOS Microphone settings\n* See also\n\n### [statusline](https://code.claude.com/docs/en/statusline.md)\n\n* Set up a status line\n  * Use the /statusline command\n  * Manually configure a status line\n  * Disable the status line\n* Build a status line step by step\n* How status lines work\n* Available data\n  * Context window fields\n* Examples\n  * Context window usage\n  * Git status with colors\n  * Cost and duration tracking\n  * Display multiple lines\n  * Clickable links\n  * Rate limit usage\n  * Cache expensive operations\n  * Windows configuration\n* Subagent status lines\n* Tips\n* Troubleshooting\n\n### [keybindings](https://code.claude.com/docs/en/keybindings.md)\n\n* Configuration file\n* Contexts\n* Available actions\n  * App actions\n  * History actions\n  * Chat actions\n  * Autocomplete actions\n  * Confirmation actions\n  * Permission actions\n  * Transcript actions\n  * History search actions\n  * Task actions\n  * Theme actions\n  * Help actions\n  * Tabs actions\n  * Attachments actions\n  * Footer actions\n  * Message selector actions\n  * Diff actions\n  * Model picker actions\n  * Select actions\n  * Plugin actions\n  * Settings actions\n  * Voice actions\n  * Scroll actions\n* Keystroke syntax\n  * Modifiers\n  * Uppercase letters\n  * Chords\n  * Special keys\n* Unbind default shortcuts\n* Reserved shortcuts\n* Terminal conflicts\n* Vim mode interaction\n* Validation\n\n## Reference\n\n### [cli-reference](https://code.claude.com/docs/en/cli-reference.md)\n\n* CLI commands\n* CLI flags\n  * System prompt flags\n* See also\n\n### [commands](https://code.claude.com/docs/en/commands.md)\n\n* Commands across a typical workflow\n* All commands\n* MCP prompts\n* See also\n\n### [env-vars](https://code.claude.com/docs/en/env-vars.md)\n\n* Set environment variables\n  * In your shell\n  * In settings files\n* Precedence\n* Variables\n* See also\n\n### [tools-reference](https://code.claude.com/docs/en/tools-reference.md)\n\n* Configure tools with permission rules and hooks\n* Agent tool behavior\n* Bash tool behavior\n* Edit tool behavior\n* Glob tool behavior\n* Grep tool behavior\n* LSP tool behavior\n* Monitor tool\n  * WebSocket source\n* NotebookEdit tool behavior\n* PowerShell tool\n  * Enable the PowerShell tool\n  * Shell selection in settings, hooks, and skills\n  * Preview limitations\n* Read tool behavior\n* WebFetch tool behavior\n* WebSearch tool behavior\n* Write tool behavior\n* Check which tools are available\n* See also\n\n### [interactive-mode](https://code.claude.com/docs/en/interactive-mode.md)\n\n* Keyboard shortcuts\n  * General controls\n  * Text editing\n  * Theme and display\n  * Multiline input\n  * Quick commands\n  * Transcript viewer\n  * Voice input\n* Commands\n* Vim editor mode\n  * Mode switching\n  * Navigation (NORMAL mode)\n  * Editing (NORMAL mode)\n  * Text objects (NORMAL mode)\n  * Visual mode\n* Command history\n  * Reverse search with Ctrl+R\n* Background Bash commands\n  * How backgrounding works\n  * Shell mode with `!` prefix\n* Prompt suggestions\n* Side questions with /btw\n* Task list\n* Session recap\n* PR review status\n* See also\n\n### [checkpointing](https://code.claude.com/docs/en/checkpointing.md)\n\n* How checkpoints work\n  * Automatic tracking\n  * Rewind and summarize\n    * Rewind past a cleared conversation\n    * Restore vs. summarize\n* Common use cases\n* Limitations\n  * Bash command changes not tracked\n  * External changes not tracked\n  * Not a replacement for version control\n* See also\n\n### [hooks](https://code.claude.com/docs/en/hooks.md)\n\n* Hook lifecycle\n  * How a hook resolves\n* Configuration\n  * Hook locations\n  * Matcher patterns\n    * Match MCP tools\n  * Hook handler fields\n    * Common fields\n    * Command hook fields\n      * Exec form and shell form\n    * HTTP hook fields\n    * MCP tool hook fields\n    * Prompt and agent hook fields\n  * Reference scripts by path\n  * Hooks in skills and agents\n  * The `/hooks` menu\n  * Disable or remove hooks\n* Hook input and output\n  * Common input fields\n  * Exit code output\n    * Exit code 2 behavior per event\n  * HTTP response handling\n  * JSON output\n    * Emit terminal notifications\n    * Add context for Claude\n    * Decision control\n* Hook events\n  * SessionStart\n    * SessionStart input\n    * SessionStart decision control\n    * Persist environment variables\n  * Setup\n    * Setup input\n    * Setup decision control\n  * InstructionsLoaded\n    * InstructionsLoaded input\n    * InstructionsLoaded decision control\n  * UserPromptSubmit\n    * UserPromptSubmit input\n    * UserPromptSubmit decision control\n  * UserPromptExpansion\n    * UserPromptExpansion input\n    * UserPromptExpansion decision control\n  * MessageDisplay\n    * MessageDisplay input\n    * MessageDisplay output\n  * PreToolUse\n    * PreToolUse input\n      * Bash\n      * Write\n      * Edit\n      * Read\n      * Glob\n      * Grep\n      * WebFetch\n      * WebSearch\n      * Agent\n      * AskUserQuestion\n      * ExitPlanMode\n    * PreToolUse decision control\n    * Defer a tool call for later\n  * PermissionRequest\n    * PermissionRequest input\n    * PermissionRequest decision control\n    * Permission update entries\n  * PostToolUse\n    * PostToolUse input\n    * PostToolUse decision control\n  * PostToolUseFailure\n    * PostToolUseFailure input\n    * PostToolUseFailure decision control\n  * PostToolBatch\n    * PostToolBatch input\n    * PostToolBatch decision control\n  * PermissionDenied\n    * PermissionDenied input\n    * PermissionDenied decision control\n  * Notification\n    * Notification input\n  * SubagentStart\n    * SubagentStart input\n  * SubagentStop\n    * SubagentStop input\n  * TaskCreated\n    * TaskCreated input\n    * TaskCreated decision control\n  * TaskCompleted\n    * TaskCompleted input\n    * TaskCompleted decision control\n  * Stop\n    * Stop input\n    * Stop decision control\n  * StopFailure\n    * StopFailure input\n  * TeammateIdle\n    * TeammateIdle input\n    * TeammateIdle decision control\n  * ConfigChange\n    * ConfigChange input\n    * ConfigChange decision control\n  * CwdChanged\n    * CwdChanged input\n    * CwdChanged output\n  * FileChanged\n    * FileChanged input\n    * FileChanged output\n  * WorktreeCreate\n    * WorktreeCreate input\n    * WorktreeCreate output\n  * WorktreeRemove\n    * WorktreeRemove input\n  * PreCompact\n    * PreCompact input\n  * PostCompact\n    * PostCompact input\n  * SessionEnd\n    * SessionEnd input\n  * Elicitation\n    * Elicitation input\n    * Elicitation output\n  * ElicitationResult\n    * ElicitationResult input\n    * ElicitationResult output\n* Prompt-based hooks\n  * How prompt-based hooks work\n  * Prompt hook configuration\n  * Response schema\n  * Check multiple conditions before stopping\n* Agent-based hooks\n  * How agent hooks work\n  * Agent hook configuration\n* Run hooks in the background\n  * Configure an async hook\n  * How async hooks execute\n  * Run tests after file changes\n  * Limitations\n* Security considerations\n  * Disclaimer\n  * Security best practices\n* Windows PowerShell tool\n* Debug hooks\n\n### [plugins-reference](https://code.claude.com/docs/en/plugins-reference.md)\n\n* Plugin components reference\n  * Skills\n  * Agents\n  * Hooks\n  * MCP servers\n  * LSP servers\n  * Monitors\n  * Themes\n* Plugin installation scopes\n* Skills-directory plugins\n  * Choose where the plugin loads from\n  * Edit, reload, and disable a skills-directory plugin\n* Plugin manifest schema\n  * Complete schema\n  * Required fields\n  * Unrecognized fields\n  * Metadata fields\n  * Default enablement\n  * Component path fields\n  * Experimental components\n  * User configuration\n  * Channels\n  * Path behavior rules\n  * Environment variables\n    * Persistent data directory\n* Plugin caching and file resolution\n  * Path traversal limitations\n  * Share files within a marketplace with symlinks\n* Plugin directory structure\n  * Standard plugin layout\n  * File locations reference\n* CLI commands reference\n  * plugin init\n  * plugin install\n  * plugin uninstall\n  * plugin prune\n  * plugin enable\n  * plugin disable\n  * plugin update\n  * plugin list\n  * plugin details\n  * plugin tag\n* Debugging and development tools\n  * Debugging commands\n  * Common issues\n  * Example error messages\n  * Hook troubleshooting\n  * MCP server troubleshooting\n  * Directory structure mistakes\n* Distribution and versioning reference\n  * Version management\n* See also\n\n### [channels-reference](https://code.claude.com/docs/en/channels-reference.md)\n\n* Overview\n* What you need\n* Example: build a webhook receiver\n* Test during the research preview\n* Server options\n* Notification format\n* Expose a reply tool\n* Gate inbound messages\n* Relay permission prompts\n  * How relay works\n  * Permission request fields\n  * Add relay to a chat bridge\n  * Full example\n* Package as a plugin\n* See also\n\n## Glossary\n\n### [glossary](https://code.claude.com/docs/en/glossary.md)\n\n* A\n  * Agent teams\n  * Agentic coding\n  * Agentic harness\n  * Agentic loop\n  * Artifact\n  * Auto memory\n  * Auto mode\n* B\n  * Bare mode\n  * Bundled skills\n* C\n  * Channel\n  * Checkpoint\n  * `.claude` directory\n  * CLAUDE.md\n  * Command\n  * Compaction\n  * Context window\n* D\n  * Dispatch\n* E\n  * Effort level\n  * Extended thinking\n* H\n  * Hook\n* M\n  * Managed settings\n  * MCP (Model Context Protocol)\n  * MCP Tool Search\n* N\n  * Non-interactive mode\n* O\n  * Output style\n* P\n  * Permission mode\n  * Permission rule\n  * Plan mode\n  * Plugin\n  * Project trust\n  * Prompt injection\n* R\n  * Remote Control\n  * Rules\n* S\n  * Sandboxing\n  * Session\n  * Settings layers\n  * Skill\n  * Subagent\n  * Surface\n* T\n  * Teleport\n  * Tool\n  * Turn\n* V\n  * Verification loop\n* W\n  * Worktree isolation\n* Deprecated and renamed terms\n\n## Agent SDK\n\n### [overview](https://code.claude.com/docs/en/agent-sdk/overview.md)\n\n* Get started\n* Capabilities\n  * Claude Code features\n* Compare the Agent SDK to other Claude tools\n* Changelog\n* Reporting bugs\n* Branding guidelines\n* License and terms\n* Next steps\n\n### [quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart.md)\n\n* Prerequisites\n* Setup\n* Create a buggy file\n* Build an agent that finds and fixes bugs\n  * Run your agent\n  * Try other prompts\n  * Customize your agent\n* Key concepts\n* Next steps\n\n## Core concepts\n\n### [agent-loop](https://code.claude.com/docs/en/agent-sdk/agent-loop.md)\n\n* The loop at a glance\n* Turns and messages\n* Message types\n  * Handle messages\n* Tool execution\n  * Built-in tools\n  * Tool permissions\n  * Parallel tool execution\n* Control how the loop runs\n  * Turns and budget\n  * Effort level\n  * Permission mode\n  * Model\n* The context window\n  * What consumes context\n  * Automatic compaction\n  * Keep context efficient\n* Sessions and continuity\n* Handle the result\n* Hooks\n* Put it all together\n* Next steps\n\n### [claude-code-features](https://code.claude.com/docs/en/agent-sdk/claude-code-features.md)\n\n* Control filesystem settings with settingSources\n  * What settingSources does not control\n* Project instructions (CLAUDE.md and rules)\n  * CLAUDE.md load locations\n* Skills\n* Hooks\n  * When to use which hook type\n* Choose the right feature\n* Related resources\n\n### [sessions](https://code.claude.com/docs/en/agent-sdk/sessions.md)\n\n* Choose an approach\n  * Continue, resume, and fork\n* Automatic session management\n  * Python: `ClaudeSDKClient`\n  * TypeScript: `continue: true`\n* Use session options with `query()`\n  * Capture the session ID\n  * Resume by ID\n  * Fork to explore alternatives\n* Resume across hosts\n* Related resources\n\n### [session-storage](https://code.claude.com/docs/en/agent-sdk/session-storage.md)\n\n* The `SessionStore` interface\n* Quick start\n* Write your own adapter\n* Reference implementations\n  * Validate your adapter\n* Behavior notes\n  * Dual-write architecture\n  * Mirror writes are best-effort\n  * `getSessionMessages` returns the post-compaction chain\n  * `forkSession` is not a byte copy\n  * Subagent transcripts\n  * Retention\n* Supported on\n* Related resources\n\n## Input and output\n\n### [streaming-vs-single-mode](https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode.md)\n\n* Overview\n* Streaming Input Mode (Recommended)\n  * How It Works\n  * Benefits\n  * Implementation Example\n* Single Message Input\n  * When to Use Single Message Input\n  * Limitations\n  * Implementation Example\n\n### [user-input](https://code.claude.com/docs/en/agent-sdk/user-input.md)\n\n* Detect when Claude needs input\n* Handle tool approval requests\n  * Respond to tool requests\n* Handle clarifying questions\n  * Question format\n    * Option previews (TypeScript)\n  * Response format\n    * Support free-text input\n  * Complete example\n* Limitations\n* Other ways to get user input\n  * Streaming input\n  * Custom tools\n* Related resources\n\n### [streaming-output](https://code.claude.com/docs/en/agent-sdk/streaming-output.md)\n\n* Enable streaming output\n* StreamEvent reference\n* Message flow\n* Stream text responses\n* Stream tool calls\n* Build a streaming UI\n* Known limitations\n* Next steps\n\n### [structured-outputs](https://code.claude.com/docs/en/agent-sdk/structured-outputs.md)\n\n* Why structured outputs?\n* Quick start\n* Type-safe schemas with Zod and Pydantic\n* Output format configuration\n* Example: TODO tracking agent\n* Error handling\n* Related resources\n\n## Extend with tools\n\n### [custom-tools](https://code.claude.com/docs/en/agent-sdk/custom-tools.md)\n\n* Quick reference\n* Create a custom tool\n  * Weather tool example\n  * Call a custom tool\n  * Add more tools\n  * Add tool annotations\n* Control tool access\n  * Tool name format\n  * Configure allowed tools\n* Handle errors\n* Return images and resources\n  * Images\n  * Resources\n* Return structured data\n* Example: unit converter\n* Next steps\n* Related documentation\n\n### [mcp](https://code.claude.com/docs/en/agent-sdk/mcp.md)\n\n* Quickstart\n* Add an MCP server\n  * In code\n  * From a config file\n* Allow MCP tools\n  * Tool naming convention\n  * Auto-approve with allowedTools\n  * Discover available tools\n* Transport types\n  * stdio servers\n  * HTTP/SSE servers\n  * SDK MCP servers\n* MCP tool search\n* Authentication\n  * Pass credentials via environment variables\n  * HTTP headers for remote servers\n  * OAuth2 authentication\n* Examples\n  * List issues from a repository\n  * Query a database\n* Error handling\n* Troubleshooting\n  * Server shows \"failed\" status\n  * Tools not being called\n  * Connection timeouts\n* Related resources\n\n### [tool-search](https://code.claude.com/docs/en/agent-sdk/tool-search.md)\n\n* How tool search works\n* Configure tool search\n* Optimize tool discovery\n* Limits\n* Related documentation\n\n### [subagents](https://code.claude.com/docs/en/agent-sdk/subagents.md)\n\n* Overview\n* Benefits of using subagents\n  * Context isolation\n  * Parallelization\n  * Specialized instructions and knowledge\n  * Tool restrictions\n* Create subagents\n  * Programmatic definition (recommended)\n  * AgentDefinition configuration\n  * Filesystem-based definition (alternative)\n* What subagents inherit\n* Invoke subagents\n  * Automatic invocation\n  * Explicit invocation\n  * Dynamic agent configuration\n* Detect subagent invocation\n* Resume subagents\n* Tool restrictions\n  * Common tool combinations\n* Scale up with dynamic workflows\n* Troubleshooting\n  * Claude not delegating to subagents\n  * Filesystem-based agents not loading\n  * Long prompt failures on Windows\n* Related documentation\n\n## Customize behavior\n\n### [modifying-system-prompts](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts.md)\n\n* How system prompts work\n  * Decide on a starting point\n* Customize agent behavior\n  * CLAUDE.md files for project-level instructions\n    * Load CLAUDE.md with the SDK\n  * Output styles for persistent configurations\n    * Create an output style\n    * Activate an output style\n  * Append to the `claude_code` preset\n    * Improve prompt caching across users and machines\n  * Custom system prompts\n* Compare the four approaches\n* Use cases and best practices\n  * When to use CLAUDE.md\n  * When to use output styles\n  * When to use `systemPrompt` with append\n  * When to use custom `systemPrompt`\n* Combine approaches\n  * Combine an output style with session-specific additions\n* See also\n\n### [slash-commands](https://code.claude.com/docs/en/agent-sdk/slash-commands.md)\n\n* Discovering Available Slash Commands\n* Sending Slash Commands\n* Common Slash Commands\n  * `/compact` - Compact conversation history\n  * `/clear` - Reset conversation context\n* Creating Custom Slash Commands\n  * File Locations\n  * File Format\n    * Basic Example\n    * With Frontmatter\n  * Using Custom Commands in the SDK\n  * Advanced Features\n    * Arguments and Placeholders\n    * Bash Command Execution\n    * File References\n  * Organization with Namespacing\n  * Practical Examples\n    * Pull Request Review Command\n    * Test Runner Command\n* See Also\n\n### [skills](https://code.claude.com/docs/en/agent-sdk/skills.md)\n\n* Overview\n* How Skills Work with the SDK\n* Using Skills with the SDK\n* Skill Locations\n* Creating Skills\n* Tool Restrictions\n* Discovering Available Skills\n* Testing Skills\n* Troubleshooting\n  * Skills Not Found\n  * Skill Not Being Used\n  * Additional Troubleshooting\n* Related Documentation\n  * Skills Guides\n  * SDK Resources\n\n### [plugins](https://code.claude.com/docs/en/agent-sdk/plugins.md)\n\n* What are plugins?\n* Loading plugins\n  * Path specifications\n* Verifying plugin installation\n* Using plugin skills\n* Complete example\n* Plugin structure reference\n* Common use cases\n  * Development and testing\n  * Project-specific extensions\n  * Multiple plugin sources\n* Troubleshooting\n  * Plugin not loading\n  * Skills not appearing\n  * Path resolution issues\n* See also\n\n## Control and observability\n\n### [permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md)\n\n* How permissions are evaluated\n* Allow and deny rules\n* Permission modes\n  * Available modes\n  * Set permission mode\n  * Mode details\n    * Accept edits mode (`acceptEdits`)\n    * Don't ask mode (`dontAsk`)\n    * Bypass permissions mode (`bypassPermissions`)\n    * Plan mode (`plan`)\n* Related resources\n\n### [hooks](https://code.claude.com/docs/en/agent-sdk/hooks.md)\n\n* How hooks work\n* Available hooks\n* Configure hooks\n  * Matchers\n  * Callback functions\n    * Inputs\n    * Outputs\n    * Asynchronous output\n* Examples\n  * Modify tool input\n  * Add context and block a tool\n  * Auto-approve specific tools\n  * Register multiple hooks\n  * Filter with multi-tool matchers\n  * Track subagent activity\n  * Make HTTP requests from hooks\n  * Forward notifications to Slack\n* Fix common issues\n  * Hook not firing\n  * Matcher not filtering as expected\n  * Hook timeout\n  * Tool blocked unexpectedly\n  * Modified input not applied\n  * Session hooks not available in Python\n  * Subagent permission prompts multiplying\n  * Recursive hook loops with subagents\n  * systemMessage not appearing in output\n* Related resources\n\n### [file-checkpointing](https://code.claude.com/docs/en/agent-sdk/file-checkpointing.md)\n\n* How checkpointing works\n* Implement checkpointing\n* Common patterns\n  * Checkpoint before risky operations\n  * Multiple restore points\n* Try it out\n* Limitations\n* Troubleshooting\n  * Checkpointing options not recognized\n  * User messages don't have UUIDs\n  * \"No file checkpoint found for message\" error\n  * \"File rewinding is not enabled\" error\n  * \"ProcessTransport is not ready for writing\" error\n* Next steps\n\n### [cost-tracking](https://code.claude.com/docs/en/agent-sdk/cost-tracking.md)\n\n* Understand token usage\n* Get the total cost of a query\n* Track per-step and per-model usage\n  * Track per-step usage\n  * Break down usage per model\n* Accumulate costs across multiple calls\n* Handle errors, caching, and token discrepancies\n  * Resolve output token discrepancies\n  * Track costs on failed conversations\n  * Track cache tokens\n  * Extend the prompt cache TTL to one hour\n* Related documentation\n\n### [observability](https://code.claude.com/docs/en/agent-sdk/observability.md)\n\n* How telemetry flows from the SDK\n* Enable telemetry export\n  * Flush telemetry from short-lived calls\n* Read agent traces\n* Link traces to your application\n* Tag telemetry from your agent\n* Attribute actions to your end users\n* Control sensitive data in exports\n* Related documentation\n\n### [todo-tracking](https://code.claude.com/docs/en/agent-sdk/todo-tracking.md)\n\n* Todo Lifecycle\n* When Todos Are Used\n* Examples\n  * Monitoring Todo Changes\n  * Real-time Progress Display\n* Migrate to Task tools\n* Related Documentation\n\n## Deployment\n\n### [hosting](https://code.claude.com/docs/en/agent-sdk/hosting.md)\n\n* The subprocess model\n  * State that lives on local disk\n* Choose a session pattern\n  * Ephemeral sessions\n  * Long-running sessions\n  * Hybrid sessions\n  * Multi-agent container\n* Provision the container\n  * Container-based sandboxing\n  * Runtime dependencies\n  * Resources\n  * Network\n* Handle production concerns\n  * Session and state persistence\n  * Observability\n  * Auth and secrets\n  * Scaling and concurrency\n  * Cost\n  * Multi-tenant isolation\n* Known limitations\n* Next steps\n\n### [secure-deployment](https://code.claude.com/docs/en/agent-sdk/secure-deployment.md)\n\n* Threat model\n* Built-in security features\n* Security principles\n  * Security boundaries\n  * Least privilege\n  * Defense in depth\n* Isolation technologies\n  * Sandbox runtime\n  * Containers\n  * gVisor\n  * Virtual machines\n  * Cloud deployments\n* Credential management\n  * The proxy pattern\n  * Configuring Claude Code to use a proxy\n  * Implementing a proxy\n  * Credentials for other services\n    * Custom tools\n    * Traffic forwarding\n* Filesystem configuration\n  * Read-only code mounting\n  * Writable locations\n* Further reading\n\n## SDK references\n\n### [typescript](https://code.claude.com/docs/en/agent-sdk/typescript.md)\n\n* Installation\n  * Compile to a single executable\n* Functions\n  * `query()`\n    * Parameters\n    * Returns\n  * `startup()`\n    * Parameters\n    * Returns\n    * Example\n  * `tool()`\n    * Parameters\n    * `ToolAnnotations`\n  * `createSdkMcpServer()`\n    * Parameters\n  * `listSessions()`\n    * Parameters\n    * Return type: `SDKSessionInfo`\n    * Example\n  * `getSessionMessages()`\n    * Parameters\n    * Return type: `SessionMessage`\n    * Example\n  * `getSessionInfo()`\n    * Parameters\n  * `renameSession()`\n    * Parameters\n  * `tagSession()`\n    * Parameters\n  * `resolveSettings()`\n    * Parameters\n    * Return type: `ResolvedSettings`\n    * Example\n* Types\n  * `Options`\n    * Handle slow or stalled API responses\n  * `Query` object\n    * Methods\n    * `applyFlagSettings()`\n  * `WarmQuery`\n    * Methods\n  * `SDKControlInitializeResponse`\n  * `SDKControlInterruptResponse`\n  * `AgentDefinition`\n  * `AgentMcpServerSpec`\n  * `SettingSource`\n    * Default behavior\n    * Why use settingSources\n    * Settings precedence\n  * `PermissionMode`\n  * `CanUseTool`\n  * `PermissionResult`\n  * `ToolConfig`\n  * `McpServerConfig`\n    * `McpStdioServerConfig`\n    * `McpSSEServerConfig`\n    * `McpHttpServerConfig`\n    * `McpSdkServerConfigWithInstance`\n    * `McpClaudeAIProxyServerConfig`\n  * `SdkPluginConfig`\n* Message Types\n  * `SDKMessage`\n  * `SDKAssistantMessage`\n  * `SDKUserMessage`\n  * `SDKUserMessageReplay`\n  * `SDKResultMessage`\n  * `SDKSystemMessage`\n  * `SDKPartialAssistantMessage`\n  * `SDKCompactBoundaryMessage`\n  * `SDKInformationalMessage`\n  * `SDKWorkerShuttingDownMessage`\n  * `SDKPluginInstallMessage`\n  * `SDKPermissionDeniedMessage`\n  * `SDKPermissionDenial`\n  * `SDKMessageOrigin`\n* Hook Types\n  * `HookEvent`\n  * `HookCallback`\n  * `HookCallbackMatcher`\n  * `HookInput`\n  * `BaseHookInput`\n    * `PreToolUseHookInput`\n    * `PostToolUseHookInput`\n    * `PostToolUseFailureHookInput`\n    * `PostToolBatchHookInput`\n    * `NotificationHookInput`\n    * `UserPromptSubmitHookInput`\n    * `SessionStartHookInput`\n    * `SessionEndHookInput`\n    * `StopHookInput`\n    * `SubagentStartHookInput`\n    * `SubagentStopHookInput`\n    * `PreCompactHookInput`\n    * `PermissionRequestHookInput`\n    * `SetupHookInput`\n    * `TeammateIdleHookInput`\n    * `TaskCompletedHookInput`\n    * `ConfigChangeHookInput`\n    * `WorktreeCreateHookInput`\n    * `WorktreeRemoveHookInput`\n    * `MessageDisplayHookInput`\n  * `HookJSONOutput`\n    * `AsyncHookJSONOutput`\n    * `SyncHookJSONOutput`\n* Tool Input Types\n  * `ToolInputSchemas`\n  * Agent\n  * AskUserQuestion\n  * Bash\n  * Monitor\n  * TaskOutput\n  * Edit\n  * Read\n  * Write\n  * Glob\n  * Grep\n  * TaskStop\n  * NotebookEdit\n  * WebFetch\n  * WebSearch\n  * Workflow\n  * TodoWrite\n  * TaskCreate\n  * TaskUpdate\n  * TaskGet\n  * TaskList\n  * ExitPlanMode\n  * ListMcpResources\n  * ReadMcpResource\n  * EnterWorktree\n* Tool Output Types\n  * `ToolOutputSchemas`\n  * Agent\n  * AskUserQuestion\n  * Bash\n  * Monitor\n  * Edit\n  * Read\n  * Write\n  * Glob\n  * Grep\n  * TaskStop\n  * NotebookEdit\n  * WebFetch\n  * WebSearch\n  * Workflow\n  * TodoWrite\n  * TaskCreate\n  * TaskUpdate\n  * TaskGet\n  * TaskList\n  * ExitPlanMode\n  * ListMcpResources\n  * ReadMcpResource\n  * EnterWorktree\n* Permission Types\n  * `PermissionUpdate`\n  * `PermissionBehavior`\n  * `PermissionUpdateDestination`\n  * `PermissionRuleValue`\n* Other Types\n  * `ApiKeySource`\n  * `SdkBeta`\n  * `SlashCommand`\n  * `ModelInfo`\n  * `AgentInfo`\n  * `McpServerStatus`\n  * `McpServerStatusConfig`\n  * `AccountInfo`\n  * `ModelUsage`\n  * `ConfigScope`\n  * `NonNullableUsage`\n  * `Usage`\n  * `CallToolResult`\n  * `ThinkingConfig`\n  * `SpawnedProcess`\n  * `SpawnOptions`\n  * `McpSetServersResult`\n  * `RewindFilesResult`\n  * `SDKStatusMessage`\n  * `SDKTaskNotificationMessage`\n  * `SDKToolUseSummaryMessage`\n  * `SDKHookStartedMessage`\n  * `SDKHookProgressMessage`\n  * `SDKHookResponseMessage`\n  * `SDKToolProgressMessage`\n  * `SDKAuthStatusMessage`\n  * `SDKTaskStartedMessage`\n  * `SDKTaskProgressMessage`\n  * `SDKTaskUpdatedMessage`\n  * `SDKBackgroundTasksChangedMessage`\n  * `SDKFilesPersistedEvent`\n  * `SDKRateLimitEvent`\n  * `SDKLocalCommandOutputMessage`\n  * `SDKCommandsChangedMessage`\n  * `SDKPromptSuggestionMessage`\n  * `SDKConversationResetMessage`\n  * `AbortError`\n* Sandbox Configuration\n  * `SandboxSettings`\n    * Example usage\n  * `SandboxNetworkConfig`\n  * `SandboxFilesystemConfig`\n  * Permissions Fallback for Unsandboxed Commands\n* See also\n\n### [typescript-v2-preview](https://code.claude.com/docs/en/agent-sdk/typescript-v2-preview.md)\n\n* Installation\n* Quick start\n  * One-shot prompt\n  * Basic session\n  * Multi-turn conversation\n  * Session resume\n  * Cleanup\n* API reference\n  * `unstable_v2_createSession()`\n  * `unstable_v2_resumeSession()`\n  * `unstable_v2_prompt()`\n  * SDKSession interface\n* Feature availability\n* See also\n\n### [python](https://code.claude.com/docs/en/agent-sdk/python.md)\n\n* Installation\n* Choosing between `query()` and `ClaudeSDKClient`\n  * Quick comparison\n  * When to use `query()` (one-off tasks)\n  * When to use `ClaudeSDKClient` (continuous conversation)\n* Functions\n  * `query()`\n    * Parameters\n    * Returns\n    * Example - With options\n  * `tool()`\n    * Parameters\n    * Input schema options\n    * Returns\n    * Example\n    * `ToolAnnotations`\n  * `create_sdk_mcp_server()`\n    * Parameters\n    * Returns\n    * Example\n  * `list_sessions()`\n    * Parameters\n    * Return type: `SDKSessionInfo`\n    * Example\n  * `get_session_messages()`\n    * Parameters\n    * Return type: `SessionMessage`\n    * Example\n  * `get_session_info()`\n    * Parameters\n    * Example\n  * `rename_session()`\n    * Parameters\n    * Example\n  * `tag_session()`\n    * Parameters\n    * Example\n* Classes\n  * `ClaudeSDKClient`\n    * Key Features\n    * Methods\n    * Context Manager Support\n    * Example - Continuing a conversation\n    * Example - Streaming input with ClaudeSDKClient\n    * Example - Using interrupts\n    * Example - Advanced permission control\n* Types\n  * `SdkMcpTool`\n  * `Transport`\n  * `ClaudeAgentOptions`\n    * Handle slow or stalled API responses\n  * `OutputFormat`\n  * `SystemPromptPreset`\n  * `SystemPromptFile`\n  * `SettingSource`\n    * Default behavior\n    * Why use setting\\_sources\n    * Settings precedence\n  * `AgentDefinition`\n  * `PermissionMode`\n  * `EffortLevel`\n  * `CanUseTool`\n  * `ToolPermissionContext`\n  * `PermissionResult`\n  * `PermissionResultAllow`\n  * `PermissionResultDeny`\n  * `PermissionUpdate`\n  * `PermissionRuleValue`\n  * `ToolsPreset`\n  * `ThinkingConfig`\n  * `SdkBeta`\n  * `McpSdkServerConfig`\n  * `McpServerConfig`\n    * `McpStdioServerConfig`\n    * `McpSSEServerConfig`\n    * `McpHttpServerConfig`\n  * `McpServerStatusConfig`\n  * `McpStatusResponse`\n  * `McpServerStatus`\n  * `SdkPluginConfig`\n* Message Types\n  * `Message`\n  * `UserMessage`\n  * `AssistantMessage`\n  * `AssistantMessageError`\n  * `SystemMessage`\n  * `ResultMessage`\n  * `StreamEvent`\n  * `RateLimitEvent`\n  * `RateLimitInfo`\n  * `TaskStartedMessage`\n  * `TaskUsage`\n  * `TaskProgressMessage`\n  * `TaskNotificationMessage`\n* Content Block Types\n  * `ContentBlock`\n  * `TextBlock`\n  * `ThinkingBlock`\n  * `ToolUseBlock`\n  * `ToolResultBlock`\n* Error Types\n  * `ClaudeSDKError`\n  * `CLINotFoundError`\n  * `CLIConnectionError`\n  * `ProcessError`\n  * `CLIJSONDecodeError`\n* Hook Types\n  * `HookEvent`\n  * `HookCallback`\n  * `HookContext`\n  * `HookMatcher`\n  * `HookInput`\n  * `BaseHookInput`\n  * `PreToolUseHookInput`\n  * `PostToolUseHookInput`\n  * `PostToolUseFailureHookInput`\n  * `UserPromptSubmitHookInput`\n  * `StopHookInput`\n  * `SubagentStopHookInput`\n  * `PreCompactHookInput`\n  * `NotificationHookInput`\n  * `SubagentStartHookInput`\n  * `PermissionRequestHookInput`\n  * `HookJSONOutput`\n    * `SyncHookJSONOutput`\n    * `HookSpecificOutput`\n    * `AsyncHookJSONOutput`\n  * Hook Usage Example\n* Tool Input/Output Types\n  * Agent\n  * AskUserQuestion\n  * Bash\n  * Monitor\n  * Edit\n  * Read\n  * Write\n  * Glob\n  * Grep\n  * NotebookEdit\n  * WebFetch\n  * WebSearch\n  * TodoWrite\n  * TaskCreate\n  * TaskUpdate\n  * TaskGet\n  * TaskList\n  * BashOutput\n  * KillBash\n  * ExitPlanMode\n  * ListMcpResources\n  * ReadMcpResource\n* Advanced Features with ClaudeSDKClient\n  * Building a Continuous Conversation Interface\n  * Using Hooks for Behavior Modification\n  * Real-time Progress Monitoring\n* Example Usage\n  * Basic file operations (using query)\n  * Error handling\n  * Streaming mode with client\n  * Using custom tools with ClaudeSDKClient\n* Sandbox Configuration\n  * `SandboxSettings`\n    * Example usage\n  * `SandboxNetworkConfig`\n  * `SandboxIgnoreViolations`\n  * Permissions Fallback for Unsandboxed Commands\n* See also\n\n### [migration-guide](https://code.claude.com/docs/en/agent-sdk/migration-guide.md)\n\n* Overview\n* What's Changed\n* Migration Steps\n  * For TypeScript/JavaScript Projects\n  * For Python Projects\n* Breaking changes\n  * Python: ClaudeCodeOptions renamed to ClaudeAgentOptions\n  * System prompt no longer default\n  * Settings sources default\n* Why the Rename?\n* Getting Help\n* Next Steps\n\n## What's New\n\n### [index](https://code.claude.com/docs/en/whats-new/index.md)\n\n* (No headings found)\n\n### [2026-w28](https://code.claude.com/docs/en/whats-new/2026-w28.md)\n\n* (No headings found)\n\n### [2026-w27](https://code.claude.com/docs/en/whats-new/2026-w27.md)\n\n* (No headings found)\n\n### [2026-w26](https://code.claude.com/docs/en/whats-new/2026-w26.md)\n\n* (No headings found)\n\n### [2026-w25](https://code.claude.com/docs/en/whats-new/2026-w25.md)\n\n* (No headings found)\n\n### [2026-w24](https://code.claude.com/docs/en/whats-new/2026-w24.md)\n\n* (No headings found)\n\n### [2026-w23](https://code.claude.com/docs/en/whats-new/2026-w23.md)\n\n* (No headings found)\n\n### [2026-w22](https://code.claude.com/docs/en/whats-new/2026-w22.md)\n\n* (No headings found)\n\n### [2026-w21](https://code.claude.com/docs/en/whats-new/2026-w21.md)\n\n* (No headings found)\n\n### [2026-w20](https://code.claude.com/docs/en/whats-new/2026-w20.md)\n\n* (No headings found)\n\n### [2026-w19](https://code.claude.com/docs/en/whats-new/2026-w19.md)\n\n* (No headings found)\n\n### [2026-w18](https://code.claude.com/docs/en/whats-new/2026-w18.md)\n\n* (No headings found)\n\n### [2026-w17](https://code.claude.com/docs/en/whats-new/2026-w17.md)\n\n* (No headings found)\n\n### [2026-w16](https://code.claude.com/docs/en/whats-new/2026-w16.md)\n\n* (No headings found)\n\n### [2026-w15](https://code.claude.com/docs/en/whats-new/2026-w15.md)\n\n* (No headings found)\n\n### [2026-w14](https://code.claude.com/docs/en/whats-new/2026-w14.md)\n\n* (No headings found)\n\n### [2026-w13](https://code.claude.com/docs/en/whats-new/2026-w13.md)\n\n* (No headings found)\n\n## Resources\n\n### [legal-and-compliance](https://code.claude.com/docs/en/legal-and-compliance.md)\n\n* Legal agreements\n  * License\n  * Commercial agreements\n* Compliance\n  * Healthcare compliance (BAA)\n* Usage policy\n  * Acceptable use\n  * Authentication and credential use\n* Security and trust\n  * Trust and safety\n  * Security vulnerability reporting\n","durationMs":637,"url":"https://code.claude.com/docs/en/claude_code_docs_map.md"},"sourceToolAssistantUUID":"482730bf-691c-493d-b299-63dd9a469a8a","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"22abdd21-ff9f-4aac-9b70-c4bbfca3755d","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4MdfTQJY4ZwGiAg7As","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"","signature":"EuIECpMBCA8YAipAU8z7l0hbBNtVGWvQzem5Hm8QUIMYM6TLS9P7737zBHUq3LUQa/JxB28/JSAOFpYw4bIg/Of7dja1SbD/vqUYFDIZY2xhdWRlLWhhaWt1LTQtNS0yMDI1MTAwMTgAQgh0aGlua2luZ1okNGJkZDE1Y2MtNDcxZS00ZTU2LWJhMWEtM2QzZDViNGYwMTdjEgxLlW0T3xiByuQRbLUaDGS/GSWs9IX3kvK8sCIwX1xbwTMY8XmWKWYf4ybonrv6KoTldCvj5QO/UBeVnHGNZuFGgE7QlwERc9cQlaFSKvsCxALBX5iby1XzSGd5wxfgsEz/nB9U0C+yt4pjt88+ILuTiWvULKZizcNkm51lMASeNF5hjzKoCrg6VuwRlK8rtZSDA7krYTt27Xlinsc6IJm0Ut/qMCAsd3gltkRLweMF/NLQ9GWiJca4S7VJObD4BH2QdGRU/KCKcTRZb0k3i0X760NxFk1JXb4udv/9ww8qg4ATKwmBfQoTwBlC4NbmfxAdKkMzGysOvaVI3bIirIy/6T1jhFLVig5UU40bvvSDUACLMhhjtiqyPclfYQ804yorMeOnYkzmo42BmRRQSnuNDHXYTM9Iz0hBX9ixKQFLx4/ph/aGNSH7g2T2siP5TNF+8N5LLjq2LYmo95DtGPtEM6cOyZ4Ziecj2K4aZ1Sdg/2Gu1DXOxlB0Uw1DmCchS13sQGW7OK2WuvN6NDglVXCvoSXKx70VMUF4hIB8P+w9dggZrav4OpbPT8tECkscaY+xB6cDdX+QcbfKlN7MAVWKBA8mlnBBoT1ORgB"}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":1188,"cache_read_input_tokens":13556,"cache_creation":{"ephemeral_5m_input_tokens":1188,"ephemeral_1h_input_tokens":0},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011Ccv4McbCyjx6miuyd29v6","attributionAgent":"claude-code-guide","type":"assistant","uuid":"ff141756-4df9-4194-9a9d-19430e982ea9","timestamp":"2026-07-11T09:47:34.161Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"ff141756-4df9-4194-9a9d-19430e982ea9","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4MdfTQJY4ZwGiAg7As","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_0184rLFmTHckR3643fDTPPw1","name":"Bash","input":{"command":"grep -i \"mcp\\|server\\|\\.claude\\.json\\|permission\" /Users/marcus.hinz/.config/ai-control/pools/private/projects/-Users-marcus-hinz-claude-projects-ai-control/f7704328-4eb4-4f0f-bf42-da68abab401d/tool-results/toolu_01Jpn4YmQ9TMVMPYEKuVh7QN.txt | head -50"},"caller":{"type":"direct"}}],"stop_reason":"tool_use","stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":1188,"cache_read_input_tokens":13556,"output_tokens":262,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":1188},"inference_geo":"not_available","iterations":[{"input_tokens":8,"output_tokens":262,"cache_read_input_tokens":13556,"cache_creation_input_tokens":1188,"cache_creation":{"ephemeral_5m_input_tokens":1188,"ephemeral_1h_input_tokens":0},"type":"message"}],"speed":"standard"},"diagnostics":null},"requestId":"req_011Ccv4McbCyjx6miuyd29v6","attributionAgent":"claude-code-guide","type":"assistant","uuid":"b51a3f5e-ec3b-47f0-96ec-4f01800c7a8a","timestamp":"2026-07-11T09:47:35.001Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"b51a3f5e-ec3b-47f0-96ec-4f01800c7a8a","isSidechain":true,"promptId":"463e84b3-536f-432f-b32a-4fdae6dbed7a","agentId":"a556d2e38a847bf6e","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_0184rLFmTHckR3643fDTPPw1","type":"tool_result","content":"* Stay safe with checkpoints and permissions\n  * Connecting or disconnecting an MCP server\n  * Changing permission mode\n### [permission-modes](https://code.claude.com/docs/en/permission-modes.md)\n* Switch permission modes\n* Eliminate permission prompts with auto mode\n* Skip all checks with bypassPermissions mode\n  * Configure permissions\n  * Connect MCP servers\n  * Repositories and branch permissions\n  * Choose a permission mode\n  * App permissions\n  * Configure preview servers\n  * MCP servers not working on Windows\n* Permissions for scheduled tasks\n#### [github-enterprise-server](https://code.claude.com/docs/en/github-enterprise-server.md)\n* What works with GitHub Enterprise Server\n  * GitHub App permissions\n  * Manage site permissions\n  * macOS permissions prompt keeps reappearing\n  * `computer-use` doesn't appear in `/mcp`\n  * Connect to external tools with MCP\n  * The built-in IDE MCP server\n* Access and permissions\n    * Scope MCP servers to a subagent\n    * Permission modes\n  * Permission mode, model, and effort\n  * Settings, plugins, and MCP servers\n  * Permissions\n  * Too many permission prompts\n## MCP\n### [mcp-quickstart](https://code.claude.com/docs/en/mcp-quickstart.md)\n* Add and verify a server\n* Where servers are saved\n* Change server scope\n  * Use a server in all your projects\n  * Share a server with your team\n* Additional MCP server examples\n  * Add a local server\n  * Connect a server that requires sign-in\n* Edit .mcp.json directly\n### [mcp](https://code.claude.com/docs/en/mcp.md)\n* What you can do with MCP\n* Find and build MCP servers\n* Installing MCP servers\n  * Option 1: Add a remote HTTP server\n  * Option 2: Add a remote SSE server\n  * Option 3: Add a local stdio server\n  * Option 4: Add a remote WebSocket server\n  * Managing your servers","is_error":false}]},"uuid":"2380ab40-4882-4f28-859e-8c93bd2ef0d1","timestamp":"2026-07-11T09:47:35.139Z","toolUseResult":{"stdout":"* Stay safe with checkpoints and permissions\n  * Connecting or disconnecting an MCP server\n  * Changing permission mode\n### [permission-modes](https://code.claude.com/docs/en/permission-modes.md)\n* Switch permission modes\n* Eliminate permission prompts with auto mode\n* Skip all checks with bypassPermissions mode\n  * Configure permissions\n  * Connect MCP servers\n  * Repositories and branch permissions\n  * Choose a permission mode\n  * App permissions\n  * Configure preview servers\n  * MCP servers not working on Windows\n* Permissions for scheduled tasks\n#### [github-enterprise-server](https://code.claude.com/docs/en/github-enterprise-server.md)\n* What works with GitHub Enterprise Server\n  * GitHub App permissions\n  * Manage site permissions\n  * macOS permissions prompt keeps reappearing\n  * `computer-use` doesn't appear in `/mcp`\n  * Connect to external tools with MCP\n  * The built-in IDE MCP server\n* Access and permissions\n    * Scope MCP servers to a subagent\n    * Permission modes\n  * Permission mode, model, and effort\n  * Settings, plugins, and MCP servers\n  * Permissions\n  * Too many permission prompts\n## MCP\n### [mcp-quickstart](https://code.claude.com/docs/en/mcp-quickstart.md)\n* Add and verify a server\n* Where servers are saved\n* Change server scope\n  * Use a server in all your projects\n  * Share a server with your team\n* Additional MCP server examples\n  * Add a local server\n  * Connect a server that requires sign-in\n* Edit .mcp.json directly\n### [mcp](https://code.claude.com/docs/en/mcp.md)\n* What you can do with MCP\n* Find and build MCP servers\n* Installing MCP servers\n  * Option 1: Add a remote HTTP server\n  * Option 2: Add a remote SSE server\n  * Option 3: Add a local stdio server\n  * Option 4: Add a remote WebSocket server\n  * Managing your servers","stderr":"","interrupted":false,"isImage":false,"noOutputExpected":false},"sourceToolAssistantUUID":"b51a3f5e-ec3b-47f0-96ec-4f01800c7a8a","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"2380ab40-4882-4f28-859e-8c93bd2ef0d1","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4MtzguCEMnMDNER7HF","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"","signature":"EooDCpMBCA8YAipAEOH698fjEOfMcrxMpij7VFQFyDTcAB6yqKQC1OTUzGHjGT85x+Q2vFsW70vcObgZsY1CZ+sbQ1EsYxslEatyyDIZY2xhdWRlLWhhaWt1LTQtNS0yMDI1MTAwMTgAQgh0aGlua2luZ1okNGJkZDE1Y2MtNDcxZS00ZTU2LWJhMWEtM2QzZDViNGYwMTdjEgyR0rmTBH8/rLoQrMYaDNJ4L9Iq7p33Stf+wCIw0EYNrdURTKW6PogtrjxMqGYqta4tfye0l477KIxd6fyNb92AwYYQ/EpXCn8vhs+gKqMBTYHn+11W0RV21PcsgFb2QS6JjFfP0pXwfmKec4U7FzSoIO7ZnEOzTKyv6l+4mibfGid84DY5s8VXMhMAxm69+4qcJ2NqgoiOKAoSmgmzl1BLcnTeGxljPUSwJo9MjGyA09loEw9oODXjVbZ69QgS52G+VdcXY6oubSJzdHgxkvRUZJLo2pUo8mtQTSuMzrbQ4U9qG0YwRpJUipFTyLMDluVRcRgB"}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":775,"cache_read_input_tokens":14744,"cache_creation":{"ephemeral_5m_input_tokens":775,"ephemeral_1h_input_tokens":0},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011Ccv4MsWtWLStKHVUonHHN","attributionAgent":"claude-code-guide","type":"assistant","uuid":"d5b176f1-10e6-4a22-b7fe-9dce06b9b519","timestamp":"2026-07-11T09:47:37.030Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"d5b176f1-10e6-4a22-b7fe-9dce06b9b519","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4MtzguCEMnMDNER7HF","type":"message","role":"assistant","content":[{"type":"text","text":"Now let me fetch the specific MCP and permissions documentation pages:"}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":775,"cache_read_input_tokens":14744,"cache_creation":{"ephemeral_5m_input_tokens":775,"ephemeral_1h_input_tokens":0},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011Ccv4MsWtWLStKHVUonHHN","attributionAgent":"claude-code-guide","type":"assistant","uuid":"eb96317f-cd30-46a7-ba95-abc06f3f5e3b","timestamp":"2026-07-11T09:47:37.436Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"eb96317f-cd30-46a7-ba95-abc06f3f5e3b","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4MtzguCEMnMDNER7HF","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01Q2ptd16CDNgtErxF65F6qu","name":"WebFetch","input":{"url":"https://code.claude.com/docs/en/mcp.md","prompt":"stdio MCP server, .claude.json, user scope, project scope, .mcp.json, trust, approval, permissions"},"caller":{"type":"direct"}}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":775,"cache_read_input_tokens":14744,"cache_creation":{"ephemeral_5m_input_tokens":775,"ephemeral_1h_input_tokens":0},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011Ccv4MsWtWLStKHVUonHHN","attributionAgent":"claude-code-guide","type":"assistant","uuid":"2c61bd93-5688-4486-a515-a82eb1fe86f8","timestamp":"2026-07-11T09:47:38.158Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"2c61bd93-5688-4486-a515-a82eb1fe86f8","isSidechain":true,"promptId":"463e84b3-536f-432f-b32a-4fdae6dbed7a","agentId":"a556d2e38a847bf6e","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01Q2ptd16CDNgtErxF65F6qu","type":"tool_result","content":"<persisted-output>\nOutput too large (63.7KB). Full output saved to: /Users/marcus.hinz/.config/ai-control/pools/private/projects/-Users-marcus-hinz-claude-projects-ai-control/f7704328-4eb4-4f0f-bf42-da68abab401d/tool-results/toolu_01Q2ptd16CDNgtErxF65F6qu.txt\n\nPreview (first 2KB):\n> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Connect Claude Code to tools via MCP\n\n> Learn how to connect Claude Code to your tools with the Model Context Protocol.\n\nClaude Code can connect to hundreds of external tools and data sources through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open source standard for AI-tool integrations. MCP servers give Claude Code access to your tools, databases, and APIs.\n\nConnect a server when you find yourself copying data into chat from another tool, like an issue tracker or a monitoring dashboard. Once connected, Claude can read and act on that system directly instead of working from what you paste.\n\nIf you're connecting your first server, start with the [MCP quickstart](/en/mcp-quickstart) for a step-by-step walkthrough. This page is the full reference.\n\n## What you can do with MCP\n\nWith MCP servers connected, you can ask Claude Code to:\n\n* **Implement features from issue trackers**: \"Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub.\"\n* **Analyze monitoring data**: \"Check Sentry and Statsig to check the usage of the feature described in ENG-4521.\"\n* **Query databases**: \"Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database.\"\n* **Integrate designs**: \"Update our standard email template based on the new Figma designs that were posted in Slack\"\n* **Automate workflows**: \"Create Gmail drafts inviting these 10 users to a feedback session about the new feature.\"\n* **React to external events**: an MCP server can also act as a [channel](/en/channels) that pushes messages into your session, so Claude reacts to Telegram messages, Discord chats, or webhook events while you're away.\n\n## Find and build MCP servers\n\n...\n</persisted-output>"}]},"uuid":"24cbf5d2-f913-400a-adfe-3d70d850099d","timestamp":"2026-07-11T09:47:38.574Z","toolUseResult":{"bytes":65223,"code":200,"codeText":"OK","result":"> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Connect Claude Code to tools via MCP\n\n> Learn how to connect Claude Code to your tools with the Model Context Protocol.\n\nClaude Code can connect to hundreds of external tools and data sources through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open source standard for AI-tool integrations. MCP servers give Claude Code access to your tools, databases, and APIs.\n\nConnect a server when you find yourself copying data into chat from another tool, like an issue tracker or a monitoring dashboard. Once connected, Claude can read and act on that system directly instead of working from what you paste.\n\nIf you're connecting your first server, start with the [MCP quickstart](/en/mcp-quickstart) for a step-by-step walkthrough. This page is the full reference.\n\n## What you can do with MCP\n\nWith MCP servers connected, you can ask Claude Code to:\n\n* **Implement features from issue trackers**: \"Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub.\"\n* **Analyze monitoring data**: \"Check Sentry and Statsig to check the usage of the feature described in ENG-4521.\"\n* **Query databases**: \"Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database.\"\n* **Integrate designs**: \"Update our standard email template based on the new Figma designs that were posted in Slack\"\n* **Automate workflows**: \"Create Gmail drafts inviting these 10 users to a feedback session about the new feature.\"\n* **React to external events**: an MCP server can also act as a [channel](/en/channels) that pushes messages into your session, so Claude reacts to Telegram messages, Discord chats, or webhook events while you're away.\n\n## Find and build MCP servers\n\nBrowse reviewed connectors in the [Anthropic Directory](https://claude.ai/directory). Directory connectors use the same MCP infrastructure as Claude Code, so you can add any remote server listed there with `claude mcp add`.\n\n<Warning>\n  Verify you trust each server before connecting it. Servers that fetch external content can expose you to [prompt injection risk](/en/security#protect-against-prompt-injection).\n</Warning>\n\nTo build your own server, see the [MCP server guide](https://modelcontextprotocol.io/docs/develop/build-server) for protocol fundamentals and the [Claude connector building docs](https://claude.com/docs/connectors/building) for authentication, testing, and Directory submission.\n\nYou can also have Claude scaffold a server for you with the official [`mcp-server-dev` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev).\n\n<Steps>\n  <Step title=\"Install the plugin\">\n    In a Claude Code session, run:\n\n    ```\n    /plugin install mcp-server-dev@claude-plugins-official\n    ```\n\n    If Claude Code reports that the marketplace is not found, run `/plugin marketplace add anthropics/claude-plugins-official` first, then retry the install. Once installed, run `/reload-plugins` to activate it in the current session.\n  </Step>\n\n  <Step title=\"Run the build skill\">\n    ```\n    /mcp-server-dev:build-mcp-server\n    ```\n\n    Claude asks about your use case and scaffolds a remote HTTP or local stdio server.\n  </Step>\n</Steps>\n\n## Installing MCP servers\n\nMCP servers can be configured in several ways depending on your needs:\n\n### Option 1: Add a remote HTTP server\n\nHTTP servers are the recommended option for connecting to remote MCP servers. This is the most widely supported transport for cloud-based services.\n\n```bash theme={null}\n# Basic syntax\nclaude mcp add --transport http <name> <url>\n\n# Real example: Connect to Notion\nclaude mcp add --transport http notion https://mcp.notion.com/mcp\n\n# Example with Bearer token\nclaude mcp add --transport http secure-api https://api.example.com/mcp \\\n  --header \"Authorization: Bearer your-token\"\n```\n\nWhen configuring MCP servers via JSON in `.mcp.json`, `~/.claude.json`, or `claude mcp add-json`, the `type` field accepts `streamable-http` as an alias for `http`. The MCP specification uses the name `streamable-http` for this transport, so configurations copied from server documentation work without modification.\n\nA JSON entry that has a `url` but no `type` is a configuration error, because Claude Code reads an entry with no `type` as a stdio server. Claude Code skips that server and reports `MCP server \"<name>\" has a \"url\" but no \"type\"; add \"type\": \"http\" (or \"sse\" / \"ws\") to this entry`. Before v2.1.202, Claude Code reported this misconfiguration as `command: expected string, received undefined`.\n\n### Option 2: Add a remote SSE server\n\n<Warning>\n  The SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead, where available.\n</Warning>\n\n```bash theme={null}\n# Basic syntax\nclaude mcp add --transport sse <name> <url>\n\n# Real example: Connect to Asana\nclaude mcp add --transport sse asana https://mcp.asana.com/sse\n\n# Example with authentication header\nclaude mcp add --transport sse private-api https://api.company.com/sse \\\n  --header \"X-API-Key: your-key-here\"\n```\n\n### Option 3: Add a local stdio server\n\nStdio servers run as local processes on your machine. They're ideal for tools that need direct system access or custom scripts.\n\nClaude Code sets `CLAUDE_PROJECT_DIR` in the spawned server's environment to the project root, so your server can resolve project-relative paths without depending on the working directory. This is the same directory hooks receive in their `CLAUDE_PROJECT_DIR` variable. Read it from inside your server process, for example `process.env.CLAUDE_PROJECT_DIR` in Node or `os.environ[\"CLAUDE_PROJECT_DIR\"]` in Python.\n\n`CLAUDE_PROJECT_DIR` is the stable project root and doesn't change when you add or remove working directories mid-session. A server that limits its own filesystem access to a set of allowed directories should implement the MCP `roots/list` request instead. Claude Code answers `roots/list` with the session's launch directory plus every [additional working directory](/en/permissions#working-directories) you've granted with `--add-dir`, `/add-dir`, or the `additionalDirectories` setting. Claude Code sends `notifications/roots/list_changed` when that set changes. Before v2.1.203, `roots/list` returned only the launch directory and Claude Code didn't send `notifications/roots/list_changed`.\n\nThis variable is set in the server's environment, not in Claude Code's own environment, so referencing it via `${VAR}` expansion in a project- or user-scoped `.mcp.json` `command` or `args` requires a default such as `${CLAUDE_PROJECT_DIR:-.}`. Plugin-provided MCP configurations substitute `${CLAUDE_PROJECT_DIR}` directly and don't need the default.\n\n```bash theme={null}\n# Basic syntax\nclaude mcp add [options] <name> -- <command> [args...]\n\n# Real example: Add Airtable server\nclaude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \\\n  -- npx -y airtable-mcp-server\n```\n\n<Note>\n  **Important: Separate server arguments with `--`**\n\n  For stdio servers, the `--` (double dash) separates Claude's own options, such as `--transport`, `--env`, and `--scope`, from the command and arguments that run the server. Everything after `--` is passed to the server untouched.\n\n  For example:\n\n  * `claude mcp add --transport stdio myserver -- npx server` → runs `npx server`\n  * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → runs `python server.py --port 8080` with `KEY=value` in environment\n\n  Without `--`, Claude Code would try to parse the server's flags, like `--port` above, as its own options.\n\n  `--env` accepts multiple `KEY=value` pairs. If the server name comes directly after `--env`, the CLI reads the name as another pair and rejects it, so place at least one other option between `--env` and the server name, as in the examples above.\n</Note>\n\n### Option 4: Add a remote WebSocket server\n\nWebSocket servers hold a persistent bidirectional connection, which suits remote MCP servers that push events to Claude unprompted. Use HTTP instead when your server only responds to requests, since HTTP supports OAuth and the `claude mcp add --transport` flag, while WebSocket supports neither.\n\nConfigure WebSocket servers in `.mcp.json` or with `claude mcp add-json`:\n\n```bash theme={null}\nclaude mcp add-json events-server \\\n  '{\"type\":\"ws\",\"url\":\"wss://mcp.example.com/socket\",\"headers\":{\"Authorization\":\"Bearer YOUR_TOKEN\"}}'\n```\n\nThe `type: \"ws\"` entry accepts the same `url`, `headers`, `headersHelper`, `timeout`, and `alwaysLoad` fields as `http`. Authentication is header-only, so pass a static token in `headers` or generate one at connect time with [`headersHelper`](#use-dynamic-headers-for-custom-authentication). The `claude mcp add --transport` flag doesn't accept `ws`.\n\n### Managing your servers\n\nOnce configured, you can manage your MCP servers with these commands:\n\n```bash theme={null}\n# List all configured servers\nclaude mcp list\n\n# Get details for a specific server\nclaude mcp get github\n\n# Remove a server\nclaude mcp remove github\n\n# (within Claude Code) Check server status\n/mcp\n```\n\nProject-scoped servers from `.mcp.json` that are awaiting your approval appear in `claude mcp list` as `⏸ Pending approval`. Run `claude` interactively to review and approve them. `claude mcp get <name>` shows pending servers as `⏸ Pending approval` and rejected servers as `✗ Rejected`.\n\nAs of v2.1.196, `claude mcp list` and `claude mcp get` read `.mcp.json` approvals only from settings files that aren't checked into the repository until you trust the workspace by running `claude` in it and accepting the workspace trust dialog. A cloned repository can't approve its own servers: [`enableAllProjectMcpServers` or `enabledMcpjsonServers`](/en/settings#available-settings) committed to the project's `.claude/settings.json` is ignored in an untrusted folder, and the server stays at `⏸ Pending approval` instead of being connected and health-checked.\n\nApprovals from these sources still apply in an untrusted folder:\n\n* your user `~/.claude/settings.json`\n* managed settings\n* settings passed with `--settings`\n* `.claude/settings.local.json`, as long as git doesn't track it\n\nA `disabledMcpjsonServers` entry in any settings file still rejects the server.\n\nThe `/mcp` panel shows the tool count next to each connected server and flags servers that advertise the tools capability but expose no tools.\n\nIf your request needs tools from a server that is still connecting in the background, Claude waits for that server before continuing. With [tool search](#scale-with-mcp-tool-search) enabled, which is the default, the wait happens inside the `ToolSearch` call. In configurations without tool search, such as Google Cloud's Agent Platform, a custom `ANTHROPIC_BASE_URL`, or `ENABLE_TOOL_SEARCH=false`, Claude uses the `WaitForMcpServers` tool instead.\n\nSome server names are reserved for Claude Code's built-in servers: `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview`, and `Claude Browser`. If your configuration defines a server with a reserved name, Claude Code skips it at load time and shows a warning asking you to rename it. `claude mcp add` rejects a reserved name with an error.\n\n`Claude Preview` and `Claude Browser` both name the built-in server that the [Claude Code desktop app's preview pane](/en/desktop#preview-your-app) uses. Before v2.1.205, `Claude Browser` wasn't reserved, so a user-configured server could register under that name.\n\n### Dynamic tool updates\n\nClaude Code supports MCP `list_changed` notifications, allowing MCP servers to dynamically update their available tools, prompts, and resources without requiring you to disconnect and reconnect. When an MCP server sends a `list_changed` notification, Claude Code automatically refreshes the available capabilities from that server.\n\n### Automatic reconnection\n\nIf an HTTP or SSE server disconnects mid-session, Claude Code automatically reconnects with exponential backoff: up to five attempts, starting at a one-second delay and doubling each time. The server appears as pending in `/mcp` while reconnection is in progress. After five failed attempts the server is marked as failed and you can retry manually from `/mcp`. Stdio servers are local processes and are not reconnected automatically.\n\nThe same backoff applies when an HTTP or SSE server fails its initial connection at startup. As of v2.1.121, Claude Code retries the initial connection up to three times on transient errors such as a 5xx response, a connection refused, or a timeout, then marks the server as failed if it still can't connect. Authentication and not-found errors are not retried because they require a configuration change to resolve.\n\nWhen a configured server fails to connect, Claude Code tells Claude which server failed and its connection error, including in `ToolSearch` results that find no matching tool, so Claude reports the connection failure in its response. Requires [tool search](#scale-with-mcp-tool-search), which is enabled by default. In configurations without tool search, such as a custom `ANTHROPIC_BASE_URL`, `ENABLE_TOOL_SEARCH=false`, or a Haiku model, and on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, Claude Code doesn't report failed server connections to Claude. Before v2.1.205, Claude Code didn't pass connection errors to Claude, and Claude could respond as if the failed server's tools were never configured.\n\nAs of v2.1.191, the capability discovery requests that run after a successful connection, such as `tools/list`, `prompts/list`, and `resources/list`, also retry transient network and server errors up to three times with short backoff. Authentication errors, 4xx responses, and request timeouts are not retried.\n\n### Push messages with channels\n\nAn MCP server can also push messages directly into your session so Claude can react to external events like CI results, monitoring alerts, or chat messages. To enable this, your server declares the `claude/channel` capability and you opt it in with the `--channels` flag at startup. See [Channels](/en/channels) to use an officially supported channel, or [Channels reference](/en/channels-reference) to build your own.\n\n<Tip>\n  Tips:\n\n  * Use the `-s` or `--scope` flag to specify where the configuration is stored:\n    * `local` (default): available only to you in the current project. Older versions called this scope `project`\n    * `project`: shared with everyone in the project via the `.mcp.json` file\n    * `user`: available to you across all projects. Older versions called this scope `global`\n  * Set environment variables with `-e` or `--env` flags (for example, `-e KEY=value`)\n  * The `--transport` and `--header` flags also accept `-t` and `-H` short forms\n  * Configure MCP server startup timeout using the `MCP_TIMEOUT` environment variable (for example, `MCP_TIMEOUT=10000 claude` sets a 10-second timeout)\n  * Set a per-server tool execution timeout by adding a `timeout` field in milliseconds to that server's `.mcp.json` entry, for example `\"timeout\": 600000` for ten minutes. This overrides the `MCP_TOOL_TIMEOUT` environment variable for that server only\n  * Claude Code displays a warning when MCP tool output exceeds 10,000 tokens. To increase this limit, set the `MAX_MCP_OUTPUT_TOKENS` environment variable (for example, `MAX_MCP_OUTPUT_TOKENS=50000`)\n  * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication\n</Tip>\n\nThe per-server `timeout` is a hard wall-clock limit per tool call, and progress notifications from the server don't extend it. Values below 1000 are ignored and fall through to `MCP_TOOL_TIMEOUT`, or to its default of about 28 hours when that variable is unset. {/* min-version: 2.1.162 */}Before v2.1.162, values below 1000 were floored to one second instead.\n\nA per-server `timeout` of at least 1000 also acts as a floor on the idle timeout described below: Claude Code never aborts that server's tool calls for idleness sooner than the per-server `timeout`. Requires Claude Code v2.1.203 or later.\n\nFor HTTP and SSE servers, the per-request fetch first-byte budget has a 60-second minimum.\n\nA tool call to an MCP server that sends no response and no progress notification for the idle window aborts with an error instead of waiting for the wall-clock limit. The idle timeout requires Claude Code v2.1.187 or later. {/* min-version: 2.1.203 */}It applies to every server type except IDE servers and SDK in-process servers. The idle window defaults to five minutes for HTTP, SSE, WebSocket, and [claude.ai connector](#use-mcp-servers-from-claude-ai) servers, and to 30 minutes for stdio servers. Before v2.1.203, stdio servers were exempt from the idle timeout.\n\nSet the [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/en/env-vars) environment variable in milliseconds to change the idle window, or set it to `0` to disable the check.\n\n### Plugin-provided MCP servers\n\n[Plugins](/en/plugins) can bundle MCP servers, automatically providing tools and integrations when the plugin is enabled. Plugin MCP servers work identically to user-configured servers.\n\n**How plugin MCP servers work**:\n\n* Plugins define MCP servers in `.mcp.json` at the plugin root or inline in `plugin.json`\n* When a plugin is enabled, its MCP servers start automatically\n* Plugin MCP tools appear alongside manually configured MCP tools\n* Plugin servers are managed through plugin installation, not `/mcp` commands\n\n**Example plugin MCP configuration**:\n\nIn `.mcp.json` at plugin root:\n\n```json theme={null}\n{\n  \"mcpServers\": {\n    \"database-tools\": {\n      \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/db-server\",\n      \"args\": [\"--config\", \"${CLAUDE_PLUGIN_ROOT}/config.json\"],\n      \"env\": {\n        \"DB_URL\": \"${DB_URL}\"\n      }\n    }\n  }\n}\n```\n\nOr inline in `plugin.json`:\n\n```json theme={null}\n{\n  \"name\": \"my-plugin\",\n  \"mcpServers\": {\n    \"plugin-api\": {\n      \"command\": \"${CLAUDE_PLUGIN_ROOT}/servers/api-server\",\n      \"args\": [\"--port\", \"8080\"]\n    }\n  }\n}\n```\n\n**Plugin MCP features**:\n\n* **Automatic lifecycle**: at session startup, servers for enabled plugins connect automatically. If you enable or disable a plugin during a session, run `/reload-plugins` to connect or disconnect its MCP servers\n* **Environment variables**: use `${CLAUDE_PLUGIN_ROOT}` for bundled plugin files, `${CLAUDE_PLUGIN_DATA}` for [persistent state](/en/plugins-reference#persistent-data-directory) that survives plugin updates, and `${CLAUDE_PROJECT_DIR}` for the stable project root\n* **User environment access**: access to the same environment variables as manually configured servers\n* **Multiple transport types**: support for stdio, SSE, HTTP, and WebSocket transports, though transport support may vary by server\n\n**Viewing plugin MCP servers**:\n\n```bash theme={null}\n# Within Claude Code, see all MCP servers including plugin ones\n/mcp\n```\n\nPlugin servers appear in the list with indicators showing they come from plugins.\n\n**Plugin MCP tool names**:\n\nTools from a plugin-bundled MCP server include both the plugin name and the server key in their callable name. The full form is `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`, where any character outside `A-Z`, `a-z`, `0-9`, `_`, and `-` is replaced with `_`. For the `database-tools` server bundled in a plugin named `my-plugin`, a `query` tool is callable as:\n\n```\nmcp__plugin_my-plugin_database-tools__query\n```\n\nUse this full name when referencing the tool in [permission rules](/en/permissions), a skill's `allowed-tools` list, a [subagent's `tools` field](/en/sub-agents#available-tools), or a [hook matcher](/en/hooks#match-mcp-tools). A hook matcher written against the bare server key, such as `mcp__database-tools__.*`, never fires for a plugin-bundled server.\n\nThe server itself registers under the scoped name `plugin:<plugin-name>:<server-name>`, such as `plugin:my-plugin:database-tools`. Use that name where a configured server name is expected, such as an [`mcp_tool` hook's `server` field](/en/hooks#mcp-tool-hook-fields).\n\n**Benefits of plugin MCP servers**:\n\n* **Bundled distribution**: tools and servers packaged together\n* **Automatic setup**: no manual MCP configuration needed\n* **Team consistency**: everyone gets the same tools when the plugin is installed\n\nSee the [plugin components reference](/en/plugins-reference#mcp-servers) for details on bundling MCP servers with plugins.\n\n## MCP installation scopes\n\nMCP servers can be configured at three scopes. The scope you choose controls which projects the server loads in and whether the configuration is shared with your team. Administrators can also deploy servers at the enterprise level via [managed configuration](#managed-mcp-configuration).\n\n| Scope                     | Loads in             | Shared with team         | Stored in                   |\n| ------------------------- | -------------------- | ------------------------ | --------------------------- |\n| [Local](#local-scope)     | Current project only | No                       | `~/.claude.json`            |\n| [Project](#project-scope) | Current project only | Yes, via version control | `.mcp.json` in project root |\n| [User](#user-scope)       | All your projects    | No                       | `~/.claude.json`            |\n\n### Local scope\n\nLocal scope is the default. A local-scoped server loads only in the project where you added it and stays private to you. Claude Code stores it in `~/.claude.json` under that project's path, so the same server won't appear in your other projects. Use local scope for personal development servers, experimental configurations, or servers with credentials you don't want in version control.\n\n<Note>\n  The term \"local scope\" for MCP servers differs from general local settings. MCP local-scoped servers are stored in `~/.claude.json` (your home directory), while general local settings use `.claude/settings.local.json` (in the project directory). See [Settings](/en/settings#settings-files) for details on settings file locations.\n</Note>\n\n```bash theme={null}\n# Add a local-scoped server (default)\nclaude mcp add --transport http stripe https://mcp.stripe.com\n\n# Explicitly specify local scope\nclaude mcp add --transport http stripe --scope local https://mcp.stripe.com\n```\n\nThe command writes the server into the entry for your current project inside `~/.claude.json`. The example below shows the result when you run it from `/path/to/your/project`:\n\n```json theme={null}\n{\n  \"projects\": {\n    \"/path/to/your/project\": {\n      \"mcpServers\": {\n        \"stripe\": {\n          \"type\": \"http\",\n          \"url\": \"https://mcp.stripe.com\"\n        }\n      }\n    }\n  }\n}\n```\n\n### Project scope\n\nProject-scoped servers enable team collaboration by storing configurations in a `.mcp.json` file at your project's root directory. This file is designed to be checked into version control, ensuring all team members have access to the same MCP tools and services. When you add a project-scoped server, Claude Code automatically creates or updates this file with the appropriate configuration structure.\n\n```bash theme={null}\n# Add a project-scoped server\nclaude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp\n```\n\nThe resulting `.mcp.json` file follows a standardized format:\n\n```json theme={null}\n{\n  \"mcpServers\": {\n    \"shared-server\": {\n      \"command\": \"/path/to/server\",\n      \"args\": [],\n      \"env\": {}\n    }\n  }\n}\n```\n\nFor security reasons, Claude Code prompts for approval before using project-scoped servers from `.mcp.json` files. If you need to reset these approval choices, use the `claude mcp reset-project-choices` command.\n\n### User scope\n\nUser-scoped servers are stored in `~/.claude.json` and provide cross-project accessibility, making them available across all projects on your machine while remaining private to your user account. This scope works well for personal utility servers, development tools, or services you frequently use across different projects.\n\n```bash theme={null}\n# Add a user server\nclaude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic\n```\n\n### Scope hierarchy and precedence\n\nWhen the same server is defined in more than one place, Claude Code connects to it once, using the definition from the highest-precedence source. The entire server entry from that source is used; fields are not merged across scopes.\n\n1. Local scope\n2. Project scope\n3. User scope\n4. [Plugin-provided servers](/en/plugins)\n5. [claude.ai connectors](#use-mcp-servers-from-claude-ai)\n\nThe three scopes match duplicates by name. Plugins and connectors match by endpoint, so one that points at the same URL or command as a server above is treated as a duplicate.\n\n### Environment variable expansion in `.mcp.json`\n\nClaude Code supports environment variable expansion in `.mcp.json` files, allowing teams to share configurations while maintaining flexibility for machine-specific paths and sensitive values like API keys.\n\n**Supported syntax:**\n\n* `${VAR}`: expands to the value of environment variable `VAR`\n* `${VAR:-default}`: expands to `VAR` if set, otherwise uses `default`\n\n**Expansion locations:**\nEnvironment variables can be expanded in:\n\n* `command`: the server executable path\n* `args`: command-line arguments\n* `env`: environment variables passed to the server\n* `url`: for HTTP server types\n* `headers`: for HTTP server authentication\n\n**Example with variable expansion:**\n\n```json theme={null}\n{\n  \"mcpServers\": {\n    \"api-server\": {\n      \"type\": \"http\",\n      \"url\": \"${API_BASE_URL:-https://api.example.com}/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${API_KEY}\"\n      }\n    }\n  }\n}\n```\n\nIf a required environment variable isn't set and has no default value, Claude Code fails to parse the config.\n\n## Practical examples\n\n### Example: Monitor errors with Sentry\n\n```bash theme={null}\nclaude mcp add --transport http sentry https://mcp.sentry.dev/mcp\n```\n\nAuthenticate with your Sentry account:\n\n```text theme={null}\n/mcp\n```\n\nThen debug production issues:\n\n```text theme={null}\nWhat are the most common errors in the last 24 hours?\n```\n\n```text theme={null}\nShow me the stack trace for error ID abc123\n```\n\n```text theme={null}\nWhich deployment introduced these new errors?\n```\n\n### Example: Connect to GitHub for code reviews\n\nGitHub's remote MCP server authenticates with a GitHub personal access token passed as a header. To get one, open your [GitHub token settings](https://github.com/settings/personal-access-tokens), generate a new fine-grained token with access to the repositories you want Claude to work with, then add the server:\n\n```bash theme={null}\nclaude mcp add --transport http github https://api.githubcopilot.com/mcp/ \\\n  --header \"Authorization: Bearer YOUR_GITHUB_PAT\"\n```\n\nThen work with GitHub:\n\n```text theme={null}\nReview PR #456 and suggest improvements\n```\n\n```text theme={null}\nCreate a new issue for the bug we just found\n```\n\n```text theme={null}\nShow me all open PRs assigned to me\n```\n\n### Example: Query your PostgreSQL database\n\n```bash theme={null}\nclaude mcp add --transport stdio db -- npx -y @bytebase/dbhub \\\n  --dsn \"postgresql://readonly:pass@prod.db.com:5432/analytics\"\n```\n\nThen query your database naturally:\n\n```text theme={null}\nWhat's our total revenue this month?\n```\n\n```text theme={null}\nShow me the schema for the orders table\n```\n\n```text theme={null}\nFind customers who haven't made a purchase in 90 days\n```\n\n## Authenticate with remote MCP servers\n\nMany cloud-based MCP servers require authentication. Claude Code supports OAuth 2.0 for secure connections.\n\nClaude Code marks a remote server as needing authentication when the server responds with `401 Unauthorized` or `403 Forbidden`. Either status code flags the server in `/mcp` so you can complete the OAuth flow.\n\nAs of v2.1.195, when a token refresh fails because the server rejects the stored refresh token, Claude Code immediately shows a notice pointing at `/mcp`. The connected server's menu there offers Re-authenticate, so you can sign in again before the next tool call fails.\n\nA custom server that returns a `WWW-Authenticate` header pointing to its authorization server gets the same automatic discovery as any other remote server.\n\nAs of v2.1.193, Claude Code also shows a startup notice when one or more configured servers need authentication, so you don't have to open `/mcp` to discover which servers need sign-in.\n\nIn non-interactive mode there's no `/mcp` panel, so Claude Code can't run the OAuth flow for you. As of v2.1.196, when a configured server needs authentication during a `claude -p` or Agent SDK run with [tool search](#scale-with-mcp-tool-search) enabled, which is the default, Claude Code tells Claude that the server's tools are unavailable until you authorize it. Claude can then name the server that needs sign-in instead of responding as if the server weren't configured. Complete the sign-in from an interactive session with `/mcp` or `claude mcp login <name>`.\n\nIf you configured `headers.Authorization` for the server and the server rejects that header, Claude Code reports the connection as failed instead of falling back to OAuth. Check that the token is valid for the MCP endpoint, or remove the header to use the OAuth flow.\n\n<Steps>\n  <Step title=\"Add the server that requires authentication\">\n    For example:\n\n    ```bash theme={null}\n    claude mcp add --transport http sentry https://mcp.sentry.dev/mcp\n    ```\n  </Step>\n\n  <Step title=\"Use the /mcp command within Claude Code\">\n    In Claude Code, use the command:\n\n    ```text theme={null}\n    /mcp\n    ```\n\n    Then follow the steps in your browser to log in.\n  </Step>\n</Steps>\n\n<Tip>\n  Tips:\n\n  * Authentication tokens are stored securely and refreshed automatically\n  * Use \"Clear authentication\" in the `/mcp` menu to revoke access\n  * If your browser doesn't open automatically, copy the provided URL and open it manually\n  * If the browser redirect fails with a connection error after authenticating, paste the full callback URL from your browser's address bar into the URL prompt that appears in Claude Code\n  * OAuth authentication works with HTTP servers\n</Tip>\n\n### Authenticate from the command line\n\nFrom v2.1.186, `claude mcp login <name>` runs a configured server's OAuth flow directly from your shell, so you don't need to open the `/mcp` panel inside a session.\n\n```bash theme={null}\nclaude mcp login sentry\n```\n\nTo clear stored credentials later, run `claude mcp logout <name>`.\n\nAs of v2.1.191, the command detects when no local browser is available, such as during an SSH session or on Linux without a display server, and prints the authorization URL instead of trying to open a browser. Open the URL on your local machine, then paste the full redirect URL from your browser's address bar back at the prompt. The command needs an interactive terminal for the paste step, so connect with `ssh -t`. Pass `--no-browser` to force the URL prompt even when a local browser is detected.\n\n```bash theme={null}\nclaude mcp login sentry --no-browser\n```\n\n### Use a fixed OAuth callback port\n\nSome MCP servers require a specific redirect URI registered in advance. By default, Claude Code picks a random available port for the OAuth callback. Use `--callback-port` to fix the port so it matches a pre-registered redirect URI of the form `http://localhost:PORT/callback`.\n\nYou can use `--callback-port` on its own (with dynamic client registration) or together with `--client-id` (with pre-configured credentials).\n\n```bash theme={null}\n# Fixed callback port with dynamic client registration\nclaude mcp add --transport http \\\n  --callback-port 8080 \\\n  my-server https://mcp.example.com/mcp\n```\n\n### Use pre-configured OAuth credentials\n\nSome MCP servers don't support automatic OAuth setup via Dynamic Client Registration. If you see an error like \"Incompatible auth server: does not support dynamic client registration,\" the server requires pre-configured credentials. Claude Code also supports servers that use a Client ID Metadata Document (CIMD) instead of Dynamic Client Registration, and discovers these automatically. If automatic discovery fails, register an OAuth app through the server's developer portal first, then provide the credentials when adding the server.\n\n<Steps>\n  <Step title=\"Register an OAuth app with the server\">\n    Create an app through the server's developer portal and note your client ID and client secret.\n\n    Many servers also require a redirect URI. If so, choose a port and register a redirect URI in the format `http://localhost:PORT/callback`. Use that same port with `--callback-port` in the next step.\n  </Step>\n\n  <Step title=\"Add the server with your credentials\">\n    Choose one of the following methods. The port used for `--callback-port` can be any available port. It needs to match the redirect URI you registered in the previous step.\n\n    <Tabs>\n      <Tab title=\"claude mcp add\">\n        Use `--client-id` to pass your app's client ID. The `--client-secret` flag prompts for the secret with masked input:\n\n        ```bash theme={null}\n        claude mcp add --transport http \\\n          --client-id your-client-id --client-secret --callback-port 8080 \\\n          my-server https://mcp.example.com/mcp\n        ```\n      </Tab>\n\n      <Tab title=\"claude mcp add-json\">\n        Include the `oauth` object in the JSON config and pass `--client-secret` as a separate flag:\n\n        ```bash theme={null}\n        claude mcp add-json my-server \\\n          '{\"type\":\"http\",\"url\":\"https://mcp.example.com/mcp\",\"oauth\":{\"clientId\":\"your-client-id\",\"callbackPort\":8080}}' \\\n          --client-secret\n        ```\n      </Tab>\n\n      <Tab title=\"claude mcp add-json (callback port only)\">\n        Use `--callback-port` without a client ID to fix the port while using dynamic client registration:\n\n        ```bash theme={null}\n        claude mcp add-json my-server \\\n          '{\"type\":\"http\",\"url\":\"https://mcp.example.com/mcp\",\"oauth\":{\"callbackPort\":8080}}'\n        ```\n      </Tab>\n\n      <Tab title=\"CI / env var\">\n        Set the secret via environment variable to skip the interactive prompt:\n\n        ```bash theme={null}\n        MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \\\n          --client-id your-client-id --client-secret --callback-port 8080 \\\n          my-server https://mcp.example.com/mcp\n        ```\n      </Tab>\n    </Tabs>\n  </Step>\n\n  <Step title=\"Authenticate in Claude Code\">\n    Run `/mcp` in Claude Code and follow the browser login flow.\n  </Step>\n</Steps>\n\n<Tip>\n  Tips:\n\n  * The client secret is stored securely in your system keychain (macOS) or a credentials file, not in your config\n  * If the server uses a public OAuth client with no secret, use only `--client-id` without `--client-secret`\n  * `--callback-port` can be used with or without `--client-id`\n  * These flags only apply to HTTP and SSE transports. They have no effect on stdio servers\n  * Use `claude mcp get <name>` to verify that OAuth credentials are configured for a server\n</Tip>\n\n### Override OAuth metadata discovery\n\nPoint Claude Code at a specific OAuth authorization server metadata URL to bypass the default discovery chain. Set `authServerMetadataUrl` when the MCP server's standard endpoints error, or when you want to route discovery through an internal proxy. By default, Claude Code first checks RFC 9728 Protected Resource Metadata at `/.well-known/oauth-protected-resource`, then falls back to RFC 8414 authorization server metadata at `/.well-known/oauth-authorization-server`.\n\nSet `authServerMetadataUrl` in the `oauth` object of your server's config in `.mcp.json`:\n\n```json theme={null}\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.example.com/mcp\",\n      \"oauth\": {\n        \"authServerMetadataUrl\": \"https://auth.example.com/.well-known/openid-configuration\"\n      }\n    }\n  }\n}\n```\n\nThe URL must use `https://`. `authServerMetadataUrl` requires Claude Code v2.1.64 or later. The metadata URL's `scopes_supported` overrides the scopes the upstream server advertises.\n\n### Restrict OAuth scopes\n\nSet `oauth.scopes` to pin the scopes Claude Code requests during the authorization flow. This is the supported way to restrict an MCP server to a security-team-approved subset when the upstream authorization server advertises more scopes than you want to grant. The value is a single space-separated string, matching the `scope` parameter format in RFC 6749 §3.3.\n\n```json theme={null}\n{\n  \"mcpServers\": {\n    \"slack\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.slack.com/mcp\",\n      \"oauth\": {\n        \"scopes\": \"channels:read chat:write search:read\"\n      }\n    }\n  }\n}\n```\n\n`oauth.scopes` takes precedence over both `authServerMetadataUrl` and the scopes the server discovers at `/.well-known`. Leave it unset to let the MCP server determine the requested scope set.\n\nAs of v2.1.196, when `oauth.scopes` isn't set, Claude Code requests the scope provided by the server's `WWW-Authenticate` header or its protected resource metadata, and sends no `scope` parameter when neither provides one. It no longer requests the full `scopes_supported` catalog from automatically discovered authorization server metadata. Requesting that catalog made identity providers that advertise admin-only or template scopes reject the authorization request with an `invalid_scope` error. Metadata fetched from a configured `authServerMetadataUrl` still supplies its `scopes_supported` as the requested scopes.\n\nIf the authorization server advertises `offline_access` in `scopes_supported`, Claude Code appends it to the pinned scopes so the access token can be refreshed without a new browser sign-in.\n\nIf the server later returns a 403 `insufficient_scope` for a tool call, Claude Code re-authenticates with the same pinned scopes. Widen `oauth.scopes` when a tool you need requires a scope outside the pinned set.\n\n### Use dynamic headers for custom authentication\n\nIf your MCP server uses an authentication scheme other than OAuth, such as Kerberos, short-lived tokens, or an internal SSO, use `headersHelper` to generate request headers at connection time. Claude Code runs the command and merges its output into the connection headers.\n\n```json theme={null}\n{\n  \"mcpServers\": {\n    \"internal-api\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.internal.example.com\",\n      \"headersHelper\": \"/opt/bin/get-mcp-auth-headers.sh\"\n    }\n  }\n}\n```\n\nThe command can also be inline:\n\n```json theme={null}\n{\n  \"mcpServers\": {\n    \"internal-api\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.internal.example.com\",\n      \"headersHelper\": \"echo '{\\\"Authorization\\\": \\\"Bearer '\\\"$(get-token)\\\"'\\\"}'\"\n    }\n  }\n}\n```\n\n**Requirements:**\n\n* The command must write a JSON object of string key-value pairs to stdout\n* The command runs in a shell with a 10-second timeout\n* Dynamic headers override any static `headers` with the same name\n\nThe helper runs fresh on each connection, at session start and on reconnect. There is no caching, so your script is responsible for any token reuse.\n\nAs of v2.1.193, if a tool call returns `401 Unauthorized` or `403 Forbidden`, Claude Code automatically re-runs the helper, reconnects with the fresh headers, and retries the call once. Claude Code marks the server as needing authentication in `/mcp` only if that retry also fails.\n\nClaude Code sets these environment variables when executing the helper:\n\n| Variable                      | Value                                                                                                        |\n| :---------------------------- | :----------------------------------------------------------------------------------------------------------- |\n| `CLAUDE_CODE_MCP_SERVER_NAME` | the name of the MCP server                                                                                   |\n| `CLAUDE_CODE_MCP_SERVER_URL`  | the URL of the MCP server                                                                                    |\n| `CLAUDE_PLUGIN_ROOT`          | the plugin's root directory. Set only when a [plugin](/en/plugins-reference#mcp-servers) provides the server |\n\nUse these to write a single helper script that serves multiple MCP servers.\n\nFor a plugin-provided server, the helper also runs with its working directory set to the plugin root, so a relative `headersHelper` path resolves inside the plugin directory rather than against the session's working directory. Requires Claude Code v2.1.195 or later.\n\n<Note>\n  `headersHelper` executes arbitrary shell commands. When defined at project or local scope, it only runs after you accept the workspace trust dialog.\n</Note>\n\n## Add MCP servers from JSON configuration\n\nIf you have a JSON configuration for an MCP server, you can add it directly:\n\n<Steps>\n  <Step title=\"Add an MCP server from JSON\">\n    ```bash theme={null}\n    # Basic syntax\n    claude mcp add-json <name> '<json>'\n\n    # Example: Adding an HTTP server with JSON configuration\n    claude mcp add-json weather-api '{\"type\":\"http\",\"url\":\"https://api.weather.com/mcp\",\"headers\":{\"Authorization\":\"Bearer token\"}}'\n\n    # Example: Adding a stdio server with JSON configuration\n    claude mcp add-json local-weather '{\"type\":\"stdio\",\"command\":\"/path/to/weather-cli\",\"args\":[\"--api-key\",\"abc123\"],\"env\":{\"CACHE_DIR\":\"/tmp\"}}'\n\n    # Example: Adding an HTTP server with pre-configured OAuth credentials\n    claude mcp add-json my-server '{\"type\":\"http\",\"url\":\"https://mcp.example.com/mcp\",\"oauth\":{\"clientId\":\"your-client-id\",\"callbackPort\":8080}}' --client-secret\n    ```\n  </Step>\n\n  <Step title=\"Verify the server was added\">\n    ```bash theme={null}\n    claude mcp get weather-api\n    ```\n  </Step>\n</Steps>\n\n<Tip>\n  Tips:\n\n  * Make sure the JSON is properly escaped in your shell\n  * The JSON must conform to the MCP server configuration schema\n  * You can use `--scope user` to add the server to your user configuration instead of the project-specific one\n</Tip>\n\n## Import MCP servers from Claude Desktop\n\nIf you've already configured MCP servers in Claude Desktop, you can import them:\n\n<Steps>\n  <Step title=\"Import servers from Claude Desktop\">\n    ```bash theme={null}\n    # Basic syntax \n    claude mcp add-from-claude-desktop \n    ```\n  </Step>\n\n  <Step title=\"Select which servers to import\">\n    After running the command, you'll see an interactive dialog that allows you to select which servers you want to import.\n  </Step>\n\n  <Step title=\"Verify the servers were imported\">\n    ```bash theme={null}\n    claude mcp list \n    ```\n  </Step>\n</Steps>\n\nServer names added through `claude mcp` commands can contain only letters, numbers, hyphens, and underscores. Claude Desktop doesn't apply that restriction, so a Claude Desktop server whose name contains any other character, such as a space, can't be imported. The import reports each name it rejects and still imports the other servers you selected. Before v2.1.205, the first invalid name stopped the import and none of the selected servers were added.\n\n<Tip>\n  Tips:\n\n  * This feature only works on macOS and Windows Subsystem for Linux (WSL)\n  * It reads the Claude Desktop configuration file from its standard location on those platforms\n  * Use the `--scope user` flag to add servers to your user configuration\n  * Imported servers keep the same names as in Claude Desktop when the name contains only letters, numbers, hyphens, and underscores. Claude Code reports a server whose name contains any other character and skips it\n  * If servers with the same names already exist, they get a numerical suffix (for example, `server_1`)\n</Tip>\n\n## Use MCP servers from claude.ai\n\nIf you've logged into Claude Code with a [claude.ai](https://claude.ai) account, MCP servers you've added in claude.ai are automatically available in Claude Code:\n\n<Steps>\n  <Step title=\"Configure MCP servers in claude.ai\">\n    Add servers at [claude.ai/customize/connectors](https://claude.ai/customize/connectors). On Team and Enterprise plans, only admins can add servers.\n  </Step>\n\n  <Step title=\"Authenticate the MCP server\">\n    Complete any required authentication steps in claude.ai.\n  </Step>\n\n  <Step title=\"View and manage servers in Claude Code\">\n    In Claude Code, use the command:\n\n    ```text theme={null}\n    /mcp\n    ```\n\n    Servers from claude.ai appear in the list with indicators showing they come from claude.ai.\n  </Step>\n</Steps>\n\nFrom v2.1.161, connectors you have never signed in to are collapsed behind a `Show unused connectors` row at the end of the claude.ai section, so an organization-provisioned list doesn't fill the panel. Select the row to expand them. A connector you signed in to before stays visible even when it currently needs re-authentication.\n\nConnectors from claude.ai are fetched only when your active [authentication method](/en/authentication#authentication-precedence) is your claude.ai subscription. They aren't loaded when `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `apiKeyHelper`, or a third-party provider such as Amazon Bedrock or Google Cloud's Agent Platform is active, even if you previously ran `/login`.\n\nIf `/mcp` doesn't list a connector you added, run `/status` to confirm which authentication method is active, unset that environment variable or remove the `apiKeyHelper` setting, then run `/login` to select your claude.ai account.\n\nA server you've added in Claude Code takes [precedence](#scope-hierarchy-and-precedence) over a claude.ai connector that points at the same URL. When this happens, `/mcp` lists the connector as hidden and shows how to remove the duplicate if you'd rather use the connector.\n\nSome Anthropic-hosted connectors, such as Microsoft 365, Gmail, and Google Calendar, don't support local OAuth from Claude Code because the upstream identity provider only accepts the redirect URL that claude.ai registered. From v2.1.162, authenticating one of these hosts in `/mcp` shows a message directing you to connect it at Settings → Connectors on claude.ai instead. Once connected there, the connector appears in Claude Code automatically.\n\n### Disable claude.ai connectors\n\nTo disable claude.ai MCP servers in Claude Code, set [`disableClaudeAiConnectors`](/en/settings#available-settings) to `true` in any settings scope:\n\n```json theme={null}\n{\n  \"disableClaudeAiConnectors\": true\n}\n```\n\nThis setting uses any-source-true semantics: `true` in any settings source takes precedence. A checked-in project `.claude/settings.json` can opt a repository out of cloud connectors, but a project-level `false` can't re-enable connectors that a user- or policy-level `true` has disabled. Servers passed explicitly via `--mcp-config` are unaffected.\n\nYou can also set the `ENABLE_CLAUDEAI_MCP_SERVERS` environment variable to `false`, which has the same effect for the current shell session:\n\n```bash theme={null}\nENABLE_CLAUDEAI_MCP_SERVERS=false claude\n```\n\nTo block individual claude.ai connectors instead of all of them, add them to [`deniedMcpServers`](/en/managed-mcp) by name or by URL pattern. For example, a `serverName` entry of `\"claude.ai Slack\"` blocks the Slack connector. To toggle a connector on or off for the current project only, use the `/mcp` panel.\n\n<Note>\n  These client-side settings govern local Claude Code sessions. In [Claude Code on the web](/en/claude-code-on-the-web) sessions, claude.ai connectors are provisioned by the remote host and arrive as explicit `--mcp-config` entries, so `disableClaudeAiConnectors` doesn't apply there. Connector URLs are also rewritten through the session proxy, so a `deniedMcpServers` `serverUrl` pattern targeting the vendor URL won't match. Manage which connectors a cloud session can use from your claude.ai organization settings.\n</Note>\n\n## Use Claude Code as an MCP server\n\nYou can use Claude Code itself as an MCP server that other applications can connect to:\n\n```bash theme={null}\n# Start Claude as a stdio MCP server\nclaude mcp serve\n```\n\nYou can use this in Claude Desktop by adding this configuration to claude\\_desktop\\_config.json:\n\n```json theme={null}\n{\n  \"mcpServers\": {\n    \"claude-code\": {\n      \"type\": \"stdio\",\n      \"command\": \"claude\",\n      \"args\": [\"mcp\", \"serve\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n<Warning>\n  **Configuring the executable path**: the `command` field must reference the Claude Code executable. If the `claude` command is not in your system's PATH, you'll need to specify the full path to the executable.\n\n  To find the full path:\n\n  ```bash theme={null}\n  which claude\n  ```\n\n  Then use the full path in your configuration:\n\n  ```json theme={null}\n  {\n    \"mcpServers\": {\n      \"claude-code\": {\n        \"type\": \"stdio\",\n        \"command\": \"/full/path/to/claude\",\n        \"args\": [\"mcp\", \"serve\"],\n        \"env\": {}\n      }\n    }\n  }\n  ```\n\n  Without the correct executable path, you'll encounter errors like `spawn claude ENOENT`.\n</Warning>\n\n<Tip>\n  Tips:\n\n  * The server provides access to Claude's tools like View, Edit, LS, etc.\n  * In Claude Desktop, try asking Claude to read files in a directory, make edits, and more.\n  * This MCP server only exposes Claude Code's tools to your MCP client, so your own client is responsible for implementing user confirmation for individual tool calls.\n</Tip>\n\n## MCP output limits and warnings\n\nWhen MCP tools produce large outputs, Claude Code helps manage the token usage to prevent overwhelming your conversation context:\n\n* **Output warning threshold**: Claude Code displays a warning when any MCP tool output exceeds 10,000 tokens\n* **Configurable limit**: you can adjust the maximum allowed MCP output tokens using the `MAX_MCP_OUTPUT_TOKENS` environment variable\n* **Default limit**: the default maximum is 25,000 tokens\n* **Scope**: the environment variable applies to tools that don't declare their own limit. Tools that set [`anthropic/maxResultSizeChars`](#raise-the-limit-for-a-specific-tool) use that value instead for text content, regardless of what `MAX_MCP_OUTPUT_TOKENS` is set to. Tools that return image data are still subject to `MAX_MCP_OUTPUT_TOKENS`\n\nTo increase the limit for tools that produce large outputs:\n\n```bash theme={null}\nexport MAX_MCP_OUTPUT_TOKENS=50000\nclaude\n```\n\nThis is particularly useful when working with MCP servers that:\n\n* Query large datasets or databases\n* Generate detailed reports or documentation\n* Process extensive log files or debugging information\n\n### Raise the limit for a specific tool\n\nIf you're building an MCP server, you can allow individual tools to return results larger than the default persist-to-disk threshold by setting `_meta[\"anthropic/maxResultSizeChars\"]` in the tool's `tools/list` response entry. Claude Code raises that tool's threshold to the annotated value, up to a hard ceiling of 500,000 characters.\n\nThis is useful for tools that return inherently large but necessary outputs, such as database schemas or full file trees. Without the annotation, results that exceed the default threshold are persisted to disk and replaced with a file reference in the conversation.\n\n```json theme={null}\n{\n  \"name\": \"get_schema\",\n  \"description\": \"Returns the full database schema\",\n  \"_meta\": {\n    \"anthropic/maxResultSizeChars\": 200000\n  }\n}\n```\n\nThe annotation applies independently of `MAX_MCP_OUTPUT_TOKENS` for text content, so users don't need to raise the environment variable for tools that declare it. Tools that return image data are still subject to the token limit.\n\n<Warning>\n  If you frequently encounter output warnings with specific MCP servers you don't control, consider increasing the `MAX_MCP_OUTPUT_TOKENS` limit. You can also ask the server author to add the `anthropic/maxResultSizeChars` annotation or to paginate their responses. The annotation has no effect on tools that return image content; for those, raising `MAX_MCP_OUTPUT_TOKENS` is the only option.\n</Warning>\n\n## Tool input schemas with a root-level combinator\n\nSome MCP servers declare a tool's input schema as a JSON Schema union, with `anyOf`, `oneOf`, or `allOf` at the top level of the schema. The Claude API doesn't accept those keywords at the schema root. It does accept combinators nested inside `properties`, which Claude Code sends unchanged.\n\nAs of Claude Code v2.1.195, tools with a root-level combinator stay available. Before sending the tool to the API, Claude Code flattens the schema into a single object and prepends a sentence to the tool's description that tells Claude which parameter groups belong together:\n\n* `allOf`: properties from every branch are merged, and each branch's `required` list still applies\n* `anyOf` and `oneOf`: properties from every branch are merged, and each branch's `required` list is described in the tool description instead of enforced by the schema\n\nYour server receives whichever arguments Claude chose, so keep validating the combination server-side.\n\nWhen Claude Code can't produce a schema the API accepts, or on a deployment that doesn't receive the remote configuration that enables the rewrite, such as an offline machine, it skips that one tool, records the reason in the server's log, and leaves the server's other tools available. Versions earlier than v2.1.195 skip every tool whose input schema has a root-level `anyOf`, `oneOf`, or `allOf`.\n\n## Require approval for a specific tool\n\nIf you're building an MCP server, you can mark a tool as requiring explicit approval on every call by setting `_meta[\"anthropic/requiresUserInteraction\"]` to `true` in the tool's `tools/list` response entry. The value must be the JSON boolean `true`; any other value is ignored.\n\nClaude Code shows that tool's permission prompt on every call, even in `acceptEdits`, `auto`, and `bypassPermissions` [permission modes](/en/permissions#permission-modes), and doesn't offer a \"don't ask again\" option for it. [Allow rules](/en/permissions#permission-rule-syntax) that match the tool don't skip the prompt either. In `dontAsk` mode, which never prompts, Claude Code denies the call instead.\n\nThe prompt has to reach a person. In non-interactive mode with [`--permission-prompt-tool`](/en/cli-reference#cli-flags), an `allow` result from the prompt tool for a flagged tool is converted to a deny with the message `MCP tool requires user interaction; not supported via --permission-prompt-tool`. The Agent SDK's [`canUseTool` callback](/en/agent-sdk/permissions) does receive these calls and can approve them, because the SDK host is expected to show them to a user.\n\nUse this for tools whose permission prompt is itself the point, such as a consent or access-grant step where auto-approval would mean no human ever agreed. Other tools from the same server keep their normal permission behavior.\n\nThe following `tools/list` entry marks one tool as always requiring approval.\n\n```json theme={null}\n{\n  \"name\": \"grant_access\",\n  \"description\": \"Requests access to a protected resource\",\n  \"_meta\": {\n    \"anthropic/requiresUserInteraction\": true\n  }\n}\n```\n\nThe `anthropic/requiresUserInteraction` annotation requires Claude Code v2.1.199 or later. Earlier versions ignore it and apply the standard permission flow.\n\nWhen a session is connected to [Remote Control](/en/remote-control) or an SDK host, Claude Code marks the permission request as requiring user interaction, so the client shows the tool's permission prompt for you to answer instead of a one-tap approve action.\n\n## Respond to MCP elicitation requests\n\nMCP servers can request structured input from you mid-task using elicitation. When a server needs information it can't get on its own, Claude Code displays an interactive dialog and passes your response back to the server. No configuration is required on your side: elicitation dialogs appear automatically when a server requests them.\n\nServers can request input in two ways:\n\n* **Form mode**: Claude Code shows a dialog with form fields defined by the server (for example, a username and password prompt). Fill in the fields and submit.\n* **URL mode**: Claude Code opens a browser URL for authentication or approval. Complete the flow in the browser, then confirm in the CLI.\n\nTo auto-respond to elicitation requests without showing a dialog, use the [`Elicitation` hook](/en/hooks#elicitation).\n\nIf you're building an MCP server that uses elicitation, see the [MCP elicitation specification](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation) for protocol details and schema examples.\n\n## Use MCP resources\n\nMCP servers can expose resources that you can reference using @ mentions, similar to how you reference files.\n\n### Reference MCP resources\n\n<Steps>\n  <Step title=\"List available resources\">\n    Type `@` in your prompt to see available resources from all connected MCP servers. Resources appear alongside files in the autocomplete menu.\n  </Step>\n\n  <Step title=\"Reference a specific resource\">\n    Use the format `@server:protocol://resource/path` to reference a resource:\n\n    ```text theme={null}\n    Can you analyze @github:issue://123 and suggest a fix?\n    ```\n\n    ```text theme={null}\n    Please review the API documentation at @docs:file://api/authentication\n    ```\n  </Step>\n\n  <Step title=\"Multiple resource references\">\n    You can reference multiple resources in a single prompt:\n\n    ```text theme={null}\n    Compare @postgres:schema://users with @docs:file://database/user-model\n    ```\n  </Step>\n</Steps>\n\n<Tip>\n  Tips:\n\n  * Resources are automatically fetched and included as attachments when referenced\n  * Resource paths are fuzzy-searchable in the @ mention autocomplete\n  * Claude Code automatically provides tools to list and read MCP resources when servers support them\n  * Resources can contain any type of content that the MCP server provides (text, JSON, structured data, etc.)\n</Tip>\n\n## Scale with MCP tool search\n\nTool search keeps MCP context usage low by deferring tool definitions until Claude needs them. Only tool names and server instructions load at session start, so adding more MCP servers has minimal impact on your context window. Claude Code doesn't impose a fixed per-server tool cap; the practical limit is your context window budget.\n\n### How it works\n\nTool search is enabled by default. MCP tools are deferred rather than loaded into context upfront, and Claude uses a search tool to discover relevant ones when a task needs them. Only the tools Claude actually uses enter context. From your perspective, MCP tools work exactly as before.\n\nIf you prefer threshold-based loading, set `ENABLE_TOOL_SEARCH=auto` to load schemas upfront when they fit within 10% of the context window and defer only the overflow. See [Configure tool search](#configure-tool-search) for all options.\n\n### For MCP server authors\n\nIf you're building an MCP server, the server instructions field becomes more useful with tool search enabled. Server instructions help Claude understand when to search for your tools, similar to how [skills](/en/skills) work.\n\nAdd clear, descriptive server instructions that explain:\n\n* What category of tasks your tools handle\n* When Claude should search for your tools\n* Key capabilities your server provides\n\nClaude Code truncates tool descriptions and server instructions at 2KB each. Keep them concise to avoid truncation, and put critical details near the start.\n\n### Configure tool search\n\nTool search is enabled by default: MCP tools are deferred and discovered on demand. Claude Code disables it by default on Google Cloud's Agent Platform. It is also disabled when `ANTHROPIC_BASE_URL` points to a non-first-party host, since most proxies don't forward `tool_reference` blocks. Set `ENABLE_TOOL_SEARCH` explicitly to override either fallback.\n\nTool search requires a model that supports `tool_reference` blocks. Haiku models don't support it. On Google Cloud's Agent Platform, tool search is supported for Claude Sonnet 4.5 and later and Claude Opus 4.5 and later.\n\nControl tool search behavior with the `ENABLE_TOOL_SEARCH` environment variable:\n\n| Value    | Behavior                                                                                                                                                                                                                                                                 |\n| :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| (unset)  | All MCP tools deferred and loaded on demand. Falls back to loading upfront on Google Cloud's Agent Platform or when `ANTHROPIC_BASE_URL` is a non-first-party host                                                                                                       |\n| `true`   | All MCP tools deferred. Claude Code sends the beta header even on Google Cloud's Agent Platform and through proxies. Requests fail on Google Cloud's Agent Platform models earlier than Sonnet 4.5 or Opus 4.5, or on proxies that don't support `tool_reference` blocks |\n| `auto`   | Threshold mode: tools load upfront if they fit within 10% of the context window, deferred otherwise                                                                                                                                                                      |\n| `auto:N` | Threshold mode with a custom percentage, where `N` is 0-100. For example, `auto:5` for 5%                                                                                                                                                                                |\n| `false`  | All MCP tools loaded upfront, no deferral                                                                                                                                                                                                                                |\n\n```bash theme={null}\n# Use a custom 5% threshold\nENABLE_TOOL_SEARCH=auto:5 claude\n\n# Disable tool search entirely\nENABLE_TOOL_SEARCH=false claude\n```\n\nOr set the value in your [settings.json `env` field](/en/settings#available-settings).\n\nYou can also disable the `ToolSearch` tool specifically:\n\n```json theme={null}\n{\n  \"permissions\": {\n    \"deny\": [\"ToolSearch\"]\n  }\n}\n```\n\n### Exempt a server from deferral\n\nIf a server's tools should always be visible to Claude without a search step, set `alwaysLoad` to `true` in that server's configuration. Every tool from that server then loads into context at session start regardless of the `ENABLE_TOOL_SEARCH` setting. Use this for a small number of tools that Claude needs on every turn, since each upfront tool consumes context that would otherwise be available for your conversation.\n\nThe following `.mcp.json` entry exempts one HTTP server while leaving other servers deferred:\n\n```json theme={null}\n{\n  \"mcpServers\": {\n    \"core-tools\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.example.com/mcp\",\n      \"alwaysLoad\": true\n    }\n  }\n}\n```\n\nThe `alwaysLoad` field is available on all server types and requires Claude Code v2.1.121 or later. An MCP server can also mark individual tools as always-loaded by including `\"anthropic/alwaysLoad\": true` in the tool's `_meta` object, which has the same effect for that tool only.\n\nSetting `alwaysLoad: true` also blocks startup until the server connects, capped at the standard 5-second connect timeout. This applies even though MCP startup is otherwise [non-blocking by default](/en/env-vars), since the tools must be present when the first prompt is built. Other servers continue to connect in the background.\n\n## Use MCP prompts as commands\n\nMCP servers can expose prompts that become available as commands in Claude Code.\n\n### Execute MCP prompts\n\n<Steps>\n  <Step title=\"Discover available prompts\">\n    Type `/` to see all available commands, including those from MCP servers. MCP prompts appear with the format `/mcp__servername__promptname`.\n  </Step>\n\n  <Step title=\"Execute a prompt without arguments\">\n    ```text theme={null}\n    /mcp__github__list_prs\n    ```\n  </Step>\n\n  <Step title=\"Execute a prompt with arguments\">\n    Many prompts accept arguments. Pass them space-separated after the command:\n\n    ```text theme={null}\n    /mcp__github__pr_review 456\n    ```\n\n    ```text theme={null}\n    /mcp__jira__create_issue \"Bug in login flow\" high\n    ```\n  </Step>\n</Steps>\n\n<Tip>\n  Tips:\n\n  * MCP prompts are dynamically discovered from connected servers\n  * Arguments are parsed based on the prompt's defined parameters\n  * Prompt results are injected directly into the conversation\n  * Server and prompt names are normalized, with spaces converted to underscores\n</Tip>\n\n## Managed MCP configuration\n\nFor organizations that need centralized control over which MCP servers users can connect to, see [Managed MCP configuration](/en/managed-mcp). It covers deploying a fixed server set with `managed-mcp.json`, restricting servers with `allowedMcpServers` and `deniedMcpServers`, and what users see when a server is blocked.\n","durationMs":407,"url":"https://code.claude.com/docs/en/mcp.md"},"sourceToolAssistantUUID":"2c61bd93-5688-4486-a515-a82eb1fe86f8","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"24cbf5d2-f913-400a-adfe-3d70d850099d","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4MtzguCEMnMDNER7HF","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_019DuSTVcB9kUiUCHiUHZDUs","name":"WebFetch","input":{"url":"https://code.claude.com/docs/en/mcp-quickstart.md","prompt":"edit .mcp.json directly, where servers are saved, server scope, trust permissions"},"caller":{"type":"direct"}}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":775,"cache_read_input_tokens":14744,"cache_creation":{"ephemeral_5m_input_tokens":775,"ephemeral_1h_input_tokens":0},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011Ccv4MsWtWLStKHVUonHHN","attributionAgent":"claude-code-guide","type":"assistant","uuid":"2777910c-4eed-4a19-ba93-ec464996ff3f","timestamp":"2026-07-11T09:47:38.723Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"2777910c-4eed-4a19-ba93-ec464996ff3f","isSidechain":true,"promptId":"463e84b3-536f-432f-b32a-4fdae6dbed7a","agentId":"a556d2e38a847bf6e","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_019DuSTVcB9kUiUCHiUHZDUs","type":"tool_result","content":"> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Connect to MCP servers\n\n> Add an MCP server to Claude Code, verify the connection, and find the configuration on disk.\n\nThe [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) lets Claude Code use tools beyond its built-in set, such as searching an issue tracker, querying a database, or controlling a web browser. These tools come from MCP servers, which run on your machine or as hosted services.\n\nThis guide walks you through connecting one MCP server end to end with the Claude Code CLI. By the end, you'll have a server connected and responding, know where its configuration lives on disk, and know how to fix the most common connection errors.\n\n<Note>\n  You can also add MCP servers from other surfaces, including the desktop app, VS Code, and the web. See [Connect from other surfaces](#connect-from-other-surfaces).\n</Note>\n\nFor every way to connect and configure MCP servers in Claude Code, see the [MCP reference](/en/mcp).\n\n## Before you begin\n\nMake sure you have:\n\n* [Claude Code installed](/en/quickstart) and authenticated\n* A terminal open in a project directory. Any directory works, including an empty one.\n\n## Add and verify a server\n\nThe example below connects to the [Claude Code documentation MCP server](https://code.claude.com/docs/mcp), a hosted server with full-text search over the Claude Code docs. It doesn't require authentication or any special configuration, so it works well as a first server to test the setup flow with.\n\nThe steps are the same for any server: add it, check the connection status, then use it in a session, with an optional cleanup step at the end. Some servers add a step, like a browser sign-in, shown in [Additional MCP server examples](#additional-mcp-server-examples). For more servers to connect, browse the [Anthropic Directory](/en/mcp#find-and-build-mcp-servers).\n\n<Steps>\n  <Step title=\"Add the MCP server\">\n    Register the server with Claude Code. Run this in your terminal, not inside a `claude` session: you're configuring the server before starting a conversation.\n\n    ```bash theme={null}\n    claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp\n    ```\n\n    The parts of the command:\n\n    * `claude mcp add`: registers a server with Claude Code.\n    * `--transport http`: the server is hosted at a URL rather than run as a local process.\n    * `claude-code-docs`: a name you make up. Calling the same server `docs` would work identically. Claude Code uses whatever name you pick to label the server's tools in Claude's output and to refer to the server in commands like `claude mcp remove`.\n    * `https://code.claude.com/docs/mcp`: the URL where the server is hosted.\n\n    The command prints a confirmation like `Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config`. The `local config` part means the server is registered to you, in this project: if you start Claude Code in a different project, this server isn't active there. To register a server once for all your projects, add it at user scope, covered in [Change server scope](#change-server-scope).\n  </Step>\n\n  <Step title=\"Check the connection status\">\n    Confirm the server appears in your server list and check its status:\n\n    ```bash theme={null}\n    claude mcp list\n    ```\n\n    The server appears with a status indicator:\n\n    | Status                             | Meaning                                                                                                                                                                       |\n    | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n    | `✓ Connected`                      | Ready to use. This is what you should see for `claude-code-docs`                                                                                                              |\n    | `! Connected · tools fetch failed` | The server connected but couldn't list its tools. Run `claude mcp get <name>` for the error detail                                                                            |\n    | `! Needs authentication`           | The server is reachable but needs a browser sign-in, or a token passed with `--header`. See [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in) |\n    | `✗ Failed to connect`              | Server didn't respond. See [Troubleshooting](#troubleshooting)                                                                                                                |\n    | `✗ Connection error`               | The connection attempt threw an error. See [Troubleshooting](#troubleshooting)                                                                                                |\n    | `⏸ Pending approval`               | A project-scoped server you haven't approved yet. See [Edit .mcp.json directly](#edit-mcp-json-directly)                                                                      |\n  </Step>\n\n  <Step title=\"Use the server\">\n    Start a session and ask Claude to use the new server by name:\n\n    ```bash theme={null}\n    claude\n    ```\n\n    ```text theme={null}\n    Use the claude-code-docs server to look up what MCP_TIMEOUT does\n    ```\n\n    <Info>\n      You don't normally need to name a server in your prompt, since Claude chooses relevant tools on its own. Naming it here guarantees the demonstration goes through the new server rather than another tool, such as web fetch, that could answer the same question.\n    </Info>\n\n    The first time Claude calls the server, it asks for permission to use the new tool. Approve it to continue. The tool call in Claude's output is labeled with the server name, which is how you confirm the answer came from the MCP server rather than Claude's built-in knowledge.\n  </Step>\n\n  <Step title=\"Remove the server\">\n    This step is optional. When you're done experimenting, you can remove the server:\n\n    ```bash theme={null}\n    claude mcp remove claude-code-docs\n    ```\n\n    <Note>\n      Each connected server takes some space in [Claude's context window](/en/how-claude-code-works#the-context-window) because its tool names and server instructions load into every session. Removing servers you no longer use keeps that space free.\n    </Note>\n  </Step>\n</Steps>\n\n## Where servers are saved\n\nThe `claude mcp add` command writes the server's details to a configuration file. By default it registers the server at `local` scope: private to you, active only in the current project. Pass `--scope user` to register it once for all your projects, or `--scope project` to share it with teammates. [Change server scope](#change-server-scope) walks through both.\n\n<Note>\n  `claude mcp add` works the same in every shell, including PowerShell and Command Prompt. Inside a `claude` session, use the `/mcp` command to check and manage servers you've already added.\n</Note>\n\nThere are other ways to add a server, each covered later on this page:\n\n* [Add a local server](#add-a-local-server): run a program on your machine instead of connecting to a URL.\n* [Edit `.mcp.json` directly](#edit-mcp-json-directly): write the JSON entry yourself instead of using the command.\n* [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in): add a hosted server that needs a browser sign-in before its tools work.\n\n### Find your configuration on disk\n\nThe `claude mcp add` command writes the server to one of three scopes, stored across two files, depending on the `--scope` flag. You don't need to edit these files directly, but knowing where they are helps with debugging and version control.\n\n| Scope     | File                                                   | Available to                             |\n| :-------- | :----------------------------------------------------- | :--------------------------------------- |\n| `local`   | `~/.claude.json`, under the entry for this project     | Only you, only this project. The default |\n| `project` | `.mcp.json` in your project root                       | Everyone who clones the project          |\n| `user`    | `~/.claude.json`, under the top-level `mcpServers` key | Only you, all projects                   |\n\nOn Windows, `~/.claude.json` resolves to `%USERPROFILE%\\.claude.json`, typically `C:\\Users\\YourName\\.claude.json`. If you've set [`CLAUDE_CONFIG_DIR`](/en/env-vars), Claude Code reads `.claude.json` from inside that directory instead.\n\nRun `claude mcp get claude-code-docs` to see which scope holds a server's definition. For how the scopes interact when the same server is defined in more than one, see [MCP installation scopes](/en/mcp#mcp-installation-scopes).\n\n## Change server scope\n\nA server's scope is fixed when you add it, so changing scope means removing the entry and re-adding it at the new one. Both cases below start by removing the local entry from the first walkthrough, so the server has only one definition. If you already removed it at the end of that walkthrough, skip this command:\n\n```bash theme={null}\nclaude mcp remove claude-code-docs --scope local\n```\n\n### Use a server in all your projects\n\nRe-add the server at `user` scope to make it active in every project you open, still private to you:\n\n```bash theme={null}\nclaude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp\n```\n\n### Share a server with your team\n\nRe-add the server at `project` scope, which writes to `.mcp.json` in the project root:\n\n```bash theme={null}\nclaude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp\n```\n\nCommit `.mcp.json` to version control. Teammates who clone the repository and start Claude Code see a prompt to approve the server, then it connects for them too.\n\n## Additional MCP server examples\n\nThe first walkthrough used a hosted server that connects without any sign-in. The examples below cover the other two common shapes, with the same add, check, use flow.\n\n### Add a local server\n\nA local stdio server is a program Claude Code starts as a subprocess on your machine, rather than a service it reaches over a URL. Use one for tools that need access to local resources like a browser, your filesystem, or a database socket.\n\nThe [Playwright MCP server](https://github.com/microsoft/playwright-mcp) is a good one to try: it gives Claude a browser it can navigate, click, and read, and it needs no account. It runs through `npx`, so it requires [Node.js](https://nodejs.org/en/download) 18 or later.\n\n<Steps>\n  <Step title=\"Add the Playwright server\">\n    Register the server with the command Claude Code should run to start it:\n\n    ```bash theme={null}\n    claude mcp add playwright -- npx -y @playwright/mcp@latest\n    ```\n\n    This command differs from the hosted example in three ways:\n\n    * There's no `--transport` flag, because local servers use the default `stdio` transport.\n    * Everything after the `--` separator is the command Claude Code runs to start the server.\n    * `-y` tells `npx` to install the package without prompting.\n\n    Playwright drives whichever Chrome is already installed on your machine. To use a different browser, append `--browser` with the browser name, for example `--browser firefox`, after `@playwright/mcp@latest`.\n  </Step>\n\n  <Step title=\"Check the connection\">\n    The `Added` confirmation means the entry was saved, not that the command runs. Check the connection:\n\n    ```bash theme={null}\n    claude mcp list\n    ```\n\n    The first check can show `✗ Failed to connect` while `npx` downloads the package, so wait a moment and run it again.\n  </Step>\n\n  <Step title=\"Use the browser\">\n    Give Claude a task that needs the browser:\n\n    ```text theme={null}\n    Use playwright to open https://example.com and tell me the page title\n    ```\n\n    A browser window opens so you can watch it work, and the tool calls in Claude's output are labeled with the `playwright` server name and the action, like `browser_navigate`.\n\n    Try pointing it at your local dev server to check that a page still renders after a change, or have it walk through a bug report step by step.\n  </Step>\n</Steps>\n\n### Connect a server that requires sign-in\n\nHosted services like Sentry, Linear, and Notion run their MCP servers behind OAuth: you add the server's URL, then sign in through your browser.\n\nThe steps below use Sentry as the example. To connect a different service, substitute its URL, which you can find in the [Anthropic Directory](/en/mcp#find-and-build-mcp-servers) or the service's documentation.\n\n<Steps>\n  <Step title=\"Add the server\">\n    The `add` command is the same as for the docs server, with Sentry's URL:\n\n    ```bash theme={null}\n    claude mcp add --transport http sentry https://mcp.sentry.dev/mcp\n    ```\n\n    After adding, `claude mcp list` shows the server with `! Needs authentication`. That's expected: the next step completes the sign-in.\n  </Step>\n\n  <Step title=\"Authenticate in your browser\">\n    Start a Claude Code session and open the MCP panel:\n\n    ```text theme={null}\n    /mcp\n    ```\n\n    Select `sentry` from the list, press Enter, and choose `Authenticate`. Your browser opens to Sentry's sign-in page. Approve the connection there.\n\n    Back in Claude Code, the server's status changes to connected. If sign-in fails or the browser doesn't open, see [Troubleshooting](#troubleshooting).\n  </Step>\n\n  <Step title=\"Use the server\">\n    Ask Claude something that needs the service, like `What Sentry projects do I have access to?`, and look for tool calls labeled with the `sentry` server name in its output.\n  </Step>\n</Steps>\n\nServers that authenticate with a static token instead of OAuth take the token at add time with `--header \"Authorization: Bearer <token>\"`. See the [GitHub example](/en/mcp#example-connect-to-github-for-code-reviews) for a worked version.\n\n## Edit .mcp.json directly\n\nEvery file in the [scope table](#find-your-configuration-on-disk) uses the same JSON format for server entries. This section edits `.mcp.json`, the project-scope file. It's the one most worth writing by hand because it's checked into the repository, where it doubles as configuration-as-code for your team.\n\nCreate `.mcp.json` in your project root. The example below defines both servers from this guide, the hosted docs server reached over HTTP and the Playwright server as a local `stdio` process:\n\n```json theme={null}\n{\n  \"mcpServers\": {\n    \"claude-code-docs\": {\n      \"type\": \"http\",\n      \"url\": \"https://code.claude.com/docs/mcp\"\n    },\n    \"playwright\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@playwright/mcp@latest\"]\n    }\n  }\n}\n```\n\nThe fields differ by server type:\n\n* For HTTP servers, `url` is the endpoint Claude Code connects to.\n* For stdio servers, `command` and `args` are the program it runs.\n\nAfter saving the file, start a new Claude Code session in the project. Claude Code reads `.mcp.json` at startup.\n\nThe first time Claude Code sees a project-scoped server, it asks you to approve it. The prompt exists so a repository you clone can't launch processes on your machine without your consent. Approve the prompt, or run `/mcp` to approve later if you missed it.\n\nOnce you've approved, run `/mcp` and check that the servers show as connected. If one shows an error instead, see [Troubleshooting](#troubleshooting).\n\n## Connect from other surfaces\n\nThis guide uses the `claude mcp` CLI commands, but every Claude Code surface can connect to MCP servers:\n\n* **Claude Code desktop app**: add servers through the [Connectors UI](/en/desktop#connect-external-tools).\n* **Claude Desktop chat app**: a separate app from Claude Code. To copy servers from its `claude_desktop_config.json` into the CLI, run `claude mcp add-from-claude-desktop` on macOS or WSL.\n* **VS Code**: see [Connect to external tools with MCP](/en/vs-code#connect-to-external-tools-with-mcp).\n* **Claude Code on the web**: reads `.mcp.json` from your repository. See [Edit .mcp.json directly](#edit-mcp-json-directly).\n* **Claude.ai**: connectors you add at [claude.ai/customize/connectors](https://claude.ai/customize/connectors) load automatically in the CLI when you sign in with that account. See [Use MCP servers from Claude.ai](/en/mcp#use-mcp-servers-from-claude-ai).\n\n## Troubleshooting\n\nIf a server doesn't connect, check its status with `/mcp` inside a session or `claude mcp list` from your shell, then match the symptom below. The `/mcp` panel also lets you reconnect or authenticate without leaving the session.\n\n<AccordionGroup>\n  <Accordion title=\"/mcp shows No MCP servers configured\">\n    Claude Code didn't find any servers for the current directory. The most common causes:\n\n    * You ran `claude mcp add` from a different project. Local-scoped servers are tied to the project where you added them: the repository root, or the exact directory if you weren't in a git repository. Re-add the server from the project you're in now, or add it with `--scope user` so it isn't tied to a project.\n    * You edited a configuration file at the wrong path. The correct files are `~/.claude.json` and `<project>/.mcp.json`. Claude Code doesn't read paths such as `~/.claude/.mcp.json`, `~/.claude/config/mcp.json`, `~/.claude/mcp.json`, or `%APPDATA%\\Claude\\mcp.json`. For user-scoped servers, run `claude mcp add --scope user`, which writes to the `mcpServers` key in `~/.claude.json`; for project-scoped servers, edit `.mcp.json` at the project root.\n  </Accordion>\n\n  <Accordion title=\"Status shows Failed to connect or Connection error\">\n    Both statuses mean the server didn't start or the URL didn't respond. They can also appear for HTTP servers that expect a token rather than the browser sign-in covered in [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in).\n\n    As of v2.1.191, an HTTP server that returns `404 Not Found` shows `MCP endpoint not found at <url>. Check the URL in your MCP config.` when you select the server in `/mcp`, with the URL Claude Code tried. Earlier versions show a generic `Error POSTing to endpoint` message without the URL. Compare the URL to the server's documented MCP endpoint path, then run `claude mcp remove <name>` and re-add with the correct URL.\n\n    For HTTP servers, confirm the URL is reachable from your machine:\n\n    ```bash theme={null}\n    curl -I https://mcp.sentry.dev/mcp\n    ```\n\n    In PowerShell, use `curl.exe` instead of `curl` so the request goes to the real curl binary rather than the `Invoke-WebRequest` alias.\n\n    The response tells you which kind of problem you have:\n\n    * A `404` or `405`: the server is up. Many MCP endpoints answer only POST requests, so this still confirms the URL is reachable from your machine.\n    * A `401` or `403`: the server is up and you need to authenticate. Use the browser sign-in in [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in), or for servers that take a token instead, like GitHub's, pass it with `--header \"Authorization: Bearer <token>\"` on the `claude mcp add` command.\n    * No response at all: check the URL and your network.\n\n    For stdio servers, run the configured command directly in your terminal to see the underlying error. For the Playwright server from this guide, run:\n\n    ```bash theme={null}\n    npx -y @playwright/mcp@latest\n    ```\n\n    What happens next tells you where the problem is:\n\n    * The command starts and waits for input: the server itself works. Run `claude mcp get <name>` and confirm the command shown there matches what you just ran. If the command shown differs from what you typed, you likely omitted the `--` separator before the server command. Remove the server and re-add it with `--` in place. If you wrote `.mcp.json` by hand, check its syntax and location.\n    * The command errors: the message names what's missing, such as Node.js or a browser.\n  </Accordion>\n\n  <Accordion title=\"Connection timed out at startup\">\n    The server took longer than the default 30-second startup timeout. A stdio server's first run can be slow while `npx` downloads the package. Increase the limit with the [`MCP_TIMEOUT`](/en/env-vars) environment variable, in milliseconds:\n\n    ```bash theme={null}\n    MCP_TIMEOUT=60000 claude\n    ```\n\n    In PowerShell, set the variable before the command on the same line:\n\n    ```powershell theme={null}\n    $env:MCP_TIMEOUT = \"60000\"; claude\n    ```\n  </Accordion>\n\n  <Accordion title=\"Server already exists\">\n    You've already added a server with that name at the same scope. Either remove the existing entry first or choose a different name:\n\n    ```bash theme={null}\n    claude mcp remove claude-code-docs\n    ```\n\n    If the name exists at more than one scope, `remove` reports `exists in multiple scopes`. Pass `--scope` to choose which copy to delete, for example `claude mcp remove claude-code-docs --scope local`.\n  </Accordion>\n\n  <Accordion title=\"Server connects but no tools appear\">\n    Run `/mcp` inside a session and select the server to see its tool list. If the list is empty, the server started but didn't register any tools, which usually means it's missing a required environment variable such as an API key.\n\n    Pass the variable with `--env KEY=value` on `claude mcp add`, or in the `env` field of the server's `.mcp.json` entry. The server's documentation lists the variables it needs.\n  </Accordion>\n\n  <Accordion title=\"Changes to .mcp.json don't take effect\">\n    Claude Code reads `.mcp.json` at session start. Exit and restart the session after editing the file.\n\n    If your servers still don't appear, run `/mcp` and look for a parse warning. Claude Code skips malformed entries and shows the offending field there.\n\n    If you previously rejected the server when prompted, reset project approvals:\n\n    ```bash theme={null}\n    claude mcp reset-project-choices\n    ```\n  </Accordion>\n\n  <Accordion title=\"OAuth sign-in fails or browser doesn't open\">\n    Run `/mcp`, select the server, and choose `Authenticate` again. If the browser doesn't open automatically, copy the URL shown in the terminal and open it manually. See [Authenticate with remote MCP servers](/en/mcp#authenticate-with-remote-mcp-servers) for fixed callback ports and pre-configured credentials.\n  </Accordion>\n</AccordionGroup>\n\n## Next steps\n\nWith one server connected, explore the rest of what MCP enables:\n\n* [Find more MCP servers](/en/mcp#find-and-build-mcp-servers) in the Anthropic Directory\n* [Share servers with your team](/en/mcp#mcp-installation-scopes) using installation scopes\n* [Manage MCP access for an organization](/en/managed-mcp) with managed settings and policy controls\n* [Reference MCP resources](/en/mcp#use-mcp-resources) in prompts with @ mentions\n* [Run MCP prompts as commands](/en/mcp#use-mcp-prompts-as-commands) from the `/` menu\n* [Build your own server](https://modelcontextprotocol.io/quickstart/server) with the MCP SDK\n"}]},"uuid":"78ebf1e8-5643-4590-9ad4-499a84eed2f0","timestamp":"2026-07-11T09:47:39.326Z","toolUseResult":{"bytes":23226,"code":200,"codeText":"OK","result":"> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Connect to MCP servers\n\n> Add an MCP server to Claude Code, verify the connection, and find the configuration on disk.\n\nThe [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) lets Claude Code use tools beyond its built-in set, such as searching an issue tracker, querying a database, or controlling a web browser. These tools come from MCP servers, which run on your machine or as hosted services.\n\nThis guide walks you through connecting one MCP server end to end with the Claude Code CLI. By the end, you'll have a server connected and responding, know where its configuration lives on disk, and know how to fix the most common connection errors.\n\n<Note>\n  You can also add MCP servers from other surfaces, including the desktop app, VS Code, and the web. See [Connect from other surfaces](#connect-from-other-surfaces).\n</Note>\n\nFor every way to connect and configure MCP servers in Claude Code, see the [MCP reference](/en/mcp).\n\n## Before you begin\n\nMake sure you have:\n\n* [Claude Code installed](/en/quickstart) and authenticated\n* A terminal open in a project directory. Any directory works, including an empty one.\n\n## Add and verify a server\n\nThe example below connects to the [Claude Code documentation MCP server](https://code.claude.com/docs/mcp), a hosted server with full-text search over the Claude Code docs. It doesn't require authentication or any special configuration, so it works well as a first server to test the setup flow with.\n\nThe steps are the same for any server: add it, check the connection status, then use it in a session, with an optional cleanup step at the end. Some servers add a step, like a browser sign-in, shown in [Additional MCP server examples](#additional-mcp-server-examples). For more servers to connect, browse the [Anthropic Directory](/en/mcp#find-and-build-mcp-servers).\n\n<Steps>\n  <Step title=\"Add the MCP server\">\n    Register the server with Claude Code. Run this in your terminal, not inside a `claude` session: you're configuring the server before starting a conversation.\n\n    ```bash theme={null}\n    claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp\n    ```\n\n    The parts of the command:\n\n    * `claude mcp add`: registers a server with Claude Code.\n    * `--transport http`: the server is hosted at a URL rather than run as a local process.\n    * `claude-code-docs`: a name you make up. Calling the same server `docs` would work identically. Claude Code uses whatever name you pick to label the server's tools in Claude's output and to refer to the server in commands like `claude mcp remove`.\n    * `https://code.claude.com/docs/mcp`: the URL where the server is hosted.\n\n    The command prints a confirmation like `Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config`. The `local config` part means the server is registered to you, in this project: if you start Claude Code in a different project, this server isn't active there. To register a server once for all your projects, add it at user scope, covered in [Change server scope](#change-server-scope).\n  </Step>\n\n  <Step title=\"Check the connection status\">\n    Confirm the server appears in your server list and check its status:\n\n    ```bash theme={null}\n    claude mcp list\n    ```\n\n    The server appears with a status indicator:\n\n    | Status                             | Meaning                                                                                                                                                                       |\n    | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n    | `✓ Connected`                      | Ready to use. This is what you should see for `claude-code-docs`                                                                                                              |\n    | `! Connected · tools fetch failed` | The server connected but couldn't list its tools. Run `claude mcp get <name>` for the error detail                                                                            |\n    | `! Needs authentication`           | The server is reachable but needs a browser sign-in, or a token passed with `--header`. See [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in) |\n    | `✗ Failed to connect`              | Server didn't respond. See [Troubleshooting](#troubleshooting)                                                                                                                |\n    | `✗ Connection error`               | The connection attempt threw an error. See [Troubleshooting](#troubleshooting)                                                                                                |\n    | `⏸ Pending approval`               | A project-scoped server you haven't approved yet. See [Edit .mcp.json directly](#edit-mcp-json-directly)                                                                      |\n  </Step>\n\n  <Step title=\"Use the server\">\n    Start a session and ask Claude to use the new server by name:\n\n    ```bash theme={null}\n    claude\n    ```\n\n    ```text theme={null}\n    Use the claude-code-docs server to look up what MCP_TIMEOUT does\n    ```\n\n    <Info>\n      You don't normally need to name a server in your prompt, since Claude chooses relevant tools on its own. Naming it here guarantees the demonstration goes through the new server rather than another tool, such as web fetch, that could answer the same question.\n    </Info>\n\n    The first time Claude calls the server, it asks for permission to use the new tool. Approve it to continue. The tool call in Claude's output is labeled with the server name, which is how you confirm the answer came from the MCP server rather than Claude's built-in knowledge.\n  </Step>\n\n  <Step title=\"Remove the server\">\n    This step is optional. When you're done experimenting, you can remove the server:\n\n    ```bash theme={null}\n    claude mcp remove claude-code-docs\n    ```\n\n    <Note>\n      Each connected server takes some space in [Claude's context window](/en/how-claude-code-works#the-context-window) because its tool names and server instructions load into every session. Removing servers you no longer use keeps that space free.\n    </Note>\n  </Step>\n</Steps>\n\n## Where servers are saved\n\nThe `claude mcp add` command writes the server's details to a configuration file. By default it registers the server at `local` scope: private to you, active only in the current project. Pass `--scope user` to register it once for all your projects, or `--scope project` to share it with teammates. [Change server scope](#change-server-scope) walks through both.\n\n<Note>\n  `claude mcp add` works the same in every shell, including PowerShell and Command Prompt. Inside a `claude` session, use the `/mcp` command to check and manage servers you've already added.\n</Note>\n\nThere are other ways to add a server, each covered later on this page:\n\n* [Add a local server](#add-a-local-server): run a program on your machine instead of connecting to a URL.\n* [Edit `.mcp.json` directly](#edit-mcp-json-directly): write the JSON entry yourself instead of using the command.\n* [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in): add a hosted server that needs a browser sign-in before its tools work.\n\n### Find your configuration on disk\n\nThe `claude mcp add` command writes the server to one of three scopes, stored across two files, depending on the `--scope` flag. You don't need to edit these files directly, but knowing where they are helps with debugging and version control.\n\n| Scope     | File                                                   | Available to                             |\n| :-------- | :----------------------------------------------------- | :--------------------------------------- |\n| `local`   | `~/.claude.json`, under the entry for this project     | Only you, only this project. The default |\n| `project` | `.mcp.json` in your project root                       | Everyone who clones the project          |\n| `user`    | `~/.claude.json`, under the top-level `mcpServers` key | Only you, all projects                   |\n\nOn Windows, `~/.claude.json` resolves to `%USERPROFILE%\\.claude.json`, typically `C:\\Users\\YourName\\.claude.json`. If you've set [`CLAUDE_CONFIG_DIR`](/en/env-vars), Claude Code reads `.claude.json` from inside that directory instead.\n\nRun `claude mcp get claude-code-docs` to see which scope holds a server's definition. For how the scopes interact when the same server is defined in more than one, see [MCP installation scopes](/en/mcp#mcp-installation-scopes).\n\n## Change server scope\n\nA server's scope is fixed when you add it, so changing scope means removing the entry and re-adding it at the new one. Both cases below start by removing the local entry from the first walkthrough, so the server has only one definition. If you already removed it at the end of that walkthrough, skip this command:\n\n```bash theme={null}\nclaude mcp remove claude-code-docs --scope local\n```\n\n### Use a server in all your projects\n\nRe-add the server at `user` scope to make it active in every project you open, still private to you:\n\n```bash theme={null}\nclaude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp\n```\n\n### Share a server with your team\n\nRe-add the server at `project` scope, which writes to `.mcp.json` in the project root:\n\n```bash theme={null}\nclaude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp\n```\n\nCommit `.mcp.json` to version control. Teammates who clone the repository and start Claude Code see a prompt to approve the server, then it connects for them too.\n\n## Additional MCP server examples\n\nThe first walkthrough used a hosted server that connects without any sign-in. The examples below cover the other two common shapes, with the same add, check, use flow.\n\n### Add a local server\n\nA local stdio server is a program Claude Code starts as a subprocess on your machine, rather than a service it reaches over a URL. Use one for tools that need access to local resources like a browser, your filesystem, or a database socket.\n\nThe [Playwright MCP server](https://github.com/microsoft/playwright-mcp) is a good one to try: it gives Claude a browser it can navigate, click, and read, and it needs no account. It runs through `npx`, so it requires [Node.js](https://nodejs.org/en/download) 18 or later.\n\n<Steps>\n  <Step title=\"Add the Playwright server\">\n    Register the server with the command Claude Code should run to start it:\n\n    ```bash theme={null}\n    claude mcp add playwright -- npx -y @playwright/mcp@latest\n    ```\n\n    This command differs from the hosted example in three ways:\n\n    * There's no `--transport` flag, because local servers use the default `stdio` transport.\n    * Everything after the `--` separator is the command Claude Code runs to start the server.\n    * `-y` tells `npx` to install the package without prompting.\n\n    Playwright drives whichever Chrome is already installed on your machine. To use a different browser, append `--browser` with the browser name, for example `--browser firefox`, after `@playwright/mcp@latest`.\n  </Step>\n\n  <Step title=\"Check the connection\">\n    The `Added` confirmation means the entry was saved, not that the command runs. Check the connection:\n\n    ```bash theme={null}\n    claude mcp list\n    ```\n\n    The first check can show `✗ Failed to connect` while `npx` downloads the package, so wait a moment and run it again.\n  </Step>\n\n  <Step title=\"Use the browser\">\n    Give Claude a task that needs the browser:\n\n    ```text theme={null}\n    Use playwright to open https://example.com and tell me the page title\n    ```\n\n    A browser window opens so you can watch it work, and the tool calls in Claude's output are labeled with the `playwright` server name and the action, like `browser_navigate`.\n\n    Try pointing it at your local dev server to check that a page still renders after a change, or have it walk through a bug report step by step.\n  </Step>\n</Steps>\n\n### Connect a server that requires sign-in\n\nHosted services like Sentry, Linear, and Notion run their MCP servers behind OAuth: you add the server's URL, then sign in through your browser.\n\nThe steps below use Sentry as the example. To connect a different service, substitute its URL, which you can find in the [Anthropic Directory](/en/mcp#find-and-build-mcp-servers) or the service's documentation.\n\n<Steps>\n  <Step title=\"Add the server\">\n    The `add` command is the same as for the docs server, with Sentry's URL:\n\n    ```bash theme={null}\n    claude mcp add --transport http sentry https://mcp.sentry.dev/mcp\n    ```\n\n    After adding, `claude mcp list` shows the server with `! Needs authentication`. That's expected: the next step completes the sign-in.\n  </Step>\n\n  <Step title=\"Authenticate in your browser\">\n    Start a Claude Code session and open the MCP panel:\n\n    ```text theme={null}\n    /mcp\n    ```\n\n    Select `sentry` from the list, press Enter, and choose `Authenticate`. Your browser opens to Sentry's sign-in page. Approve the connection there.\n\n    Back in Claude Code, the server's status changes to connected. If sign-in fails or the browser doesn't open, see [Troubleshooting](#troubleshooting).\n  </Step>\n\n  <Step title=\"Use the server\">\n    Ask Claude something that needs the service, like `What Sentry projects do I have access to?`, and look for tool calls labeled with the `sentry` server name in its output.\n  </Step>\n</Steps>\n\nServers that authenticate with a static token instead of OAuth take the token at add time with `--header \"Authorization: Bearer <token>\"`. See the [GitHub example](/en/mcp#example-connect-to-github-for-code-reviews) for a worked version.\n\n## Edit .mcp.json directly\n\nEvery file in the [scope table](#find-your-configuration-on-disk) uses the same JSON format for server entries. This section edits `.mcp.json`, the project-scope file. It's the one most worth writing by hand because it's checked into the repository, where it doubles as configuration-as-code for your team.\n\nCreate `.mcp.json` in your project root. The example below defines both servers from this guide, the hosted docs server reached over HTTP and the Playwright server as a local `stdio` process:\n\n```json theme={null}\n{\n  \"mcpServers\": {\n    \"claude-code-docs\": {\n      \"type\": \"http\",\n      \"url\": \"https://code.claude.com/docs/mcp\"\n    },\n    \"playwright\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@playwright/mcp@latest\"]\n    }\n  }\n}\n```\n\nThe fields differ by server type:\n\n* For HTTP servers, `url` is the endpoint Claude Code connects to.\n* For stdio servers, `command` and `args` are the program it runs.\n\nAfter saving the file, start a new Claude Code session in the project. Claude Code reads `.mcp.json` at startup.\n\nThe first time Claude Code sees a project-scoped server, it asks you to approve it. The prompt exists so a repository you clone can't launch processes on your machine without your consent. Approve the prompt, or run `/mcp` to approve later if you missed it.\n\nOnce you've approved, run `/mcp` and check that the servers show as connected. If one shows an error instead, see [Troubleshooting](#troubleshooting).\n\n## Connect from other surfaces\n\nThis guide uses the `claude mcp` CLI commands, but every Claude Code surface can connect to MCP servers:\n\n* **Claude Code desktop app**: add servers through the [Connectors UI](/en/desktop#connect-external-tools).\n* **Claude Desktop chat app**: a separate app from Claude Code. To copy servers from its `claude_desktop_config.json` into the CLI, run `claude mcp add-from-claude-desktop` on macOS or WSL.\n* **VS Code**: see [Connect to external tools with MCP](/en/vs-code#connect-to-external-tools-with-mcp).\n* **Claude Code on the web**: reads `.mcp.json` from your repository. See [Edit .mcp.json directly](#edit-mcp-json-directly).\n* **Claude.ai**: connectors you add at [claude.ai/customize/connectors](https://claude.ai/customize/connectors) load automatically in the CLI when you sign in with that account. See [Use MCP servers from Claude.ai](/en/mcp#use-mcp-servers-from-claude-ai).\n\n## Troubleshooting\n\nIf a server doesn't connect, check its status with `/mcp` inside a session or `claude mcp list` from your shell, then match the symptom below. The `/mcp` panel also lets you reconnect or authenticate without leaving the session.\n\n<AccordionGroup>\n  <Accordion title=\"/mcp shows No MCP servers configured\">\n    Claude Code didn't find any servers for the current directory. The most common causes:\n\n    * You ran `claude mcp add` from a different project. Local-scoped servers are tied to the project where you added them: the repository root, or the exact directory if you weren't in a git repository. Re-add the server from the project you're in now, or add it with `--scope user` so it isn't tied to a project.\n    * You edited a configuration file at the wrong path. The correct files are `~/.claude.json` and `<project>/.mcp.json`. Claude Code doesn't read paths such as `~/.claude/.mcp.json`, `~/.claude/config/mcp.json`, `~/.claude/mcp.json`, or `%APPDATA%\\Claude\\mcp.json`. For user-scoped servers, run `claude mcp add --scope user`, which writes to the `mcpServers` key in `~/.claude.json`; for project-scoped servers, edit `.mcp.json` at the project root.\n  </Accordion>\n\n  <Accordion title=\"Status shows Failed to connect or Connection error\">\n    Both statuses mean the server didn't start or the URL didn't respond. They can also appear for HTTP servers that expect a token rather than the browser sign-in covered in [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in).\n\n    As of v2.1.191, an HTTP server that returns `404 Not Found` shows `MCP endpoint not found at <url>. Check the URL in your MCP config.` when you select the server in `/mcp`, with the URL Claude Code tried. Earlier versions show a generic `Error POSTing to endpoint` message without the URL. Compare the URL to the server's documented MCP endpoint path, then run `claude mcp remove <name>` and re-add with the correct URL.\n\n    For HTTP servers, confirm the URL is reachable from your machine:\n\n    ```bash theme={null}\n    curl -I https://mcp.sentry.dev/mcp\n    ```\n\n    In PowerShell, use `curl.exe` instead of `curl` so the request goes to the real curl binary rather than the `Invoke-WebRequest` alias.\n\n    The response tells you which kind of problem you have:\n\n    * A `404` or `405`: the server is up. Many MCP endpoints answer only POST requests, so this still confirms the URL is reachable from your machine.\n    * A `401` or `403`: the server is up and you need to authenticate. Use the browser sign-in in [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in), or for servers that take a token instead, like GitHub's, pass it with `--header \"Authorization: Bearer <token>\"` on the `claude mcp add` command.\n    * No response at all: check the URL and your network.\n\n    For stdio servers, run the configured command directly in your terminal to see the underlying error. For the Playwright server from this guide, run:\n\n    ```bash theme={null}\n    npx -y @playwright/mcp@latest\n    ```\n\n    What happens next tells you where the problem is:\n\n    * The command starts and waits for input: the server itself works. Run `claude mcp get <name>` and confirm the command shown there matches what you just ran. If the command shown differs from what you typed, you likely omitted the `--` separator before the server command. Remove the server and re-add it with `--` in place. If you wrote `.mcp.json` by hand, check its syntax and location.\n    * The command errors: the message names what's missing, such as Node.js or a browser.\n  </Accordion>\n\n  <Accordion title=\"Connection timed out at startup\">\n    The server took longer than the default 30-second startup timeout. A stdio server's first run can be slow while `npx` downloads the package. Increase the limit with the [`MCP_TIMEOUT`](/en/env-vars) environment variable, in milliseconds:\n\n    ```bash theme={null}\n    MCP_TIMEOUT=60000 claude\n    ```\n\n    In PowerShell, set the variable before the command on the same line:\n\n    ```powershell theme={null}\n    $env:MCP_TIMEOUT = \"60000\"; claude\n    ```\n  </Accordion>\n\n  <Accordion title=\"Server already exists\">\n    You've already added a server with that name at the same scope. Either remove the existing entry first or choose a different name:\n\n    ```bash theme={null}\n    claude mcp remove claude-code-docs\n    ```\n\n    If the name exists at more than one scope, `remove` reports `exists in multiple scopes`. Pass `--scope` to choose which copy to delete, for example `claude mcp remove claude-code-docs --scope local`.\n  </Accordion>\n\n  <Accordion title=\"Server connects but no tools appear\">\n    Run `/mcp` inside a session and select the server to see its tool list. If the list is empty, the server started but didn't register any tools, which usually means it's missing a required environment variable such as an API key.\n\n    Pass the variable with `--env KEY=value` on `claude mcp add`, or in the `env` field of the server's `.mcp.json` entry. The server's documentation lists the variables it needs.\n  </Accordion>\n\n  <Accordion title=\"Changes to .mcp.json don't take effect\">\n    Claude Code reads `.mcp.json` at session start. Exit and restart the session after editing the file.\n\n    If your servers still don't appear, run `/mcp` and look for a parse warning. Claude Code skips malformed entries and shows the offending field there.\n\n    If you previously rejected the server when prompted, reset project approvals:\n\n    ```bash theme={null}\n    claude mcp reset-project-choices\n    ```\n  </Accordion>\n\n  <Accordion title=\"OAuth sign-in fails or browser doesn't open\">\n    Run `/mcp`, select the server, and choose `Authenticate` again. If the browser doesn't open automatically, copy the URL shown in the terminal and open it manually. See [Authenticate with remote MCP servers](/en/mcp#authenticate-with-remote-mcp-servers) for fixed callback ports and pre-configured credentials.\n  </Accordion>\n</AccordionGroup>\n\n## Next steps\n\nWith one server connected, explore the rest of what MCP enables:\n\n* [Find more MCP servers](/en/mcp#find-and-build-mcp-servers) in the Anthropic Directory\n* [Share servers with your team](/en/mcp#mcp-installation-scopes) using installation scopes\n* [Manage MCP access for an organization](/en/managed-mcp) with managed settings and policy controls\n* [Reference MCP resources](/en/mcp#use-mcp-resources) in prompts with @ mentions\n* [Run MCP prompts as commands](/en/mcp#use-mcp-prompts-as-commands) from the `/` menu\n* [Build your own server](https://modelcontextprotocol.io/quickstart/server) with the MCP SDK\n","durationMs":594,"url":"https://code.claude.com/docs/en/mcp-quickstart.md"},"sourceToolAssistantUUID":"2777910c-4eed-4a19-ba93-ec464996ff3f","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"78ebf1e8-5643-4590-9ad4-499a84eed2f0","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4MtzguCEMnMDNER7HF","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01D1BduvnYaZQPyJZLR2tadg","name":"WebFetch","input":{"url":"https://code.claude.com/docs/en/permission-modes.md","prompt":"MCP server permissions, permissions.allow, mcp__ tool naming, user scope vs project scope"},"caller":{"type":"direct"}}],"stop_reason":"tool_use","stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":775,"cache_read_input_tokens":14744,"output_tokens":353,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":775},"inference_geo":"not_available","iterations":[{"input_tokens":8,"output_tokens":353,"cache_read_input_tokens":14744,"cache_creation_input_tokens":775,"cache_creation":{"ephemeral_5m_input_tokens":775,"ephemeral_1h_input_tokens":0},"type":"message"}],"speed":"standard"},"diagnostics":null},"requestId":"req_011Ccv4MsWtWLStKHVUonHHN","attributionAgent":"claude-code-guide","type":"assistant","uuid":"ada0c464-1859-42f5-a50b-86383f68e333","timestamp":"2026-07-11T09:47:39.386Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"ada0c464-1859-42f5-a50b-86383f68e333","isSidechain":true,"promptId":"463e84b3-536f-432f-b32a-4fdae6dbed7a","agentId":"a556d2e38a847bf6e","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01D1BduvnYaZQPyJZLR2tadg","type":"tool_result","content":"> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Choose a permission mode\n\n> Control whether Claude asks before editing files or running commands. Cycle modes with Shift+Tab in the CLI or use the mode selector in VS Code, Desktop, and claude.ai.\n\nWhen Claude wants to edit a file, run a shell command, or make a network request, it pauses and asks you to approve the action. Permission modes control how often that pause happens. The mode you pick shapes the flow of a session: Manual mode has you review each action as it comes, while looser modes let Claude work in longer uninterrupted stretches and report back when done. Pick more oversight for sensitive work, or fewer interruptions when you trust the direction.\n\n## Available modes\n\nEach mode makes a different tradeoff between convenience and oversight. The table below shows what Claude can do without a permission prompt in each mode.\n\n| Mode                                                                | What runs without asking                                                               | Best for                                |\n| :------------------------------------------------------------------ | :------------------------------------------------------------------------------------- | :-------------------------------------- |\n| `default`                                                           | Reads only. Labeled **Manual** in the CLI and IDE extensions                           | Getting started, sensitive work         |\n| [`acceptEdits`](#auto-approve-file-edits-with-acceptedits-mode)     | Reads, file edits, and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.) | Iterating on code you're reviewing      |\n| [`plan`](#analyze-before-you-edit-with-plan-mode)                   | Reads only                                                                             | Exploring a codebase before changing it |\n| [`auto`](#eliminate-prompts-with-auto-mode)                         | Everything, with background safety checks                                              | Long tasks, reducing prompt fatigue     |\n| [`dontAsk`](#allow-only-pre-approved-tools-with-dontask-mode)       | Only pre-approved tools                                                                | Locked-down CI and scripts              |\n| [`bypassPermissions`](#skip-all-checks-with-bypasspermissions-mode) | Everything                                                                             | Isolated containers and VMs only        |\n\nThe mode that reviews every action is named **Manual** in the CLI, in `claude --help`, and in the VS Code and JetBrains extensions. Its config value is `default`, which is what hooks and SDK integrations use. The CLI accepts `manual` as an alias wherever you type the value, for example `claude --permission-mode manual` or `\"defaultMode\": \"manual\"`. The Manual label and the `manual` alias require Claude Code v2.1.200 or later.\n\nIn every mode except `bypassPermissions`, writes to [protected paths](#protected-paths) are never auto-approved, guarding repository state and Claude's own configuration against accidental corruption.\n\nModes set the baseline. Layer [permission rules](/en/permissions#manage-permissions) on top to pre-approve or block specific tools. Deny rules and explicit ask rules apply in every mode, including `bypassPermissions`. Allow rules have no effect in that mode because everything else is already approved.\n\n## Switch permission modes\n\nYou can switch modes mid-session, at startup, or as a persistent default. The mode is set through these controls, not by asking Claude in chat. Select your interface below to see how to change it.\n\n<Tabs>\n  <Tab title=\"CLI\">\n    **During a session**: press `Shift+Tab` to cycle `default` → `acceptEdits` → `plan`. The current mode appears in the status bar. {/* min-version: 2.1.203 */}Manual mode, `default` in that cycle, shows a gray `⏸ manual mode on` badge. Before v2.1.203, the status bar showed no badge in Manual mode.\n\n    Not every mode is in the default cycle:\n\n    * `auto`: appears when your account meets the [auto mode requirements](#eliminate-prompts-with-auto-mode); cycling to it switches modes without a confirmation prompt\n    * `bypassPermissions`: appears after you start with `--permission-mode bypassPermissions`, `--dangerously-skip-permissions`, or `--allow-dangerously-skip-permissions`; the `--allow-` variant adds the mode to the cycle without activating it\n    * `dontAsk`: never appears in the cycle; set it with `--permission-mode dontAsk`\n\n    Enabled optional modes slot in after `plan`, with `bypassPermissions` first and `auto` last. If you have both enabled, you will cycle through `bypassPermissions` on the way to `auto`.\n\n    **At startup**: pass the mode as a flag.\n\n    ```bash theme={null}\n    claude --permission-mode plan\n    ```\n\n    **As a default**: set `defaultMode` in [settings](/en/settings#settings-files).\n\n    ```json theme={null}\n    {\n      \"permissions\": {\n        \"defaultMode\": \"acceptEdits\"\n      }\n    }\n    ```\n\n    The same `--permission-mode` flag works with `-p` for [non-interactive runs](/en/headless).\n  </Tab>\n\n  <Tab title=\"VS Code\">\n    **During a session**: click the mode indicator at the bottom of the prompt box.\n\n    **As a default**: set `claudeCode.initialPermissionMode` in VS Code settings, or use the Claude Code extension settings panel.\n\n    The mode indicator shows these labels, mapped to the mode each one applies:\n\n    | UI label           | Mode                |\n    | :----------------- | :------------------ |\n    | Manual             | `default`           |\n    | Edit automatically | `acceptEdits`       |\n    | Plan               | `plan`              |\n    | Auto               | `auto`              |\n    | Bypass permissions | `bypassPermissions` |\n\n    Before v2.1.205, the extension labeled `plan` as Plan mode and `auto` as Auto mode.\n\n    Auto mode appears in the mode indicator when your account meets every requirement listed in the [auto mode section](#eliminate-prompts-with-auto-mode). The `claudeCode.initialPermissionMode` setting does not accept `auto`. To start in auto mode by default, set `defaultMode` in your [user settings](/en/settings#settings-files) instead. Claude Code ignores `defaultMode: \"auto\"` in project and local settings.\n\n    Bypass permissions requires the **Allow dangerously skip permissions** toggle in the extension settings before it appears in the mode indicator.\n\n    See the [VS Code guide](/en/vs-code) for extension-specific details.\n  </Tab>\n\n  <Tab title=\"JetBrains\">\n    The JetBrains plugin runs Claude Code in the IDE terminal, so switching modes works the same as in the CLI: press `Shift+Tab` to cycle, or pass `--permission-mode` when launching.\n  </Tab>\n\n  <Tab title=\"Desktop\">\n    Use the mode selector next to the send button. Auto and Bypass permissions appear only after you enable them in Desktop settings. See the [Desktop guide](/en/desktop#choose-a-permission-mode).\n  </Tab>\n\n  <Tab title=\"Web and mobile\">\n    Use the mode dropdown next to the prompt box on [claude.ai/code](https://claude.ai/code) or in the mobile app. Permission prompts appear in claude.ai for approval. Which modes appear depends on where the session runs:\n\n    * **Cloud sessions** on [Claude Code on the web](/en/claude-code-on-the-web): Accept edits, Plan, and Auto. Accept edits corresponds to `default` mode: the cloud environment pre-approves file edits regardless of mode, so the dropdown shows Accept edits instead of Manual. Cloud sessions still honor `defaultMode: \"acceptEdits\"` from settings. Auto mode appears only when your organization allows it and the selected model supports it. Bypass permissions isn't available.\n    * **[Remote Control](/en/remote-control) sessions** on your local machine: Manual, Accept edits, and Plan. You can't select Auto or Bypass permissions from the app. {/* min-version: 2.1.202 */}The dropdown shows the mode the local session is in, including a mode set from the terminal, and updates when the mode changes in the app or in the terminal. The one exception is Bypass permissions: the session never reports that mode to claude.ai, so switching into it from the terminal doesn't change what the dropdown shows. Before v2.1.202, sessions connected with `/remote-control` or `claude --remote-control` didn't report their mode at all, so claude.ai and the mobile app could show a mode the session wasn't in. The mismatch affected only the label: Claude Code generated permission prompts from the session's actual mode, and they still appeared in the app for approval.\n\n    For Remote Control, you can also set the starting mode when launching the host:\n\n    ```bash theme={null}\n    claude remote-control --permission-mode acceptEdits\n    ```\n  </Tab>\n</Tabs>\n\n## Auto-approve file edits with acceptEdits mode\n\n`acceptEdits` mode lets Claude create and edit files in your working directory without prompting. The status bar shows `⏵⏵ accept edits on` while this mode is active.\n\nIn addition to file edits, `acceptEdits` mode auto-approves common filesystem Bash commands: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, and `sed`. These commands are also auto-approved when prefixed with safe environment variables such as `LANG=C` or `NO_COLOR=1`, or process wrappers such as `timeout`, `nice`, or `nohup`. Like file edits, auto-approval applies only to paths inside your working directory or `additionalDirectories`. Paths outside that scope, writes to [protected paths](#protected-paths), and all other Bash commands still prompt.\n\nWhen the [PowerShell tool](/en/tools-reference#powershell-tool) is enabled, `acceptEdits` mode also auto-approves `Set-Content`, `Add-Content`, `Clear-Content`, and `Remove-Item` on in-scope paths, along with their common aliases. The same scope and protected-path rules apply.\n\nUse `acceptEdits` when you want to review changes in your editor or via `git diff` after the fact rather than approving each edit inline.\n\nPress `Shift+Tab` once from Manual mode to enter it, or start with it directly:\n\n```bash theme={null}\nclaude --permission-mode acceptEdits\n```\n\n## Analyze before you edit with plan mode\n\nPlan mode tells Claude to research and propose changes without making them. Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source. Permission prompts still apply as they do in Manual mode.\n\nEnter plan mode by pressing `Shift+Tab` or prefixing a single prompt with `/plan`. You can also start in plan mode from the CLI:\n\n```bash theme={null}\nclaude --permission-mode plan\n```\n\nPress `Shift+Tab` again to leave plan mode without approving a plan.\n\n### Review and approve a plan\n\nWhen the plan is ready, Claude presents it and asks how to proceed. From that prompt you can:\n\n* Approve and start in auto mode\n* Approve and accept edits\n* Approve and review each edit manually\n* Keep planning with feedback\n* Refine with [Ultraplan](/en/ultraplan) for browser-based review\n\nApproving a plan exits plan mode and switches the session to the permission mode each approve option describes, so Claude starts editing. To plan again, cycle back to plan mode with `Shift+Tab`, or prefix your next prompt with `/plan`.\n\nPress `Ctrl+G` to open the proposed plan in your default text editor and edit it directly before Claude proceeds. When [`showClearContextOnPlanAccept`](/en/settings#available-settings) is enabled, each approve option also offers to clear the planning context first.\n\nAccepting a plan also names the session from the plan content automatically, unless you've already set a name with `--name` or `/rename`.\n\n### Set plan mode as the default\n\nTo make plan mode the default for a project, set `defaultMode` in `.claude/settings.json`:\n\n```json theme={null}\n{\n  \"permissions\": {\n    \"defaultMode\": \"plan\"\n  }\n}\n```\n\n<h2 id=\"eliminate-prompts-with-auto-mode\">\n  Eliminate permission prompts with auto mode\n</h2>\n\n<Note>\n  Auto mode requires Claude Code v2.1.83 or later.\n</Note>\n\nAuto mode lets Claude execute without routine permission prompts. A separate classifier model reviews actions before they run, blocking anything that escalates beyond your request, targets unrecognized infrastructure, or appears driven by hostile content Claude read. Explicit [ask rules](/en/permissions#manage-permissions) still force a prompt.\n\nAuto mode also nudges Claude to keep working without stopping for clarifying questions, though Claude still asks when your prompt or a skill explicitly relies on it. For stronger autonomous behavior while keeping permission prompts, set the [Proactive output style](/en/output-styles) instead.\n\n<Warning>\n  Auto mode reduces permission prompts but does not guarantee safety. Use it for tasks where you trust the general direction, not as a replacement for review on sensitive operations.\n</Warning>\n\nAuto mode is available only when your account meets all of these requirements:\n\n* **Plan**: All plans.\n* **Owner**: on Team and Enterprise, an Owner must enable it in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code) before users can turn it on. Administrators can also lock it off by setting `permissions.disableAutoMode` to `\"disable\"` in [managed settings](/en/permissions#managed-settings).\n* **Model**: on the Anthropic API, Claude Opus 4.6 or later, or Sonnet 4.6 or later. On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and signed-in [Claude apps gateway](/en/claude-apps-gateway) sessions, only Claude Sonnet 5, Opus 4.7, and Opus 4.8. Older models, including Sonnet 4.5, Opus 4.5, Haiku, and claude-3 models, are not supported on any provider.\n* **Provider**: available by default on the Anthropic API. On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and signed-in Claude apps gateway sessions, auto mode is off until you [set `CLAUDE_CODE_ENABLE_AUTO_MODE`](#enable-auto-mode-on-bedrock-agent-platform-or-foundry).\n\nIf Claude Code reports auto mode as unavailable, one of these requirements is unmet; this is not a transient outage. A separate message that names a model and says auto mode \"cannot determine the safety\" of an action is a transient classifier outage; see the [error reference](/en/errors#auto-mode-cannot-determine-the-safety-of-an-action).\n\nIf you set `defaultMode: \"auto\"` in [settings](/en/settings#available-settings) and the session starts in `default` mode with no error, the setting is likely in `.claude/settings.json` or `.claude/settings.local.json`. Claude Code v2.1.142 and later ignore `auto` from those files so a repository cannot grant itself auto mode. Move it to `~/.claude/settings.json`.\n\n### Enable auto mode on Bedrock, Agent Platform, or Foundry\n\nOn [Amazon Bedrock](/en/amazon-bedrock), [Google Cloud's Agent Platform](/en/google-vertex-ai), [Microsoft Foundry](/en/microsoft-foundry), and signed-in [Claude apps gateway](/en/claude-apps-gateway) sessions, auto mode does not appear in the `Shift+Tab` cycle until `CLAUDE_CODE_ENABLE_AUTO_MODE` is set to `1`. The variable works in Claude Code v2.1.158 and later. Only Claude Sonnet 5, Opus 4.7, and Opus 4.8 are supported on these providers.\n\nTo enable it for one developer, add the variable to the `env` block in `~/.claude/settings.json`:\n\n```json theme={null}\n{\n  \"env\": {\n    \"CLAUDE_CODE_ENABLE_AUTO_MODE\": \"1\"\n  }\n}\n```\n\nTo enable it for your organization, add the same `env` block to [managed settings](/en/settings#settings-files).\n\nOnce the variable is set, auto mode appears in the `Shift+Tab` cycle for every session. To make it the default starting mode, also set `\"permissions\": {\"defaultMode\": \"auto\"}` in user or managed settings. On these providers, Claude Code ignores `defaultMode: \"auto\"` unless `CLAUDE_CODE_ENABLE_AUTO_MODE` is also set.\n\nTo prevent developers from enabling auto mode, set `disableAutoMode` to `\"disable\"` in managed settings. This overrides the enable variable.\n\nIf you connect through an [LLM gateway](/en/llm-gateway) configured with `ANTHROPIC_BASE_URL`, auto mode may already be reachable without the enable variable, because the gateway routes requests through the Anthropic API. This does not apply to a signed-in [Claude apps gateway](/en/claude-apps-gateway) session, which is its own provider class and requires the enable variable. The `disableAutoMode` setting applies the same way in either configuration.\n\n### What the classifier blocks by default\n\nThe classifier trusts your working directory and the remotes that were configured for it when the session started. {/* min-version: 2.1.200 */}A remote added or repointed during the session with `git remote add` or `git remote set-url` isn't trusted, and everything else is treated as external until you [configure trusted infrastructure](/en/auto-mode-config). Before v2.1.200, remotes added mid-session were also trusted.\n\n**Blocked by default**:\n\n* Downloading and executing code, like `curl | bash`\n* Sending sensitive data to external endpoints\n* Production deploys and migrations\n* Mass deletion on cloud storage\n* Granting IAM or repo permissions\n* Modifying shared infrastructure\n* Irreversibly destroying files that existed before the session\n* Force push\n* {/* min-version: 2.1.203 */}Pushing to the repository's default branch when the push carries sensitive content such as secrets or personal or entrusted data, carries changes concealed or misdescribed relative to what you asked for, carries content ported in or first read from outside the repository, or routes around a pull request, review, or check you asked for. A plain push to the default branch isn't blocked on its own, and clearing a flagged push requires naming the flagged content or the bypassed review, not only the push. The classifier is one layer: [`permissions.deny` rules](/en/permissions#manage-permissions) apply in every mode and can block pushes to the default branch outright, and the remote's own branch protection still applies. Before v2.1.203, any direct push to the default branch was blocked\n* {/* min-version: 2.1.182 */}`git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop`, or `git stash clear`, which the classifier presumes would discard uncommitted changes\n* `git commit --amend` when the commit at HEAD was not created in this session\n* {/* min-version: 2.1.198 */}From v2.1.198, `git commit --amend` when the commit at HEAD has already been pushed. A message-only reword is not blocked: `--amend -m` with nothing newly staged, on a commit that Claude created during this session\n* `terraform destroy`, `pulumi destroy`, `cdk destroy`, or `terragrunt destroy`, and applying a plan that destroys resources\n\nClaude Code v2.1.195 and later block more categories by default. Several depend on [environment](/en/auto-mode-config#define-trusted-infrastructure) entries, such as sensitive remote targets and protected IaC scopes, that you can narrow to concrete names.\n\n* Writing to a secret manager, or changing DNS records or TLS certificates\n* Merging a pull request no human has approved, approving Claude's own pull request, or disabling CI checks\n* Posting a comment that is itself a command to automation, such as `atlantis apply` or a bot's `/deploy` or `/merge`\n* Toggling, ramping, or deleting a production feature flag\n* Applying infrastructure changes to a protected IaC scope, or draining and removing cluster nodes\n* Writes to a shared compute cluster that reach beyond the resource you named, such as a label selector or `--all` that catches other users' jobs\n* Creating Kubernetes resources that run on every node or intercept cluster traffic, such as DaemonSets and admission webhooks\n* Interactive shells or port-forwards into a sensitive remote target\n* Opening a tunnel or reverse shell that makes a local service reachable from the public internet\n* Printing a live credential or token into the transcript or a file\n* Accessing a location listed as a sensitive data location in your [environment](/en/auto-mode-config#define-trusted-infrastructure), or copying data out of one. {/* min-version: 2.1.198 */}As of v2.1.198 this also blocks sending data from one to an audience the entry excludes\n* Routing a package install around your internal package registry to a public registry. {/* min-version: 2.1.198 */}As of v2.1.198, this also applies when you've told Claude an internal registry or mirror exists in the conversation, not only when one is listed in your environment\n* Running a command with a flag that disarms a safety guard, like `--insecure`\n* Launching an autonomous agent loop that runs without human approval or a sandbox, such as one started with `--dangerously-skip-permissions` or `--no-sandbox`. {/* min-version: 2.1.198 */}As of v2.1.198 this also covers running a third-party agent or eval harness with isolation and per-action approval disabled, such as a runner started with `--yes-always`\n* [Claude in Chrome](/en/chrome) browser actions that could send page content, cookies, or credentials off-origin\n\nClaude Code v2.1.198 and later also block these by default:\n\n* Deleting files in `/tmp`, `$TMPDIR`, or another shared scratch or cache directory by wildcard, glob, or age filter rather than by a specific named path\n* Including sensitive details in content sent, uploaded, published, or written to other people or shared systems, when your own message didn't authorize those details for that recipient. {/* min-version: 2.1.200 */}PR and issue bodies, commit messages, and comments count as this kind of outbound content when the repository is outside the trust boundary or public, including your organization's own public repositories; internal file paths, code names, live API response data such as emails or account identifiers, and infrastructure identifiers count as sensitive details. The PR, issue, and commit-message scoping requires Claude Code v2.1.200 or later. {/* min-version: 2.1.203 */}Live personal data from an API response in a PR or issue body, such as an email address, an account or organization identifier, or a usage metric, requires you to name those details and the recipient regardless of the repository's visibility or trust boundary. That check requires Claude Code v2.1.203 or later\n* Sending keystrokes to Claude Code's own tmux pane to drive its own interface, which the classifier treats as Claude changing its own permissions or oversight\n\nClaude Code v2.1.200 and later also block these by default:\n\n* Commenting out, deleting, or force-passing a test or assertion that guards security behavior, such as auth, access control, input validation, or sandboxing\n* Deleting or tearing down a stateful resource Claude didn't create in the session, when no more specific deletion rule applies and you didn't name that resource\n* Repointing an API base URL, proxy endpoint, webhook receiver, or registry mirror at a third-party host that doesn't fit the task, including in example files like `.env.example`\n* Changing where pushes go with `git remote set-url` or `git remote add`, unless you named the new remote\n* Pushing secrets or personal or entrusted data to a repository known to be public, or pushing confidential material there that isn't part of that repository's own work. {/* min-version: 2.1.203 */}A dotfiles repository's own subject matter is the one exception for personal or entrusted data, and content from a private repository reaching any public surface is blocked the same way; both refinements require Claude Code v2.1.203 or later. Before v2.1.203, personal data was grouped with confidential material and blocked only when it wasn't part of that repository's own work. When a repository's visibility isn't established, the classifier doesn't block on that alone; it judges the content against the other rules instead\n* Opening a pull request against a different repository or organization, forking with `gh repo fork`, or pushing to a third-party repository, unless you named that external target\n\nClaude Code v2.1.203 and later also block these by default:\n\n* Content from a sensitive local store, or from a file whose name, path, or type marks it as sensitive, entering a commit, a push, PR or issue text, a gist or paste, or a package publish, unless you named both the source and the destination. Session transcripts and conversation logs, credential and configuration dot-folders such as SSH keys, cloud credentials, browser profiles, and shell history, and user-data exports all count, and the repository being private doesn't clear it\n\nClaude Code v2.1.205 and later also block these by default:\n\n* Writing to Claude Code session transcripts, the `.jsonl` history files under `~/.claude/projects/` or your configured config directory, whether directly or through a shell command. The rule also covers the metadata lines Claude Code appends to each transcript entry for its own checks. A transcript is session state that Claude Code writes, not a working file, and a tampered entry reaches every later check once you resume the session, so auto mode blocks these writes as defense in depth. Reading a transcript isn't blocked\n* A recursive forced delete such as `rm -rf \"$VAR\"` or `Remove-Item -Recurse -Force $dir` whose target is a shell variable, or a glob rooted at one, that isn't assigned anywhere in the conversation the classifier sees. The value came only from earlier command output, which the classifier never receives, so the classifier can't verify the deletion target against the other deletion rules. The classifier reads the conversation rather than command output by design, so it blocks the call instead of guessing at the target. The block clears when you name the exact path being deleted, or when Claude re-runs the delete with the resolved literal path written into the command. Deletes whose target the classifier can resolve aren't affected\n\n**Allowed by default**:\n\n* Local file operations in your working directory\n* Installing dependencies declared in your lock files or manifests\n* Reading `.env` and sending credentials to their matching API\n* Read-only HTTP requests\n* Pushing to the branch you started on or one Claude created\n\nClaude Code v2.1.195 and later also allow these by default:\n\n* Deleting the exact jobs Claude created earlier in the same session\n* Reading, reviewing, or writing security-related code, configs, and threat models as part of your task\n* Messages between agents working together in the same multi-agent session\n* Sending data to the trusted domains, buckets, and services you list in [`environment`](/en/auto-mode-config#define-trusted-infrastructure). This covers data flow only, not destructive or credential operations on the same infrastructure\n* [Claude in Chrome](/en/chrome) navigation to a trusted internal domain, localhost, or a URL you named\n\nSandbox network access requests are routed through the classifier rather than allowed by default. {/* min-version: 2.1.198 */}As of v2.1.198, the classifier reuses its verdict for a network host and port instead of re-running on every connection:\n\n* An allow is reused until new content enters the conversation, at which point that host is checked again\n* In the interactive CLI, a deny is dropped when the turn ends\n* In [non-interactive mode](/en/headless) and Agent SDK sessions there is no turn boundary, so a deny is reused for the rest of the run\n* Changing your permission mode or rules drops all cached verdicts\n\nRun `claude auto-mode defaults` to see the full rule lists. If routine actions get blocked, an administrator can add trusted repos, buckets, and services via the `autoMode.environment` setting: see [Configure auto mode](/en/auto-mode-config).\n\n### Boundaries you state in conversation\n\nThe classifier treats boundaries you state in the conversation as a block signal. If you tell Claude \"don't push\" or \"wait until I review before deploying\", the classifier blocks matching actions even when the default rules would allow them. A boundary stays in force until you lift it in a later message. Claude's own judgment that a condition was met does not lift it.\n\nBoundaries are not stored as rules. The classifier re-reads them from the transcript on each check, so a boundary can be lost if [context compaction](/en/costs#reduce-token-usage) removes the message that stated it. For a hard guarantee, add a [deny rule](/en/permissions#permission-rule-syntax) instead.\n\n### When auto mode falls back\n\nEach denied action shows a notification and appears in `/permissions` under the Recently denied tab, where you can press `r` to retry it with a manual approval.\n\nIf the classifier blocks an action 3 times in a row or 20 times total, auto mode pauses and Claude Code resumes prompting. Approving the prompted action resumes auto mode. These thresholds are not configurable. Any allowed action resets the consecutive counter, while the total counter persists for the session and resets only when its own limit triggers a fallback.\n\nIn [non-interactive mode](/en/headless) with the `-p` flag, repeated blocks abort the session since there is no user to prompt.\n\nRepeated blocks usually mean the classifier is missing context about your infrastructure. Use `/feedback` to report false positives, or have an administrator [configure trusted infrastructure](/en/auto-mode-config).\n\n<AccordionGroup>\n  <Accordion title=\"How the classifier evaluates actions\">\n    Each action goes through a fixed decision order. The first matching step wins:\n\n    1. Actions matching your [allow or deny rules](/en/permissions#manage-permissions) resolve immediately, except writes to [protected paths](#protected-paths), which route to the classifier even when an allow rule matches\n    2. Read-only actions and file edits in your working directory are auto-approved, except writes to [protected paths](#protected-paths)\n    3. Everything else goes to the classifier. {/* min-version: 2.1.199 */}As of v2.1.199, an MCP tool marked with [`_meta[\"anthropic/requiresUserInteraction\"]`](/en/mcp#require-approval-for-a-specific-tool) skips the classifier and prompts you directly, so a consent step is never auto-approved on the tool author's behalf\n    4. If the classifier blocks, Claude receives the reason and tries an alternative\n\n    On entering auto mode, broad allow rules that grant arbitrary code execution are dropped:\n\n    * Blanket `Bash(*)` or `PowerShell(*)`\n    * Wildcarded interpreters like `Bash(python*)`\n    * Package-manager run commands\n    * `Agent` allow rules\n\n    Narrow rules like `Bash(npm test)` carry over. Dropped rules are restored when you leave auto mode.\n\n    The classifier sees user messages, tool calls, and your CLAUDE.md content. Tool results are stripped, so hostile content in a file or web page cannot manipulate it directly. A separate server-side probe scans incoming tool results and flags suspicious content before Claude reads it. For more on how these layers work together, see the [auto mode announcement](https://claude.com/blog/auto-mode) and the [engineering deep dive](https://www.anthropic.com/engineering/claude-code-auto-mode).\n  </Accordion>\n\n  <Accordion title=\"How auto mode handles subagents\">\n    The classifier checks [subagent](/en/sub-agents) work at three points:\n\n    1. Before a subagent starts, the delegated task description is evaluated, so a dangerous-looking task is blocked at spawn time.\n    2. While the subagent runs, each of its actions goes through the classifier with the same rules as the parent session, and any `permissionMode` in the subagent's frontmatter is ignored.\n    3. When the subagent finishes, the classifier reviews its full action history; if that return check flags a concern, a security warning is prepended to the subagent's results.\n\n    Step 1 requires Claude Code v2.1.178 or later. Earlier versions applied the classifier at steps 2 and 3, but did not evaluate the task description before the subagent started.\n  </Accordion>\n\n  <Accordion title=\"Cost and latency\">\n    The classifier runs on a server-configured model that is independent of your `/model` selection, so switching models does not change classifier availability. Classifier calls count toward your token usage. Each check sends a portion of the transcript plus the pending action, adding a round-trip before execution. Reads and working-directory edits outside protected paths skip the classifier, so the overhead comes mainly from shell commands and network operations. {/* min-version: 2.1.198 */}As of v2.1.198, a sandbox network verdict for a host and port is reused instead of re-classified on every connection, so repeated connections to the same host don't each add a check. [What the classifier blocks by default](#what-the-classifier-blocks-by-default) describes how long an allow and a deny last.\n  </Accordion>\n</AccordionGroup>\n\n## Allow only pre-approved tools with dontAsk mode\n\n`dontAsk` mode auto-denies every tool call that would otherwise prompt. The status bar shows `⏵⏵ don't ask on` while this mode is active. Only actions matching your `permissions.allow` rules and [read-only Bash commands](/en/permissions#read-only-commands) can execute; explicit [`ask` rules](/en/permissions#manage-permissions) are denied rather than prompting. {/* min-version: 2.1.199 */}As of v2.1.199, an MCP tool marked with [`_meta[\"anthropic/requiresUserInteraction\"]`](/en/mcp#require-approval-for-a-specific-tool) is also denied in this mode even when an allow rule matches it, because its approval card needs an answer this mode never collects. This makes the mode fully non-interactive for CI pipelines or restricted environments where you pre-define exactly what Claude may do. Cloud sessions on [Claude Code on the web](/en/claude-code-on-the-web) ignore `defaultMode: \"dontAsk\"`; see [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) for details.\n\nSet it at startup with the flag:\n\n```bash theme={null}\nclaude --permission-mode dontAsk\n```\n\n## Skip all checks with bypassPermissions mode\n\n`bypassPermissions` mode disables permission prompts and safety checks so tool calls execute immediately. As of v2.1.126 this includes writes to [protected paths](#protected-paths), which earlier versions still prompted for. Explicit [ask rules](/en/permissions#manage-permissions) still force a prompt in this mode, and removals targeting the filesystem root or home directory, such as `rm -rf /` and `rm -rf ~`, still prompt as a circuit breaker against model error. {/* min-version: 2.1.199 */}As of v2.1.199, MCP tools marked with [`_meta[\"anthropic/requiresUserInteraction\"]`](/en/mcp#require-approval-for-a-specific-tool) also still prompt. Only use this mode in isolated environments like containers, VMs, or dev containers without internet access, where Claude Code cannot damage your host system.\n\nYou cannot enter `bypassPermissions` from a session that was started without one of the enabling flags; restart with one to enable it:\n\n```bash theme={null}\nclaude --permission-mode bypassPermissions\n```\n\nThe `--dangerously-skip-permissions` flag is equivalent.\n\nOn Linux and macOS, Claude Code refuses to start in this mode when running as root or under `sudo`:\n\n```text theme={null}\n--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons\n```\n\nThe check is skipped automatically inside a recognized sandbox. To run autonomously in a container, use the [dev container](/en/devcontainer) configuration, which runs Claude Code as a non-root user.\n\n[Claude Code on the web](/en/claude-code-on-the-web) does not honor `defaultMode: \"bypassPermissions\"` or `\"dontAsk\"` from your settings files, so a repository's checked-in settings cannot start a cloud session in bypass-permissions mode. The setting is ignored silently and the session starts in the mode shown in the mode dropdown instead. See [Switch permission modes](#switch-permission-modes) for which modes cloud sessions offer.\n\n<Warning>\n  `bypassPermissions` offers no protection against prompt injection or unintended actions. For background safety checks with far fewer permission prompts, use [auto mode](#eliminate-prompts-with-auto-mode) instead. Administrators can block this mode by setting `permissions.disableBypassPermissionsMode` to `\"disable\"` in [managed settings](/en/permissions#managed-settings).\n</Warning>\n\n## Protected paths\n\nWrites to a small set of paths are never auto-approved, in every mode except `bypassPermissions`. This prevents accidental corruption of repository state and Claude's own configuration.\n\n| Mode                             | Protected-path writes    |\n| :------------------------------- | :----------------------- |\n| `default`, `acceptEdits`, `plan` | Prompted                 |\n| `auto`                           | Routed to the classifier |\n| `dontAsk`                        | Denied                   |\n| `bypassPermissions`              | Allowed                  |\n\n[`permissions.allow`](/en/permissions#manage-permissions) rules in settings files do not pre-approve protected-path writes. The safety check runs before Claude Code evaluates allow rules from settings, so an entry such as `Edit(.claude/**)` in `~/.claude/settings.json` or `.claude/settings.json` does not change the per-mode outcome in the table above. In modes that prompt, the prompt for a `.claude/` write offers **Yes, and allow Claude to edit its own settings for this session**, which approves later `.claude/` writes in that session without prompting again.\n\nProtected directories:\n\n* `.git`\n* `.config/git`\n* `.vscode`\n* `.idea`\n* `.husky`\n* `.cargo`\n* `.devcontainer`\n* `.yarn`\n* `.mvn`\n* `.claude`, except for `.claude/worktrees` where Claude stores its own git worktrees\n\nProtected files:\n\n* `.gitconfig`, `.gitmodules`\n* `.bashrc`, `.bash_profile`, `.bash_login`, `.bash_aliases`, `.bash_logout`, `.zshrc`, `.zprofile`, `.zshenv`, `.zlogin`, `.zlogout`, `.profile`, `.envrc`\n* `.npmrc`, `.yarnrc`, `.yarnrc.yml`, `.pnp.cjs`, `.pnp.loader.mjs`, `.pnpmfile.cjs`, `bunfig.toml`, `.bunfig.toml`\n* `.bazelrc`, `.bazelversion`, `.bazeliskrc`\n* `.pre-commit-config.yaml`, `lefthook.yml`, `lefthook.yaml`, `.lefthook.yml`, `.lefthook.yaml`\n* `gradle-wrapper.properties`, `maven-wrapper.properties`\n* `.devcontainer.json`\n* `.ripgreprc`, `pyrightconfig.json`\n* `.mcp.json`, `.claude.json`\n\n## See also\n\n* [Permissions](/en/permissions): allow, ask, and deny rules; managed policies\n* [Configure auto mode](/en/auto-mode-config): tell the classifier which infrastructure your organization trusts\n* [Hooks](/en/hooks): custom permission logic via `PreToolUse` and `PermissionRequest` hooks\n* [Ultraplan](/en/ultraplan): run plan mode in a Claude Code on the web session with browser-based review\n* [Security](/en/security): safeguards and best practices\n* [Sandboxing](/en/sandboxing): filesystem and network isolation for Bash commands\n* [Non-interactive mode](/en/headless): run Claude Code with the `-p` flag\n"}]},"uuid":"e9c485e7-4ab5-4a81-a231-901758d65a78","timestamp":"2026-07-11T09:47:39.695Z","toolUseResult":{"bytes":39042,"code":200,"codeText":"OK","result":"> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Choose a permission mode\n\n> Control whether Claude asks before editing files or running commands. Cycle modes with Shift+Tab in the CLI or use the mode selector in VS Code, Desktop, and claude.ai.\n\nWhen Claude wants to edit a file, run a shell command, or make a network request, it pauses and asks you to approve the action. Permission modes control how often that pause happens. The mode you pick shapes the flow of a session: Manual mode has you review each action as it comes, while looser modes let Claude work in longer uninterrupted stretches and report back when done. Pick more oversight for sensitive work, or fewer interruptions when you trust the direction.\n\n## Available modes\n\nEach mode makes a different tradeoff between convenience and oversight. The table below shows what Claude can do without a permission prompt in each mode.\n\n| Mode                                                                | What runs without asking                                                               | Best for                                |\n| :------------------------------------------------------------------ | :------------------------------------------------------------------------------------- | :-------------------------------------- |\n| `default`                                                           | Reads only. Labeled **Manual** in the CLI and IDE extensions                           | Getting started, sensitive work         |\n| [`acceptEdits`](#auto-approve-file-edits-with-acceptedits-mode)     | Reads, file edits, and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.) | Iterating on code you're reviewing      |\n| [`plan`](#analyze-before-you-edit-with-plan-mode)                   | Reads only                                                                             | Exploring a codebase before changing it |\n| [`auto`](#eliminate-prompts-with-auto-mode)                         | Everything, with background safety checks                                              | Long tasks, reducing prompt fatigue     |\n| [`dontAsk`](#allow-only-pre-approved-tools-with-dontask-mode)       | Only pre-approved tools                                                                | Locked-down CI and scripts              |\n| [`bypassPermissions`](#skip-all-checks-with-bypasspermissions-mode) | Everything                                                                             | Isolated containers and VMs only        |\n\nThe mode that reviews every action is named **Manual** in the CLI, in `claude --help`, and in the VS Code and JetBrains extensions. Its config value is `default`, which is what hooks and SDK integrations use. The CLI accepts `manual` as an alias wherever you type the value, for example `claude --permission-mode manual` or `\"defaultMode\": \"manual\"`. The Manual label and the `manual` alias require Claude Code v2.1.200 or later.\n\nIn every mode except `bypassPermissions`, writes to [protected paths](#protected-paths) are never auto-approved, guarding repository state and Claude's own configuration against accidental corruption.\n\nModes set the baseline. Layer [permission rules](/en/permissions#manage-permissions) on top to pre-approve or block specific tools. Deny rules and explicit ask rules apply in every mode, including `bypassPermissions`. Allow rules have no effect in that mode because everything else is already approved.\n\n## Switch permission modes\n\nYou can switch modes mid-session, at startup, or as a persistent default. The mode is set through these controls, not by asking Claude in chat. Select your interface below to see how to change it.\n\n<Tabs>\n  <Tab title=\"CLI\">\n    **During a session**: press `Shift+Tab` to cycle `default` → `acceptEdits` → `plan`. The current mode appears in the status bar. {/* min-version: 2.1.203 */}Manual mode, `default` in that cycle, shows a gray `⏸ manual mode on` badge. Before v2.1.203, the status bar showed no badge in Manual mode.\n\n    Not every mode is in the default cycle:\n\n    * `auto`: appears when your account meets the [auto mode requirements](#eliminate-prompts-with-auto-mode); cycling to it switches modes without a confirmation prompt\n    * `bypassPermissions`: appears after you start with `--permission-mode bypassPermissions`, `--dangerously-skip-permissions`, or `--allow-dangerously-skip-permissions`; the `--allow-` variant adds the mode to the cycle without activating it\n    * `dontAsk`: never appears in the cycle; set it with `--permission-mode dontAsk`\n\n    Enabled optional modes slot in after `plan`, with `bypassPermissions` first and `auto` last. If you have both enabled, you will cycle through `bypassPermissions` on the way to `auto`.\n\n    **At startup**: pass the mode as a flag.\n\n    ```bash theme={null}\n    claude --permission-mode plan\n    ```\n\n    **As a default**: set `defaultMode` in [settings](/en/settings#settings-files).\n\n    ```json theme={null}\n    {\n      \"permissions\": {\n        \"defaultMode\": \"acceptEdits\"\n      }\n    }\n    ```\n\n    The same `--permission-mode` flag works with `-p` for [non-interactive runs](/en/headless).\n  </Tab>\n\n  <Tab title=\"VS Code\">\n    **During a session**: click the mode indicator at the bottom of the prompt box.\n\n    **As a default**: set `claudeCode.initialPermissionMode` in VS Code settings, or use the Claude Code extension settings panel.\n\n    The mode indicator shows these labels, mapped to the mode each one applies:\n\n    | UI label           | Mode                |\n    | :----------------- | :------------------ |\n    | Manual             | `default`           |\n    | Edit automatically | `acceptEdits`       |\n    | Plan               | `plan`              |\n    | Auto               | `auto`              |\n    | Bypass permissions | `bypassPermissions` |\n\n    Before v2.1.205, the extension labeled `plan` as Plan mode and `auto` as Auto mode.\n\n    Auto mode appears in the mode indicator when your account meets every requirement listed in the [auto mode section](#eliminate-prompts-with-auto-mode). The `claudeCode.initialPermissionMode` setting does not accept `auto`. To start in auto mode by default, set `defaultMode` in your [user settings](/en/settings#settings-files) instead. Claude Code ignores `defaultMode: \"auto\"` in project and local settings.\n\n    Bypass permissions requires the **Allow dangerously skip permissions** toggle in the extension settings before it appears in the mode indicator.\n\n    See the [VS Code guide](/en/vs-code) for extension-specific details.\n  </Tab>\n\n  <Tab title=\"JetBrains\">\n    The JetBrains plugin runs Claude Code in the IDE terminal, so switching modes works the same as in the CLI: press `Shift+Tab` to cycle, or pass `--permission-mode` when launching.\n  </Tab>\n\n  <Tab title=\"Desktop\">\n    Use the mode selector next to the send button. Auto and Bypass permissions appear only after you enable them in Desktop settings. See the [Desktop guide](/en/desktop#choose-a-permission-mode).\n  </Tab>\n\n  <Tab title=\"Web and mobile\">\n    Use the mode dropdown next to the prompt box on [claude.ai/code](https://claude.ai/code) or in the mobile app. Permission prompts appear in claude.ai for approval. Which modes appear depends on where the session runs:\n\n    * **Cloud sessions** on [Claude Code on the web](/en/claude-code-on-the-web): Accept edits, Plan, and Auto. Accept edits corresponds to `default` mode: the cloud environment pre-approves file edits regardless of mode, so the dropdown shows Accept edits instead of Manual. Cloud sessions still honor `defaultMode: \"acceptEdits\"` from settings. Auto mode appears only when your organization allows it and the selected model supports it. Bypass permissions isn't available.\n    * **[Remote Control](/en/remote-control) sessions** on your local machine: Manual, Accept edits, and Plan. You can't select Auto or Bypass permissions from the app. {/* min-version: 2.1.202 */}The dropdown shows the mode the local session is in, including a mode set from the terminal, and updates when the mode changes in the app or in the terminal. The one exception is Bypass permissions: the session never reports that mode to claude.ai, so switching into it from the terminal doesn't change what the dropdown shows. Before v2.1.202, sessions connected with `/remote-control` or `claude --remote-control` didn't report their mode at all, so claude.ai and the mobile app could show a mode the session wasn't in. The mismatch affected only the label: Claude Code generated permission prompts from the session's actual mode, and they still appeared in the app for approval.\n\n    For Remote Control, you can also set the starting mode when launching the host:\n\n    ```bash theme={null}\n    claude remote-control --permission-mode acceptEdits\n    ```\n  </Tab>\n</Tabs>\n\n## Auto-approve file edits with acceptEdits mode\n\n`acceptEdits` mode lets Claude create and edit files in your working directory without prompting. The status bar shows `⏵⏵ accept edits on` while this mode is active.\n\nIn addition to file edits, `acceptEdits` mode auto-approves common filesystem Bash commands: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, and `sed`. These commands are also auto-approved when prefixed with safe environment variables such as `LANG=C` or `NO_COLOR=1`, or process wrappers such as `timeout`, `nice`, or `nohup`. Like file edits, auto-approval applies only to paths inside your working directory or `additionalDirectories`. Paths outside that scope, writes to [protected paths](#protected-paths), and all other Bash commands still prompt.\n\nWhen the [PowerShell tool](/en/tools-reference#powershell-tool) is enabled, `acceptEdits` mode also auto-approves `Set-Content`, `Add-Content`, `Clear-Content`, and `Remove-Item` on in-scope paths, along with their common aliases. The same scope and protected-path rules apply.\n\nUse `acceptEdits` when you want to review changes in your editor or via `git diff` after the fact rather than approving each edit inline.\n\nPress `Shift+Tab` once from Manual mode to enter it, or start with it directly:\n\n```bash theme={null}\nclaude --permission-mode acceptEdits\n```\n\n## Analyze before you edit with plan mode\n\nPlan mode tells Claude to research and propose changes without making them. Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source. Permission prompts still apply as they do in Manual mode.\n\nEnter plan mode by pressing `Shift+Tab` or prefixing a single prompt with `/plan`. You can also start in plan mode from the CLI:\n\n```bash theme={null}\nclaude --permission-mode plan\n```\n\nPress `Shift+Tab` again to leave plan mode without approving a plan.\n\n### Review and approve a plan\n\nWhen the plan is ready, Claude presents it and asks how to proceed. From that prompt you can:\n\n* Approve and start in auto mode\n* Approve and accept edits\n* Approve and review each edit manually\n* Keep planning with feedback\n* Refine with [Ultraplan](/en/ultraplan) for browser-based review\n\nApproving a plan exits plan mode and switches the session to the permission mode each approve option describes, so Claude starts editing. To plan again, cycle back to plan mode with `Shift+Tab`, or prefix your next prompt with `/plan`.\n\nPress `Ctrl+G` to open the proposed plan in your default text editor and edit it directly before Claude proceeds. When [`showClearContextOnPlanAccept`](/en/settings#available-settings) is enabled, each approve option also offers to clear the planning context first.\n\nAccepting a plan also names the session from the plan content automatically, unless you've already set a name with `--name` or `/rename`.\n\n### Set plan mode as the default\n\nTo make plan mode the default for a project, set `defaultMode` in `.claude/settings.json`:\n\n```json theme={null}\n{\n  \"permissions\": {\n    \"defaultMode\": \"plan\"\n  }\n}\n```\n\n<h2 id=\"eliminate-prompts-with-auto-mode\">\n  Eliminate permission prompts with auto mode\n</h2>\n\n<Note>\n  Auto mode requires Claude Code v2.1.83 or later.\n</Note>\n\nAuto mode lets Claude execute without routine permission prompts. A separate classifier model reviews actions before they run, blocking anything that escalates beyond your request, targets unrecognized infrastructure, or appears driven by hostile content Claude read. Explicit [ask rules](/en/permissions#manage-permissions) still force a prompt.\n\nAuto mode also nudges Claude to keep working without stopping for clarifying questions, though Claude still asks when your prompt or a skill explicitly relies on it. For stronger autonomous behavior while keeping permission prompts, set the [Proactive output style](/en/output-styles) instead.\n\n<Warning>\n  Auto mode reduces permission prompts but does not guarantee safety. Use it for tasks where you trust the general direction, not as a replacement for review on sensitive operations.\n</Warning>\n\nAuto mode is available only when your account meets all of these requirements:\n\n* **Plan**: All plans.\n* **Owner**: on Team and Enterprise, an Owner must enable it in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code) before users can turn it on. Administrators can also lock it off by setting `permissions.disableAutoMode` to `\"disable\"` in [managed settings](/en/permissions#managed-settings).\n* **Model**: on the Anthropic API, Claude Opus 4.6 or later, or Sonnet 4.6 or later. On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and signed-in [Claude apps gateway](/en/claude-apps-gateway) sessions, only Claude Sonnet 5, Opus 4.7, and Opus 4.8. Older models, including Sonnet 4.5, Opus 4.5, Haiku, and claude-3 models, are not supported on any provider.\n* **Provider**: available by default on the Anthropic API. On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and signed-in Claude apps gateway sessions, auto mode is off until you [set `CLAUDE_CODE_ENABLE_AUTO_MODE`](#enable-auto-mode-on-bedrock-agent-platform-or-foundry).\n\nIf Claude Code reports auto mode as unavailable, one of these requirements is unmet; this is not a transient outage. A separate message that names a model and says auto mode \"cannot determine the safety\" of an action is a transient classifier outage; see the [error reference](/en/errors#auto-mode-cannot-determine-the-safety-of-an-action).\n\nIf you set `defaultMode: \"auto\"` in [settings](/en/settings#available-settings) and the session starts in `default` mode with no error, the setting is likely in `.claude/settings.json` or `.claude/settings.local.json`. Claude Code v2.1.142 and later ignore `auto` from those files so a repository cannot grant itself auto mode. Move it to `~/.claude/settings.json`.\n\n### Enable auto mode on Bedrock, Agent Platform, or Foundry\n\nOn [Amazon Bedrock](/en/amazon-bedrock), [Google Cloud's Agent Platform](/en/google-vertex-ai), [Microsoft Foundry](/en/microsoft-foundry), and signed-in [Claude apps gateway](/en/claude-apps-gateway) sessions, auto mode does not appear in the `Shift+Tab` cycle until `CLAUDE_CODE_ENABLE_AUTO_MODE` is set to `1`. The variable works in Claude Code v2.1.158 and later. Only Claude Sonnet 5, Opus 4.7, and Opus 4.8 are supported on these providers.\n\nTo enable it for one developer, add the variable to the `env` block in `~/.claude/settings.json`:\n\n```json theme={null}\n{\n  \"env\": {\n    \"CLAUDE_CODE_ENABLE_AUTO_MODE\": \"1\"\n  }\n}\n```\n\nTo enable it for your organization, add the same `env` block to [managed settings](/en/settings#settings-files).\n\nOnce the variable is set, auto mode appears in the `Shift+Tab` cycle for every session. To make it the default starting mode, also set `\"permissions\": {\"defaultMode\": \"auto\"}` in user or managed settings. On these providers, Claude Code ignores `defaultMode: \"auto\"` unless `CLAUDE_CODE_ENABLE_AUTO_MODE` is also set.\n\nTo prevent developers from enabling auto mode, set `disableAutoMode` to `\"disable\"` in managed settings. This overrides the enable variable.\n\nIf you connect through an [LLM gateway](/en/llm-gateway) configured with `ANTHROPIC_BASE_URL`, auto mode may already be reachable without the enable variable, because the gateway routes requests through the Anthropic API. This does not apply to a signed-in [Claude apps gateway](/en/claude-apps-gateway) session, which is its own provider class and requires the enable variable. The `disableAutoMode` setting applies the same way in either configuration.\n\n### What the classifier blocks by default\n\nThe classifier trusts your working directory and the remotes that were configured for it when the session started. {/* min-version: 2.1.200 */}A remote added or repointed during the session with `git remote add` or `git remote set-url` isn't trusted, and everything else is treated as external until you [configure trusted infrastructure](/en/auto-mode-config). Before v2.1.200, remotes added mid-session were also trusted.\n\n**Blocked by default**:\n\n* Downloading and executing code, like `curl | bash`\n* Sending sensitive data to external endpoints\n* Production deploys and migrations\n* Mass deletion on cloud storage\n* Granting IAM or repo permissions\n* Modifying shared infrastructure\n* Irreversibly destroying files that existed before the session\n* Force push\n* {/* min-version: 2.1.203 */}Pushing to the repository's default branch when the push carries sensitive content such as secrets or personal or entrusted data, carries changes concealed or misdescribed relative to what you asked for, carries content ported in or first read from outside the repository, or routes around a pull request, review, or check you asked for. A plain push to the default branch isn't blocked on its own, and clearing a flagged push requires naming the flagged content or the bypassed review, not only the push. The classifier is one layer: [`permissions.deny` rules](/en/permissions#manage-permissions) apply in every mode and can block pushes to the default branch outright, and the remote's own branch protection still applies. Before v2.1.203, any direct push to the default branch was blocked\n* {/* min-version: 2.1.182 */}`git reset --hard`, `git checkout -- .`, `git restore .`, `git clean -fd`, `git stash drop`, or `git stash clear`, which the classifier presumes would discard uncommitted changes\n* `git commit --amend` when the commit at HEAD was not created in this session\n* {/* min-version: 2.1.198 */}From v2.1.198, `git commit --amend` when the commit at HEAD has already been pushed. A message-only reword is not blocked: `--amend -m` with nothing newly staged, on a commit that Claude created during this session\n* `terraform destroy`, `pulumi destroy`, `cdk destroy`, or `terragrunt destroy`, and applying a plan that destroys resources\n\nClaude Code v2.1.195 and later block more categories by default. Several depend on [environment](/en/auto-mode-config#define-trusted-infrastructure) entries, such as sensitive remote targets and protected IaC scopes, that you can narrow to concrete names.\n\n* Writing to a secret manager, or changing DNS records or TLS certificates\n* Merging a pull request no human has approved, approving Claude's own pull request, or disabling CI checks\n* Posting a comment that is itself a command to automation, such as `atlantis apply` or a bot's `/deploy` or `/merge`\n* Toggling, ramping, or deleting a production feature flag\n* Applying infrastructure changes to a protected IaC scope, or draining and removing cluster nodes\n* Writes to a shared compute cluster that reach beyond the resource you named, such as a label selector or `--all` that catches other users' jobs\n* Creating Kubernetes resources that run on every node or intercept cluster traffic, such as DaemonSets and admission webhooks\n* Interactive shells or port-forwards into a sensitive remote target\n* Opening a tunnel or reverse shell that makes a local service reachable from the public internet\n* Printing a live credential or token into the transcript or a file\n* Accessing a location listed as a sensitive data location in your [environment](/en/auto-mode-config#define-trusted-infrastructure), or copying data out of one. {/* min-version: 2.1.198 */}As of v2.1.198 this also blocks sending data from one to an audience the entry excludes\n* Routing a package install around your internal package registry to a public registry. {/* min-version: 2.1.198 */}As of v2.1.198, this also applies when you've told Claude an internal registry or mirror exists in the conversation, not only when one is listed in your environment\n* Running a command with a flag that disarms a safety guard, like `--insecure`\n* Launching an autonomous agent loop that runs without human approval or a sandbox, such as one started with `--dangerously-skip-permissions` or `--no-sandbox`. {/* min-version: 2.1.198 */}As of v2.1.198 this also covers running a third-party agent or eval harness with isolation and per-action approval disabled, such as a runner started with `--yes-always`\n* [Claude in Chrome](/en/chrome) browser actions that could send page content, cookies, or credentials off-origin\n\nClaude Code v2.1.198 and later also block these by default:\n\n* Deleting files in `/tmp`, `$TMPDIR`, or another shared scratch or cache directory by wildcard, glob, or age filter rather than by a specific named path\n* Including sensitive details in content sent, uploaded, published, or written to other people or shared systems, when your own message didn't authorize those details for that recipient. {/* min-version: 2.1.200 */}PR and issue bodies, commit messages, and comments count as this kind of outbound content when the repository is outside the trust boundary or public, including your organization's own public repositories; internal file paths, code names, live API response data such as emails or account identifiers, and infrastructure identifiers count as sensitive details. The PR, issue, and commit-message scoping requires Claude Code v2.1.200 or later. {/* min-version: 2.1.203 */}Live personal data from an API response in a PR or issue body, such as an email address, an account or organization identifier, or a usage metric, requires you to name those details and the recipient regardless of the repository's visibility or trust boundary. That check requires Claude Code v2.1.203 or later\n* Sending keystrokes to Claude Code's own tmux pane to drive its own interface, which the classifier treats as Claude changing its own permissions or oversight\n\nClaude Code v2.1.200 and later also block these by default:\n\n* Commenting out, deleting, or force-passing a test or assertion that guards security behavior, such as auth, access control, input validation, or sandboxing\n* Deleting or tearing down a stateful resource Claude didn't create in the session, when no more specific deletion rule applies and you didn't name that resource\n* Repointing an API base URL, proxy endpoint, webhook receiver, or registry mirror at a third-party host that doesn't fit the task, including in example files like `.env.example`\n* Changing where pushes go with `git remote set-url` or `git remote add`, unless you named the new remote\n* Pushing secrets or personal or entrusted data to a repository known to be public, or pushing confidential material there that isn't part of that repository's own work. {/* min-version: 2.1.203 */}A dotfiles repository's own subject matter is the one exception for personal or entrusted data, and content from a private repository reaching any public surface is blocked the same way; both refinements require Claude Code v2.1.203 or later. Before v2.1.203, personal data was grouped with confidential material and blocked only when it wasn't part of that repository's own work. When a repository's visibility isn't established, the classifier doesn't block on that alone; it judges the content against the other rules instead\n* Opening a pull request against a different repository or organization, forking with `gh repo fork`, or pushing to a third-party repository, unless you named that external target\n\nClaude Code v2.1.203 and later also block these by default:\n\n* Content from a sensitive local store, or from a file whose name, path, or type marks it as sensitive, entering a commit, a push, PR or issue text, a gist or paste, or a package publish, unless you named both the source and the destination. Session transcripts and conversation logs, credential and configuration dot-folders such as SSH keys, cloud credentials, browser profiles, and shell history, and user-data exports all count, and the repository being private doesn't clear it\n\nClaude Code v2.1.205 and later also block these by default:\n\n* Writing to Claude Code session transcripts, the `.jsonl` history files under `~/.claude/projects/` or your configured config directory, whether directly or through a shell command. The rule also covers the metadata lines Claude Code appends to each transcript entry for its own checks. A transcript is session state that Claude Code writes, not a working file, and a tampered entry reaches every later check once you resume the session, so auto mode blocks these writes as defense in depth. Reading a transcript isn't blocked\n* A recursive forced delete such as `rm -rf \"$VAR\"` or `Remove-Item -Recurse -Force $dir` whose target is a shell variable, or a glob rooted at one, that isn't assigned anywhere in the conversation the classifier sees. The value came only from earlier command output, which the classifier never receives, so the classifier can't verify the deletion target against the other deletion rules. The classifier reads the conversation rather than command output by design, so it blocks the call instead of guessing at the target. The block clears when you name the exact path being deleted, or when Claude re-runs the delete with the resolved literal path written into the command. Deletes whose target the classifier can resolve aren't affected\n\n**Allowed by default**:\n\n* Local file operations in your working directory\n* Installing dependencies declared in your lock files or manifests\n* Reading `.env` and sending credentials to their matching API\n* Read-only HTTP requests\n* Pushing to the branch you started on or one Claude created\n\nClaude Code v2.1.195 and later also allow these by default:\n\n* Deleting the exact jobs Claude created earlier in the same session\n* Reading, reviewing, or writing security-related code, configs, and threat models as part of your task\n* Messages between agents working together in the same multi-agent session\n* Sending data to the trusted domains, buckets, and services you list in [`environment`](/en/auto-mode-config#define-trusted-infrastructure). This covers data flow only, not destructive or credential operations on the same infrastructure\n* [Claude in Chrome](/en/chrome) navigation to a trusted internal domain, localhost, or a URL you named\n\nSandbox network access requests are routed through the classifier rather than allowed by default. {/* min-version: 2.1.198 */}As of v2.1.198, the classifier reuses its verdict for a network host and port instead of re-running on every connection:\n\n* An allow is reused until new content enters the conversation, at which point that host is checked again\n* In the interactive CLI, a deny is dropped when the turn ends\n* In [non-interactive mode](/en/headless) and Agent SDK sessions there is no turn boundary, so a deny is reused for the rest of the run\n* Changing your permission mode or rules drops all cached verdicts\n\nRun `claude auto-mode defaults` to see the full rule lists. If routine actions get blocked, an administrator can add trusted repos, buckets, and services via the `autoMode.environment` setting: see [Configure auto mode](/en/auto-mode-config).\n\n### Boundaries you state in conversation\n\nThe classifier treats boundaries you state in the conversation as a block signal. If you tell Claude \"don't push\" or \"wait until I review before deploying\", the classifier blocks matching actions even when the default rules would allow them. A boundary stays in force until you lift it in a later message. Claude's own judgment that a condition was met does not lift it.\n\nBoundaries are not stored as rules. The classifier re-reads them from the transcript on each check, so a boundary can be lost if [context compaction](/en/costs#reduce-token-usage) removes the message that stated it. For a hard guarantee, add a [deny rule](/en/permissions#permission-rule-syntax) instead.\n\n### When auto mode falls back\n\nEach denied action shows a notification and appears in `/permissions` under the Recently denied tab, where you can press `r` to retry it with a manual approval.\n\nIf the classifier blocks an action 3 times in a row or 20 times total, auto mode pauses and Claude Code resumes prompting. Approving the prompted action resumes auto mode. These thresholds are not configurable. Any allowed action resets the consecutive counter, while the total counter persists for the session and resets only when its own limit triggers a fallback.\n\nIn [non-interactive mode](/en/headless) with the `-p` flag, repeated blocks abort the session since there is no user to prompt.\n\nRepeated blocks usually mean the classifier is missing context about your infrastructure. Use `/feedback` to report false positives, or have an administrator [configure trusted infrastructure](/en/auto-mode-config).\n\n<AccordionGroup>\n  <Accordion title=\"How the classifier evaluates actions\">\n    Each action goes through a fixed decision order. The first matching step wins:\n\n    1. Actions matching your [allow or deny rules](/en/permissions#manage-permissions) resolve immediately, except writes to [protected paths](#protected-paths), which route to the classifier even when an allow rule matches\n    2. Read-only actions and file edits in your working directory are auto-approved, except writes to [protected paths](#protected-paths)\n    3. Everything else goes to the classifier. {/* min-version: 2.1.199 */}As of v2.1.199, an MCP tool marked with [`_meta[\"anthropic/requiresUserInteraction\"]`](/en/mcp#require-approval-for-a-specific-tool) skips the classifier and prompts you directly, so a consent step is never auto-approved on the tool author's behalf\n    4. If the classifier blocks, Claude receives the reason and tries an alternative\n\n    On entering auto mode, broad allow rules that grant arbitrary code execution are dropped:\n\n    * Blanket `Bash(*)` or `PowerShell(*)`\n    * Wildcarded interpreters like `Bash(python*)`\n    * Package-manager run commands\n    * `Agent` allow rules\n\n    Narrow rules like `Bash(npm test)` carry over. Dropped rules are restored when you leave auto mode.\n\n    The classifier sees user messages, tool calls, and your CLAUDE.md content. Tool results are stripped, so hostile content in a file or web page cannot manipulate it directly. A separate server-side probe scans incoming tool results and flags suspicious content before Claude reads it. For more on how these layers work together, see the [auto mode announcement](https://claude.com/blog/auto-mode) and the [engineering deep dive](https://www.anthropic.com/engineering/claude-code-auto-mode).\n  </Accordion>\n\n  <Accordion title=\"How auto mode handles subagents\">\n    The classifier checks [subagent](/en/sub-agents) work at three points:\n\n    1. Before a subagent starts, the delegated task description is evaluated, so a dangerous-looking task is blocked at spawn time.\n    2. While the subagent runs, each of its actions goes through the classifier with the same rules as the parent session, and any `permissionMode` in the subagent's frontmatter is ignored.\n    3. When the subagent finishes, the classifier reviews its full action history; if that return check flags a concern, a security warning is prepended to the subagent's results.\n\n    Step 1 requires Claude Code v2.1.178 or later. Earlier versions applied the classifier at steps 2 and 3, but did not evaluate the task description before the subagent started.\n  </Accordion>\n\n  <Accordion title=\"Cost and latency\">\n    The classifier runs on a server-configured model that is independent of your `/model` selection, so switching models does not change classifier availability. Classifier calls count toward your token usage. Each check sends a portion of the transcript plus the pending action, adding a round-trip before execution. Reads and working-directory edits outside protected paths skip the classifier, so the overhead comes mainly from shell commands and network operations. {/* min-version: 2.1.198 */}As of v2.1.198, a sandbox network verdict for a host and port is reused instead of re-classified on every connection, so repeated connections to the same host don't each add a check. [What the classifier blocks by default](#what-the-classifier-blocks-by-default) describes how long an allow and a deny last.\n  </Accordion>\n</AccordionGroup>\n\n## Allow only pre-approved tools with dontAsk mode\n\n`dontAsk` mode auto-denies every tool call that would otherwise prompt. The status bar shows `⏵⏵ don't ask on` while this mode is active. Only actions matching your `permissions.allow` rules and [read-only Bash commands](/en/permissions#read-only-commands) can execute; explicit [`ask` rules](/en/permissions#manage-permissions) are denied rather than prompting. {/* min-version: 2.1.199 */}As of v2.1.199, an MCP tool marked with [`_meta[\"anthropic/requiresUserInteraction\"]`](/en/mcp#require-approval-for-a-specific-tool) is also denied in this mode even when an allow rule matches it, because its approval card needs an answer this mode never collects. This makes the mode fully non-interactive for CI pipelines or restricted environments where you pre-define exactly what Claude may do. Cloud sessions on [Claude Code on the web](/en/claude-code-on-the-web) ignore `defaultMode: \"dontAsk\"`; see [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) for details.\n\nSet it at startup with the flag:\n\n```bash theme={null}\nclaude --permission-mode dontAsk\n```\n\n## Skip all checks with bypassPermissions mode\n\n`bypassPermissions` mode disables permission prompts and safety checks so tool calls execute immediately. As of v2.1.126 this includes writes to [protected paths](#protected-paths), which earlier versions still prompted for. Explicit [ask rules](/en/permissions#manage-permissions) still force a prompt in this mode, and removals targeting the filesystem root or home directory, such as `rm -rf /` and `rm -rf ~`, still prompt as a circuit breaker against model error. {/* min-version: 2.1.199 */}As of v2.1.199, MCP tools marked with [`_meta[\"anthropic/requiresUserInteraction\"]`](/en/mcp#require-approval-for-a-specific-tool) also still prompt. Only use this mode in isolated environments like containers, VMs, or dev containers without internet access, where Claude Code cannot damage your host system.\n\nYou cannot enter `bypassPermissions` from a session that was started without one of the enabling flags; restart with one to enable it:\n\n```bash theme={null}\nclaude --permission-mode bypassPermissions\n```\n\nThe `--dangerously-skip-permissions` flag is equivalent.\n\nOn Linux and macOS, Claude Code refuses to start in this mode when running as root or under `sudo`:\n\n```text theme={null}\n--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons\n```\n\nThe check is skipped automatically inside a recognized sandbox. To run autonomously in a container, use the [dev container](/en/devcontainer) configuration, which runs Claude Code as a non-root user.\n\n[Claude Code on the web](/en/claude-code-on-the-web) does not honor `defaultMode: \"bypassPermissions\"` or `\"dontAsk\"` from your settings files, so a repository's checked-in settings cannot start a cloud session in bypass-permissions mode. The setting is ignored silently and the session starts in the mode shown in the mode dropdown instead. See [Switch permission modes](#switch-permission-modes) for which modes cloud sessions offer.\n\n<Warning>\n  `bypassPermissions` offers no protection against prompt injection or unintended actions. For background safety checks with far fewer permission prompts, use [auto mode](#eliminate-prompts-with-auto-mode) instead. Administrators can block this mode by setting `permissions.disableBypassPermissionsMode` to `\"disable\"` in [managed settings](/en/permissions#managed-settings).\n</Warning>\n\n## Protected paths\n\nWrites to a small set of paths are never auto-approved, in every mode except `bypassPermissions`. This prevents accidental corruption of repository state and Claude's own configuration.\n\n| Mode                             | Protected-path writes    |\n| :------------------------------- | :----------------------- |\n| `default`, `acceptEdits`, `plan` | Prompted                 |\n| `auto`                           | Routed to the classifier |\n| `dontAsk`                        | Denied                   |\n| `bypassPermissions`              | Allowed                  |\n\n[`permissions.allow`](/en/permissions#manage-permissions) rules in settings files do not pre-approve protected-path writes. The safety check runs before Claude Code evaluates allow rules from settings, so an entry such as `Edit(.claude/**)` in `~/.claude/settings.json` or `.claude/settings.json` does not change the per-mode outcome in the table above. In modes that prompt, the prompt for a `.claude/` write offers **Yes, and allow Claude to edit its own settings for this session**, which approves later `.claude/` writes in that session without prompting again.\n\nProtected directories:\n\n* `.git`\n* `.config/git`\n* `.vscode`\n* `.idea`\n* `.husky`\n* `.cargo`\n* `.devcontainer`\n* `.yarn`\n* `.mvn`\n* `.claude`, except for `.claude/worktrees` where Claude stores its own git worktrees\n\nProtected files:\n\n* `.gitconfig`, `.gitmodules`\n* `.bashrc`, `.bash_profile`, `.bash_login`, `.bash_aliases`, `.bash_logout`, `.zshrc`, `.zprofile`, `.zshenv`, `.zlogin`, `.zlogout`, `.profile`, `.envrc`\n* `.npmrc`, `.yarnrc`, `.yarnrc.yml`, `.pnp.cjs`, `.pnp.loader.mjs`, `.pnpmfile.cjs`, `bunfig.toml`, `.bunfig.toml`\n* `.bazelrc`, `.bazelversion`, `.bazeliskrc`\n* `.pre-commit-config.yaml`, `lefthook.yml`, `lefthook.yaml`, `.lefthook.yml`, `.lefthook.yaml`\n* `gradle-wrapper.properties`, `maven-wrapper.properties`\n* `.devcontainer.json`\n* `.ripgreprc`, `pyrightconfig.json`\n* `.mcp.json`, `.claude.json`\n\n## See also\n\n* [Permissions](/en/permissions): allow, ask, and deny rules; managed policies\n* [Configure auto mode](/en/auto-mode-config): tell the classifier which infrastructure your organization trusts\n* [Hooks](/en/hooks): custom permission logic via `PreToolUse` and `PermissionRequest` hooks\n* [Ultraplan](/en/ultraplan): run plan mode in a Claude Code on the web session with browser-based review\n* [Security](/en/security): safeguards and best practices\n* [Sandboxing](/en/sandboxing): filesystem and network isolation for Bash commands\n* [Non-interactive mode](/en/headless): run Claude Code with the `-p` flag\n","durationMs":305,"url":"https://code.claude.com/docs/en/permission-modes.md"},"sourceToolAssistantUUID":"ada0c464-1859-42f5-a50b-86383f68e333","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"e9c485e7-4ab5-4a81-a231-901758d65a78","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4NDMVtX3J8m4d4NxUb","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"","signature":"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"}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":16442,"cache_read_input_tokens":15519,"cache_creation":{"ephemeral_5m_input_tokens":16442,"ephemeral_1h_input_tokens":0},"output_tokens":3,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011Ccv4NCVer2g6rYuAKXGxu","attributionAgent":"claude-code-guide","type":"assistant","uuid":"16115f83-eb7d-43ae-8a08-5a307736d0c7","timestamp":"2026-07-11T09:48:02.429Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"16115f83-eb7d-43ae-8a08-5a307736d0c7","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4NDMVtX3J8m4d4NxUb","type":"message","role":"assistant","content":[{"type":"text","text":"Let me fetch the permissions reference doc to understand rule precedence and where they're read from:"}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":16442,"cache_read_input_tokens":15519,"cache_creation":{"ephemeral_5m_input_tokens":16442,"ephemeral_1h_input_tokens":0},"output_tokens":3,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011Ccv4NCVer2g6rYuAKXGxu","attributionAgent":"claude-code-guide","type":"assistant","uuid":"24de7230-4b41-415f-acac-ab72a7d744f7","timestamp":"2026-07-11T09:48:02.652Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"24de7230-4b41-415f-acac-ab72a7d744f7","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4NDMVtX3J8m4d4NxUb","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01BpkaXsfWXnZforvjcDYRb6","name":"Bash","input":{"command":"grep -i \"permissions\\|mcp__\" /Users/marcus.hinz/.config/ai-control/pools/private/projects/-Users-marcus-hinz-claude-projects-ai-control/f7704328-4eb4-4f0f-bf42-da68abab401d/tool-results/toolu_01Jpn4YmQ9TMVMPYEKuVh7QN.txt | grep -A 5 -B 5 \"permissions.md\\|manage-permissions\\|permission rules\""},"caller":{"type":"direct"}}],"stop_reason":"tool_use","stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":16442,"cache_read_input_tokens":15519,"output_tokens":1859,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":16442},"inference_geo":"not_available","iterations":[{"input_tokens":8,"output_tokens":1859,"cache_read_input_tokens":15519,"cache_creation_input_tokens":16442,"cache_creation":{"ephemeral_5m_input_tokens":16442,"ephemeral_1h_input_tokens":0},"type":"message"}],"speed":"standard"},"diagnostics":null},"requestId":"req_011Ccv4NCVer2g6rYuAKXGxu","attributionAgent":"claude-code-guide","type":"assistant","uuid":"5a88ae0a-66d5-4b72-8ced-36eabb3f66d8","timestamp":"2026-07-11T09:48:05.108Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"5a88ae0a-66d5-4b72-8ced-36eabb3f66d8","isSidechain":true,"promptId":"463e84b3-536f-432f-b32a-4fdae6dbed7a","agentId":"a556d2e38a847bf6e","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01BpkaXsfWXnZforvjcDYRb6","type":"tool_result","content":"  * macOS permissions prompt keeps reappearing\n* Access and permissions\n  * Permissions\n  * Check directory permissions\n## Settings and permissions\n### [permissions](https://code.claude.com/docs/en/permissions.md)\n* Manage permissions\n* Extend permissions with hooks\n* How permissions interact with sandboxing\n* How sandboxing relates to permissions and permission modes\n  * Tool permissions\n### [permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md)\n* How permissions are evaluated\n    * Bypass permissions mode (`bypassPermissions`)\n  * Permissions Fallback for Unsandboxed Commands\n  * Permissions Fallback for Unsandboxed Commands","is_error":false}]},"uuid":"6bed832a-be6b-4171-af7a-22f73ae0f350","timestamp":"2026-07-11T09:48:05.268Z","toolUseResult":{"stdout":"  * macOS permissions prompt keeps reappearing\n* Access and permissions\n  * Permissions\n  * Check directory permissions\n## Settings and permissions\n### [permissions](https://code.claude.com/docs/en/permissions.md)\n* Manage permissions\n* Extend permissions with hooks\n* How permissions interact with sandboxing\n* How sandboxing relates to permissions and permission modes\n  * Tool permissions\n### [permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md)\n* How permissions are evaluated\n    * Bypass permissions mode (`bypassPermissions`)\n  * Permissions Fallback for Unsandboxed Commands\n  * Permissions Fallback for Unsandboxed Commands","stderr":"","interrupted":false,"isImage":false,"noOutputExpected":false},"sourceToolAssistantUUID":"5a88ae0a-66d5-4b72-8ced-36eabb3f66d8","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"6bed832a-be6b-4171-af7a-22f73ae0f350","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4Q7Dx6fkD2huA7W3BQ","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"","signature":"Eq0CCpMBCA8YAipADzNtskV7ZeCkXEK2nvDn0p73iyxL7jXdjDOBGBJmx07UbnCEhejrfVHZQmxqbgc3ORkyE/zKtTmPQn/WuenGvDIZY2xhdWRlLWhhaWt1LTQtNS0yMDI1MTAwMTgAQgh0aGlua2luZ1okNGJkZDE1Y2MtNDcxZS00ZTU2LWJhMWEtM2QzZDViNGYwMTdjEgzgn9pxlwbqqvteyagaDJHF+dEA2ieQ3NZVoSIwLGVO+AV0aR/20u9MmaSBD0u092kW10pXPycQBu5KAFrtrz1TBJoeHKGKieJxDv7NKkcAZa3aFy3Nr1eKSfPX7BAIA0dW8nBtARNO9N8TmyhpEtoXQrJRd3/AnS+yfS6NLItRizd2PrAP6ffTRcE3QNnoQ5kfWxbgWBgB"}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":2042,"cache_read_input_tokens":31961,"cache_creation":{"ephemeral_5m_input_tokens":2042,"ephemeral_1h_input_tokens":0},"output_tokens":1,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011Ccv4Q5q7knqfrsoHpNDcq","attributionAgent":"claude-code-guide","type":"assistant","uuid":"feb8b200-bc10-4cb1-a254-905787597ebe","timestamp":"2026-07-11T09:48:07.245Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"feb8b200-bc10-4cb1-a254-905787597ebe","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4Q7Dx6fkD2huA7W3BQ","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_012Mh9C1mvjeVLZRZLAz7AK1","name":"WebFetch","input":{"url":"https://code.claude.com/docs/en/permissions.md","prompt":"mcp__ permission naming, permissions.allow, where rules are read, user-scope vs project-scope, MCP server trust gate"},"caller":{"type":"direct"}}],"stop_reason":"tool_use","stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":2042,"cache_read_input_tokens":31961,"output_tokens":134,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":2042},"inference_geo":"not_available","iterations":[{"input_tokens":8,"output_tokens":134,"cache_read_input_tokens":31961,"cache_creation_input_tokens":2042,"cache_creation":{"ephemeral_5m_input_tokens":2042,"ephemeral_1h_input_tokens":0},"type":"message"}],"speed":"standard"},"diagnostics":null},"requestId":"req_011Ccv4Q5q7knqfrsoHpNDcq","attributionAgent":"claude-code-guide","type":"assistant","uuid":"9d53f008-3a68-425f-bf90-a733f177d892","timestamp":"2026-07-11T09:48:08.002Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"9d53f008-3a68-425f-bf90-a733f177d892","isSidechain":true,"promptId":"463e84b3-536f-432f-b32a-4fdae6dbed7a","agentId":"a556d2e38a847bf6e","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_012Mh9C1mvjeVLZRZLAz7AK1","type":"tool_result","content":"> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Configure permissions\n\n> Control what Claude Code can access and do with fine-grained permission rules, modes, and managed policies.\n\nClaude Code supports fine-grained permissions so that you can specify exactly what the agent is allowed to do and what it can't. Permission settings can be checked into version control and distributed to all developers in your organization, as well as customized by individual developers.\n\n## Permission system\n\nClaude Code uses a tiered permission system to balance power and safety:\n\n| Tool type         | Example          | Approval required                                                                   | \"Yes, don't ask again\" behavior               |\n| :---------------- | :--------------- | :---------------------------------------------------------------------------------- | :-------------------------------------------- |\n| Read-only         | File reads, Grep | No, within the [working directory and additional directories](#working-directories) | N/A                                           |\n| Bash commands     | Shell execution  | Yes, except a built-in set of [read-only commands](#read-only-commands)             | Permanently per project directory and command |\n| File modification | Edit/write files | Yes                                                                                 | Until session end                             |\n\n## Manage permissions\n\nYou can view and manage Claude Code's tool permissions with `/permissions`. This UI lists all permission rules and the `settings.json` file each rule comes from.\n\n* **Allow** rules let Claude Code use the specified tool without manual approval.\n* **Ask** rules prompt for confirmation whenever Claude Code tries to use the specified tool.\n* **Deny** rules prevent Claude Code from using the specified tool.\n\nRules are evaluated in order: deny, then ask, then allow. The first match in that order determines the outcome, and rule specificity doesn't change the order.\n\nA broad deny rule like `Bash(aws *)` blocks every matching call, including calls that also match a narrower allow rule like `Bash(aws s3 ls)`, so a deny rule can't carry allowlist exceptions. The same precedence applies between ask and allow: a matching ask rule prompts even when a more specific allow rule also matches the same call.\n\nDeny rules behave differently depending on whether they name a tool or scope a pattern within one. A bare tool name like `Bash` removes the tool from Claude's context entirely, so Claude never sees it. A scoped rule like `Bash(rm *)` leaves the tool available and blocks matching calls when Claude attempts them.\n\n<Note>\n  Permission rules are enforced by Claude Code, not by the model. Instructions in your prompt or `CLAUDE.md` shape what Claude tries to do, but they don't change what Claude Code allows. To grant or revoke access, use `/permissions`, the rules described here, a [permission mode](/en/permission-modes), or a [PreToolUse hook](#extend-permissions-with-hooks).\n</Note>\n\n## Permission modes\n\nClaude Code supports several permission modes that control how it approves tool calls. See [Permission modes](/en/permission-modes) for when to use each one. Set the `defaultMode` in your [settings files](/en/settings#settings-files):\n\n| Mode                | Description                                                                                                                                                                                                                                                                  |\n| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `default`           | Standard behavior: prompts for permission on first use of each tool. {/* min-version: 2.1.200 */}Labeled Manual in the CLI and the VS Code and JetBrains extensions, and Claude Code accepts `manual` as an alias. The label and alias require Claude Code v2.1.200 or later |\n| `acceptEdits`       | Automatically accepts file edits and common filesystem commands such as `mkdir`, `touch`, `mv`, and `cp` for paths in the working directory or `additionalDirectories`                                                                                                       |\n| `plan`              | Claude reads files and runs read-only shell commands to explore but doesn't edit your source files. Labeled Plan in the CLI and the VS Code extension                                                                                                                        |\n| `auto`              | Auto-approves tool calls with background safety checks that verify actions align with your request                                                                                                                                                                           |\n| `dontAsk`           | Auto-denies tools unless pre-approved via `/permissions` or `permissions.allow` rules                                                                                                                                                                                        |\n| `bypassPermissions` | Skips permission prompts, except those forced by explicit `ask` rules. Root and home directory removals such as `rm -rf /` also still prompt as a circuit breaker                                                                                                            |\n\n<Warning>\n  `bypassPermissions` mode skips permission prompts, including for writes to `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn`, and `.mvn`. Explicit `ask` rules still force a prompt, and removals targeting the filesystem root or home directory, such as `rm -rf /` and `rm -rf ~`, still prompt as a circuit breaker against model error. Only use this mode in isolated environments like containers or VMs where Claude Code can't cause damage.\n</Warning>\n\nTo prevent `bypassPermissions` or `auto` mode from being used, set `permissions.disableBypassPermissionsMode` or `permissions.disableAutoMode` to `\"disable\"` in any [settings file](/en/settings#settings-files). These are most useful in [managed settings](#managed-settings) where they can't be overridden.\n\n## Permission rule syntax\n\nPermission rules follow the format `Tool` or `Tool(specifier)`.\n\n### Match all uses of a tool\n\nTo match all uses of a tool, use only the tool name without parentheses:\n\n| Rule       | Effect                         |\n| :--------- | :----------------------------- |\n| `Bash`     | Matches all Bash commands      |\n| `WebFetch` | Matches all web fetch requests |\n| `Read`     | Matches all file reads         |\n\n`Bash(*)` is equivalent to `Bash` and matches all Bash commands. As a deny rule, both forms remove the tool from Claude's context.\n\n### Use specifiers for fine-grained control\n\nAdd a specifier in parentheses to match specific tool uses:\n\n| Rule                           | Effect                                                   |\n| :----------------------------- | :------------------------------------------------------- |\n| `Bash(npm run build)`          | Matches the exact command `npm run build`                |\n| `Read(./.env)`                 | Matches reading the `.env` file in the current directory |\n| `WebFetch(domain:example.com)` | Matches fetch requests to example.com                    |\n\n### Match by input parameter\n\nDeny and ask rules can match a top-level input parameter on any tool with `Tool(param:value)`. The rule matches when Claude calls the tool with that parameter set to that exact value. An allow rule for one parameter value wouldn't establish that the call is safe overall, so allow rules continue to use each tool's own specifier syntax. This works for any scalar parameter the tool accepts:\n\n| Rule                           | Matches                                      |\n| :----------------------------- | :------------------------------------------- |\n| `Agent(model:opus)`            | Agent calls that request the Opus model tier |\n| `Agent(isolation:worktree)`    | Agent calls that request a git worktree      |\n| `Bash(run_in_background:true)` | Bash calls that run in the background        |\n\nParameter matching follows these rules:\n\n* The parameter name must be a direct field of the tool's input, such as `model` on the Agent tool. Fields nested inside an object or array are not matchable\n* Each rule names one parameter. To gate on both `model` and `isolation`, write two rules, `Agent(model:opus)` and `Agent(isolation:worktree)`, rather than combining them in one rule\n* The value supports `*` as a wildcard that matches any sequence of characters, so `Agent(isolation:*)` matches any explicit isolation value. Without `*` the match is exact\n* A parameter the model omits is never matched, so `Agent(model:*)` doesn't match a call that leaves `model` unset\n* The value is compared against the literal input Claude sends, before any normalization. `Agent(model:opus)` matches the alias `opus` but not a full model ID. Run with [`--verbose`](/en/cli-reference) to see the exact parameter names and values in each tool call\n* Whitespace around the colon is ignored\n\nFields that a tool already matches with its own canonicalizing rules are not matchable this way: `command` for Bash and PowerShell, `file_path` for Read, Edit, and Write, `path` for Grep and Glob, `notebook_path` for NotebookEdit, and `url` for WebFetch. A rule like `Bash(command:rm *)` would be bypassable by a compound command, so Claude Code ignores it and emits a startup warning. Use `Bash(rm *)`, `Read(./path)`, or `WebFetch(domain:host)` instead.\n\n### Wildcard patterns\n\nBash rules support glob patterns with `*`. Wildcards can appear at any position in the command. This configuration allows npm and git commit commands while blocking git push:\n\n```json theme={null}\n{\n  \"permissions\": {\n    \"allow\": [\n      \"Bash(npm run *)\",\n      \"Bash(git commit *)\",\n      \"Bash(git * main)\",\n      \"Bash(* --version)\",\n      \"Bash(* --help *)\"\n    ],\n    \"deny\": [\n      \"Bash(git push *)\"\n    ]\n  }\n}\n```\n\nThe space before `*` matters: `Bash(ls *)` matches `ls -la` but not `lsof`, while `Bash(ls*)` matches both. The `:*` suffix is an equivalent way to write a trailing wildcard, so `Bash(ls:*)` matches the same commands as `Bash(ls *)`.\n\nThe permission dialog writes the space-separated form when you select \"Yes, don't ask again\" for a command prefix. The `:*` form is only recognized at the end of a pattern. In a pattern like `Bash(git:* push)`, the colon is treated as a literal character and won't match git commands.\n\n### Tool name wildcards\n\nDeny and ask rules also accept glob patterns in the tool-name position. The pattern must match the full tool name: `\"*\"` matches every tool, and `\"mcp__*\"` matches every MCP tool across all servers. A tool matched by a bare-name glob deny rule is removed from Claude's context, the same as a bare tool name. This configuration denies every MCP tool:\n\n```json theme={null}\n{\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__*\"\n    ]\n  }\n}\n```\n\nAllow rules accept tool-name globs only after a literal `mcp__<server>__` prefix. The server segment must be glob-free so the rule names a specific server you configured. `mcp__puppeteer__*` matches every tool from the `puppeteer` server, and `mcp__github__get_*` matches its `get_` tools. An unanchored allow glob such as `\"*\"`, `\"B*\"`, or `\"mcp__*\"` is skipped with a warning and doesn't auto-approve anything.\n\nA deny or ask rule whose tool name matches no known tool produces a startup warning to catch typos. Tool names containing `_` or `*` are exempt from the check.\n\nThe label shown for a tool in the transcript and permission dialog can differ from its canonical name. For example, the tool labeled `Stop Task` in the transcript has the canonical name `TaskStop`. Permission rules and [hook matchers](/en/hooks) match the canonical name only, so a rule written as `Stop Task` doesn't match. For deny and ask rules, the startup warning above catches the mismatch. Use the canonical names listed in the [tools reference](/en/tools-reference).\n\n## Tool-specific permission rules\n\n### Bash\n\nBash permission rules support wildcard matching with `*`. Wildcards can appear at any position in the command, including at the beginning, middle, or end:\n\n* `Bash(npm run build)` matches the exact Bash command `npm run build`\n* `Bash(npm run test *)` matches Bash commands starting with `npm run test`\n* `Bash(npm *)` matches any command starting with `npm `\n* `Bash(* install)` matches any command ending with ` install`\n* `Bash(git * main)` matches commands like `git checkout main` and `git log --oneline main`\n\nA single `*` matches any sequence of characters including spaces, so one wildcard can span multiple arguments. `Bash(git *)` matches `git log --oneline --all`, and `Bash(git * main)` matches `git push origin main` as well as `git merge main`.\n\nWhen `*` appears at the end with a space before it (like `Bash(ls *)`), it enforces a word boundary, requiring the prefix to be followed by a space or end-of-string. For example, `Bash(ls *)` matches `ls -la` but not `lsof`. In contrast, `Bash(ls*)` without a space matches both `ls -la` and `lsof` because there's no word boundary constraint.\n\n#### Compound commands\n\n<Tip>\n  Claude Code is aware of shell operators, so a rule like `Bash(safe-cmd *)` won't give it permission to run the command `safe-cmd && other-cmd`. The recognized command separators are `&&`, `||`, `;`, `|`, `|&`, `&`, and newlines. A rule must match each subcommand independently.\n</Tip>\n\nWhen you approve a compound command with \"Yes, don't ask again\", Claude Code saves a separate rule for each subcommand that requires approval, rather than a single rule for the full compound string. For example, approving `git status && npm test` saves a rule for `npm test`, so future `npm test` invocations are recognized regardless of what precedes the `&&`. Subcommands like `cd` into a subdirectory generate their own Read rule for that path. Up to 5 rules may be saved for a single compound command.\n\n#### Process wrappers\n\nBefore matching Bash rules, Claude Code strips a fixed set of process wrappers so a rule like `Bash(npm test *)` also matches `timeout 30 npm test`. The recognized wrappers are `timeout`, `time`, `nice`, `nohup`, and `stdbuf`.\n\nBare `xargs` is also stripped, so `Bash(grep *)` matches `xargs grep pattern`. Stripping applies only when `xargs` has no flags: an invocation like `xargs -n1 grep pattern` is matched as an `xargs` command, so rules written for the inner command do not cover it.\n\nThis wrapper list is built in and is not configurable. Development environment runners such as `direnv exec`, `devbox run`, `mise exec`, `npx`, and `docker exec` are not in the list. Because these tools execute their arguments as a command, a rule like `Bash(devbox run *)` matches whatever comes after `run`, including `devbox run rm -rf .`. To approve work inside an environment runner, write a specific rule that includes both the runner and the inner command, such as `Bash(devbox run npm test)`. Add one rule per inner command you want to allow.\n\nExec wrappers such as `watch`, `setsid`, `ionice`, and `flock` always prompt and can't be auto-approved by a prefix rule like `Bash(watch *)`. The same applies to `find` with `-exec` or `-delete`: a `Bash(find *)` rule doesn't cover these forms. To approve a specific invocation, write an exact-match rule for the full command string.\n\n#### Read-only commands\n\nClaude Code recognizes a built-in set of Bash commands as read-only and runs them without a permission prompt in every mode. These include `ls`, `cat`, `echo`, `pwd`, `head`, `tail`, `grep`, `find`, `wc`, `which`, `diff`, `stat`, `du`, `cd`, and read-only forms of `git`. The set is not configurable; to require a prompt for one of these commands, add an `ask` or `deny` rule for it.\n\nUnquoted glob patterns are permitted for commands whose every flag is read-only, so `ls *.ts` and `wc -l src/*.py` run without a prompt. Commands with write-capable or exec-capable flags, such as `find`, `sort`, `sed`, and `git`, still prompt when an unquoted glob is present because the glob could expand to a flag like `-delete`.\n\nA `cd` into a path inside your working directory or an [additional directory](#working-directories) is also read-only. A compound command like `cd packages/api && ls` runs without a prompt when each part qualifies on its own. Combining `cd` with `git` in one compound command prompts when the `cd` changes into a different directory, since running `git` in a new directory can execute that directory's hooks. A `cd` whose target resolves to the current working directory is a no-op and doesn't trigger this prompt.\n\n<Warning>\n  Bash permission patterns that try to constrain command arguments are fragile. For example, `Bash(curl http://github.com/ *)` intends to restrict curl to GitHub URLs, but won't match variations like:\n\n  * Options before URL: `curl -X GET http://github.com/...`\n  * Different protocol: `curl https://github.com/...`\n  * Redirects: `curl -L http://bit.ly/xyz`, which redirects to GitHub\n  * Variables: `URL=http://github.com && curl $URL`\n  * Extra spaces: `curl  http://github.com`\n\n  For more reliable URL filtering, consider:\n\n  * **Restrict Bash network tools**: use deny rules to block `curl`, `wget`, and similar commands, then use the WebFetch tool with `WebFetch(domain:github.com)` permission for allowed domains\n  * **Use PreToolUse hooks**: implement a hook that validates URLs in Bash commands and blocks disallowed domains\n  * **Add CLAUDE.md guidance**: describe your allowed curl patterns in `CLAUDE.md`. This shapes what Claude tries but doesn't enforce a boundary, so pair it with one of the options above\n\n  Note that using WebFetch alone doesn't prevent network access. If Bash is allowed, Claude can still use `curl`, `wget`, or other tools to reach any URL.\n</Warning>\n\n### PowerShell\n\nPowerShell permission rules use the same shape as Bash rules. Wildcards with `*` match at any position, the `:*` suffix is equivalent to a trailing ` *`, and a bare `PowerShell` or `PowerShell(*)` matches every command. This configuration allows `Get-ChildItem` and `git commit` commands while blocking `Remove-Item`:\n\n```json theme={null}\n{\n  \"permissions\": {\n    \"allow\": [\n      \"PowerShell(Get-ChildItem *)\",\n      \"PowerShell(git commit *)\"\n    ],\n    \"deny\": [\n      \"PowerShell(Remove-Item *)\"\n    ]\n  }\n}\n```\n\nCommon aliases are canonicalized before matching. A rule written for the cmdlet name also matches its aliases, so `PowerShell(Get-ChildItem *)` matches `gci`, `ls`, and `dir` as well. Matching is case-insensitive.\n\nClaude Code parses the PowerShell AST and checks each command in a compound command independently. Pipeline operators `|`, statement separators `;`, and on PowerShell 7+ the chain operators `&&` and `||` split a compound command into subcommands. A rule must match every subcommand for the compound command to be allowed.\n\n### Read and Edit\n\n`Edit` rules apply to all built-in tools that edit files. Claude makes a best-effort attempt to apply `Read` rules to all built-in tools that read files like Grep and Glob, to `@file` mentions in your prompts, and to the selection and open-file context that a connected [IDE](/en/vs-code#the-built-in-ide-mcp-server) shares with Claude.\n\n<Warning>\n  Read and Edit deny rules apply to Claude's built-in file tools and to file commands Claude Code recognizes in Bash, such as `cat`, `head`, `tail`, and `sed`. They don't apply to arbitrary subprocesses that read or write files indirectly, like a Python or Node script that opens files itself. For OS-level enforcement that blocks all processes from accessing a path, [enable the sandbox](/en/sandboxing).\n</Warning>\n\nRead and Edit rules both follow the [gitignore](https://git-scm.com/docs/gitignore) specification with four distinct pattern types:\n\n| Pattern            | Meaning                              | Example                          | Matches                                          |\n| ------------------ | ------------------------------------ | -------------------------------- | ------------------------------------------------ |\n| `//path`           | Absolute path from filesystem root   | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**`                        |\n| `~/path`           | Path from home directory             | `Read(~/Documents/*.pdf)`        | `/Users/alice/Documents/*.pdf`                   |\n| `/path`            | Path relative to the settings source | `Edit(/src/**/*.ts)`             | `<project root>/src/**/*.ts` in project settings |\n| `path` or `./path` | Path relative to current directory   | `Read(*.env)`                    | `<cwd>/*.env`                                    |\n\n<Warning>\n  A pattern like `/Users/alice/file` isn't an absolute path. The single leading slash anchors at the settings source, not the filesystem root. Use `//Users/alice/file` for absolute paths.\n</Warning>\n\nA `/path` pattern anchors at the directory associated with the settings file that defines it, so the same rule matches different locations depending on where you put it:\n\n| Rule defined in                                            | `/path` resolves to        |\n| :--------------------------------------------------------- | :------------------------- |\n| Project or local settings, such as `.claude/settings.json` | `<project root>/path`      |\n| User settings at `~/.claude/settings.json`                 | `~/.claude/path`           |\n| A file passed with `--settings <file>`                     | `<directory of file>/path` |\n| CLI flags, `/permissions`, or session rules                | `<original cwd>/path`      |\n\nA deny rule such as `Read(/secrets/**)` in user settings blocks `~/.claude/secrets/**`, not a `secrets` directory in your project. To write a rule in user settings that applies inside every project, use a `//` absolute path or a `~/` home-relative path instead.\n\nOn Windows, paths are normalized to POSIX form before matching. `C:\\Users\\alice` becomes `/c/Users/alice`, so use `//c/**/.env` to match `.env` files anywhere on that drive. To match across all drives, use `//**/.env`.\n\nExamples:\n\n* `Edit(/docs/**)`: edits in `<project>/docs/`, not `/docs/` or `<project>/.claude/docs/`\n* `Read(~/.zshrc)`: reads your home directory's `.zshrc`\n* `Edit(//tmp/scratch.txt)`: edits the absolute path `/tmp/scratch.txt`\n* `Read(src/**)`: reads from `<current-directory>/src/`\n\nA rule only matches files under its anchor, so the anchor determines how far a deny rule reaches. Bare filenames follow gitignore semantics and match at any depth, so `Read(.env)` and `Read(**/.env)` are equivalent:\n\n| Deny rule                       | Blocks                                       | Does not block                                       |\n| ------------------------------- | -------------------------------------------- | ---------------------------------------------------- |\n| `Read(.env)` or `Read(**/.env)` | any `.env` at or under the current directory | `.env` in a parent directory or another project      |\n| `Read(//**/.env)`               | any `.env` anywhere on the filesystem        | nothing; the rule is anchored at the filesystem root |\n\n<Note>\n  In gitignore patterns, `*` matches within a single path segment and can appear at any position in the pattern, while `**` matches across directories. To allow all file access, use only the tool name without parentheses: `Read`, `Edit`, or `Write`.\n</Note>\n\nWhen you approve a file path with \"Yes, don't ask again\", Claude Code escapes gitignore pattern characters in that path, such as `[`, `]`, and `*`, so the generated rule matches only the literal path you approved. Rules you write yourself aren't escaped. Before v2.1.202, Claude Code saved the path unescaped, so a generated rule for a directory named `[2024-06] Reports` could fail to match its own path or match unintended sibling directories.\n\nWhen Claude accesses a symlink, permission rules check two paths: the symlink itself and the file it resolves to. Allow and deny rules treat that pair differently: allow rules fall back to prompting you, while deny rules block outright.\n\n* **Allow rules**: apply only when both the symlink path and its target match. A symlink inside an allowed directory that points outside it still prompts you.\n* **Deny rules**: apply when either the symlink path or its target matches. A symlink that points to a denied file is itself denied.\n\nFor example, with `Read(./project/**)` allowed and `Read(~/.ssh/**)` denied, a symlink at `./project/key` pointing to `~/.ssh/id_rsa` is blocked: the target fails the allow rule and matches the deny rule.\n\n### WebFetch\n\nWebFetch rules use a `domain:` prefix and match against the hostname of the requested URL. Matching is case-insensitive, supports `*` wildcards, and strips a trailing `.` from both the rule and the hostname so `example.com.` and `example.com` are treated the same.\n\n* `WebFetch(domain:example.com)` matches requests to `example.com`\n* `WebFetch(domain:*.example.com)` matches any subdomain at any depth, such as `api.example.com` or `a.b.example.com`, but not `example.com` itself\n* `WebFetch(domain:*)` matches every domain and is equivalent to a bare `WebFetch` rule\n\nIn any position other than a leading `*.` or a bare `*`, the wildcard matches only the text between two dots. `WebFetch(domain:example.*)` matches `example.org`, where `*` becomes `org`, but not `example.evil.com`, where `*` would have to become `evil.com` and cross a dot. This keeps a trailing wildcard from matching domains an attacker could register.\n\n### MCP\n\nMCP rules use the server name as configured in Claude Code, optionally followed by the name of a tool from that server.\n\n* `mcp__puppeteer` matches any tool provided by the `puppeteer` server\n* `mcp__puppeteer__*` uses wildcard syntax and also matches all tools from the `puppeteer` server\n* `mcp__puppeteer__puppeteer_navigate` matches the `puppeteer_navigate` tool provided by the `puppeteer` server\n\n### Agent (subagents)\n\nUse `Agent(AgentName)` rules to control which [subagents](/en/sub-agents) Claude can use:\n\n* `Agent(Explore)` matches the Explore subagent\n* `Agent(Plan)` matches the Plan subagent\n* `Agent(my-custom-agent)` matches a custom subagent named `my-custom-agent`\n\nAdd these rules to the `deny` array in your settings or use the `--disallowedTools` CLI flag to disable specific agents. To disable the Explore agent:\n\n```json theme={null}\n{\n  \"permissions\": {\n    \"deny\": [\"Agent(Explore)\"]\n  }\n}\n```\n\n### Cd\n\n`Cd` rules control which directories the [`/cd` command](/en/commands) can move the session to. `Cd` is not a model-invocable tool: Claude can't call it, and the rules apply only when you run `/cd` yourself.\n\nA bare `Cd` deny rule disables `/cd` entirely. A `Cd(<path-pattern>)` deny rule blocks matching targets. Deny rules check every spelling of the target, including each symlink hop it resolves through, so a rule written for one path also blocks targets that resolve to it.\n\nAdding any `Cd` allow rule switches `/cd` to allowlist mode: the resolved target directory must match one of your allow rules, or `/cd` refuses. With no `Cd` rules configured, `/cd` keeps its default behavior and prompts you to trust an unfamiliar directory.\n\nPath patterns share the `//`, `~/`, and `/` anchors from [Read and Edit rules](#read-and-edit), but matching is anchored to the whole directory path rather than gitignore-style. `*` matches exactly one path segment and `**` matches across segments. A trailing `/**` also matches its named root.\n\n| Rule                  | Matches                                   | Does not match               |\n| --------------------- | ----------------------------------------- | ---------------------------- |\n| `Cd(~/code/*)`        | `~/code/app`                              | `~/code/app/src`, `~/code`   |\n| `Cd(~/code/**)`       | `~/code` and any directory under it       | directories outside `~/code` |\n| `Cd(**/node_modules)` | any `node_modules` directory at any depth | `node_modules/pkg`           |\n\n## Extend permissions with hooks\n\n[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 prompt. The hook output can deny the tool call, force a prompt, or skip the prompt to let the call proceed.\n\nHook decisions don't bypass permission rules. Deny and ask rules are evaluated regardless of what a PreToolUse hook returns, so a matching deny rule blocks the call and a matching ask rule still prompts even when the hook returned `\"allow\"` or `\"ask\"`. This preserves the deny-first precedence described in [Manage permissions](#manage-permissions), including deny rules set in managed settings.\n\nA blocking hook also takes precedence over allow rules. A hook that exits with code 2 stops the tool call before permission rules are evaluated, so the block applies even when an allow rule would otherwise let the call proceed. To run all Bash commands without prompts except for a few you want blocked, add `\"Bash\"` to your allow list and register a PreToolUse hook that rejects those specific commands. See [Block edits to protected files](/en/hooks-guide#block-edits-to-protected-files) for a hook script you can adapt.\n\n## Working directories\n\nBy default, Claude has access to files in the directory where you launched it. You can extend this access:\n\n* **During startup**: use `--add-dir <path>` CLI argument\n* **During session**: use `/add-dir` command\n* **Persistent configuration**: add to `additionalDirectories` in [settings files](/en/settings#settings-files)\n\nFiles 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.\n\nTo change the session's primary working directory instead of adding another, use [`/cd`](/en/commands). The `/cd` command requires Claude Code v2.1.169 or later. Unlike `/add-dir`, it relocates the session: the new directory's `CLAUDE.md` is loaded and `--resume` finds the session from there.\n\n### Additional directories grant file access, not configuration\n\nAdding a directory extends where Claude can read and edit files. It doesn't make that directory a full configuration root: most `.claude/` configuration is not discovered from additional directories, though a few types are loaded as exceptions.\n\nThese exceptions apply only to directories added with the `--add-dir` flag or the `/add-dir` command. Directories listed in `permissions.additionalDirectories` in a settings file grant file access only and don't load any of the configuration below.\n\nThe following configuration types are loaded from `--add-dir` directories:\n\n| Configuration                                                                         | Loaded from `--add-dir`                                                                                                                                            |\n| :------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Skills](/en/skills) in `.claude/skills/`                                             | Yes, with live reload                                                                                                                                              |\n| [Subagents](/en/sub-agents) in `.claude/agents/`                                      | Yes                                                                                                                                                                |\n| [Settings](/en/settings) in `.claude/settings.json` and `.claude/settings.local.json` | `enabledPlugins` and `extraKnownMarketplaces` keys only                                                                                                            |\n| [CLAUDE.md](/en/memory) files, `.claude/rules/`, and `CLAUDE.local.md`                | Only when `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` is set. `CLAUDE.local.md` additionally requires the `local` setting source, which is enabled by default |\n\nCommands and output styles are discovered from the current working directory and its parents, your user directory at `~/.claude/`, and managed settings. Hooks and other `settings.json` keys load from the current working directory's `.claude/` folder with no parent-directory fallback, alongside your user `~/.claude/settings.json` and managed settings. To share that configuration across projects, use one of these approaches:\n\n* **User-level configuration**: place files in `~/.claude/agents/`, `~/.claude/output-styles/`, or `~/.claude/settings.json` to make them available in every project\n* **Plugins**: package and distribute configuration as a [plugin](/en/plugins) that teams can install\n* **Launch from the config directory**: run Claude Code from the directory containing the `.claude/` configuration you want\n\n## How permissions interact with sandboxing\n\nPermissions and [sandboxing](/en/sandboxing) are complementary security layers:\n\n* **Permissions** control which tools Claude Code can use and which files or domains it can access. They apply to all tools, including Bash, Read, Edit, WebFetch, and MCP.\n* **Sandboxing** provides OS-level enforcement that restricts the Bash tool's filesystem and network access. It applies only to Bash commands and their child processes.\n\nUse both for defense-in-depth:\n\n* Permission deny rules block Claude from even attempting to access restricted resources\n* Sandbox restrictions prevent Bash commands from reaching resources outside defined boundaries, even if a prompt injection bypasses Claude's decision-making\n* Filesystem restrictions in the sandbox combine the [`sandbox.filesystem`](/en/sandboxing) settings with Read and Edit deny rules; both are merged into the final sandbox boundary\n* Network restrictions combine WebFetch permission rules with the sandbox's `allowedDomains` and `deniedDomains` lists\n\nWhen sandboxing is enabled with `autoAllowBashIfSandboxed: true`, which is the default, sandboxed Bash commands run without prompting even if your permissions include a bare `Bash` ask rule, or the [equivalent `Bash(*)` form](#match-all-uses-of-a-tool): the sandbox boundary substitutes for that whole-tool prompt. These checks still apply:\n\n* Content-scoped ask rules like `Bash(git push *)` still force a prompt\n* Explicit deny rules still apply\n* `rm` or `rmdir` commands that target `/`, your home directory, or other critical system paths still trigger a prompt\n\nCommands that won't run sandboxed, such as excluded commands, respect the bare `Bash` ask rule as usual. See [sandbox modes](/en/sandboxing#sandbox-modes) to change this behavior.\n\n## Managed settings\n\nFor organizations that need centralized control over Claude Code configuration, administrators can deploy managed settings that can't be overridden by user or project settings. These policy settings follow the same format as regular settings files and can be delivered through MDM/OS-level policies, managed settings files, [server-managed settings](/en/server-managed-settings), or a self-hosted [Claude apps gateway](/en/claude-apps-gateway). See [settings files](/en/settings#settings-files) for delivery mechanisms and file locations.\n\n### Managed-only settings\n\nThe following settings are only read from managed settings. Placing them in user or project settings files has no effect.\n\n| Setting                                        | Description                                                                                                                                                                                                                                                                                                                         |\n| :--------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `allowAllClaudeAiMcps`                         | When `true`, claude.ai connectors load alongside a deployed `managed-mcp.json` instead of being suppressed by its exclusive control. See [Managed MCP configuration](/en/managed-mcp)                                                                                                                                               |\n| `allowedChannelPlugins`                        | Allowlist of channel plugins that may push messages. Replaces the default Anthropic allowlist when set. Requires `channelsEnabled: true`. See [Restrict which channel plugins can run](/en/channels#restrict-which-channel-plugins-can-run)                                                                                         |\n| `allowManagedHooksOnly`                        | When `true`, only managed hooks, SDK hooks, and hooks from plugins force-enabled in managed settings `enabledPlugins` are loaded. User, project, and all other plugin hooks are blocked                                                                                                                                             |\n| `allowManagedMcpServersOnly`                   | When `true`, only `allowedMcpServers` from managed settings are respected. `deniedMcpServers` still merges from all sources. See [Managed MCP configuration](/en/managed-mcp)                                                                                                                                                       |\n| `allowManagedPermissionRulesOnly`              | When `true`, prevents user and project settings from defining `allow`, `ask`, or `deny` permission rules. Only rules in managed settings apply. Doesn't affect the MCP server allowlist; for that, set `allowManagedMcpServersOnly`                                                                                                 |\n| `blockedMarketplaces`                          | Blocklist of marketplace sources. Blocked sources are checked before downloading, so they never touch the filesystem. See [managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions)                                                                                                              |\n| `channelsEnabled`                              | Allow [channels](/en/channels) for the organization. See [enterprise controls](/en/channels#enterprise-controls) for the default on each plan                                                                                                                                                                                       |\n| `disableSideloadFlags`                         | {/* min-version: 2.1.193 */}Reject the `--plugin-dir`, `--plugin-url`, `--agents`, and `--mcp-config` CLI flags at startup. Without this, users can bypass `strictKnownMarketplaces` for a single run by passing these flags. See [`disableSideloadFlags`](/en/settings#available-settings). Requires Claude Code v2.1.193 or later |\n| `forceRemoteSettingsRefresh`                   | When `true`, blocks CLI startup until remote managed settings are freshly fetched and exits if the fetch fails. See [fail-closed enforcement](/en/server-managed-settings#enforce-fail-closed-startup)                                                                                                                              |\n| `pluginTrustMessage`                           | Custom message appended to the plugin trust warning shown before installation                                                                                                                                                                                                                                                       |\n| `sandbox.filesystem.allowManagedReadPathsOnly` | When `true`, only `filesystem.allowRead` paths from managed settings are respected. `denyRead` still merges from all sources                                                                                                                                                                                                        |\n| `sandbox.network.allowManagedDomainsOnly`      | When `true`, only `allowedDomains` and `WebFetch(domain:...)` allow rules from managed settings are respected. Non-allowed domains are blocked automatically without prompting the user. Denied domains still merge from all sources                                                                                                |\n| `strictKnownMarketplaces`                      | Controls which plugin marketplace sources users can add and install plugins from. See [managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions)                                                                                                                                                  |\n| `strictPluginOnlyCustomization`                | Block skills, agents, hooks, and MCP servers from user and project sources, so they can only come from plugins or managed settings. `true` locks all four surfaces; an array such as `[\"skills\", \"hooks\"]` locks only the named ones. See [`strictPluginOnlyCustomization`](/en/settings#strictpluginonlycustomization)             |\n| `wslInheritsWindowsSettings`                   | When `true` in the Windows HKLM registry key or `C:\\Program Files\\ClaudeCode\\managed-settings.json`, WSL reads managed settings from the Windows policy chain in addition to `/etc/claude-code`. See [Settings files](/en/settings#settings-files)                                                                                  |\n\n`disableBypassPermissionsMode` is typically placed in managed settings to enforce organizational policy, but it works from any scope. A user can set it in their own settings to lock themselves out of bypass mode.\n\n<Note>\n  On Team and Enterprise plans, an Owner enables or disables [Remote Control](/en/remote-control) and [web sessions](/en/claude-code-on-the-web) organization-wide in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code). Remote Control can additionally be disabled per device with the [`disableRemoteControl`](/en/settings#available-settings) setting. Web sessions have no per-device managed settings key.\n</Note>\n\n## Settings precedence\n\nPermission rules follow the same [settings precedence](/en/settings#settings-precedence) as all other Claude Code settings:\n\n1. **Managed settings**: can't be overridden by any other level, including command line arguments\n2. **Command line arguments**: temporary session overrides\n3. **Local project settings** (`.claude/settings.local.json`)\n4. **Shared project settings** (`.claude/settings.json`)\n5. **User settings** (`~/.claude/settings.json`)\n\nIf a tool is denied at any level, no other level can allow it. For example, a managed settings deny can't be overridden by `--allowedTools`, and `--disallowedTools` can add restrictions beyond what managed settings define.\n\nThe same holds across settings scopes: if user settings allow a permission and project settings deny it, the deny rule blocks it. The reverse is also true: a user-level deny blocks a project-level allow, because deny rules from any scope are evaluated before allow rules.\n\nEmbedding hosts can supply additional managed policy via the SDK `managedSettings` option when [`parentSettingsBehavior`](/en/settings#settings-precedence) is set to `\"merge\"`; embedder values can tighten policy but not loosen it.\n\n## Project allow rules and workspace trust\n\n`permissions.allow` rules and `permissions.additionalDirectories` entries in a project's `.claude/settings.json` grant capability, so Claude Code applies them only after you accept the [workspace trust dialog](/en/security#additional-safeguards) for that workspace. Until then, Claude Code reads the rules but doesn't apply them. The trust dialog lists the allow rules and additional directories the folder would grant so you can review them before accepting. `deny` and `ask` rules aren't affected, since they only restrict.\n\nClaude Code saves trust per workspace, keyed on the git repository root or, outside a repository, the directory you started Claude Code from. When you start in your home directory, trust is held for the current session only and isn't written to disk; see the [additional safeguards](/en/security#additional-safeguards) note. Trusting a parent directory doesn't apply a nested project's allow rules.\n\n`.claude/settings.local.json` is your own file, so the workspace trust check usually doesn't apply to it. When a repository could have supplied the file, such as when it is committed to git or `.claude` is a symlink, its allow rules and additional directories go through the trust check like project settings.\n\nAllow rules and additional directories in `.claude/settings.local.json` also apply without workspace trust in two cases:\n\n* The directory you started Claude Code from isn't inside a git repository.\n* The session runs in your own configuration home: your home directory or any directory whose `.claude` subdirectory you've set as [`CLAUDE_CONFIG_DIR`](/en/env-vars).\n\nIn both cases the file is one you created rather than one a repository could have supplied, and a repository-committed `.claude/settings.local.json` still requires workspace trust. Versions 2.1.196 through 2.1.199 treated the file as repository-supplied in those workspaces, ignored its allow rules, and printed a [`this workspace has not been trusted`](/en/errors#workspace-has-not-been-trusted) warning to stderr. The two exceptions above match v2.1.195 and earlier and were restored in v2.1.200.\n\nAlso as of v2.1.200, a workspace whose allow rules or additional directories still aren't applied, but that never showed the trust dialog because a parent directory was already trusted, shows the dialog the next time you start Claude Code there interactively. The dialog offers two choices:\n\n* **Yes, I trust this folder**: saves trust for that workspace and applies the rules in the same session.\n* **No, continue without these permissions**: keeps working with those rules ignored. The dialog appears again in the next session.\n\nIn [non-interactive mode](/en/headless) with `-p`, no dialog appears and the rules stay ignored.\n\n## Example configurations\n\nThis [repository](https://github.com/anthropics/claude-code/tree/main/examples/settings) includes starter settings configurations for common deployment scenarios. Use these as starting points and adjust them to fit your needs.\n\n## See also\n\n* [Settings](/en/settings): complete configuration reference including the permission settings table\n* [Configure auto mode](/en/auto-mode-config): tell the auto mode classifier which infrastructure your organization trusts\n* [Sandboxing](/en/sandboxing): OS-level filesystem and network isolation for Bash commands\n* [Authentication](/en/authentication): set up user access to Claude Code\n* [Security](/en/security): security safeguards and best practices\n* [Hooks](/en/hooks-guide): automate workflows and extend permission evaluation\n"}]},"uuid":"0eaab3f7-a53c-411b-95b0-9036cf7b131e","timestamp":"2026-07-11T09:48:08.240Z","toolUseResult":{"bytes":48062,"code":200,"codeText":"OK","result":"> ## Documentation Index\n> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt\n> Use this file to discover all available pages before exploring further.\n\n# Configure permissions\n\n> Control what Claude Code can access and do with fine-grained permission rules, modes, and managed policies.\n\nClaude Code supports fine-grained permissions so that you can specify exactly what the agent is allowed to do and what it can't. Permission settings can be checked into version control and distributed to all developers in your organization, as well as customized by individual developers.\n\n## Permission system\n\nClaude Code uses a tiered permission system to balance power and safety:\n\n| Tool type         | Example          | Approval required                                                                   | \"Yes, don't ask again\" behavior               |\n| :---------------- | :--------------- | :---------------------------------------------------------------------------------- | :-------------------------------------------- |\n| Read-only         | File reads, Grep | No, within the [working directory and additional directories](#working-directories) | N/A                                           |\n| Bash commands     | Shell execution  | Yes, except a built-in set of [read-only commands](#read-only-commands)             | Permanently per project directory and command |\n| File modification | Edit/write files | Yes                                                                                 | Until session end                             |\n\n## Manage permissions\n\nYou can view and manage Claude Code's tool permissions with `/permissions`. This UI lists all permission rules and the `settings.json` file each rule comes from.\n\n* **Allow** rules let Claude Code use the specified tool without manual approval.\n* **Ask** rules prompt for confirmation whenever Claude Code tries to use the specified tool.\n* **Deny** rules prevent Claude Code from using the specified tool.\n\nRules are evaluated in order: deny, then ask, then allow. The first match in that order determines the outcome, and rule specificity doesn't change the order.\n\nA broad deny rule like `Bash(aws *)` blocks every matching call, including calls that also match a narrower allow rule like `Bash(aws s3 ls)`, so a deny rule can't carry allowlist exceptions. The same precedence applies between ask and allow: a matching ask rule prompts even when a more specific allow rule also matches the same call.\n\nDeny rules behave differently depending on whether they name a tool or scope a pattern within one. A bare tool name like `Bash` removes the tool from Claude's context entirely, so Claude never sees it. A scoped rule like `Bash(rm *)` leaves the tool available and blocks matching calls when Claude attempts them.\n\n<Note>\n  Permission rules are enforced by Claude Code, not by the model. Instructions in your prompt or `CLAUDE.md` shape what Claude tries to do, but they don't change what Claude Code allows. To grant or revoke access, use `/permissions`, the rules described here, a [permission mode](/en/permission-modes), or a [PreToolUse hook](#extend-permissions-with-hooks).\n</Note>\n\n## Permission modes\n\nClaude Code supports several permission modes that control how it approves tool calls. See [Permission modes](/en/permission-modes) for when to use each one. Set the `defaultMode` in your [settings files](/en/settings#settings-files):\n\n| Mode                | Description                                                                                                                                                                                                                                                                  |\n| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `default`           | Standard behavior: prompts for permission on first use of each tool. {/* min-version: 2.1.200 */}Labeled Manual in the CLI and the VS Code and JetBrains extensions, and Claude Code accepts `manual` as an alias. The label and alias require Claude Code v2.1.200 or later |\n| `acceptEdits`       | Automatically accepts file edits and common filesystem commands such as `mkdir`, `touch`, `mv`, and `cp` for paths in the working directory or `additionalDirectories`                                                                                                       |\n| `plan`              | Claude reads files and runs read-only shell commands to explore but doesn't edit your source files. Labeled Plan in the CLI and the VS Code extension                                                                                                                        |\n| `auto`              | Auto-approves tool calls with background safety checks that verify actions align with your request                                                                                                                                                                           |\n| `dontAsk`           | Auto-denies tools unless pre-approved via `/permissions` or `permissions.allow` rules                                                                                                                                                                                        |\n| `bypassPermissions` | Skips permission prompts, except those forced by explicit `ask` rules. Root and home directory removals such as `rm -rf /` also still prompt as a circuit breaker                                                                                                            |\n\n<Warning>\n  `bypassPermissions` mode skips permission prompts, including for writes to `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn`, and `.mvn`. Explicit `ask` rules still force a prompt, and removals targeting the filesystem root or home directory, such as `rm -rf /` and `rm -rf ~`, still prompt as a circuit breaker against model error. Only use this mode in isolated environments like containers or VMs where Claude Code can't cause damage.\n</Warning>\n\nTo prevent `bypassPermissions` or `auto` mode from being used, set `permissions.disableBypassPermissionsMode` or `permissions.disableAutoMode` to `\"disable\"` in any [settings file](/en/settings#settings-files). These are most useful in [managed settings](#managed-settings) where they can't be overridden.\n\n## Permission rule syntax\n\nPermission rules follow the format `Tool` or `Tool(specifier)`.\n\n### Match all uses of a tool\n\nTo match all uses of a tool, use only the tool name without parentheses:\n\n| Rule       | Effect                         |\n| :--------- | :----------------------------- |\n| `Bash`     | Matches all Bash commands      |\n| `WebFetch` | Matches all web fetch requests |\n| `Read`     | Matches all file reads         |\n\n`Bash(*)` is equivalent to `Bash` and matches all Bash commands. As a deny rule, both forms remove the tool from Claude's context.\n\n### Use specifiers for fine-grained control\n\nAdd a specifier in parentheses to match specific tool uses:\n\n| Rule                           | Effect                                                   |\n| :----------------------------- | :------------------------------------------------------- |\n| `Bash(npm run build)`          | Matches the exact command `npm run build`                |\n| `Read(./.env)`                 | Matches reading the `.env` file in the current directory |\n| `WebFetch(domain:example.com)` | Matches fetch requests to example.com                    |\n\n### Match by input parameter\n\nDeny and ask rules can match a top-level input parameter on any tool with `Tool(param:value)`. The rule matches when Claude calls the tool with that parameter set to that exact value. An allow rule for one parameter value wouldn't establish that the call is safe overall, so allow rules continue to use each tool's own specifier syntax. This works for any scalar parameter the tool accepts:\n\n| Rule                           | Matches                                      |\n| :----------------------------- | :------------------------------------------- |\n| `Agent(model:opus)`            | Agent calls that request the Opus model tier |\n| `Agent(isolation:worktree)`    | Agent calls that request a git worktree      |\n| `Bash(run_in_background:true)` | Bash calls that run in the background        |\n\nParameter matching follows these rules:\n\n* The parameter name must be a direct field of the tool's input, such as `model` on the Agent tool. Fields nested inside an object or array are not matchable\n* Each rule names one parameter. To gate on both `model` and `isolation`, write two rules, `Agent(model:opus)` and `Agent(isolation:worktree)`, rather than combining them in one rule\n* The value supports `*` as a wildcard that matches any sequence of characters, so `Agent(isolation:*)` matches any explicit isolation value. Without `*` the match is exact\n* A parameter the model omits is never matched, so `Agent(model:*)` doesn't match a call that leaves `model` unset\n* The value is compared against the literal input Claude sends, before any normalization. `Agent(model:opus)` matches the alias `opus` but not a full model ID. Run with [`--verbose`](/en/cli-reference) to see the exact parameter names and values in each tool call\n* Whitespace around the colon is ignored\n\nFields that a tool already matches with its own canonicalizing rules are not matchable this way: `command` for Bash and PowerShell, `file_path` for Read, Edit, and Write, `path` for Grep and Glob, `notebook_path` for NotebookEdit, and `url` for WebFetch. A rule like `Bash(command:rm *)` would be bypassable by a compound command, so Claude Code ignores it and emits a startup warning. Use `Bash(rm *)`, `Read(./path)`, or `WebFetch(domain:host)` instead.\n\n### Wildcard patterns\n\nBash rules support glob patterns with `*`. Wildcards can appear at any position in the command. This configuration allows npm and git commit commands while blocking git push:\n\n```json theme={null}\n{\n  \"permissions\": {\n    \"allow\": [\n      \"Bash(npm run *)\",\n      \"Bash(git commit *)\",\n      \"Bash(git * main)\",\n      \"Bash(* --version)\",\n      \"Bash(* --help *)\"\n    ],\n    \"deny\": [\n      \"Bash(git push *)\"\n    ]\n  }\n}\n```\n\nThe space before `*` matters: `Bash(ls *)` matches `ls -la` but not `lsof`, while `Bash(ls*)` matches both. The `:*` suffix is an equivalent way to write a trailing wildcard, so `Bash(ls:*)` matches the same commands as `Bash(ls *)`.\n\nThe permission dialog writes the space-separated form when you select \"Yes, don't ask again\" for a command prefix. The `:*` form is only recognized at the end of a pattern. In a pattern like `Bash(git:* push)`, the colon is treated as a literal character and won't match git commands.\n\n### Tool name wildcards\n\nDeny and ask rules also accept glob patterns in the tool-name position. The pattern must match the full tool name: `\"*\"` matches every tool, and `\"mcp__*\"` matches every MCP tool across all servers. A tool matched by a bare-name glob deny rule is removed from Claude's context, the same as a bare tool name. This configuration denies every MCP tool:\n\n```json theme={null}\n{\n  \"permissions\": {\n    \"deny\": [\n      \"mcp__*\"\n    ]\n  }\n}\n```\n\nAllow rules accept tool-name globs only after a literal `mcp__<server>__` prefix. The server segment must be glob-free so the rule names a specific server you configured. `mcp__puppeteer__*` matches every tool from the `puppeteer` server, and `mcp__github__get_*` matches its `get_` tools. An unanchored allow glob such as `\"*\"`, `\"B*\"`, or `\"mcp__*\"` is skipped with a warning and doesn't auto-approve anything.\n\nA deny or ask rule whose tool name matches no known tool produces a startup warning to catch typos. Tool names containing `_` or `*` are exempt from the check.\n\nThe label shown for a tool in the transcript and permission dialog can differ from its canonical name. For example, the tool labeled `Stop Task` in the transcript has the canonical name `TaskStop`. Permission rules and [hook matchers](/en/hooks) match the canonical name only, so a rule written as `Stop Task` doesn't match. For deny and ask rules, the startup warning above catches the mismatch. Use the canonical names listed in the [tools reference](/en/tools-reference).\n\n## Tool-specific permission rules\n\n### Bash\n\nBash permission rules support wildcard matching with `*`. Wildcards can appear at any position in the command, including at the beginning, middle, or end:\n\n* `Bash(npm run build)` matches the exact Bash command `npm run build`\n* `Bash(npm run test *)` matches Bash commands starting with `npm run test`\n* `Bash(npm *)` matches any command starting with `npm `\n* `Bash(* install)` matches any command ending with ` install`\n* `Bash(git * main)` matches commands like `git checkout main` and `git log --oneline main`\n\nA single `*` matches any sequence of characters including spaces, so one wildcard can span multiple arguments. `Bash(git *)` matches `git log --oneline --all`, and `Bash(git * main)` matches `git push origin main` as well as `git merge main`.\n\nWhen `*` appears at the end with a space before it (like `Bash(ls *)`), it enforces a word boundary, requiring the prefix to be followed by a space or end-of-string. For example, `Bash(ls *)` matches `ls -la` but not `lsof`. In contrast, `Bash(ls*)` without a space matches both `ls -la` and `lsof` because there's no word boundary constraint.\n\n#### Compound commands\n\n<Tip>\n  Claude Code is aware of shell operators, so a rule like `Bash(safe-cmd *)` won't give it permission to run the command `safe-cmd && other-cmd`. The recognized command separators are `&&`, `||`, `;`, `|`, `|&`, `&`, and newlines. A rule must match each subcommand independently.\n</Tip>\n\nWhen you approve a compound command with \"Yes, don't ask again\", Claude Code saves a separate rule for each subcommand that requires approval, rather than a single rule for the full compound string. For example, approving `git status && npm test` saves a rule for `npm test`, so future `npm test` invocations are recognized regardless of what precedes the `&&`. Subcommands like `cd` into a subdirectory generate their own Read rule for that path. Up to 5 rules may be saved for a single compound command.\n\n#### Process wrappers\n\nBefore matching Bash rules, Claude Code strips a fixed set of process wrappers so a rule like `Bash(npm test *)` also matches `timeout 30 npm test`. The recognized wrappers are `timeout`, `time`, `nice`, `nohup`, and `stdbuf`.\n\nBare `xargs` is also stripped, so `Bash(grep *)` matches `xargs grep pattern`. Stripping applies only when `xargs` has no flags: an invocation like `xargs -n1 grep pattern` is matched as an `xargs` command, so rules written for the inner command do not cover it.\n\nThis wrapper list is built in and is not configurable. Development environment runners such as `direnv exec`, `devbox run`, `mise exec`, `npx`, and `docker exec` are not in the list. Because these tools execute their arguments as a command, a rule like `Bash(devbox run *)` matches whatever comes after `run`, including `devbox run rm -rf .`. To approve work inside an environment runner, write a specific rule that includes both the runner and the inner command, such as `Bash(devbox run npm test)`. Add one rule per inner command you want to allow.\n\nExec wrappers such as `watch`, `setsid`, `ionice`, and `flock` always prompt and can't be auto-approved by a prefix rule like `Bash(watch *)`. The same applies to `find` with `-exec` or `-delete`: a `Bash(find *)` rule doesn't cover these forms. To approve a specific invocation, write an exact-match rule for the full command string.\n\n#### Read-only commands\n\nClaude Code recognizes a built-in set of Bash commands as read-only and runs them without a permission prompt in every mode. These include `ls`, `cat`, `echo`, `pwd`, `head`, `tail`, `grep`, `find`, `wc`, `which`, `diff`, `stat`, `du`, `cd`, and read-only forms of `git`. The set is not configurable; to require a prompt for one of these commands, add an `ask` or `deny` rule for it.\n\nUnquoted glob patterns are permitted for commands whose every flag is read-only, so `ls *.ts` and `wc -l src/*.py` run without a prompt. Commands with write-capable or exec-capable flags, such as `find`, `sort`, `sed`, and `git`, still prompt when an unquoted glob is present because the glob could expand to a flag like `-delete`.\n\nA `cd` into a path inside your working directory or an [additional directory](#working-directories) is also read-only. A compound command like `cd packages/api && ls` runs without a prompt when each part qualifies on its own. Combining `cd` with `git` in one compound command prompts when the `cd` changes into a different directory, since running `git` in a new directory can execute that directory's hooks. A `cd` whose target resolves to the current working directory is a no-op and doesn't trigger this prompt.\n\n<Warning>\n  Bash permission patterns that try to constrain command arguments are fragile. For example, `Bash(curl http://github.com/ *)` intends to restrict curl to GitHub URLs, but won't match variations like:\n\n  * Options before URL: `curl -X GET http://github.com/...`\n  * Different protocol: `curl https://github.com/...`\n  * Redirects: `curl -L http://bit.ly/xyz`, which redirects to GitHub\n  * Variables: `URL=http://github.com && curl $URL`\n  * Extra spaces: `curl  http://github.com`\n\n  For more reliable URL filtering, consider:\n\n  * **Restrict Bash network tools**: use deny rules to block `curl`, `wget`, and similar commands, then use the WebFetch tool with `WebFetch(domain:github.com)` permission for allowed domains\n  * **Use PreToolUse hooks**: implement a hook that validates URLs in Bash commands and blocks disallowed domains\n  * **Add CLAUDE.md guidance**: describe your allowed curl patterns in `CLAUDE.md`. This shapes what Claude tries but doesn't enforce a boundary, so pair it with one of the options above\n\n  Note that using WebFetch alone doesn't prevent network access. If Bash is allowed, Claude can still use `curl`, `wget`, or other tools to reach any URL.\n</Warning>\n\n### PowerShell\n\nPowerShell permission rules use the same shape as Bash rules. Wildcards with `*` match at any position, the `:*` suffix is equivalent to a trailing ` *`, and a bare `PowerShell` or `PowerShell(*)` matches every command. This configuration allows `Get-ChildItem` and `git commit` commands while blocking `Remove-Item`:\n\n```json theme={null}\n{\n  \"permissions\": {\n    \"allow\": [\n      \"PowerShell(Get-ChildItem *)\",\n      \"PowerShell(git commit *)\"\n    ],\n    \"deny\": [\n      \"PowerShell(Remove-Item *)\"\n    ]\n  }\n}\n```\n\nCommon aliases are canonicalized before matching. A rule written for the cmdlet name also matches its aliases, so `PowerShell(Get-ChildItem *)` matches `gci`, `ls`, and `dir` as well. Matching is case-insensitive.\n\nClaude Code parses the PowerShell AST and checks each command in a compound command independently. Pipeline operators `|`, statement separators `;`, and on PowerShell 7+ the chain operators `&&` and `||` split a compound command into subcommands. A rule must match every subcommand for the compound command to be allowed.\n\n### Read and Edit\n\n`Edit` rules apply to all built-in tools that edit files. Claude makes a best-effort attempt to apply `Read` rules to all built-in tools that read files like Grep and Glob, to `@file` mentions in your prompts, and to the selection and open-file context that a connected [IDE](/en/vs-code#the-built-in-ide-mcp-server) shares with Claude.\n\n<Warning>\n  Read and Edit deny rules apply to Claude's built-in file tools and to file commands Claude Code recognizes in Bash, such as `cat`, `head`, `tail`, and `sed`. They don't apply to arbitrary subprocesses that read or write files indirectly, like a Python or Node script that opens files itself. For OS-level enforcement that blocks all processes from accessing a path, [enable the sandbox](/en/sandboxing).\n</Warning>\n\nRead and Edit rules both follow the [gitignore](https://git-scm.com/docs/gitignore) specification with four distinct pattern types:\n\n| Pattern            | Meaning                              | Example                          | Matches                                          |\n| ------------------ | ------------------------------------ | -------------------------------- | ------------------------------------------------ |\n| `//path`           | Absolute path from filesystem root   | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**`                        |\n| `~/path`           | Path from home directory             | `Read(~/Documents/*.pdf)`        | `/Users/alice/Documents/*.pdf`                   |\n| `/path`            | Path relative to the settings source | `Edit(/src/**/*.ts)`             | `<project root>/src/**/*.ts` in project settings |\n| `path` or `./path` | Path relative to current directory   | `Read(*.env)`                    | `<cwd>/*.env`                                    |\n\n<Warning>\n  A pattern like `/Users/alice/file` isn't an absolute path. The single leading slash anchors at the settings source, not the filesystem root. Use `//Users/alice/file` for absolute paths.\n</Warning>\n\nA `/path` pattern anchors at the directory associated with the settings file that defines it, so the same rule matches different locations depending on where you put it:\n\n| Rule defined in                                            | `/path` resolves to        |\n| :--------------------------------------------------------- | :------------------------- |\n| Project or local settings, such as `.claude/settings.json` | `<project root>/path`      |\n| User settings at `~/.claude/settings.json`                 | `~/.claude/path`           |\n| A file passed with `--settings <file>`                     | `<directory of file>/path` |\n| CLI flags, `/permissions`, or session rules                | `<original cwd>/path`      |\n\nA deny rule such as `Read(/secrets/**)` in user settings blocks `~/.claude/secrets/**`, not a `secrets` directory in your project. To write a rule in user settings that applies inside every project, use a `//` absolute path or a `~/` home-relative path instead.\n\nOn Windows, paths are normalized to POSIX form before matching. `C:\\Users\\alice` becomes `/c/Users/alice`, so use `//c/**/.env` to match `.env` files anywhere on that drive. To match across all drives, use `//**/.env`.\n\nExamples:\n\n* `Edit(/docs/**)`: edits in `<project>/docs/`, not `/docs/` or `<project>/.claude/docs/`\n* `Read(~/.zshrc)`: reads your home directory's `.zshrc`\n* `Edit(//tmp/scratch.txt)`: edits the absolute path `/tmp/scratch.txt`\n* `Read(src/**)`: reads from `<current-directory>/src/`\n\nA rule only matches files under its anchor, so the anchor determines how far a deny rule reaches. Bare filenames follow gitignore semantics and match at any depth, so `Read(.env)` and `Read(**/.env)` are equivalent:\n\n| Deny rule                       | Blocks                                       | Does not block                                       |\n| ------------------------------- | -------------------------------------------- | ---------------------------------------------------- |\n| `Read(.env)` or `Read(**/.env)` | any `.env` at or under the current directory | `.env` in a parent directory or another project      |\n| `Read(//**/.env)`               | any `.env` anywhere on the filesystem        | nothing; the rule is anchored at the filesystem root |\n\n<Note>\n  In gitignore patterns, `*` matches within a single path segment and can appear at any position in the pattern, while `**` matches across directories. To allow all file access, use only the tool name without parentheses: `Read`, `Edit`, or `Write`.\n</Note>\n\nWhen you approve a file path with \"Yes, don't ask again\", Claude Code escapes gitignore pattern characters in that path, such as `[`, `]`, and `*`, so the generated rule matches only the literal path you approved. Rules you write yourself aren't escaped. Before v2.1.202, Claude Code saved the path unescaped, so a generated rule for a directory named `[2024-06] Reports` could fail to match its own path or match unintended sibling directories.\n\nWhen Claude accesses a symlink, permission rules check two paths: the symlink itself and the file it resolves to. Allow and deny rules treat that pair differently: allow rules fall back to prompting you, while deny rules block outright.\n\n* **Allow rules**: apply only when both the symlink path and its target match. A symlink inside an allowed directory that points outside it still prompts you.\n* **Deny rules**: apply when either the symlink path or its target matches. A symlink that points to a denied file is itself denied.\n\nFor example, with `Read(./project/**)` allowed and `Read(~/.ssh/**)` denied, a symlink at `./project/key` pointing to `~/.ssh/id_rsa` is blocked: the target fails the allow rule and matches the deny rule.\n\n### WebFetch\n\nWebFetch rules use a `domain:` prefix and match against the hostname of the requested URL. Matching is case-insensitive, supports `*` wildcards, and strips a trailing `.` from both the rule and the hostname so `example.com.` and `example.com` are treated the same.\n\n* `WebFetch(domain:example.com)` matches requests to `example.com`\n* `WebFetch(domain:*.example.com)` matches any subdomain at any depth, such as `api.example.com` or `a.b.example.com`, but not `example.com` itself\n* `WebFetch(domain:*)` matches every domain and is equivalent to a bare `WebFetch` rule\n\nIn any position other than a leading `*.` or a bare `*`, the wildcard matches only the text between two dots. `WebFetch(domain:example.*)` matches `example.org`, where `*` becomes `org`, but not `example.evil.com`, where `*` would have to become `evil.com` and cross a dot. This keeps a trailing wildcard from matching domains an attacker could register.\n\n### MCP\n\nMCP rules use the server name as configured in Claude Code, optionally followed by the name of a tool from that server.\n\n* `mcp__puppeteer` matches any tool provided by the `puppeteer` server\n* `mcp__puppeteer__*` uses wildcard syntax and also matches all tools from the `puppeteer` server\n* `mcp__puppeteer__puppeteer_navigate` matches the `puppeteer_navigate` tool provided by the `puppeteer` server\n\n### Agent (subagents)\n\nUse `Agent(AgentName)` rules to control which [subagents](/en/sub-agents) Claude can use:\n\n* `Agent(Explore)` matches the Explore subagent\n* `Agent(Plan)` matches the Plan subagent\n* `Agent(my-custom-agent)` matches a custom subagent named `my-custom-agent`\n\nAdd these rules to the `deny` array in your settings or use the `--disallowedTools` CLI flag to disable specific agents. To disable the Explore agent:\n\n```json theme={null}\n{\n  \"permissions\": {\n    \"deny\": [\"Agent(Explore)\"]\n  }\n}\n```\n\n### Cd\n\n`Cd` rules control which directories the [`/cd` command](/en/commands) can move the session to. `Cd` is not a model-invocable tool: Claude can't call it, and the rules apply only when you run `/cd` yourself.\n\nA bare `Cd` deny rule disables `/cd` entirely. A `Cd(<path-pattern>)` deny rule blocks matching targets. Deny rules check every spelling of the target, including each symlink hop it resolves through, so a rule written for one path also blocks targets that resolve to it.\n\nAdding any `Cd` allow rule switches `/cd` to allowlist mode: the resolved target directory must match one of your allow rules, or `/cd` refuses. With no `Cd` rules configured, `/cd` keeps its default behavior and prompts you to trust an unfamiliar directory.\n\nPath patterns share the `//`, `~/`, and `/` anchors from [Read and Edit rules](#read-and-edit), but matching is anchored to the whole directory path rather than gitignore-style. `*` matches exactly one path segment and `**` matches across segments. A trailing `/**` also matches its named root.\n\n| Rule                  | Matches                                   | Does not match               |\n| --------------------- | ----------------------------------------- | ---------------------------- |\n| `Cd(~/code/*)`        | `~/code/app`                              | `~/code/app/src`, `~/code`   |\n| `Cd(~/code/**)`       | `~/code` and any directory under it       | directories outside `~/code` |\n| `Cd(**/node_modules)` | any `node_modules` directory at any depth | `node_modules/pkg`           |\n\n## Extend permissions with hooks\n\n[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 prompt. The hook output can deny the tool call, force a prompt, or skip the prompt to let the call proceed.\n\nHook decisions don't bypass permission rules. Deny and ask rules are evaluated regardless of what a PreToolUse hook returns, so a matching deny rule blocks the call and a matching ask rule still prompts even when the hook returned `\"allow\"` or `\"ask\"`. This preserves the deny-first precedence described in [Manage permissions](#manage-permissions), including deny rules set in managed settings.\n\nA blocking hook also takes precedence over allow rules. A hook that exits with code 2 stops the tool call before permission rules are evaluated, so the block applies even when an allow rule would otherwise let the call proceed. To run all Bash commands without prompts except for a few you want blocked, add `\"Bash\"` to your allow list and register a PreToolUse hook that rejects those specific commands. See [Block edits to protected files](/en/hooks-guide#block-edits-to-protected-files) for a hook script you can adapt.\n\n## Working directories\n\nBy default, Claude has access to files in the directory where you launched it. You can extend this access:\n\n* **During startup**: use `--add-dir <path>` CLI argument\n* **During session**: use `/add-dir` command\n* **Persistent configuration**: add to `additionalDirectories` in [settings files](/en/settings#settings-files)\n\nFiles 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.\n\nTo change the session's primary working directory instead of adding another, use [`/cd`](/en/commands). The `/cd` command requires Claude Code v2.1.169 or later. Unlike `/add-dir`, it relocates the session: the new directory's `CLAUDE.md` is loaded and `--resume` finds the session from there.\n\n### Additional directories grant file access, not configuration\n\nAdding a directory extends where Claude can read and edit files. It doesn't make that directory a full configuration root: most `.claude/` configuration is not discovered from additional directories, though a few types are loaded as exceptions.\n\nThese exceptions apply only to directories added with the `--add-dir` flag or the `/add-dir` command. Directories listed in `permissions.additionalDirectories` in a settings file grant file access only and don't load any of the configuration below.\n\nThe following configuration types are loaded from `--add-dir` directories:\n\n| Configuration                                                                         | Loaded from `--add-dir`                                                                                                                                            |\n| :------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [Skills](/en/skills) in `.claude/skills/`                                             | Yes, with live reload                                                                                                                                              |\n| [Subagents](/en/sub-agents) in `.claude/agents/`                                      | Yes                                                                                                                                                                |\n| [Settings](/en/settings) in `.claude/settings.json` and `.claude/settings.local.json` | `enabledPlugins` and `extraKnownMarketplaces` keys only                                                                                                            |\n| [CLAUDE.md](/en/memory) files, `.claude/rules/`, and `CLAUDE.local.md`                | Only when `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` is set. `CLAUDE.local.md` additionally requires the `local` setting source, which is enabled by default |\n\nCommands and output styles are discovered from the current working directory and its parents, your user directory at `~/.claude/`, and managed settings. Hooks and other `settings.json` keys load from the current working directory's `.claude/` folder with no parent-directory fallback, alongside your user `~/.claude/settings.json` and managed settings. To share that configuration across projects, use one of these approaches:\n\n* **User-level configuration**: place files in `~/.claude/agents/`, `~/.claude/output-styles/`, or `~/.claude/settings.json` to make them available in every project\n* **Plugins**: package and distribute configuration as a [plugin](/en/plugins) that teams can install\n* **Launch from the config directory**: run Claude Code from the directory containing the `.claude/` configuration you want\n\n## How permissions interact with sandboxing\n\nPermissions and [sandboxing](/en/sandboxing) are complementary security layers:\n\n* **Permissions** control which tools Claude Code can use and which files or domains it can access. They apply to all tools, including Bash, Read, Edit, WebFetch, and MCP.\n* **Sandboxing** provides OS-level enforcement that restricts the Bash tool's filesystem and network access. It applies only to Bash commands and their child processes.\n\nUse both for defense-in-depth:\n\n* Permission deny rules block Claude from even attempting to access restricted resources\n* Sandbox restrictions prevent Bash commands from reaching resources outside defined boundaries, even if a prompt injection bypasses Claude's decision-making\n* Filesystem restrictions in the sandbox combine the [`sandbox.filesystem`](/en/sandboxing) settings with Read and Edit deny rules; both are merged into the final sandbox boundary\n* Network restrictions combine WebFetch permission rules with the sandbox's `allowedDomains` and `deniedDomains` lists\n\nWhen sandboxing is enabled with `autoAllowBashIfSandboxed: true`, which is the default, sandboxed Bash commands run without prompting even if your permissions include a bare `Bash` ask rule, or the [equivalent `Bash(*)` form](#match-all-uses-of-a-tool): the sandbox boundary substitutes for that whole-tool prompt. These checks still apply:\n\n* Content-scoped ask rules like `Bash(git push *)` still force a prompt\n* Explicit deny rules still apply\n* `rm` or `rmdir` commands that target `/`, your home directory, or other critical system paths still trigger a prompt\n\nCommands that won't run sandboxed, such as excluded commands, respect the bare `Bash` ask rule as usual. See [sandbox modes](/en/sandboxing#sandbox-modes) to change this behavior.\n\n## Managed settings\n\nFor organizations that need centralized control over Claude Code configuration, administrators can deploy managed settings that can't be overridden by user or project settings. These policy settings follow the same format as regular settings files and can be delivered through MDM/OS-level policies, managed settings files, [server-managed settings](/en/server-managed-settings), or a self-hosted [Claude apps gateway](/en/claude-apps-gateway). See [settings files](/en/settings#settings-files) for delivery mechanisms and file locations.\n\n### Managed-only settings\n\nThe following settings are only read from managed settings. Placing them in user or project settings files has no effect.\n\n| Setting                                        | Description                                                                                                                                                                                                                                                                                                                         |\n| :--------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `allowAllClaudeAiMcps`                         | When `true`, claude.ai connectors load alongside a deployed `managed-mcp.json` instead of being suppressed by its exclusive control. See [Managed MCP configuration](/en/managed-mcp)                                                                                                                                               |\n| `allowedChannelPlugins`                        | Allowlist of channel plugins that may push messages. Replaces the default Anthropic allowlist when set. Requires `channelsEnabled: true`. See [Restrict which channel plugins can run](/en/channels#restrict-which-channel-plugins-can-run)                                                                                         |\n| `allowManagedHooksOnly`                        | When `true`, only managed hooks, SDK hooks, and hooks from plugins force-enabled in managed settings `enabledPlugins` are loaded. User, project, and all other plugin hooks are blocked                                                                                                                                             |\n| `allowManagedMcpServersOnly`                   | When `true`, only `allowedMcpServers` from managed settings are respected. `deniedMcpServers` still merges from all sources. See [Managed MCP configuration](/en/managed-mcp)                                                                                                                                                       |\n| `allowManagedPermissionRulesOnly`              | When `true`, prevents user and project settings from defining `allow`, `ask`, or `deny` permission rules. Only rules in managed settings apply. Doesn't affect the MCP server allowlist; for that, set `allowManagedMcpServersOnly`                                                                                                 |\n| `blockedMarketplaces`                          | Blocklist of marketplace sources. Blocked sources are checked before downloading, so they never touch the filesystem. See [managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions)                                                                                                              |\n| `channelsEnabled`                              | Allow [channels](/en/channels) for the organization. See [enterprise controls](/en/channels#enterprise-controls) for the default on each plan                                                                                                                                                                                       |\n| `disableSideloadFlags`                         | {/* min-version: 2.1.193 */}Reject the `--plugin-dir`, `--plugin-url`, `--agents`, and `--mcp-config` CLI flags at startup. Without this, users can bypass `strictKnownMarketplaces` for a single run by passing these flags. See [`disableSideloadFlags`](/en/settings#available-settings). Requires Claude Code v2.1.193 or later |\n| `forceRemoteSettingsRefresh`                   | When `true`, blocks CLI startup until remote managed settings are freshly fetched and exits if the fetch fails. See [fail-closed enforcement](/en/server-managed-settings#enforce-fail-closed-startup)                                                                                                                              |\n| `pluginTrustMessage`                           | Custom message appended to the plugin trust warning shown before installation                                                                                                                                                                                                                                                       |\n| `sandbox.filesystem.allowManagedReadPathsOnly` | When `true`, only `filesystem.allowRead` paths from managed settings are respected. `denyRead` still merges from all sources                                                                                                                                                                                                        |\n| `sandbox.network.allowManagedDomainsOnly`      | When `true`, only `allowedDomains` and `WebFetch(domain:...)` allow rules from managed settings are respected. Non-allowed domains are blocked automatically without prompting the user. Denied domains still merge from all sources                                                                                                |\n| `strictKnownMarketplaces`                      | Controls which plugin marketplace sources users can add and install plugins from. See [managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions)                                                                                                                                                  |\n| `strictPluginOnlyCustomization`                | Block skills, agents, hooks, and MCP servers from user and project sources, so they can only come from plugins or managed settings. `true` locks all four surfaces; an array such as `[\"skills\", \"hooks\"]` locks only the named ones. See [`strictPluginOnlyCustomization`](/en/settings#strictpluginonlycustomization)             |\n| `wslInheritsWindowsSettings`                   | When `true` in the Windows HKLM registry key or `C:\\Program Files\\ClaudeCode\\managed-settings.json`, WSL reads managed settings from the Windows policy chain in addition to `/etc/claude-code`. See [Settings files](/en/settings#settings-files)                                                                                  |\n\n`disableBypassPermissionsMode` is typically placed in managed settings to enforce organizational policy, but it works from any scope. A user can set it in their own settings to lock themselves out of bypass mode.\n\n<Note>\n  On Team and Enterprise plans, an Owner enables or disables [Remote Control](/en/remote-control) and [web sessions](/en/claude-code-on-the-web) organization-wide in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code). Remote Control can additionally be disabled per device with the [`disableRemoteControl`](/en/settings#available-settings) setting. Web sessions have no per-device managed settings key.\n</Note>\n\n## Settings precedence\n\nPermission rules follow the same [settings precedence](/en/settings#settings-precedence) as all other Claude Code settings:\n\n1. **Managed settings**: can't be overridden by any other level, including command line arguments\n2. **Command line arguments**: temporary session overrides\n3. **Local project settings** (`.claude/settings.local.json`)\n4. **Shared project settings** (`.claude/settings.json`)\n5. **User settings** (`~/.claude/settings.json`)\n\nIf a tool is denied at any level, no other level can allow it. For example, a managed settings deny can't be overridden by `--allowedTools`, and `--disallowedTools` can add restrictions beyond what managed settings define.\n\nThe same holds across settings scopes: if user settings allow a permission and project settings deny it, the deny rule blocks it. The reverse is also true: a user-level deny blocks a project-level allow, because deny rules from any scope are evaluated before allow rules.\n\nEmbedding hosts can supply additional managed policy via the SDK `managedSettings` option when [`parentSettingsBehavior`](/en/settings#settings-precedence) is set to `\"merge\"`; embedder values can tighten policy but not loosen it.\n\n## Project allow rules and workspace trust\n\n`permissions.allow` rules and `permissions.additionalDirectories` entries in a project's `.claude/settings.json` grant capability, so Claude Code applies them only after you accept the [workspace trust dialog](/en/security#additional-safeguards) for that workspace. Until then, Claude Code reads the rules but doesn't apply them. The trust dialog lists the allow rules and additional directories the folder would grant so you can review them before accepting. `deny` and `ask` rules aren't affected, since they only restrict.\n\nClaude Code saves trust per workspace, keyed on the git repository root or, outside a repository, the directory you started Claude Code from. When you start in your home directory, trust is held for the current session only and isn't written to disk; see the [additional safeguards](/en/security#additional-safeguards) note. Trusting a parent directory doesn't apply a nested project's allow rules.\n\n`.claude/settings.local.json` is your own file, so the workspace trust check usually doesn't apply to it. When a repository could have supplied the file, such as when it is committed to git or `.claude` is a symlink, its allow rules and additional directories go through the trust check like project settings.\n\nAllow rules and additional directories in `.claude/settings.local.json` also apply without workspace trust in two cases:\n\n* The directory you started Claude Code from isn't inside a git repository.\n* The session runs in your own configuration home: your home directory or any directory whose `.claude` subdirectory you've set as [`CLAUDE_CONFIG_DIR`](/en/env-vars).\n\nIn both cases the file is one you created rather than one a repository could have supplied, and a repository-committed `.claude/settings.local.json` still requires workspace trust. Versions 2.1.196 through 2.1.199 treated the file as repository-supplied in those workspaces, ignored its allow rules, and printed a [`this workspace has not been trusted`](/en/errors#workspace-has-not-been-trusted) warning to stderr. The two exceptions above match v2.1.195 and earlier and were restored in v2.1.200.\n\nAlso as of v2.1.200, a workspace whose allow rules or additional directories still aren't applied, but that never showed the trust dialog because a parent directory was already trusted, shows the dialog the next time you start Claude Code there interactively. The dialog offers two choices:\n\n* **Yes, I trust this folder**: saves trust for that workspace and applies the rules in the same session.\n* **No, continue without these permissions**: keeps working with those rules ignored. The dialog appears again in the next session.\n\nIn [non-interactive mode](/en/headless) with `-p`, no dialog appears and the rules stay ignored.\n\n## Example configurations\n\nThis [repository](https://github.com/anthropics/claude-code/tree/main/examples/settings) includes starter settings configurations for common deployment scenarios. Use these as starting points and adjust them to fit your needs.\n\n## See also\n\n* [Settings](/en/settings): complete configuration reference including the permission settings table\n* [Configure auto mode](/en/auto-mode-config): tell the auto mode classifier which infrastructure your organization trusts\n* [Sandboxing](/en/sandboxing): OS-level filesystem and network isolation for Bash commands\n* [Authentication](/en/authentication): set up user access to Claude Code\n* [Security](/en/security): security safeguards and best practices\n* [Hooks](/en/hooks-guide): automate workflows and extend permission evaluation\n","durationMs":231,"url":"https://code.claude.com/docs/en/permissions.md"},"sourceToolAssistantUUID":"9d53f008-3a68-425f-bf90-a733f177d892","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"0eaab3f7-a53c-411b-95b0-9036cf7b131e","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4QL6rQanUXM3WNeTUH","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"","signature":"EvpRCpMBCA8YAipAF2xc9CEWLTRdXPZ8HbTJQJTFx6h7n+IiDx7YHK+MX7nJvFz1r7iSpTtBd0+AlCDL4bSF6itrGCkbpEYjYydRuzIZY2xhdWRlLWhhaWt1LTQtNS0yMDI1MTAwMTgAQgh0aGlua2luZ1okNGJkZDE1Y2MtNDcxZS00ZTU2LWJhMWEtM2QzZDViNGYwMTdjEgyIyCUqYcxdSSKK0gwaDAksGBDVvEsWOrnDHyIwK22Xb+2RA7lmchZTOIerue3pHE18T0ofa8Zlt5SBU9gfmyeInpDkaar/L7hd30i7KpNQ/c4r0zM+tLxnMV0mnQXwBBnY1zoEueWuAuIp4sCFiRRwr7LMoVsZxe1pHF6AlLCb9C0xIH6re6/ZMJDvdWVq0dg5qniivOlWRfQxrvuhq1HlRdYQWEr0cOzDtqj84wsHjpdc+cZrk5AeRd54rrBPPZtDU0bA/hkrM1+un0LKOdIG1oromsEmRp9bDu3da21MXrdBUwE19SrhDa3AUAJYEaD39AWQ4h2tNOTTlNTDii4JLZ0L0bJ0TOuHqlT+hYME6YJu48eBhTRAphe7La4DeWToPz7oPRxrnMYL5/Jy2BMYxbWDjpe1t1nyA/ix9xvgUVyMoZmKLF4ZJtHOnzyXHYBMYcprU/lpmpOoTynrmotVoWMZq9XpQkoLQYoAGuddgZx+y0und3s124NLyN7LnSVaxXCyx9o918TqiMMw/lD6lO6ZCaE65b4fOb7tlFNZRqyk9TjIbnJvMUZRif7vdrbHtpomNTofGbyVrszJK4bp9galpKh2lbeSYdkJKCAPSd640LJ+aUwOlfDktA6ffhKASSHEqDSrsHA63YdWw6LrH7Bw/6+74ebYrqlbEMDN80bGC8xohb+tOjhtFPr3CNjNfMa8kq/heSQvTVzp2zAL2tjylyJSws6DqUG0emD6rXrWbaQK7XOpGG3PrCiX7Bh4Th1RgdMUI2S/w6Nc2OGnoWJ9s+RyA/JNGF0vJ97Yd8bd0QyqQGM1aR3/OzG07US3ygJx2jNkbCFnpd7Ge6C9CMU+0c6QClVkETR0ed42Pr77uhpxZLhHNkSbqmktGBYZJl4IGFmbvMjgCMIboOchA9LQ67lXK1RUheCZ4RqacOjRD5lQ2LGxzb2s2Gc3/aVVEfK5c9rfQWnrQqnmvpegdPUju5CcgnNhlgPPjYDvI6+kSGgw3YkYO0RixkOzRY1cFtDuso7LZd43ib5XoolC7XgWi7IRj4k2eAyEEgV79nsOc7ZdiGa6yc9TzotWqF0GDIlHvaGApt9sP9s3pgRFwwC1RVOtnOCjICuktiQemKwnuBeE1FnKL69H+yKGoKxQGD6fqnis0avnru0j+85UmIW4ZPhpjD80DS9oFBwMhJU017UejPOfvjaIxAhsVrXObz2NYW1Urun27/emX0Sbw64ny2gk7ZO6giu3KDc8RzpvGqpfNjVssBeare6dsp/jk+Nv8H2036cJ53te9H1PzCVndLfinoydkRph3SM773QFdcc4QhhbmJmOcvOmp33C8dOQPxNfXnXXULYnmPmFzYBlBhwTgUCclFFqJYTVhTuy2boT2hAHE35xoYgz4kX5rSyGS1cdlpu61Pq18cfFCYZgW3Bzjcw6MOo37cGw+/RzotDcFWOJ76EKW3bqJpTZXA3l+SlaUDEwhQ8swlvfXhKBCi6BPuyCKR4zvw4Bj/W66J9bToo7cCdtwINF/ypPTu/S7gIZkgfRBoz/Pe/4VonItkO+uEkMVz8gPdc9A33j/PXOHgKL9dNbU/WWRPAlB8sRt+iAZ2meUleg28H3t5ONVxrKaOCBGpaJ3P12tXKVXBbbEVjzUQatj9LBpuGe3fRWuG8XPYGEviEoCg0QUoQS2vlxvleIMQ9aAbM+dJAJBWhsE7niDupUpXl7a0jSMV0Vb0fyPMMtMIT6fuwTsJahON1QI6L7wzhtY4B9mZRnpl3o3tK/c+iljY1IEPOA8d5AWJyHj8bMTFqQ9RC6LhgwgtO+badaFKJ0NFAr3WlGtkR1zS1NJOyuvaTIvmm9Bq02fxJqivgUm/X6ywMfr/h6UeH0hGJTE4krQNhO+QApxmZYcXuFxAIHD56isYO6H8KGcsorXwTqjFlBo/BLqSN6wuyYM1gEZ4DU6TDfAPbiv2vD4KE9BixI91XnAYkR+qQ7pd5CFPXYSPmY/uObwUSEmdapl7oeR860iUMfGUfLARKALCSTubywAx4/oSBAz+urBZr1Ji2Qu9Bjji37s8I+fzOagnmaUYMeL4FoNZ4Ef+dHpwwWa4ZrnzlOF0T8NFSzy7JDAFM8idopuSI8mSN6TSqVgzl6OBDI07C7TnQvpKgEVPLCPlpRFpHfDss4Py23UJ19/N1l7Hv33fz/lYwn+HqQJh0vnlWQfUTgM27f2CWyqh3uPGsiKgZTfR0skhN1nrnqgHl/rIgXLm4UsGEfIvNwkqXk1C5qfN9KflJ6G3JCJMGvYuCeVB43iq29bmrgEWI62hvUv21XFLONrnuORUYQzGPayOHu4K6WF8vJn1W1wmIXf7BAcXGJQ2f/3Y/Qt/5bUTTDk1IkXKpa+bieIYGFnyjLN1IKKm5oerpylq996/zMh6/7PqiM0VOU0V4NrHkWVuGNatJ8s/1Cl7EDmHVvZKhhEGhPStLjNxEPON6wa57Yyao00xYX+Gs18VgzX/0ntvI1S96G1fAam+IkPYO1ZA0rzEpyArTWeVIRsY/6FR9aL456NubKCcYWci5rpzcLZjKIb32e2Lmrqb8CStPqAFFIOBUfSJYixnJqXSMnWla0B0EBjuNj7H6/6zE5o5X0GJqJ6sKUX6bypRxnO02aB+Smr6MIIU75K6U/OsXwvPTUAyx2uvBcvfjMB3Mf/tswaR1nFgx1WtcfXTCUCHymto/+QfBhftoj6n29hLpzx/mlf8nykLJveEIQuBnI2JXwpEmPFAzoUg8Ad6tCYdEc7eiYQbtebtpmjNIyZshKcmx6is51Pgvr7uL/nTa94VHHe9T0RhuA0uk51COcI6H7/NXoMZ5xx+1mg9pYBjr11945Nhe2f5uYgbQKT7JlYvvcy0U6cksgGFrtxytFPYdq72Dtx0wDt7UNOkrgybiurodFCj5fusaFg5XpvkL4dsYA0Zw9F6uys/vAVjVqQup9Qs5hxm2llBcIBnTsNHX4dVGq12p28jvuZGEH/LlpjwFNxEsECJFjtjzOOnpnpjQevKxkq1qmvZ8BsSCheFL9DOAeAFApNAKQ/rY0pggdijU/EDtPxgltgPH3HbSNBDc0xtZ7QJG7f40YKZEBzbICk9xf/oJEiUNxmB5ukhmxHLfmJaISjIHj6VWyguZ2uQgODFH3cowGnyylnHTz9pTu9grjWbMLL134bkiCCgiOXy3CMRV2+WX/KfIbjIjRASkBgkOrTYhqsTb/vu0Clx5p2HFgbbLqvl9y7TMUp3/fV5Wo7ryqXvnbkhOkbQvU8ieCzP9Q1bhCwa+1HvjRzwgMH+vtWm0o5QZH26yaSwnjQnw1wwtuadCtBY5YXd3nI/zzpp5Jd7ikpK2T7wdRL2X0G5CoxLzEKPLByRO36DSGk+28llhILmNdpz8Cs9uZhjeqnbxjGCRNqMruyA3GyHn1OhwbTz7PVW631DZHlJ+L7QN00jkqYmmxstmQ08SY0LmFQVQ7q0L3t2bi+BLa9ZCUK/cDxiZ7qBEk8cNijJHUrI0/Zi7oOyp5eUaoxXd4DXCNk//0ycFVlj+YArPvLwMNlMmamhFfZkWeQl8CI5W97AFN1YrvFxnVYRaf97yfWJpwNIrPf/jYju7WsTPnmVqsXpLsuHtsb5RvT1O1gXNiD0Hk9cRIYUOnzBOIZ+Yu/56dGOuWvgzywTFC5C9E+aBfS+/kcWSjNPiCyHroUYsIhASd2uMX2ImnC5isfVDnjU3WmryKZyfNYJSqNdw5JQdqG6sWjLMIE56r3SrxL1Rq+6H5eOyfCwaGolOGvBtd3XCvxIFdHs7ieWMgiVWAQu51LEOh9BrU57scttjpAhyLeOmdyZIOi363gP9btHwa4Km57yFx9VnUJ04nS1c+qve53cKGqsMCu4I8MNMbcfcTCjHcvP1zaaRmhOQQX84clVlB7dR2rN/EaiX9gJQeFAammqi7feziiON/ZEQwfi34D9i/ZzyLu63+4iXATgN0uK2nYwMi7cuzSc3VShv0Ivzt1c/2f1WYmzSCs/SKycZnz+hHAfMyLHkqDIFsqL0alzK4JfqHkF8h0hOxO1xdtn77Te8QC1CYySPI8mDLcfZBxp656hBrIION6HP6xlbN8Ii6klqtzybppn/ouz2o0/m6DHMFUiWWaEkX3XugfiG6iqjs/Mkq0o21QfWPnZqey0O0IDLCIc041VWgVFqfNMmllCtilCEqJDcBJ2xdh7gq1F96dtw0WBfmNhwk9dMh7oAEuukbhiF40faDdhxprT2T3X9Y7Z+VL0FrfioYFz/0DG3fR7kjGFYD0XqBWKM1pcFakP11wOGD/rgqD4psyeAca5ORIZJ4I7Dy5abyUPc070CDi90bUqEjxMbW53PkRGx7YRjj4GL1SiT1XjZhqNyRTn8CuUcitJPL6dwpk8Z9MesixBr7WEwptFpTo7lcUGb/eunJNv5+3BpyNWwRHRzClgulx8g8N2pO/UpEp++zdlISNLyv6xib6h7XaynXPc0kFXK7DrHU4rHKnOuBBvvRvo7hucKhMwhADOpOLUqdSrMG2QQ9p/lYmhv1C7QsUWc9gBL4TfWShE9cldN4AdNA0pT6kaZY9pZ5e3JRNAWQFYjkeIzfORNbaI5F2DylnBQ0Nvxu44WgGuFxP0WtsJ/trQYgbAxw3wOQSIpO3ieuL+V7EIKX/oQWnwDGmiFQHDDz7hEhpao/1anZjwTsxXFRWpTzawsN5BauBPCRrty+PvkYXGaYtysfacbRwHGyI9Ezj5J3S0IWpxFqLyssF3RNAGQLWm2KxXQrFcvPGEOk/7iWiTIE1JIL1XDhwJiFh8Umwk7eWl07n4pteZbrdzbVFEL2+EjdCIT9Dm63ci/VOJ5k5sNBjY/chFv2dWIAN52BL4jNQdchgfkksgquavQEgMxsY2i49BNyFrCp6G5I8YuIm6Bgts9YU3SfmMxQk6orRBbMG44SA/Z9A1OAF9V95pDylsMmItSYamSls26GGB0iTFoiybzMrbR9wo1KnuHCdDRrns9TQ2jPwMfANthv23p95zs4OYCyFXHpHYADsuSE77V02r8fktUA4Ns/VAwOSX8OTrAzpouf72Pph0rp6v05lZFZq49O67UZzCwSr3k1OOqN65afazBkLYjG/iO5p/vle+NDORw0Jka5NggfLA8NLUUJPiRkHumo7VCbJn+8aawPG5Hiic6X+h/lwHdy903wYrunEOre3DXXel9xWEj20YuOSKf8Up7o8eTXdojLOiHVXjcOvMtwjw4CzqkCALyVS9IrxjUOtwUvprRXBb+m+2vfyQgLgknd+qV/xXv1lTkuU3GvA4JkmNLbs7G1qjCwNacxQil0BemfGkf/UHCTR0xuFv3kV3DJLiFaVmboNrdSqCMaHNU9MV0P/zSKMrBBQy663BbPCbPuZf1BOWTuj3uTPvOY+4i/kVDfs6LWyPl22QsOBFF0sU+Fmbfp1smzB7mE6HEbAki7jkZ8EWIPRJkoInkgkwoeB5TonqLj4cQO3RrRwbqUMgHfZNp1LxKH6bvd/Iui8EJ0PjBCEJfAh9pDSVi9bRYZ/ZfPct+X36XRW2pXqTiBBVi3I+EWt1q4+cXsf3a67P5zQAJMtODEkd49OVz91jY4wETvsgNEuAXZUpMVofatgkGGiea/6LZgaH0cx2vC165ebFHdhwY5LdgM0oH/z32FDWRnJubNwt+qp7IMWcJdpdmvijDEkfY/QtonUFJ4YT60O/MW0f93Udmq/toe9U7dYWYpfQVHI6wmg21PlvKnj8bGEywSsY1SZvowe8aWn/k2RU7K2Vbnoaqfe65BT2dfrHwVN/hJF5EBi0mpcLBcdqi2H6/sa0+G5aUR3I/usIbMqp3edm8bLEJXiWrrgGU8ZP2zwBYdIyb5s7dSQLIqrOnS4NTIruh48ELstwJrL35xb+mwhneEG70+OJRE/wyVMNslXSMWwcpmWFHGmY17vfp9fEQ9OWg0bQTEZoQvmy6I5f5PbGifo95ZIGmMjayTK4ejeV2F4YstnGYcraAKh8q5hlPCkcomMWJFgSWSqKArKo4TCXsNS89G1Yk1NmbnqsNg4uCQx+P1zce1ZYJ2aLYbcvYLFwQ0WFvPebvUn9fRbyVULCOxquCmgrNU0QWqICVoQa4opL3UHAHSWR5FOP6D9oBKGB7Iuet0Zn6wSR340nVoAphuW3VRRjFwv89o1hKV2gT9klZqPBSnC+WYzC9xGUyL/ADZTkibipcubPR46r01DCLTdpZ0Uk15XnAkSDuHq7bvHcq7GLRKDmTqcnX8EQiG8lUfnkAAFC8f6g4Bs2mArNFPfY7zgZm+YUHTnOPBOtKdPpJfOi/lrGodVHRHz4lttVkeF55/rZTK/2tu0oAN9IE3c9SG3scH8j/dvkTDdH6fxgrx4RUtFwVxmAEEDOn10j4N/Mejn/7eNU3Kw+VbNAY9GSyPISYuSN1JPCwA/BS2nzVvYXZLYtEmvcxfmB2sxyPByd8kccNt7wNhjXLY5IhZZzqqxe4JTP8//UdQeTOwCT0L66b8qTxDjtzaZAPyQnYUs0A/5khbhTvM5QcDt6OqGYrDRT6L64XI+IEYAQ1cJDWLXiLWda3TEYdMwv34LebJW4wrtBna9SUc9ui9f1Gs5xXTIPrFnkEirAt2SicD1OeUWMQ5hkSZvvNmj3wwqCxtn8C81kQcywA8mnAjZspWahfROEH2rfnt9z6YZw0OjMQeeZana5tbSewjFgwTes83w4kxDeD7pSQlSfYmxe8q3kZEVs06hclHk2P4X+IJbNhLbqIk1l0VBe+Q5QIkTntxVrnt/D9YSO4LSJu3bEZl6JY8pIBmLsY27zWwNMo0jbYlCR1wl+3a0wFgclu19tlz6Djr1cW/S1X+shIF4h0bYgQiry7Cj8Mk/NorQJ0mSMRSnxxarD/rUe1APQ5kFXuAYK1uq68ISXL+RLr0PICEIcfwLcHEMpgU7TlATOe6TivT0mTR7FAhZsJeEdIgZ/5PVJMhpLW4Louhd/PItQi8wW+4mJxRLfb4wQzlcEEuu9YGCdOkSWQdCzVI5hq1n8IrbzVcctNEhAYoruMQSRZRG4Um6DTZSNH4l/yxQ3dY75vsxsBur5DHCPNtI6xK9Z7niDzcaP32TscbmBL6MwdgF5drPWOyeCs0PFKP2VoFesLTiDJytKayV2AmCr8EC4lMh69/LlQi9bdOJwfxJSvokPuKLGkau3pq0c0Jjus2egKFoU5cFptbjRaGS9ww63Qyt+jUSUI9rAAb0NhQFrXP8sypTIQiZuLcE3ZW5l9NbxjnEki8a5XFEzqGNyvdaGtrt1u5zwQoikIgXsdQWxFPkdzfXjcbsDex9s+2IOda2MLk/AS1W/lpLRglFRHYGYd62lmz8lUC2ZBo+gY7/US11eOedrOba4fVSZniKovc/H3AfHeSHg6dBi5ZPRmlsMCSougqOksYsdvo8aPJxlcYjmXKhQdpfXEPF/O5vEB6NEteaXOi33fpMfQlxKc5Gyqz3e8ri0bQIMyWTIyoXCUd21Ac35uWIDfDvcWFXCZgPPvYXZeGN8Eje3EWmXHKfgAy63eKOh12J/CSQxdQFkOg7n6Gv2ZIaWEz2KokuqEPCnMfoBYqyskjGZYQlaFPOcyP0gzVPfggAyvLBy8cYmtbAJiEFskDsaW9ko/nx3OjMVAoa7o30BtUXcmO1P3F2wDRnr4cRsoIQ6LE45gHmZOHkrOvbmyynERo8G2vKydx/3UdRn8CuceN9UrJwSY5/4AzDaziYj7vHcsJdJm09KqIjw/n/1ygS3naX4Y2nyHCXz4+G7VPvyDXZP/0rDttG2AH/wN/bg4phzEYBDMc7w5PJ6n5Tbgc9jzeOysvYJGf45o/XtcOWLUkmfNCR1VdIgCDA0IIzBNrTwCPlNgt0wlEqZumoE8o0+p2aX7rLE8qWWLPK4QmExBMJjrGbYIYLkk0x15W7IZJpiaV7ioDdR/k+V/WJvk/hdSR/TJG4Qj6CYUOalix06SrNqvPP1Z9aigCtn642JxWffImRGQ+L5HsIiHtQx4qmov5ccQroh3DwLwOZGOBhAS7s3BenVj4TZSdlHB0D03l1aVujye/jogv2YB9P31ybO7ZSQHpnqmXeIo2X0AIT7U6POgFbZ6UCApdCysANn5BdbWK/u+C4/+mt56OC6hYp19NlOl0sk37k5ssjXdlZ/TZwNyD5iJxNjS5zD2UNT+bUxmSEOgAg25o9UvFxOjEiOREtMo+WirYr//ExeL3wfKJrp3gzt6nF6q2OHabpS/JuWBaOSbvhVAQv6s8IbJTQW9rnYW4dbYglNEo0pGydF0CFf7qR9wUCcaLYyGFWUrQbjK5F2yCQvudQ8t7KjYkDkT+vgPksks3STM9WZ10jg6UcZtCAmhbA2Lc7ocdZaMmEGfxKiH97XZ4PzY40UVlx+DCaqGNjTB+xPIC5QYf9U8BF1+cZvoy/AB9Osq00v33BLOYCWAy6XqmngUtbISKG6j0JuAG43kUy18VxmeT77biKClBiEv+dlWRTPrj/2kabGASkUU7Zpht5Aj+GVxJxy9UmBY/G1sXzKgoS8vqnHS94IppHIhW8LljzmL0jTCYAvKYue+bA6q2u7hMUnzqeeHWQU+VZH+OsFER1zCRsmzATCMaHJBYaunROpjMw7IQcu5Qih1TvQnP/kx+N8IXnt6WpIYqDBhcPiRZ5MEhszeGY5/sHJl2fNzb+dafi7fGbNKvQUfs+ZotOPeEu0Ivvb93humFf7u840ctwTnFjQr8PKRtHL5w2z1ZRcog/ZdAlNITGopUOWoTe4c5HKEhFg2oplwXIuCek9FrDJ9WjzbFirUHd4qH/boBIDRaDMR6zm9czr+g7pOFDoBte4KGVzxsDJvMakWtYfA0f7dpWG0Z9bHdpaxWIZuTO6o44dNTQJRFSDMogg1NDfDZA8dXbmlnw149G5VI0ml6CVCBCg7qLy4VE6o9xBtkdlDU6koMiwjNrDhUlxP3WtfrBiM5Uyp/IcoO6KYrqt7awvVFSnlehXXAs5WEWGleXGf8hG0qA5Nm8CTb2UF6Es2NHfGyztbt3xjGncF9Z5jF1eWGFbrOXTbzFxHZyHntWsTQ23JyvIMY9XRo+Z0/kQGpm3LyYYeYVyUCpEflvjr56nh1PogzjoBYsbKJmM38t7m72/AwlTo+usu6lA2pwwsgd4wSad2EBbAdC5nlCQ9jQXPNXoAXFuVdltPmAE/WHUvS290O7g0F+0H39DMaF5x3cE/nL/DNpzZVDPfz0Ivza7uQgoZABqlomrgWQjAu59mGoG7mmgc7jrkddo/xGIzkHR98JMDAkhH8RQUxKvDyiNKpEgiQTHePazU7JQ+9ng+/RuDcqJTB6eQli+otADI0E6A84w0cnp7CvJadS8W24dMyJTdr3trkFabi/mS5vsx71ZxgFgqgEFIuRHwQQ+w92Iy7xT0T1gJOCXTCgoW6D0anUn30V0LHqPLSiCpGASw+cpF31tRwrA/T19pp837etf8AGSRMhAQwz0qPftNvZoOTS/W1QlPFVbZHyM1DqhkoTGE9/2damsSBvHptVtAt70tafdHKndHkgfhWlNhqkUXmvjenp5bPTj3hTZZUaroCRm3EqTh6lDVHYCLMokNCyhr3Vi1QfrOgyQN52PKtCUbzRogRva5zJrHIFMZ3M8QqORgzK3ryA1OjGXsLaMlpLsP8mleyz+kd9fb2+QnZkUgwKyZ/fFGA2JoJQuP1YIrbbmhDBSwB2Cp4t0jR4JCqfpyVEncD24FwcygEjvAOMarP01jdmPjz1xyhtn2gk6lkS9dgVg07xpVfHUP2eaGRfN83T18x+o0iOYIjJfuKMlr7hAlEPJ4C+xd9QfaoikDSbBUZOXUvrL66Bt7+q2KALI1EyhR5fuZwxcBYAO4moDkEc59IeovFRiA60AEBSfTKlKAzawDxME4O98o/04SwROdxkUEl7T0AB8fG3ZY2cli4uGUW063MBIPNpl3PmPI0jT2V/hWr9EALedLVx6WIzlNXk3KswWwwEc5JqMbf7aBxEcEeMlsYLdsOycpTC1J/ARaXdMMKyQ8yV9byS/5b6oXd6aV/zJ/d8PTHiOKMxu8/JCk4mpGD7ABwXQEAcbANc0gjsRX3jhMDcdgEwjJgHtgsrI9xMItqDhp/VqNvgee+pdGeCsgILScGHRQ0kVCumZnwcuXZAhEpa2lsiUXhOf+jNEJysZnRL7aqP7ipWtFH3nMrkb9KVabDc0cpxKbo1tugjK/F3YlTg4fO/yfVYG454rOGJAam1C9ESec8dUoBKyZvcA7FvQlCBASO7cs9kXxbooHgtMMB7aittD3O7d0+CxP6mxmQTuShhcsdTrWMCBJ7RtV/it3yVkf1m2W3xsWrMLGsV5DgDqJSxAGpq0mhpLLcLJ61GKsyKhOZRLOKCwUM8F/aHzgVNnmy9ptwDuDdIDAX60HqcFJ1Dqn46TCBVpdNIyBjyc27kumbN/PEZQvd2sqWf+6mkAJnJxaYweSlKrEGFyQwr5aIBz2JqlqXcjdIGZchS9lwTSc2YL9ZPIFRX0mwzuOCFX0AVGcf7edOAhdMAWYVmQaPMt1G1lZmO4ZGbdA7SUcFK+1Ilhqu/oM4QZmOWBA2UlVVtJpUmVAjQIcGUQw+WV70kAbsCmAmq+L1ViAsy8uK6op0m7c488s5V1LAx4N7tDmAGqS5wCpiAH8PCtLGuCxfyMa8bKE1O5DUlDNRlaDYcScLrRoDThsQa4p50AXL3ePNWySbol0eGDNO0dpaGOwo8QS4LJQVoUPLeGUjl+ut09kyB3fgBDyWX3ww9expCMxcvHMhjij7JOi9wv6im2Mtj+5izEMAeD2Jx71caUyUhrUBZxYVtXrFG/WXaLdtmp2uhGDe8Bvijn9sLYTveKfUn6CI8ega/D7rWOOgpBOy+UA8VP3BMzfQtu3eYxbbu09AXly7bVlkOKPsWp5FHCcugrjASJjDsJ8PldhmICkwDrWZQRQy6N31OedgjPTm0FP2qYoUh7ZUfS1KjKHnvlExWmpw0qKnsT0gFhS0WLIhfl0gihL8i6AtKprmXocunv+CnbCP+m0Z3mT5W9PssMYKtFgvhWHWPbHY2ikm0vZR7FLF2zEmfLxOzufrEJjK5w0Yzn8f9tIGr8z5p6cUxJO6zBhaHXjEh+Ip4KyhAAKu1dcmsCTyV2lxJpeYQAnvDgbn6FshtO7FKu9wxx/g88VgIs4lUueBGwNvrPlYIRBKV3PzvS76iBqMx/yQ52eRoetiB3+ArtBoQMcRTG5hmjJ+1ZtCXq3LPtDsYAAlAGiKuU5DBmTP44icnGN/0jQ0g6lNbzSEJIvNamDCdNRjR09HOCaX3LdBmHKzY/sQ3HbiSMCUUR0H4lPhP/am6YF0yNEhfF84FZacvVfAgtGeRphFTTABURfZFhS7W2LYNkWPSWqqDWBFubvccNNItknlwGHmY3gAH2RpKv9sWBuK5lSUBQEuqj5SXzeWhUuhk6ZHwBqOlDd1B8MxQ9OvCyDjdW40YTtpk0GzpD4YVVuRjzUHcypFb4oG/s6I47O2f3WYZIjCpPVfz0zFokoGJSuGb/tUAWe7u+JXYxCopEWFOg5iqthdrTks89VeN9bNh1OD1/ZMD7m01xGJHh9tkVkJkez5egNyaoqhlvI9AGbh56STohB266sWLXRCZAqPvdkoGZuUj49E2rpVgHW5TnyEHV6QGPDt18jHorx2UkgfH9I4e3T8cbv0ejOW6S3/xooiUxKPL8cBMPpl7b/4YDYuIK9w7YRmNffXWdrzxuSI0IibmNiRx6sqAZDGoyNYEEMkROr4/+BgyPa95dz6pe+GygyqFXHhk4EVzn27lOSnBysEnUQ0KXK9Aa41IjjMZz0oU4fg3BztcSSrnY/4ZnobEmkT+ESG3d/01+JsnbJG2a3WgUZ0MFLJCwOz9hvBggeV7h8y4mywTnRMdE6LCAdS/yU+gQv0DnEjlP2yO9UWuNZIRJ/1RTwT8lK1q1S6ZL5Wx7pEMeSX9q/3wyDFpBwpKspbd14s8KJPz7csyutHtXbqKRvKBU1QXkyGgDpI9aHTFw29gztg+xLBRZwKdjopOrUtlRBIXzSjLdy3e4swEmaq8TYOtJzOR7xl533RDVCCeH28vgEKbOxWEB26oPRVJF0ngXWDNFjKXEcZb8zT/BM/ieF2vFuVC04WuAt/XZN4oLoQHJvvP4BKPZovvJ8mGdTyhT2H0gZ9ezaptdmWlSb0KMqtClHpBHLqB/uLr3Nh2rF3yN7HaNAvKrmmNd1lsLnG0/Ttpj8bXcos4oP3gAA9QiC37GcxjYrXUe8jlt0qOsUHJ7muhE69JAydH6llQpN8xk+UgHIrrNNE1ELPHlJ84zYGmWlLrQwQgxp8BBBB0uHEJWw6ebOwJJ4fiPDMbaIqtiHdbpgmnfEHIltL/9bzqcCCBc/MhDLi6A2LBMMvA0b0IiEZ1sfA8RwLSyiMOjv5p47w9c6xfzNf50MDJgURaEyT1jaIrEdtrCV01YfZXc5M8QPsZQrj5c3o7hjLBjn5Gy4qnpXeg9EDa95KdUa5ywKEotQTyzwRU9m9OUFcCMGacWusRgfDJVLMZz9PmVs5a0g63DkKmMNtnCfYJrAiuxUsIpUz1W9gqeQwV547l6Y60ClX1kq6Zn8HBpLNfbf37NZYqS4NKUBMaRWKIf56aBFUEXjb5dOmzcT+XNMwFPhXC451uyqqSmN0JCgKhEowoYnb4OrbXaDDN9vGGb1lxGLPu1D9F4BnX+/ksVhbjvcZGXJvqE0U1CyejKbTKaaECYLFIXvx6vn3s/l0wSULSu8uFEuIJFhh5WxPvMp8KaHqEiOT8oN7zMYiPYil4UfG8v8oRdwEkk3AEY6c47t6m3njKLhiVKOufR9lSx+4uiU5pUG30tEy7mG6zE2GqjIWNRLgp5ic889VKVTD3LuXZ7GbMyPaeNK5oyk92Ee18xe0KSCQPrASBk9WIrQwFGEIUQNurjYbGTTghZd85UkQZe4n0JARJPLebC5dsUP/9zoseGthW6sXlp7jXFtv1gwAQ8vJ0SAg+IKEmNHbaMk7F6bHzzvTayBMAwPh8fKrYfVIqzM3zbw2psDBV4A75ZvEWTfU5t+nD+wFIx4gSSRIsSv6ll4KBtcyMc+ZQ+PkLOFd5uGaAhlNImX+Pgf3W7mJ5KAV9VIzOi8iymKf7OhEYP7Oukif39+XxvuV0sNPJJJRkfyiW2SObg//aMl/FYK15HlrIvaIgVTtK6v/FNRU4z4NykfU0kBRh+a2HC522JrSOnaSoZSvSRbWMy/kCMYPvAML9UuS5bMhcbJOALA+TrAu2zFAECjV2jDw2hPMaHjor9zC3mY9kthpHW6RYVvUZNVUsTdm9oz/ZUVbEyWZdDwWqJ1EzcRpFouxF3jgsL9usCuBwjVwXaQ0wZbDYeXbvUYaX1bjHHLjKW3MV0t9ghYj9hdiqamIJZ/RZ8j+ayMe4ftqNBWL6D0tq+fcpfJ5QLir8oc4ZVXd+6LNSbUdt5k4ExlFGRBV1PcPZ+gBf7T10swtuerLKKc8sYzx1WxEUcfjv8gotyKKgFHHQGrk3joWjbmBXTRg/Zvph1cOKbL7T2E1f6GffANTYDj9VbuIJ41+ofqGfs8Fqo6t7Tr1kpcwCxdima5LUltuti9onp3b2zCWGdiy/yp5CKH6oYuL4Ia+AMio25ER9jKuphn/df9FYzoeDdEcY74hdvAVOKV82jG7ynaMKfIYAQ=="}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":11191,"cache_read_input_tokens":34003,"cache_creation":{"ephemeral_5m_input_tokens":11191,"ephemeral_1h_input_tokens":0},"output_tokens":3,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null},"requestId":"req_011Ccv4QJufoUT1mKQsodvTA","attributionAgent":"claude-code-guide","type":"assistant","uuid":"43ff4d3f-1510-4c02-a268-30782f9474cb","timestamp":"2026-07-11T09:48:41.542Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}
{"parentUuid":"43ff4d3f-1510-4c02-a268-30782f9474cb","isSidechain":true,"agentId":"a556d2e38a847bf6e","message":{"model":"claude-haiku-4-5-20251001","id":"msg_011Ccv4QL6rQanUXM3WNeTUH","type":"message","role":"assistant","content":[{"type":"text","text":"Based on the official documentation, here are the precise answers:\n\n## 1. Separate server \"trust\" gate?\n\n**No separate gate documented for user-scope servers.** The `Pending approval` status shown in `/mcp` is *only* for project-scoped servers (those in `.mcp.json`). User-scoped servers written to `~/.claude.json` under the top-level `mcpServers` key have no separate approval step in the documentation. If your server shows `✓ Connected`, the server is loaded.\n\nIf you're still getting prompts despite that, it's a **tool-level permission issue**, not a server-approval issue.\n\n## 2. Where `permissions.allow` is read\n\n**Yes, `permissions.allow` is read from user-scope settings.** Settings precedence is:\n1. Managed settings\n2. Command line arguments  \n3. Local project (`.claude/settings.local.json`)\n4. Shared project (`.claude/settings.json`)\n5. **User** (`~/.claude/settings.json`, or `$CLAUDE_CONFIG_DIR/settings.json` if `CLAUDE_CONFIG_DIR` is set)\n\nSince you wrote to `$CLAUDE_CONFIG_DIR/settings.json`, it should be read as user settings. **However**: there's no explicit guarantee in the docs that `permissions.allow` for MCP tools from user-scope servers works the same as for project-scope ones. Known edge case: if this directory is *also* a git repo and `workspace trust` applies, project allow rules require trust acceptance—but user settings typically don't require that gate.\n\n## 3. Process restart requirement\n\n**Explicit only for `.mcp.json` changes**: \"After saving the file, start a new Claude Code session in the project. Claude Code reads `.mcp.json` at startup.\"\n\nFor `.claude.json` and `settings.json` changes, restart is **not explicitly documented**, but best practice: **start a new session**. These are read at startup, not hot-reloaded. A terminal that was already open when the files changed won't see updates.\n\n## 4. Permission string naming for direct `.claude.json` entries\n\n**Yes, correct.** The mangling uses the object key: `mcpServers.aicontrol` → `mcp__aicontrol__<toolname>`. If your tool is `write_panel`, the string `mcp__aicontrol__write_panel` is right. No additional prefix for user-scope.\n\nConfirm the exact tool name:\n```bash\nclaude mcp get aicontrol\n```\n\n## 5. Minimal config for zero-prompt execution\n\nAssuming `default` (Manual) permission mode:\n\n**In `$CLAUDE_CONFIG_DIR/.claude.json`:**\n```json\n{\n  \"mcpServers\": {\n    \"aicontrol\": {\n      \"type\": \"stdio\",\n      \"command\": \"…\",\n      \"args\": [\"--mcp-panel\"]\n    }\n  }\n}\n```\n\n**In `$CLAUDE_CONFIG_DIR/settings.json`:**\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"mcp__aicontrol__write_panel\"\n    ]\n  }\n}\n```\n\n**Then**: start a **fresh session** (`claude` from the shell). The tool should appear with no prompts.\n\n---\n\n### Diagnostics if it still prompts:\n\n1. **Verify tool name exactly**: run `/mcp` → select `aicontrol` → check the exact tool name listed (it might not be `write_panel`).\n2. **Verify permission string is loaded**: run `/permissions` → check that `mcp__aicontrol__write_panel` appears under **Allow** and shows source as `$CLAUDE_CONFIG_DIR/settings.json`.\n3. **Check JSON syntax**: malformed settings.json silently skips that file with no error.\n4. **Verify server scope**: in `.claude.json`, confirm the server is at the **top level** under `mcpServers`, not nested under a project entry (which would make it local-scoped).\n\nIf `/permissions` doesn't show your allow rule, the settings file isn't being read. If it does but you're still prompted, there may be an undocumented tool-approval gate or a version difference in behavior."}],"stop_reason":"end_turn","stop_sequence":null,"stop_details":null,"usage":{"input_tokens":8,"cache_creation_input_tokens":11191,"cache_read_input_tokens":34003,"output_tokens":3695,"server_tool_use":{"web_search_requests":0,"web_fetch_requests":0},"service_tier":"standard","cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":11191},"inference_geo":"not_available","iterations":[{"input_tokens":8,"output_tokens":3695,"cache_read_input_tokens":34003,"cache_creation_input_tokens":11191,"cache_creation":{"ephemeral_5m_input_tokens":11191,"ephemeral_1h_input_tokens":0},"type":"message"}],"speed":"standard"},"diagnostics":null},"requestId":"req_011Ccv4QJufoUT1mKQsodvTA","attributionAgent":"claude-code-guide","type":"assistant","uuid":"1571f1c6-dc92-4f0d-ba8b-8e634daa19c9","timestamp":"2026-07-11T09:48:53.005Z","userType":"external","entrypoint":"cli","cwd":"/Users/marcus.hinz/claude-projects/ai-control","sessionId":"f7704328-4eb4-4f0f-bf42-da68abab401d","version":"2.1.207","gitBranch":"main"}