Anthropic - Claude Code Docs Changes

amazon-bedrock.md +21 −10

Details

7Before configuring Claude Code with Bedrock, ensure you have:7Before configuring Claude Code with Bedrock, ensure you have:

8 8

9* An AWS account with Bedrock access enabled9* An AWS account with Bedrock access enabled

~~10* Access to desired Claude models (e.g., Claude Sonnet 4.5) in Bedrock~~10* Access to desired Claude models (for example, Claude Sonnet 4.5) in Bedrock

11* AWS CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)11* AWS CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)

12* Appropriate IAM permissions12* Appropriate IAM permissions

13 13

48export AWS_PROFILE=your-profile-name48export AWS_PROFILE=your-profile-name

49```49```

50 50

~~51**Option D: Bedrock API keys**~~51**Option D: AWS Management Console credentials**

53```bash theme={null}

54aws login

55```

57[Learn more](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html) about `aws login`.

59**Option E: Bedrock API keys**

52 60

53```bash theme={null}61```bash theme={null}

54export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key62export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

75 83

76##### Configuration settings explained84##### Configuration settings explained

77 85

78**`awsAuthRefresh`**: Use this for commands that modify the `.aws` directory (e.g., updating credentials, SSO cache, or config files). Output is shown to the user (but user input is not supported), making it suitable for browser-based authentication flows where the CLI displays a code to enter in the browser.86**`awsAuthRefresh`**: Use this for commands that modify the `.aws` directory, such as updating credentials, SSO cache, or config files. The command's output is displayed to the user, but interactive input isn't supported. This works well for browser-based SSO flows where the CLI displays a URL or code and you complete authentication in the browser.

79 87

80**`awsCredentialExport`**: Only use this if you cannot modify `.aws` and must directly return credentials. Output is captured silently (not shown to the user). The command must output JSON in this format:88**`awsCredentialExport`**: Only use this if you can't modify `.aws` and must directly return credentials. Output is captured silently and not shown to the user. The command must output JSON in this format:

81 89

82```json theme={null}90```json theme={null}

83{91{

119 127

120<Note>128<Note>

121 For Bedrock users, Claude Code will not automatically upgrade from Haiku 3.5 to Haiku 4.5. To manually switch to a newer Haiku model, set the `ANTHROPIC_DEFAULT_HAIKU_MODEL` environment variable to the full model name (e.g., `us.anthropic.claude-haiku-4-5-20251001-v1:0`).129 For Bedrock users, Claude Code won't automatically upgrade from Haiku 3.5 to Haiku 4.5. To manually switch to a newer Haiku model, set the `ANTHROPIC_DEFAULT_HAIKU_MODEL` environment variable to the full model name (for example, `us.anthropic.claude-haiku-4-5-20251001-v1:0`).

122</Note>130</Note>

123 131

124To customize models, use one of these methods:132To customize models, use one of these methods:

135export DISABLE_PROMPT_CACHING=1143export DISABLE_PROMPT_CACHING=1

136```144```

137 145

138<Note>146<Note>[Prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching) may not be available in all regions.</Note>

139 [Prompt caching](/en/docs/build-with-claude/prompt-caching) may not be available in all regions

140</Note>

141 147

142### 5. Output token configuration148### 5. Output token configuration

143 149

144When using Claude Code with Amazon Bedrock, we recommend the following token settings:150These are the recommended token settings for Claude Code with Amazon Bedrock:

145 151

146```bash theme={null}152```bash theme={null}

147# Recommended output token settings for Bedrock153# Recommended output token settings for Bedrock

151 157

152**Why these values:**158**Why these values:**

153 159

154* **`CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096`**: Bedrock's burndown throttling logic sets a minimum of 4096 tokens as the max\_token penalty. Setting this lower won't reduce costs but may cut off long tool uses, causing the Claude Code agent loop to fail persistently. Claude Code typically uses less than 4096 output tokens without extended thinking, but may need this headroom for tasks involving significant file creation or Write tool usage.160* **`CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096`**: Bedrock's burndown throttling logic sets a minimum of 4096 tokens as the `max_token` penalty. Setting this lower won't reduce costs but may cut off long tool uses, causing the Claude Code agent loop to fail persistently. Claude Code typically uses less than 4096 output tokens without extended thinking, but may need this headroom for tasks involving significant file creation or Write tool usage.

155 161

156* **`MAX_THINKING_TOKENS=1024`**: This provides space for extended thinking without cutting off tool use responses, while still maintaining focused reasoning chains. This balance helps prevent trajectory changes that aren't always helpful for coding tasks specifically.162* **`MAX_THINKING_TOKENS=1024`**: This provides space for extended thinking without cutting off tool use responses, while still maintaining focused reasoning chains. This balance helps prevent trajectory changes that aren't always helpful for coding tasks specifically.

157 163

223* [Bedrock pricing](https://aws.amazon.com/bedrock/pricing/)229* [Bedrock pricing](https://aws.amazon.com/bedrock/pricing/)

224* [Bedrock inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)230* [Bedrock inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)

225* [Claude Code on Amazon Bedrock: Quick Setup Guide](https://community.aws/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide)- [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)231* [Claude Code on Amazon Bedrock: Quick Setup Guide](https://community.aws/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide)- [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)

232

233

234---

235

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

analytics.md +5 −0

Details

85 85

86* [Monitoring usage with OpenTelemetry](/en/monitoring-usage) for custom metrics and alerting86* [Monitoring usage with OpenTelemetry](/en/monitoring-usage) for custom metrics and alerting

87* [Identity and access management](/en/iam) for role configuration87* [Identity and access management](/en/iam) for role configuration

90---

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

checkpointing.md +5 −0

Details

63* [Interactive mode](/en/interactive-mode) - Keyboard shortcuts and session controls63* [Interactive mode](/en/interactive-mode) - Keyboard shortcuts and session controls

64* [Slash commands](/en/slash-commands) - Accessing checkpoints using `/rewind`64* [Slash commands](/en/slash-commands) - Accessing checkpoints using `/rewind`

65* [CLI reference](/en/cli-reference) - Command-line options65* [CLI reference](/en/cli-reference) - Command-line options

68---

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

chrome.md +220 −0 added

Details

1# Use Claude Code with Chrome (beta)

3> Connect Claude Code to your browser to test web apps, debug with console logs, and automate browser tasks.

5<Note>

6 Chrome integration is in beta and currently works with Google Chrome only. It is not yet supported on Brave, Arc, or other Chromium-based browsers. WSL (Windows Subsystem for Linux) is also not supported.

7</Note>

9Claude Code integrates with the Claude in Chrome browser extension to give you browser automation capabilities directly from your terminal. Build in your terminal, then test and debug in your browser without switching contexts.

11## What the integration enables

13With Chrome connected, you can chain browser actions with terminal commands in a single workflow. For example: scrape documentation from a website, analyze it, generate code based on what you learned, and commit the result.

15Key capabilities include:

17* **Live debugging**: Claude reads console errors and DOM state directly, then fixes the code that caused them

18* **Design verification**: Build a UI from a Figma mock, then have Claude open it in the browser and verify it matches

19* **Web app testing**: Test form validation, check for visual regressions, or verify user flows work correctly

20* **Authenticated web apps**: Interact with Google Docs, Gmail, Notion, or any app you're logged into without needing API connectors

21* **Data extraction**: Pull structured information from web pages and save it locally

22* **Task automation**: Automate repetitive browser tasks like data entry, form filling, or multi-site workflows

23* **Session recording**: Record browser interactions as GIFs to document or share what happened

25## Prerequisites

27Before using Claude Code with Chrome, you need:

29* [Google Chrome](https://www.google.com/chrome/) browser

30* [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or higher

31* [Claude Code CLI](/en/quickstart#step-1:-install-claude-code) version 2.0.73 or higher

32* A paid Claude plan (Pro, Team, or Enterprise)

34## How the integration works

36Claude Code communicates with Chrome through the Claude in Chrome browser extension. The extension uses Chrome's [Native Messaging API](https://developer.chrome.com/docs/extensions/develop/concepts/native-messaging) to receive commands from Claude Code and execute them in your browser. This architecture lets Claude Code control browser tabs, read page content, and perform actions while you continue working in your terminal.

38When Claude encounters a login page, CAPTCHA, or other blocker, it pauses and asks you to handle it. You can provide credentials for Claude to enter, or log in manually in the browser. Once you're past the blocker, tell Claude to continue and it picks up where it left off.

40Claude opens new tabs for browser tasks rather than taking over existing ones. However, it shares your browser's login state, so if you're already signed into a site in Chrome, Claude can access it without re-authenticating.

42<Note>

43 The Chrome integration requires a visible browser window. When Claude performs browser actions, you'll see Chrome open and navigate in real time. There's no headless mode since the integration relies on your actual browser session with its login state.

44</Note>

46## Set up the integration

48<Steps>

49 <Step title="Update Claude Code">

50 Chrome integration requires a recent version of Claude Code. If you installed using the [native installer](/en/quickstart#step-1:-install-claude-code), updates happen automatically. Otherwise, run:

52 ```bash theme={null}

53 claude update

54 ```

55 </Step>

57 <Step title="Start Claude Code with Chrome enabled">

58 Launch Claude Code with the `--chrome` flag:

60 ```bash theme={null}

61 claude --chrome

62 ```

63 </Step>

65 <Step title="Verify the connection">

66 Run `/chrome` to check the connection status and manage settings. If the extension isn't detected, you'll see a warning with a link to install it.

67 </Step>

68</Steps>

70You can also enable Chrome integration from within an existing session using the `/chrome` slash command.

72## Try it out

74Once connected, type this into Claude to see the integration in action:

76```

77Go to code.claude.com/docs, click on the search box,

78type "hooks", and tell me what results appear

79```

81Claude opens the page, clicks into the search field, types the query, and reports the autocomplete results. This shows navigation, clicking, and typing in a single workflow.

83## Example workflows

85Claude can navigate pages, click and type, fill forms, scroll, read console logs and network requests, manage tabs, resize windows, and record GIFs. Run `/mcp` and click into `claude-in-chrome` to see the full list of available tools.

87The following examples show common patterns for browser automation.

89### Test a local web application

91When developing a web app, ask Claude to verify your changes work correctly:

93```

94I just updated the login form validation. Can you open localhost:3000,

95try submitting the form with invalid data, and check if the error

96messages appear correctly?

97```

99Claude navigates to your local server, interacts with the form, and reports what it observes.

100

101### Debug with console logs

102

103If your app has issues, Claude can read console output to help diagnose problems:

104

105```

106Open the dashboard page and check the console for any errors when

107the page loads.

108```

109

110Claude reads the console messages and can filter for specific patterns or error types.

111

112### Automate form filling

113

114Speed up repetitive data entry tasks:

115

116```

117I have a spreadsheet of customer contacts in contacts.csv. For each row,

118go to our CRM at crm.example.com, click "Add Contact", and fill in the

119name, email, and phone fields.

120```

121

122Claude reads your local file, navigates the web interface, and enters the data for each record.

123

124### Draft content in Google Docs

125

126Use Claude to write directly in your documents without API setup:

127

128```

129Draft a project update based on our recent commits and add it to my

130Google Doc at docs.google.com/document/d/abc123

131```

132

133Claude opens the document, clicks into the editor, and types the content. This works with any web app you're logged into: Gmail, Notion, Sheets, and more.

134

135### Extract data from web pages

136

137Pull structured information from websites:

138

139```

140Go to the product listings page and extract the name, price, and

141availability for each item. Save the results as a CSV file.

142```

143

144Claude navigates to the page, reads the content, and compiles the data into a structured format.

145

146### Run multi-site workflows

147

148Coordinate tasks across multiple websites:

149

150```

151Check my calendar for meetings tomorrow, then for each meeting with

152an external attendee, look up their company on LinkedIn and add a

153note about what they do.

154```

155

156Claude works across tabs to gather information and complete the workflow.

157

158### Record a demo GIF

159

160Create shareable recordings of browser interactions:

161

162```

163Record a GIF showing how to complete the checkout flow, from adding

164an item to the cart through to the confirmation page.

165```

166

167Claude records the interaction sequence and saves it as a GIF file.

168

169## Best practices

170

171When using browser automation, keep these guidelines in mind:

172

173* **Modal dialogs can interrupt the flow**: JavaScript alerts, confirms, and prompts block browser events and prevent Claude from receiving commands. If a dialog appears, dismiss it manually and tell Claude to continue.

174* **Use fresh tabs**: Claude creates new tabs for each session. If a tab becomes unresponsive, ask Claude to create a new one.

175* **Filter console output**: Console logs can be verbose. When debugging, tell Claude what patterns to look for rather than asking for all console output.

176

177## Troubleshooting

178

179### Extension not detected

180

181If Claude Code shows "Chrome extension not detected":

182

1831. Verify the Chrome extension (version 1.0.36 or higher) is installed

1842. Verify Claude Code is version 2.0.73 or higher by running `claude --version`

1853. Check that Chrome is running

1864. Run `/chrome` and select "Reconnect extension" to re-establish the connection

1875. If the issue persists, restart both Claude Code and Chrome

188

189### Browser not responding

190

191If Claude's browser commands stop working:

192

1931. Check if a modal dialog (alert, confirm, prompt) is blocking the page

1942. Ask Claude to create a new tab and try again

1953. Restart the Chrome extension by disabling and re-enabling it

196

197### First-time setup

198

199The first time you use the integration, Claude Code installs a native messaging host that allows communication between the CLI and Chrome. If you encounter permission errors, you may need to restart Chrome for the installation to take effect.

200

201## Enable by default

202

203Chrome integration requires the `--chrome` flag each time you start Claude Code. To enable it by default, run `/chrome` and select "Enabled by default".

204

205<Note>

206 Enabling Chrome by default increases context usage since browser tools are always loaded. If you notice increased context consumption, disable this setting and use `--chrome` only when needed.

207</Note>

208

209Site-level permissions are inherited from the Chrome extension. Manage permissions in the Chrome extension settings to control which sites Claude can browse, click, and type on. Run `/chrome` to see current permission settings.

210

211## See also

212

213* [CLI reference](/en/cli-reference) - Command-line flags including `--chrome`

214* [Common workflows](/en/common-workflows) - More ways to use Claude Code

215* [Getting started with Claude for Chrome](https://support.anthropic.com/en/articles/12012173-getting-started-with-claude-for-chrome) - Full documentation for the Chrome extension, including shortcuts, scheduling, and permissions

216

217

218---

219

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

claude-code-on-the-web.md +19 −5

Details

11Claude Code on the web lets developers kick off Claude Code from the Claude app. This is perfect for:11Claude Code on the web lets developers kick off Claude Code from the Claude app. This is perfect for:

12 12

13* **Answering questions**: Ask about code architecture and how features are implemented13* **Answering questions**: Ask about code architecture and how features are implemented

~~14* **Bugfixes and routine tasks**: Well-defined tasks that don't require frequent steering~~14* **Bug fixes and routine tasks**: Well-defined tasks that don't require frequent steering

15* **Parallel work**: Tackle multiple bug fixes in parallel15* **Parallel work**: Tackle multiple bug fixes in parallel

16* **Repositories not on your local machine**: Work on code you don't have checked out locally16* **Repositories not on your local machine**: Work on code you don't have checked out locally

17* **Backend changes**: Where Claude Code can write tests and then write code to pass those tests17* **Backend changes**: Where Claude Code can write tests and then write code to pass those tests

29 29

30* **Pro users**30* **Pro users**

31* **Max users**31* **Max users**

32 32* **Team premium seat users**

~~33Coming soon to Team and Enterprise premium seat users.~~33* **Enterprise premium seat users**

34 34

35## Getting started35## Getting started

36 36

92The universal image includes pre-configured environments for:92The universal image includes pre-configured environments for:

93 93

94* **Python**: Python 3.x with pip, poetry, and common scientific libraries94* **Python**: Python 3.x with pip, poetry, and common scientific libraries

~~95* **Node.js**: Latest LTS versions with npm, yarn, and pnpm~~95* **Node.js**: Latest LTS versions with npm, yarn, pnpm, and bun

96* **Ruby**: Versions 3.1.6, 3.2.6, 3.3.6 (default: 3.3.6) with gem, bundler, and rbenv for version management

97* **PHP**: Version 8.4.14

96* **Java**: OpenJDK with Maven and Gradle98* **Java**: OpenJDK with Maven and Gradle

97* **Go**: Latest stable version with module support99* **Go**: Latest stable version with module support

98* **Rust**: Rust toolchain with cargo100* **Rust**: Rust toolchain with cargo

99* **C++**: GCC and Clang compilers101* **C++**: GCC and Clang compilers

100 102

103#### Databases

104

105The universal image includes the following databases:

106

107* **PostgreSQL**: Version 16

108* **Redis**: Version 7.0

109

101### Environment configuration110### Environment configuration

102 111

103When you start a session in Claude Code on the web, here's what happens under the hood:112When you start a session in Claude Code on the web, here's what happens under the hood:

464 473

465## Best practices474## Best practices

466 475

4671. **Use Claude Code hooks**: Configure [sessionStart hooks](/en/hooks#sessionstart) to automate environment setup and dependency installation.4761. **Use Claude Code hooks**: Configure [SessionStart hooks](/en/hooks#sessionstart) to automate environment setup and dependency installation.

4682. **Document requirements**: Clearly specify dependencies and commands in your `CLAUDE.md` file. If you have an `AGENTS.md` file, you can source it in your `CLAUDE.md` using `@AGENTS.md` to maintain a single source of truth.4772. **Document requirements**: Clearly specify dependencies and commands in your `CLAUDE.md` file. If you have an `AGENTS.md` file, you can source it in your `CLAUDE.md` using `@AGENTS.md` to maintain a single source of truth.

469 478

470## Related resources479## Related resources

473* [Settings reference](/en/settings)482* [Settings reference](/en/settings)

474* [Security](/en/security)483* [Security](/en/security)

475* [Data usage](/en/data-usage)484* [Data usage](/en/data-usage)

485

486

487---

488

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

cli-reference.md +44 −20

Details

5## CLI commands5## CLI commands

6 6

~~8| :--------------------------------- | :--------------------------------------------- | :------------------------------------------------ |~~8| :------------------------------ | :--------------------------------------------- | :------------------------------------------------ |

18 18

21Customize Claude Code's behavior with these command-line flags:21Customize Claude Code's behavior with these command-line flags:

22 22

24| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |24| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------- |

26| `--agent` | Specify an agent for the current session (overrides the `agent` setting) | `claude --agent my-custom-agent` |

26| `--agents` | Define custom [subagents](/en/sub-agents) dynamically via JSON (see below for format) | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |27| `--agents` | Define custom [subagents](/en/sub-agents) dynamically via JSON (see below for format) | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

27| `--allowedTools` | A list of tools that should be allowed without prompting the user for permission, in addition to [settings.json files](/en/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Read"` |28| `--allowedTools` | Tools that execute without prompting for permission. To restrict which tools are available, use `--tools` instead | `"Bash(git log:*)" "Bash(git diff:*)" "Read"` |

28| `--disallowedTools` | A list of tools that should be disallowed without prompting the user for permission, in addition to [settings.json files](/en/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |29| `--append-system-prompt` | Append custom text to the end of the default system prompt (works in both interactive and print modes) | `claude --append-system-prompt "Always use TypeScript"` |

36| `--enable-lsp-logging` | Enable verbose LSP logging for debugging language server issues. Logs are written to `~/.claude/debug/` | `claude --enable-lsp-logging` |

37| `--fallback-model` | Enable automatic fallback to specified model when default model is overloaded (print mode only) | `claude -p --fallback-model sonnet "query"` |

38| `--fork-session` | When resuming, create a new session ID instead of reusing the original (use with `--resume` or `--continue`) | `claude --resume abc123 --fork-session` |

39| `--ide` | Automatically connect to IDE on startup if exactly one valid IDE is available | `claude --ide` |

35| `--include-partial-messages` | Include partial streaming events in output (requires `--print` and `--output-format=stream-json`) | `claude -p --output-format stream-json --include-partial-messages "query"` |40| `--include-partial-messages` | Include partial streaming events in output (requires `--print` and `--output-format=stream-json`) | `claude -p --output-format stream-json --include-partial-messages "query"` |

42| `--json-schema` | Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see [Agent SDK Structured Outputs](https://docs.claude.com/en/docs/agent-sdk/structured-outputs)) | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

44| `--mcp-config` | Load MCP servers from JSON files or strings (space-separated) | `claude --mcp-config ./mcp.json` |

38| `--model` | Sets the model for the current session with an alias for the latest model (`sonnet` or `opus`) or a model's full name | `claude --model claude-sonnet-4-5-20250929` |45| `--model` | Sets the model for the current session with an alias for the latest model (`sonnet` or `opus`) or a model's full name | `claude --model claude-sonnet-4-5-20250929` |

47| `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |

48| `--permission-mode` | Begin in a specified [permission mode](/en/iam#permission-modes) | `claude --permission-mode plan` |

53| `--session-id` | Use a specific session ID for the conversation (must be a valid UUID) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |

54| `--setting-sources` | Comma-separated list of setting sources to load (`user`, `project`, `local`) | `claude --setting-sources user,project` |

55| `--settings` | Path to a settings JSON file or a JSON string to load additional settings from | `claude --settings ./settings.json` |

56| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignoring all other MCP configurations | `claude --strict-mcp-config --mcp-config ./mcp.json` |

57| `--system-prompt` | Replace the entire system prompt with custom text (works in both interactive and print modes) | `claude --system-prompt "You are a Python expert"` |

58| `--system-prompt-file` | Load system prompt from a file, replacing the default prompt (print mode only) | `claude -p --system-prompt-file ./custom-prompt.txt "query"` |

59| `--tools` | Specify the list of available tools from the built-in set (use `""` to disable all, `"default"` for all, or tool names like `"Bash,Edit,Read"`) | `claude -p --tools "Bash,Edit,Read" "query"` |

60| `--verbose` | Enable verbose logging, shows full turn-by-turn output (helpful for debugging in both print and interactive modes) | `claude --verbose` |

61| `--version`, `-v` | Output the version number | `claude -v` |

44 62

45<Tip>63<Tip>

46 The `--output-format json` flag is particularly useful for scripting and64 The `--output-format json` flag is particularly useful for scripting and

52The `--agents` flag accepts a JSON object that defines one or more custom subagents. Each subagent requires a unique name (as the key) and a definition object with the following fields:70The `--agents` flag accepts a JSON object that defines one or more custom subagents. Each subagent requires a unique name (as the key) and a definition object with the following fields:

53 71

~~55| :------------ | :------- | :-------------------------------------------------------------------------------------------------------------- |~~73| :------------ | :------- | :--------------------------------------------------------------------------------------------------------------------- |

56| `description` | Yes | Natural language description of when the subagent should be invoked |74| `description` | Yes | Natural language description of when the subagent should be invoked |

57| `prompt` | Yes | The system prompt that guides the subagent's behavior |75| `prompt` | Yes | The system prompt that guides the subagent's behavior |

~~58| `tools` | No | Array of specific tools the subagent can use (e.g., `["Read", "Edit", "Bash"]`). If omitted, inherits all tools |~~76| `tools` | No | Array of specific tools the subagent can use (for example, `["Read", "Edit", "Bash"]`). If omitted, inherits all tools |

59| `model` | No | Model alias to use: `sonnet`, `opus`, or `haiku`. If omitted, uses the default subagent model |77| `model` | No | Model alias to use: `sonnet`, `opus`, or `haiku`. If omitted, uses the default subagent model |

60 78

61Example:79Example:

114 132

115For detailed information about print mode (`-p`) including output formats,133For detailed information about print mode (`-p`) including output formats,

116streaming, verbose logging, and programmatic usage, see the134streaming, verbose logging, and programmatic usage, see the

117[SDK documentation](/en/sdk).135[SDK documentation](https://docs.claude.com/en/docs/agent-sdk).

118 136

119## See also137## See also

120 138

139* [Chrome extension](/en/chrome) - Browser automation and web testing

121* [Interactive mode](/en/interactive-mode) - Shortcuts, input modes, and interactive features140* [Interactive mode](/en/interactive-mode) - Shortcuts, input modes, and interactive features

122* [Slash commands](/en/slash-commands) - Interactive session commands141* [Slash commands](/en/slash-commands) - Interactive session commands

123* [Quickstart guide](/en/quickstart) - Getting started with Claude Code142* [Quickstart guide](/en/quickstart) - Getting started with Claude Code

124* [Common workflows](/en/common-workflows) - Advanced workflows and patterns143* [Common workflows](/en/common-workflows) - Advanced workflows and patterns

125* [Settings](/en/settings) - Configuration options144* [Settings](/en/settings) - Configuration options

126* [SDK documentation](/en/sdk) - Programmatic usage and integrations145* [SDK documentation](https://docs.claude.com/en/docs/agent-sdk) - Programmatic usage and integrations

146

147

148---

149

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

common-workflows.md +119 −97

Details

173 </Step>173 </Step>

174 174

175 <Step title="Use subagents automatically">175 <Step title="Use subagents automatically">

176 Claude Code will automatically delegate appropriate tasks to specialized subagents:176 Claude Code automatically delegates appropriate tasks to specialized subagents:

177 177

178 ```178 ```

179 > review my recent code changes for security issues179 > review my recent code changes for security issues

201 201

202 Then select "Create New subagent" and follow the prompts to define:202 Then select "Create New subagent" and follow the prompts to define:

203 203

204 * Subagent type (e.g., `api-designer`, `performance-optimizer`)204 * A unique identifier that describes the subagent's purpose (for example, `code-reviewer`, `api-designer`).

205 * When to use it205 * When Claude should use this agent

206 * Which tools it can access206 * Which tools it can access

207 * Its specialized system prompt207 * A system prompt describing the agent's role and behavior

208 </Step>208 </Step>

209</Steps>209</Steps>

210 210

235 235

236You can switch into Plan Mode during a session using **Shift+Tab** to cycle through permission modes.236You can switch into Plan Mode during a session using **Shift+Tab** to cycle through permission modes.

237 237

238If you are in Normal Mode, **Shift+Tab** will first switch into Auto-Accept Mode, indicated by `⏵⏵ accept edits on` at the bottom of the terminal. A subsequent **Shift+Tab** will switch into Plan Mode, indicated by `⏸ plan mode on`.238If you are in Normal Mode, **Shift+Tab** first switches into Auto-Accept Mode, indicated by `⏵⏵ accept edits on` at the bottom of the terminal. A subsequent **Shift+Tab** will switch into Plan Mode, indicated by `⏸ plan mode on`.

239 239

240**Start a new session in Plan Mode**240**Start a new session in Plan Mode**

241 241

247 247

248**Run "headless" queries in Plan Mode**248**Run "headless" queries in Plan Mode**

249 249

250You can also run a query in Plan Mode directly with `-p` (i.e., in ["headless mode"](/en/sdk/sdk-headless)):250You can also run a query in Plan Mode directly with `-p` (that is, in ["headless mode"](/en/headless)):

251 251

252```bash theme={null}252```bash theme={null}

253claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"253claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

263> I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.263> I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.

264```264```

265 265

266Claude will analyze the current implementation and create a comprehensive plan. Refine with follow-ups:266Claude analyzes the current implementation and create a comprehensive plan. Refine with follow-ups:

267 267

268```268```

269> What about backward compatibility?269> What about backward compatibility?

315 </Step>315 </Step>

316</Steps>316</Steps>

317 317

318<Tip>318Claude can generate tests that follow your project's existing patterns and conventions. When asking for tests, be specific about what behavior you want to verify. Claude examines your existing test files to match the style, frameworks, and assertion patterns already in use.

319 Tips:

320 319

321 * Ask for tests that cover edge cases and error conditions320For comprehensive coverage, ask Claude to identify edge cases you might have missed. Claude can analyze your code paths and suggest tests for error conditions, boundary values, and unexpected inputs that are easy to overlook.

322 * Request both unit and integration tests when appropriate

323 * Have Claude explain the testing strategy

324</Tip>

325 321

326***322***

327 323

336 ```332 ```

337 </Step>333 </Step>

338 334

339 <Step title="Generate a PR with Claude">335 <Step title="Generate a pull request with Claude">

340 ```336 ```

341 > create a pr 337 > create a pr

342 ```338 ```

496 Tips:492 Tips:

497 493

498 * File paths can be relative or absolute494 * File paths can be relative or absolute

499 * @ file references add CLAUDE.md in the file's directory and parent directories to context495 * @ file references add `CLAUDE.md` in the file's directory and parent directories to context

500 * Directory references show file listings, not contents496 * Directory references show file listings, not contents

501 * You can reference multiple files in a single message (e.g., "@file1.js and @file2.js")497 * You can reference multiple files in a single message (for example, "@file1.js and @file2.js")

502</Tip>498</Tip>

503 499

504***500***

505 501

506## Use extended thinking502## Use extended thinking (thinking mode)

503

504[Extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) reserves a portion of the total output token budget for Claude to reason through complex problems step-by-step. This reasoning is visible in verbose mode, which you can toggle on with `Ctrl+O`.

507 505

508Suppose you're working on complex architectural decisions, challenging bugs, or planning multi-step implementations that require deep reasoning.506Extended thinking is particularly valuable for complex architectural decisions, challenging bugs, multi-step implementation planning, and evaluating tradeoffs between different approaches. It provides more space for exploring multiple solutions, analyzing edge cases, and self-correcting mistakes.

509 507

510<Note>508<Note>

511 [Extended thinking](/en/docs/build-with-claude/extended-thinking) is disabled by default in Claude Code. You can enable it on-demand by using `Tab` to toggle Thinking on, or by using prompts like "think" or "think hard". You can also enable it permanently by setting the [`MAX_THINKING_TOKENS` environment variable](/en/settings#environment-variables) in your settings.509 Sonnet 4.5 and Opus 4.5 have thinking enabled by default. All other models have thinking disabled by default. Use `/model` to view or switch your current model.

512</Note>510</Note>

513 511

514<Steps>512You can configure thinking mode for Claude Code in two ways:

515 <Step title="Provide context and ask Claude to think">

516 ```

517 > I need to implement a new authentication system using OAuth2 for our API. Think deeply about the best approach for implementing this in our codebase.

518 ```

519 513

520 Claude will gather relevant information from your codebase and514| Scope | How to enable | Details |

521 use extended thinking, which will be visible in the interface.515| --------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |

522 </Step>516| **Global default** | Use `/config` to toggle thinking mode on | Sets your default across all projects.<br />Saved as `alwaysThinkingEnabled` in `~/.claude/settings.json` |

517| **Environment variable override** | Set [`MAX_THINKING_TOKENS`](/en/settings#environment-variables) environment variable | When set, applies a custom token budget to all requests, overriding your thinking mode configuration. Example: `export MAX_THINKING_TOKENS=1024` |

523 518

524 <Step title="Refine the thinking with follow-up prompts">519### Per-request thinking with `ultrathink`

525 ```

526 > think about potential security vulnerabilities in this approach

527 ```

528 520

529 ```521You can include `ultrathink` as a keyword in your message to enable thinking for a single request:

530 > think hard about edge cases we should handle

531 ```

532 </Step>

533</Steps>

534 522

535<Tip>523```

536 Tips to get the most value out of extended thinking:524> ultrathink: design a caching layer for our API

525```

537 526

538 [Extended thinking](/en/docs/build-with-claude/extended-thinking) is most valuable for complex tasks such as:527Note that `ultrathink` both allocates the thinking budget AND semantically signals to Claude to reason more thoroughly, which may result in deeper thinking than necessary for your task.

539 528

540 * Planning complex architectural changes529The `ultrathink` keyword only works when `MAX_THINKING_TOKENS` is not set. When `MAX_THINKING_TOKENS` is configured, it takes priority and controls the thinking budget for all requests.

541 * Debugging intricate issues

542 * Creating implementation plans for new features

543 * Understanding complex codebases

544 * Evaluating tradeoffs between different approaches

545 530

546 Use `Tab` to toggle Thinking on and off during a session.531Other phrases like "think", "think hard", and "think more" are interpreted as regular prompt instructions and don't allocate thinking tokens.

547 532

548 The way you prompt for thinking results in varying levels of thinking depth:533To view Claude's thinking process, press `Ctrl+O` to toggle verbose mode and see the internal reasoning displayed as gray italic text.

549 534

550 * "think" triggers basic extended thinking535See the [token budget section below](#how-extended-thinking-token-budgets-work) for detailed budget information and cost implications.

551 * intensifying phrases such as "keep hard", "think more", "think a lot", or "think longer" triggers deeper thinking

552 536

553 For more extended thinking prompting tips, see [Extended thinking tips](/en/docs/build-with-claude/prompt-engineering/extended-thinking-tips).537### How extended thinking token budgets work

554</Tip>

555 538

556<Note>539Extended thinking uses a **token budget** that controls how much internal reasoning Claude can perform before responding.

557 Claude will display its thinking process as italic gray text above the540

558 response.541A larger thinking token budget provides:

559</Note>542

543* More space to explore multiple solution approaches step-by-step

544* Room to analyze edge cases and evaluate tradeoffs thoroughly

545* Ability to revise reasoning and self-correct mistakes

546

547Token budgets for thinking mode:

548

549* When thinking is **enabled** (via `/config` or `ultrathink`), Claude can use up to **31,999 tokens** from your output budget for internal reasoning

550* When thinking is **disabled**, Claude uses **0 tokens** for thinking

551

552**Custom token budgets:**

553

554* You can set a custom thinking token budget using the [`MAX_THINKING_TOKENS` environment variable](/en/settings#environment-variables)

555* This takes highest priority and overrides the default 31,999 token budget

556* See the [extended thinking documentation](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for valid token ranges

557

558<Warning>

559 You're charged for all thinking tokens used, even though Claude 4 models show summarized thinking

560</Warning>

560 561

561***562***

562 563

563## Resume previous conversations564## Resume previous conversations

564 565

565Suppose you've been working on a task with Claude Code and need to continue where you left off in a later session.566When starting Claude Code, you can resume a previous session:

567

568* `claude --continue` continues the most recent conversation in the current directory

569* `claude --resume` opens a conversation picker or resumes by name

566 570

567Claude Code provides two options for resuming previous conversations:571From inside an active session, use `/resume` to switch to a different conversation.

568 572

569* `--continue` to automatically continue the most recent conversation573Sessions are stored per project directory. The `/resume` picker shows sessions from the same git repository, including worktrees.

570* `--resume` to display a conversation picker574

575### Name your sessions

576

577Give sessions descriptive names to find them later. This is a best practice when working on multiple tasks or features.

571 578

572<Steps>579<Steps>

573 <Step title="Continue the most recent conversation">580 <Step title="Name the current session">

574 ```bash theme={null}581 Use `/rename` during a session to give it a memorable name:

575 claude --continue582

583 ```

584 > /rename auth-refactor

576 ```585 ```

577 586

578 This immediately resumes your most recent conversation without any prompts.587 You can also rename any session from the picker: run `/resume`, navigate to a session, and press `R`.

579 </Step>588 </Step>

580 589

581 <Step title="Continue in non-interactive mode">590 <Step title="Resume by name later">

591 From the command line:

592

582 ```bash theme={null}593 ```bash theme={null}

583 claude --continue --print "Continue with my task"594 claude --resume auth-refactor

584 ```595 ```

585 596

586 Use `--print` with `--continue` to resume the most recent conversation in non-interactive mode, perfect for scripts or automation.597 Or from inside an active session:

587 </Step>

588 598

589 <Step title="Show conversation picker">

590 ```bash theme={null}

591 claude --resume

592 ```599 ```

600 > /resume auth-refactor

601 ```

602 </Step>

603</Steps>

593 604

594 This displays an interactive conversation selector with a clean list view showing:605### Use the session picker

595 606

596 * Session summary (or initial prompt)607The `/resume` command (or `claude --resume` without arguments) opens an interactive session picker with these features:

597 * Metadata: time elapsed, message count, and git branch

598 608

599 Use arrow keys to navigate and press Enter to select a conversation. Press Esc to exit.609**Keyboard shortcuts in the picker:**

600 </Step>610

601</Steps>611| Shortcut | Action |

612| :-------- | :------------------------------------------------ |

613| `↑` / `↓` | Navigate between sessions |

614| `→` / `←` | Expand or collapse grouped sessions |

615| `Enter` | Select and resume the highlighted session |

616| `P` | Preview the session content |

617| `R` | Rename the highlighted session |

618| `/` | Search to filter sessions |

619| `A` | Toggle between current directory and all projects |

620| `B` | Filter to sessions from your current git branch |

621| `Esc` | Exit the picker or search mode |

622

623**Session organization:**

624

625The picker displays sessions with helpful metadata:

626

627* Session name or initial prompt

628* Time elapsed since last activity

629* Message count

630* Git branch (if applicable)

631

632Forked sessions (created with `/rewind` or `--fork-session`) are grouped together under their root session, making it easier to find related conversations.

602 633

603<Tip>634<Tip>

604 Tips:635 Tips:

605 636

606 * Conversation history is stored locally on your machine637 * **Name sessions early**: Use `/rename` when starting work on a distinct task—it's much easier to find "payment-integration" than "explain this function" later

607 * Use `--continue` for quick access to your most recent conversation638 * Use `--continue` for quick access to your most recent conversation

608 * Use `--resume` when you need to select a specific past conversation639 * Use `--resume session-name` when you know which session you need

609 * When resuming, you'll see the entire conversation history before continuing640 * Use `--resume` (without a name) when you need to browse and select

641 * For scripts, use `claude --continue --print "prompt"` to resume in non-interactive mode

642 * Press `P` in the picker to preview a session before resuming it

610 * The resumed conversation starts with the same model and configuration as the original643 * The resumed conversation starts with the same model and configuration as the original

611 644

612 How it works:645 How it works:

615 2. **Message Deserialization**: When resuming, the entire message history is restored to maintain context648 2. **Message Deserialization**: When resuming, the entire message history is restored to maintain context

616 3. **Tool State**: Tool usage and results from the previous conversation are preserved649 3. **Tool State**: Tool usage and results from the previous conversation are preserved

617 4. **Context Restoration**: The conversation resumes with all previous context intact650 4. **Context Restoration**: The conversation resumes with all previous context intact

~~618~~

619 Examples:

~~620~~

621 ```bash theme={null}

622 # Continue most recent conversation

623 claude --continue

~~624~~

625 # Continue most recent conversation with a specific prompt

626 claude --continue --print "Show me our progress"

~~627~~

628 # Show conversation picker

629 claude --resume

~~630~~

631 # Continue most recent conversation in non-interactive mode

632 claude --continue --print "Run the tests again"

633 ```

634</Tip>651</Tip>

635 652

636***653***

822<Tip>839<Tip>

823 Tips:840 Tips:

824 841

825 * Command names are derived from the filename (e.g., `optimize.md` becomes `/optimize`)842 * Command names are derived from the filename (for example, `optimize.md` becomes `/optimize`)

826 * You can organize commands in subdirectories (e.g., `.claude/commands/frontend/component.md` creates `/component` with "(project:frontend)" shown in the description)843 * You can organize commands in subdirectories (for example, `.claude/commands/frontend/component.md` creates `/component` with "(project:frontend)" shown in the description)

827 * Project commands are available to everyone who clones the repository844 * Project commands are available to everyone who clones the repository

828 * The Markdown file content becomes the prompt sent to Claude when the command is invoked845 * The Markdown file content becomes the prompt sent to Claude when the command is invoked

829</Tip>846</Tip>

850 > /fix-issue 123 867 > /fix-issue 123

851 ```868 ```

852 869

853 This will replace \$ARGUMENTS with "123" in the prompt.870 This replaces \$ARGUMENTS with "123" in the prompt.

854 </Step>871 </Step>

855</Steps>872</Steps>

856 873

947<Card title="Claude Code reference implementation" icon="code" href="https://github.com/anthropics/claude-code/tree/main/.devcontainer">964<Card title="Claude Code reference implementation" icon="code" href="https://github.com/anthropics/claude-code/tree/main/.devcontainer">

948 Clone our development container reference implementation.965 Clone our development container reference implementation.

949</Card>966</Card>

967

968

969---

970

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

costs.md +6 −1

Details

35 35

36When using Claude API, you can limit the total Claude Code workspace spend. To configure, [follow these instructions](https://support.claude.com/en/articles/9796807-creating-and-managing-workspaces). Admins can view cost and usage reporting by [following these instructions](https://support.claude.com/en/articles/9534590-cost-and-usage-reporting-in-console).36When using Claude API, you can limit the total Claude Code workspace spend. To configure, [follow these instructions](https://support.claude.com/en/articles/9796807-creating-and-managing-workspaces). Admins can view cost and usage reporting by [following these instructions](https://support.claude.com/en/articles/9534590-cost-and-usage-reporting-in-console).

37 37

38On Bedrock and Vertex, Claude Code does not send metrics from your cloud. In order to get cost metrics, several large enterprises reported using [LiteLLM](/en/bedrock-vertex-proxies#litellm), which is an open-source tool that helps companies [track spend by key](https://docs.litellm.ai/docs/proxy/virtual_keys#tracking-spend). This project is unaffiliated with Anthropic and we have not audited its security.38On Bedrock and Vertex, Claude Code does not send metrics from your cloud. In order to get cost metrics, several large enterprises reported using [LiteLLM](/en/third-party-integrations#litellm), which is an open-source tool that helps companies [track spend by key](https://docs.litellm.ai/docs/proxy/virtual_keys#tracking-spend). This project is unaffiliated with Anthropic and we have not audited its security.

39 39

40### Rate limit recommendations40### Rate limit recommendations

41 41

129 For team deployments, we recommend starting with a small pilot group to129 For team deployments, we recommend starting with a small pilot group to

130 establish usage patterns before wider rollout.130 establish usage patterns before wider rollout.

131</Note>131</Note>

132

133

134---

135

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

data-usage.md +10 −3

Details

17 If you're a new user, you can pick your setting for model training during the signup process.17 If you're a new user, you can pick your setting for model training during the signup process.

18 You can change your selection at any time in your Privacy Settings.18 You can change your selection at any time in your Privacy Settings.

19 19

20**Commercial users**: (Team and Enterprise plans, API, 3rd-party platforms, and Claude Gov) maintain existing policies: Anthropic does not train generative models using code or prompts sent to Claude Code under commercial terms, unless the customer has chosen to provide their data to us for model improvement (e.g. [Developer Partner Program](https://support.claude.com/en/articles/11174108-about-the-development-partner-program)).20**Commercial users**: (Team and Enterprise plans, API, 3rd-party platforms, and Claude Gov) maintain existing policies: Anthropic does not train generative models using code or prompts sent to Claude Code under commercial terms, unless the customer has chosen to provide their data to us for model improvement (for example, the [Developer Partner Program](https://support.claude.com/en/articles/11174108-about-the-development-partner-program)).

21 21

22### Development Partner Program22### Development Partner Program

23 23

39 39

40* Users who allow data use for model improvement: 5-year retention period to support model development and safety improvements40* Users who allow data use for model improvement: 5-year retention period to support model development and safety improvements

41* Users who don't allow data use for model improvement: 30-day retention period41* Users who don't allow data use for model improvement: 30-day retention period

~~42* Privacy settings can be changed at any time at [claude.ai/settings/data-privacy-controls](claude.ai/settings/data-privacy-controls).~~42* Privacy settings can be changed at any time at [claude.ai/settings/data-privacy-controls](https://claude.ai/settings/data-privacy-controls).

43 43

44**Commercial users (Team, Enterprise, and API)**:44**Commercial users (Team, Enterprise, and API)**:

45 45

53 53

54## Data flow and dependencies54## Data flow and dependencies

55 55

56<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=4672f138596e864633b4b7c7ae4ae812" alt="Claude Code data flow diagram" data-og-width="1597" width="1597" data-og-height="1285" height="1285" data-path="images/claude-code-data-flow.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?w=280&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=5d9bdaf7ea50fc38dc01bbde7b952835 280w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?w=560&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=525736e5860ac9f262de4b40c9c68a0e 560w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?w=840&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=5262f9d1a1d0cffb0d5944e49b2d72be 840w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?w=1100&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=ec74e6b2f87b667f6d0e2278c20944de 1100w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?w=1650&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=05f11b1d061b6ddbb69969d4e535547a 1650w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?w=2500&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=9b9cce0fb5989bd1d27f143825be73ff 2500w" />56The diagram below shows how Claude Code connects to external services during installation and normal operation. Solid lines indicate required connections, while dashed lines represent optional or user-initiated data flows.

58<img src="https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=9e77f476347e7c9983f6e211d27cf6a9" alt="Diagram showing Claude Code's external connections: install/update connects to NPM, and user requests connect to Anthropic services including Console auth, public-api, and optionally Statsig, Sentry, and bug reporting" data-og-width="720" width="720" data-og-height="520" height="520" data-path="images/claude-code-data-flow.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=280&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=94c033b9b6db3d10b9e2d7c6d681d9dc 280w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=560&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=430aaaf77c28c501d5753ffa456ee227 560w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=840&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=63c3c3f160b522220a8291fe2f93f970 840w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=1100&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=a7f6e838482f4a1a0a0b4683439369ea 1100w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=1650&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=5fbf749c2f94babb3ef72edfb7aba1e9 1650w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=2500&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=7a1babbdccc4986957698d9c5c30c4a8 2500w" />

57 59

58Claude Code is installed from [NPM](https://www.npmjs.com/package/@anthropic-ai/claude-code). Claude Code runs locally. In order to interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs. The data is encrypted in transit via TLS and is not encrypted at rest. Claude Code is compatible with most popular VPNs and LLM proxies.60Claude Code is installed from [NPM](https://www.npmjs.com/package/@anthropic-ai/claude-code). Claude Code runs locally. In order to interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs. The data is encrypted in transit via TLS and is not encrypted at rest. Claude Code is compatible with most popular VPNs and LLM proxies.

59 61

95 97

96All environment variables can be checked into `settings.json` ([read more](/en/settings)).98All environment variables can be checked into `settings.json` ([read more](/en/settings)).

100

101---

102

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

desktop.md +107 −0 added

Details

1# Claude Code on desktop

3> Run Claude Code tasks locally or on secure cloud infrastructure with the Claude desktop app

5<img src="https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=c4e9dc9737b437d36ab253b75a1cc595" alt="Claude Code on desktop interface" data-og-width="4132" width="4132" data-og-height="2620" height="2620" data-path="images/desktop-interface.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?w=280&fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=b1a8421a544c3e8c78679fa1a7b56190 280w, https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?w=560&fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=79cf4ea0923098cc429198678ea50903 560w, https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?w=840&fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=14bcbcd569d179770fe656686ffbf6bf 840w, https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?w=1100&fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=b873274db1e9ff8585ba545032aa24a5 1100w, https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?w=1650&fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=25553dced783c3a8c2a1134a53295f7e 1650w, https://mintcdn.com/claude-code/zEGbGSbinVtT3BLw/images/desktop-interface.png?w=2500&fit=max&auto=format&n=zEGbGSbinVtT3BLw&q=85&s=9ad49e6468c2f87b1895093deeea7bb2 2500w" />

7## Claude Code on desktop (Preview)

9The Claude desktop app provides a native interface for running multiple Claude Code sessions on your local machine and seamless integration with Claude Code on the web.

11## Features

13Claude Code on desktop provides:

15* **Parallel local sessions with `git` worktrees**: Run multiple Claude Code sessions simultaneously in the same repository, each with its own isolated `git` worktree

16* **Include files listed in your `.gitignore` in your worktrees**: Automatically copy files in your `.gitignore`, like `.env`, to new worktrees using `.worktreeinclude`

17* **Launch Claude Code on the web**: Kick off secure cloud sessions directly from the desktop app

19## Installation

21Download and install the Claude Desktop app from [claude.ai/download](https://claude.ai/download)

23<Note>

24 Local sessions are not available on Windows arm64 architectures.

25</Note>

27## Using Git worktrees

29Claude Code on desktop enables running multiple Claude Code sessions in the same repository using Git worktrees. Each session gets its own isolated worktree, allowing Claude to work on different tasks without conflicts. The default location for worktrees is `~/.claude-worktrees` but this can be configured in your settings on the Claude desktop app.

31<Note>

32 If you start a local session in a folder that does not have Git initialized, the desktop app will not create a new worktree.

33</Note>

35### Copying files ignored with `.gitignore`

37When Claude Code creates a worktree, files ignored via `.gitignore` aren't automatically available. Including a `.worktreeinclude` file solves this by specifying which ignored files should be copied to new worktrees.

39Create a `.worktreeinclude` file in your repository root:

41```

42.env

43.env.local

44.env.*

45**/.claude/settings.local.json

46```

48The file uses `.gitignore`-style patterns. When a worktree is created, files matching these patterns that are also in your `.gitignore` will be copied from your main repository to the worktree.

50<Tip>

51 Only files that are both matched by `.worktreeinclude` AND listed in `.gitignore` are copied. This prevents accidentally duplicating tracked files.

52</Tip>

54### Launch Claude Code on the web

56From the desktop app, you can kick off Claude Code sessions that run on Anthropic's secure cloud infrastructure. This is useful for:

58To start a web session from desktop, select a remote environment when creating a new session.

60For more details, see [Claude Code on the web](/en/claude-code-on-the-web).

62## Bundled Claude Code version

64Claude Code on desktop includes a bundled, stable version of Claude Code to ensure a consistent experience for all desktop users. The bundled version is required and downloaded on first launch even if a version of Claude Code exists on the computer. Desktop automatically manages version updates and cleans up old versions.

66<Note>

67 The bundled Claude Code version in Desktop may differ from the latest CLI version. Desktop prioritizes stability while the CLI may have newer features.

68</Note>

70## Environment configuration

72For local environments, Claude Code on desktop automatically extracts your `$PATH` environment variable from your shell configuration. This allows local sessions to access development tools like `yarn`, `npm`, `node`, and other commands available in your terminal without additional setup.

74### Custom environment variables

76Select "Local" environment, then to the right, select the settings button. This will open a dialog where you can update local environment variables. This is useful for setting project-specific variables or API keys that your development workflows require. Environment variable values are masked in the UI for security reasons.

78<Note>

79 Environment variables must be specified as key-value pairs, in [`.env` format](https://www.dotenv.org/). For example:

81 ```

82 API_KEY=your_api_key

83 DEBUG=true

85 # Multiline values - wrap in quotes

86 CERT="-----BEGIN CERT-----

87 MIIE...

88 -----END CERT-----"

89 ```

90</Note>

92## Enterprise configuration

94Organizations can disable local Claude Code use in the desktop application with the `isClaudeCodeForDesktopEnabled` [enterprise policy option](https://support.claude.com/en/articles/12622667-enterprise-configuration#h_003283c7cb). Additionally, Claude Code on the web can be disabled in your [admin settings](https://claude.ai/admin-settings/claude-code).

96## Related resources

98* [Claude Code on the web](/en/claude-code-on-the-web)

99* [Claude Desktop support articles](https://support.claude.com/en/collections/16163169-claude-desktop)

100* [Enterprise Configuration](https://support.claude.com/en/articles/12622667-enterprise-configuration)

101* [Common workflows](/en/common-workflows)

102* [Settings reference](/en/settings)

103

104

105---

106

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

devcontainer.md +6 −1

Details

8 8

9<Warning>9<Warning>

10 While the devcontainer provides substantial protections, no system is completely immune to all attacks.10 While the devcontainer provides substantial protections, no system is completely immune to all attacks.

~~11 When executed with `--dangerously-skip-permissions`, devcontainers do not prevent a malicious project from exfiltrating anything accessible in the devcontainer including Claude Code credentials.~~11 When executed with `--dangerously-skip-permissions`, devcontainers don't prevent a malicious project from exfiltrating anything accessible in the devcontainer including Claude Code credentials.

12 We recommend only using devcontainers when developing with trusted repositories.12 We recommend only using devcontainers when developing with trusted repositories.

13 Always maintain good security practices and monitor Claude's activities.13 Always maintain good security practices and monitor Claude's activities.

14</Warning>14</Warning>

75* [VS Code devcontainers documentation](https://code.visualstudio.com/docs/devcontainers/containers)75* [VS Code devcontainers documentation](https://code.visualstudio.com/docs/devcontainers/containers)

76* [Claude Code security best practices](/en/security)76* [Claude Code security best practices](/en/security)

77* [Enterprise network configuration](/en/network-config)77* [Enterprise network configuration](/en/network-config)

80---

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

discover-plugins.md +363 −0 added

Details

1# Discover and install prebuilt plugins through marketplaces

3> Find and install plugins from marketplaces to extend Claude Code with new commands, agents, and capabilities.

5Plugins extend Claude Code with custom commands, agents, hooks, and MCP servers. Plugin marketplaces are catalogs that help you discover and install these extensions without building them yourself.

7Looking to create and distribute your own marketplace? See [Create and distribute a plugin marketplace](/en/plugin-marketplaces).

9## How marketplaces work

11A marketplace is a catalog of plugins that someone else has created and shared. Using a marketplace is a two-step process:

13<Steps>

14 <Step title="Add the marketplace">

15 This registers the catalog with Claude Code so you can browse what's available. No plugins are installed yet.

16 </Step>

18 <Step title="Install individual plugins">

19 Browse the catalog and install the plugins you want.

20 </Step>

21</Steps>

23Think of it like adding an app store: adding the store gives you access to browse its collection, but you still choose which apps to download individually.

25## Official Anthropic marketplace

27The official Anthropic marketplace (`claude-plugins-official`) is automatically available when you start Claude Code. Run `/plugin` and go to the **Discover** tab to browse what's available.

29To install a plugin from the official marketplace:

31```shell theme={null}

32/plugin install plugin-name@claude-plugins-official

33```

35<Note>

36 The official marketplace is maintained by Anthropic. To distribute your own plugins, [create your own marketplace](/en/plugin-marketplaces) and share it with users.

37</Note>

39The official marketplace includes several categories of plugins:

41### Code intelligence

43Code intelligence plugins help Claude understand your codebase more deeply. With these plugins installed, Claude can jump to definitions, find references, and see type errors immediately after edits. These plugins use the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP), the same technology that powers VS Code's code intelligence.

45These plugins require the language server binary to be installed on your system. If you already have a language server installed, Claude may prompt you to install the corresponding plugin when you open a project.

47| Language | Plugin | Binary required |

48| :--------- | :------------------ | :--------------------------- |

49| C/C++ | `clangd-lsp` | `clangd` |

50| C# | `csharp-lsp` | `csharp-ls` |

51| Go | `gopls-lsp` | `gopls` |

52| Java | `jdtls-lsp` | `jdtls` |

53| Lua | `lua-lsp` | `lua-language-server` |

54| PHP | `php-lsp` | `intelephense` |

55| Python | `pyright-lsp` | `pyright-langserver` |

56| Rust | `rust-analyzer-lsp` | `rust-analyzer` |

57| Swift | `swift-lsp` | `sourcekit-lsp` |

58| TypeScript | `typescript-lsp` | `typescript-language-server` |

60You can also [create your own LSP plugin](/en/plugins-reference#lsp-servers) for other languages.

62<Note>

63 If you see `Executable not found in $PATH` in the `/plugin` Errors tab after installing a plugin, install the required binary from the table above.

64</Note>

66### External integrations

68These plugins bundle pre-configured [MCP servers](/en/mcp) so you can connect Claude to external services without manual setup:

70* **Source control**: `github`, `gitlab`

71* **Project management**: `atlassian` (Jira/Confluence), `asana`, `linear`, `notion`

72* **Design**: `figma`

73* **Infrastructure**: `vercel`, `firebase`, `supabase`

74* **Communication**: `slack`

75* **Monitoring**: `sentry`

77### Development workflows

79Plugins that add commands and agents for common development tasks:

81* **commit-commands**: Git commit workflows including commit, push, and PR creation

82* **pr-review-toolkit**: Specialized agents for reviewing pull requests

83* **agent-sdk-dev**: Tools for building with the Claude Agent SDK

84* **plugin-dev**: Toolkit for creating your own plugins

86### Output styles

88Customize how Claude responds:

90* **explanatory-output-style**: Educational insights about implementation choices

91* **learning-output-style**: Interactive learning mode for skill building

93## Try it: add the demo marketplace

95Anthropic also maintains a [demo plugins marketplace](https://github.com/anthropics/claude-code/tree/main/plugins) (`claude-code-plugins`) with example plugins that show what's possible with the plugin system. Unlike the official marketplace, you need to add this one manually.

97<Steps>

98 <Step title="Add the marketplace">

99 From within Claude Code, run the `plugin marketplace add` command for the `anthropics/claude-code` marketplace:

100

101 ```shell theme={null}

102 /plugin marketplace add anthropics/claude-code

103 ```

104

105 This downloads the marketplace catalog and makes its plugins available to you.

106 </Step>

107

108 <Step title="Browse available plugins">

109 Run `/plugin` to open the plugin manager. This opens a tabbed interface with four tabs you can cycle through using **Tab** (or **Shift+Tab** to go backward):

110

111 * **Discover**: browse available plugins from all your marketplaces

112 * **Installed**: view and manage your installed plugins

113 * **Marketplaces**: add, remove, or update your added marketplaces

114 * **Errors**: view any plugin loading errors

115

116 Go to the **Discover** tab to see plugins from the marketplace you just added.

117 </Step>

118

119 <Step title="Install a plugin">

120 Select a plugin to view its details, then choose an installation scope:

121

122 * **User scope**: install for yourself across all projects

123 * **Project scope**: install for all collaborators on this repository

124 * **Local scope**: install for yourself in this repository only

125

126 For example, select **commit-commands** (a plugin that adds git workflow commands) and install it to your user scope.

127

128 You can also install directly from the command line:

129

130 ```shell theme={null}

131 /plugin install commit-commands@anthropics-claude-code

132 ```

133

134 See [Configuration scopes](/en/settings#configuration-scopes) to learn more about scopes.

135 </Step>

136

137 <Step title="Use your new plugin">

138 After installing, the plugin's commands are immediately available. Plugin commands are namespaced by the plugin name, so **commit-commands** provides commands like `/commit-commands:commit`.

139

140 Try it out by making a change to a file and running:

141

142 ```shell theme={null}

143 /commit-commands:commit

144 ```

145

146 This stages your changes, generates a commit message, and creates the commit.

147

148 Each plugin works differently. Check the plugin's description in the **Discover** tab or its homepage to learn what commands and capabilities it provides.

149 </Step>

150</Steps>

151

152The rest of this guide covers all the ways you can add marketplaces, install plugins, and manage your configuration.

153

154## Add marketplaces

155

156Use the `/plugin marketplace add` command to add marketplaces from different sources.

157

158<Tip>

159 **Shortcuts**: You can use `/plugin market` instead of `/plugin marketplace`, and `rm` instead of `remove`.

160</Tip>

161

162* **GitHub repositories**: `owner/repo` format (for example, `anthropics/claude-code`)

163* **Git URLs**: any git repository URL (GitLab, Bitbucket, self-hosted)

164* **Local paths**: directories or direct paths to `marketplace.json` files

165* **Remote URLs**: direct URLs to hosted `marketplace.json` files

166

167### Add from GitHub

168

169Add a GitHub repository that contains a `.claude-plugin/marketplace.json` file using the `owner/repo` format—where `owner` is the GitHub username or organization and `repo` is the repository name.

170

171For example, `anthropics/claude-code` refers to the `claude-code` repository owned by `anthropics`:

172

173```shell theme={null}

174/plugin marketplace add anthropics/claude-code

175```

176

177### Add from other Git hosts

178

179Add any git repository by providing the full URL. This works with any Git host, including GitLab, Bitbucket, and self-hosted servers:

180

181Using HTTPS:

182

183```shell theme={null}

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

185```

186

187Using SSH:

188

189```shell theme={null}

190/plugin marketplace add git@gitlab.com:company/plugins.git

191```

192

193To add a specific branch or tag, append `#` followed by the ref:

194

195```shell theme={null}

196/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0

197```

198

199### Add from local paths

200

201Add a local directory that contains a `.claude-plugin/marketplace.json` file:

202

203```shell theme={null}

204/plugin marketplace add ./my-marketplace

205```

206

207You can also add a direct path to a `marketplace.json` file:

208

209```shell theme={null}

210/plugin marketplace add ./path/to/marketplace.json

211```

212

213Or add a remote `marketplace.json` file via URL:

214

215```shell theme={null}

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

217```

218

219## Install plugins

220

221Once you've added marketplaces, you can install plugins directly (installs to user scope by default):

222

223```shell theme={null}

224/plugin install plugin-name@marketplace-name

225```

226

227To choose a different [installation scope](/en/settings#configuration-scopes), use the interactive UI: run `/plugin`, go to the **Discover** tab, and press **Enter** on a plugin. You'll see options for:

228

229* **User scope** (default): install for yourself across all projects

230* **Project scope**: install for all collaborators on this repository (adds to `.claude/settings.json`)

231* **Local scope**: install for yourself in this repository only (not shared with collaborators)

232

233You may also see plugins with **managed** scope—these are installed by enterprise administrators via [managed settings](/en/settings#enterprise-managed-policy-settings) and cannot be modified.

234

235Run `/plugin` and go to the **Installed** tab to see your plugins grouped by scope.

236

237<Warning>

238 Make sure you trust a plugin before installing it. Anthropic does not control what MCP servers, files, or other software are included in plugins and cannot verify that they work as intended. Check each plugin's homepage for more information.

239</Warning>

240

241## Manage installed plugins

242

243Run `/plugin` and go to the **Installed** tab to view, enable, disable, or uninstall your plugins.

244

245You can also manage plugins with direct commands.

246

247Disable a plugin without uninstalling:

248

249```shell theme={null}

250/plugin disable plugin-name@marketplace-name

251```

252

253Re-enable a disabled plugin:

254

255```shell theme={null}

256/plugin enable plugin-name@marketplace-name

257```

258

259Completely remove a plugin:

260

261```shell theme={null}

262/plugin uninstall plugin-name@marketplace-name

263```

264

265The `--scope` option lets you target a specific scope with CLI commands:

266

267```shell theme={null}

268claude plugin install formatter@your-org --scope project

269claude plugin uninstall formatter@your-org --scope project

270```

271

272## Manage marketplaces

273

274You can manage marketplaces through the interactive `/plugin` interface or with CLI commands.

275

276### Use the interactive interface

277

278Run `/plugin` and go to the **Marketplaces** tab to:

279

280* View all your added marketplaces with their sources and status

281* Add new marketplaces

282* Update marketplace listings to fetch the latest plugins

283* Remove marketplaces you no longer need

284

285### Use CLI commands

286

287You can also manage marketplaces with direct commands.

288

289List all configured marketplaces:

290

291```shell theme={null}

292/plugin marketplace list

293```

294

295Refresh plugin listings from a marketplace:

296

297```shell theme={null}

298/plugin marketplace update marketplace-name

299```

300

301Remove a marketplace:

302

303```shell theme={null}

304/plugin marketplace remove marketplace-name

305```

306

307<Warning>

308 Removing a marketplace will uninstall any plugins you installed from it.

309</Warning>

310

311### Configure auto-updates

312

313Claude Code can automatically update marketplaces and their installed plugins at startup. When auto-update is enabled for a marketplace, Claude Code refreshes the marketplace data and updates installed plugins to their latest versions. If any plugins were updated, you'll see a notification suggesting you restart Claude Code.

314

315Toggle auto-update for individual marketplaces through the UI:

316

3171. Run `/plugin` to open the plugin manager

3182. Select **Marketplaces**

3193. Choose a marketplace from the list

3204. Select **Enable auto-update** or **Disable auto-update**

321

322Official Anthropic marketplaces have auto-update enabled by default. Third-party and local development marketplaces have auto-update disabled by default.

323

324To disable all automatic updates entirely for both Claude Code and all plugins, set the `DISABLE_AUTOUPDATER` environment variable. See [Auto updates](/en/setup#auto-updates) for details.

325

326## Configure team marketplaces

327

328Team admins can set up automatic marketplace installation for projects by adding marketplace configuration to `.claude/settings.json`. When team members trust the repository folder, Claude Code prompts them to install these marketplaces and plugins.

329

330For full configuration options including `extraKnownMarketplaces` and `enabledPlugins`, see [Plugin settings](/en/settings#plugin-settings).

331

332## Troubleshooting

333

334### /plugin command not recognized

335

336If you see "unknown command" or the `/plugin` command doesn't appear:

337

3381. **Check your version**: Run `claude --version`. Plugins require version 1.0.33 or later.

3392. **Update Claude Code**:

340 * **Homebrew**: `brew upgrade claude-code`

341 * **npm**: `npm update -g @anthropic-ai/claude-code`

342 * **Native installer**: Re-run the install command from [Setup](/en/setup)

3433. **Restart Claude Code**: After updating, restart your terminal and run `claude` again.

344

345### Common issues

346

347* **Marketplace not loading**: Verify the URL is accessible and that `.claude-plugin/marketplace.json` exists at the path

348* **Plugin installation failures**: Check that plugin source URLs are accessible and repositories are public (or you have access)

349* **Files not found after installation**: Plugins are copied to a cache, so paths referencing files outside the plugin directory won't work

350* **Plugin Skills not appearing**: Clear the cache with `rm -rf ~/.claude/plugins/cache`, restart Claude Code, and reinstall the plugin. See [Plugin Skills not appearing](/en/skills#plugin-skills-not-appearing-after-installation) for details.

351

352For detailed troubleshooting with solutions, see [Troubleshooting](/en/plugin-marketplaces#troubleshooting) in the marketplace guide. For debugging tools, see [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools).

353

354## Next steps

355

356* **Build your own plugins**: See [Plugins](/en/plugins) to create custom commands, agents, and hooks

357* **Create a marketplace**: See [Create a plugin marketplace](/en/plugin-marketplaces) to distribute plugins to your team or community

358* **Technical reference**: See [Plugins reference](/en/plugins-reference) for complete specifications

359

360

361---

362

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

github-actions.md +16 −8

Details

6 6

7<Note>7<Note>

8 Claude Code GitHub Actions is built on top of the [Claude Code8 Claude Code GitHub Actions is built on top of the [Claude Code

~~9 SDK](/en/sdk), which enables programmatic integration of~~9 SDK](https://docs.claude.com/en/docs/agent-sdk), which enables programmatic integration of

10 Claude Code into your applications. You can use the SDK to build custom10 Claude Code into your applications. You can use the SDK to build custom

11 automation workflows beyond GitHub Actions.11 automation workflows beyond GitHub Actions.

12</Note>12</Note>

13 13

14<Info>

15 **Claude Opus 4.5 is now available.** Claude Code GitHub Actions default to Sonnet. To use Opus 4.5, configure the [model parameter](#breaking-changes-reference) to use `claude-opus-4-5-20251101`.

16</Info>

14## Why use Claude Code GitHub Actions?18## Why use Claude Code GitHub Actions?

15 19

16* **Instant PR creation**: Describe what you need, and Claude creates a complete PR with all necessary changes20* **Instant PR creation**: Describe what you need, and Claude creates a complete PR with all necessary changes

633. **Copy the workflow file** from [examples/claude.yml](https://github.com/anthropics/claude-code-action/blob/main/examples/claude.yml) into your repository's `.github/workflows/`673. **Copy the workflow file** from [examples/claude.yml](https://github.com/anthropics/claude-code-action/blob/main/examples/claude.yml) into your repository's `.github/workflows/`

64 68

65<Tip>69<Tip>

~~66 After completing either the quickstart or manual setup, test the action by~~70 After completing either the quickstart or manual setup, test the action by tagging `@claude` in an issue or PR comment.

~~67 tagging `@claude` in an issue or PR comment!~~

68</Tip>71</Tip>

69 72

70## Upgrading from Beta73## Upgrading from Beta

186 with:189 with:

187 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}190 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

188 prompt: "Generate a summary of yesterday's commits and open issues"191 prompt: "Generate a summary of yesterday's commits and open issues"

189 claude_args: "--model claude-opus-4-1-20250805"192 claude_args: "--model claude-opus-4-5-20251101"

190```193```

191 194

192### Common use cases195### Common use cases

209 212

210### Security considerations213### Security considerations

211 214

212<Warning>Never commit API keys directly to your repository!</Warning>215<Warning>Never commit API keys directly to your repository.</Warning>

213 216

214For comprehensive security guidance including permissions, authentication, and best practices, see the [Claude Code Action security documentation](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md).217For comprehensive security guidance including permissions, authentication, and best practices, see the [Claude Code Action security documentation](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md).

215 218

220* Limit action permissions to only what's necessary223* Limit action permissions to only what's necessary

221* Review Claude's suggestions before merging224* Review Claude's suggestions before merging

222 225

223Always use GitHub Secrets (e.g., `${{ secrets.ANTHROPIC_API_KEY }}`) rather than hardcoding API keys directly in your workflow files.226Always use GitHub Secrets (for example, `${{ secrets.ANTHROPIC_API_KEY }}`) rather than hardcoding API keys directly in your workflow files.

224 227

225### Optimizing performance228### Optimizing performance

226 229

633\*Prompt is optional - when omitted for issue/PR comments, Claude responds to trigger phrase\636\*Prompt is optional - when omitted for issue/PR comments, Claude responds to trigger phrase\

634\*\*Required for direct Claude API, not for Bedrock/Vertex637\*\*Required for direct Claude API, not for Bedrock/Vertex

635 638

636#### Using claude\_args639#### Pass CLI arguments

637 640

638The `claude_args` parameter accepts any Claude Code CLI arguments:641The `claude_args` parameter accepts any Claude Code CLI arguments:

639 642

644Common arguments:647Common arguments:

645 648

646* `--max-turns`: Maximum conversation turns (default: 10)649* `--max-turns`: Maximum conversation turns (default: 10)

647* `--model`: Model to use (e.g., `claude-sonnet-4-5-20250929`)650* `--model`: Model to use (for example, `claude-sonnet-4-5-20250929`)

648* `--mcp-config`: Path to MCP configuration651* `--mcp-config`: Path to MCP configuration

649* `--allowed-tools`: Comma-separated list of allowed tools652* `--allowed-tools`: Comma-separated list of allowed tools

650* `--debug`: Enable debug output653* `--debug`: Enable debug output

6672. **Custom prompts**: Use the `prompt` parameter in the workflow file to provide workflow-specific instructions. This allows you to customize Claude's behavior for different workflows or tasks.6702. **Custom prompts**: Use the `prompt` parameter in the workflow file to provide workflow-specific instructions. This allows you to customize Claude's behavior for different workflows or tasks.

668 671

669Claude will follow these guidelines when creating PRs and responding to requests.672Claude will follow these guidelines when creating PRs and responding to requests.

673

674

675---

676

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

gitlab-ci-cd.md +8 −3

Details

9</Info>9</Info>

10 10

11<Note>11<Note>

~~12 This integration is built on top of the [Claude Code CLI and SDK](/en/sdk), enabling programmatic use of Claude in your CI/CD jobs and custom automation workflows.~~12 This integration is built on top of the [Claude Code CLI and SDK](https://docs.claude.com/en/docs/agent-sdk), enabling programmatic use of Claude in your CI/CD jobs and custom automation workflows.

13</Note>13</Note>

14 14

15## Why use Claude Code with GitLab?15## Why use Claude Code with GitLab?

379 379

380### Security considerations380### Security considerations

381 381

382Never commit API keys or cloud credentials to your repository! Always use GitLab CI/CD variables:382**Never commit API keys or cloud credentials to your repository**. Always use GitLab CI/CD variables:

383 383

384* Add `ANTHROPIC_API_KEY` as a masked variable (and protect it if needed)384* Add `ANTHROPIC_API_KEY` as a masked variable (and protect it if needed)

385* Use provider-specific OIDC where possible (no long-lived keys)385* Use provider-specific OIDC where possible (no long-lived keys)

404* **API costs**:404* **API costs**:

405 * Each Claude interaction consumes tokens based on prompt and response size405 * Each Claude interaction consumes tokens based on prompt and response size

406 * Token usage varies by task complexity and codebase size406 * Token usage varies by task complexity and codebase size

407 * See [Anthropic pricing](/en/docs/about-claude/pricing) for details407 * See [Anthropic pricing](https://docs.claude.com/en/docs/about-claude/pricing) for details

408 408

409* **Cost optimization tips**:409* **Cost optimization tips**:

410 * Use specific `@claude` commands to reduce unnecessary turns410 * Use specific `@claude` commands to reduce unnecessary turns

460 460

4611. **CLAUDE.md**: Define coding standards, security requirements, and project conventions. Claude reads this during runs and follows your rules.4611. **CLAUDE.md**: Define coding standards, security requirements, and project conventions. Claude reads this during runs and follows your rules.

4622. **Custom prompts**: Pass task-specific instructions via `prompt`/`prompt_file` in the job. Use different prompts for different jobs (for example, review, implement, refactor).4622. **Custom prompts**: Pass task-specific instructions via `prompt`/`prompt_file` in the job. Use different prompts for different jobs (for example, review, implement, refactor).

463

464

465---

466

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

google-vertex-ai.md +10 −5

Details

8 8

9* A Google Cloud Platform (GCP) account with billing enabled9* A Google Cloud Platform (GCP) account with billing enabled

10* A GCP project with Vertex AI API enabled10* A GCP project with Vertex AI API enabled

~~11* Access to desired Claude models (e.g., Claude Sonnet 4.5)~~11* Access to desired Claude models (for example, Claude Sonnet 4.5)

12* Google Cloud SDK (`gcloud`) installed and configured12* Google Cloud SDK (`gcloud`) installed and configured

13* Quota allocated in desired GCP region13* Quota allocated in desired GCP region

14 14

44 44

451. Navigate to the [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)451. Navigate to the [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)

462. Search for "Claude" models462. Search for "Claude" models

~~473. Request access to desired Claude models (e.g., Claude Sonnet 4.5)~~473. Request access to desired Claude models (for example, Claude Sonnet 4.5)

484. Wait for approval (may take 24-48 hours)484. Wait for approval (may take 24-48 hours)

49 49

50### 3. Configure GCP credentials50### 3. Configure GCP credentials

82```82```

83 83

84<Note>84<Note>

85 [Prompt caching](/en/docs/build-with-claude/prompt-caching) is automatically supported when you specify the `cache_control` ephemeral flag. To disable it, set `DISABLE_PROMPT_CACHING=1`. For heightened rate limits, contact Google Cloud support.85 [Prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching) is automatically supported when you specify the `cache_control` ephemeral flag. To disable it, set `DISABLE_PROMPT_CACHING=1`. For heightened rate limits, contact Google Cloud support.

86</Note>86</Note>

87 87

88<Note>88<Note>

99| Small/fast model | `claude-haiku-4-5@20251001` |99| Small/fast model | `claude-haiku-4-5@20251001` |

100 100

101<Note>101<Note>

102 For Vertex AI users, Claude Code will not automatically upgrade from Haiku 3.5 to Haiku 4.5. To manually switch to a newer Haiku model, set the `ANTHROPIC_DEFAULT_HAIKU_MODEL` environment variable to the full model name (e.g., `claude-haiku-4-5@20251001`).102 For Vertex AI users, Claude Code will not automatically upgrade from Haiku 3.5 to Haiku 4.5. To manually switch to a newer Haiku model, set the `ANTHROPIC_DEFAULT_HAIKU_MODEL` environment variable to the full model name (for example, `claude-haiku-4-5@20251001`).

103</Note>103</Note>

104 104

105To customize models:105To customize models:

127 127

128## 1M token context window128## 1M token context window

129 129

130Claude Sonnet 4 and Sonnet 4.5 support the [1M token context window](/en/docs/build-with-claude/context-windows#1m-token-context-window) on Vertex AI.130Claude Sonnet 4 and Sonnet 4.5 support the [1M token context window](https://docs.claude.com/en/docs/build-with-claude/context-windows#1m-token-context-window) on Vertex AI.

131 131

132<Note>132<Note>

133 The 1M token context window is currently in beta. To use the extended context window, include the `context-1m-2025-08-07` beta header in your Vertex AI requests.133 The 1M token context window is currently in beta. To use the extended context window, include the `context-1m-2025-08-07` beta header in your Vertex AI requests.

157* [Vertex AI documentation](https://cloud.google.com/vertex-ai/docs)157* [Vertex AI documentation](https://cloud.google.com/vertex-ai/docs)

158* [Vertex AI pricing](https://cloud.google.com/vertex-ai/pricing)158* [Vertex AI pricing](https://cloud.google.com/vertex-ai/pricing)

159* [Vertex AI quotas and limits](https://cloud.google.com/vertex-ai/docs/quotas)159* [Vertex AI quotas and limits](https://cloud.google.com/vertex-ai/docs/quotas)

160

161

162---

163

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

headless.md +91 −142

Details

~~1# Headless mode~~1# Run Claude Code programmatically

2 2

~~3> Run Claude Code programmatically without interactive UI~~3> Use the Agent SDK to run Claude Code programmatically from the CLI, Python, or TypeScript.

4 4

~~5## Overview~~5The [Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) gives you the same tools, agent loop, and context management that power Claude Code. It's available as a CLI for scripts and CI/CD, or as [Python](https://platform.claude.com/docs/en/agent-sdk/python) and [TypeScript](https://platform.claude.com/docs/en/agent-sdk/typescript) packages for full programmatic control.

6 6

~~7The headless mode allows you to run Claude Code programmatically from command line scripts and automation tools without any interactive UI.~~7<Note>

8 The CLI was previously called "headless mode." The `-p` flag and all CLI options work the same way.

9</Note>

8 10

~~9## Basic usage~~11To run Claude Code programmatically from the CLI, pass `-p` with your prompt and any [CLI options](/en/cli-reference):

~~11The primary command-line interface to Claude Code is the `claude` command. Use the `--print` (or `-p`) flag to run in non-interactive mode and print the final result:~~

12 12

13```bash theme={null}13```bash theme={null}

~~14claude -p "Stage my changes and write a set of commits for them" \~~14claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

~~15 --allowedTools "Bash,Read" \~~

~~16 --permission-mode acceptEdits~~

17```15```

18 16

~~19## Configuration Options~~17This page covers using the Agent SDK via the CLI (`claude -p`). For the Python and TypeScript SDK packages with structured outputs, tool approval callbacks, and native message objects, see the [full Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview).

~~21Headless mode leverages all the CLI options available in Claude Code. Here are the key ones for automation and scripting:~~

22 18

23| Flag | Description | Example |19## Basic usage

24| :------------------------- | :----------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |

25| `--print`, `-p` | Run in non-interactive mode | `claude -p "query"` |

26| `--output-format` | Specify output format (`text`, `json`, `stream-json`) | `claude -p --output-format json` |

27| `--resume`, `-r` | Resume a conversation by session ID | `claude --resume abc123` |

28| `--continue`, `-c` | Continue the most recent conversation | `claude --continue` |

29| `--verbose` | Enable verbose logging | `claude --verbose` |

30| `--append-system-prompt` | Append to system prompt (only with `--print`) | `claude --append-system-prompt "Custom instruction"` |

31| `--allowedTools` | Space-separated list of allowed tools, or <br /><br /> string of comma-separated list of allowed tools | `claude --allowedTools mcp__slack mcp__filesystem`<br /><br />`claude --allowedTools "Bash(npm install),mcp__filesystem"` |

32| `--disallowedTools` | Space-separated list of denied tools, or <br /><br /> string of comma-separated list of denied tools | `claude --disallowedTools mcp__splunk mcp__github`<br /><br />`claude --disallowedTools "Bash(git commit),mcp__github"` |

33| `--mcp-config` | Load MCP servers from a JSON file | `claude --mcp-config servers.json` |

34| `--permission-prompt-tool` | MCP tool for handling permission prompts (only with `--print`) | `claude --permission-prompt-tool mcp__auth__prompt` |

35 20

~~36For a complete list of CLI options and features, see the [CLI reference](/en/cli-reference) documentation.~~21Add the `-p` (or `--print`) flag to any `claude` command to run it non-interactively. All [CLI options](/en/cli-reference) work with `-p`, including:

37 22

~~38## Multi-turn conversations~~23* `--continue` for [continuing conversations](#continue-conversations)

24* `--allowedTools` for [auto-approving tools](#auto-approve-tools)

25* `--output-format` for [structured output](#get-structured-output)

39 26

~~40For multi-turn conversations, you can resume conversations or continue from the most recent session:~~27This example asks Claude a question about your codebase and prints the response:

41 28

42```bash theme={null}29```bash theme={null}

~~43# Continue the most recent conversation~~30claude -p "What does the auth module do?"

~~44claude --continue "Now refactor this for better performance"~~

~~46# Resume a specific conversation by session ID~~

~~47claude --resume 550e8400-e29b-41d4-a716-446655440000 "Update the tests"~~

~~49# Resume in non-interactive mode~~

~~50claude --resume 550e8400-e29b-41d4-a716-446655440000 "Fix all linting issues" --no-interactive~~

51```31```

52 32

~~53## Output Formats~~33## Examples

54 34

~~55### Text Output (Default)~~35These examples highlight common CLI patterns.

56 36

~~57```bash theme={null}~~37### Get structured output

~~58claude -p "Explain file src/components/Header.tsx"~~

~~59# Output: This is a React component showing...~~

~~60```~~

61 38

~~62### JSON Output~~39Use `--output-format` to control how responses are returned:

63 40

~~64Returns structured data including metadata:~~41* `text` (default): plain text output

42* `json`: structured JSON with result, session ID, and metadata

43* `stream-json`: newline-delimited JSON for real-time streaming

65 44

~~66```bash theme={null}~~45This example returns a project summary as JSON with session metadata, with the text result in the `result` field:

~~67claude -p "How does the data layer work?" --output-format json~~

~~68```~~

69 46

~~70Response format:~~47```bash theme={null}

71 48claude -p "Summarize this project" --output-format json

~~72```json theme={null}~~

~~73{~~

~~74 "type": "result",~~

~~75 "subtype": "success",~~

~~76 "total_cost_usd": 0.003,~~

~~77 "is_error": false,~~

~~78 "duration_ms": 1234,~~

~~79 "duration_api_ms": 800,~~

~~80 "num_turns": 6,~~

~~81 "result": "The response text here...",~~

~~82 "session_id": "abc123"~~

~~83}~~

84```49```

85 50

~~86### Streaming JSON Output~~51To get output conforming to a specific schema, use `--output-format json` with `--json-schema` and a [JSON Schema](https://json-schema.org/) definition. The response includes metadata about the request (session ID, usage, etc.) with the structured output in the `structured_output` field.

87 52

~~88Streams each message as it is received:~~53This example extracts function names and returns them as an array of strings:

89 54

90```bash theme={null}55```bash theme={null}

~~91claude -p "Build an application" --output-format stream-json~~56claude -p "Extract the main function names from auth.py" \

57 --output-format json \

58 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

92```59```

93 60

94Each conversation begins with an initial `init` system message, followed by a list of user and assistant messages, followed by a final `result` system message with stats. Each message is emitted as a separate JSON object.61<Tip>

95 62 Use a tool like [jq](https://jqlang.github.io/jq/) to parse the response and extract specific fields:

~~96## Input Formats~~

~~98### Text Input (Default)~~

99 63

100```bash theme={null}64 ```bash theme={null}

101# Direct argument65 # Extract the text result

102claude -p "Explain this code"66 claude -p "Summarize this project" --output-format json | jq -r '.result'

~~103~~

104# From stdin

105echo "Explain this code" | claude -p

106```

107 67

108### Streaming JSON Input68 # Extract structured output

69 claude -p "Extract function names from auth.py" \

70 --output-format json \

71 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \

72 | jq '.structured_output'

73 ```

74</Tip>

109 75

110A stream of messages provided via `stdin` where each message represents a user turn. This allows multiple turns of a conversation without re-launching the `claude` binary and allows providing guidance to the model while it is processing a request.76### Auto-approve tools

111 77

112Each message is a JSON 'User message' object, following the same format as the output message schema. Messages are formatted using the [jsonl](https://jsonlines.org/) format where each line of input is a complete JSON object. Streaming JSON input requires `-p` and `--output-format stream-json`.78Use `--allowedTools` to let Claude use certain tools without prompting. This example runs a test suite and fixes failures, allowing Claude to execute Bash commands and read/edit files without asking for permission:

113 79

114```bash theme={null}80```bash theme={null}

115echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explain this code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose81claude -p "Run the test suite and fix any failures" \

82 --allowedTools "Bash,Read,Edit"

116```83```

117 84

118## Agent Integration Examples85### Create a commit

119 86

120### SRE Incident Response Bot87This example reviews staged changes and creates a commit with an appropriate message:

121 88

122```bash theme={null}89```bash theme={null}

123#!/bin/bash90claude -p "Look at my staged changes and create an appropriate commit" \

~~124~~ 91 --allowedTools "Bash(git diff:*),Bash(git log:*),Bash(git status:*),Bash(git commit:*)"

125# Automated incident response agent92```

126investigate_incident() {

127 local incident_description="$1"

128 local severity="${2:-medium}"

129 93

130 claude -p "Incident: $incident_description (Severity: $severity)" \94<Note>

131 --append-system-prompt "You are an SRE expert. Diagnose the issue, assess impact, and provide immediate action items." \95 [Slash commands](/en/slash-commands) like `/commit` are only available in interactive mode. In `-p` mode, describe the task you want to accomplish instead.

132 --output-format json \96</Note>

133 --allowedTools "Bash,Read,WebSearch,mcp__datadog" \

134 --mcp-config monitoring-tools.json

135}

136 97

137# Usage98### Customize the system prompt

138investigate_incident "Payment API returning 500 errors" "high"

139```

140 99

141### Automated Security Review100Use `--append-system-prompt` to add instructions while keeping Claude Code's default behavior. This example pipes a PR diff to Claude and instructs it to review for security vulnerabilities:

142 101

143```bash theme={null}102```bash theme={null}

144# Security audit agent for pull requests103gh pr diff "$1" | claude -p \

145audit_pr() {104 --append-system-prompt "You are a security engineer. Review for vulnerabilities." \

146 local pr_number="$1"105 --output-format json

106```

147 107

148 gh pr diff "$pr_number" | claude -p \108See [system prompt flags](/en/cli-reference#system-prompt-flags) for more options including `--system-prompt` to fully replace the default prompt.

149 --append-system-prompt "You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues." \

150 --output-format json \

151 --allowedTools "Read,Grep,WebSearch"

152}

153 109

154# Usage and save to file110### Continue conversations

155audit_pr 123 > security-report.json

156```

157 111

158### Multi-turn Legal Assistant112Use `--continue` to continue the most recent conversation, or `--resume` with a session ID to continue a specific conversation. This example runs a review, then sends follow-up prompts:

159 113

160```bash theme={null}114```bash theme={null}

161# Legal document review with session persistence115# First request

162session_id=$(claude -p "Start legal review session" --output-format json | jq -r '.session_id')116claude -p "Review this codebase for performance issues"

163 117

164# Review contract in multiple steps118# Continue the most recent conversation

165claude -p --resume "$session_id" "Review contract.pdf for liability clauses"119claude -p "Now focus on the database queries" --continue

166claude -p --resume "$session_id" "Check compliance with GDPR requirements"120claude -p "Generate a summary of all issues found" --continue

167claude -p --resume "$session_id" "Generate executive summary of risks"

168```121```

169 122

170## Best Practices123If you're running multiple conversations, capture the session ID to resume a specific one:

171 124

172* **Use JSON output format** for programmatic parsing of responses:125```bash theme={null}

126session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')

127claude -p "Continue that review" --resume "$session_id"

128```

173 129

174 ```bash theme={null}130## Next steps

175 # Parse JSON response with jq

176 result=$(claude -p "Generate code" --output-format json)

177 code=$(echo "$result" | jq -r '.result')

178 cost=$(echo "$result" | jq -r '.cost_usd')

179 ```

180 131

181* **Handle errors gracefully** - check exit codes and stderr:132<CardGroup cols={2}>

133 <Card title="Agent SDK quickstart" icon="play" href="https://platform.claude.com/docs/en/agent-sdk/quickstart">

134 Build your first agent with Python or TypeScript

135 </Card>

182 136

183 ```bash theme={null}137 <Card title="CLI reference" icon="terminal" href="/en/cli-reference">

184 if ! claude -p "$prompt" 2>error.log; then138 Explore all CLI flags and options

185 echo "Error occurred:" >&2139 </Card>

186 cat error.log >&2

187 exit 1

188 fi

189 ```

~~190~~

191* **Use session management** for maintaining context in multi-turn conversations

192 140

193* **Consider timeouts** for long-running operations:141 <Card title="GitHub Actions" icon="github" href="/en/github-actions">

142 Use the Agent SDK in GitHub workflows

143 </Card>

194 144

195 ```bash theme={null}145 <Card title="GitLab CI/CD" icon="gitlab" href="/en/gitlab-ci-cd">

196 timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"146 Use the Agent SDK in GitLab pipelines

197 ```147 </Card>

148</CardGroup>

198 149

199* **Respect rate limits** when making multiple requests by adding delays between calls

200 150

201## Related Resources151---

202 152

203* [CLI usage and controls](/en/cli-reference) - Complete CLI documentation153> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

204* [Common workflows](/en/common-workflows) - Step-by-step guides for common use cases

hooks.md +143 −35

Details

15* `.claude/settings.local.json` - Local project settings (not committed)15* `.claude/settings.local.json` - Local project settings (not committed)

16* Enterprise managed policy settings16* Enterprise managed policy settings

17 17

18<Note>

19 Enterprise administrators can use `allowManagedHooksOnly` to block user, project, and plugin hooks. See [Hook configuration](/en/settings#hook-configuration).

20</Note>

18### Structure22### Structure

19 23

20Hooks are organized by matchers, where each matcher can have multiple hooks:24Hooks are organized by matchers, where each matcher can have multiple hooks:

38```42```

39 43

40* **matcher**: Pattern to match tool names, case-sensitive (only applicable for44* **matcher**: Pattern to match tool names, case-sensitive (only applicable for

~~41 `PreToolUse` and `PostToolUse`)~~45 `PreToolUse`, `PermissionRequest`, and `PostToolUse`)

42 * Simple strings match exactly: `Write` matches only the Write tool46 * Simple strings match exactly: `Write` matches only the Write tool

43 * Supports regex: `Edit|Write` or `Notebook.*`47 * Supports regex: `Edit|Write` or `Notebook.*`

44 * Use `*` to match all tools. You can also use empty string (`""`) or leave48 * Use `*` to match all tools. You can also use empty string (`""`) or leave

49 * `prompt`: (For `type: "prompt"`) The prompt to send to the LLM for evaluation53 * `prompt`: (For `type: "prompt"`) The prompt to send to the LLM for evaluation

50 * `timeout`: (Optional) How long a hook should run, in seconds, before canceling that specific hook54 * `timeout`: (Optional) How long a hook should run, in seconds, before canceling that specific hook

51 55

~~52For events like `UserPromptSubmit`, `Notification`, `Stop`, and `SubagentStop`~~56For events like `UserPromptSubmit`, `Stop`, and `SubagentStop`

53that don't use matchers, you can omit the matcher field:57that don't use matchers, you can omit the matcher field:

54 58

55```json theme={null}59```json theme={null}

211* **SubagentStop**: Evaluate if a subagent has completed its task215* **SubagentStop**: Evaluate if a subagent has completed its task

212* **UserPromptSubmit**: Validate user prompts with LLM assistance216* **UserPromptSubmit**: Validate user prompts with LLM assistance

213* **PreToolUse**: Make context-aware permission decisions217* **PreToolUse**: Make context-aware permission decisions

218* **PermissionRequest**: Intelligently allow or deny permission dialogs

214 219

215### Example: Intelligent Stop hook220### Example: Intelligent Stop hook

216 221

257| --------------------- | ----------------------- | ------------------------------ |262| --------------------- | ----------------------- | ------------------------------ |

289* `Write` - File writing294* `Write` - File writing

290* `WebFetch`, `WebSearch` - Web operations295* `WebFetch`, `WebSearch` - Web operations

291 296

297Use [PreToolUse decision control](#pretooluse-decision-control) to allow, deny, or ask for permission to use the tool.

298

299### PermissionRequest

300

301Runs when the user is shown a permission dialog.

302Use [PermissionRequest decision control](#permissionrequest-decision-control) to allow or deny on behalf of the user.

303

304Recognizes the same matcher values as PreToolUse.

305

292### PostToolUse306### PostToolUse

293 307

294Runs immediately after a tool completes successfully.308Runs immediately after a tool completes successfully.

297 311

298### Notification312### Notification

299 313

300Runs when Claude Code sends notifications. Notifications are sent when:314Runs when Claude Code sends notifications. Supports matchers to filter by notification type.

301 315

3021. Claude needs your permission to use a tool. Example: "Claude needs your316**Common matchers:**

303 permission to use Bash"317

3042. The prompt input has been idle for at least 60 seconds. "Claude is waiting318* `permission_prompt` - Permission requests from Claude Code

305 for your input"319* `idle_prompt` - When Claude is waiting for user input (after 60+ seconds of idle time)

320* `auth_success` - Authentication success notifications

321* `elicitation_dialog` - When Claude Code needs input for MCP tool elicitation

322

323You can use matchers to run different hooks for different notification types, or omit the matcher to run hooks for all notifications.

324

325**Example: Different notifications for different types**

326

327```json theme={null}

328{

329 "hooks": {

330 "Notification": [

331 {

332 "matcher": "permission_prompt",

333 "hooks": [

334 {

335 "type": "command",

336 "command": "/path/to/permission-alert.sh"

337 }

338 ]

339 },

340 {

341 "matcher": "idle_prompt",

342 "hooks": [

343 {

344 "type": "command",

345 "command": "/path/to/idle-notification.sh"

346 }

347 ]

348 }

349 ]

350 }

351}

352```

306 353

307### UserPromptSubmit354### UserPromptSubmit

308 355

361 408

362**Example: Persisting all environment changes from the hook**409**Example: Persisting all environment changes from the hook**

363 410

364When your setup modifies the environment (e.g., `nvm use`), capture and persist all changes by diffing the environment:411When your setup modifies the environment (for example, `nvm use`), capture and persist all changes by diffing the environment:

365 412

366```bash theme={null}413```bash theme={null}

367#!/bin/bash414#!/bin/bash

409 session_id: string456 session_id: string

410 transcript_path: string // Path to conversation JSON457 transcript_path: string // Path to conversation JSON

411 cwd: string // The current working directory when the hook is invoked458 cwd: string // The current working directory when the hook is invoked

412 permission_mode: string // Current permission mode: "default", "plan", "acceptEdits", or "bypassPermissions"459 permission_mode: string // Current permission mode: "default", "plan", "acceptEdits", "dontAsk", or "bypassPermissions"

413 460

414 // Event-specific fields461 // Event-specific fields

415 hook_event_name: string462 hook_event_name: string

432 "tool_input": {479 "tool_input": {

433 "file_path": "/path/to/file.txt",480 "file_path": "/path/to/file.txt",

434 "content": "file content"481 "content": "file content"

435 }482 },

483 "tool_use_id": "toolu_01ABC123..."

436}484}

437```485```

438 486

455 "tool_response": {503 "tool_response": {

456 "filePath": "/path/to/file.txt",504 "filePath": "/path/to/file.txt",

457 "success": true505 "success": true

458 }506 },

507 "tool_use_id": "toolu_01ABC123..."

459}508}

460```509```

461 510

468 "cwd": "/Users/...",517 "cwd": "/Users/...",

469 "permission_mode": "default",518 "permission_mode": "default",

470 "hook_event_name": "Notification",519 "hook_event_name": "Notification",

471 "message": "Task completed successfully"520 "message": "Claude needs your permission to use Bash",

521 "notification_type": "permission_prompt"

472}522}

473```523```

474 524

544 594

545## Hook Output595## Hook Output

546 596

547There are two ways for hooks to return output back to Claude Code. The output597There are two mutually exclusive ways for hooks to return output back to Claude Code. The output

548communicates whether to block and any feedback that should be shown to Claude598communicates whether to block and any feedback that should be shown to Claude

549and the user.599and the user.

550 600

552 602

553Hooks communicate status through exit codes, stdout, and stderr:603Hooks communicate status through exit codes, stdout, and stderr:

554 604

555* **Exit code 0**: Success. `stdout` is shown to the user in transcript mode605* **Exit code 0**: Success. `stdout` is shown to the user in verbose mode

556 (CTRL-R), except for `UserPromptSubmit` and `SessionStart`, where stdout is606 (ctrl+o), except for `UserPromptSubmit` and `SessionStart`, where stdout is

557 added to the context.607 added to the context. JSON output in `stdout` is parsed for structured control

558* **Exit code 2**: Blocking error. `stderr` is fed back to Claude to process608 (see [Advanced: JSON Output](#advanced-json-output)).

559 automatically. See per-hook-event behavior below.609* **Exit code 2**: Blocking error. Only `stderr` is used as the error message

560* **Other exit codes**: Non-blocking error. `stderr` is shown to the user and610 and fed back to Claude. The format is `[command]: {stderr}`. JSON in `stdout`

561 execution continues.611 is **not** processed for exit code 2. See per-hook-event behavior below.

612* **Other exit codes**: Non-blocking error. `stderr` is shown to the user in verbose mode (ctrl+o) with

613 format `Failed with non-blocking status code: {stderr}`. If `stderr` is empty,

614 it shows `No stderr output`. Execution continues.

562 615

563<Warning>616<Warning>

564 Reminder: Claude Code does not see stdout if the exit code is 0, except for617 Reminder: Claude Code does not see stdout if the exit code is 0, except for

568#### Exit Code 2 Behavior621#### Exit Code 2 Behavior

569 622

570| Hook Event | Behavior |623| Hook Event | Behavior |

571| ------------------ | ------------------------------------------------------------------ |624| ------------------- | ------------------------------------------------------------------ |

626| `PermissionRequest` | Denies the permission, shows stderr to Claude |

581 635

582### Advanced: JSON Output636### Advanced: JSON Output

583 637

584Hooks can return structured JSON in `stdout` for more sophisticated control:638Hooks can return structured JSON in `stdout` for more sophisticated control.

639

640<Warning>

641 JSON output is only processed when the hook exits with code 0. If your hook

642 exits with code 2 (blocking error), `stderr` text is used directly—any JSON in `stdout`

643 is ignored. For other non-zero exit codes, only `stderr` is shown to the user in verbose mode (ctrl+o).

644</Warning>

585 645

586#### Common JSON Fields646#### Common JSON Fields

587 647

625 685

626Additionally, hooks can modify tool inputs before execution using `updatedInput`:686Additionally, hooks can modify tool inputs before execution using `updatedInput`:

627 687

628* `updatedInput` allows you to modify the tool's input parameters before the tool executes. This is a `Record<string, unknown>` object containing the fields you want to change or add.688* `updatedInput` allows you to modify the tool's input parameters before the tool executes.

629* This is most useful with `"permissionDecision": "allow"` to modify and approve tool calls.689* This is most useful with `"permissionDecision": "allow"` to modify and approve tool calls.

630 690

631```json theme={null}691```json theme={null}

648 `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively.708 `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively.

649</Note>709</Note>

650 710

711#### `PermissionRequest` Decision Control

712

713`PermissionRequest` hooks can allow or deny permission requests shown to the user.

714

715* For `"behavior": "allow"` you can also optionally pass in an `"updatedInput"` that modifies the tool's input parameters before the tool executes.

716* For `"behavior": "deny"` you can also optionally pass in a `"message"` string that tells the model why the permission was denied, and a boolean `"interrupt"` which will stop Claude.

717

718```json theme={null}

719{

720 "hookSpecificOutput": {

721 "hookEventName": "PermissionRequest",

722 "decision": {

723 "behavior": "allow",

724 "updatedInput": {

725 "command": "npm run lint"

726 }

727 }

728 }

729}

730```

731

651#### `PostToolUse` Decision Control732#### `PostToolUse` Decision Control

652 733

653`PostToolUse` hooks can provide feedback to Claude after tool execution.734`PostToolUse` hooks can provide feedback to Claude after tool execution.

669 750

670#### `UserPromptSubmit` Decision Control751#### `UserPromptSubmit` Decision Control

671 752

672`UserPromptSubmit` hooks can control whether a user prompt is processed.753`UserPromptSubmit` hooks can control whether a user prompt is processed and add context.

754

755**Adding context (exit code 0):**

756There are two ways to add context to the conversation:

757

7581. **Plain text stdout** (simpler): Any non-JSON text written to stdout is added

759 as context. This is the easiest way to inject information.

760

7612. **JSON with `additionalContext`** (structured): Use the JSON format below for

762 more control. The `additionalContext` field is added as context.

763

764Both methods work with exit code 0. Plain stdout is shown as hook output in

765the transcript; `additionalContext` is added more discretely.

673 766

674* `"block"` prevents the prompt from being processed. The submitted prompt is767**Blocking prompts:**

675 erased from context. `"reason"` is shown to the user but not added to context.768

676* `undefined` allows the prompt to proceed normally. `"reason"` is ignored.769* `"decision": "block"` prevents the prompt from being processed. The submitted

677* `"hookSpecificOutput.additionalContext"` adds the string to the context if not770 prompt is erased from context. `"reason"` is shown to the user but not added

678 blocked.771 to context.

772* `"decision": undefined` (or omitted) allows the prompt to proceed normally.

679 773

680```json theme={null}774```json theme={null}

681{775{

688}782}

689```783```

690 784

785<Note>

786 The JSON format isn't required for simple use cases. To add context, you can print plain text to stdout with exit code 0. Use JSON when you need to

787 block prompts or want more structured control.

788</Note>

789

691#### `Stop`/`SubagentStop` Decision Control790#### `Stop`/`SubagentStop` Decision Control

692 791

693`Stop` and `SubagentStop` hooks can control whether Claude must continue.792`Stop` and `SubagentStop` hooks can control whether Claude must continue.

781<Note>880<Note>

782 For `UserPromptSubmit` hooks, you can inject context using either method:881 For `UserPromptSubmit` hooks, you can inject context using either method:

783 882

784 * Exit code 0 with stdout: Claude sees the context (special case for `UserPromptSubmit`)883 * **Plain text stdout** with exit code 0: Simplest approach, prints text

785 * JSON output: Provides more control over the behavior884 * **JSON output** with exit code 0: Use `"decision": "block"` to reject prompts,

885 or `additionalContext` for structured context injection

886

887 Remember: Exit code 2 only uses `stderr` for the error message. To block using

888 JSON (with a custom reason), use `"decision": "block"` with exit code 0.

786</Note>889</Note>

787 890

788```python theme={null}891```python theme={null}

859 output = {962 output = {

860 "decision": "approve",963 "decision": "approve",

861 "reason": "Documentation file auto-approved",964 "reason": "Documentation file auto-approved",

862 "suppressOutput": True # Don't show in transcript mode965 "suppressOutput": True # Don't show in verbose mode

863 }966 }

864 print(json.dumps(output))967 print(json.dumps(output))

865 sys.exit(0)968 sys.exit(0)

972 * The `CLAUDE_CODE_REMOTE` environment variable indicates whether the hook is running in a remote (web) environment (`"true"`) or local CLI environment (not set or empty). Use this to run different logic based on execution context.1075 * The `CLAUDE_CODE_REMOTE` environment variable indicates whether the hook is running in a remote (web) environment (`"true"`) or local CLI environment (not set or empty). Use this to run different logic based on execution context.

973* **Input**: JSON via stdin1076* **Input**: JSON via stdin

974* **Output**:1077* **Output**:

975 * PreToolUse/PostToolUse/Stop/SubagentStop: Progress shown in transcript (Ctrl-R)1078 * PreToolUse/PermissionRequest/PostToolUse/Stop/SubagentStop: Progress shown in verbose mode (ctrl+o)

976 * Notification/SessionEnd: Logged to debug only (`--debug`)1079 * Notification/SessionEnd: Logged to debug only (`--debug`)

977 * UserPromptSubmit/SessionStart: stdout added as context for Claude1080 * UserPromptSubmit/SessionStart: stdout added as context for Claude

978 1081

1021[DEBUG] Hook command completed with status 0: <Your stdout>1124[DEBUG] Hook command completed with status 0: <Your stdout>

1022```1125```

1023 1126

1024Progress messages appear in transcript mode (Ctrl-R) showing:1127Progress messages appear in verbose mode (ctrl+o) showing:

1025 1128

1026* Which hook is running1129* Which hook is running

1027* Command being executed1130* Command being executed

1028* Success/failure status1131* Success/failure status

1029* Output or error messages1132* Output or error messages

1133

1134

1135---

1136

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

hooks-guide.md +7 −1

Details

40workflow:40workflow:

41 41

42* **PreToolUse**: Runs before tool calls (can block them)42* **PreToolUse**: Runs before tool calls (can block them)

43* **PermissionRequest**: Runs when a permission dialog is shown (can allow or deny)

43* **PostToolUse**: Runs after tool calls complete44* **PostToolUse**: Runs after tool calls complete

44* **UserPromptSubmit**: Runs when the user submits a prompt, before Claude processes it45* **UserPromptSubmit**: Runs when the user submits a prompt, before Claude processes it

45* **Notification**: Runs when Claude Code sends notifications46* **Notification**: Runs when Claude Code sends notifications

91directory. This hook will then apply to all projects, not just your current92directory. This hook will then apply to all projects, not just your current

92project.93project.

93 94

~~94Then press Esc until you return to the REPL. Your hook is now registered!~~95Then press `Esc` until you return to the REPL. Your hook is now registered.

95 96

96### Step 5: Verify your hook97### Step 5: Verify your hook

97 98

330* For comprehensive security best practices and safety guidelines, see [Security Considerations](/en/hooks#security-considerations) in the hooks reference documentation.331* For comprehensive security best practices and safety guidelines, see [Security Considerations](/en/hooks#security-considerations) in the hooks reference documentation.

331* For troubleshooting steps and debugging techniques, see [Debugging](/en/hooks#debugging) in the hooks reference332* For troubleshooting steps and debugging techniques, see [Debugging](/en/hooks#debugging) in the hooks reference

332 documentation.333 documentation.

334

335

336---

337

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

iam.md +22 −33

Details

4 4

5## Authentication methods5## Authentication methods

6 6

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

8 8

9* Claude API via the Claude Console9* Claude API via the Claude Console

10* Amazon Bedrock10* Amazon Bedrock

11* Microsoft Foundry

11* Google Vertex AI12* Google Vertex AI

12 13

13### Claude API authentication14### Claude API authentication

29 30

30### Cloud provider authentication31### Cloud provider authentication

31 32

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

33 34

~~341. Follow the [Bedrock docs](/en/amazon-bedrock) or [Vertex docs](/en/google-vertex-ai)~~351. Follow the [Bedrock docs](/en/amazon-bedrock), [Vertex docs](/en/google-vertex-ai), or [Microsoft Foundry docs](/en/microsoft-foundry)

352. Distribute the environment variables and instructions for generating cloud credentials to your users. Read more about how to [manage configuration here](/en/settings).362. Distribute the environment variables and instructions for generating cloud credentials to your users. Read more about how to [manage configuration here](/en/settings).

363. Users can [install Claude Code](/en/setup#installation)373. Users can [install Claude Code](/en/setup#installation)

37 38

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

69 70

70| Mode | Description |71| Mode | Description |

~~71| :------------------ | :--------------------------------------------------------------------------- |~~72| :------------------ | :------------------------------------------------------------------------------------------------------------------------ |

72| `default` | Standard behavior - prompts for permission on first use of each tool |73| `default` | Standard behavior - prompts for permission on first use of each tool |

73| `acceptEdits` | Automatically accepts file edit permissions for the session |74| `acceptEdits` | Automatically accepts file edit permissions for the session |

74| `plan` | Plan Mode - Claude can analyze but not modify files or execute commands |75| `plan` | Plan Mode - Claude can analyze but not modify files or execute commands |

76| `dontAsk` | Auto-denies tools unless pre-approved via `/permissions` or [`permissions.allow`](/en/settings#permission-settings) rules |

75| `bypassPermissions` | Skips all permission prompts (requires safe environment - see warning below) |77| `bypassPermissions` | Skips all permission prompts (requires safe environment - see warning below) |

76 78

77#### Working directories79#### Working directories

146**MCP**148**MCP**

147 149

148* `mcp__puppeteer` Matches any tool provided by the `puppeteer` server (name configured in Claude Code)150* `mcp__puppeteer` Matches any tool provided by the `puppeteer` server (name configured in Claude Code)

151* `mcp__puppeteer__*` Wildcard syntax that also matches all tools from the `puppeteer` server

149* `mcp__puppeteer__puppeteer_navigate` Matches the `puppeteer_navigate` tool provided by the `puppeteer` server152* `mcp__puppeteer__puppeteer_navigate` Matches the `puppeteer_navigate` tool provided by the `puppeteer` server

150 153

151<Warning>

152 Unlike other permission types, MCP permissions do NOT support wildcards (`*`).

~~153~~

154 To approve all tools from an MCP server:

~~155~~

156 * ✅ Use: `mcp__github` (approves ALL GitHub tools)

157 * ❌ Don't use: `mcp__github__*` (wildcards are not supported)

~~158~~

159 To approve specific tools only, list each one:

~~160~~

161 * ✅ Use: `mcp__github__get_issue`

162 * ✅ Use: `mcp__github__list_issues`

163</Warning>

~~164~~

165### Additional permission control with hooks154### Additional permission control with hooks

166 155

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

168 157

169### Enterprise managed policy settings158### Enterprise managed settings

~~170~~

171For enterprise deployments of Claude Code, we support enterprise managed policy settings that take precedence over user and project settings. This allows system administrators to enforce security policies that users cannot override.

~~172~~

173System administrators can deploy policies to:

174 159

175* macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`160For enterprise deployments of Claude Code, administrators can configure and distribute settings to their organization through the [Claude.ai admin console](https://claude.ai/admin-settings/claude-code). These settings are fetched automatically when users authenticate and cannot be overridden locally. This feature is available to Claude for Enterprise customers. If you don't see this option in your admin console, contact your Anthropic account team to have the feature enabled.

176* Linux and WSL: `/etc/claude-code/managed-settings.json`

177* Windows: `C:\ProgramData\ClaudeCode\managed-settings.json`

178 161

179These policy files follow the same format as regular [settings files](/en/settings#settings-files) but cannot be overridden by user or project settings. This ensures consistent security policies across your organization.162For organizations that prefer file-based policy distribution, Claude Code also supports `managed-settings.json` files that can be deployed to [system directories](/en/settings#settings-files). These policy files follow the same format as regular settings files and cannot be overridden by user or project settings.

180 163

181### Settings precedence164### Settings precedence

182 165

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

184 167

1851. Enterprise policies1681. Managed settings (via Claude.ai admin console)

1862. Command line arguments1692. File-based managed settings (`managed-settings.json`)

1873. Local project settings (`.claude/settings.local.json`)1703. Command line arguments

1884. Shared project settings (`.claude/settings.json`)1714. Local project settings (`.claude/settings.local.json`)

1895. User settings (`~/.claude/settings.json`)1725. Shared project settings (`.claude/settings.json`)

1736. User settings (`~/.claude/settings.json`)

190 174

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

192 176

195Claude Code securely manages your authentication credentials:179Claude Code securely manages your authentication credentials:

196 180

197* **Storage location**: On macOS, API keys, OAuth tokens, and other credentials are stored in the encrypted macOS Keychain.181* **Storage location**: On macOS, API keys, OAuth tokens, and other credentials are stored in the encrypted macOS Keychain.

198* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Bedrock Auth, and Vertex Auth.182* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.

199* **Custom credential scripts**: The [`apiKeyHelper`](/en/settings#available-settings) setting can be configured to run a shell script that returns an API key.183* **Custom credential scripts**: The [`apiKeyHelper`](/en/settings#available-settings) setting can be configured to run a shell script that returns an API key.

200* **Refresh intervals**: By default, `apiKeyHelper` is called after 5 minutes or on HTTP 401 response. Set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals.184* **Refresh intervals**: By default, `apiKeyHelper` is called after 5 minutes or on HTTP 401 response. Set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals.

185

186

187---

188

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

interactive-mode.md +9 −5

Details

5## Keyboard shortcuts5## Keyboard shortcuts

6 6

7<Note>7<Note>

~~8 Keyboard shortcuts may vary by platform and terminal. Press `?` to see available shortcuts for your environment.~~8 Keyboard shortcuts may vary by platform and terminal. Press `?` to see available shortcuts for your environment. For example, Option key combinations on macOS may require configuring your terminal to use Option as a meta/escape key.

9</Note>9</Note>

10 10

11### General controls11### General controls

12 12

~~14| :------------------------------------------- | :----------------------------------------------------------------------- | :---------------------------------------------------------- |~~14| :-------------------------------------------- | :--------------------------------- | :---------------------------------------------------------- |

~~23| `Tab` | Toggle [extended thinking](/en/docs/build-with-claude/extended-thinking) | Switch between Thinking on and Thinking off |~~

24| `Option+P` (macOS) or `Alt+P` (Windows/Linux) | Switch model | Switch models without clearing your prompt |

25 25

26### Multiline input26### Multiline input

27 27

40### Quick commands40### Quick commands

41 41

~~43| :----------- | :--------------------------------- | :------------------------------------------------------------ |~~43| :----------- | :---------------- | :------------------------------------------------------------ |

~~44| `#` at start | Memory shortcut - add to CLAUDE.md | Prompts for file selection |~~

47| `@` | File path mention | Trigger file path autocomplete |46| `@` | File path mention | Trigger file path autocomplete |

167* [CLI reference](/en/cli-reference) - Command-line flags and options166* [CLI reference](/en/cli-reference) - Command-line flags and options

168* [Settings](/en/settings) - Configuration options167* [Settings](/en/settings) - Configuration options

169* [Memory management](/en/memory) - Managing CLAUDE.md files168* [Memory management](/en/memory) - Managing CLAUDE.md files

169

170

171---

172

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

jetbrains.md +9 −6

Details

20* **Quick launch**: Use `Cmd+Esc` (Mac) or `Ctrl+Esc` (Windows/Linux) to open Claude Code directly from your editor, or click the Claude Code button in the UI20* **Quick launch**: Use `Cmd+Esc` (Mac) or `Ctrl+Esc` (Windows/Linux) to open Claude Code directly from your editor, or click the Claude Code button in the UI

21* **Diff viewing**: Code changes can be displayed directly in the IDE diff viewer instead of the terminal21* **Diff viewing**: Code changes can be displayed directly in the IDE diff viewer instead of the terminal

22* **Selection context**: The current selection/tab in the IDE is automatically shared with Claude Code22* **Selection context**: The current selection/tab in the IDE is automatically shared with Claude Code

~~23* **File reference shortcuts**: Use `Cmd+Option+K` (Mac) or `Alt+Ctrl+K` (Linux/Windows) to insert file references (e.g., @File#L1-99)~~23* **File reference shortcuts**: Use `Cmd+Option+K` (Mac) or `Alt+Ctrl+K` (Linux/Windows) to insert file references (for example, @File#L1-99)

24* **Diagnostic sharing**: Diagnostic errors (lint, syntax, etc.) from the IDE are automatically shared with Claude as you work24* **Diagnostic sharing**: Diagnostic errors (lint, syntax, etc.) from the IDE are automatically shared with Claude as you work

25 25

26## Installation26## Installation

29 29

30Find and install the [Claude Code plugin](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) from the JetBrains marketplace and restart your IDE.30Find and install the [Claude Code plugin](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) from the JetBrains marketplace and restart your IDE.

31 31

~~32### Auto-Installation~~32If you haven't installed Claude Code yet, see [our quickstart guide](/en/quickstart) for installation instructions.

~~34The plugin may also be auto-installed when you run `claude` in the integrated terminal. The IDE must be restarted completely to take effect.~~

35 33

36<Note>34<Note>

~~37 After installing the plugin, you must restart your IDE completely for it to take effect. You may need to restart multiple times.~~35 After installing the plugin, you may need to restart your IDE completely for it to take effect.

38</Note>36</Note>

39 37

40## Usage38## Usage

70 68

71#### General Settings69#### General Settings

72 70

~~73* **Claude command**: Specify a custom command to run Claude (e.g., `claude`, `/usr/local/bin/claude`, or `npx @anthropic/claude`)~~71* **Claude command**: Specify a custom command to run Claude (for example, `claude`, `/usr/local/bin/claude`, or `npx @anthropic/claude`)

74* **Suppress notification for Claude command not found**: Skip notifications about not finding the Claude command72* **Suppress notification for Claude command not found**: Skip notifications about not finding the Claude command

75* **Enable using Option+Enter for multi-line prompts** (macOS only): When enabled, Option+Enter inserts new lines in Claude Code prompts. Disable if experiencing issues with the Option key being captured unexpectedly (requires terminal restart)73* **Enable using Option+Enter for multi-line prompts** (macOS only): When enabled, Option+Enter inserts new lines in Claude Code prompts. Disable if experiencing issues with the Option key being captured unexpectedly (requires terminal restart)

76* **Enable automatic updates**: Automatically check for and install plugin updates (applied on restart)74* **Enable automatic updates**: Automatically check for and install plugin updates (applied on restart)

148* Being aware of which files Claude Code has access to modify146* Being aware of which files Claude Code has access to modify

149 147

150For additional help, see our [troubleshooting guide](/en/troubleshooting).148For additional help, see our [troubleshooting guide](/en/troubleshooting).

149

150

151---

152

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

legal-and-compliance.md +5 −0

Details

34***34***

35 35

39---

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

llm-gateway.md +38 −8

Details

1# LLM gateway configuration1# LLM gateway configuration

2 2

~~3> Learn how to configure Claude Code with LLM gateway solutions, including LiteLLM setup, authentication methods, and enterprise features like usage tracking and budget management.~~3> Learn how to configure Claude Code to work with LLM gateway solutions. Covers gateway requirements, authentication configuration, model selection, and provider-specific endpoint setup.

4 4

~~5LLM gateways provide a centralized proxy layer between Claude Code and model providers, offering:~~5LLM gateways provide a centralized proxy layer between Claude Code and model providers, often providing:

6 6

7* **Centralized authentication** - Single point for API key management7* **Centralized authentication** - Single point for API key management

8* **Usage tracking** - Monitor usage across teams and projects8* **Usage tracking** - Monitor usage across teams and projects

10* **Audit logging** - Track all model interactions for compliance10* **Audit logging** - Track all model interactions for compliance

11* **Model routing** - Switch between providers without code changes11* **Model routing** - Switch between providers without code changes

12 12

13## Gateway requirements

15For an LLM gateway to work with Claude Code, it must meet the following requirements:

17**API format**

19The gateway must expose to clients at least one of the following API formats:

211. **Anthropic Messages**: `/v1/messages`, `/v1/messages/count_tokens`

22 * Must forward request headers: `anthropic-beta`, `anthropic-version`

242. **Bedrock InvokeModel**: `/invoke`, `/invoke-with-response-stream`

25 * Must preserve request body fields: `anthropic_beta`, `anthropic_version`

273. **Vertex rawPredict**: `:rawPredict`, `:streamRawPredict`, `/count-tokens:rawPredict`

28 * Must forward request headers: `anthropic-beta`, `anthropic-version`

30Failure to forward headers or preserve body fields may result in reduced functionality or inability to use Claude Code features.

32<Note>

33 Claude Code determines which features to enable based on the API format. When using the Anthropic Messages format with Bedrock or Vertex, you may need to set environment variable `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`.

34</Note>

36## Configuration

38### Model selection

40By default, Claude Code will use standard model names for the selected API format.

42If you have configured custom model names in your gateway, use the environment variables documented in [Model configuration](/en/model-config) to match your custom names.

13## LiteLLM configuration44## LiteLLM configuration

14 45

15<Note>46<Note>

129export CLOUD_ML_REGION=us-east5160export CLOUD_ML_REGION=us-east5

130```161```

131 162

132### Model selection

~~133~~

134By default, the models will use those specified in [Model configuration](/en/bedrock-vertex-proxies#model-configuration).

~~135~~

136If you have configured custom model names in LiteLLM, set the aforementioned environment variables to those custom names.

~~137~~

138For more detailed information, refer to the [LiteLLM documentation](https://docs.litellm.ai/).163For more detailed information, refer to the [LiteLLM documentation](https://docs.litellm.ai/).

139 164

140## Additional resources165## Additional resources

143* [Claude Code settings](/en/settings)168* [Claude Code settings](/en/settings)

144* [Enterprise network configuration](/en/network-config)169* [Enterprise network configuration](/en/network-config)

145* [Third-party integrations overview](/en/third-party-integrations)170* [Third-party integrations overview](/en/third-party-integrations)

171

172

173---

174

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

mcp.md +190 −32

Details

3> Learn how to connect Claude Code to your tools with the Model Context Protocol.3> Learn how to connect Claude Code to your tools with the Model Context Protocol.

4 4

5 5

6Claude 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.6Claude 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.

7 7

8## What you can do with MCP8## What you can do with MCP

9 9

11 11

12* **Implement features from issue trackers**: "Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub."12* **Implement features from issue trackers**: "Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub."

13* **Analyze monitoring data**: "Check Sentry and Statsig to check the usage of the feature described in ENG-4521."13* **Analyze monitoring data**: "Check Sentry and Statsig to check the usage of the feature described in ENG-4521."

~~14* **Query databases**: "Find emails of 10 random users who used feature ENG-4521, based on our Postgres database."~~14* **Query databases**: "Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database."

15* **Integrate designs**: "Update our standard email template based on the new Figma designs that were posted in Slack"15* **Integrate designs**: "Update our standard email template based on the new Figma designs that were posted in Slack"

16* **Automate workflows**: "Create Gmail drafts inviting these 10 users to a feedback session about the new feature."16* **Automate workflows**: "Create Gmail drafts inviting these 10 users to a feedback session about the new feature."

17 17

121 * `local` (default): Available only to you in the current project (was called `project` in older versions)121 * `local` (default): Available only to you in the current project (was called `project` in older versions)

122 * `project`: Shared with everyone in the project via `.mcp.json` file122 * `project`: Shared with everyone in the project via `.mcp.json` file

123 * `user`: Available to you across all projects (was called `global` in older versions)123 * `user`: Available to you across all projects (was called `global` in older versions)

124 * Set environment variables with `--env` flags (e.g., `--env KEY=value`)124 * Set environment variables with `--env` flags (for example, `--env KEY=value`)

125 * Configure MCP server startup timeout using the MCP\_TIMEOUT environment variable (e.g., `MCP_TIMEOUT=10000 claude` sets a 10-second timeout)125 * Configure MCP server startup timeout using the MCP\_TIMEOUT environment variable (for example, `MCP_TIMEOUT=10000 claude` sets a 10-second timeout)

126 * Claude Code will display a warning when MCP tool output exceeds 10,000 tokens. To increase this limit, set the `MAX_MCP_OUTPUT_TOKENS` environment variable (e.g., `MAX_MCP_OUTPUT_TOKENS=50000`)126 * Claude Code will display 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`)

127 * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication127 * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication

128</Tip>128</Tip>

129 129

209 209

210### Local scope210### Local scope

211 211

212Local-scoped servers represent the default configuration level and are stored in your project-specific user settings. These servers remain private to you and are only accessible when working within the current project directory. This scope is ideal for personal development servers, experimental configurations, or servers containing sensitive credentials that shouldn't be shared.212Local-scoped servers represent the default configuration level and are stored in `~/.claude.json` under your project's path. These servers remain private to you and are only accessible when working within the current project directory. This scope is ideal for personal development servers, experimental configurations, or servers containing sensitive credentials that shouldn't be shared.

213 213

214```bash theme={null}214```bash theme={null}

215# Add a local-scoped server (default)215# Add a local-scoped server (default)

246 246

247### User scope247### User scope

248 248

249User-scoped servers 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.249User-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.

250 250

251```bash theme={null}251```bash theme={null}

252# Add a user server252# Add a user server

259 259

260* **Local scope**: Personal servers, experimental configurations, or sensitive credentials specific to one project260* **Local scope**: Personal servers, experimental configurations, or sensitive credentials specific to one project

261* **Project scope**: Team-shared servers, project-specific tools, or services required for collaboration261* **Project scope**: Team-shared servers, project-specific tools, or services required for collaboration

262* **User scope**: Personal utilities needed across multiple projects, development tools, or frequently-used services262* **User scope**: Personal utilities needed across multiple projects, development tools, or frequently used services

263

264<Note>

265 **Where are MCP servers stored?**

266

267 * **User and local scope**: `~/.claude.json` (in the `mcpServers` field or under project paths)

268 * **Project scope**: `.mcp.json` in your project root (checked into source control)

269 * **Enterprise managed**: `managed-mcp.json` in system directories (see [Enterprise MCP configuration](#enterprise-mcp-configuration))

270</Note>

263 271

264### Scope hierarchy and precedence272### Scope hierarchy and precedence

265 273

455 * It reads the Claude Desktop configuration file from its standard location on those platforms463 * It reads the Claude Desktop configuration file from its standard location on those platforms

456 * Use the `--scope user` flag to add servers to your user configuration464 * Use the `--scope user` flag to add servers to your user configuration

457 * Imported servers will have the same names as in Claude Desktop465 * Imported servers will have the same names as in Claude Desktop

458 * If servers with the same names already exist, they will get a numerical suffix (e.g., `server_1`)466 * If servers with the same names already exist, they will get a numerical suffix (for example, `server_1`)

459</Tip>467</Tip>

460 468

461## Use Claude Code as an MCP server469## Use Claude Code as an MCP server

514 522

515 * The server provides access to Claude's tools like View, Edit, LS, etc.523 * The server provides access to Claude's tools like View, Edit, LS, etc.

516 * In Claude Desktop, try asking Claude to read files in a directory, make edits, and more.524 * In Claude Desktop, try asking Claude to read files in a directory, make edits, and more.

517 * Note that this MCP server is simply exposing Claude Code's tools to your MCP client, so your own client is responsible for implementing user confirmation for individual tool calls.525 * Note that this MCP server is only exposing Claude Code's tools to your MCP client, so your own client is responsible for implementing user confirmation for individual tool calls.

518</Tip>526</Tip>

519 527

520## MCP output limits and warnings528## MCP output limits and warnings

625 633

626## Enterprise MCP configuration634## Enterprise MCP configuration

627 635

628For organizations that need centralized control over MCP servers, Claude Code supports enterprise-managed MCP configurations. This allows IT administrators to:636For organizations that need centralized control over MCP servers, Claude Code supports two enterprise configuration options:

637

6381. **Exclusive control with `managed-mcp.json`**: Deploy a fixed set of MCP servers that users cannot modify or extend

6392. **Policy-based control with allowlists/denylists**: Allow users to add their own servers, but restrict which ones are permitted

640

641These options allow IT administrators to:

629 642

630* **Control which MCP servers employees can access**: Deploy a standardized set of approved MCP servers across the organization643* **Control which MCP servers employees can access**: Deploy a standardized set of approved MCP servers across the organization

631* **Prevent unauthorized MCP servers**: Optionally restrict users from adding their own MCP servers644* **Prevent unauthorized MCP servers**: Restrict users from adding unapproved MCP servers

632* **Disable MCP entirely**: Remove MCP functionality completely if needed645* **Disable MCP entirely**: Remove MCP functionality completely if needed

633 646

634### Setting up enterprise MCP configuration647### Option 1: Exclusive control with managed-mcp.json

648

649When you deploy a `managed-mcp.json` file, it takes **exclusive control** over all MCP servers. Users cannot add, modify, or use any MCP servers other than those defined in this file. This is the simplest approach for organizations that want complete control.

650

651System administrators deploy the configuration file to a system-wide directory:

635 652

636System administrators can deploy an enterprise MCP configuration file alongside the managed settings file:653* macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`

654* Linux and WSL: `/etc/claude-code/managed-mcp.json`

655* Windows: `C:\Program Files\ClaudeCode\managed-mcp.json`

637 656

638* **macOS**: `/Library/Application Support/ClaudeCode/managed-mcp.json`657<Note>

639* **Windows**: `C:\ProgramData\ClaudeCode\managed-mcp.json`658 These are system-wide paths (not user home directories like `~/Library/...`) that require administrator privileges. They are designed to be deployed by IT administrators.

640* **Linux**: `/etc/claude-code/managed-mcp.json`659</Note>

641 660

642The `managed-mcp.json` file uses the same format as a standard `.mcp.json` file:661The `managed-mcp.json` file uses the same format as a standard `.mcp.json` file:

643 662

664}683}

665```684```

666 685

667### Restricting MCP servers with allowlists and denylists686### Option 2: Policy-based control with allowlists and denylists

668 687

669In addition to providing enterprise-managed servers, administrators can control which MCP servers users are allowed to configure using `allowedMcpServers` and `deniedMcpServers` in the `managed-settings.json` file:688Instead of taking exclusive control, administrators can allow users to configure their own MCP servers while enforcing restrictions on which servers are permitted. This approach uses `allowedMcpServers` and `deniedMcpServers` in the [managed settings file](/en/settings#settings-files).

670 689

671* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`690<Note>

672* **Windows**: `C:\ProgramData\ClaudeCode\managed-settings.json`691 **Choosing between options**: Use Option 1 (`managed-mcp.json`) when you want to deploy a fixed set of servers with no user customization. Use Option 2 (allowlists/denylists) when you want to allow users to add their own servers within policy constraints.

673* **Linux**: `/etc/claude-code/managed-settings.json`692</Note>

693

694#### Restriction options

695

696Each entry in the allowlist or denylist can restrict servers in three ways:

697

6981. **By server name** (`serverName`): Matches the configured name of the server

6992. **By command** (`serverCommand`): Matches the exact command and arguments used to start stdio servers

7003. **By URL pattern** (`serverUrl`): Matches remote server URLs with wildcard support

701

702**Important**: Each entry must have exactly one of `serverName`, `serverCommand`, or `serverUrl`.

703

704#### Example configuration

674 705

675```json theme={null}706```json theme={null}

676{707{

677 "allowedMcpServers": [708 "allowedMcpServers": [

709 // Allow by server name

678 { "serverName": "github" },710 { "serverName": "github" },

679 { "serverName": "sentry" },711 { "serverName": "sentry" },

680 { "serverName": "company-internal" }712

713 // Allow by exact command (for stdio servers)

714 { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },

715 { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

716

717 // Allow by URL pattern (for remote servers)

718 { "serverUrl": "https://mcp.company.com/*" },

719 { "serverUrl": "https://*.internal.corp/*" }

681 ],720 ],

682 "deniedMcpServers": [721 "deniedMcpServers": [

683 { "serverName": "filesystem" }722 // Block by server name

723 { "serverName": "dangerous-server" },

724

725 // Block by exact command (for stdio servers)

726 { "serverCommand": ["npx", "-y", "unapproved-package"] },

727

728 // Block by URL pattern (for remote servers)

729 { "serverUrl": "https://*.untrusted.com/*" }

684 ]730 ]

685}731}

686```732```

687 733

688**Allowlist behavior (`allowedMcpServers`)**:734#### How command-based restrictions work

735

736**Exact matching**:

737

738* Command arrays must match **exactly** - both the command and all arguments in the correct order

739* Example: `["npx", "-y", "server"]` will NOT match `["npx", "server"]` or `["npx", "-y", "server", "--flag"]`

740

741**Stdio server behavior**:

742

743* When the allowlist contains **any** `serverCommand` entries, stdio servers **must** match one of those commands

744* Stdio servers cannot pass by name alone when command restrictions are present

745* This ensures administrators can enforce which commands are allowed to run

746

747**Non-stdio server behavior**:

748

749* Remote servers (HTTP, SSE, WebSocket) use URL-based matching when `serverUrl` entries exist in the allowlist

750* If no URL entries exist, remote servers fall back to name-based matching

751* Command restrictions do not apply to remote servers

752

753#### How URL-based restrictions work

754

755URL patterns support wildcards using `*` to match any sequence of characters. This is useful for allowing entire domains or subdomains.

756

757**Wildcard examples**:

758

759* `https://mcp.company.com/*` - Allow all paths on a specific domain

760* `https://*.example.com/*` - Allow any subdomain of example.com

761* `http://localhost:*/*` - Allow any port on localhost

762

763**Remote server behavior**:

764

765* When the allowlist contains **any** `serverUrl` entries, remote servers **must** match one of those URL patterns

766* Remote servers cannot pass by name alone when URL restrictions are present

767* This ensures administrators can enforce which remote endpoints are allowed

768

769<Accordion title="Example: URL-only allowlist">

770 ```json theme={null}

771 {

772 "allowedMcpServers": [

773 { "serverUrl": "https://mcp.company.com/*" },

774 { "serverUrl": "https://*.internal.corp/*" }

775 ]

776 }

777 ```

778

779 **Result**:

780

781 * HTTP server at `https://mcp.company.com/api`: ✅ Allowed (matches URL pattern)

782 * HTTP server at `https://api.internal.corp/mcp`: ✅ Allowed (matches wildcard subdomain)

783 * HTTP server at `https://external.com/mcp`: ❌ Blocked (doesn't match any URL pattern)

784 * Stdio server with any command: ❌ Blocked (no name or command entries to match)

785</Accordion>

786

787<Accordion title="Example: Command-only allowlist">

788 ```json theme={null}

789 {

790 "allowedMcpServers": [

791 { "serverCommand": ["npx", "-y", "approved-package"] }

792 ]

793 }

794 ```

795

796 **Result**:

797

798 * Stdio server with `["npx", "-y", "approved-package"]`: ✅ Allowed (matches command)

799 * Stdio server with `["node", "server.js"]`: ❌ Blocked (doesn't match command)

800 * HTTP server named "my-api": ❌ Blocked (no name entries to match)

801</Accordion>

802

803<Accordion title="Example: Mixed name and command allowlist">

804 ```json theme={null}

805 {

806 "allowedMcpServers": [

807 { "serverName": "github" },

808 { "serverCommand": ["npx", "-y", "approved-package"] }

809 ]

810 }

811 ```

812

813 **Result**:

814

815 * Stdio server named "local-tool" with `["npx", "-y", "approved-package"]`: ✅ Allowed (matches command)

816 * Stdio server named "local-tool" with `["node", "server.js"]`: ❌ Blocked (command entries exist but doesn't match)

817 * Stdio server named "github" with `["node", "server.js"]`: ❌ Blocked (stdio servers must match commands when command entries exist)

818 * HTTP server named "github": ✅ Allowed (matches name)

819 * HTTP server named "other-api": ❌ Blocked (name doesn't match)

820</Accordion>

821

822<Accordion title="Example: Name-only allowlist">

823 ```json theme={null}

824 {

825 "allowedMcpServers": [

826 { "serverName": "github" },

827 { "serverName": "internal-tool" }

828 ]

829 }

830 ```

831

832 **Result**:

833

834 * Stdio server named "github" with any command: ✅ Allowed (no command restrictions)

835 * Stdio server named "internal-tool" with any command: ✅ Allowed (no command restrictions)

836 * HTTP server named "github": ✅ Allowed (matches name)

837 * Any server named "other": ❌ Blocked (name doesn't match)

838</Accordion>

839

840#### Allowlist behavior (`allowedMcpServers`)

689 841

690* `undefined` (default): No restrictions - users can configure any MCP server842* `undefined` (default): No restrictions - users can configure any MCP server

691* Empty array `[]`: Complete lockdown - users cannot configure any MCP servers843* Empty array `[]`: Complete lockdown - users cannot configure any MCP servers

692* List of server names: Users can only configure the specified servers844* List of entries: Users can only configure servers that match by name, command, or URL pattern

693 845

694**Denylist behavior (`deniedMcpServers`)**:846#### Denylist behavior (`deniedMcpServers`)

695 847

696* `undefined` (default): No servers are blocked848* `undefined` (default): No servers are blocked

697* Empty array `[]`: No servers are blocked849* Empty array `[]`: No servers are blocked

698* List of server names: Specified servers are explicitly blocked across all scopes850* List of entries: Specified servers are explicitly blocked across all scopes

699 851

700**Important notes**:852#### Important notes

701 853

702* These restrictions apply to all scopes: user, project, local, and even enterprise servers from `managed-mcp.json`854* **Option 1 and Option 2 can be combined**: If `managed-mcp.json` exists, it has exclusive control and users cannot add servers. Allowlists/denylists still apply to the enterprise servers themselves.

703* **Denylist takes absolute precedence**: If a server appears in both lists, it will be blocked855* **Denylist takes absolute precedence**: If a server matches a denylist entry (by name, command, or URL), it will be blocked even if it's on the allowlist

856* Name-based, command-based, and URL-based restrictions work together: a server passes if it matches **either** a name entry, a command entry, or a URL pattern (unless blocked by denylist)

704 857

705<Note>858<Note>

706 **Enterprise configuration precedence**: The enterprise MCP configuration has the highest precedence and cannot be overridden by user, local, or project configurations.859 **When using `managed-mcp.json`**: Users cannot add MCP servers through `claude mcp add` or configuration files. The `allowedMcpServers` and `deniedMcpServers` settings still apply to filter which enterprise servers are actually loaded.

707</Note>860</Note>

861

862

863---

864

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

memory.md +134 −19

Details

9Claude Code offers four memory locations in a hierarchical structure, each serving a different purpose:9Claude Code offers four memory locations in a hierarchical structure, each serving a different purpose:

10 10

12| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |12| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |

13| **Enterprise policy** | macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br />Linux: `/etc/claude-code/CLAUDE.md`<br />Windows: `C:\ProgramData\ClaudeCode\CLAUDE.md` | Organization-wide instructions managed by IT/DevOps | Company coding standards, security policies, compliance requirements | All users in organization |13| **Enterprise policy** | • macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br />• Linux: `/etc/claude-code/CLAUDE.md`<br />• Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | Organization-wide instructions managed by IT/DevOps | Company coding standards, security policies, compliance requirements | All users in organization |

15| **Project rules** | `./.claude/rules/*.md` | Modular, topic-specific project instructions | Language-specific guidelines, testing conventions, API standards | Team members via source control |

17 18

18All memory files are automatically loaded into Claude Code's context when launched. Files higher in the hierarchy take precedence and are loaded first, providing a foundation that more specific memories build upon.19All memory files are automatically loaded into Claude Code's context when launched. Files higher in the hierarchy take precedence and are loaded first, providing a foundation that more specific memories build upon.

19 20

21<Note>

22 CLAUDE.local.md files are automatically added to .gitignore, making them ideal for private project-specific preferences that shouldn't be checked into version control.

23</Note>

20## CLAUDE.md imports25## CLAUDE.md imports

21 26

22CLAUDE.md files can import additional files using `@path/to/import` syntax. The following example imports 3 files:27CLAUDE.md files can import additional files using `@path/to/import` syntax. The following example imports 3 files:

28- git workflow @docs/git-instructions.md33- git workflow @docs/git-instructions.md

29```34```

30 35

31Both relative and absolute paths are allowed. In particular, importing files in user's home dir is a convenient way for your team members to provide individual instructions that are not checked into the repository. Previously CLAUDE.local.md served a similar purpose, but is now deprecated in favor of imports since they work better across multiple git worktrees.36Both relative and absolute paths are allowed. In particular, importing files in user's home dir is a convenient way for your team members to provide individual instructions that are not checked into the repository. Imports are an alternative to CLAUDE.local.md that work better across multiple git worktrees.

32 37

33```38```

34# Individual Preferences39# Individual Preferences

49 54

50Claude will also discover CLAUDE.md nested in subtrees under your current working directory. Instead of loading them at launch, they are only included when Claude reads files in those subtrees.55Claude will also discover CLAUDE.md nested in subtrees under your current working directory. Instead of loading them at launch, they are only included when Claude reads files in those subtrees.

51 56

~~52## Quickly add memories with the `#` shortcut~~

~~54The fastest way to add a memory is to start your input with the `#` character:~~

~~56```~~

~~57# Always use descriptive variable names~~

~~58```~~

~~60You'll be prompted to select which memory file to store this in.~~

62## Directly edit memories with `/memory`57## Directly edit memories with `/memory`

63 58

64Use the `/memory` slash command during a session to open any memory file in your system editor for more extensive additions or organization.59Use the `/memory` slash command during a session to open any memory file in your system editor for more extensive additions or organization.

82 * CLAUDE.md memories can be used for both instructions shared with your team and for your individual preferences.77 * CLAUDE.md memories can be used for both instructions shared with your team and for your individual preferences.

83</Tip>78</Tip>

84 79

80## Modular rules with `.claude/rules/`

82For larger projects, you can organize instructions into multiple files using the `.claude/rules/` directory. This allows teams to maintain focused, well-organized rule files instead of one large CLAUDE.md.

84### Basic structure

86Place markdown files in your project's `.claude/rules/` directory:

88```

89your-project/

90├── .claude/

91│ ├── CLAUDE.md # Main project instructions

92│ └── rules/

93│ ├── code-style.md # Code style guidelines

94│ ├── testing.md # Testing conventions

95│ └── security.md # Security requirements

96```

98All `.md` files in `.claude/rules/` are automatically loaded as project memory, with the same priority as `.claude/CLAUDE.md`.

100### Path-specific rules

101

102Rules can be scoped to specific files using YAML frontmatter with the `paths` field. These conditional rules only apply when Claude is working with files matching the specified patterns.

103

104```markdown theme={null}

105---

106paths: src/api/**/*.ts

107---

108

109# API Development Rules

110

111- All API endpoints must include input validation

112- Use the standard error response format

113- Include OpenAPI documentation comments

114```

115

116Rules without a `paths` field are loaded unconditionally and apply to all files.

117

118### Glob patterns

119

120The `paths` field supports standard glob patterns:

121

122| Pattern | Matches |

123| ---------------------- | ---------------------------------------- |

124| `**/*.ts` | All TypeScript files in any directory |

125| `src/**/*` | All files under `src/` directory |

126| `*.md` | Markdown files in the project root |

127| `src/components/*.tsx` | React components in a specific directory |

128

129You can use braces to match multiple patterns efficiently:

130

131```markdown theme={null}

132---

133paths: src/**/*.{ts,tsx}

134---

135

136# TypeScript/React Rules

137```

138

139This expands to match both `src/**/*.ts` and `src/**/*.tsx`. You can also combine multiple patterns with commas:

140

141```markdown theme={null}

142---

143paths: {src,lib}/**/*.ts, tests/**/*.test.ts

144---

145```

146

147### Subdirectories

148

149Rules can be organized into subdirectories for better structure:

150

151```

152.claude/rules/

153├── frontend/

154│ ├── react.md

155│ └── styles.md

156├── backend/

157│ ├── api.md

158│ └── database.md

159└── general.md

160```

161

162All `.md` files are discovered recursively.

163

164### Symlinks

165

166The `.claude/rules/` directory supports symlinks, allowing you to share common rules across multiple projects:

167

168```bash theme={null}

169# Symlink a shared rules directory

170ln -s ~/shared-claude-rules .claude/rules/shared

171

172# Symlink individual rule files

173ln -s ~/company-standards/security.md .claude/rules/security.md

174```

175

176Symlinks are resolved and their contents are loaded normally. Circular symlinks are detected and handled gracefully.

177

178### User-level rules

179

180You can create personal rules that apply to all your projects in `~/.claude/rules/`:

181

182```

183~/.claude/rules/

184├── preferences.md # Your personal coding preferences

185└── workflows.md # Your preferred workflows

186```

187

188User-level rules are loaded before project rules, giving project rules higher priority.

189

190<Tip>

191 Best practices for `.claude/rules/`:

192

193 * **Keep rules focused**: Each file should cover one topic (e.g., `testing.md`, `api-design.md`)

194 * **Use descriptive filenames**: The filename should indicate what the rules cover

195 * **Use conditional rules sparingly**: Only add `paths` frontmatter when rules truly apply to specific file types

196 * **Organize with subdirectories**: Group related rules (e.g., `frontend/`, `backend/`)

197</Tip>

198

85## Organization-level memory management199## Organization-level memory management

86 200

87Enterprise organizations can deploy centrally managed CLAUDE.md files that apply to all users.201Enterprise organizations can deploy centrally managed CLAUDE.md files that apply to all users.

88 202

89To set up organization-level memory management:203To set up organization-level memory management:

90 204

~~911. Create the enterprise memory file in the appropriate location for your operating system:~~2051. Create the enterprise memory file at the **Enterprise policy** location shown in the [memory types table above](#determine-memory-type).

~~93* macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`~~

~~94* Linux/WSL: `/etc/claude-code/CLAUDE.md`~~

~~95* Windows: `C:\ProgramData\ClaudeCode\CLAUDE.md`~~

96 206

972. Deploy via your configuration management system (MDM, Group Policy, Ansible, etc.) to ensure consistent distribution across all developer machines.2072. Deploy via your configuration management system (MDM, Group Policy, Ansible, etc.) to ensure consistent distribution across all developer machines.

98 208

101* **Be specific**: "Use 2-space indentation" is better than "Format code properly".211* **Be specific**: "Use 2-space indentation" is better than "Format code properly".

102* **Use structure to organize**: Format each individual memory as a bullet point and group related memories under descriptive markdown headings.212* **Use structure to organize**: Format each individual memory as a bullet point and group related memories under descriptive markdown headings.

103* **Review periodically**: Update memories as your project evolves to ensure Claude is always using the most up to date information and context.213* **Review periodically**: Update memories as your project evolves to ensure Claude is always using the most up to date information and context.

214

215

216---

217

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

microsoft-foundry.md +112 −0 added

Details

1# Claude Code on Microsoft Foundry

3> Learn about configuring Claude Code through Microsoft Foundry, including setup, configuration, and troubleshooting.

5## Prerequisites

7Before configuring Claude Code with Microsoft Foundry, ensure you have:

9* An Azure subscription with access to Microsoft Foundry

10* RBAC permissions to create Microsoft Foundry resources and deployments

11* Azure CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)

13## Setup

15### 1. Provision Microsoft Foundry resource

17First, create a Claude resource in Azure:

191. Navigate to the [Microsoft Foundry portal](https://ai.azure.com/)

202. Create a new resource, noting your resource name

213. Create deployments for the Claude models:

22 * Claude Opus

23 * Claude Sonnet

24 * Claude Haiku

26### 2. Configure Azure credentials

28Claude Code supports two authentication methods for Microsoft Foundry. Choose the method that best fits your security requirements.

30**Option A: API key authentication**

321. Navigate to your resource in the Microsoft Foundry portal

332. Go to the **Endpoints and keys** section

343. Copy **API Key**

354. Set the environment variable:

37```bash theme={null}

38export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key

39```

41**Option B: Microsoft Entra ID authentication**

43When `ANTHROPIC_FOUNDRY_API_KEY` is not set, Claude Code automatically uses the Azure SDK [default credential chain](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview).

44This supports a variety of methods for authenticating local and remote workloads.

46On local environments, you commonly may use the Azure CLI:

48```bash theme={null}

49az login

50```

52<Note>

53 When using Microsoft Foundry, the `/login` and `/logout` commands are disabled since authentication is handled through Azure credentials.

54</Note>

56### 3. Configure Claude Code

58Set the following environment variables to enable Microsoft Foundry. Note that your deployments' names are set as the model identifiers in Claude Code (may be optional if using suggested deployment names).

60```bash theme={null}

61# Enable Microsoft Foundry integration

62export CLAUDE_CODE_USE_FOUNDRY=1

64# Azure resource name (replace {resource} with your resource name)

65export ANTHROPIC_FOUNDRY_RESOURCE={resource}

66# Or provide the full base URL:

67# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com

69# Set models to your resource's deployment names

70export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-5'

71export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

72export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-1'

73```

75For more details on model configuration options, see [Model configuration](/en/model-config).

77## Azure RBAC configuration

79The `Azure AI User` and `Cognitive Services User` default roles include all required permissions for invoking Claude models.

81For more restrictive permissions, create a custom role with the following:

83```json theme={null}

84{

85 "permissions": [

86 {

87 "dataActions": [

88 "Microsoft.CognitiveServices/accounts/providers/*"

89 ]

90 }

91 ]

92}

93```

95For details, see [Microsoft Foundry RBAC documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/rbac-azure-ai-foundry).

97## Troubleshooting

99If you receive an error "Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed":

100

101* Configure Entra ID on the environment, or set `ANTHROPIC_FOUNDRY_API_KEY`.

102

103## Additional resources

104

105* [Microsoft Foundry documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-azure-ai-foundry)

106* [Microsoft Foundry models](https://ai.azure.com/explore/models)

107* [Microsoft Foundry pricing](https://azure.microsoft.com/en-us/pricing/details/ai-foundry/)

108

109

110---

111

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

model-config.md +20 −12

Details

4 4

5## Available models5## Available models

6 6

~~7For the `model` setting in Claude Code, you can either configure:~~7For the `model` setting in Claude Code, you can configure either:

8 8

9* A **model alias**9* A **model alias**

~~10* A full **[model name](/en/docs/about-claude/models/overview#model-names)**~~10* A **model name**

~~11* For Bedrock, an ARN~~11 * Anthropic API: A full **[model name](https://docs.claude.com/en/docs/about-claude/models/overview#model-names)**

12 * Bedrock: an inference profile ARN

13 * Foundry: a deployment name

14 * Vertex: a version name

12 15

13### Model aliases16### Model aliases

14 17

16remembering exact version numbers:19remembering exact version numbers:

17 20

18| Model alias | Behavior |21| Model alias | Behavior |

~~19| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |~~22| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

20| **`default`** | Recommended model setting, depending on your account type |23| **`default`** | Recommended model setting, depending on your account type |

21| **`sonnet`** | Uses the latest Sonnet model (currently Sonnet 4.5) for daily coding tasks |24| **`sonnet`** | Uses the latest Sonnet model (currently Sonnet 4.5) for daily coding tasks |

23| **`haiku`** | Uses the fast and efficient Haiku model for simple tasks |26| **`haiku`** | Uses the fast and efficient Haiku model for simple tasks |

~~24| **`sonnet[1m]`** | Uses Sonnet with a [1 million token context window](/en/docs/build-with-claude/context-windows#1m-token-context-window) window for long sessions |~~27| **`sonnet[1m]`** | Uses Sonnet with a [1 million token context window](https://docs.claude.com/en/docs/build-with-claude/context-windows#1m-token-context-window) window for long sessions |

25| **`opusplan`** | Special mode that uses `opus` during plan mode, then switches to `sonnet` for execution |28| **`opusplan`** | Special mode that uses `opus` during plan mode, then switches to `sonnet` for execution |

26 29

27### Setting your model30### Setting your model

80 83

81For Console/API users, the `[1m]` suffix can be added to full model names to84For Console/API users, the `[1m]` suffix can be added to full model names to

82enable a85enable a

~~83[1 million token context window](/en/docs/build-with-claude/context-windows#1m-token-context-window).~~86[1 million token context window](https://docs.claude.com/en/docs/build-with-claude/context-windows#1m-token-context-window).

84 87

85```bash theme={null}88```bash theme={null}

86# Example of using a full model name with the [1m] suffix89# Example of using a full model name with the [1m] suffix

88```91```

89 92

90Note: Extended context models have93Note: Extended context models have

~~91[different pricing](/en/docs/about-claude/pricing#long-context-pricing).~~94[different pricing](https://docs.claude.com/en/docs/about-claude/pricing#long-context-pricing).

92 95

93## Checking your current model96## Checking your current model

94 97

100## Environment variables103## Environment variables

101 104

102You can use the following environment variables, which must be full **model105You can use the following environment variables, which must be full **model

103names**, to control the model names that the aliases map to.106names** (or equivalent for your API provider), to control the model names that the aliases map to.

104 107

105| Env var | Description |108| Environment variable | Description |

106| -------------------------------- | --------------------------------------------------------------------------------------------- |109| -------------------------------- | --------------------------------------------------------------------------------------------- |

114 117

115### Prompt caching configuration118### Prompt caching configuration

116 119

117Claude Code automatically uses [prompt caching](/en/docs/build-with-claude/prompt-caching) to optimize performance and reduce costs. You can disable prompt caching globally or for specific model tiers:120Claude Code automatically uses [prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching) to optimize performance and reduce costs. You can disable prompt caching globally or for specific model tiers:

118 121

119| Env var | Description |122| Environment variable | Description |

120| ------------------------------- | ---------------------------------------------------------------------------------------------- |123| ------------------------------- | ---------------------------------------------------------------------------------------------- |

121| `DISABLE_PROMPT_CACHING` | Set to `1` to disable prompt caching for all models (takes precedence over per-model settings) |124| `DISABLE_PROMPT_CACHING` | Set to `1` to disable prompt caching for all models (takes precedence over per-model settings) |

125 128

126These environment variables give you fine-grained control over prompt caching behavior. The global `DISABLE_PROMPT_CACHING` setting takes precedence over the model-specific settings, allowing you to quickly disable all caching when needed. The per-model settings are useful for selective control, such as when debugging specific models or working with cloud providers that may have different caching implementations.129These environment variables give you fine-grained control over prompt caching behavior. The global `DISABLE_PROMPT_CACHING` setting takes precedence over the model-specific settings, allowing you to quickly disable all caching when needed. The per-model settings are useful for selective control, such as when debugging specific models or working with cloud providers that may have different caching implementations.

130

131

132---

133

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

monitoring-usage.md +67 −73

Details

6 6

7All metrics are time series data exported via OpenTelemetry's standard metrics protocol, and events are exported via OpenTelemetry's logs/events protocol. It is the user's responsibility to ensure their metrics and logs backends are properly configured and that the aggregation granularity meets their monitoring requirements.7All metrics are time series data exported via OpenTelemetry's standard metrics protocol, and events are exported via OpenTelemetry's logs/events protocol. It is the user's responsibility to ensure their metrics and logs backends are properly configured and that the aggregation granularity meets their monitoring requirements.

8 8

~~9<Note>~~9## Quick start

~~10 OpenTelemetry support is currently in beta and details are subject to change.~~

~~11</Note>~~

~~13## Quick Start~~

14 10

15Configure OpenTelemetry using environment variables:11Configure OpenTelemetry using environment variables:

16 12

43 39

44For full configuration options, see the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options).40For full configuration options, see the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options).

45 41

~~46## Administrator Configuration~~42## Administrator configuration

48Administrators can configure OpenTelemetry settings for all users through the managed settings file. This allows for centralized control of telemetry settings across an organization. See the [settings precedence](/en/settings#settings-precedence) for more information about how settings are applied.

~~50The managed settings file is located at:~~

51 43

~~52* macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`~~44Administrators can configure OpenTelemetry settings for all users through the [managed settings file](/en/settings#settings-files). This allows for centralized control of telemetry settings across an organization. See the [settings precedence](/en/settings#settings-precedence) for more information about how settings are applied.

~~53* Linux and WSL: `/etc/claude-code/managed-settings.json`~~

~~54* Windows: `C:\ProgramData\ClaudeCode\managed-settings.json`~~

55 45

56Example managed settings configuration:46Example managed settings configuration:

57 47

72 Managed settings can be distributed via MDM (Mobile Device Management) or other device management solutions. Environment variables defined in the managed settings file have high precedence and cannot be overridden by users.62 Managed settings can be distributed via MDM (Mobile Device Management) or other device management solutions. Environment variables defined in the managed settings file have high precedence and cannot be overridden by users.

73</Note>63</Note>

74 64

~~75## Configuration Details~~65## Configuration details

76 66

~~77### Common Configuration Variables~~67### Common configuration variables

78 68

~~80| ----------------------------------------------- | --------------------------------------------------------- | ------------------------------------ |~~70| ----------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------ |

81| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1` |71| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1` |

93| `OTEL_METRIC_EXPORT_INTERVAL` | Export interval in milliseconds (default: 60000) | `5000`, `60000` |83| `OTEL_METRIC_EXPORT_INTERVAL` | Export interval in milliseconds (default: 60000) | `5000`, `60000` |

94| `OTEL_LOGS_EXPORT_INTERVAL` | Logs export interval in milliseconds (default: 5000) | `1000`, `10000` |84| `OTEL_LOGS_EXPORT_INTERVAL` | Logs export interval in milliseconds (default: 5000) | `1000`, `10000` |

86| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic headers (default: 1740000ms / 29 minutes) | `900000` |

96 87

~~97### Metrics Cardinality Control~~88### Metrics cardinality control

98 89

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

100 91

106 97

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

108 99

109### Dynamic Headers100### Dynamic headers

110 101

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

112 103

113#### Settings Configuration104#### Settings configuration

114 105

115Add to your `.claude/settings.json`:106Add to your `.claude/settings.json`:

116 107

120}111}

121```112```

122 113

123#### Script Requirements114#### Script requirements

124 115

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

126 117

130echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"121echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

131```122```

132 123

133#### Important Limitations124#### Refresh behavior

134 125

135**Headers are fetched only at startup, not during runtime.** This is due to OpenTelemetry exporter architecture limitations.126The headers helper script runs at startup and periodically thereafter to support token refresh. By default, the script runs every 29 minutes. Customize the interval with the `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` environment variable.

136 127

137For scenarios requiring frequent token refresh, use an OpenTelemetry Collector as a proxy that can refresh its own headers.128### Multi-team organization support

~~138~~

139### Multi-Team Organization Support

140 129

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

142 131

176 export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"165 export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

177 ```166 ```

178 167

179 Note: Quoting the entire key=value pair (e.g., `"key=value with spaces"`) is not supported by the OpenTelemetry specification and will result in attributes being prefixed with quotes.168 Note: wrapping values in quotes doesn't escape spaces. For example, `org.name="My Company"` results in the literal value `"My Company"` (with quotes included), not `My Company`.

180</Warning>169</Warning>

181 170

182### Example Configurations171### Example configurations

183 172

184```bash theme={null}173```bash theme={null}

185# Console debugging (1-second intervals)174# Console debugging (1-second intervals)

224export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317213export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

225```214```

226 215

227## Available Metrics and Events216## Available metrics and events

228 217

229### Standard Attributes218### Standard attributes

230 219

231All metrics and events share these standard attributes:220All metrics and events share these standard attributes:

232 221

234| ------------------- | ------------------------------------------------------------- | --------------------------------------------------- |223| ------------------- | -------------------------------------------------------------------- | --------------------------------------------------- |

240 229

241### Metrics230### Metrics

242 231

254| `claude_code.active_time.total` | Total active time in seconds | s |243| `claude_code.active_time.total` | Total active time in seconds | s |

255 244

256### Metric Details245### Metric details

257 246

258#### Session Counter247#### Session counter

259 248

260Incremented at the start of each session.249Incremented at the start of each session.

261 250

263 252

264* All [standard attributes](#standard-attributes)253* All [standard attributes](#standard-attributes)

265 254

266#### Lines of Code Counter255#### Lines of code counter

267 256

268Incremented when code is added or removed.257Incremented when code is added or removed.

269 258

272* All [standard attributes](#standard-attributes)261* All [standard attributes](#standard-attributes)

273* `type`: (`"added"`, `"removed"`)262* `type`: (`"added"`, `"removed"`)

274 263

275#### Pull Request Counter264#### Pull request counter

276 265

277Incremented when creating pull requests via Claude Code.266Incremented when creating pull requests via Claude Code.

278 267

280 269

281* All [standard attributes](#standard-attributes)270* All [standard attributes](#standard-attributes)

282 271

283#### Commit Counter272#### Commit counter

284 273

285Incremented when creating git commits via Claude Code.274Incremented when creating git commits via Claude Code.

286 275

288 277

289* All [standard attributes](#standard-attributes)278* All [standard attributes](#standard-attributes)

290 279

291#### Cost Counter280#### Cost counter

292 281

293Incremented after each API request.282Incremented after each API request.

294 283

295**Attributes**:284**Attributes**:

296 285

297* All [standard attributes](#standard-attributes)286* All [standard attributes](#standard-attributes)

298* `model`: Model identifier (e.g., "claude-sonnet-4-5-20250929")287* `model`: Model identifier (for example, "claude-sonnet-4-5-20250929")

299 288

300#### Token Counter289#### Token counter

301 290

302Incremented after each API request.291Incremented after each API request.

303 292

305 294

306* All [standard attributes](#standard-attributes)295* All [standard attributes](#standard-attributes)

307* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)296* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)

308* `model`: Model identifier (e.g., "claude-sonnet-4-5-20250929")297* `model`: Model identifier (for example, "claude-sonnet-4-5-20250929")

309 298

310#### Code Edit Tool Decision Counter299#### Code edit tool decision counter

311 300

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

313 302

316* All [standard attributes](#standard-attributes)305* All [standard attributes](#standard-attributes)

317* `tool`: Tool name (`"Edit"`, `"Write"`, `"NotebookEdit"`)306* `tool`: Tool name (`"Edit"`, `"Write"`, `"NotebookEdit"`)

318* `decision`: User decision (`"accept"`, `"reject"`)307* `decision`: User decision (`"accept"`, `"reject"`)

319* `language`: Programming language of the edited file (e.g., `"TypeScript"`, `"Python"`, `"JavaScript"`, `"Markdown"`). Returns `"unknown"` for unrecognized file extensions.308* `language`: Programming language of the edited file (for example, `"TypeScript"`, `"Python"`, `"JavaScript"`, `"Markdown"`). Returns `"unknown"` for unrecognized file extensions.

320 309

321#### Active Time Counter310#### Active time counter

322 311

323Tracks actual time spent actively using Claude Code (not idle time). This metric is incremented during user interactions such as typing prompts or receiving responses.312Tracks actual time spent actively using Claude Code (not idle time). This metric is incremented during user interactions such as typing prompts or receiving responses.

324 313

330 319

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

332 321

333#### User Prompt Event322#### User prompt event

334 323

335Logged when a user submits a prompt.324Logged when a user submits a prompt.

336 325

344* `prompt_length`: Length of the prompt333* `prompt_length`: Length of the prompt

345* `prompt`: Prompt content (redacted by default, enable with `OTEL_LOG_USER_PROMPTS=1`)334* `prompt`: Prompt content (redacted by default, enable with `OTEL_LOG_USER_PROMPTS=1`)

346 335

347#### Tool Result Event336#### Tool result event

348 337

349Logged when a tool completes execution.338Logged when a tool completes execution.

350 339

364* `tool_parameters`: JSON string containing tool-specific parameters (when available)353* `tool_parameters`: JSON string containing tool-specific parameters (when available)

365 * For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `sandbox`354 * For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `sandbox`

366 355

367#### API Request Event356#### API request event

368 357

369Logged for each API request to Claude.358Logged for each API request to Claude.

370 359

375* All [standard attributes](#standard-attributes)364* All [standard attributes](#standard-attributes)

376* `event.name`: `"api_request"`365* `event.name`: `"api_request"`

377* `event.timestamp`: ISO 8601 timestamp366* `event.timestamp`: ISO 8601 timestamp

378* `model`: Model used (e.g., "claude-sonnet-4-5-20250929")367* `model`: Model used (for example, "claude-sonnet-4-5-20250929")

379* `cost_usd`: Estimated cost in USD368* `cost_usd`: Estimated cost in USD

380* `duration_ms`: Request duration in milliseconds369* `duration_ms`: Request duration in milliseconds

381* `input_tokens`: Number of input tokens370* `input_tokens`: Number of input tokens

383* `cache_read_tokens`: Number of tokens read from cache372* `cache_read_tokens`: Number of tokens read from cache

384* `cache_creation_tokens`: Number of tokens used for cache creation373* `cache_creation_tokens`: Number of tokens used for cache creation

385 374

386#### API Error Event375#### API error event

387 376

388Logged when an API request to Claude fails.377Logged when an API request to Claude fails.

389 378

394* All [standard attributes](#standard-attributes)383* All [standard attributes](#standard-attributes)

395* `event.name`: `"api_error"`384* `event.name`: `"api_error"`

396* `event.timestamp`: ISO 8601 timestamp385* `event.timestamp`: ISO 8601 timestamp

397* `model`: Model used (e.g., "claude-sonnet-4-5-20250929")386* `model`: Model used (for example, "claude-sonnet-4-5-20250929")

398* `error`: Error message387* `error`: Error message

399* `status_code`: HTTP status code (if applicable)388* `status_code`: HTTP status code (if applicable)

400* `duration_ms`: Request duration in milliseconds389* `duration_ms`: Request duration in milliseconds

401* `attempt`: Attempt number (for retried requests)390* `attempt`: Attempt number (for retried requests)

402 391

403#### Tool Decision Event392#### Tool decision event

404 393

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

406 395

411* All [standard attributes](#standard-attributes)400* All [standard attributes](#standard-attributes)

412* `event.name`: `"tool_decision"`401* `event.name`: `"tool_decision"`

413* `event.timestamp`: ISO 8601 timestamp402* `event.timestamp`: ISO 8601 timestamp

414* `tool_name`: Name of the tool (e.g., "Read", "Edit", "Write", "NotebookEdit", etc.)403* `tool_name`: Name of the tool (for example, "Read", "Edit", "Write", "NotebookEdit")

415* `decision`: Either `"accept"` or `"reject"`404* `decision`: Either `"accept"` or `"reject"`

416* `source`: Decision source - `"config"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`405* `source`: Decision source - `"config"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`

417 406

418## Interpreting Metrics and Events Data407## Interpreting metrics and events data

419 408

420The metrics exported by Claude Code provide valuable insights into usage patterns and productivity. Here are some common visualizations and analyses you can create:409The metrics exported by Claude Code provide valuable insights into usage patterns and productivity. Here are some common visualizations and analyses you can create:

421 410

422### Usage Monitoring411### Usage monitoring

423 412

424| Metric | Analysis Opportunity |413| Metric | Analysis Opportunity |

425| ------------------------------------------------------------- | --------------------------------------------------------- |414| ------------------------------------------------------------- | --------------------------------------------------------- |

430 419

431### Cost Monitoring420### Cost monitoring

432 421

433The `claude_code.cost.usage` metric helps with:422The `claude_code.cost.usage` metric helps with:

434 423

439 Cost metrics are approximations. For official billing data, refer to your API provider (Claude Console, AWS Bedrock, or Google Cloud Vertex).428 Cost metrics are approximations. For official billing data, refer to your API provider (Claude Console, AWS Bedrock, or Google Cloud Vertex).

440</Note>429</Note>

441 430

442### Alerting and Segmentation431### Alerting and segmentation

443 432

444Common alerts to consider:433Common alerts to consider:

445 434

449 438

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

451 440

452### Event Analysis441### Event analysis

453 442

454The event data provides detailed insights into Claude Code interactions:443The event data provides detailed insights into Claude Code interactions:

455 444

456**Tool Usage Patterns**: Analyze tool result events to identify:445**Tool Usage Patterns**: analyze tool result events to identify:

457 446

458* Most frequently used tools447* Most frequently used tools

459* Tool success rates448* Tool success rates

460* Average tool execution times449* Average tool execution times

461* Error patterns by tool type450* Error patterns by tool type

462 451

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

464 453

465## Backend Considerations454## Backend considerations

466 455

467Your choice of metrics and logs backends will determine the types of analyses you can perform:456Your choice of metrics and logs backends determines the types of analyses you can perform:

468 457

469### For Metrics:458### For metrics

470 459

471* **Time series databases (e.g., Prometheus)**: Rate calculations, aggregated metrics460* **Time series databases (for example, Prometheus)**: Rate calculations, aggregated metrics

472* **Columnar stores (e.g., ClickHouse)**: Complex queries, unique user analysis461* **Columnar stores (for example, ClickHouse)**: Complex queries, unique user analysis

473* **Full-featured observability platforms (e.g., Honeycomb, Datadog)**: Advanced querying, visualization, alerting462* **Full-featured observability platforms (for example, Honeycomb, Datadog)**: Advanced querying, visualization, alerting

474 463

475### For Events/Logs:464### For events/logs

476 465

477* **Log aggregation systems (e.g., Elasticsearch, Loki)**: Full-text search, log analysis466* **Log aggregation systems (for example, Elasticsearch, Loki)**: Full-text search, log analysis

478* **Columnar stores (e.g., ClickHouse)**: Structured event analysis467* **Columnar stores (for example, ClickHouse)**: Structured event analysis

479* **Full-featured observability platforms (e.g., Honeycomb, Datadog)**: Correlation between metrics and events468* **Full-featured observability platforms (for example, Honeycomb, Datadog)**: Correlation between metrics and events

480 469

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

482 471

483## Service Information472## Service information

484 473

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

486 475

487* `service.name`: `claude-code`476* `service.name`: `claude-code`

488* `service.version`: Current Claude Code version477* `service.version`: Current Claude Code version

489* `os.type`: Operating system type (e.g., `linux`, `darwin`, `windows`)478* `os.type`: Operating system type (for example, `linux`, `darwin`, `windows`)

490* `os.version`: Operating system version string479* `os.version`: Operating system version string

491* `host.arch`: Host architecture (e.g., `amd64`, `arm64`)480* `host.arch`: Host architecture (for example, `amd64`, `arm64`)

492* `wsl.version`: WSL version number (only present when running on Windows Subsystem for Linux)481* `wsl.version`: WSL version number (only present when running on Windows Subsystem for Linux)

493* Meter Name: `com.anthropic.claude_code`482* Meter Name: `com.anthropic.claude_code`

494 483

495## ROI Measurement Resources484## ROI measurement resources

496 485

497For a comprehensive guide on measuring return on investment for Claude Code, including telemetry setup, cost analysis, productivity metrics, and automated reporting, see the [Claude Code ROI Measurement Guide](https://github.com/anthropics/claude-code-monitoring-guide). This repository provides ready-to-use Docker Compose configurations, Prometheus and OpenTelemetry setups, and templates for generating productivity reports integrated with tools like Linear.486For a comprehensive guide on measuring return on investment for Claude Code, including telemetry setup, cost analysis, productivity metrics, and automated reporting, see the [Claude Code ROI Measurement Guide](https://github.com/anthropics/claude-code-monitoring-guide). This repository provides ready-to-use Docker Compose configurations, Prometheus and OpenTelemetry setups, and templates for generating productivity reports integrated with tools like Linear.

498 487

499## Security/Privacy Considerations488## Security/privacy considerations

500 489

501* Telemetry is opt-in and requires explicit configuration490* Telemetry is opt-in and requires explicit configuration

502* Sensitive information like API keys or file contents are never included in metrics or events491* Sensitive information like API keys or file contents are never included in metrics or events

505## Monitoring Claude Code on Amazon Bedrock494## Monitoring Claude Code on Amazon Bedrock

506 495

507For detailed Claude Code usage monitoring guidance for Amazon Bedrock, see [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md).496For detailed Claude Code usage monitoring guidance for Amazon Bedrock, see [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md).

497

498

499---

500

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

network-config.md +5 −0

Details

88* [Claude Code settings](/en/settings)88* [Claude Code settings](/en/settings)

89* [Environment variables reference](/en/settings#environment-variables)89* [Environment variables reference](/en/settings#environment-variables)

90* [Troubleshooting guide](/en/troubleshooting)90* [Troubleshooting guide](/en/troubleshooting)

93---

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

output-styles.md +31 −16

Details

27 27

28Output styles directly modify Claude Code's system prompt.28Output styles directly modify Claude Code's system prompt.

29 29

~~30* Non-default output styles exclude instructions specific to code generation and~~30* All output styles exclude instructions for efficient output (such as

~~31 efficient output normally built into Claude Code (such as responding concisely~~31 responding concisely).

~~32 and verifying code with tests).~~32* Custom output styles exclude instructions for coding (such as verifying code

~~33* Instead, these output styles have their own custom instructions added to the~~33 with tests), unless `keep-coding-instructions` is true.

34* All output styles have their own custom instructions added to the end of the

34 system prompt.35 system prompt.

36* All output styles trigger reminders for Claude to adhere to the output style

37 instructions during the conversation.

35 38

36## Change your output style39## Change your output style

37 40

38You can either:41You can either:

39 42

~~40* Run `/output-style` to access the menu and select your output style (this can~~43* Run `/output-style` to access a menu and select your output style (this can

41 also be accessed from the `/config` menu)44 also be accessed from the `/config` menu)

42 45

43* Run `/output-style [style]`, such as `/output-style explanatory`, to directly46* Run `/output-style [style]`, such as `/output-style explanatory`, to directly

44 switch to a style47 switch to a style

45 48

~~46These changes apply to the [local project level](/en/settings)~~49These changes apply to the [local project level](/en/settings) and are saved in

~~47and are saved in `.claude/settings.local.json`.~~50`.claude/settings.local.json`. You can also directly edit the `outputStyle`

51field in a settings file at a different level.

48 52

49## Create a custom output style53## Create a custom output style

50 54

~~51To set up a new output style with Claude's help, run~~55Custom output styles are Markdown files with frontmatter and the text that will

~~52`/output-style:new I want an output style that ...`~~56be added to the system prompt:

~~54By default, output styles created through `/output-style:new` are saved as~~

~~55markdown files at the user level in `~/.claude/output-styles` and can be used~~

~~56across projects. They have the following structure:~~

57 57

58```markdown theme={null}58```markdown theme={null}

59---59---

72[Define how the assistant should behave in this style...]72[Define how the assistant should behave in this style...]

73```73```

74 74

~~75You can also create your own output style Markdown files and save them either at~~75You can save these files at the user level (`~/.claude/output-styles`) or

~~76the user level (`~/.claude/output-styles`) or the project level~~76project level (`.claude/output-styles`).

~~77(`.claude/output-styles`).~~77

78### Frontmatter

80Output style files support frontmatter, useful for specifying metadata about the

81command:

83| Frontmatter | Purpose | Default |

84| :------------------------- | :-------------------------------------------------------------------------- | :---------------------- |

85| `name` | Name of the output style, if not the file name | Inherits from file name |

86| `description` | Description of the output style. Used only in the UI of `/output-style` | None |

87| `keep-coding-instructions` | Whether to keep the parts of Claude Code's system prompt related to coding. | false |

78 88

79## Comparisons to related features89## Comparisons to related features

80 90

97 107

98You can think of output styles as "stored system prompts" and custom slash108You can think of output styles as "stored system prompts" and custom slash

99commands as "stored prompts".109commands as "stored prompts".

110

111

112---

113

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

overview.md +43 −28

Details

10 10

11**Install Claude Code:**11**Install Claude Code:**

12 12

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

13<Tabs>15<Tabs>

~~14 <Tab title="macOS/Linux">~~16 <Tab title="Native Install (Recommended)">

17 **macOS, Linux, WSL:**

15 ```bash theme={null}19 ```bash theme={null}

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

17 ```21 ```

~~18 </Tab>~~

19 22

~~20 <Tab title="Homebrew">~~23 **Windows PowerShell:**

~~21 ```bash theme={null}~~

~~22 brew install --cask claude-code~~

~~23 ```~~

~~24 </Tab>~~

25 24

~~26 <Tab title="Windows">~~

27 ```powershell theme={null}25 ```powershell theme={null}

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

29 ```27 ```

29 **Windows CMD:**

31 ```batch theme={null}

32 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

33 ```

34 </Tab>

36 <Tab title="Homebrew">

37 ```sh theme={null}

38 brew install --cask claude-code

39 ```

30 </Tab>40 </Tab>

31 41

32 <Tab title="NPM">42 <Tab title="NPM">

~~33 ```bash theme={null}~~43 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):

45 ```sh theme={null}

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

35 ```47 ```

~~37 Requires [Node.js 18+](https://nodejs.org/en/download/)~~

38 </Tab>48 </Tab>

39</Tabs>49</Tabs>

40 50

45claude55claude

46```56```

47 57

~~48You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 mins) →](/en/quickstart)~~58You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 minutes) →](/en/quickstart)

49 59

50<Tip>60<Tip>

~~51 See [advanced setup](/en/setup) for installation options or [troubleshooting](/en/troubleshooting) if you hit issues.~~61 Claude Code automatically keeps itself up to date. See [advanced setup](/en/setup) for installation options, manual updates, or uninstallation instructions. Visit [troubleshooting](/en/troubleshooting) if you hit issues.

52</Tip>62</Tip>

53 63

~~54<Note>~~

55 **New VS Code Extension (Beta)**: Prefer a graphical interface? Our new [VS Code extension](/en/vs-code) provides an easy-to-use native IDE experience without requiring terminal familiarity. Simply install from the marketplace and start coding with Claude directly in your sidebar.

~~56</Note>~~

58## What Claude Code does for you64## What Claude Code does for you

59 65

60* **Build features from descriptions**: Tell Claude what you want to build in plain English. It will make a plan, write the code, and ensure it works.66* **Build features from descriptions**: Tell Claude what you want to build in plain English. It will make a plan, write the code, and ensure it works.

61* **Debug and fix issues**: Describe a bug or paste an error message. Claude Code will analyze your codebase, identify the problem, and implement a fix.67* **Debug and fix issues**: Describe a bug or paste an error message. Claude Code will analyze your codebase, identify the problem, and implement a fix.

62* **Navigate any codebase**: Ask anything about your team's codebase, and get a thoughtful answer back. Claude Code maintains awareness of your entire project structure, can find up-to-date information from the web, and with [MCP](/en/mcp) can pull from external datasources like Google Drive, Figma, and Slack.68* **Navigate any codebase**: Ask anything about your team's codebase, and get a thoughtful answer back. Claude Code maintains awareness of your entire project structure, can find up-to-date information from the web, and with [MCP](/en/mcp) can pull from external data sources like Google Drive, Figma, and Slack.

63* **Automate tedious tasks**: Fix fiddly lint issues, resolve merge conflicts, and write release notes. Do all this in a single command from your developer machines, or automatically in CI.69* **Automate tedious tasks**: Fix fiddly lint issues, resolve merge conflicts, and write release notes. Do all this in a single command from your developer machines, or automatically in CI.

64 70

65## Why developers love Claude Code71## Why developers love Claude Code

72## Next steps78## Next steps

73 79

74<CardGroup>80<CardGroup>

~~75 <Card title="Quickstart" icon="rocket" href="/en/docs/claude-code/quickstart">~~81 <Card title="Quickstart" icon="rocket" href="/en/quickstart">

76 See Claude Code in action with practical examples82 See Claude Code in action with practical examples

77 </Card>83 </Card>

78 84

~~79 <Card title="Common workflows" icon="graduation-cap" href="/en/docs/claude-code/common-workflows">~~85 <Card title="Common workflows" icon="graduation-cap" href="/en/common-workflows">

80 Step-by-step guides for common workflows86 Step-by-step guides for common workflows

81 </Card>87 </Card>

82 88

~~83 <Card title="Troubleshooting" icon="wrench" href="/en/docs/claude-code/troubleshooting">~~89 <Card title="Troubleshooting" icon="wrench" href="/en/troubleshooting">

84 Solutions for common issues with Claude Code90 Solutions for common issues with Claude Code

85 </Card>91 </Card>

86 92

~~87 <Card title="IDE setup" icon="laptop" href="/en/docs/claude-code/ide-integrations">~~93 <Card title="IDE setup" icon="laptop" href="/en/vs-code">

88 Add Claude Code to your IDE94 Add Claude Code to your IDE

89 </Card>95 </Card>

90</CardGroup>96</CardGroup>

92## Additional resources98## Additional resources

93 99

94<CardGroup>100<CardGroup>

~~95 <Card title="Build with the Agent SDK" icon="code-branch" href="https://docs.claude.com/en/api/agent-sdk/overview">~~101 <Card title="About Claude Code" icon="sparkles" href="https://claude.com/product/claude-code">

102 Learn more about Claude Code on claude.com

103 </Card>

104

105 <Card title="Build with the Agent SDK" icon="code-branch" href="https://docs.claude.com/en/docs/agent-sdk/overview">

96 Create custom AI agents with the Claude Agent SDK106 Create custom AI agents with the Claude Agent SDK

97 </Card>107 </Card>

98 108

~~99 <Card title="Host on AWS or GCP" icon="cloud" href="/en/docs/claude-code/third-party-integrations">~~109 <Card title="Host on AWS or GCP" icon="cloud" href="/en/third-party-integrations">

100 Configure Claude Code with Amazon Bedrock or Google Vertex AI110 Configure Claude Code with Amazon Bedrock or Google Vertex AI

101 </Card>111 </Card>

102 112

103 <Card title="Settings" icon="gear" href="/en/docs/claude-code/settings">113 <Card title="Settings" icon="gear" href="/en/settings">

104 Customize Claude Code for your workflow114 Customize Claude Code for your workflow

105 </Card>115 </Card>

106 116

107 <Card title="Commands" icon="terminal" href="/en/docs/claude-code/cli-reference">117 <Card title="Commands" icon="terminal" href="/en/cli-reference">

108 Learn about CLI commands and controls118 Learn about CLI commands and controls

109 </Card>119 </Card>

110 120

112 Clone our development container reference implementation122 Clone our development container reference implementation

113 </Card>123 </Card>

114 124

115 <Card title="Security" icon="shield" href="/en/docs/claude-code/security">125 <Card title="Security" icon="shield" href="/en/security">

116 Discover Claude Code's safeguards and best practices for safe usage126 Discover Claude Code's safeguards and best practices for safe usage

117 </Card>127 </Card>

118 128

119 <Card title="Privacy and data usage" icon="lock" href="/en/docs/claude-code/data-usage">129 <Card title="Privacy and data usage" icon="lock" href="/en/data-usage">

120 Understand how Claude Code handles your data130 Understand how Claude Code handles your data

121 </Card>131 </Card>

122</CardGroup>132</CardGroup>

133

134

135---

136

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

plugin-marketplaces.md +274 −196

Details

~~1# Plugin marketplaces~~1# Create and distribute a plugin marketplace

2 2

~~3> Create and manage plugin marketplaces to distribute Claude Code extensions across teams and communities.~~3> Build and host plugin marketplaces to distribute Claude Code extensions across teams and communities.

4 4

5Plugin marketplaces are catalogs of available plugins that make it easy to discover, install, and manage Claude Code extensions. This guide shows you how to use existing marketplaces and create your own for team distribution.5A plugin marketplace is a catalog that lets you distribute plugins to others. Marketplaces provide centralized discovery, version tracking, automatic updates, and support for multiple source types (git repositories, local paths, and more). This guide shows you how to create your own marketplace to share plugins with your team or community.

6 6

~~7## Overview~~7Looking to install plugins from an existing marketplace? See [Discover and install prebuilt plugins](/en/discover-plugins).

~~9A marketplace is a JSON file that lists available plugins and describes where to find them. Marketplaces provide:~~

~~11* **Centralized discovery**: Browse plugins from multiple sources in one place~~

~~12* **Version management**: Track and update plugin versions automatically~~

~~13* **Team distribution**: Share required plugins across your organization~~

~~14* **Flexible sources**: Support for git repositories, GitHub repos, local paths, and package managers~~

~~16### Prerequisites~~

~~18* Claude Code installed and running~~

~~19* Basic familiarity with JSON file format~~

~~20* For creating marketplaces: Git repository or local development environment~~

~~22## Add and use marketplaces~~

~~24Add marketplaces using the `/plugin marketplace` commands to access plugins from different sources:~~

~~26### Add GitHub marketplaces~~

~~28```shell Add a GitHub repository containing .claude-plugin/marketplace.json theme={null}~~

~~29/plugin marketplace add owner/repo~~

~~30```~~

~~32### Add Git repositories~~

~~34```shell Add any git repository theme={null}~~

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

~~36```~~

37 8

~~38### Add local marketplaces for development~~9## Overview

39 10

~~40```shell Add local directory containing .claude-plugin/marketplace.json theme={null}~~11Creating and distributing a marketplace involves:

~~41/plugin marketplace add ./my-marketplace~~

~~42```~~

43 12

~~44```shell Add direct path to marketplace.json file theme={null}~~131. **Creating plugins**: build one or more plugins with commands, agents, hooks, MCP servers, or LSP servers. This guide assumes you already have plugins to distribute; see [Create plugins](/en/plugins) for details on how to create them.

~~45/plugin marketplace add ./path/to/marketplace.json~~142. **Creating a marketplace file**: define a `marketplace.json` that lists your plugins and where to find them (see [Create the marketplace file](#create-the-marketplace-file)).

~~46```~~153. **Host the marketplace**: push to GitHub, GitLab, or another git host (see [Host and distribute marketplaces](#host-and-distribute-marketplaces)).

164. **Share with users**: users add your marketplace with `/plugin marketplace add` and install individual plugins (see [Discover and install plugins](/en/discover-plugins)).

47 17

~~48```shell Add remote marketplace.json via URL theme={null}~~18Once your marketplace is live, you can update it by pushing changes to your repository. Users refresh their local copy with `/plugin marketplace update`.

~~49/plugin marketplace add https://url.of/marketplace.json~~

~~50```~~

51 19

~~52### Install plugins from marketplaces~~20## Walkthrough: create a local marketplace

53 21

~~54Once you've added marketplaces, install plugins directly:~~22This example creates a marketplace with one plugin: a `/review` command for code reviews. You'll create the directory structure, add a slash command, create the plugin manifest and marketplace catalog, then install and test it.

55 23

~~56```shell Install from any known marketplace theme={null}~~24<Steps>

~~57/plugin install plugin-name@marketplace-name~~25 <Step title="Create the directory structure">

~~58```~~26 ```bash theme={null}

27 mkdir -p my-marketplace/.claude-plugin

28 mkdir -p my-marketplace/plugins/review-plugin/.claude-plugin

29 mkdir -p my-marketplace/plugins/review-plugin/commands

30 ```

31 </Step>

59 32

~~60```shell Browse available plugins interactively theme={null}~~33 <Step title="Create the plugin command">

~~61/plugin~~34 Create a Markdown file that defines what the `/review` command does.

~~62```~~

63 35

~~64### Verify marketplace installation~~36 ```markdown my-marketplace/plugins/review-plugin/commands/review.md theme={null}

37 Review the code I've selected or the recent changes for:

38 - Potential bugs or edge cases

39 - Security concerns

40 - Performance issues

41 - Readability improvements

65 42

~~66After adding a marketplace:~~43 Be concise and actionable.

44 ```

45 </Step>

67 46

~~681. **List marketplaces**: Run `/plugin marketplace list` to confirm it's added~~47 <Step title="Create the plugin manifest">

~~692. **Browse plugins**: Use `/plugin` to see available plugins from your marketplace~~48 Create a `plugin.json` file that describes the plugin. The manifest goes in the `.claude-plugin/` directory.

~~703. **Test installation**: Try installing a plugin to verify the marketplace works correctly~~

71 49

~~72## Configure team marketplaces~~50 ```json my-marketplace/plugins/review-plugin/.claude-plugin/plugin.json theme={null}

51 {

52 "name": "review-plugin",

53 "description": "Adds a /review command for quick code reviews",

54 "version": "1.0.0"

55 }

56 ```

57 </Step>

73 58

~~74Set up automatic marketplace installation for team projects by specifying required marketplaces in `.claude/settings.json`:~~59 <Step title="Create the marketplace file">

60 Create the marketplace catalog that lists your plugin.

75 61

~~76```json theme={null}~~62 ```json my-marketplace/.claude-plugin/marketplace.json theme={null}

~~77{~~63 {

~~78 "extraKnownMarketplaces": {~~64 "name": "my-plugins",

~~79 "team-tools": {~~65 "owner": {

~~80 "source": {~~66 "name": "Your Name"

~~81 "source": "github",~~

~~82 "repo": "your-org/claude-plugins"~~

~~83 }~~

84 },67 },

~~85 "project-specific": {~~68 "plugins": [

~~86 "source": {~~69 {

~~87 "source": "git",~~70 "name": "review-plugin",

~~88 "url": "https://git.company.com/project-plugins.git"~~71 "source": "./plugins/review-plugin",

~~89 }~~72 "description": "Adds a /review command for quick code reviews"

90 }73 }

74 ]

91 }75 }

~~92}~~76 ```

~~93```~~77 </Step>

94 78

~~95When team members trust the repository folder, Claude Code automatically installs these marketplaces and any plugins specified in the `enabledPlugins` field.~~79 <Step title="Add and install">

80 Add the marketplace and install the plugin.

96 81

~~97***~~82 ```shell theme={null}

83 /plugin marketplace add ./my-marketplace

84 /plugin install review-plugin@my-plugins

85 ```

86 </Step>

98 87

~~99## Create your own marketplace~~88 <Step title="Try it out">

89 Select some code in your editor and run your new command.

100 90

101Build and distribute custom plugin collections for your team or community.91 ```shell theme={null}

92 /review

93 ```

94 </Step>

95</Steps>

102 96

103### Prerequisites for marketplace creation97To learn more about what plugins can do, including hooks, agents, MCP servers, and LSP servers, see [Plugins](/en/plugins).

104 98

105* Git repository (GitHub, GitLab, or other git hosting)99<Note>

106* Understanding of JSON file format100 **How plugins are installed**: When users install a plugin, Claude Code copies the plugin directory to a cache location. This means plugins can't reference files outside their directory using paths like `../shared-utils`, because those files won't be copied.

107* One or more plugins to distribute101

102 If you need to share files across plugins, use symlinks (which are followed during copying) or restructure your marketplace so the shared directory is inside the plugin source path. See [Plugin caching and file resolution](/en/plugins-reference#plugin-caching-and-file-resolution) for details.

103</Note>

108 104

109### Create the marketplace file105## Create the marketplace file

110 106

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

108

109Each plugin entry needs at minimum a `name` and `source` (where to fetch it from). See the [full schema](#marketplace-schema) below for all available fields.

112 110

113```json theme={null}111```json theme={null}

114{112{

115 "name": "company-tools",113 "name": "company-tools",

116 "owner": {114 "owner": {

117 "name": "DevTools Team",115 "name": "DevTools Team",

118 "email": "devtools@company.com"116 "email": "devtools@example.com"

119 },117 },

120 "plugins": [118 "plugins": [

121 {119 {

139}137}

140```138```

141 139

142### Marketplace schema140## Marketplace schema

143 141

144#### Required fields142### Required fields

145 143

147| :-------- | :----- | :--------------------------------------------- |145| :-------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |

149

150<Note>

151 **Reserved names**: The following marketplace names are reserved for official Anthropic use and cannot be used by third-party marketplaces: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `life-sciences`. Names that impersonate official marketplaces (like `official-claude-plugins` or `anthropic-tools-v2`) are also blocked.

152</Note>

153

154### Owner fields

155

157| :------ | :----- | :------- | :------------------------------- |

151 160

152#### Optional metadata161### Optional metadata

153 162

155| :--------------------- | :----- | :------------------------------------ |164| :--------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

159 168

160### Plugin entries169## Plugin entries

161 170

162<Note>171Each plugin entry in the `plugins` array describes a plugin and where to find it. You can include any field from the [plugin manifest schema](/en/plugins-reference#plugin-manifest-schema) (like `description`, `version`, `author`, `commands`, `hooks`, etc.), plus these marketplace-specific fields: `source`, `category`, `tags`, and `strict`.

163 Plugin entries are based on the *plugin manifest schema* (with all fields made optional) plus marketplace-specific fields (`source`, `category`, `tags`, `strict`), with `name` being required.

164</Note>

165 172

166**Required fields:**173### Required fields

167 174

169| :------- | :------------- | :---------------------------------------- |176| :------- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

172 179

173#### Optional plugin fields180### Optional plugin fields

174 181

175**Standard metadata fields:**182**Standard metadata fields:**

176 183

178| :------------ | :------ | :---------------------------------------------------------------- |185| :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

188| `strict` | boolean | Require plugin.json in plugin folder (default: true) <sup>1</sup> |195| `strict` | boolean | Controls whether plugins need their own `plugin.json` file. When `true` (default), the plugin source must contain a `plugin.json`, and any fields you add here in the marketplace entry get merged with it. When `false`, the plugin doesn't need its own `plugin.json`; the marketplace entry itself defines everything about the plugin. Use `false` when you want to define simple plugins entirely in your marketplace file. |

189 196

190**Component configuration fields:**197**Component configuration fields:**

191 198

198 206

199*<sup>1 - When `strict: true` (default), the plugin must include a `plugin.json` manifest file, and marketplace fields supplement those values. When `strict: false`, the plugin.json is optional. If it's missing, the marketplace entry serves as the complete plugin manifest.</sup>*207## Plugin sources

200 208

201### Plugin sources209### Relative paths

~~202~~

203#### Relative paths

204 210

205For plugins in the same repository:211For plugins in the same repository:

206 212

211}217}

212```218```

213 219

214#### GitHub repositories220### GitHub repositories

215 221

216```json theme={null}222```json theme={null}

217{223{

223}229}

224```230```

225 231

226#### Git repositories232### Git repositories

227 233

228```json theme={null}234```json theme={null}

229{235{

235}241}

236```242```

237 243

238#### Advanced plugin entries244### Advanced plugin entries

239 245

240Plugin entries can override default component locations and provide additional metadata. Note that `${CLAUDE_PLUGIN_ROOT}` is an environment variable that resolves to the plugin's installation directory (for details see [Environment variables](/en/plugins-reference#environment-variables)):246This example shows a plugin entry using many of the optional fields, including custom paths for commands, agents, hooks, and MCP servers:

241 247

242```json theme={null}248```json theme={null}

243{249{

250 "version": "2.1.0",256 "version": "2.1.0",

251 "author": {257 "author": {

252 "name": "Enterprise Team",258 "name": "Enterprise Team",

253 "email": "enterprise@company.com"259 "email": "enterprise@example.com"

254 },260 },

255 "homepage": "https://docs.company.com/plugins/enterprise-tools",261 "homepage": "https://docs.example.com/plugins/enterprise-tools",

256 "repository": "https://github.com/company/enterprise-plugin",262 "repository": "https://github.com/company/enterprise-plugin",

257 "license": "MIT",263 "license": "MIT",

258 "keywords": ["enterprise", "workflow", "automation"],264 "keywords": ["enterprise", "workflow", "automation"],

262 "./commands/enterprise/",268 "./commands/enterprise/",

263 "./commands/experimental/preview.md"269 "./commands/experimental/preview.md"

264 ],270 ],

265 "agents": [271 "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],

266 "./agents/security-reviewer.md",

267 "./agents/compliance-checker.md"

268 ],

269 "hooks": {272 "hooks": {

270 "PostToolUse": [273 "PostToolUse": [

271 {274 {

272 "matcher": "Write|Edit",275 "matcher": "Write|Edit",

273 "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"}]276 "hooks": [

277 {

278 "type": "command",

279 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"

280 }

281 ]

274 }282 }

275 ]283 ]

276 },284 },

284}292}

285```293```

286 294

287<Note>295Key things to notice:

288 **Schema relationship**: Plugin entries use the plugin manifest schema with all fields made optional, plus marketplace-specific fields (`source`, `strict`, `category`, `tags`). This means any field valid in a `plugin.json` file can also be used in a marketplace entry. When `strict: false`, the marketplace entry serves as the complete plugin manifest if no `plugin.json` exists. When `strict: true` (default), marketplace fields supplement the plugin's own manifest file.

289</Note>

290 296

291***297* **`commands` and `agents`**: You can specify multiple directories or individual files. Paths are relative to the plugin root.

298* **`${CLAUDE_PLUGIN_ROOT}`**: Use this variable in hooks and MCP server configs to reference files within the plugin's installation directory. This is necessary because plugins are copied to a cache location when installed.

299* **`strict: false`**: Since this is set to false, the plugin doesn't need its own `plugin.json`. The marketplace entry defines everything.

292 300

293## Host and distribute marketplaces301## Host and distribute marketplaces

294 302

295Choose the best hosting strategy for your plugin distribution needs.

~~296~~

297### Host on GitHub (recommended)303### Host on GitHub (recommended)

298 304

299GitHub provides the easiest distribution method:305GitHub provides the easiest distribution method:

300 306

3011. **Create a repository**: Set up a new repository for your marketplace3071. **Create a repository**: Set up a new repository for your marketplace

3022. **Add marketplace file**: Create `.claude-plugin/marketplace.json` with your plugin definitions3082. **Add marketplace file**: Create `.claude-plugin/marketplace.json` with your plugin definitions

3033. **Share with teams**: Team members add with `/plugin marketplace add owner/repo`3093. **Share with teams**: Users add your marketplace with `/plugin marketplace add owner/repo`

304 310

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

306 312

307### Host on other git services313### Host on other git services

308 314

309Any git hosting service works for marketplace distribution, using a URL to an arbitrary git repository.315Any git hosting service works, such as GitLab, Bitbucket, and self-hosted servers. Users add with the full repository URL:

~~310~~

311For example, using GitLab:

312 316

313```shell theme={null}317```shell theme={null}

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

315```319```

316 320

317### Use local marketplaces for development321### Test locally before distribution

318 322

319Test your marketplace locally before distribution:323Test your marketplace locally before sharing:

320 324

321```shell Add local marketplace for testing theme={null}325```shell theme={null}

322/plugin marketplace add ./my-local-marketplace326/plugin marketplace add ./my-local-marketplace

323```

~~324~~

325```shell Test plugin installation theme={null}

326/plugin install test-plugin@my-local-marketplace327/plugin install test-plugin@my-local-marketplace

327```328```

328 329

329## Manage marketplace operations330For the full range of add commands (GitHub, Git URLs, local paths, remote URLs), see [Add marketplaces](/en/discover-plugins#add-marketplaces).

330 331

331### List known marketplaces332### Require marketplaces for your team

332 333

333```shell List all configured marketplaces theme={null}334You can configure your repository so team members are automatically prompted to install your marketplace when they trust the project folder. Add your marketplace to `.claude/settings.json`:

334/plugin marketplace list

335```

336 335

337Shows all configured marketplaces with their sources and status.336```json theme={null}

337{

338 "extraKnownMarketplaces": {

339 "company-tools": {

340 "source": {

341 "source": "github",

342 "repo": "your-org/claude-plugins"

343 }

344 }

345 }

346}

347```

338 348

339### Update marketplace metadata349You can also specify which plugins should be enabled by default:

340 350

341```shell Refresh marketplace metadata theme={null}351```json theme={null}

342/plugin marketplace update marketplace-name352{

353 "enabledPlugins": {

354 "code-formatter@company-tools": true,

355 "deployment-tools@company-tools": true

356 }

357}

343```358```

344 359

345Refreshes plugin listings and metadata from the marketplace source.360For full configuration options, see [Plugin settings](/en/settings#plugin-settings).

346 361

347### Remove a marketplace362### Enterprise marketplace restrictions

348 363

349```shell Remove a marketplace theme={null}364For organizations requiring strict control over plugin sources, enterprise administrators can restrict which plugin marketplaces users are allowed to add using the [`strictKnownMarketplaces`](/en/settings#strictknownmarketplaces) setting in managed settings.

350/plugin marketplace remove marketplace-name

351```

352 365

353Removes the marketplace from your configuration.366When `strictKnownMarketplaces` is configured in managed settings, the restriction behavior depends on the value:

354 367

355<Warning>368| Value | Behavior |

356 Removing a marketplace will uninstall any plugins you installed from it.369| ------------------- | ---------------------------------------------------------------- |

357</Warning>370| Undefined (default) | No restrictions. Users can add any marketplace |

371| Empty array `[]` | Complete lockdown. Users cannot add any new marketplaces |

372| List of sources | Users can only add marketplaces that match the allowlist exactly |

358 373

359***374#### Common configurations

360 375

361## Troubleshooting marketplaces376Disable all marketplace additions:

362 377

363### Common marketplace issues378```json theme={null}

379{

380 "strictKnownMarketplaces": []

381}

382```

364 383

365#### Marketplace not loading384Allow specific marketplaces only:

366 385

367**Symptoms**: Can't add marketplace or see plugins from it386```json theme={null}

387{

388 "strictKnownMarketplaces": [

389 {

390 "source": "github",

391 "repo": "acme-corp/approved-plugins"

392 },

393 {

394 "source": "github",

395 "repo": "acme-corp/security-tools",

396 "ref": "v2.0"

397 },

398 {

399 "source": "url",

400 "url": "https://plugins.example.com/marketplace.json"

401 }

402 ]

403}

404```

368 405

369**Solutions**:406#### How restrictions work

370 407

371* Verify the marketplace URL is accessible408Restrictions are validated early in the plugin installation process, before any network requests or filesystem operations occur. This prevents unauthorized marketplace access attempts.

372* Check that `.claude-plugin/marketplace.json` exists at the specified path

373* Ensure JSON syntax is valid using `claude plugin validate`

374* For private repositories, confirm you have access permissions

375 409

376#### Plugin installation failures410The allowlist uses exact matching. For a marketplace to be allowed, all specified fields must match exactly:

377 411

378**Symptoms**: Marketplace appears but plugin installation fails412* For GitHub sources: `repo` is required, and `ref` or `path` must also match if specified in the allowlist

413* For URL sources: the full URL must match exactly

379 414

380**Solutions**:415Because `strictKnownMarketplaces` is set in [managed settings](/en/settings#settings-file-locations), individual users and project configurations cannot override these restrictions.

381 416

382* Verify plugin source URLs are accessible417For complete configuration details including all supported source types and comparison with `extraKnownMarketplaces`, see the [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces).

383* Check that plugin directories contain required files418

384* For GitHub sources, ensure repositories are public or you have access419## Validation and testing

385* Test plugin sources manually by cloning/downloading

386 420

387### Validation and testing421Test your marketplace before sharing.

388 422

389Test your marketplace before sharing:423Validate your marketplace JSON syntax:

390 424

391```bash Validate marketplace JSON syntax theme={null}425```bash theme={null}

392claude plugin validate .426claude plugin validate .

393```427```

394 428

395```shell Add marketplace for testing theme={null}429Or from within Claude Code:

430

431```shell theme={null}

432/plugin validate .

433```

434

435Add the marketplace for testing:

436

437```shell theme={null}

396/plugin marketplace add ./path/to/marketplace438/plugin marketplace add ./path/to/marketplace

397```439```

398 440

399```shell Install test plugin theme={null}441Install a test plugin to verify everything works:

442

443```shell theme={null}

400/plugin install test-plugin@marketplace-name444/plugin install test-plugin@marketplace-name

401```445```

402 446

403For complete plugin testing workflows, see [Test your plugins locally](/en/plugins#test-your-plugins-locally). For technical troubleshooting, see [Plugins reference](/en/plugins-reference).447For complete plugin testing workflows, see [Test your plugins locally](/en/plugins#test-your-plugins-locally). For technical troubleshooting, see [Plugins reference](/en/plugins-reference).

404 448

405***449## Troubleshooting

450

451### Marketplace not loading

406 452

407## Next steps453**Symptoms**: Can't add marketplace or see plugins from it

454

455**Solutions**:

456

457* Verify the marketplace URL is accessible

458* Check that `.claude-plugin/marketplace.json` exists at the specified path

459* Ensure JSON syntax is valid using `claude plugin validate` or `/plugin validate`

460* For private repositories, confirm you have access permissions

408 461

409### For marketplace users462### Marketplace validation errors

410 463

411* **Discover community marketplaces**: Search GitHub for Claude Code plugin collections464Run `claude plugin validate .` or `/plugin validate .` from your marketplace directory to check for issues. Common errors:

412* **Contribute feedback**: Report issues and suggest improvements to marketplace maintainers

413* **Share useful marketplaces**: Help your team discover valuable plugin collections

414 465

415### For marketplace creators466| Error | Cause | Solution |

467| :------------------------------------------------ | :------------------------------ | :------------------------------------------------------------ |

468| `File not found: .claude-plugin/marketplace.json` | Missing manifest | Create `.claude-plugin/marketplace.json` with required fields |

469| `Invalid JSON syntax: Unexpected token...` | JSON syntax error | Check for missing commas, extra commas, or unquoted strings |

470| `Duplicate plugin name "x" found in marketplace` | Two plugins share the same name | Give each plugin a unique `name` value |

471| `plugins[0].source: Path traversal not allowed` | Source path contains `..` | Use paths relative to marketplace root without `..` |

416 472

417* **Build plugin collections**: Create themed marketplace around specific use cases473**Warnings** (non-blocking):

418* **Establish versioning**: Implement clear versioning and update policies

419* **Community engagement**: Gather feedback and maintain active marketplace communities

420* **Documentation**: Provide clear README files explaining your marketplace contents

421 474

422### For organizations475* `Marketplace has no plugins defined`: add at least one plugin to the `plugins` array

476* `No marketplace description provided`: add `metadata.description` to help users understand your marketplace

477* `Plugin "x" uses npm source which is not yet fully implemented`: use `github` or local path sources instead

423 478

424* **Private marketplaces**: Set up internal marketplaces for proprietary tools479### Plugin installation failures

425* **Governance policies**: Establish guidelines for plugin approval and security review480

426* **Training resources**: Help teams discover and adopt useful plugins effectively481**Symptoms**: Marketplace appears but plugin installation fails

482

483**Solutions**:

484

485* Verify plugin source URLs are accessible

486* Check that plugin directories contain required files

487* For GitHub sources, ensure repositories are public or you have access

488* Test plugin sources manually by cloning/downloading

489

490### Files not found after installation

491

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

493

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

495

496**Solutions**: See [Plugin caching and file resolution](/en/plugins-reference#plugin-caching-and-file-resolution) for workarounds including symlinks and directory restructuring.

497

498For additional debugging tools and common issues, see [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools).

427 499

428## See also500## See also

429 501

430* [Plugins](/en/plugins) - Installing and using plugins502* [Discover and install prebuilt plugins](/en/discover-plugins) - Installing plugins from existing marketplaces

503* [Plugins](/en/plugins) - Creating your own plugins

431* [Plugins reference](/en/plugins-reference) - Complete technical specifications and schemas504* [Plugins reference](/en/plugins-reference) - Complete technical specifications and schemas

432* [Plugin development](/en/plugins#develop-more-complex-plugins) - Creating your own plugins505* [Plugin settings](/en/settings#plugin-settings) - Plugin configuration options

433* [Settings](/en/settings#plugin-configuration) - Plugin configuration options506* [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces) - Enterprise marketplace restrictions

507

508

509---

510

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

plugins.md +273 −251

Details

~~1# Plugins~~1# Create plugins

2 2

~~3> Extend Claude Code with custom commands, agents, hooks, Skills, and MCP servers through the plugin system.~~3> Create custom plugins to extend Claude Code with slash commands, agents, hooks, Skills, and MCP servers.

5Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. This guide covers creating your own plugins with slash commands, agents, Skills, hooks, and MCP servers.

7Looking to install existing plugins? See [Discover and install plugins](/en/discover-plugins). For complete technical specifications, see [Plugins reference](/en/plugins-reference).

9## When to use plugins vs standalone configuration

11Claude Code supports two ways to add custom slash commands, agents, and hooks:

13| Approach | Slash command names | Best for |

14| :---------------------------------------------------------- | :------------------- | :---------------------------------------------------------------------------------------------- |

15| **Standalone** (`.claude/` directory) | `/hello` | Personal workflows, project-specific customizations, quick experiments |

16| **Plugins** (directories with `.claude-plugin/plugin.json`) | `/plugin-name:hello` | Sharing with teammates, distributing to community, versioned releases, reusable across projects |

18**Use standalone configuration when**:

20* You're customizing Claude Code for a single project

21* The configuration is personal and doesn't need to be shared

22* You're experimenting with slash commands or hooks before packaging them

23* You want short slash command names like `/hello` or `/review`

25**Use plugins when**:

27* You want to share functionality with your team or community

28* You need the same slash commands/agents across multiple projects

29* You want version control and easy updates for your extensions

30* You're distributing through a marketplace

31* You're okay with namespaced slash commands like `/my-plugin:hello` (namespacing prevents conflicts between plugins)

4 32

5<Tip>33<Tip>

~~6 For complete technical specifications and schemas, see [Plugins reference](/en/plugins-reference). For marketplace management, see [Plugin marketplaces](/en/plugin-marketplaces).~~34 Start with standalone configuration in `.claude/` for quick iteration, then [convert to a plugin](#convert-existing-configurations-to-plugins) when you're ready to share.

7</Tip>35</Tip>

8 36

9Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. Install plugins from [marketplaces](/en/plugin-marketplaces) to add pre-built commands, agents, hooks, Skills, and MCP servers, or create your own to automate your workflows.

11## Quickstart37## Quickstart

12 38

~~13Let's create a simple greeting plugin to get you familiar with the plugin system. We'll build a working plugin that adds a custom command, test it locally, and understand the core concepts.~~39This quickstart walks you through creating a plugin with a custom slash command. You'll create a manifest (the configuration file that defines your plugin), add a slash command, and test it locally using the `--plugin-dir` flag.

14 40

15### Prerequisites41### Prerequisites

16 42

~~17* Claude Code installed on your machine~~43* Claude Code [installed and authenticated](/en/quickstart#step-1-install-claude-code)

~~18* Basic familiarity with command-line tools~~44* Claude Code version 1.0.33 or later (run `claude --version` to check)

46<Note>

47 If you don't see the `/plugin` command, update Claude Code to the latest version. See [Troubleshooting](/en/troubleshooting) for upgrade instructions.

48</Note>

19 49

20### Create your first plugin50### Create your first plugin

21 51

22<Steps>52<Steps>

~~23 <Step title="Create the marketplace structure">~~

~~24 ```bash theme={null}~~

~~25 mkdir test-marketplace~~

~~26 cd test-marketplace~~

~~27 ```~~

~~28 </Step>~~

30 <Step title="Create the plugin directory">53 <Step title="Create the plugin directory">

54 Every plugin lives in its own directory containing a manifest and your custom commands, agents, or hooks. Create one now:

31 ```bash theme={null}56 ```bash theme={null}

32 mkdir my-first-plugin57 mkdir my-first-plugin

~~33 cd my-first-plugin~~

34 ```58 ```

35 </Step>59 </Step>

36 60

37 <Step title="Create the plugin manifest">61 <Step title="Create the plugin manifest">

~~38 ```bash Create .claude-plugin/plugin.json theme={null}~~62 The manifest file at `.claude-plugin/plugin.json` defines your plugin's identity: its name, description, and version. Claude Code uses this metadata to display your plugin in the plugin manager.

~~39 mkdir .claude-plugin~~63

~~40 cat > .claude-plugin/plugin.json << 'EOF'~~64 Create the `.claude-plugin` directory inside your plugin folder:

66 ```bash theme={null}

67 mkdir my-first-plugin/.claude-plugin

68 ```

70 Then create `my-first-plugin/.claude-plugin/plugin.json` with this content:

72 ```json my-first-plugin/.claude-plugin/plugin.json theme={null}

41 {73 {

42 "name": "my-first-plugin",74 "name": "my-first-plugin",

~~43 "description": "A simple greeting plugin to learn the basics",~~75 "description": "A greeting plugin to learn the basics",

44 "version": "1.0.0",76 "version": "1.0.0",

45 "author": {77 "author": {

46 "name": "Your Name"78 "name": "Your Name"

47 }79 }

48 }80 }

~~49 EOF~~

50 ```81 ```

83 | Field | Purpose |

84 | :------------ | :--------------------------------------------------------------------------------------------------------------------- |

85 | `name` | Unique identifier and slash command namespace. Slash commands are prefixed with this (e.g., `/my-first-plugin:hello`). |

86 | `description` | Shown in the plugin manager when browsing or installing plugins. |

87 | `version` | Track releases using [semantic versioning](/en/plugins-reference#version-management). |

88 | `author` | Optional. Helpful for attribution. |

90 For additional fields like `homepage`, `repository`, and `license`, see the [full manifest schema](/en/plugins-reference#plugin-manifest-schema).

51 </Step>91 </Step>

52 92

~~53 <Step title="Add a custom command">~~93 <Step title="Add a slash command">

~~54 ```bash Create commands/hello.md theme={null}~~94 Slash commands are Markdown files in the `commands/` directory. The filename becomes the slash command name, prefixed with the plugin's namespace (`hello.md` in a plugin named `my-first-plugin` creates `/my-first-plugin:hello`). The Markdown content tells Claude how to respond when someone runs the slash command.

~~55 mkdir commands~~95

~~56 cat > commands/hello.md << 'EOF'~~96 Create a `commands` directory in your plugin folder:

98 ```bash theme={null}

99 mkdir my-first-plugin/commands

100 ```

101

102 Then create `my-first-plugin/commands/hello.md` with this content:

103

104 ```markdown my-first-plugin/commands/hello.md theme={null}

57 ---105 ---

~~58 description: Greet the user with a personalized message~~106 description: Greet the user with a friendly message

59 ---107 ---

60 108

61 # Hello Command109 # Hello Command

62 110

~~63 Greet the user warmly and ask how you can help them today. Make the greeting personal and encouraging.~~111 Greet the user warmly and ask how you can help them today.

~~64 EOF~~

65 ```112 ```

66 </Step>113 </Step>

67 114

~~68 <Step title="Create the marketplace manifest">~~115 <Step title="Test your plugin">

~~69 ```bash Create marketplace.json theme={null}~~116 Run Claude Code with the `--plugin-dir` flag to load your plugin:

~~70 cd ..~~

~~71 mkdir .claude-plugin~~

~~72 cat > .claude-plugin/marketplace.json << 'EOF'~~

~~73 {~~

~~74 "name": "test-marketplace",~~

~~75 "owner": {~~

~~76 "name": "Test User"~~

~~77 },~~

~~78 "plugins": [~~

~~79 {~~

~~80 "name": "my-first-plugin",~~

~~81 "source": "./my-first-plugin",~~

~~82 "description": "My first test plugin"~~

~~83 }~~

~~84 ]~~

~~85 }~~

~~86 EOF~~

~~87 ```~~

~~88 </Step>~~

89 117

~~90 <Step title="Install and test your plugin">~~118 ```bash theme={null}

~~91 ```bash Start Claude Code from parent directory theme={null}~~119 claude --plugin-dir ./my-first-plugin

~~92 cd ..~~

~~93 claude~~

94 ```120 ```

95 121

~~96 ```shell Add the test marketplace theme={null}~~122 Once Claude Code starts, try your new command:

~~97 /plugin marketplace add ./test-marketplace~~123

124 ```shell theme={null}

125 /my-first-plugin:hello

98 ```126 ```

99 127

100 ```shell Install your plugin theme={null}128 You'll see Claude respond with a greeting. Run `/help` to see your command listed under the plugin namespace.

101 /plugin install my-first-plugin@test-marketplace129

130 <Note>

131 **Why namespacing?** Plugin slash commands are always namespaced (like `/greet:hello`) to prevent conflicts when multiple plugins have commands with the same name.

132

133 To change the namespace prefix, update the `name` field in `plugin.json`.

134 </Note>

135 </Step>

136

137 <Step title="Add slash command arguments">

138 Make your slash command dynamic by accepting user input. The `$ARGUMENTS` placeholder captures any text the user provides after the slash command.

139

140 Update your `hello.md` file:

141

142 ```markdown my-first-plugin/commands/hello.md theme={null}

143 ---

144 description: Greet the user with a personalized message

145 ---

146

147 # Hello Command

148

149 Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

102 ```150 ```

103 151

104 Select "Install now". You'll then need to restart Claude Code in order to use the new plugin.152 Restart Claude Code to pick up the changes, then try the command with your name:

105 153

106 ```shell Try your new command theme={null}154 ```shell theme={null}

107 /hello155 /my-first-plugin:hello Alex

108 ```156 ```

109 157

110 You'll see Claude use your greeting command! Check `/help` to see your new command listed.158 Claude will greet you by name. For more argument options like `$1`, `$2` for individual parameters, see [Slash commands](/en/slash-commands).

111 </Step>159 </Step>

112</Steps>160</Steps>

113 161

114You've successfully created and tested a plugin with these key components:162You've successfully created and tested a plugin with these key components:

115 163

116* **Plugin manifest** (`.claude-plugin/plugin.json`) - Describes your plugin's metadata164* **Plugin manifest** (`.claude-plugin/plugin.json`): describes your plugin's metadata

117* **Commands directory** (`commands/`) - Contains your custom slash commands165* **Commands directory** (`commands/`): contains your custom slash commands

118* **Test marketplace** - Allows you to test your plugin locally166* **Command arguments** (`$ARGUMENTS`): captures user input for dynamic behavior

119 167

120### Plugin structure overview168<Tip>

169 The `--plugin-dir` flag is useful for development and testing. When you're ready to share your plugin with others, see [Create and distribute a plugin marketplace](/en/plugin-marketplaces).

170</Tip>

121 171

122Your plugin follows this basic structure:172## Plugin structure overview

123 173

124```174You've created a plugin with a slash command, but plugins can include much more: custom agents, Skills, hooks, MCP servers, and LSP servers.

125my-first-plugin/

126├── .claude-plugin/

127│ └── plugin.json # Plugin metadata

128├── commands/ # Custom slash commands (optional)

129│ └── hello.md

130├── agents/ # Custom agents (optional)

131│ └── helper.md

132├── skills/ # Agent Skills (optional)

133│ └── my-skill/

134│ └── SKILL.md

135└── hooks/ # Event handlers (optional)

136 └── hooks.json

137```

138 175

139**Additional components you can add:**176<Warning>

177 **Common mistake**: Don't put `commands/`, `agents/`, `skills/`, or `hooks/` inside the `.claude-plugin/` directory. Only `plugin.json` goes inside `.claude-plugin/`. All other directories must be at the plugin root level.

178</Warning>

140 179

141* **Commands**: Create markdown files in `commands/` directory180| Directory | Location | Purpose |

142* **Agents**: Create agent definitions in `agents/` directory181| :---------------- | :---------- | :---------------------------------------------- |

143* **Skills**: Create `SKILL.md` files in `skills/` directory182| `.claude-plugin/` | Plugin root | Contains only `plugin.json` manifest (required) |

144* **Hooks**: Create `hooks/hooks.json` for event handling183| `commands/` | Plugin root | Slash commands as Markdown files |

145* **MCP servers**: Create `.mcp.json` for external tool integration184| `agents/` | Plugin root | Custom agent definitions |

185| `skills/` | Plugin root | Agent Skills with `SKILL.md` files |

186| `hooks/` | Plugin root | Event handlers in `hooks.json` |

187| `.mcp.json` | Plugin root | MCP server configurations |

188| `.lsp.json` | Plugin root | LSP server configurations for code intelligence |

146 189

147<Note>190<Note>

148 **Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, and MCP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/plugins-reference).191 **Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, MCP servers, and LSP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/plugins-reference).

149</Note>192</Note>

150 193

151***194## Develop more complex plugins

~~152~~

153## Install and manage plugins

~~154~~

155Learn how to discover, install, and manage plugins to extend your Claude Code capabilities.

156 195

157### Prerequisites196Once you're comfortable with basic plugins, you can create more sophisticated extensions.

158 197

159* Claude Code installed and running198### Add Skills to your plugin

160* Basic familiarity with command-line interfaces

161 199

162### Add marketplaces200Plugins can include [Agent Skills](/en/skills) to extend Claude's capabilities. Skills are model-invoked: Claude automatically uses them based on the task context.

163 201

164Marketplaces are catalogs of available plugins. Add them to discover and install plugins:202Add a `skills/` directory at your plugin root with Skill folders containing `SKILL.md` files:

165 203

166```shell Add a marketplace theme={null}

167/plugin marketplace add your-org/claude-plugins

168```204```

~~169~~ 205my-plugin/

170```shell Browse available plugins theme={null}206├── .claude-plugin/

171/plugin207│ └── plugin.json

208└── skills/

209 └── code-review/

210 └── SKILL.md

172```211```

173 212

174For detailed marketplace management including Git repositories, local development, and team distribution, see [Plugin marketplaces](/en/plugin-marketplaces).213Each `SKILL.md` needs frontmatter with `name` and `description` fields, followed by instructions:

175 214

176### Install plugins215```yaml theme={null}

216---

217name: code-review

218description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.

219---

177 220

178#### Via interactive menu (recommended for discovery)221When reviewing code, check for:

~~179~~ 2221. Code organization and structure

180```shell Open the plugin management interface theme={null}2232. Error handling

181/plugin2243. Security concerns

2254. Test coverage

182```226```

183 227

184Select "Browse Plugins" to see available options with descriptions, features, and installation options.228After installing the plugin, restart Claude Code to load the Skills. For complete Skill authoring guidance including progressive disclosure and tool restrictions, see [Agent Skills](/en/skills).

185 229

186#### Via direct commands (for quick installation)230### Add LSP servers to your plugin

187 231

188```shell Install a specific plugin theme={null}232<Tip>

189/plugin install formatter@your-org233 For common languages like TypeScript, Python, and Rust, install the pre-built LSP plugins from the official marketplace. Create custom LSP plugins only when you need support for languages not already covered.

190```234</Tip>

191 235

192```shell Enable a disabled plugin theme={null}236LSP (Language Server Protocol) plugins give Claude real-time code intelligence. If you need to support a language that doesn't have an official LSP plugin, you can create your own by adding an `.lsp.json` file to your plugin:

193/plugin enable plugin-name@marketplace-name

194```

195 237

196```shell Disable without uninstalling theme={null}238```json .lsp.json theme={null}

197/plugin disable plugin-name@marketplace-name239{

240 "go": {

241 "command": "gopls",

242 "args": ["serve"],

243 "extensionToLanguage": {

244 ".go": "go"

245 }

246 }

247}

198```248```

199 249

200```shell Completely remove a plugin theme={null}250Users installing your plugin must have the language server binary installed on their machine.

201/plugin uninstall plugin-name@marketplace-name

202```

203 251

204### Verify installation252For complete LSP configuration options, see [LSP servers](/en/plugins-reference#lsp-servers).

205 253

206After installing a plugin:254### Organize complex plugins

207 255

2081. **Check available commands**: Run `/help` to see new commands256For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/plugins-reference#plugin-directory-structure).

2092. **Test plugin features**: Try the plugin's commands and features

2103. **Review plugin details**: Use `/plugin` → "Manage Plugins" to see what the plugin provides

211 257

212## Set up team plugin workflows258### Test your plugins locally

213 259

214Configure plugins at the repository level to ensure consistent tooling across your team. When team members trust your repository folder, Claude Code automatically installs specified marketplaces and plugins.260Use the `--plugin-dir` flag to test plugins during development. This loads your plugin directly without requiring installation.

215 261

216**To set up team plugins:**262```bash theme={null}

263claude --plugin-dir ./my-plugin

264```

217 265

2181. Add marketplace and plugin configuration to your repository's `.claude/settings.json`266As you make changes to your plugin, restart Claude Code to pick up the updates. Test your plugin components:

2192. Team members trust the repository folder

2203. Plugins install automatically for all team members

221 267

222For complete instructions including configuration examples, marketplace setup, and rollout best practices, see [Configure team marketplaces](/en/plugin-marketplaces#how-to-configure-team-marketplaces).268* Try your commands with `/command-name`

269* Check that agents appear in `/agents`

270* Verify hooks work as expected

223 271

224***272<Tip>

273 You can load multiple plugins at once by specifying the flag multiple times:

225 274

226## Develop more complex plugins275 ```bash theme={null}

276 claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

277 ```

278</Tip>

227 279

228Once you're comfortable with basic plugins, you can create more sophisticated extensions.280### Debug plugin issues

229 281

230### Add Skills to your plugin282If your plugin isn't working as expected:

231 283

232Plugins can include [Agent Skills](/en/skills) to extend Claude's capabilities. Skills are model-invoked—Claude autonomously uses them based on the task context.2841. **Check the structure**: Ensure your directories are at the plugin root, not inside `.claude-plugin/`

2852. **Test components individually**: Check each command, agent, and hook separately

2863. **Use validation and debugging tools**: See [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools) for CLI commands and troubleshooting techniques

233 287

234To add Skills to your plugin, create a `skills/` directory at your plugin root and add Skill folders with `SKILL.md` files. Plugin Skills are automatically available when the plugin is installed.288### Share your plugins

235 289

236For complete Skill authoring guidance, see [Agent Skills](/en/skills).290When your plugin is ready to share:

237 291

238### Organize complex plugins2921. **Add documentation**: Include a `README.md` with installation and usage instructions

2932. **Version your plugin**: Use [semantic versioning](/en/plugins-reference#version-management) in your `plugin.json`

2943. **Create or use a marketplace**: Distribute through [plugin marketplaces](/en/plugin-marketplaces) for installation

2954. **Test with others**: Have team members test the plugin before wider distribution

239 296

240For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/plugins-reference#plugin-directory-structure).297Once your plugin is in a marketplace, others can install it using the instructions in [Discover and install plugins](/en/discover-plugins).

241 298

242### Test your plugins locally299<Note>

300 For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/plugins-reference).

301</Note>

243 302

244When developing plugins, use a local marketplace to test changes iteratively. This workflow builds on the quickstart pattern and works for plugins of any complexity.303## Convert existing configurations to plugins

245 304

246<Steps>305If you already have custom commands, Skills, or hooks in your `.claude/` directory, you can convert them into a plugin for easier sharing and distribution.

247 <Step title="Set up your development structure">

248 Organize your plugin and marketplace for testing:

249 306

250 ```bash Create directory structure theme={null}307### Migration steps

251 mkdir dev-marketplace

252 cd dev-marketplace

253 mkdir my-plugin

254 ```

255 308

256 This creates:309<Steps>

310 <Step title="Create the plugin structure">

311 Create a new plugin directory:

257 312

313 ```bash theme={null}

314 mkdir -p my-plugin/.claude-plugin

258 ```315 ```

259 dev-marketplace/

260 ├── .claude-plugin/marketplace.json (you'll create this)

261 └── my-plugin/ (your plugin under development)

262 ├── .claude-plugin/plugin.json

263 ├── commands/

264 ├── agents/

265 └── hooks/

266 ```

267 </Step>

268 316

269 <Step title="Create the marketplace manifest">317 Create the manifest file at `my-plugin/.claude-plugin/plugin.json`:

270 ```bash Create marketplace.json theme={null}318

271 mkdir .claude-plugin319 ```json my-plugin/.claude-plugin/plugin.json theme={null}

272 cat > .claude-plugin/marketplace.json << 'EOF'

273 {

274 "name": "dev-marketplace",

275 "owner": {

276 "name": "Developer"

277 },

278 "plugins": [

279 {320 {

280 "name": "my-plugin",321 "name": "my-plugin",

281 "source": "./my-plugin",322 "description": "Migrated from standalone configuration",

282 "description": "Plugin under development"323 "version": "1.0.0"

283 }

284 ]

285 }324 }

286 EOF

287 ```325 ```

288 </Step>326 </Step>

289 327

290 <Step title="Install and test">328 <Step title="Copy your existing files">

291 ```bash Start Claude Code from parent directory theme={null}329 Copy your existing configurations to the plugin directory:

292 cd ..

293 claude

294 ```

~~295~~

296 ```shell Add your development marketplace theme={null}

297 /plugin marketplace add ./dev-marketplace

298 ```

299 330

300 ```shell Install your plugin theme={null}331 ```bash theme={null}

301 /plugin install my-plugin@dev-marketplace332 # Copy commands

302 ```333 cp -r .claude/commands my-plugin/

303 334

304 Test your plugin components:335 # Copy agents (if any)

336 cp -r .claude/agents my-plugin/

305 337

306 * Try your commands with `/command-name`338 # Copy skills (if any)

307 * Check that agents appear in `/agents`339 cp -r .claude/skills my-plugin/

308 * Verify hooks work as expected340 ```

309 </Step>341 </Step>

310 342

311 <Step title="Iterate on your plugin">343 <Step title="Migrate hooks">

312 After making changes to your plugin code:344 If you have hooks in your settings, create a hooks directory:

313 345

314 ```shell Uninstall the current version theme={null}346 ```bash theme={null}

315 /plugin uninstall my-plugin@dev-marketplace347 mkdir my-plugin/hooks

316 ```348 ```

317 349

318 ```shell Reinstall to test changes theme={null}350 Create `my-plugin/hooks/hooks.json` with your hooks configuration. Copy the `hooks` object from your `.claude/settings.json` or `settings.local.json`—the format is the same:

319 /plugin install my-plugin@dev-marketplace

320 ```

321 351

322 Repeat this cycle as you develop and refine your plugin.352 ```json my-plugin/hooks/hooks.json theme={null}

353 {

354 "hooks": {

355 "PostToolUse": [

356 {

357 "matcher": "Write|Edit",

358 "hooks": [{ "type": "command", "command": "npm run lint:fix $FILE" }]

359 }

360 ]

361 }

362 }

363 ```

323 </Step>364 </Step>

324</Steps>

325 365

326<Note>366 <Step title="Test your migrated plugin">

327 **For multiple plugins**: Organize plugins in subdirectories like `./plugins/plugin-name` and update your marketplace.json accordingly. See [Plugin sources](/en/plugin-marketplaces#plugin-sources) for organization patterns.367 Load your plugin to verify everything works:

328</Note>

329 368

330### Debug plugin issues369 ```bash theme={null}

~~331~~ 370 claude --plugin-dir ./my-plugin

332If your plugin isn't working as expected:371 ```

~~333~~

3341. **Check the structure**: Ensure your directories are at the plugin root, not inside `.claude-plugin/`

3352. **Test components individually**: Check each command, agent, and hook separately

3363. **Use validation and debugging tools**: See [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools) for CLI commands and troubleshooting techniques

337 372

338### Share your plugins373 Test each component: run your commands, check agents appear in `/agents`, and verify hooks trigger correctly.

374 </Step>

375</Steps>

339 376

340When your plugin is ready to share:377### What changes when migrating

341 378

3421. **Add documentation**: Include a README.md with installation and usage instructions379| Standalone (`.claude/`) | Plugin |

3432. **Version your plugin**: Use semantic versioning in your `plugin.json`380| :---------------------------- | :------------------------------- |

3443. **Create or use a marketplace**: Distribute through plugin marketplaces for easy installation381| Only available in one project | Can be shared via marketplaces |

3454. **Test with others**: Have team members test the plugin before wider distribution382| Files in `.claude/commands/` | Files in `plugin-name/commands/` |

383| Hooks in `settings.json` | Hooks in `hooks/hooks.json` |

384| Must manually copy to share | Install with `/plugin install` |

346 385

347<Note>386<Note>

348 For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/plugins-reference).387 After migrating, you can remove the original files from `.claude/` to avoid duplicates. The plugin version will take precedence when loaded.

349</Note>388</Note>

350 389

351***

~~352~~

353## Next steps390## Next steps

354 391

355Now that you understand Claude Code's plugin system, here are suggested paths for different goals:392Now that you understand Claude Code's plugin system, here are suggested paths for different goals:

356 393

357### For plugin users394### For plugin users

358 395

359* **Discover plugins**: Browse community marketplaces for useful tools396* [Discover and install plugins](/en/discover-plugins): browse marketplaces and install plugins

360* **Team adoption**: Set up repository-level plugins for your projects397* [Configure team marketplaces](/en/discover-plugins#configure-team-marketplaces): set up repository-level plugins for your team

361* **Marketplace management**: Learn to manage multiple plugin sources

362* **Advanced usage**: Explore plugin combinations and workflows

363 398

364### For plugin developers399### For plugin developers

365 400

366* **Create your first marketplace**: [Plugin marketplaces guide](/en/plugin-marketplaces)401* [Create and distribute a marketplace](/en/plugin-marketplaces): package and share your plugins

367* **Advanced components**: Dive deeper into specific plugin components:402* [Plugins reference](/en/plugins-reference): complete technical specifications

368 * [Slash commands](/en/slash-commands) - Command development details403* Dive deeper into specific plugin components:

369 * [Subagents](/en/sub-agents) - Agent configuration and capabilities404 * [Slash commands](/en/slash-commands): command development details

370 * [Agent Skills](/en/skills) - Extend Claude's capabilities405 * [Subagents](/en/sub-agents): agent configuration and capabilities

371 * [Hooks](/en/hooks) - Event handling and automation406 * [Agent Skills](/en/skills): extend Claude's capabilities

372 * [MCP](/en/mcp) - External tool integration407 * [Hooks](/en/hooks): event handling and automation

373* **Distribution strategies**: Package and share your plugins effectively408 * [MCP](/en/mcp): external tool integration

374* **Community contribution**: Consider contributing to community plugin collections409

~~375~~ 410

376### For team leads and administrators411---

~~377~~ 412

378* **Repository configuration**: Set up automatic plugin installation for team projects413> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

379* **Plugin governance**: Establish guidelines for plugin approval and security review

380* **Marketplace maintenance**: Create and maintain organization-specific plugin catalogs

381* **Training and documentation**: Help team members adopt plugin workflows effectively

~~382~~

383## See also

~~384~~

385* [Plugin marketplaces](/en/plugin-marketplaces) - Creating and managing plugin catalogs

386* [Slash commands](/en/slash-commands) - Understanding custom commands

387* [Subagents](/en/sub-agents) - Creating and using specialized agents

388* [Agent Skills](/en/skills) - Extend Claude's capabilities

389* [Hooks](/en/hooks) - Automating workflows with event handlers

390* [MCP](/en/mcp) - Connecting to external tools and services

391* [Settings](/en/settings) - Configuration options for plugins

plugins-reference.md +414 −21

Details

3> Complete technical reference for Claude Code plugin system, including schemas, CLI commands, and component specifications.3> Complete technical reference for Claude Code plugin system, including schemas, CLI commands, and component specifications.

4 4

5<Tip>5<Tip>

~~6 For hands-on tutorials and practical usage, see [Plugins](/en/plugins). For plugin management across teams and communities, see [Plugin marketplaces](/en/plugin-marketplaces).~~6 Looking to install plugins? See [Discover and install plugins](/en/discover-plugins). For creating plugins, see [Plugins](/en/plugins). For distributing plugins, see [Plugin marketplaces](/en/plugin-marketplaces).

7</Tip>7</Tip>

8 8

9This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.9This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.

87For SKILL.md format and complete Skill authoring guidance, see:87For SKILL.md format and complete Skill authoring guidance, see:

88 88

89* [Use Skills in Claude Code](/en/skills)89* [Use Skills in Claude Code](/en/skills)

~~90* [Agent Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure)~~90* [Agent Skills overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview#skill-structure)

91 91

92### Hooks92### Hooks

93 93

120**Available events**:120**Available events**:

121 121

122* `PreToolUse`: Before Claude uses any tool122* `PreToolUse`: Before Claude uses any tool

123* `PostToolUse`: After Claude uses any tool123* `PostToolUse`: After Claude successfully uses any tool

124* `PostToolUseFailure`: After Claude tool execution fails

125* `PermissionRequest`: When a permission dialog is shown

124* `UserPromptSubmit`: When user submits a prompt126* `UserPromptSubmit`: When user submits a prompt

125* `Notification`: When Claude Code sends notifications127* `Notification`: When Claude Code sends notifications

126* `Stop`: When Claude attempts to stop128* `Stop`: When Claude attempts to stop

129* `SubagentStart`: When a subagent is started

127* `SubagentStop`: When a subagent attempts to stop130* `SubagentStop`: When a subagent attempts to stop

128* `SessionStart`: At the beginning of sessions131* `SessionStart`: At the beginning of sessions

129* `SessionEnd`: At the end of sessions132* `SessionEnd`: At the end of sessions

132**Hook types**:135**Hook types**:

133 136

134* `command`: Execute shell commands or scripts137* `command`: Execute shell commands or scripts

135* `validation`: Validate file contents or project state138* `prompt`: Evaluate a prompt with an LLM (uses `$ARGUMENTS` placeholder for context)

136* `notification`: Send alerts or status updates139* `agent`: Run an agentic verifier with tools for complex verification tasks

137 140

138### MCP servers141### MCP servers

139 142

171* Server capabilities integrate seamlessly with Claude's existing tools174* Server capabilities integrate seamlessly with Claude's existing tools

172* Plugin servers can be configured independently of user MCP servers175* Plugin servers can be configured independently of user MCP servers

173 176

177### LSP servers

178

179<Tip>

180 Looking to use LSP plugins? Install them from the official marketplace—search for "lsp" in the `/plugin` Discover tab. This section documents how to create LSP plugins for languages not covered by the official marketplace.

181</Tip>

182

183Plugins can provide [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) servers to give Claude real-time code intelligence while working on your codebase.

184

185LSP integration provides:

186

187* **Instant diagnostics**: Claude sees errors and warnings immediately after each edit

188* **Code navigation**: go to definition, find references, and hover information

189* **Language awareness**: type information and documentation for code symbols

190

191**Location**: `.lsp.json` in plugin root, or inline in `plugin.json`

192

193**Format**: JSON configuration mapping language server names to their configurations

194

195**`.lsp.json` file format**:

196

197```json theme={null}

198{

199 "go": {

200 "command": "gopls",

201 "args": ["serve"],

202 "extensionToLanguage": {

203 ".go": "go"

204 }

205 }

206}

207```

208

209**Inline in `plugin.json`**:

210

211```json theme={null}

212{

213 "name": "my-plugin",

214 "lspServers": {

215 "go": {

216 "command": "gopls",

217 "args": ["serve"],

218 "extensionToLanguage": {

219 ".go": "go"

220 }

221 }

222 }

223}

224```

225

226**Required fields:**

227

228| Field | Description |

229| :-------------------- | :------------------------------------------- |

230| `command` | The LSP binary to execute (must be in PATH) |

231| `extensionToLanguage` | Maps file extensions to language identifiers |

232

233**Optional fields:**

234

235| Field | Description |

236| :---------------------- | :-------------------------------------------------------- |

237| `args` | Command-line arguments for the LSP server |

238| `transport` | Communication transport: `stdio` (default) or `socket` |

239| `env` | Environment variables to set when starting the server |

240| `initializationOptions` | Options passed to the server during initialization |

241| `settings` | Settings passed via `workspace/didChangeConfiguration` |

242| `workspaceFolder` | Workspace folder path for the server |

243| `startupTimeout` | Max time to wait for server startup (milliseconds) |

244| `shutdownTimeout` | Max time to wait for graceful shutdown (milliseconds) |

245| `restartOnCrash` | Whether to automatically restart the server if it crashes |

246| `maxRestarts` | Maximum number of restart attempts before giving up |

247| `loggingConfig` | Debug logging configuration (see below) |

248

249**Debug logging configuration:**

250

251The `loggingConfig` field enables verbose LSP logging when users pass `--enable-lsp-logging`. This helps debug language server issues without impacting normal operation.

252

253```json theme={null}

254"loggingConfig": {

255 "args": ["--log-level", "4"],

256 "env": {

257 "TSS_LOG": "-level verbose -file ${CLAUDE_PLUGIN_LSP_LOG_FILE}"

258 }

259}

260```

261

262| Field | Description |

263| :----- | :----------------------------------------------------------------- |

264| `args` | Additional command-line arguments appended when logging is enabled |

265| `env` | Additional environment variables merged when logging is enabled |

266

267The `${CLAUDE_PLUGIN_LSP_LOG_FILE}` variable expands to the log file path. Logs are written to `~/.claude/debug/`.

268

269<Warning>

270 **You must install the language server binary separately.** LSP plugins configure how Claude Code connects to a language server, but they don't include the server itself. If you see `Executable not found in $PATH` in the `/plugin` Errors tab, install the required binary for your language.

271</Warning>

272

273**Available LSP plugins:**

274

275| Plugin | Language server | Install command |

276| :--------------- | :------------------------- | :----------------------------------------------------------------------------------------- |

277| `pyright-lsp` | Pyright (Python) | `pip install pyright` or `npm install -g pyright` |

278| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |

279| `rust-lsp` | rust-analyzer | [See rust-analyzer installation](https://rust-analyzer.github.io/manual.html#installation) |

280

281Install the language server first, then install the plugin from the marketplace.

282

283***

284

285## Plugin installation scopes

286

287When you install a plugin, you choose a **scope** that determines where the plugin is available and who else can use it:

288

289| Scope | Settings file | Use case |

290| :-------- | :---------------------------- | :------------------------------------------------------- |

291| `user` | `~/.claude/settings.json` | Personal plugins available across all projects (default) |

292| `project` | `.claude/settings.json` | Team plugins shared via version control |

293| `local` | `.claude/settings.local.json` | Project-specific plugins, gitignored |

294| `managed` | `managed-settings.json` | Enterprise-managed plugins (read-only, update only) |

295

296Plugins use the same scope system as other Claude Code configurations. For installation instructions and scope flags, see [Install plugins](/en/discover-plugins#install-plugins). For a complete explanation of scopes, see [Configuration scopes](/en/settings#configuration-scopes).

297

174***298***

175 299

176## Plugin manifest schema300## Plugin manifest schema

195 "keywords": ["keyword1", "keyword2"],319 "keywords": ["keyword1", "keyword2"],

196 "commands": ["./custom/commands/special.md"],320 "commands": ["./custom/commands/special.md"],

197 "agents": "./custom/agents/",321 "agents": "./custom/agents/",

322 "skills": "./custom/skills/",

198 "hooks": "./config/hooks.json",323 "hooks": "./config/hooks.json",

199 "mcpServers": "./mcp-config.json"324 "mcpServers": "./mcp-config.json",

325 "outputStyles": "./styles/",

326 "lspServers": "./.lsp.json"

200}327}

201```328```

202 329

221### Component path fields348### Component path fields

222 349

224| :----------- | :------------- | :----------------------------------- | :------------------------------------- |351| :------------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- |

229 359

230### Path behavior rules360### Path behavior rules

231 361

274 404

275***405***

276 406

407## Plugin caching and file resolution

408

409For security and verification purposes, Claude Code copies plugins to a cache directory rather than using them in-place. Understanding this behavior is important when developing plugins that reference external files.

410

411### How plugin caching works

412

413When you install a plugin, Claude Code copies the plugin files to a cache directory:

414

415* **For marketplace plugins with relative paths**: The path specified in the `source` field is copied recursively. For example, if your marketplace entry specifies `"source": "./plugins/my-plugin"`, the entire `./plugins` directory is copied.

416* **For plugins with `.claude-plugin/plugin.json`**: The implicit root directory (the directory containing `.claude-plugin/plugin.json`) is copied recursively.

417

418### Path traversal limitations

419

420Plugins cannot reference files outside their copied directory structure. Paths that traverse outside the plugin root (such as `../shared-utils`) will not work after installation because those external files are not copied to the cache.

421

422### Working with external dependencies

423

424If your plugin needs to access files outside its directory, you have two options:

425

426**Option 1: Use symlinks**

427

428Create symbolic links to external files within your plugin directory. Symlinks are honored during the copy process:

429

430```bash theme={null}

431# Inside your plugin directory

432ln -s /path/to/shared-utils ./shared-utils

433```

434

435The symlinked content will be copied into the plugin cache.

436

437**Option 2: Restructure your marketplace**

438

439Set the plugin path to a parent directory that contains all required files, then provide the rest of the plugin manifest directly in the marketplace entry:

440

441```json theme={null}

442{

443 "name": "my-plugin",

444 "source": "./",

445 "description": "Plugin that needs root-level access",

446 "commands": ["./plugins/my-plugin/commands/"],

447 "agents": ["./plugins/my-plugin/agents/"],

448 "strict": false

449}

450```

451

452This approach copies the entire marketplace root, giving your plugin access to sibling directories.

453

454<Note>

455 Symlinks that point to locations outside the plugin's logical root are followed during copying. This provides flexibility while maintaining the security benefits of the caching system.

456</Note>

457

458***

459

277## Plugin directory structure460## Plugin directory structure

278 461

279### Standard plugin layout462### Standard plugin layout

301│ ├── hooks.json # Main hook config484│ ├── hooks.json # Main hook config

302│ └── security-hooks.json # Additional hooks485│ └── security-hooks.json # Additional hooks

303├── .mcp.json # MCP server definitions486├── .mcp.json # MCP server definitions

487├── .lsp.json # LSP server configurations

304├── scripts/ # Hook and utility scripts488├── scripts/ # Hook and utility scripts

305│ ├── security-scan.sh489│ ├── security-scan.sh

306│ ├── format-code.py490│ ├── format-code.py

319| :-------------- | :--------------------------- | :------------------------------- |503| :-------------- | :--------------------------- | :------------------------------- |

510| **LSP servers** | `.lsp.json` | Language server configurations |

511

512***

513

514## CLI commands reference

515

516Claude Code provides CLI commands for non-interactive plugin management, useful for scripting and automation.

517

518### plugin install

519

520Install a plugin from available marketplaces.

521

522```bash theme={null}

523claude plugin install <plugin> [options]

524```

525

526**Arguments:**

527

528* `<plugin>`: Plugin name or `plugin-name@marketplace-name` for a specific marketplace

529

530**Options:**

531

532| Option | Description | Default |

533| :-------------------- | :------------------------------------------------ | :------ |

534| `-s, --scope <scope>` | Installation scope: `user`, `project`, or `local` | `user` |

535| `-h, --help` | Display help for command | |

536

537**Examples:**

538

539```bash theme={null}

540# Install to user scope (default)

541claude plugin install formatter@my-marketplace

542

543# Install to project scope (shared with team)

544claude plugin install formatter@my-marketplace --scope project

545

546# Install to local scope (gitignored)

547claude plugin install formatter@my-marketplace --scope local

548```

549

550### plugin uninstall

551

552Remove an installed plugin.

553

554```bash theme={null}

555claude plugin uninstall <plugin> [options]

556```

557

558**Arguments:**

559

560* `<plugin>`: Plugin name or `plugin-name@marketplace-name`

561

562**Options:**

563

564| Option | Description | Default |

565| :-------------------- | :-------------------------------------------------- | :------ |

566| `-s, --scope <scope>` | Uninstall from scope: `user`, `project`, or `local` | `user` |

567| `-h, --help` | Display help for command | |

568

569**Aliases:** `remove`, `rm`

570

571### plugin enable

572

573Enable a disabled plugin.

574

575```bash theme={null}

576claude plugin enable <plugin> [options]

577```

578

579**Arguments:**

580

581* `<plugin>`: Plugin name or `plugin-name@marketplace-name`

582

583**Options:**

584

585| Option | Description | Default |

586| :-------------------- | :--------------------------------------------- | :------ |

587| `-s, --scope <scope>` | Scope to enable: `user`, `project`, or `local` | `user` |

588| `-h, --help` | Display help for command | |

589

590### plugin disable

591

592Disable a plugin without uninstalling it.

593

594```bash theme={null}

595claude plugin disable <plugin> [options]

596```

597

598**Arguments:**

599

600* `<plugin>`: Plugin name or `plugin-name@marketplace-name`

601

602**Options:**

603

604| Option | Description | Default |

605| :-------------------- | :---------------------------------------------- | :------ |

606| `-s, --scope <scope>` | Scope to disable: `user`, `project`, or `local` | `user` |

607| `-h, --help` | Display help for command | |

608

609### plugin update

610

611Update a plugin to the latest version.

612

613```bash theme={null}

614claude plugin update <plugin> [options]

615```

616

617**Arguments:**

618

619* `<plugin>`: Plugin name or `plugin-name@marketplace-name`

620

621**Options:**

622

623| Option | Description | Default |

624| :-------------------- | :-------------------------------------------------------- | :------ |

625| `-s, --scope <scope>` | Scope to update: `user`, `project`, `local`, or `managed` | `user` |

626| `-h, --help` | Display help for command | |

326 627

327***628***

328 629

346### Common issues647### Common issues

347 648

349| :--------------------- | :------------------------------ | :--------------------------------------------------- |650| :---------------------------------- | :------------------------------ | :-------------------------------------------------------------------------------- |

353| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths |654| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths |

656| LSP `Executable not found in $PATH` | Language server not installed | Install the binary (e.g., `npm install -g typescript-language-server typescript`) |

657

658### Example error messages

659

660**Manifest validation errors**:

661

662* `Invalid JSON syntax: Unexpected token } in JSON at position 142`: check for missing commas, extra commas, or unquoted strings

663* `Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required`: a required field is missing

664* `Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...`: JSON syntax error

665

666**Plugin loading errors**:

667

668* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`: command path exists but contains no valid command files

669* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`: the `source` path in marketplace.json points to a non-existent directory

670* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`: remove duplicate component definitions or set `strict: true` in marketplace entry

671

672### Hook troubleshooting

673

674**Hook script not executing**:

675

6761. Check the script is executable: `chmod +x ./scripts/your-script.sh`

6772. Verify the shebang line: First line should be `#!/bin/bash` or `#!/usr/bin/env bash`

6783. Check the path uses `${CLAUDE_PLUGIN_ROOT}`: `"command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"`

6794. Test the script manually: `./scripts/your-script.sh`

680

681**Hook not triggering on expected events**:

682

6831. Verify the event name is correct (case-sensitive): `PostToolUse`, not `postToolUse`

6842. Check the matcher pattern matches your tools: `"matcher": "Write|Edit"` for file operations

6853. Confirm the hook type is valid: `command`, `prompt`, or `agent`

686

687### MCP server troubleshooting

688

689**Server not starting**:

690

6911. Check the command exists and is executable

6922. Verify all paths use `${CLAUDE_PLUGIN_ROOT}` variable

6933. Check the MCP server logs: `claude --debug` shows initialization errors

6944. Test the server manually outside of Claude Code

695

696**Server tools not appearing**:

697

6981. Ensure the server is properly configured in `.mcp.json` or `plugin.json`

6992. Verify the server implements the MCP protocol correctly

7003. Check for connection timeouts in debug output

701

702### Directory structure mistakes

703

704**Symptoms**: Plugin loads but components (commands, agents, hooks) are missing.

705

706**Correct structure**: Components must be at the plugin root, not inside `.claude-plugin/`. Only `plugin.json` belongs in `.claude-plugin/`.

707

708```

709my-plugin/

710├── .claude-plugin/

711│ └── plugin.json ← Only manifest here

712├── commands/ ← At root level

713├── agents/ ← At root level

714└── hooks/ ← At root level

715```

716

717If your components are inside `.claude-plugin/`, move them to the plugin root.

718

719**Debug checklist**:

720

7211. Run `claude --debug` and look for "loading plugin" messages

7222. Check that each component directory is listed in the debug output

7233. Verify file permissions allow reading the plugin files

355 724

356***725***

357 726

362Follow semantic versioning for plugin releases:731Follow semantic versioning for plugin releases:

363 732

364```json theme={null}733```json theme={null}

734{

735 "name": "my-plugin",

736 "version": "2.1.0"

737}

738```

739

740**Version format**: `MAJOR.MINOR.PATCH`

741

742* **MAJOR**: Breaking changes (incompatible API changes)

743* **MINOR**: New features (backward-compatible additions)

744* **PATCH**: Bug fixes (backward-compatible fixes)

745

746**Best practices**:

747

748* Start at `1.0.0` for your first stable release

749* Update the version in `plugin.json` before distributing changes

750* Document changes in a `CHANGELOG.md` file

751* Use pre-release versions like `2.0.0-beta.1` for testing

752

753***

365 754

366## See also755## See also

367 756

368- [Plugins](/en/plugins) - Tutorials and practical usage757* [Plugins](/en/plugins) - Tutorials and practical usage

369- [Plugin marketplaces](/en/plugin-marketplaces) - Creating and managing marketplaces758* [Plugin marketplaces](/en/plugin-marketplaces) - Creating and managing marketplaces

370- [Slash commands](/en/slash-commands) - Command development details759* [Slash commands](/en/slash-commands) - Command development details

371- [Subagents](/en/sub-agents) - Agent configuration and capabilities760* [Subagents](/en/sub-agents) - Agent configuration and capabilities

372- [Agent Skills](/en/skills) - Extend Claude's capabilities761* [Agent Skills](/en/skills) - Extend Claude's capabilities

373- [Hooks](/en/hooks) - Event handling and automation762* [Hooks](/en/hooks) - Event handling and automation

374- [MCP](/en/mcp) - External tool integration763* [MCP](/en/mcp) - External tool integration

375- [Settings](/en/settings) - Configuration options for plugins764* [Settings](/en/settings) - Configuration options for plugins

376```765

766

767---

768

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

quickstart.md +23 −14

Details

18 18

19<Tabs>19<Tabs>

20 <Tab title="Native Install (Recommended)">20 <Tab title="Native Install (Recommended)">

~~21 **Homebrew (macOS, Linux):**~~

~~23 ```sh theme={null} theme={null} theme={null}~~

~~24 brew install --cask claude-code~~

~~25 ```~~

27 **macOS, Linux, WSL:**21 **macOS, Linux, WSL:**

28 22

~~29 ```bash theme={null} theme={null} theme={null}~~23 ```bash theme={null}

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

31 ```25 ```

32 26

33 **Windows PowerShell:**27 **Windows PowerShell:**

34 28

~~35 ```powershell theme={null} theme={null} theme={null}~~29 ```powershell theme={null}

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

37 ```31 ```

38 32

39 **Windows CMD:**33 **Windows CMD:**

40 34

~~41 ```batch theme={null} theme={null} theme={null}~~35 ```batch theme={null}

42 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd36 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

43 ```37 ```

44 </Tab>38 </Tab>

45 39

40 <Tab title="Homebrew">

41 ```sh theme={null}

42 brew install --cask claude-code

43 ```

44 </Tab>

46 <Tab title="NPM">46 <Tab title="NPM">

47 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):47 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):

48 48

~~49 ```sh theme={null} theme={null} theme={null}~~49 ```sh theme={null}

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

51 ```51 ```

52 </Tab>52 </Tab>

304Now that you've learned the basics, explore more advanced features:304Now that you've learned the basics, explore more advanced features:

305 305

306<CardGroup cols={3}>306<CardGroup cols={3}>

307 <Card title="Common workflows" icon="graduation-cap" href="/en/docs/claude-code/common-workflows">307 <Card title="Common workflows" icon="graduation-cap" href="/en/common-workflows">

308 Step-by-step guides for common tasks308 Step-by-step guides for common tasks

309 </Card>309 </Card>

310 310

311 <Card title="CLI reference" icon="terminal" href="/en/docs/claude-code/cli-reference">311 <Card title="CLI reference" icon="terminal" href="/en/cli-reference">

312 Master all commands and options312 Master all commands and options

313 </Card>313 </Card>

314 314

315 <Card title="Configuration" icon="gear" href="/en/docs/claude-code/settings">315 <Card title="Configuration" icon="gear" href="/en/settings">

316 Customize Claude Code for your workflow316 Customize Claude Code for your workflow

317 </Card>317 </Card>

318 318

319 <Card title="Claude Code on the web" icon="cloud" href="/en/docs/claude-code/claude-code-on-the-web">319 <Card title="Claude Code on the web" icon="cloud" href="/en/claude-code-on-the-web">

320 Run tasks asynchronously in the cloud320 Run tasks asynchronously in the cloud

321 </Card>321 </Card>

322

323 <Card title="About Claude Code" icon="sparkles" href="https://claude.com/product/claude-code">

324 Learn more on claude.com

325 </Card>

322</CardGroup>326</CardGroup>

323 327

324## Getting help328## Getting help

326* **In Claude Code**: Type `/help` or ask "how do I..."330* **In Claude Code**: Type `/help` or ask "how do I..."

327* **Documentation**: You're here! Browse other guides331* **Documentation**: You're here! Browse other guides

328* **Community**: Join our [Discord](https://www.anthropic.com/discord) for tips and support332* **Community**: Join our [Discord](https://www.anthropic.com/discord) for tips and support

333

334

335---

336

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

sandboxing.md +21 −2

Details

66> /sandbox66> /sandbox

67```67```

68 68

~~69This activates the sandboxed bash tool with default settings, allowing access to your current working directory while blocking access to sensitive system locations.~~69This opens a menu where you can choose between sandbox modes.

71### Sandbox modes

73Claude Code offers two sandbox modes:

75**Auto-allow mode**: Bash commands will attempt to run inside the sandbox and are automatically allowed without requiring permission. Commands that cannot be sandboxed (such as those needing network access to non-allowed hosts) fall back to the regular permission flow. Explicit ask/deny rules you've configured are always respected.

77**Regular permissions mode**: All bash commands go through the standard permission flow, even when sandboxed. This provides more control but requires more approvals.

79In both modes, the sandbox enforces the same filesystem and network restrictions. The difference is only in whether sandboxed commands are auto-approved or require explicit permission.

81<Info>

82 Auto-allow mode works independently of your permission mode setting. Even if you're not in "accept edits" mode, sandboxed bash commands will run automatically when auto-allow is enabled. This means bash commands that modify files within the sandbox boundaries will execute without prompting, even when file edit tools would normally require approval.

83</Info>

70 84

71### Configure sandboxing85### Configure sandboxing

72 86

141 155

142* Privilege Escalation via Unix Sockets: The `allowUnixSockets` configuration can inadvertently grant access to powerful system services that could lead to sandbox bypasses. For example, if it is used to allow access to `/var/run/docker.sock` this would effectively grant access to the host system through exploiting the docker socket. Users are encouraged to carefully consider any unix sockets that they allow through the sandbox.156* Privilege Escalation via Unix Sockets: The `allowUnixSockets` configuration can inadvertently grant access to powerful system services that could lead to sandbox bypasses. For example, if it is used to allow access to `/var/run/docker.sock` this would effectively grant access to the host system through exploiting the docker socket. Users are encouraged to carefully consider any unix sockets that they allow through the sandbox.

143* Filesystem Permission Escalation: Overly broad filesystem write permissions can enable privilege escalation attacks. Allowing writes to directories containing executables in `$PATH`, system configuration directories, or user shell configuration files (`.bashrc`, `.zshrc`) can lead to code execution in different security contexts when other users or system processes access these files.157* Filesystem Permission Escalation: Overly broad filesystem write permissions can enable privilege escalation attacks. Allowing writes to directories containing executables in `$PATH`, system configuration directories, or user shell configuration files (`.bashrc`, `.zshrc`) can lead to code execution in different security contexts when other users or system processes access these files.

144* Linux Sandbox Strength: The Linux implementation provides strong filesystem and network isolation but includes an `enableWeakerNestedSandbox` mode that enables it to work inside of Docker environments without privileged namespaces. This option considerably weakens security and should only be used incases where additional isolation is otherwise enforced.158* Linux Sandbox Strength: The Linux implementation provides strong filesystem and network isolation but includes an `enableWeakerNestedSandbox` mode that enables it to work inside of Docker environments without privileged namespaces. This option considerably weakens security and should only be used in cases where additional isolation is otherwise enforced.

145 159

146## Advanced usage160## Advanced usage

147 161

203* [IAM](/en/iam) - Permission configuration and access control217* [IAM](/en/iam) - Permission configuration and access control

204* [Settings](/en/settings) - Complete configuration reference218* [Settings](/en/settings) - Complete configuration reference

205* [CLI reference](/en/cli-reference) - Command-line options including `-sb`219* [CLI reference](/en/cli-reference) - Command-line options including `-sb`

220

221

222---

223

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

sdk/migration-guide.md +0 −327 deleted

File DeletedView Diff

~~1# Migrate to Claude Agent SDK~~

~~3> Guide for migrating the Claude Code TypeScript and Python SDKs to the Claude Agent SDK~~

~~5## Overview~~

7The Claude Code SDK has been renamed to the **Claude Agent SDK** and its documentation has been reorganized. This change reflects the SDK's broader capabilities for building AI agents beyond just coding tasks.

~~9## What's Changed~~

~~11| Aspect | Old | New |~~

~~12| :------------------------- | :----------------------------- | :------------------------------- |~~

~~13| **Package Name (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |~~

~~14| **Python Package** | `claude-code-sdk` | `claude-agent-sdk` |~~

~~15| **Documentation Location** | Claude Code docs → SDK section | API Guide → Agent SDK section |~~

~~17<Note>~~

18 **Documentation Changes:** The Agent SDK documentation has moved from the Claude Code docs to the API Guide under a dedicated [Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) section. The Claude Code docs now focus on the CLI tool and automation features.

~~19</Note>~~

~~21## Migration Steps~~

~~23### For TypeScript/JavaScript Projects~~

~~25**1. Uninstall the old package:**~~

~~27```bash theme={null}~~

~~28npm uninstall @anthropic-ai/claude-code~~

~~29```~~

~~31**2. Install the new package:**~~

~~33```bash theme={null}~~

~~34npm install @anthropic-ai/claude-agent-sdk~~

~~35```~~

~~37**3. Update your imports:**~~

~~39Change all imports from `@anthropic-ai/claude-code` to `@anthropic-ai/claude-agent-sdk`:~~

~~41```typescript theme={null}~~

~~42// Before~~

~~43import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";~~

~~45// After~~

~~46import {~~

~~47 query,~~

~~48 tool,~~

~~49 createSdkMcpServer,~~

~~50} from "@anthropic-ai/claude-agent-sdk";~~

~~51```~~

~~53**4. Update package.json dependencies:**~~

~~55If you have the package listed in your `package.json`, update it:~~

~~57```json theme={null}~~

~~58// Before~~

~~59{~~

~~60 "dependencies": {~~

~~61 "@anthropic-ai/claude-code": "^1.0.0"~~

~~62 }~~

~~63}~~

~~65// After~~

~~66{~~

~~67 "dependencies": {~~

~~68 "@anthropic-ai/claude-agent-sdk": "^0.1.0"~~

~~69 }~~

~~70}~~

~~71```~~

~~73That's it! No other code changes are required.~~

~~75### For Python Projects~~

~~77**1. Uninstall the old package:**~~

~~79```bash theme={null}~~

~~80pip uninstall claude-code-sdk~~

~~81```~~

~~83**2. Install the new package:**~~

~~85```bash theme={null}~~

~~86pip install claude-agent-sdk~~

~~87```~~

~~89**3. Update your imports:**~~

~~91Change all imports from `claude_code_sdk` to `claude_agent_sdk`:~~

~~93```python theme={null}~~

~~94# Before~~

~~95from claude_code_sdk import query, ClaudeCodeOptions~~

~~97# After~~

~~98from claude_agent_sdk import query, ClaudeAgentOptions~~

~~99```~~

~~100~~

101**4. Update type names:**

~~102~~

103Change `ClaudeCodeOptions` to `ClaudeAgentOptions`:

~~104~~

105```python theme={null}

106# Before

107from claude_agent_sdk import query, ClaudeCodeOptions

~~108~~

109options = ClaudeCodeOptions(

110 model="claude-sonnet-4-5"

111)

~~112~~

113# After

114from claude_agent_sdk import query, ClaudeAgentOptions

~~115~~

116options = ClaudeAgentOptions(

117 model="claude-sonnet-4-5"

118)

119```

~~120~~

121**5. Review [breaking changes](#breaking-changes)**

~~122~~

123Make any code changes needed to complete the migration.

~~124~~

125## Breaking changes

~~126~~

127<Warning>

128 To improve isolation and explicit configuration, Claude Agent SDK v0.1.0 introduces breaking changes for users migrating from Claude Code SDK. Review this section carefully before migrating.

129</Warning>

~~130~~

131### Python: ClaudeCodeOptions renamed to ClaudeAgentOptions

~~132~~

133**What changed:** The Python SDK type `ClaudeCodeOptions` has been renamed to `ClaudeAgentOptions`.

~~134~~

135**Migration:**

~~136~~

137```python theme={null}

138# BEFORE (v0.0.x)

139from claude_agent_sdk import query, ClaudeCodeOptions

~~140~~

141options = ClaudeCodeOptions(

142 model="claude-sonnet-4-5",

143 permission_mode="acceptEdits"

144)

~~145~~

146# AFTER (v0.1.0)

147from claude_agent_sdk import query, ClaudeAgentOptions

~~148~~

149options = ClaudeAgentOptions(

150 model="claude-sonnet-4-5",

151 permission_mode="acceptEdits"

152)

153```

~~154~~

155**Why this changed:** The type name now matches the "Claude Agent SDK" branding and provides consistency across the SDK's naming conventions.

~~156~~

157### System prompt no longer default

~~158~~

159**What changed:** The SDK no longer uses Claude Code's system prompt by default.

~~160~~

161**Migration:**

~~162~~

163<CodeGroup>

164 ```typescript TypeScript theme={null}

165 // BEFORE (v0.0.x) - Used Claude Code's system prompt by default

166 const result = query({ prompt: "Hello" });

~~167~~

168 // AFTER (v0.1.0) - Uses empty system prompt by default

169 // To get the old behavior, explicitly request Claude Code's preset:

170 const result = query({

171 prompt: "Hello",

172 options: {

173 systemPrompt: { type: "preset", preset: "claude_code" }

174 }

175 });

~~176~~

177 // Or use a custom system prompt:

178 const result = query({

179 prompt: "Hello",

180 options: {

181 systemPrompt: "You are a helpful coding assistant"

182 }

183 });

184 ```

~~185~~

186 ```python Python theme={null}

187 # BEFORE (v0.0.x) - Used Claude Code's system prompt by default

188 async for message in query(prompt="Hello"):

189 print(message)

~~190~~

191 # AFTER (v0.1.0) - Uses empty system prompt by default

192 # To get the old behavior, explicitly request Claude Code's preset:

193 from claude_agent_sdk import query, ClaudeAgentOptions

~~194~~

195 async for message in query(

196 prompt="Hello",

197 options=ClaudeAgentOptions(

198 system_prompt={"type": "preset", "preset": "claude_code"} # Use the preset

199 )

200 ):

201 print(message)

~~202~~

203 # Or use a custom system prompt:

204 async for message in query(

205 prompt="Hello",

206 options=ClaudeAgentOptions(

207 system_prompt="You are a helpful coding assistant"

208 )

209 ):

210 print(message)

211 ```

212</CodeGroup>

~~213~~

214**Why this changed:** Provides better control and isolation for SDK applications. You can now build agents with custom behavior without inheriting Claude Code's CLI-focused instructions.

~~215~~

216### Settings Sources No Longer Loaded by Default

~~217~~

218**What changed:** The SDK no longer reads from filesystem settings (CLAUDE.md, settings.json, slash commands, etc.) by default.

~~219~~

220**Migration:**

~~221~~

222<CodeGroup>

223 ```typescript TypeScript theme={null}

224 // BEFORE (v0.0.x) - Loaded all settings automatically

225 const result = query({ prompt: "Hello" });

226 // Would read from:

227 // - ~/.claude/settings.json (user)

228 // - .claude/settings.json (project)

229 // - .claude/settings.local.json (local)

230 // - CLAUDE.md files

231 // - Custom slash commands

~~232~~

233 // AFTER (v0.1.0) - No settings loaded by default

234 // To get the old behavior:

235 const result = query({

236 prompt: "Hello",

237 options: {

238 settingSources: ["user", "project", "local"]

239 }

240 });

~~241~~

242 // Or load only specific sources:

243 const result = query({

244 prompt: "Hello",

245 options: {

246 settingSources: ["project"] // Only project settings

247 }

248 });

249 ```

~~250~~

251 ```python Python theme={null}

252 # BEFORE (v0.0.x) - Loaded all settings automatically

253 async for message in query(prompt="Hello"):

254 print(message)

255 # Would read from:

256 # - ~/.claude/settings.json (user)

257 # - .claude/settings.json (project)

258 # - .claude/settings.local.json (local)

259 # - CLAUDE.md files

260 # - Custom slash commands

~~261~~

262 # AFTER (v0.1.0) - No settings loaded by default

263 # To get the old behavior:

264 from claude_agent_sdk import query, ClaudeAgentOptions

~~265~~

266 async for message in query(

267 prompt="Hello",

268 options=ClaudeAgentOptions(

269 setting_sources=["user", "project", "local"]

270 )

271 ):

272 print(message)

~~273~~

274 # Or load only specific sources:

275 async for message in query(

276 prompt="Hello",

277 options=ClaudeAgentOptions(

278 setting_sources=["project"] # Only project settings

279 )

280 ):

281 print(message)

282 ```

283</CodeGroup>

~~284~~

285**Why this changed:** Ensures SDK applications have predictable behavior independent of local filesystem configurations. This is especially important for:

~~286~~

287* **CI/CD environments** - Consistent behavior without local customizations

288* **Deployed applications** - No dependency on filesystem settings

289* **Testing** - Isolated test environments

290* **Multi-tenant systems** - Prevent settings leakage between users

~~291~~

292<Note>

293 **Backward compatibility:** If your application relied on filesystem settings (custom slash commands, CLAUDE.md instructions, etc.), add `settingSources: ['user', 'project', 'local']` to your options.

294</Note>

~~295~~

296## Why the Rename?

~~297~~

298The Claude Code SDK was originally designed for coding tasks, but it has evolved into a powerful framework for building all types of AI agents. The new name "Claude Agent SDK" better reflects its capabilities:

~~299~~

300* Building business agents (legal assistants, finance advisors, customer support)

301* Creating specialized coding agents (SRE bots, security reviewers, code review agents)

302* Developing custom agents for any domain with tool use, MCP integration, and more

~~303~~

304## Getting Help

~~305~~

306If you encounter any issues during migration:

~~307~~

308**For TypeScript/JavaScript:**

~~309~~

3101. Check that all imports are updated to use `@anthropic-ai/claude-agent-sdk`

3112. Verify your package.json has the new package name

3123. Run `npm install` to ensure dependencies are updated

~~313~~

314**For Python:**

~~315~~

3161. Check that all imports are updated to use `claude_agent_sdk`

3172. Verify your requirements.txt or pyproject.toml has the new package name

3183. Run `pip install claude-agent-sdk` to ensure the package is installed

~~319~~

320See the [Troubleshooting](/en/troubleshooting) guide for common issues.

~~321~~

322## Next Steps

~~323~~

324* Explore the [Agent SDK Overview](https://docs.claude.com/en/api/agent-sdk/overview) to learn about available features

325* Check out the [TypeScript SDK Reference](https://docs.claude.com/en/api/agent-sdk/typescript) for detailed API documentation

326* Review the [Python SDK Reference](https://docs.claude.com/en/api/agent-sdk/python) for Python-specific documentation

327* Learn about [Custom Tools](https://docs.claude.com/en/api/agent-sdk/custom-tools) and [MCP Integration](https://docs.claude.com/en/api/agent-sdk/mcp)

security.md +7 −2

Details

87 87

88## IDE security88## IDE security

89 89

~~90See [here](/en/ide-integrations#security) for more information on the security of running Claude Code in an IDE.~~90See [here](/en/vs-code#security) for more information on the security of running Claude Code in an IDE.

91 91

92## Cloud execution security92## Cloud execution security

93 93

113 113

114### Team security114### Team security

115 115

116* Use [enterprise managed policies](/en/iam#enterprise-managed-policy-settings) to enforce organizational standards116* Use [enterprise managed settings](/en/iam#enterprise-managed-settings) to enforce organizational standards

117* Share approved permission configurations through version control117* Share approved permission configurations through version control

118* Train team members on security best practices118* Train team members on security best practices

119* Monitor Claude Code usage through [OpenTelemetry metrics](/en/monitoring-usage)119* Monitor Claude Code usage through [OpenTelemetry metrics](/en/monitoring-usage)

134* [Monitoring usage](/en/monitoring-usage) - Track and audit Claude Code activity134* [Monitoring usage](/en/monitoring-usage) - Track and audit Claude Code activity

135* [Development containers](/en/devcontainer) - Secure, isolated environments135* [Development containers](/en/devcontainer) - Secure, isolated environments

136* [Anthropic Trust Center](https://trust.anthropic.com) - Security certifications and compliance136* [Anthropic Trust Center](https://trust.anthropic.com) - Security certifications and compliance

137

138

139---

140

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

settings.md +495 −59

Details

4 4

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

6 6

7## Configuration scopes

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

11### Available scopes

14| :------------- | :----------------------------------- | :----------------------------------- | :--------------------- |

18| **Local** | `.claude/*.local.*` files | You, in this repository only | No (gitignored) |

20### When to use each scope

22**Enterprise scope** is for:

24* Security policies that must be enforced organization-wide

25* Compliance requirements that can't be overridden

26* Standardized configurations deployed by IT/DevOps

28**User scope** is best for:

30* Personal preferences you want everywhere (themes, editor settings)

31* Tools and plugins you use across all projects

32* API keys and authentication (stored securely)

34**Project scope** is best for:

36* Team-shared settings (permissions, hooks, MCP servers)

37* Plugins the whole team should have

38* Standardizing tooling across collaborators

40**Local scope** is best for:

42* Personal overrides for a specific project

43* Testing configurations before sharing with the team

44* Machine-specific settings that won't work for others

46### How scopes interact

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

501. **Enterprise** (highest) - can't be overridden by anything

512. **Command line arguments** - temporary session overrides

523. **Local** - overrides project and user settings

534. **Project** - overrides user settings

545. **User** (lowest) - applies when nothing else specifies the setting

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

58### What uses scopes

60Scopes apply to many Claude Code features:

63| :-------------- | :------------------------ | :--------------------------------- | :----------------------------- |

70***

7## Settings files72## Settings files

8 73

9The `settings.json` file is our official mechanism for configuring Claude74The `settings.json` file is our official mechanism for configuring Claude

14* **Project settings** are saved in your project directory:79* **Project settings** are saved in your project directory:

15 * `.claude/settings.json` for settings that are checked into source control and shared with your team80 * `.claude/settings.json` for settings that are checked into source control and shared with your team

16 * `.claude/settings.local.json` for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore `.claude/settings.local.json` when it is created.81 * `.claude/settings.local.json` for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore `.claude/settings.local.json` when it is created.

~~17* For enterprise deployments of Claude Code, we also support **enterprise~~82* **Managed settings** (Enterprise): Enterprise administrators can configure and distribute Claude Code settings to their organization through the [Claude.ai admin console](https://claude.ai/admin-settings/claude-code). These settings are fetched automatically when users authenticate, take precedence over user and project settings, and cannot be overridden locally. This feature is available to Claude for Enterprise customers. If you don't see this option in your admin console, contact your Anthropic account team to have the feature enabled.

~~18 managed policy settings**. These take precedence over user and project~~83

~~19 settings. System administrators can deploy policies to:~~84 For organizations that prefer file-based policy distribution, Claude Code also supports `managed-settings.json` and `managed-mcp.json` files that can be deployed to system directories:

~~20 * macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`~~85

~~21 * Linux and WSL: `/etc/claude-code/managed-settings.json`~~86 * macOS: `/Library/Application Support/ClaudeCode/`

~~22 * Windows: `C:\ProgramData\ClaudeCode\managed-settings.json`~~87 * Linux and WSL: `/etc/claude-code/`

~~23* Enterprise deployments can also configure **managed MCP servers** that override~~88 * Windows: `C:\Program Files\ClaudeCode\`

~~24 user-configured servers. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration):~~89

~~25 * macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`~~90 <Note>

~~26 * Linux and WSL: `/etc/claude-code/managed-mcp.json`~~91 These are system-wide paths (not user home directories like `~/Library/...`) that require administrator privileges. They are designed to be deployed by IT administrators.

~~27 * Windows: `C:\ProgramData\ClaudeCode\managed-mcp.json`~~92 </Note>

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

96 <Note>

97 Enterprise deployments can also restrict **plugin marketplace additions** using

98 `strictKnownMarketplaces`. For more information, see [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions).

99 </Note>

100* **Other configuration** is stored in `~/.claude.json`. This file contains your preferences (theme, notification settings, editor mode), OAuth session, [MCP server](/en/mcp) configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in `.mcp.json`.

28 101

29```JSON Example settings.json theme={null}102```JSON Example settings.json theme={null}

30{103{

58`settings.json` supports a number of options:131`settings.json` supports a number of options:

59 132

60| Key | Description | Example |133| Key | Description | Example |

61| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |134| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- |

62| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests | `/bin/generate_temp_api_key.sh` |135| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests | `/bin/generate_temp_api_key.sh` |

63| `cleanupPeriodDays` | How long to locally retain chat transcripts based on last activity date (default: 30 days) | `20` |136| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup. Setting to `0` immediately deletes all sessions. (default: 30 days) | `20` |

64| `companyAnnouncements` | Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |137| `companyAnnouncements` | Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |

65| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |138| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |

66| `includeCoAuthoredBy` | Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |139| `attribution` | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

140| `includeCoAuthoredBy` | **Deprecated**: Use `attribution` instead. Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |

68| `hooks` | Configure custom commands to run before or after tool executions. See [hooks documentation](hooks) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |142| `hooks` | Configure custom commands to run before or after tool executions. See [hooks documentation](/en/hooks) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |

144| `allowManagedHooksOnly` | (Enterprise) Prevent loading of user, project, and plugin hooks. Only allows managed hooks and SDK hooks. See [Hook configuration](#hook-configuration) | `true` |

71| `statusLine` | Configure a custom status line to display context. See [statusLine documentation](statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |146| `otelHeadersHelper` | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically (see [Dynamic headers](/en/monitoring-usage#dynamic-headers)) | `/bin/generate_otel_headers.sh` |

72| `outputStyle` | Configure an output style to adjust the system prompt. See [output styles documentation](output-styles) | `"Explanatory"` |147| `statusLine` | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |

148| `fileSuggestion` | Configure a custom script for `@` file autocomplete. See [File suggestion settings](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

149| `outputStyle` | Configure an output style to adjust the system prompt. See [output styles documentation](/en/output-styles) | `"Explanatory"` |

74| `forceLoginOrgUUID` | Specify the UUID of an organization to automatically select it during login, bypassing the organization selection step. Requires `forceLoginMethod` to be set | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |151| `forceLoginOrgUUID` | Specify the UUID of an organization to automatically select it during login, bypassing the organization selection step. Requires `forceLoginMethod` to be set | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |

78| `allowedMcpServers` | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "github" }]` |155| `allowedMcpServers` | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "github" }]` |

79| `deniedMcpServers` | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including enterprise servers. Denylist takes precedence over allowlist. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "filesystem" }]` |156| `deniedMcpServers` | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including enterprise servers. Denylist takes precedence over allowlist. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "filesystem" }]` |

157| `strictKnownMarketplaces` | When set in managed-settings.json, allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

80| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |158| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

81| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |159| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

160| `alwaysThinkingEnabled` | Enable [extended thinking](/en/common-workflows#use-extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly | `true` |

82 161

83### Permission settings162### Permission settings

84 163

87| `allow` | Array of [permission rules](/en/iam#configuring-permissions) to allow tool use. **Note:** Bash rules use prefix matching, not regex | `[ "Bash(git diff:*)" ]` |166| `allow` | Array of [permission rules](/en/iam#configuring-permissions) to allow tool use. **Note:** Bash rules use prefix matching, not regex | `[ "Bash(git diff:*)" ]` |

88| `ask` | Array of [permission rules](/en/iam#configuring-permissions) to ask for confirmation upon tool use. | `[ "Bash(git push:*)" ]` |167| `ask` | Array of [permission rules](/en/iam#configuring-permissions) to ask for confirmation upon tool use. | `[ "Bash(git push:*)" ]` |

89| `deny` | Array of [permission rules](/en/iam#configuring-permissions) to deny tool use. Use this to also exclude sensitive files from Claude Code access. **Note:** Bash patterns are prefix matches and can be bypassed (see [Bash permission limitations](/en/iam#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |168| `deny` | Array of [permission rules](/en/iam#configuring-permissions) to deny tool use. Use this to also exclude sensitive files from Claude Code access. **Note:** Bash patterns are prefix matches and can be bypassed (see [Bash permission limitations](/en/iam#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |

92| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed policy settings](iam#enterprise-managed-policy-settings) | `"disable"` |171| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed settings](/en/iam#enterprise-managed-settings) | `"disable"` |

93 172

94### Sandbox settings173### Sandbox settings

95 174

105| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |184| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |

108| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |187| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |

109| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |188| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |

133}212}

134```213```

135 214

136**Filesystem access** is controlled via Read/Edit permissions:215**Filesystem and network restrictions** use standard permission rules:

216

217* Use `Read` deny rules to block Claude from reading specific files or directories

218* Use `Edit` allow rules to let Claude write to directories beyond the current working directory

219* Use `Edit` deny rules to block writes to specific paths

220* Use `WebFetch` allow/deny rules to control which network domains Claude can access

221

222### Attribution settings

223

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

225

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

227* Pull request descriptions are plain text

228

229| Keys | Description |

230| :------- | :----------------------------------------------------------------------------------------- |

231| `commit` | Attribution for git commits, including any trailers. Empty string hides commit attribution |

232| `pr` | Attribution for pull request descriptions. Empty string hides pull request attribution |

233

234**Default commit attribution:**

235

236```

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

238

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

240```

241

242**Default pull request attribution:**

243

244```

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

246```

247

248**Example:**

249

250```json theme={null}

251{

252 "attribution": {

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

254 "pr": ""

255 }

256}

257```

258

259<Note>

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

261</Note>

262

263### File suggestion settings

264

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

266

267```json theme={null}

268{

269 "fileSuggestion": {

270 "type": "command",

271 "command": "~/.claude/file-suggestion.sh"

272 }

273}

274```

275

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

137 277

138* Read deny rules block file reads in sandbox278```json theme={null}

139* Edit allow rules permit file writes (in addition to the defaults, e.g. the current working directory)279{"query": "src/comp"}

140* Edit deny rules block writes within allowed paths280```

141 281

142**Network access** is controlled via WebFetch permissions:282Output newline-separated file paths to stdout (currently limited to 15):

143 283

144* WebFetch allow rules permit network domains284```

145* WebFetch deny rules block network domains285src/components/Button.tsx

286src/components/Modal.tsx

287src/components/Form.tsx

288```

289

290**Example:**

291

292```bash theme={null}

293#!/bin/bash

294query=$(cat | jq -r '.query')

295your-repo-file-index --query "$query" | head -20

296```

297

298### Hook configuration

299

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

301

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

303

304* Managed hooks and SDK hooks are loaded

305* User hooks, project hooks, and plugin hooks are blocked

306

307**Configuration:**

308

309```json theme={null}

310{

311 "allowManagedHooksOnly": true

312}

313```

146 314

147### Settings precedence315### Settings precedence

148 316

149Settings are applied in order of precedence (highest to lowest):317Settings apply in order of precedence. From highest to lowest:

150 318

1511. **Enterprise managed policies** (`managed-settings.json`)3191. **Managed settings** (Enterprise)

152 * Deployed by IT/DevOps320 * Remote settings configured via the [Claude.ai admin console](https://claude.ai/admin-settings/claude-code)

321 * Fetched automatically when users authenticate

153 * Cannot be overridden322 * Cannot be overridden

154 323

1552. **Command line arguments**3242. **File-based managed settings** (`managed-settings.json`)

325 * Policies deployed by IT/DevOps to system directories

326 * Cannot be overridden by user or project settings

327 * Ignored when remote managed settings are configured

328

3293. **Command line arguments**

156 * Temporary overrides for a specific session330 * Temporary overrides for a specific session

157 331

1583. **Local project settings** (`.claude/settings.local.json`)3324. **Local project settings** (`.claude/settings.local.json`)

159 * Personal project-specific settings333 * Personal project-specific settings

160 334

1614. **Shared project settings** (`.claude/settings.json`)3355. **Shared project settings** (`.claude/settings.json`)

162 * Team-shared project settings in source control336 * Team-shared project settings in source control

163 337

1645. **User settings** (`~/.claude/settings.json`)3386. **User settings** (`~/.claude/settings.json`)

165 * Personal global settings339 * Personal global settings

166 340

167This hierarchy ensures that enterprise security policies are always enforced while still allowing teams and individuals to customize their experience.341This hierarchy ensures that enterprise security policies are always enforced while still allowing teams and individuals to customize their experience.

168 342

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

344

169### Key points about the configuration system345### Key points about the configuration system

170 346

171* **Memory files (CLAUDE.md)**: Contain instructions and context that Claude loads at startup347* **Memory files (`CLAUDE.md`)**: Contain instructions and context that Claude loads at startup

172* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior348* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior

173* **Slash commands**: Custom commands that can be invoked during a session with `/command-name`349* **Slash commands**: Custom commands that can be invoked during a session with `/command-name`

174* **MCP servers**: Extend Claude Code with additional tools and integrations350* **MCP servers**: Extend Claude Code with additional tools and integrations

175* **Precedence**: Higher-level configurations (Enterprise) override lower-level ones (User/Project)351* **Precedence**: Higher-level configurations (Enterprise) override lower-level ones (User/Project)

176* **Inheritance**: Settings are merged, with more specific settings adding to or overriding broader ones352* **Inheritance**: Settings are merged, with more specific settings adding to or overriding broader ones

177 353

178### System prompt availability354### System prompt

179 355

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

181 Unlike for claude.ai, we do not publish Claude Code's internal system prompt on this website. Use CLAUDE.md files or `--append-system-prompt` to add custom instructions to Claude Code's behavior.

182</Note>

183 357

184### Excluding sensitive files358### Excluding sensitive files

185 359

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

187 361

188```json theme={null}362```json theme={null}

189{363{

221```json theme={null}395```json theme={null}

222{396{

223 "enabledPlugins": {397 "enabledPlugins": {

224 "formatter@company-tools": true,398 "formatter@acme-tools": true,

225 "deployer@company-tools": true,399 "deployer@acme-tools": true,

226 "analyzer@security-plugins": false400 "analyzer@security-plugins": false

227 },401 },

228 "extraKnownMarketplaces": {402 "extraKnownMarketplaces": {

229 "company-tools": {403 "acme-tools": {

230 "source": "github",404 "source": "github",

231 "repo": "company/claude-plugins"405 "repo": "acme-corp/claude-plugins"

232 }406 }

233 }407 }

234}408}

272```json theme={null}446```json theme={null}

273{447{

274 "extraKnownMarketplaces": {448 "extraKnownMarketplaces": {

275 "company-tools": {449 "acme-tools": {

276 "source": {450 "source": {

277 "source": "github",451 "source": "github",

278 "repo": "company-org/claude-plugins"452 "repo": "acme-corp/claude-plugins"

279 }453 }

280 },454 },

281 "security-plugins": {455 "security-plugins": {

282 "source": {456 "source": {

283 "source": "git",457 "source": "git",

284 "url": "https://git.company.com/security/plugins.git"458 "url": "https://git.example.com/security/plugins.git"

285 }459 }

286 }460 }

287 }461 }

294* `git`: Any git URL (uses `url`)468* `git`: Any git URL (uses `url`)

295* `directory`: Local filesystem path (uses `path`, for development only)469* `directory`: Local filesystem path (uses `path`, for development only)

296 470

471#### `strictKnownMarketplaces`

472

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

474

475**Managed settings file locations**:

476

477* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`

478* **Linux and WSL**: `/etc/claude-code/managed-settings.json`

479* **Windows**: `C:\ProgramData\ClaudeCode\managed-settings.json`

480

481**Key characteristics**:

482

483* Only available in enterprise managed settings (`managed-settings.json`)

484* Cannot be overridden by user or project settings (highest precedence)

485* Enforced BEFORE network/filesystem operations (blocked sources never execute)

486* Uses exact matching for source specifications (including `ref`, `path` for git sources)

487

488**Allowlist behavior**:

489

490* `undefined` (default): No restrictions - users can add any marketplace

491* Empty array `[]`: Complete lockdown - users cannot add any new marketplaces

492* List of sources: Users can only add marketplaces that match exactly

493

494**All supported source types**:

495

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

497

4981. **GitHub repositories**:

499

500```json theme={null}

501{ "source": "github", "repo": "acme-corp/approved-plugins" }

502{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }

503{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }

504```

505

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

507

5082. **Git repositories**:

509

510```json theme={null}

511{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }

512{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }

513{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }

514```

515

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

517

5183. **URL-based marketplaces**:

519

520```json theme={null}

521{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }

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

523```

524

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

526

5274. **NPM packages**:

528

529```json theme={null}

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

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

532```

533

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

535

5365. **File paths**:

537

538```json theme={null}

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

540{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

541```

542

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

544

5456. **Directory paths**:

546

547```json theme={null}

548{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }

549{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

550```

551

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

553

554**Configuration examples**:

555

556Example - Allow specific marketplaces only:

557

558```json theme={null}

559{

560 "strictKnownMarketplaces": [

561 {

562 "source": "github",

563 "repo": "acme-corp/approved-plugins"

564 },

565 {

566 "source": "github",

567 "repo": "acme-corp/security-tools",

568 "ref": "v2.0"

569 },

570 {

571 "source": "url",

572 "url": "https://plugins.example.com/marketplace.json"

573 },

574 {

575 "source": "npm",

576 "package": "@acme-corp/compliance-plugins"

577 }

578 ]

579}

580```

581

582Example - Disable all marketplace additions:

583

584```json theme={null}

585{

586 "strictKnownMarketplaces": []

587}

588```

589

590**Exact matching requirements**:

591

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

593

594* The `repo` or `url` must match exactly

595* The `ref` field must match exactly (or both be undefined)

596* The `path` field must match exactly (or both be undefined)

597

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

599

600```json theme={null}

601// These are DIFFERENT sources:

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

603{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

604

605// These are also DIFFERENT:

606{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }

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

608```

609

610**Comparison with `extraKnownMarketplaces`**:

611

612| Aspect | `strictKnownMarketplaces` | `extraKnownMarketplaces` |

613| --------------------- | ------------------------------------ | ------------------------------------ |

614| **Purpose** | Enterprise policy enforcement | Team convenience |

615| **Settings file** | `managed-settings.json` only | Any settings file |

616| **Behavior** | Blocks non-allowlisted additions | Auto-installs missing marketplaces |

617| **When enforced** | Before network/filesystem operations | After user trust prompt |

618| **Can be overridden** | No (highest precedence) | Yes (by higher precedence settings) |

619| **Source format** | Direct source object | Named marketplace with nested source |

620| **Use case** | Compliance, security restrictions | Onboarding, standardization |

621

622**Format difference**:

623

624`strictKnownMarketplaces` uses direct source objects:

625

626```json theme={null}

627{

628 "strictKnownMarketplaces": [

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

630 ]

631}

632```

633

634`extraKnownMarketplaces` requires named marketplaces:

635

636```json theme={null}

637{

638 "extraKnownMarketplaces": {

639 "acme-tools": {

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

641 }

642 }

643}

644```

645

646**Important notes**:

647

648* Restrictions are checked BEFORE any network requests or filesystem operations

649* When blocked, users see clear error messages indicating the source is blocked by enterprise policy

650* The restriction applies only to adding NEW marketplaces; previously installed marketplaces remain accessible

651* Enterprise managed settings have the highest precedence and cannot be overridden

652

653See [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions) for user-facing documentation.

654

297### Managing plugins655### Managing plugins

298 656

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

315</Note>673</Note>

316 674

317| Variable | Purpose |675| Variable | Purpose |

318| :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |676| :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

319| `ANTHROPIC_API_KEY` | API key sent as `X-Api-Key` header, typically for the Claude SDK (for interactive usage, run `/login`) |677| `ANTHROPIC_API_KEY` | API key sent as `X-Api-Key` header, typically for the Claude SDK (for interactive usage, run `/login`) |

320| `ANTHROPIC_AUTH_TOKEN` | Custom value for the `Authorization` header (the value you set here will be prefixed with `Bearer `) |678| `ANTHROPIC_AUTH_TOKEN` | Custom value for the `Authorization` header (the value you set here will be prefixed with `Bearer `) |

683| `ANTHROPIC_FOUNDRY_API_KEY` | API key for Microsoft Foundry authentication (see [Microsoft Foundry](/en/microsoft-foundry)) |

325| `ANTHROPIC_MODEL` | Name of the model setting to use (see [Model Configuration](/en/model-config#environment-variables)) |684| `ANTHROPIC_MODEL` | Name of the model setting to use (see [Model Configuration](/en/model-config#environment-variables)) |

696| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Set to `1` to disable Anthropic API-specific `anthropic-beta` headers. Use this if experiencing issues like "Unexpected value(s) for the `anthropic-beta` header" when using an LLM gateway with third-party providers |

337| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |697| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |

338| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |698| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |

341| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip AWS authentication for Bedrock (e.g. when using an LLM gateway) |701| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic OpenTelemetry headers in milliseconds (default: 1740000 / 29 minutes). See [Dynamic headers](/en/monitoring-usage#dynamic-headers) |

342| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (e.g. when using an LLM gateway) |702| `CLAUDE_CODE_SHELL_PREFIX` | Command prefix to wrap all bash commands (for example, for logging or auditing). Example: `/path/to/logger.sh` will execute `/path/to/logger.sh <command>` |

703| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip AWS authentication for Bedrock (for example, when using an LLM gateway) |

704| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) |

705| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (for example, when using an LLM gateway) |

708| `CLAUDE_CODE_USE_FOUNDRY` | Use [Microsoft Foundry](/en/microsoft-foundry) |

711| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic updates. |

358| `MAX_MCP_OUTPUT_TOKENS` | Maximum number of tokens allowed in MCP tool responses. Claude Code displays a warning when output exceeds 10,000 tokens (default: 25000) |723| `MAX_MCP_OUTPUT_TOKENS` | Maximum number of tokens allowed in MCP tool responses. Claude Code displays a warning when output exceeds 10,000 tokens (default: 25000) |

359| `MAX_THINKING_TOKENS` | Enable [extended thinking](/en/docs/build-with-claude/extended-thinking) and set the token budget for the thinking process. Extended thinking improves performance on complex reasoning and coding tasks but impacts [prompt caching efficiency](/en/docs/build-with-claude/prompt-caching#caching-with-thinking-blocks). Disabled by default. |724| `MAX_THINKING_TOKENS` | Enable [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) and set the token budget for the thinking process. Extended thinking improves performance on complex reasoning and coding tasks but impacts [prompt caching efficiency](https://docs.claude.com/en/docs/build-with-claude/prompt-caching#caching-with-thinking-blocks). Disabled by default. |

363| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum number of characters for slash command metadata shown to [SlashCommand tool](/en/slash-commands#slashcommand-tool) (default: 15000) |728| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum number of characters for slash command metadata shown to [SlashCommand tool](/en/slash-commands#slashcommand-tool) (default: 15000) |

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

374 739

376| :--------------- | :------------------------------------------------------------------ | :------------------ |741| :------------------ | :------------------------------------------------------------------------------------------------ | :------------------ |

377| **Bash** | Executes shell commands in your environment | Yes |742| **AskUserQuestion** | Asks the user multiple choice questions to gather information or clarify ambiguity | No |

743| **Bash** | Executes shell commands in your environment (see [Bash tool behavior](#bash-tool-behavior) below) | Yes |

744| **BashOutput** | Retrieves output from a background bash shell | No |

378| **Edit** | Makes targeted edits to specific files | Yes |745| **Edit** | Makes targeted edits to specific files | Yes |

746| **ExitPlanMode** | Prompts the user to exit plan mode and start coding | Yes |

379| **Glob** | Finds files based on pattern matching | No |747| **Glob** | Finds files based on pattern matching | No |

380| **Grep** | Searches for patterns in file contents | No |748| **Grep** | Searches for patterns in file contents | No |

749| **KillShell** | Kills a running background bash shell by its ID | No |

381| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |750| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |

382| **NotebookRead** | Reads and displays Jupyter notebook contents | No |

383| **Read** | Reads the contents of files | No |751| **Read** | Reads the contents of files | No |

752| **Skill** | Executes a skill within the main conversation | Yes |

384| **SlashCommand** | Runs a [custom slash command](/en/slash-commands#slashcommand-tool) | Yes |753| **SlashCommand** | Runs a [custom slash command](/en/slash-commands#slashcommand-tool) | Yes |

385| **Task** | Runs a sub-agent to handle complex, multi-step tasks | No |754| **Task** | Runs a sub-agent to handle complex, multi-step tasks | No |

386| **TodoWrite** | Creates and manages structured task lists | No |755| **TodoWrite** | Creates and manages structured task lists | No |

390 759

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

392 761

762### Bash tool behavior

763

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

765

766* **Working directory persists**: When Claude changes the working directory (for example, `cd /path/to/dir`), subsequent Bash commands will execute in that directory. You can use `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` to reset to the project directory after each command.

767* **Environment variables do NOT persist**: Environment variables set in one Bash command (for example, `export MY_VAR=value`) are **not** available in subsequent Bash commands. Each Bash command runs in a fresh shell environment.

768

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

770

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

772

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

774

775```bash theme={null}

776conda activate myenv

777# or: source /path/to/venv/bin/activate

778claude

779```

780

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

782

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

784

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

786

787```bash theme={null}

788export CLAUDE_ENV_FILE=/path/to/env-setup.sh

789claude

790```

791

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

793

794```bash theme={null}

795conda activate myenv

796# or: source /path/to/venv/bin/activate

797# or: export MY_VAR=value

798```

799

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

801

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

803

804Configure in `.claude/settings.json`:

805

806```json theme={null}

807{

808 "hooks": {

809 "SessionStart": [{

810 "matcher": "startup",

811 "hooks": [{

812 "type": "command",

813 "command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""

814 }]

815 }]

816 }

817}

818```

819

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

821

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

823

393### Extending tools with hooks824### Extending tools with hooks

394 825

395You can run custom commands before or after any tool executes using826You can run custom commands before or after any tool executes using

402## See also833## See also

403 834

404* [Identity and Access Management](/en/iam#configuring-permissions) - Learn about Claude Code's permission system835* [Identity and Access Management](/en/iam#configuring-permissions) - Learn about Claude Code's permission system

405* [IAM and access control](/en/iam#enterprise-managed-policy-settings) - Enterprise policy management836* [IAM and access control](/en/iam#enterprise-managed-settings) - Enterprise policy management

406* [Troubleshooting](/en/troubleshooting#auto-updater-issues) - Solutions for common configuration issues837* [Troubleshooting](/en/troubleshooting#auto-updater-issues) - Solutions for common configuration issues

838

839

840---

841

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

setup.md +113 −26

Details

5## System requirements5## System requirements

6 6

7* **Operating Systems**: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (with WSL 1, WSL 2, or Git for Windows)7* **Operating Systems**: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (with WSL 1, WSL 2, or Git for Windows)

~~8* **Hardware**: 4GB+ RAM~~8* **Hardware**: 4 GB+ RAM

~~9* **Software**: [Node.js 18+](https://nodejs.org/en/download) (only required for NPM installation)~~9* **Software**: [Node.js 18+](https://nodejs.org/en/download) (only required for npm installation)

10* **Network**: Internet connection required for authentication and AI processing10* **Network**: Internet connection required for authentication and AI processing

11* **Shell**: Works best in Bash, Zsh or Fish11* **Shell**: Works best in Bash, Zsh or Fish

12* **Location**: [Anthropic supported countries](https://www.anthropic.com/supported-countries)12* **Location**: [Anthropic supported countries](https://www.anthropic.com/supported-countries)

13 13

14### Additional dependencies14### Additional dependencies

15 15

~~16* **ripgrep**: Usually included with Claude Code. If search functionality fails, see [search troubleshooting](/en/troubleshooting#search-and-discovery-issues).~~16* **ripgrep**: Usually included with Claude Code. If search fails, see [search troubleshooting](/en/troubleshooting#search-and-discovery-issues).

17 17

18## Standard installation18## Standard installation

19 19

21 21

22<Tabs>22<Tabs>

23 <Tab title="Native Install (Recommended)">23 <Tab title="Native Install (Recommended)">

~~24 **Homebrew (macOS, Linux):**~~

~~26 ```sh theme={null} theme={null} theme={null}~~

~~27 brew install --cask claude-code~~

~~28 ```~~

30 **macOS, Linux, WSL:**24 **macOS, Linux, WSL:**

31 25

~~32 ```bash theme={null} theme={null} theme={null}~~26 ```bash theme={null}

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

34 ```28 ```

35 29

36 **Windows PowerShell:**30 **Windows PowerShell:**

37 31

~~38 ```powershell theme={null} theme={null} theme={null}~~32 ```powershell theme={null}

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

40 ```34 ```

41 35

42 **Windows CMD:**36 **Windows CMD:**

43 37

~~44 ```batch theme={null} theme={null} theme={null}~~38 ```batch theme={null}

45 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd39 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

46 ```40 ```

47 </Tab>41 </Tab>

48 42

43 <Tab title="Homebrew">

44 ```sh theme={null}

45 brew install --cask claude-code

46 ```

47 </Tab>

49 <Tab title="NPM">49 <Tab title="NPM">

50 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):50 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):

51 51

~~52 ```sh theme={null} theme={null} theme={null}~~52 ```sh theme={null}

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

54 ```54 ```

55 </Tab>55 </Tab>

68 68

69Claude Code offers the following authentication options:69Claude Code offers the following authentication options:

70 70

711. **Claude Console**: The default option. Connect through the Claude Console and complete the OAuth process. Requires active billing at [console.anthropic.com](https://console.anthropic.com). A "Claude Code" workspace will be automatically created for usage tracking and cost management. Note that you cannot create API keys for the Claude Code workspace - it is dedicated exclusively for Claude Code usage.711. **Claude Console**: The default option. Connect through the Claude Console and complete the OAuth process. Requires active billing in the [Anthropic console](https://console.anthropic.com). A "Claude Code" workspace is automatically created for usage tracking and cost management. You can't create API keys for the Claude Code workspace; it's dedicated exclusively for Claude Code usage.

722. **Claude App (with Pro or Max plan)**: Subscribe to Claude's [Pro or Max plan](https://claude.com/pricing) for a unified subscription that includes both Claude Code and the web interface. Get more value at the same price point while managing your account in one place. Log in with your Claude.ai account. During launch, choose the option that matches your subscription type.722. **Claude App (with Pro or Max plan)**: Subscribe to Claude's [Pro or Max plan](https://claude.com/pricing) for a unified subscription that includes both Claude Code and the web interface. Get more value at the same price point while managing your account in one place. Log in with your Claude.ai account. During launch, choose the option that matches your subscription type.

~~733. **Enterprise platforms**: Configure Claude Code to use [Amazon Bedrock or Google Vertex AI](/en/third-party-integrations) for enterprise deployments with your existing cloud infrastructure.~~733. **Enterprise platforms**: Configure Claude Code to use [Amazon Bedrock, Google Vertex AI, or Microsoft Foundry](/en/third-party-integrations) for enterprise deployments with your existing cloud infrastructure.

74 74

75<Note>75<Note>

76 Claude Code securely stores your credentials. See [Credential Management](/en/iam#credential-management) for details.76 Claude Code securely stores your credentials. See [Credential Management](/en/iam#credential-management) for details.

126```126```

127 127

128<Note>128<Note>

129 **Alpine Linux and other musl/uClibc-based distributions**: The native build requires you to install `libgcc`, `libstdc++`, and `ripgrep`. Install (Alpine: `apk add libgcc libstdc++ ripgrep`) and set `USE_BUILTIN_RIPGREP=0`.129 **Alpine Linux and other musl/uClibc-based distributions**: The native build requires `libgcc`, `libstdc++`, and `ripgrep`. For Alpine: `apk add libgcc libstdc++ ripgrep`. Set `USE_BUILTIN_RIPGREP=0`.

130</Note>

~~131~~

132<Note>

133 Claude Code installed via Homebrew will auto-update outside of the brew directory unless explicitly disabled with the `DISABLE_AUTOUPDATER` environment variable (see [Auto updates](#auto-updates) section).

134</Note>130</Note>

135 131

136**Windows PowerShell:**132**Windows PowerShell:**

163 Make sure that you remove any outdated aliases or symlinks before installing.159 Make sure that you remove any outdated aliases or symlinks before installing.

164</Tip>160</Tip>

165 161

162**Binary integrity and code signing**

163

164* SHA256 checksums for all platforms are published in the release manifests, currently located at `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json` (example: replace `{VERSION}` with `2.0.30`)

165* Signed binaries are distributed for the following platforms:

166 * macOS: Signed by "Anthropic PBC" and notarized by Apple

167 * Windows: Signed by "Anthropic, PBC"

168

166### NPM installation169### NPM installation

167 170

168For environments where NPM is preferred or required:171For environments where NPM is preferred or required:

176 If you encounter permission errors, see [configure Claude Code](/en/troubleshooting#linux-permission-issues) for recommended solutions.179 If you encounter permission errors, see [configure Claude Code](/en/troubleshooting#linux-permission-issues) for recommended solutions.

177</Warning>180</Warning>

178 181

179### Local installation

~~180~~

181* After global install via npm, use `claude migrate-installer` to move to local

182* Avoids autoupdater npm permission issues

183* Some users may be automatically migrated to this method

~~184~~

185## Running on AWS or GCP182## Running on AWS or GCP

186 183

187By default, Claude Code uses the Claude API.184By default, Claude Code uses the Claude API.

212```bash theme={null}209```bash theme={null}

213claude update210claude update

214```211```

212

213## Uninstall Claude Code

214

215If you need to uninstall Claude Code, follow the instructions for your installation method.

216

217### Native installation

218

219Remove the Claude Code binary and version files:

220

221**macOS, Linux, WSL:**

222

223```bash theme={null}

224rm -f ~/.local/bin/claude

225rm -rf ~/.local/share/claude

226```

227

228**Windows PowerShell:**

229

230```powershell theme={null}

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

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

233```

234

235**Windows CMD:**

236

237```batch theme={null}

238del "%USERPROFILE%\.local\bin\claude.exe"

239rmdir /s /q "%USERPROFILE%\.local\share\claude"

240```

241

242### Homebrew installation

243

244```bash theme={null}

245brew uninstall --cask claude-code

246```

247

248### NPM installation

249

250```bash theme={null}

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

252```

253

254### Clean up configuration files (optional)

255

256<Warning>

257 Removing configuration files will delete all your settings, allowed tools, MCP server configurations, and session history.

258</Warning>

259

260To remove Claude Code settings and cached data:

261

262**macOS, Linux, WSL:**

263

264```bash theme={null}

265# Remove user settings and state

266rm -rf ~/.claude

267rm ~/.claude.json

268

269# Remove project-specific settings (run from your project directory)

270rm -rf .claude

271rm -f .mcp.json

272```

273

274**Windows PowerShell:**

275

276```powershell theme={null}

277# Remove user settings and state

278Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force

279Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

280

281# Remove project-specific settings (run from your project directory)

282Remove-Item -Path ".claude" -Recurse -Force

283Remove-Item -Path ".mcp.json" -Force

284```

285

286**Windows CMD:**

287

288```batch theme={null}

289REM Remove user settings and state

290rmdir /s /q "%USERPROFILE%\.claude"

291del "%USERPROFILE%\.claude.json"

292

293REM Remove project-specific settings (run from your project directory)

294rmdir /s /q ".claude"

295del ".mcp.json"

296```

297

298

299---

300

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

skills.md +285 −409

Details

2 2

3> Create, manage, and share Skills to extend Claude's capabilities in Claude Code.3> Create, manage, and share Skills to extend Claude's capabilities in Claude Code.

4 4

5This guide shows you how to create, use, and manage Agent Skills in Claude Code. Skills are modular capabilities that extend Claude's functionality through organized folders containing instructions, scripts, and resources.5This guide shows you how to create, use, and manage Agent Skills in Claude Code. For background on how Skills work across Claude products, see [What are Skills?](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).

6 6

~~7## Prerequisites~~7A Skill is a markdown file that teaches Claude how to do something specific: reviewing PRs using your team's standards, generating commit messages in your preferred format, or querying your company's database schema. When you ask Claude something that matches a Skill's purpose, Claude automatically applies it.

8 8

~~9* Claude Code version 1.0 or later~~9## Create your first Skill

~~10* Basic familiarity with [Claude Code](/en/quickstart)~~

11 10

~~12## What are Agent Skills?~~11This example creates a personal Skill that teaches Claude to explain code using visual diagrams and analogies. Unlike Claude's default explanations, this Skill ensures every explanation includes an ASCII diagram and a real-world analogy.

13 12

14Agent Skills package expertise into discoverable capabilities. Each Skill consists of a `SKILL.md` file with instructions that Claude reads when relevant, plus optional supporting files like scripts and templates.13<Steps>

14 <Step title="Check available Skills">

15 Before creating a Skill, see what Skills Claude already has access to:

15 16

16**How Skills are invoked**: Skills are **model-invoked**—Claude autonomously decides when to use them based on your request and the Skill's description. This is different from slash commands, which are **user-invoked** (you explicitly type `/command` to trigger them).17 ```

18 What Skills are available?

19 ```

17 20

~~18**Benefits**:~~21 Claude will list any Skills currently loaded. You may see none, or you may see Skills from plugins or your organization.

22 </Step>

19 23

~~20* Extend Claude's capabilities for your specific workflows~~24 <Step title="Create the Skill directory">

~~21* Share expertise across your team via git~~25 Create a directory for the Skill in your personal Skills folder. Personal Skills are available across all your projects. (You can also create [project Skills](#where-skills-live) in `.claude/skills/` to share with your team.)

~~22* Reduce repetitive prompting~~

~~23* Compose multiple Skills for complex tasks~~

24 26

~~25Learn more in the [Agent Skills overview](/en/docs/agents-and-tools/agent-skills/overview).~~27 ```bash theme={null}

28 mkdir -p ~/.claude/skills/explaining-code

29 ```

30 </Step>

26 31

~~27<Note>~~32 <Step title="Write SKILL.md">

28 For a deep dive into the architecture and real-world applications of Agent Skills, read our engineering blog: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).33 Every Skill needs a `SKILL.md` file. The file starts with YAML metadata between `---` markers and must include a `name` and `description`, followed by Markdown instructions that Claude follows when the Skill is active.

~~29</Note>~~

30 34

~~31## Create a Skill~~35 The `description` is especially important, because Claude uses it to decide when to apply the Skill.

32 36

~~33Skills are stored as directories containing a `SKILL.md` file.~~37 Create `~/.claude/skills/explaining-code/SKILL.md`:

34 38

~~35### Personal Skills~~39 ```yaml theme={null}

40 ---

41 name: explaining-code

42 description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"

43 ---

36 44

~~37Personal Skills are available across all your projects. Store them in `~/.claude/skills/`:~~45 When explaining code, always include:

38 46

~~39```bash theme={null}~~47 1. **Start with an analogy**: Compare the code to something from everyday life

~~40mkdir -p ~/.claude/skills/my-skill-name~~48 2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships

~~41```~~49 3. **Walk through the code**: Explain step-by-step what happens

50 4. **Highlight a gotcha**: What's a common mistake or misconception?

42 51

~~43**Use personal Skills for**:~~52 Keep explanations conversational. For complex concepts, use multiple analogies.

53 ```

54 </Step>

44 55

~~45* Your individual workflows and preferences~~56 <Step title="Load and verify the Skill">

~~46* Experimental Skills you're developing~~57 Exit and restart Claude Code to load the new Skill. Then verify it appears in the list:

~~47* Personal productivity tools~~

48 58

~~49### Project Skills~~59 ```

60 What Skills are available?

61 ```

50 62

~~51Project Skills are shared with your team. Store them in `.claude/skills/` within your project:~~63 You should see `explaining-code` in the list with its description.

64 </Step>

52 65

~~53```bash theme={null}~~66 <Step title="Test the Skill">

~~54mkdir -p .claude/skills/my-skill-name~~67 Open any file in your project and ask Claude a question that matches the Skill's description:

~~55```~~

56 68

~~57**Use project Skills for**:~~69 ```

70 How does this code work?

71 ```

58 72

~~59* Team workflows and conventions~~73 Claude should ask to use the `explaining-code` Skill, then include an analogy and ASCII diagram in its explanation. If the Skill doesn't trigger, try rephrasing to include more keywords from the description, like "explain how this works."

~~60* Project-specific expertise~~74 </Step>

~~61* Shared utilities and scripts~~75</Steps>

62 76

~~63Project Skills are checked into git and automatically available to team members.~~77The rest of this guide covers how Skills work, configuration options, and troubleshooting.

64 78

~~65### Plugin Skills~~79## How Skills work

66 80

67Skills can also come from [Claude Code plugins](/en/plugins). Plugins may bundle Skills that are automatically available when the plugin is installed. These Skills work the same way as personal and project Skills.81Skills are **model-invoked**: Claude decides which Skills to use based on your request. You don't need to explicitly call a Skill. Claude automatically applies relevant Skills when your request matches their description.

68 82

~~69## Write SKILL.md~~83When you send a request, Claude follows these steps to find and use relevant Skills:

70 84

~~71Create a `SKILL.md` file with YAML frontmatter and Markdown content:~~85<Steps>

86 <Step title="Discovery">

87 At startup, Claude loads only the name and description of each available Skill. This keeps startup fast while giving Claude enough context to know when each Skill might be relevant.

88 </Step>

72 89

~~73```yaml theme={null}~~90 <Step title="Activation">

~~74name: your-skill-name~~91 When your request matches a Skill's description, Claude asks to use the Skill. You'll see a confirmation prompt before the full `SKILL.md` is loaded into context. Claude matches requests against descriptions using semantic similarity, so [write descriptions](#skill-not-triggering) that include keywords users would naturally say.

~~75description: Brief description of what this Skill does and when to use it~~92 </Step>

76 93

~~77# Your Skill Name~~94 <Step title="Execution">

95 Claude follows the Skill's instructions, loading referenced files or running bundled scripts as needed.

96 </Step>

97</Steps>

78 98

~~79## Instructions~~99### Where Skills live

~~80Provide clear, step-by-step guidance for Claude.~~

81 100

~~82## Examples~~101Where you store a Skill determines who can use it:

~~83Show concrete examples of using this Skill.~~

~~84```~~

85 102

~~86**Field requirements**:~~103| Location | Path | Applies to |

104| :--------- | :---------------------------------------------------------- | :-------------------------------- |

105| Enterprise | See [managed settings](/en/iam#enterprise-managed-settings) | All users in your organization |

106| Personal | `~/.claude/skills/` | You, across all projects |

107| Project | `.claude/skills/` | Anyone working in this repository |

108| Plugin | Bundled with [plugins](/en/plugins) | Anyone with the plugin installed |

87 109

~~88* `name`: Must use lowercase letters, numbers, and hyphens only (max 64 characters)~~110If two Skills have the same name, the higher row wins: enterprise overrides personal, personal overrides project, and project overrides plugin.

~~89* `description`: Brief description of what the Skill does and when to use it (max 1024 characters)~~

90 111

~~91The `description` field is critical for Claude to discover when to use your Skill. It should include both what the Skill does and when Claude should use it.~~112### When to use Skills versus other options

92 113

~~93See the [best practices guide](/en/docs/agents-and-tools/agent-skills/best-practices) for complete authoring guidance including validation rules.~~114Claude Code offers several ways to customize behavior. The key difference: **Skills are triggered automatically by Claude** based on your request, while slash commands require you to type `/command` explicitly.

94 115

~~95## Add supporting files~~116| Use this | When you want to... | When it runs |

117| :--------------------------------------- | :------------------------------------------------------------------------- | :----------------------------------------- |

118| **Skills** | Give Claude specialized knowledge (e.g., "review PRs using our standards") | Claude chooses when relevant |

119| **[Slash commands](/en/slash-commands)** | Create reusable prompts (e.g., `/deploy staging`) | You type `/command` to run it |

120| **[CLAUDE.md](/en/memory)** | Set project-wide instructions (e.g., "use TypeScript strict mode") | Loaded into every conversation |

121| **[Subagents](/en/sub-agents)** | Delegate tasks to a separate context with its own tools | Claude delegates, or you invoke explicitly |

122| **[Hooks](/en/hooks)** | Run scripts on events (e.g., lint on file save) | Fires on specific tool events |

123| **[MCP servers](/en/mcp)** | Connect Claude to external tools and data sources | Claude calls MCP tools as needed |

96 124

~~97Create additional files alongside SKILL.md:~~125**Skills vs. subagents**: Skills add knowledge to the current conversation. Subagents run in a separate context with their own tools. Use Skills for guidance and standards; use subagents when you need isolation or different tool access.

98 126

~~99```~~127**Skills vs. MCP**: Skills tell Claude *how* to use tools; MCP *provides* the tools. For example, an MCP server connects Claude to your database, while a Skill teaches Claude your data model and query patterns.

100my-skill/

101├── SKILL.md (required)

102├── reference.md (optional documentation)

103├── examples.md (optional examples)

104├── scripts/

105│ └── helper.py (optional utility)

106└── templates/

107 └── template.txt (optional template)

108```

~~109~~

110Reference these files from SKILL.md:

111 128

112````markdown theme={null}129<Note>

113For advanced usage, see [reference.md](reference.md).130 For a deep dive into the architecture and real-world applications of Agent Skills, read [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).

131</Note>

114 132

115Run the helper script:133## Configure Skills

116```bash

117python scripts/helper.py input.txt

118```

119````

120 134

121Claude reads these files only when needed, using progressive disclosure to manage context efficiently.135This section covers Skill file structure, supporting files, tool restrictions, and distribution options.

122 136

123## Restrict tool access with allowed-tools137### Write SKILL.md

124 138

125Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active:139The `SKILL.md` file is the only required file in a Skill. It has two parts: YAML metadata (the section between `---` markers) at the top, and Markdown instructions that tell Claude how to use the Skill:

126 140

127```yaml theme={null}141```yaml theme={null}

128---142---

129name: safe-file-reader143name: your-skill-name

130description: Read files without making changes. Use when you need read-only file access.144description: Brief description of what this Skill does and when to use it

131allowed-tools: Read, Grep, Glob

132---145---

133 146

134# Safe File Reader147# Your Skill Name

~~135~~

136This Skill provides read-only file access.

137 148

138## Instructions149## Instructions

1391. Use Read to view file contents150Provide clear, step-by-step guidance for Claude.

1402. Use Grep to search within files

1413. Use Glob to find files by pattern

142```

~~143~~

144When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for:

~~145~~

146* Read-only Skills that shouldn't modify files

147* Skills with limited scope (e.g., only data analysis, no file writing)

148* Security-sensitive workflows where you want to restrict capabilities

~~149~~

150If `allowed-tools` is not specified, Claude will ask for permission to use tools as normal, following the standard permission model.

~~151~~

152<Note>

153 `allowed-tools` is only supported for Skills in Claude Code.

154</Note>

~~155~~

156## View available Skills

~~157~~

158Skills are automatically discovered by Claude from three sources:

~~159~~

160* Personal Skills: `~/.claude/skills/`

161* Project Skills: `.claude/skills/`

162* Plugin Skills: bundled with installed plugins

~~163~~

164**To view all available Skills**, ask Claude directly:

~~165~~

166```

167What Skills are available?

168```

~~169~~

170or

~~171~~

172```

173List all available Skills

174```

~~175~~

176This will show all Skills from all sources, including plugin Skills.

~~177~~

178**To inspect a specific Skill**, you can also check the filesystem:

~~179~~

180```bash theme={null}

181# List personal Skills

182ls ~/.claude/skills/

~~183~~

184# List project Skills (if in a project directory)

185ls .claude/skills/

~~186~~

187# View a specific Skill's content

188cat ~/.claude/skills/my-skill/SKILL.md

189```

~~190~~

191## Test a Skill

~~192~~

193After creating a Skill, test it by asking questions that match your description.

~~194~~

195**Example**: If your description mentions "PDF files":

~~196~~

197```

198Can you help me extract text from this PDF?

199```

~~200~~

201Claude autonomously decides to use your Skill if it matches the request—you don't need to explicitly invoke it. The Skill activates automatically based on the context of your question.

~~202~~

203## Debug a Skill

~~204~~

205If Claude doesn't use your Skill, check these common issues:

~~206~~

207### Make description specific

~~208~~

209**Too vague**:

~~210~~

211```yaml theme={null}

212description: Helps with documents

213```

~~214~~

215**Specific**:

~~216~~

217```yaml theme={null}

218description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

219```

~~220~~

221Include both what the Skill does and when to use it in the description.

~~222~~

223### Verify file path

~~224~~

225**Personal Skills**: `~/.claude/skills/skill-name/SKILL.md`

226**Project Skills**: `.claude/skills/skill-name/SKILL.md`

~~227~~

228Check the file exists:

~~229~~

230```bash theme={null}

231# Personal

232ls ~/.claude/skills/my-skill/SKILL.md

~~233~~

234# Project

235ls .claude/skills/my-skill/SKILL.md

236```

~~237~~

238### Check YAML syntax

~~239~~

240Invalid YAML prevents the Skill from loading. Verify the frontmatter:

~~241~~

242```bash theme={null}

243cat SKILL.md | head -n 10

244```

~~245~~

246Ensure:

~~247~~

248* Opening `---` on line 1

249* Closing `---` before Markdown content

250* Valid YAML syntax (no tabs, correct indentation)

~~251~~

252### View errors

~~253~~

254Run Claude Code with debug mode to see Skill loading errors:

255 151

256```bash theme={null}152## Examples

257claude --debug153Show concrete examples of using this Skill.

258```154```

259 155

260## Share Skills with your team156#### Available metadata fields

~~261~~

262**Recommended approach**: Distribute Skills through [plugins](/en/plugins).

~~263~~

264To share Skills via plugin:

265 157

2661. Create a plugin with Skills in the `skills/` directory158You can use the following fields in the YAML frontmatter:

2672. Add the plugin to a marketplace

2683. Team members install the plugin

269 159

270For complete instructions, see [Add Skills to your plugin](/en/plugins#add-skills-to-your-plugin).160| Field | Required | Description |

161| :-------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

162| `name` | Yes | Skill name. Must use lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. |

163| `description` | Yes | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill. |

164| `allowed-tools` | No | Tools Claude can use without asking permission when this Skill is active. See [Restrict tool access](#restrict-tool-access-with-allowed-tools). |

165| `model` | No | [Model](https://docs.claude.com/en/docs/about-claude/models/overview) to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model. |

271 166

272You can also share Skills directly through project repositories:167See the [best practices guide](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) for complete authoring guidance including validation rules.

~~273~~

274### Step 1: Add Skill to your project

~~275~~

276Create a project Skill:

~~277~~

278```bash theme={null}

279mkdir -p .claude/skills/team-skill

280# Create SKILL.md

281```

282 168

283### Step 2: Commit to git169### Update or delete a Skill

284 170

285```bash theme={null}171To update a Skill, edit its `SKILL.md` file directly. To remove a Skill, delete its directory. Exit and restart Claude Code for changes to take effect.

286git add .claude/skills/

287git commit -m "Add team Skill for PDF processing"

288git push

289```

290 172

291### Step 3: Team members get Skills automatically173### Add supporting files with progressive disclosure

292 174

293When team members pull the latest changes, Skills are immediately available:175Skills share Claude's context window with conversation history, other Skills, and your request. To keep context focused, use **progressive disclosure**: put essential information in `SKILL.md` and detailed reference material in separate files that Claude reads only when needed.

294 176

295```bash theme={null}177This approach lets you bundle comprehensive documentation, examples, and scripts without consuming context upfront. Claude loads additional files only when the task requires them.

296git pull

297claude # Skills are now available

298```

299 178

300## Update a Skill179<Tip>Keep `SKILL.md` under 500 lines for optimal performance. If your content exceeds this, split detailed reference material into separate files.</Tip>

301 180

302Edit SKILL.md directly:181#### Example: multi-file Skill structure

303 182

304```bash theme={null}183Claude discovers supporting files through links in your `SKILL.md`. The following example shows a Skill with detailed documentation in separate files and utility scripts that Claude can execute without reading:

305# Personal Skill

306code ~/.claude/skills/my-skill/SKILL.md

307 184

308# Project Skill

309code .claude/skills/my-skill/SKILL.md

310```185```

~~311~~ 186my-skill/

312Changes take effect the next time you start Claude Code. If Claude Code is already running, restart it to load the updates.187├── SKILL.md (required - overview and navigation)

~~313~~ 188├── reference.md (detailed API docs - loaded when needed)

314## Remove a Skill189├── examples.md (usage examples - loaded when needed)

~~315~~ 190└── scripts/

316Delete the Skill directory:191 └── helper.py (utility script - executed, not loaded)

~~317~~

318```bash theme={null}

319# Personal

320rm -rf ~/.claude/skills/my-skill

~~321~~

322# Project

323rm -rf .claude/skills/my-skill

324git commit -m "Remove unused Skill"

325```192```

326 193

327## Best practices194The `SKILL.md` file references these supporting files so Claude knows they exist:

~~328~~

329### Keep Skills focused

330 195

331One Skill should address one capability:196````markdown theme={null}

~~332~~ 197## Overview

333**Focused**:

~~334~~

335* "PDF form filling"

336* "Excel data analysis"

337* "Git commit messages"

~~338~~

339**Too broad**:

~~340~~

341* "Document processing" (split into separate Skills)

342* "Data tools" (split by data type or operation)

~~343~~

344### Write clear descriptions

345 198

346Help Claude discover when to use Skills by including specific triggers in your description:199[Essential instructions here]

347 200

348**Clear**:201## Additional resources

349 202

350```yaml theme={null}203- For complete API details, see [reference.md](reference.md)

351description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.204- For usage examples, see [examples.md](examples.md)

352```

353 205

354**Vague**:206## Utility scripts

355 207

356```yaml theme={null}208To validate input files, run the helper script. It checks for required fields and returns any validation errors:

357description: For files209```bash

210python scripts/helper.py input.txt

358```211```

212````

359 213

360### Test with your team214<Tip>Keep references one level deep. Link directly from `SKILL.md` to reference files. Deeply nested references (file A links to file B which links to file C) may result in Claude partially reading files.</Tip>

~~361~~

362Have teammates use Skills and provide feedback:

363 215

364* Does the Skill activate when expected?216**Bundle utility scripts for zero-context execution.** Scripts in your Skill directory can be executed without loading their contents into context. Claude runs the script and only the output consumes tokens. This is useful for:

365* Are the instructions clear?

366* Are there missing examples or edge cases?

367 217

368### Document Skill versions218* Complex validation logic that would be verbose to describe in prose

219* Data processing that's more reliable as tested code than generated code

220* Operations that benefit from consistency across uses

369 221

370You can document Skill versions in your SKILL.md content to track changes over time. Add a version history section:222In `SKILL.md`, tell Claude to run the script rather than read it:

371 223

372```markdown theme={null}224```markdown theme={null}

373# My Skill225Run the validation script to check the form:

~~374~~ 226python scripts/validate_form.py input.pdf

375## Version History

376- v2.0.0 (2025-10-01): Breaking changes to API

377- v1.1.0 (2025-09-15): Added new features

378- v1.0.0 (2025-09-01): Initial release

379```227```

380 228

381This helps team members understand what changed between versions.229For complete guidance on structuring Skills, see the [best practices guide](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns).

~~382~~

383## Troubleshooting

~~384~~

385### Claude doesn't use my Skill

386 230

387**Symptom**: You ask a relevant question but Claude doesn't use your Skill.231### Restrict tool access with allowed-tools

388 232

389**Check**: Is the description specific enough?233Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active:

~~390~~

391Vague descriptions make discovery difficult. Include both what the Skill does and when to use it, with key terms users would mention.

~~392~~

393**Too generic**:

~~394~~

395```yaml theme={null}

396description: Helps with data

397```

~~398~~

399**Specific**:

400 234

401```yaml theme={null}235```yaml theme={null}

402description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.236---

403```237name: reading-files-safely

~~404~~ 238description: Read files without making changes. Use when you need read-only file access.

405**Check**: Is the YAML valid?239allowed-tools: Read, Grep, Glob

240---

406 241

407Run validation to check for syntax errors:242# Safe File Reader

408 243

409```bash theme={null}244This Skill provides read-only file access.

410# View frontmatter

411cat .claude/skills/my-skill/SKILL.md | head -n 15

412 245

413# Check for common issues246## Instructions

414# - Missing opening or closing ---2471. Use Read to view file contents

415# - Tabs instead of spaces2482. Use Grep to search within files

416# - Unquoted strings with special characters2493. Use Glob to find files by pattern

417```250```

418 251

419**Check**: Is the Skill in the correct location?252When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for:

~~420~~

421```bash theme={null}

422# Personal Skills

423ls ~/.claude/skills/*/SKILL.md

~~424~~

425# Project Skills

426ls .claude/skills/*/SKILL.md

427```

428 253

429### Skill has errors254* Read-only Skills that shouldn't modify files

255* Skills with limited scope: for example, only data analysis, no file writing

256* Security-sensitive workflows where you want to restrict capabilities

430 257

431**Symptom**: The Skill loads but doesn't work correctly.258If `allowed-tools` is omitted, the Skill doesn't restrict tools. Claude uses its standard permission model and may ask you to approve tool usage.

432 259

433**Check**: Are dependencies available?260<Note>

261 `allowed-tools` is only supported for Skills in Claude Code.

262</Note>

434 263

435Claude will automatically install required dependencies (or ask for permission to install them) when it needs them.264### Use Skills with subagents

436 265

437**Check**: Do scripts have execute permissions?266[Subagents](/en/sub-agents) do not automatically inherit Skills from the main conversation. To give a custom subagent access to specific Skills, list them in the subagent's `skills` field in `.claude/agents/`:

438 267

439```bash theme={null}268```yaml theme={null}

440chmod +x .claude/skills/my-skill/scripts/*.py269# .claude/agents/code-reviewer/AGENT.md

270---

271name: code-reviewer

272description: Review code for quality and best practices

273skills: pr-review, security-check

274---

441```275```

442 276

443**Check**: Are file paths correct?277The listed Skills are loaded into the subagent's context when it starts. If the `skills` field is omitted, no Skills are preloaded for that subagent.

~~444~~

445Use forward slashes (Unix style) in all paths:

~~446~~

447**Correct**: `scripts/helper.py`

448**Wrong**: `scripts\helper.py` (Windows style)

~~449~~

450### Multiple Skills conflict

~~451~~

452**Symptom**: Claude uses the wrong Skill or seems confused between similar Skills.

453 278

454**Be specific in descriptions**: Help Claude choose the right Skill by using distinct trigger terms in your descriptions.279<Note>

~~455~~ 280 Built-in agents (Explore, Plan, Verify) and the Task tool do not have access to your Skills. Only custom subagents you define in `.claude/agents/` with an explicit `skills` field can use Skills.

456Instead of:281</Note>

~~457~~

458```yaml theme={null}

459# Skill 1

460description: For data analysis

461 282

462# Skill 2283### Distribute Skills

463description: For analyzing data

464```

465 284

466Use:285You can share Skills in several ways:

467 286

468```yaml theme={null}287* **Project Skills**: Commit `.claude/skills/` to version control. Anyone who clones the repository gets the Skills.

469# Skill 1288* **Plugins**: To share Skills across multiple repositories, create a `skills/` directory in your [plugin](/en/plugins) with Skill folders containing `SKILL.md` files. Distribute through a [plugin marketplace](/en/plugin-marketplaces).

470description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking.289* **Enterprise**: Administrators can deploy Skills organization-wide through [managed settings](/en/iam#enterprise-managed-settings). See [Where Skills live](#where-skills-live) for enterprise Skill paths.

~~471~~

472# Skill 2

473description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics.

474```

475 290

476## Examples291## Examples

477 292

293These examples show common Skill patterns, from minimal single-file Skills to multi-file Skills with supporting documentation and scripts.

294

478### Simple Skill (single file)295### Simple Skill (single file)

479 296

297A minimal Skill needs only a `SKILL.md` file with frontmatter and instructions. This example helps Claude generate commit messages by examining staged changes:

298

480```299```

481commit-helper/300commit-helper/

482└── SKILL.md301└── SKILL.md

506- Explain what and why, not how323- Explain what and why, not how

507```324```

508 325

509### Skill with tool permissions326### Use multiple files

510 327

511```328For complex Skills, use progressive disclosure to keep the main `SKILL.md` focused while providing detailed documentation in supporting files. This PDF processing Skill includes reference docs, utility scripts, and uses `allowed-tools` to restrict Claude to specific tools:

512code-reviewer/

513└── SKILL.md

514```

~~515~~

516```yaml theme={null}

517name: code-reviewer

518description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.

519allowed-tools: Read, Grep, Glob

~~520~~

521# Code Reviewer

~~522~~

523## Review checklist

~~524~~

5251. Code organization and structure

5262. Error handling

5273. Performance considerations

5284. Security concerns

5295. Test coverage

~~530~~

531## Instructions

~~532~~

5331. Read the target files using Read tool

5342. Search for patterns using Grep

5353. Find related files using Glob

5364. Provide detailed feedback on code quality

537```

~~538~~

539### Multi-file Skill

540 329

541```330```

542pdf-processing/331pdf-processing/

543├── SKILL.md332├── SKILL.md # Overview and quick start

544├── FORMS.md333├── FORMS.md # Form field mappings and filling instructions

545├── REFERENCE.md334├── REFERENCE.md # API details for pypdf and pdfplumber

546└── scripts/335└── scripts/

547 ├── fill_form.py336 ├── fill_form.py # Utility to populate form fields

548 └── validate.py337 └── validate.py # Checks PDFs for required fields

549```338```

550 339

551**SKILL.md**:340**`SKILL.md`**:

552 341

553````yaml theme={null}342````yaml theme={null}

554---343---

555name: pdf-processing344name: pdf-processing

556description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.345description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.

346allowed-tools: Read, Bash(python:*)

557---347---

558 348

559# PDF Processing349# PDF Processing

581````369````

582 370

583<Note>371<Note>

584 List required packages in the description. Packages must be installed in your environment before Claude can use them.372 If your Skill requires external packages, list them in the description. Packages must be installed in your environment before Claude can use them.

585</Note>373</Note>

586 374

587Claude loads additional files only when needed.375## Troubleshooting

376

377### View and test Skills

378

379To see which Skills Claude has access to, ask Claude a question like "What Skills are available?" Claude loads all available Skill names and descriptions into the context window when a conversation starts, so it can list the Skills it currently has access to.

380

381To test a specific Skill, ask Claude to do a task that matches the Skill's description. For example, if your Skill has the description "Reviews pull requests for code quality", ask Claude to "Review the changes in my current branch." Claude automatically uses the Skill when the request matches its description.

382

383### Skill not triggering

384

385The description field is how Claude decides whether to use your Skill. Vague descriptions like "Helps with documents" don't give Claude enough information to match your Skill to relevant requests.

386

387A good description answers two questions:

388

3891. **What does this Skill do?** List the specific capabilities.

3902. **When should Claude use it?** Include trigger terms users would mention.

391

392```yaml theme={null}

393description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

394```

395

396This description works because it names specific actions (extract, fill, merge) and includes keywords users would say (PDF, forms, document extraction).

397

398### Skill doesn't load

399

400**Check the file path.** Skills must be in the correct directory with the exact filename `SKILL.md` (case-sensitive):

401

402| Type | Path |

403| :--------- | :---------------------------------------------------------------------- |

404| Personal | `~/.claude/skills/my-skill/SKILL.md` |

405| Project | `.claude/skills/my-skill/SKILL.md` |

406| Enterprise | See [Where Skills live](#where-skills-live) for platform-specific paths |

407| Plugin | `skills/my-skill/SKILL.md` inside the plugin directory |

408

409**Check the YAML syntax.** Invalid YAML in the frontmatter prevents the Skill from loading. The frontmatter must start with `---` on line 1 (no blank lines before it), end with `---` before the Markdown content, and use spaces for indentation (not tabs).

410

411**Run debug mode.** Use `claude --debug` to see Skill loading errors.

412

413### Skill has errors

414

415**Check dependencies are installed.** If your Skill uses external packages, they must be installed in your environment before Claude can use them.

416

417**Check script permissions.** Scripts need execute permissions: `chmod +x scripts/*.py`

418

419**Check file paths.** Use forward slashes (Unix style) in all paths. Use `scripts/helper.py`, not `scripts\helper.py`.

420

421### Multiple Skills conflict

422

423If Claude uses the wrong Skill or seems confused between similar Skills, the descriptions are probably too similar. Make each description distinct by using specific trigger terms.

424

425For example, instead of two Skills with "data analysis" in both descriptions, differentiate them: one for "sales data in Excel files and CRM exports" and another for "log files and system metrics". The more specific your trigger terms, the easier it is for Claude to match the right Skill to your request.

426

427### Plugin Skills not appearing

428

429**Symptom**: You installed a plugin from a marketplace, but its Skills don't appear when you ask Claude "What Skills are available?"

430

431**Solution**: Clear the plugin cache and reinstall:

432

433```bash theme={null}

434rm -rf ~/.claude/plugins/cache

435```

436

437Then restart Claude Code and reinstall the plugin:

438

439```shell theme={null}

440/plugin install plugin-name@marketplace-name

441```

442

443This forces Claude Code to re-download and re-register the plugin's Skills.

444

445**If Skills still don't appear**, verify the plugin's directory structure is correct. Skills must be in a `skills/` directory at the plugin root:

446

447```

448my-plugin/

449├── .claude-plugin/

450│ └── plugin.json

451└── skills/

452 └── my-skill/

453 └── SKILL.md

454```

588 455

589## Next steps456## Next steps

590 457

591<CardGroup cols={2}>458<CardGroup cols={2}>

592 <Card title="Authoring best practices" icon="lightbulb" href="/en/docs/agents-and-tools/agent-skills/best-practices">459 <Card title="Authoring best practices" icon="lightbulb" href="https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices">

593 Write Skills that Claude can use effectively460 Write Skills that Claude can use effectively

594 </Card>461 </Card>

595 462

596 <Card title="Agent Skills overview" icon="book" href="/en/docs/agents-and-tools/agent-skills/overview">463 <Card title="Agent Skills overview" icon="book" href="https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview">

597 Learn how Skills work across Claude products464 Learn how Skills work across Claude products

598 </Card>465 </Card>

599 466

600 <Card title="Use Skills in the Agent SDK" icon="cube" href="https://docs.claude.com/en/api/agent-sdk/skills">467 <Card title="Use Skills in the Agent SDK" icon="cube" href="https://docs.claude.com/en/docs/agent-sdk/skills">

601 Use Skills programmatically with TypeScript and Python468 Use Skills programmatically with TypeScript and Python

602 </Card>469 </Card>

603 470

604 <Card title="Get started with Agent Skills" icon="rocket" href="/en/docs/agents-and-tools/agent-skills/quickstart">471 <Card title="Get started with Agent Skills" icon="rocket" href="https://docs.claude.com/en/docs/agents-and-tools/agent-skills/quickstart">

605 Create your first Skill472 Create your first Skill

606 </Card>473 </Card>

607</CardGroup>474</CardGroup>

475

476

477---

478

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

slack.md +211 −0 added

Details

1# Claude Code in Slack

3> Delegate coding tasks directly from your Slack workspace

5Claude Code in Slack brings the power of Claude Code directly into your Slack workspace. When you mention `@Claude` with a coding task, Claude automatically detects the intent and creates a Claude Code session on the web, allowing you to delegate development work without leaving your team conversations.

7This integration is built on the existing Claude for Slack app but adds intelligent routing to Claude Code on the web for coding-related requests.

9## Use cases

11* **Bug investigation and fixes**: Ask Claude to investigate and fix bugs as soon as they're reported in Slack channels.

12* **Quick code reviews and modifications**: Have Claude implement small features or refactor code based on team feedback.

13* **Collaborative debugging**: When team discussions provide crucial context (e.g., error reproductions or user reports), Claude can use that information to inform its debugging approach.

14* **Parallel task execution**: Kick off coding tasks in Slack while you continue other work, receiving notifications when complete.

16## Prerequisites

18Before using Claude Code in Slack, ensure you have the following:

20| Requirement | Details |

21| :--------------------- | :----------------------------------------------------------------------------- |

22| Claude Plan | Pro, Max, Team, or Enterprise with Claude Code access (premium seats) |

23| Claude Code on the web | Access to [Claude Code on the web](/en/claude-code-on-the-web) must be enabled |

24| GitHub Account | Connected to Claude Code on the web with at least one repository authenticated |

25| Slack Authentication | Your Slack account linked to your Claude account via the Claude app |

27## Setting up Claude Code in Slack

29<Steps>

30 <Step title="Install the Claude App in Slack">

31 A workspace administrator must install the Claude app from the Slack App Marketplace. Visit the [Slack App Marketplace](https://slack.com/marketplace/A08SF47R6P4) and click "Add to Slack" to begin the installation process.

32 </Step>

34 <Step title="Connect your Claude account">

35 After the app is installed, authenticate your individual Claude account:

37 1. Open the Claude app in Slack by clicking on "Claude" in your Apps section

38 2. Navigate to the App Home tab

39 3. Click "Connect" to link your Slack account with your Claude account

40 4. Complete the authentication flow in your browser

41 </Step>

43 <Step title="Configure Claude Code on the web">

44 Ensure your Claude Code on the web is properly configured:

46 * Visit [claude.ai/code](https://claude.ai/code) and sign in with the same account you connected to Slack

47 * Connect your GitHub account if not already connected

48 * Authenticate at least one repository that you want Claude to work with

49 </Step>

51 <Step title="Choose your routing mode">

52 After connecting your accounts, configure how Claude handles your messages in Slack. Navigate to the Claude App Home in Slack to find the **Routing Mode** setting.

54 | Mode | Behavior |

55 | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

56 | **Code only** | Claude routes all @mentions to Claude Code sessions. Best for teams using Claude in Slack exclusively for development tasks. |

57 | **Code + Chat** | Claude analyzes each message and intelligently routes between Claude Code (for coding tasks) and Claude Chat (for writing, analysis, and general questions). Best for teams who want a single @Claude entry point for all types of work. |

59 <Note>

60 In Code + Chat mode, if Claude routes a message to Chat but you wanted a coding session, you can click "Retry as Code" to create a Claude Code session instead. Similarly, if it's routed to Code but you wanted a Chat session, you can choose that option in that thread.

61 </Note>

62 </Step>

63</Steps>

65## How it works

67### Automatic detection

69When you mention @Claude in a Slack channel or thread, Claude automatically analyzes your message to determine if it's a coding task. If Claude detects coding intent, it will route your request to Claude Code on the web instead of responding as a regular chat assistant.

71You can also explicitly tell Claude to handle a request as a coding task, even if it doesn't automatically detect it.

73<Note>

74 Claude Code in Slack only works in channels (public or private). It does not work in direct messages (DMs).

75</Note>

77### Context gathering

79**From threads**: When you @mention Claude in a thread, it gathers context from all messages in that thread to understand the full conversation.

81**From channels**: When mentioned directly in a channel, Claude looks at recent channel messages for relevant context.

83This context helps Claude understand the problem, select the appropriate repository, and inform its approach to the task.

85<Warning>

86 When @Claude is invoked in Slack, Claude is given access to the conversation context to better understand your request. Claude may follow directions from other messages in the context, so users should make sure to only use Claude in trusted Slack conversations.

87</Warning>

89### Session flow

911. **Initiation**: You @mention Claude with a coding request

922. **Detection**: Claude analyzes your message and detects coding intent

933. **Session creation**: A new Claude Code session is created on claude.ai/code

944. **Progress updates**: Claude posts status updates to your Slack thread as work progresses

955. **Completion**: When finished, Claude @mentions you with a summary and action buttons

966. **Review**: Click "View Session" to see the full transcript, or "Create PR" to open a pull request

98## User interface elements

100### App Home

101

102The App Home tab shows your connection status and allows you to connect or disconnect your Claude account from Slack.

103

104### Message actions

105

106* **View Session**: Opens the full Claude Code session in your browser where you can see all work performed, continue the session, or make additional requests.

107* **Create PR**: Creates a pull request directly from the session's changes.

108* **Retry as Code**: If Claude initially responds as a chat assistant but you wanted a coding session, click this button to retry the request as a Claude Code task.

109* **Change Repo**: Allows you to select a different repository if Claude chose incorrectly.

110

111### Repository selection

112

113Claude automatically selects a repository based on context from your Slack conversation. If multiple repositories could apply, Claude may display a dropdown allowing you to choose the correct one.

114

115## Access and permissions

116

117### User-level access

118

119| Access Type | Requirement |

120| :------------------- | :-------------------------------------------------------------- |

121| Claude Code Sessions | Each user runs sessions under their own Claude account |

122| Usage & Rate Limits | Sessions count against the individual user's plan limits |

123| Repository Access | Users can only access repositories they've personally connected |

124| Session History | Sessions appear in your Claude Code history on claude.ai/code |

125

126### Workspace admin permissions

127

128Slack workspace administrators control whether the Claude app can be installed in the workspace. Individual users then authenticate with their own Claude accounts to use the integration.

129

130## What's accessible where

131

132**In Slack**: You'll see status updates, completion summaries, and action buttons. The full transcript is preserved and always accessible.

133

134**On the web**: The complete Claude Code session with full conversation history, all code changes, file operations, and the ability to continue the session or create pull requests.

135

136## Best practices

137

138### Writing effective requests

139

140* **Be specific**: Include file names, function names, or error messages when relevant.

141* **Provide context**: Mention the repository or project if it's not clear from the conversation.

142* **Define success**: Explain what "done" looks like—should Claude write tests? Update documentation? Create a PR?

143* **Use threads**: Reply in threads when discussing bugs or features so Claude can gather the full context.

144

145### When to use Slack vs. web

146

147**Use Slack when**: Context already exists in a Slack discussion, you want to kick off a task asynchronously, or you're collaborating with teammates who need visibility.

148

149**Use the web directly when**: You need to upload files, want real-time interaction during development, or are working on longer, more complex tasks.

150

151## Troubleshooting

152

153### Sessions not starting

154

1551. Verify your Claude account is connected in the Claude App Home

1562. Check that you have Claude Code on the web access enabled

1573. Ensure you have at least one GitHub repository connected to Claude Code

158

159### Repository not showing

160

1611. Connect the repository in Claude Code on the web at [claude.ai/code](https://claude.ai/code)

1622. Verify your GitHub permissions for that repository

1633. Try disconnecting and reconnecting your GitHub account

164

165### Wrong repository selected

166

1671. Click the "Change Repo" button to select a different repository

1682. Include the repository name in your request for more accurate selection

169

170### Authentication errors

171

1721. Disconnect and reconnect your Claude account in the App Home

1732. Ensure you're signed into the correct Claude account in your browser

1743. Check that your Claude plan includes Claude Code access

175

176### Session expiration

177

1781. Sessions remain accessible in your Claude Code history on the web

1792. You can continue or reference past sessions from [claude.ai/code](https://claude.ai/code)

180

181## Current limitations

182

183* **GitHub only**: Currently supports repositories on GitHub.

184* **One PR at a time**: Each session can create one pull request.

185* **Rate limits apply**: Sessions use your individual Claude plan's rate limits.

186* **Web access required**: Users must have Claude Code on the web access; those without it will only get standard Claude chat responses.

187

188## Related resources

189

190<CardGroup>

191 <Card title="Claude Code on the web" icon="globe" href="/en/claude-code-on-the-web">

192 Learn more about Claude Code on the web

193 </Card>

194

195 <Card title="Claude for Slack" icon="slack" href="https://claude.com/claude-and-slack">

196 General Claude for Slack documentation

197 </Card>

198

199 <Card title="Slack App Marketplace" icon="store" href="https://slack.com/marketplace/A08SF47R6P4">

200 Install the Claude app from the Slack Marketplace

201 </Card>

202

203 <Card title="Claude Help Center" icon="circle-question" href="https://support.claude.com">

204 Get additional support

205 </Card>

206</CardGroup>

207

208

209---

210

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

slash-commands.md +53 −37

Details

14| `/compact [instructions]` | Compact conversation with optional focus instructions |14| `/compact [instructions]` | Compact conversation with optional focus instructions |

15| `/config` | Open the Settings interface (Config tab) |15| `/config` | Open the Settings interface (Config tab) |

16| `/context` | Visualize current context usage as a colored grid |16| `/context` | Visualize current context usage as a colored grid |

~~17| `/cost` | Show token usage statistics (see [cost tracking guide](/en/costs#using-the-cost-command) for subscription-specific details) |~~17| `/cost` | Show token usage statistics. See [cost tracking guide](/en/costs#using-the-cost-command) for subscription-specific details. |

18| `/doctor` | Checks the health of your Claude Code installation |18| `/doctor` | Checks the health of your Claude Code installation |

19| `/exit` | Exit the REPL |19| `/exit` | Exit the REPL |

20| `/export [filename]` | Export the current conversation to a file or clipboard |20| `/export [filename]` | Export the current conversation to a file or clipboard |

21| `/help` | Get usage help |21| `/help` | Get usage help |

22| `/hooks` | Manage hook configurations for tool events |22| `/hooks` | Manage hook configurations for tool events |

~~23| `/init` | Initialize project with CLAUDE.md guide |~~23| `/ide` | Manage IDE integrations and show status |

24| `/init` | Initialize project with `CLAUDE.md` guide |

25| `/install-github-app` | Set up Claude GitHub Actions for a repository |

24| `/login` | Switch Anthropic accounts |26| `/login` | Switch Anthropic accounts |

25| `/logout` | Sign out from your Anthropic account |27| `/logout` | Sign out from your Anthropic account |

26| `/mcp` | Manage MCP server connections and OAuth authentication |28| `/mcp` | Manage MCP server connections and OAuth authentication |

28| `/model` | Select or change the AI model |30| `/model` | Select or change the AI model |

29| `/output-style [style]` | Set the output style directly or from a selection menu |31| `/output-style [style]` | Set the output style directly or from a selection menu |

30| `/permissions` | View or update [permissions](/en/iam#configuring-permissions) |32| `/permissions` | View or update [permissions](/en/iam#configuring-permissions) |

34| `/pr-comments` | View pull request comments |

32| `/privacy-settings` | View and update your privacy settings |35| `/privacy-settings` | View and update your privacy settings |

36| `/release-notes` | View release notes |

37| `/rename <name>` | Rename the current session for easier identification |

38| `/resume [session]` | Resume a conversation by ID or name, or open the session picker |

33| `/review` | Request code review |39| `/review` | Request code review |

~~34| `/sandbox` | Enable sandboxed bash tool with filesystem and network isolation for safer, more autonomous execution |~~

35| `/rewind` | Rewind the conversation and/or code |40| `/rewind` | Rewind the conversation and/or code |

41| `/sandbox` | Enable sandboxed bash tool with filesystem and network isolation for safer, more autonomous execution |

42| `/security-review` | Complete a security review of pending changes on the current branch |

43| `/stats` | Visualize daily usage, session history, streaks, and model preferences |

36| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |44| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |

37| `/statusline` | Set up Claude Code's status line UI |45| `/statusline` | Set up Claude Code's status line UI |

38| `/terminal-setup` | Install Shift+Enter key binding for newlines (iTerm2 and VSCode only) |46| `/terminal-setup` | Install Shift+Enter key binding for newlines (iTerm2 and VSCode only) |

41| `/vim` | Enter vim mode for alternating insert and command modes |49| `/vim` | Enter vim mode for alternating insert and command modes |

42 50

43## Custom slash commands51## Custom slash commands

44 52

45Custom slash commands allow you to define frequently-used prompts as Markdown files that Claude Code can execute. Commands are organized by scope (project-specific or personal) and support namespacing through directory structures.53Custom slash commands allow you to define frequently used prompts as Markdown files that Claude Code can execute. Commands are organized by scope (project-specific or personal) and support namespacing through directory structures.

46 54

47### Syntax55### Syntax

48 56

65 73

66**Location**: `.claude/commands/`74**Location**: `.claude/commands/`

67 75

~~68In the following example, we create the `/optimize` command:~~76The following example creates the `/optimize` command:

69 77

70```bash theme={null}78```bash theme={null}

71# Create a project command79# Create a project command

79 87

80**Location**: `~/.claude/commands/`88**Location**: `~/.claude/commands/`

81 89

~~82In the following example, we create the `/security-review` command:~~90The following example creates the `/security-review` command:

83 91

84```bash theme={null}92```bash theme={null}

85# Create a personal command93# Create a personal command

91 99

92#### Namespacing100#### Namespacing

93 101

94Organize commands in subdirectories. The subdirectories are used for organization and appear in the command description, but they do not affect the command name itself. The description will show whether the command comes from the project directory (`.claude/commands`) or the user-level directory (`~/.claude/commands`), along with the subdirectory name.102Use subdirectories to group related commands. Subdirectories appear in the command description but don't affect the command name.

103

104For example:

95 105

~~96Conflicts between user and project level commands are not supported. Otherwise, multiple commands with the same base file name can coexist.~~106* `.claude/commands/frontend/component.md` creates `/component` with description "(project:frontend)"

107* `~/.claude/commands/component.md` creates `/component` with description "(user)"

97 108

~~98For example, a file at `.claude/commands/frontend/component.md` creates the command `/component` with description showing "(project:frontend)".~~109If a project command and user command share the same name, the project command takes precedence and the user command is silently ignored. For example, if both `.claude/commands/deploy.md` and `~/.claude/commands/deploy.md` exist, `/deploy` runs the project version.

~~99Meanwhile, a file at `~/.claude/commands/component.md` creates the command `/component` with description showing "(user)".~~110

111Commands in different subdirectories can share names since the subdirectory appears in the description to distinguish them. For example, `.claude/commands/frontend/test.md` and `.claude/commands/backend/test.md` both create `/test`, but show as "(project:frontend)" and "(project:backend)" respectively.

100 112

101#### Arguments113#### Arguments

102 114

192 204

193For example:205For example:

304 316

305#### Naming conventions317#### Naming conventions

306 318

307* Server and prompt names are normalized319Server and prompt names are normalized:

320

308* Spaces and special characters become underscores321* Spaces and special characters become underscores

309* Names are lowercased for consistency322* Names are lowercase for consistency

310 323

311### Managing MCP connections324### Managing MCP connections

312 325

320 333

321### MCP permissions and wildcards334### MCP permissions and wildcards

322 335

323When configuring [permissions for MCP tools](/en/iam#tool-specific-permission-rules), note that **wildcards are not supported**:336To approve all tools from an MCP server, use either the server name alone or wildcard syntax:

337

338* `mcp__github` (approves all GitHub tools)

339* `mcp__github__*` (wildcard syntax, also approves all GitHub tools)

324 340

325* ✅ **Correct**: `mcp__github` (approves ALL tools from the github server)341To approve specific tools, list each one explicitly:

326* ✅ **Correct**: `mcp__github__get_issue` (approves specific tool)

327* ❌ **Incorrect**: `mcp__github__*` (wildcards not supported)

328 342

329To approve all tools from an MCP server, use just the server name: `mcp__servername`. To approve specific tools only, list each tool individually.343* `mcp__github__get_issue`

344* `mcp__github__list_issues`

345

346See [MCP permission rules](/en/iam#tool-specific-permission-rules) for more details.

330 347

331## `SlashCommand` tool348## `SlashCommand` tool

332 349

334during a conversation. This gives Claude the ability to invoke custom commands351during a conversation. This gives Claude the ability to invoke custom commands

335on your behalf when appropriate.352on your behalf when appropriate.

336 353

337To encourage Claude to trigger `SlashCommand` tool, your instructions (prompts,354To encourage Claude to use the `SlashCommand` tool, reference the command by name, including the slash, in your prompts or `CLAUDE.md` file. For example:

338CLAUDE.md, etc.) generally need to reference the command by name with its slash.

~~339~~

340Example:

341 355

342```356```

343> Run /write-unit-test when you are about to start writing tests.357> Run /write-unit-test when you are about to start writing tests.

344```358```

345 359

346This tool puts each available custom slash command's metadata into context up to the360This tool puts each available custom slash command's metadata into context up to the character budget limit. You can use `/context` to monitor token usage and follow the operations below to manage context.

347character budget limit. You can use `/context` to monitor token usage and follow

348the operations below to manage context.

349 361

350### `SlashCommand` tool supported commands362### `SlashCommand` tool supported commands

351 363

352`SlashCommand` tool only supports custom slash commands that:364`SlashCommand` tool only supports custom slash commands that:

353 365

354* Are user-defined. Built-in commands like `/compact` and `/init` are *not* supported.366* Are user-defined. Built-in commands like `/compact` and `/init` are *not* supported.

355* Have the `description` frontmatter field populated. We use the `description` in the context.367* Have the `description` frontmatter field populated. The description is used in the context.

356 368

357For Claude Code versions >= 1.0.124, you can see which custom slash commands369For Claude Code versions >= 1.0.124, you can see which custom slash commands

358`SlashCommand` tool can invoke by running `claude --debug` and triggering a query.370`SlashCommand` tool can invoke by running `claude --debug` and triggering a query.

366# Add to deny rules: SlashCommand378# Add to deny rules: SlashCommand

367```379```

368 380

369This will also remove SlashCommand tool (and the slash command descriptions) from context.381This also removes the SlashCommand tool and command descriptions from context.

370 382

371### Disable specific commands only383### Disable specific commands only

372 384

373To prevent a specific slash command from becoming available, add385To prevent a specific slash command from becoming available, add

374`disable-model-invocation: true` to the slash command's frontmatter.386`disable-model-invocation: true` to the slash command's frontmatter.

375 387

376This will also remove the command's metadata from context.388This also removes the command's metadata from context.

377 389

378### `SlashCommand` permission rules390### `SlashCommand` permission rules

379 391

388descriptions shown to Claude. This prevents token overflow when many commands400descriptions shown to Claude. This prevents token overflow when many commands

389are available.401are available.

390 402

391The budget includes each custom slash command's name, args, and description.403The budget includes each custom slash command's name, arguments, and description.

392 404

393* **Default limit**: 15,000 characters405* **Default limit**: 15,000 characters

394* **Custom limit**: Set via `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable406* **Custom limit**: Set via `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable

395 407

396When the character budget is exceeded, Claude will see only a subset of the408When the character budget is exceeded, Claude sees only a subset of the available commands. In `/context`, a warning shows "M of N commands".

397available commands. In `/context`, a warning will show with "M of N commands".

398 409

399## Skills vs slash commands410## Skills vs slash commands

400 411

402 413

403### Use slash commands for414### Use slash commands for

404 415

405**Quick, frequently-used prompts**:416**Quick, frequently used prompts**:

406 417

407* Simple prompt snippets you use often418* Simple prompt snippets you use often

408* Quick reminders or templates419* Quick reminders or templates

409* Frequently-used instructions that fit in one file420* Frequently used instructions that fit in one file

410 421

411**Examples**:422**Examples**:

412 423

497* [CLI reference](/en/cli-reference) - Command-line flags and options508* [CLI reference](/en/cli-reference) - Command-line flags and options

498* [Settings](/en/settings) - Configuration options509* [Settings](/en/settings) - Configuration options

499* [Memory management](/en/memory) - Managing Claude's memory across sessions510* [Memory management](/en/memory) - Managing Claude's memory across sessions

511

512

513---

514

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

statusline.md +51 −1

Details

25## How it Works25## How it Works

26 26

27* The status line is updated when the conversation messages update27* The status line is updated when the conversation messages update

~~28* Updates run at most every 300ms~~28* Updates run at most every 300 ms

29* The first line of stdout from your command becomes the status line text29* The first line of stdout from your command becomes the status line text

30* ANSI color codes are supported for styling your status line30* ANSI color codes are supported for styling your status line

31* Claude Code passes contextual information about the current session (model, directories, etc.) as JSON to your script via stdin31* Claude Code passes contextual information about the current session (model, directories, etc.) as JSON to your script via stdin

58 "total_api_duration_ms": 2300,58 "total_api_duration_ms": 2300,

59 "total_lines_added": 156,59 "total_lines_added": 156,

60 "total_lines_removed": 2360 "total_lines_removed": 23

61 },

62 "context_window": {

63 "total_input_tokens": 15234,

64 "total_output_tokens": 4521,

65 "context_window_size": 200000,

66 "current_usage": {

67 "input_tokens": 8500,

68 "output_tokens": 1200,

69 "cache_creation_input_tokens": 5000,

70 "cache_read_input_tokens": 2000

71 }

61 }72 }

62}73}

63```74```

181get_duration() { echo "$input" | jq -r '.cost.total_duration_ms'; }192get_duration() { echo "$input" | jq -r '.cost.total_duration_ms'; }

182get_lines_added() { echo "$input" | jq -r '.cost.total_lines_added'; }193get_lines_added() { echo "$input" | jq -r '.cost.total_lines_added'; }

183get_lines_removed() { echo "$input" | jq -r '.cost.total_lines_removed'; }194get_lines_removed() { echo "$input" | jq -r '.cost.total_lines_removed'; }

195get_input_tokens() { echo "$input" | jq -r '.context_window.total_input_tokens'; }

196get_output_tokens() { echo "$input" | jq -r '.context_window.total_output_tokens'; }

197get_context_window_size() { echo "$input" | jq -r '.context_window.context_window_size'; }

184 198

185# Use the helpers199# Use the helpers

186MODEL=$(get_model_name)200MODEL=$(get_model_name)

188echo "[$MODEL] 📁 ${DIR##*/}"202echo "[$MODEL] 📁 ${DIR##*/}"

189```203```

190 204

205### Context Window Usage

206

207Display the percentage of context window consumed. The `context_window` object contains:

208

209* `total_input_tokens` / `total_output_tokens`: Cumulative totals across the entire session

210* `current_usage`: Current context window usage from the last API call (may be `null` if no messages yet)

211 * `input_tokens`: Input tokens in current context

212 * `output_tokens`: Output tokens generated

213 * `cache_creation_input_tokens`: Tokens written to cache

214 * `cache_read_input_tokens`: Tokens read from cache

215

216For accurate context percentage, use `current_usage` which reflects the actual context window state:

217

218```bash theme={null}

219#!/bin/bash

220input=$(cat)

221

222MODEL=$(echo "$input" | jq -r '.model.display_name')

223CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')

224USAGE=$(echo "$input" | jq '.context_window.current_usage')

225

226if [ "$USAGE" != "null" ]; then

227 # Calculate current context from current_usage fields

228 CURRENT_TOKENS=$(echo "$USAGE" | jq '.input_tokens + .cache_creation_input_tokens + .cache_read_input_tokens')

229 PERCENT_USED=$((CURRENT_TOKENS * 100 / CONTEXT_SIZE))

230 echo "[$MODEL] Context: ${PERCENT_USED}%"

231else

232 echo "[$MODEL] Context: 0%"

233fi

234```

235

191## Tips236## Tips

192 237

193* Keep your status line concise - it should fit on one line238* Keep your status line concise - it should fit on one line

200 245

201* If your status line doesn't appear, check that your script is executable (`chmod +x`)246* If your status line doesn't appear, check that your script is executable (`chmod +x`)

202* Ensure your script outputs to stdout (not stderr)247* Ensure your script outputs to stdout (not stderr)

248

249

250---

251

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

sub-agents.md +102 −11

Details

27 </Card>27 </Card>

28 28

29 <Card title="Reusability" icon="rotate">29 <Card title="Reusability" icon="rotate">

~~30 Once created, subagents can be used across different projects and shared with your team for consistent workflows.~~30 Once created, you can use subagents across different projects and share them with your team for consistent workflows.

31 </Card>31 </Card>

32 32

33 <Card title="Flexible permissions" icon="shield-check">33 <Card title="Flexible permissions" icon="shield-check">

53 </Step>53 </Step>

54 54

55 <Step title="Define the subagent">55 <Step title="Define the subagent">

~~56 * **Recommended**: Generate with Claude first, then customize to make it yours~~56 * **Recommended**: generate with Claude first, then customize to make it yours

~~57 * Describe your subagent in detail and when it should be used~~57 * Describe your subagent in detail, including when Claude should use it

~~58 * Select the tools you want to grant access to (or leave blank to inherit all tools)~~58 * Select the tools you want to grant access to, or leave this blank to inherit all tools

~~59 * The interface shows all available tools, making selection easy~~59 * The interface shows all available tools

60 * If you're generating with Claude, you can also edit the system prompt in your own editor by pressing `e`60 * If you're generating with Claude, you can also edit the system prompt in your own editor by pressing `e`

61 </Step>61 </Step>

62 62

63 <Step title="Save and use">63 <Step title="Save and use">

~~64 Your subagent is now available! Claude will use it automatically when appropriate, or you can invoke it explicitly:~~64 Your subagent is now available. Claude uses it automatically when appropriate, or you can invoke it explicitly:

65 65

66 ```66 ```

67 > Use the code-reviewer subagent to check my recent changes67 > Use the code-reviewer subagent to check my recent changes

86 86

87[Plugins](/en/plugins) can provide custom subagents that integrate seamlessly with Claude Code. Plugin agents work identically to user-defined agents and appear in the `/agents` interface.87[Plugins](/en/plugins) can provide custom subagents that integrate seamlessly with Claude Code. Plugin agents work identically to user-defined agents and appear in the `/agents` interface.

88 88

~~89**Plugin agent locations**: Plugins include agents in their `agents/` directory (or custom paths specified in the plugin manifest).~~89**Plugin agent locations**: plugins include agents in their `agents/` directory (or custom paths specified in the plugin manifest).

90 90

91**Using plugin agents**:91**Using plugin agents**:

92 92

133description: Description of when this subagent should be invoked133description: Description of when this subagent should be invoked

134tools: tool1, tool2, tool3 # Optional - inherits all tools if omitted134tools: tool1, tool2, tool3 # Optional - inherits all tools if omitted

135model: sonnet # Optional - specify model alias or 'inherit'135model: sonnet # Optional - specify model alias or 'inherit'

136permissionMode: default # Optional - permission mode for the subagent

137skills: skill1, skill2 # Optional - skills to auto-load

136---138---

137 139

138Your subagent's system prompt goes here. This can be multiple paragraphs140Your subagent's system prompt goes here. This can be multiple paragraphs

146#### Configuration fields148#### Configuration fields

147 149

149| :------------ | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |151| :--------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

150| `name` | Yes | Unique identifier using lowercase letters and hyphens |152| `name` | Yes | Unique identifier using lowercase letters and hyphens |

151| `description` | Yes | Natural language description of the subagent's purpose |153| `description` | Yes | Natural language description of the subagent's purpose |

152| `tools` | No | Comma-separated list of specific tools. If omitted, inherits all tools from the main thread |154| `tools` | No | Comma-separated list of specific tools. If omitted, inherits all tools from the main thread |

153| `model` | No | Model to use for this subagent. Can be a model alias (`sonnet`, `opus`, `haiku`) or `'inherit'` to use the main conversation's model. If omitted, defaults to the [configured subagent model](/en/model-config) |155| `model` | No | Model to use for this subagent. Can be a model alias (`sonnet`, `opus`, `haiku`) or `'inherit'` to use the main conversation's model. If omitted, defaults to the [configured subagent model](/en/model-config) |

156| `permissionMode` | No | Permission mode for the subagent. Valid values: `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`, `ignore`. Controls how the subagent handles permission requests |

157| `skills` | No | Comma-separated list of skill names to auto-load when the subagent starts. Subagents do not inherit Skills from the parent conversation. If omitted, no Skills are preloaded. |

154 158

155### Model selection159### Model selection

156 160

196* Edit existing custom subagents, including their tool access200* Edit existing custom subagents, including their tool access

197* Delete custom subagents201* Delete custom subagents

198* See which subagents are active when duplicates exist202* See which subagents are active when duplicates exist

199* **Easily manage tool permissions** with a complete list of available tools203* **Manage tool permissions** with a complete list of available tools

200 204

201### Direct file management205### Direct file management

202 206

217# ... create subagent file221# ... create subagent file

218```222```

219 223

224<Note>

225 Subagents created by manually adding files will be loaded the next time you start a Claude Code session. To create and use a subagent immediately without restarting, use the `/agents` command instead.

226</Note>

227

220## Using subagents effectively228## Using subagents effectively

221 229

222### Automatic delegation230### Automatic delegation

245 253

246Claude Code includes built-in subagents that are available out of the box:254Claude Code includes built-in subagents that are available out of the box:

247 255

256### General-purpose subagent

257

258The general-purpose subagent is a capable agent for complex, multi-step tasks that require both exploration and action. Unlike the Explore subagent, it can modify files and execute a wider range of operations.

259

260**Key characteristics:**

261

262* **Model**: Uses Sonnet for more capable reasoning

263* **Tools**: Has access to all tools

264* **Mode**: Can read and write files, execute commands, make changes

265* **Purpose**: Complex research tasks, multi-step operations, code modifications

266

267**When Claude uses it:**

268

269Claude delegates to the general-purpose subagent when:

270

271* The task requires both exploration and modification

272* Complex reasoning is needed to interpret search results

273* Multiple strategies may be needed if initial searches fail

274* The task has multiple steps that depend on each other

275

276**Example scenario:**

277

278```

279User: Find all the places where we handle authentication and update them to use the new token format

280

281Claude: [Invokes general-purpose subagent]

282[Agent searches for auth-related code across codebase]

283[Agent reads and analyzes multiple files]

284[Agent makes necessary edits]

285[Returns detailed writeup of changes made]

286```

287

248### Plan subagent288### Plan subagent

249 289

250The Plan subagent is a specialized built-in agent designed for use during plan mode. When Claude is operating in plan mode (non-execution mode), it uses the Plan subagent to conduct research and gather information about your codebase before presenting a plan.290The Plan subagent is a specialized built-in agent designed for use during plan mode. When Claude is operating in plan mode (non-execution mode), it uses the Plan subagent to conduct research and gather information about your codebase before presenting a plan.

274 The Plan subagent is only used in plan mode. In normal execution mode, Claude uses the general-purpose agent or other custom subagents you've created.314 The Plan subagent is only used in plan mode. In normal execution mode, Claude uses the general-purpose agent or other custom subagents you've created.

275</Tip>315</Tip>

276 316

317### Explore subagent

318

319The Explore subagent is a fast, lightweight agent optimized for searching and analyzing codebases. It operates in strict read-only mode and is designed for rapid file discovery and code exploration.

320

321**Key characteristics:**

322

323* **Model**: Uses Haiku for fast, low-latency searches

324* **Mode**: Strictly read-only - cannot create, modify, or delete files

325* **Tools available**:

326 * Glob - File pattern matching

327 * Grep - Content searching with regular expressions

328 * Read - Reading file contents

329 * Bash - Read-only commands only (ls, git status, git log, git diff, find, cat, head, tail)

330

331**When Claude uses it:**

332

333Claude will delegate to the Explore subagent when it needs to search or understand a codebase but doesn't need to make changes. This is more efficient than the main agent running multiple search commands directly, as content found during the exploration process doesn't bloat the main conversation.

334

335**Thoroughness levels:**

336

337When invoking the Explore subagent, Claude specifies a thoroughness level:

338

339* **Quick** - Fast searches with minimal exploration. Good for targeted lookups.

340* **Medium** - Moderate exploration. Balances speed and thoroughness.

341* **Very thorough** - Comprehensive analysis across multiple locations and naming conventions. Used when the target might be in unexpected places.

342

343**Example scenarios:**

344

345```

346User: Where are errors from the client handled?

347

348Claude: [Invokes Explore subagent with "medium" thoroughness]

349[Explore uses Grep to search for error handling patterns]

350[Explore uses Read to examine promising files]

351[Returns findings with absolute file paths]

352Claude: Client errors are handled in src/services/process.ts:712...

353```

354

355```

356User: What's the codebase structure?

357

358Claude: [Invokes Explore subagent with "quick" thoroughness]

359[Explore uses Glob and ls to map directory structure]

360[Returns overview of key directories and their purposes]

361```

362

277## Example subagents363## Example subagents

278 364

279### Code reviewer365### Code reviewer

2943. Begin review immediately3803. Begin review immediately

295 381

296Review checklist:382Review checklist:

297- Code is simple and readable383- Code is clear and readable

298- Functions and variables are well-named384- Functions and variables are well-named

299- No duplicated code385- No duplicated code

300- Proper error handling386- Proper error handling

343- Testing approach429- Testing approach

344- Prevention recommendations430- Prevention recommendations

345 431

346Focus on fixing the underlying issue, not just symptoms.432Focus on fixing the underlying issue, not the symptoms.

347```433```

348 434

349### Data scientist435### Data scientist

477* [Slash commands](/en/slash-commands) - Learn about other built-in commands563* [Slash commands](/en/slash-commands) - Learn about other built-in commands

478* [Settings](/en/settings) - Configure Claude Code behavior564* [Settings](/en/settings) - Configure Claude Code behavior

479* [Hooks](/en/hooks) - Automate workflows with event handlers565* [Hooks](/en/hooks) - Automate workflows with event handlers

566

567

568---

569

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

terminal-config.md +6 −1

Details

10 10

11### Line breaks11### Line breaks

12 12

~~13You have several options for entering linebreaks into Claude Code:~~13You have several options for entering line breaks into Claude Code:

14 14

15* **Quick escape**: Type `\` followed by Enter to create a newline15* **Quick escape**: Type `\` followed by Enter to create a newline

16* **Keyboard shortcut**: Set up a keybinding to insert a newline16* **Keyboard shortcut**: Set up a keybinding to insert a newline

67* Mode switching: `Esc` (to NORMAL), `i`/`I`, `a`/`A`, `o`/`O` (to INSERT)67* Mode switching: `Esc` (to NORMAL), `i`/`I`, `a`/`A`, `o`/`O` (to INSERT)

68* Navigation: `h`/`j`/`k`/`l`, `w`/`e`/`b`, `0`/`$`/`^`, `gg`/`G`68* Navigation: `h`/`j`/`k`/`l`, `w`/`e`/`b`, `0`/`$`/`^`, `gg`/`G`

69* Editing: `x`, `dw`/`de`/`db`/`dd`/`D`, `cw`/`ce`/`cb`/`cc`/`C`, `.` (repeat)69* Editing: `x`, `dw`/`de`/`db`/`dd`/`D`, `cw`/`ce`/`cb`/`cc`/`C`, `.` (repeat)

72---

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

third-party-integrations.md +52 −9

Details

13 <th>Anthropic</th>13 <th>Anthropic</th>

14 <th>Amazon Bedrock</th>14 <th>Amazon Bedrock</th>

15 <th>Google Vertex AI</th>15 <th>Google Vertex AI</th>

16 <th>Microsoft Foundry</th>

16 </tr>17 </tr>

17 </thead>18 </thead>

18 19

22 <td>Supported [countries](https://www.anthropic.com/supported-countries)</td>23 <td>Supported [countries](https://www.anthropic.com/supported-countries)</td>

23 <td>Multiple AWS [regions](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html)</td>24 <td>Multiple AWS [regions](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html)</td>

24 <td>Multiple GCP [regions](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)</td>25 <td>Multiple GCP [regions](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)</td>

26 <td>Multiple Azure [regions](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/)</td>

25 </tr>27 </tr>

26 28

27 <tr>29 <tr>

29 <td>Enabled by default</td>31 <td>Enabled by default</td>

30 <td>Enabled by default</td>32 <td>Enabled by default</td>

31 <td>Enabled by default</td>33 <td>Enabled by default</td>

34 <td>Enabled by default</td>

32 </tr>35 </tr>

33 36

34 <tr>37 <tr>

35 <td>Authentication</td>38 <td>Authentication</td>

36 <td>API key</td>39 <td>API key</td>

~~37 <td>AWS credentials (IAM)</td>~~40 <td>API key or AWS credentials</td>

~~38 <td>GCP credentials (OAuth/Service Account)</td>~~41 <td>GCP credentials</td>

42 <td>API key or Microsoft Entra ID</td>

39 </tr>43 </tr>

40 44

41 <tr>45 <tr>

43 <td>Dashboard</td>47 <td>Dashboard</td>

44 <td>AWS Cost Explorer</td>48 <td>AWS Cost Explorer</td>

45 <td>GCP Billing</td>49 <td>GCP Billing</td>

50 <td>Azure Cost Management</td>

46 </tr>51 </tr>

47 52

48 <tr>53 <tr>

50 <td>Teams, usage monitoring</td>55 <td>Teams, usage monitoring</td>

51 <td>IAM policies, CloudTrail</td>56 <td>IAM policies, CloudTrail</td>

52 <td>IAM roles, Cloud Audit Logs</td>57 <td>IAM roles, Cloud Audit Logs</td>

58 <td>RBAC policies, Azure Monitor</td>

53 </tr>59 </tr>

54 </tbody>60 </tbody>

55</table>61</table>

56 62

57## Cloud providers63## Cloud providers

58 64

~~59<CardGroup cols={2}>~~65<CardGroup cols={3}>

~~60 <Card title="Amazon Bedrock" icon="aws" href="/en/docs/claude-code/amazon-bedrock">~~66 <Card title="Amazon Bedrock" icon="aws" href="/en/amazon-bedrock">

~~61 Use Claude models through AWS infrastructure with IAM-based authentication and AWS-native monitoring~~67 Use Claude models through AWS infrastructure with API key or IAM-based authentication and AWS-native monitoring

62 </Card>68 </Card>

63 69

~~64 <Card title="Google Vertex AI" icon="google" href="/en/docs/claude-code/google-vertex-ai">~~70 <Card title="Google Vertex AI" icon="google" href="/en/google-vertex-ai">

65 Access Claude models via Google Cloud Platform with enterprise-grade security and compliance71 Access Claude models via Google Cloud Platform with enterprise-grade security and compliance

66 </Card>72 </Card>

74 <Card title="Microsoft Foundry" icon="microsoft" href="/en/microsoft-foundry">

75 Access Claude through Azure with API key or Microsoft Entra ID authentication and Azure billing

76 </Card>

67</CardGroup>77</CardGroup>

68 78

69## Corporate infrastructure79## Corporate infrastructure

70 80

71<CardGroup cols={2}>81<CardGroup cols={2}>

~~72 <Card title="Enterprise Network" icon="shield" href="/en/docs/claude-code/network-config">~~82 <Card title="Enterprise Network" icon="shield" href="/en/network-config">

73 Configure Claude Code to work with your organization's proxy servers and SSL/TLS requirements83 Configure Claude Code to work with your organization's proxy servers and SSL/TLS requirements

74 </Card>84 </Card>

75 85

~~76 <Card title="LLM Gateway" icon="server" href="/en/docs/claude-code/llm-gateway">~~86 <Card title="LLM Gateway" icon="server" href="/en/llm-gateway">

77 Deploy centralized model access with usage tracking, budgeting, and audit logging87 Deploy centralized model access with usage tracking, budgeting, and audit logging

78 </Card>88 </Card>

79</CardGroup>89</CardGroup>

117export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 # If gateway handles AWS auth127export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 # If gateway handles AWS auth

118```128```

119 129

130### Using Foundry with corporate proxy

131

132Route Azure traffic through a corporate HTTP/HTTPS proxy:

133

134```bash theme={null}

135# Enable Microsoft Foundry

136export CLAUDE_CODE_USE_FOUNDRY=1

137export ANTHROPIC_FOUNDRY_RESOURCE=your-resource

138export ANTHROPIC_FOUNDRY_API_KEY=your-api-key # Or omit for Entra ID auth

139

140# Configure corporate proxy

141export HTTPS_PROXY='https://proxy.example.com:8080'

142```

143

144### Using Foundry with LLM Gateway

145

146Use a gateway service that provides Azure-compatible endpoints:

147

148```bash theme={null}

149# Enable Microsoft Foundry

150export CLAUDE_CODE_USE_FOUNDRY=1

151

152# Configure LLM gateway

153export ANTHROPIC_FOUNDRY_BASE_URL='https://your-llm-gateway.com'

154export CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1 # If gateway handles Azure auth

155```

156

120### Using Vertex AI with corporate proxy157### Using Vertex AI with corporate proxy

121 158

122Route Vertex AI traffic through a corporate HTTP/HTTPS proxy:159Route Vertex AI traffic through a corporate HTTP/HTTPS proxy:

211 248

212MCP is a great way to give Claude Code more information, such as connecting to ticket management systems or error logs. We recommend that one central team configures MCP servers and checks a `.mcp.json` configuration into the codebase so that all users benefit. [Learn more](/en/mcp).249MCP is a great way to give Claude Code more information, such as connecting to ticket management systems or error logs. We recommend that one central team configures MCP servers and checks a `.mcp.json` configuration into the codebase so that all users benefit. [Learn more](/en/mcp).

213 250

214At Anthropic, we trust Claude Code to power development across every Anthropic codebase. We hope you enjoy using Claude Code as much as we do!251At Anthropic, we trust Claude Code to power development across every Anthropic codebase. We hope you enjoy using Claude Code as much as we do.

215 252

216## Next steps253## Next steps

217 254

218* [Set up Amazon Bedrock](/en/amazon-bedrock) for AWS-native deployment255* [Set up Amazon Bedrock](/en/amazon-bedrock) for AWS-native deployment

219* [Configure Google Vertex AI](/en/google-vertex-ai) for GCP deployment256* [Configure Google Vertex AI](/en/google-vertex-ai) for GCP deployment

257* [Set up Microsoft Foundry](/en/microsoft-foundry) for Azure deployment

220* [Configure Enterprise Network](/en/network-config) for network requirements258* [Configure Enterprise Network](/en/network-config) for network requirements

221* [Deploy LLM Gateway](/en/llm-gateway) for enterprise management259* [Deploy LLM Gateway](/en/llm-gateway) for enterprise management

222* [Settings](/en/settings) for configuration options and environment variables260* [Settings](/en/settings) for configuration options and environment variables

261

262

263---

264

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

troubleshooting.md +89 −29

Details

50```50```

51 51

52<Warning>52<Warning>

53 Avoid disabling Windows PATH importing (`appendWindowsPath = false`) as this breaks the ability to easily call Windows executables from WSL. Similarly, avoid uninstalling Node.js from Windows if you use it for Windows development.53 Avoid disabling Windows PATH importing (`appendWindowsPath = false`) as this breaks the ability to call Windows executables from WSL. Similarly, avoid uninstalling Node.js from Windows if you use it for Windows development.

54</Warning>54</Warning>

55 55

56### Linux and Mac installation issues: permission or command not found errors56### Linux and Mac installation issues: permission or command not found errors

57 57

58When installing Claude Code with npm, `PATH` problems may prevent access to `claude`.58When installing Claude Code with npm, `PATH` problems may prevent access to `claude`.

~~59You may also encounter permission errors if your npm global prefix is not user writable (eg. `/usr`, or `/usr/local`).~~59You may also encounter permission errors if your npm global prefix is not user writable (for example, `/usr`, or `/usr/local`).

60 60

61#### Recommended solution: Native Claude Code installation61#### Recommended solution: Native Claude Code installation

62 62

63Claude Code has a native installation that doesn't depend on npm or Node.js.63Claude Code has a native installation that doesn't depend on npm or Node.js.

64 64

~~65<Note>~~

~~66 The native Claude Code installer is currently in beta.~~

~~67</Note>~~

69Use the following command to run the native installer.65Use the following command to run the native installer.

70 66

71**macOS, Linux, WSL:**67**macOS, Linux, WSL:**

95 91

96```92```

97 93

~~98This command installs the appropriate build of Claude Code for your operating system and architecture and adds a symlink to the installation at `~/.local/bin/claude`.~~94This command installs the appropriate build of Claude Code for your operating system and architecture and adds a symlink to the installation at `~/.local/bin/claude` (or `%USERPROFILE%\.local\bin\claude.exe` on Windows).

99 95

100<Tip>96<Tip>

101 Make sure that you have the installation directory in your system PATH.97 Make sure that you have the installation directory in your system PATH.

102</Tip>98</Tip>

103 99

104#### Alternative solution: Migrate to local installation100### Windows: "Claude Code on Windows requires git-bash"

105 101

106Alternatively, if Claude Code will run, you can migrate to a local installation:102Claude Code on native Windows requires [Git for Windows](https://git-scm.com/downloads/win) which includes Git Bash. If Git is installed but not detected:

107 103

108```bash theme={null}1041. Set the path explicitly in PowerShell before running Claude:

109claude migrate-installer105 ```powershell theme={null}

110```106 $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

107 ```

111 108

112This moves Claude Code to `~/.claude/local/` and sets up an alias in your shell configuration. No `sudo` is required for future updates.1092. Or add it to your system environment variables permanently through System Properties → Environment Variables.

113 110

114After migration, restart your shell, and then verify your installation:111If Git is installed in a non-standard location, adjust the path accordingly.

115 112

116On macOS/Linux/WSL:113### Windows: "installMethod is native, but claude command not found"

117 114

118```bash theme={null}115If you see this error after installation, the `claude` command isn't in your PATH. Add it manually:

119which claude # Should show an alias to ~/.claude/local/claude

120```

121 116

122On Windows:117<Steps>

118 <Step title="Open Environment Variables">

119 Press `Win + R`, type `sysdm.cpl`, and press Enter. Click **Advanced** → **Environment Variables**.

120 </Step>

123 121

124```powershell theme={null}122 <Step title="Edit User PATH">

125where claude # Should show path to claude executable123 Under "User variables", select **Path** and click **Edit**. Click **New** and add:

126```124

125 ```

126 %USERPROFILE%\.local\bin

127 ```

128 </Step>

129

130 <Step title="Restart your terminal">

131 Close and reopen PowerShell or CMD for changes to take effect.

132 </Step>

133</Steps>

127 134

128Verify installation:135Verify installation:

129 136

155 162

156This removes your stored authentication information and forces a clean login.163This removes your stored authentication information and forces a clean login.

157 164

165## Configuration file locations

166

167Claude Code stores configuration in several locations:

168

169| File | Purpose |

170| :---------------------------- | :--------------------------------------------------------------------- |

171| `~/.claude/settings.json` | User settings (permissions, hooks, model overrides) |

172| `.claude/settings.json` | Project settings (checked into source control) |

173| `.claude/settings.local.json` | Local project settings (not committed) |

174| `~/.claude.json` | Global state (theme, OAuth, MCP servers, allowed tools) |

175| `.mcp.json` | Project MCP servers (checked into source control) |

176| `managed-settings.json` | [Enterprise managed settings](/en/settings#settings-files) |

177| `managed-mcp.json` | [Enterprise managed MCP servers](/en/mcp#enterprise-mcp-configuration) |

178

179On Windows, `~` refers to your user home directory, such as `C:\Users\YourName`.

180

181**Enterprise managed file locations:**

182

183* macOS: `/Library/Application Support/ClaudeCode/`

184* Linux/WSL: `/etc/claude-code/`

185* Windows: `C:\ProgramData\ClaudeCode\`

186

187For details on configuring these files, see [Settings](/en/settings) and [MCP](/en/mcp).

188

189### Resetting configuration

190

191To reset Claude Code to default settings, you can remove the configuration files:

192

193```bash theme={null}

194# Reset all user settings and state

195rm ~/.claude.json

196rm -rf ~/.claude/

197

198# Reset project-specific settings

199rm -rf .claude/

200rm .mcp.json

201```

202

203<Warning>

204 This will remove all your settings, allowed tools, MCP server configurations, and session history.

205</Warning>

206

158## Performance and stability207## Performance and stability

159 208

160### High CPU or memory usage209### High CPU or memory usage

252 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.301 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.

253</Note>302</Note>

254 303

255For additional JetBrains configuration tips, see our [IDE integration guide](/en/ide-integrations#jetbrains-plugin-settings).304For additional JetBrains configuration tips, see our [JetBrains IDE guide](/en/jetbrains#plugin-settings).

256 305

257### Reporting Windows IDE integration issues (both native and WSL)306### Reporting Windows IDE integration issues (both native and WSL)

258 307

259If you're experiencing IDE integration problems on Windows, please [create an issue](https://github.com/anthropics/claude-code/issues) with the following information: whether you are native (git bash), or WSL1/WSL2, WSL networking mode (NAT or mirrored), IDE name/version, Claude Code extension/plugin version, and shell type (bash/zsh/etc)308If you're experiencing IDE integration problems on Windows, [create an issue](https://github.com/anthropics/claude-code/issues) with the following information:

260 309

261### ESC key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals310* Environment type: native Windows (Git Bash) or WSL1/WSL2

311* WSL networking mode (if applicable): NAT or mirrored

312* IDE name and version

313* Claude Code extension/plugin version

314* Shell type: Bash, Zsh, PowerShell, etc.

262 315

263If you're using Claude Code in JetBrains terminals and the ESC key doesn't interrupt the agent as expected, this is likely due to a keybinding clash with JetBrains' default shortcuts.316### Escape key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals

317

318If you're using Claude Code in JetBrains terminals and the `Esc` key doesn't interrupt the agent as expected, this is likely due to a keybinding clash with JetBrains' default shortcuts.

264 319

265To fix this issue:320To fix this issue:

266 321

270 * Click "Configure terminal keybindings" and delete the "Switch focus to Editor" shortcut325 * Click "Configure terminal keybindings" and delete the "Switch focus to Editor" shortcut

2713. Apply the changes3263. Apply the changes

272 327

273This allows the ESC key to properly interrupt Claude Code operations.328This allows the `Esc` key to properly interrupt Claude Code operations.

274 329

275## Markdown formatting issues330## Markdown formatting issues

276 331

300 355

301**Solutions:**356**Solutions:**

302 357

3031. **Ask Claude to add language tags**: Simply request "Please add appropriate language tags to all code blocks in this markdown file."3581. **Ask Claude to add language tags**: Request "Add appropriate language tags to all code blocks in this markdown file."

304 359

3052. **Use post-processing hooks**: Set up automatic formatting hooks to detect and add missing language tags. See the [markdown formatting hook example](/en/hooks-guide#markdown-formatting-hook) for implementation details.3602. **Use post-processing hooks**: Set up automatic formatting hooks to detect and add missing language tags. See the [markdown formatting hook example](/en/hooks-guide#markdown-formatting-hook) for implementation details.

306 361

323To minimize formatting issues:378To minimize formatting issues:

324 379

325* **Be explicit in requests**: Ask for "properly formatted markdown with language-tagged code blocks"380* **Be explicit in requests**: Ask for "properly formatted markdown with language-tagged code blocks"

326* **Use project conventions**: Document your preferred markdown style in [CLAUDE.md](/en/memory)381* **Use project conventions**: Document your preferred markdown style in [`CLAUDE.md`](/en/memory)

327* **Set up validation hooks**: Use post-processing hooks to automatically verify and fix common formatting issues382* **Set up validation hooks**: Use post-processing hooks to automatically verify and fix common formatting issues

328 383

329## Getting more help384## Getting more help

3342. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues3892. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues

3353. Run `/doctor` to check the health of your Claude Code installation3903. Run `/doctor` to check the health of your Claude Code installation

3364. Ask Claude directly about its capabilities and features - Claude has built-in access to its documentation3914. Ask Claude directly about its capabilities and features - Claude has built-in access to its documentation

392

393

394---

395

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

vs-code.md +209 −77

Details

~~1# Visual Studio Code~~1# Use Claude Code in VS Code

2 2

~~3> Use Claude Code with Visual Studio Code through our native extension or CLI integration~~3> Install and configure the Claude Code extension for VS Code. Get AI coding assistance with inline diffs, @-mentions, plan review, and keyboard shortcuts.

4 4

5<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=300652d5678c63905e6b0ea9e50835f8" alt="Claude Code VS Code Extension Interface" data-og-width="2500" width="2500" data-og-height="1155" height="1155" data-path="images/vs-code-extension-interface.jpg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=280&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=87630c671517a3d52e9aee627041696e 280w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=560&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=716b093879204beec8d952649ef75292 560w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=840&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=c1525d1a01513acd9d83d8b5a8fe2fc8 840w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1100&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=1d90021d58bbb51f871efec13af955c3 1100w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1650&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=7babdd25440099886f193cfa99af88ae 1650w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=2500&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=08c92eedfb56fe61a61e480fb63784b6 2500w" />5<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=300652d5678c63905e6b0ea9e50835f8" alt="VS Code editor with the Claude Code extension panel open on the right side, showing a conversation with Claude" data-og-width="2500" width="2500" data-og-height="1155" height="1155" data-path="images/vs-code-extension-interface.jpg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=280&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=87630c671517a3d52e9aee627041696e 280w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=560&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=716b093879204beec8d952649ef75292 560w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=840&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=c1525d1a01513acd9d83d8b5a8fe2fc8 840w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1100&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=1d90021d58bbb51f871efec13af955c3 1100w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1650&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=7babdd25440099886f193cfa99af88ae 1650w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=2500&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=08c92eedfb56fe61a61e480fb63784b6 2500w" />

6 6

~~7## VS Code Extension (Beta)~~7The VS Code extension provides a native graphical interface for Claude Code, integrated directly into your IDE. This is the recommended way to use Claude Code in VS Code.

8 8

9The VS Code extension, available in beta, lets you see Claude's changes in real-time through a native graphical interface integrated directly into your IDE. The VS Code extension makes it easier to access and interact with Claude Code for users who prefer a visual interface over the terminal.9With the extension, you can review and edit Claude's plans before accepting them, auto-accept edits as they're made, @-mention files with specific line ranges from your selection, access conversation history, and open multiple conversations in separate tabs or windows.

10 10

~~11### Features~~11## Prerequisites

12 12

~~13The VS Code extension provides:~~13* VS Code 1.98.0 or higher

14* An Anthropic account (you'll sign in when you first open the extension). If you're using a third-party provider like Amazon Bedrock or Google Vertex AI, see [Use third-party providers](#use-third-party-providers) instead.

14 15

~~15* **Native IDE experience**: Dedicated Claude Code sidebar panel accessed via the Spark icon~~16You don't need to install the Claude Code CLI first. However, some features like MCP server configuration require the CLI. See [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) for details.

~~16* **Plan mode with editing**: Review and edit Claude's plans before accepting them~~

~~17* **Auto-accept edits mode**: Automatically apply Claude's changes as they're made~~

~~18* **File management**: @-mention files or attach files and images using the system file picker~~

~~19* **MCP server usage**: Use Model Context Protocol servers configured through the CLI~~

~~20* **Conversation history**: Easy access to past conversations~~

~~21* **Multiple sessions**: Run multiple Claude Code sessions simultaneously~~

~~22* **Keyboard shortcuts**: Support for most shortcuts from the CLI~~

~~23* **Slash commands**: Access most CLI slash commands directly in the extension~~

24 17

~~25### Requirements~~18## Install the extension

26 19

~~27* VS Code 1.98.0 or higher~~20Click the link for your IDE to install directly:

28 21

~~29### Installation~~22* [Install for VS Code](vscode:extension/anthropic.claude-code)

23* [Install for Cursor](cursor:extension/anthropic.claude-code)

30 24

~~31Download and install the extension from the [Visual Studio Code Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code).~~25Or in VS Code, press `Cmd+Shift+X` (Mac) or `Ctrl+Shift+X` (Windows/Linux) to open the Extensions view, search for "Claude Code", and click **Install**.

32 26

~~33### How It Works~~27<Note>You may need to restart VS Code or run "Developer: Reload Window" from the Command Palette after installation.</Note>

29## Get started

34 30

35Once installed, you can start using Claude Code through the VS Code interface:31Once installed, you can start using Claude Code through the VS Code interface:

36 32

~~371. Click the Spark icon in your editor's sidebar to open the Claude Code panel~~33<Steps>

~~382. Prompt Claude Code in the same way you would in the terminal~~34 <Step title="Open the Claude Code panel">

~~393. Watch as Claude analyzes your code and suggests changes~~35 Throughout VS Code, the Spark icon indicates Claude Code: <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=a734d84e785140016672f08e0abb236c" alt="Spark icon" style={{display: "inline", height: "0.85em", verticalAlign: "middle"}} data-og-width="16" width="16" data-og-height="16" height="16" data-path="images/vs-code-spark-icon.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=280&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=9a45aad9a84b9fa1701ac99a1f9aa4e9 280w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=560&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=3f4cb9254c4d4e93989c4b6bf9292f4b 560w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=840&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=e75ccc9faa3e572db8f291ceb65bb264 840w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=1100&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=f147bd81a381a62539a4ce361fac41c7 1100w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=1650&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=78fe68efaee5d6e844bbacab1b442ed5 1650w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=2500&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=efb8dbe1dfa722d094edc6ad2ad4bedb 2500w" />

~~404. Review and accept edits directly in the interface~~36

~~41 * **Tip**: Drag the sidebar wider to see inline diffs, then click on them to expand for full details~~37 The quickest way to open Claude is to click the Spark icon in the **Editor Toolbar** (top-right corner of the editor). The icon only appears when you have a file open.

39 <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=eb4540325d94664c51776dbbfec4cf02" alt="VS Code editor showing the Spark icon in the Editor Toolbar" data-og-width="2796" width="2796" data-og-height="734" height="734" data-path="images/vs-code-editor-icon.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=280&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=56f218d5464359d6480cfe23f70a923e 280w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=560&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=344a8db024b196c795a80dc85cacb8d1 560w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=840&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=f30bf834ee0625b2a4a635d552d87163 840w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=1100&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=81fdf984840e43a9f08ae42729d1484d 1100w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=1650&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=8b60fb32de54717093d512afaa99785c 1650w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=2500&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=893e6bda8f2e9d42c8a294d394f0b736 2500w" />

41 Other ways to open Claude Code:

43 * **Command Palette**: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux), type "Claude Code", and select an option like "Open in New Tab"

44 * **Status Bar**: Click **✱ Claude Code** in the bottom-right corner of the window. This works even when no file is open.

46 You can drag the Claude panel to reposition it anywhere in VS Code. See [Customize your workflow](#customize-your-workflow) for details.

47 </Step>

49 <Step title="Send a prompt">

50 Ask Claude to help with your code or files, whether that's explaining how something works, debugging an issue, or making changes.

52 <Tip>Select text in the editor and press `Alt+K` to insert an @-mention with the file path and line numbers directly into your prompt.</Tip>

54 Here's an example of asking about a particular line in a file:

56 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ede3ed8d8d5f940e01c5de636d009cfd" alt="VS Code editor with lines 2-3 selected in a Python file, and the Claude Code panel showing a question about those lines with an @-mention reference" data-og-width="3288" width="3288" data-og-height="1876" height="1876" data-path="images/vs-code-send-prompt.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=280&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=f40bde7b2c245fe8f0f5b784e8106492 280w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=560&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=fad66a27a9a6faa23b05370aa4f398b2 560w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=840&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=4539c8a3823ca80a5c8771f6c088ce9e 840w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=1100&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=fae8ebf300c7853409a562ffa46d9c71 1100w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=1650&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=22e4462bb8cf0c0ca20f8102bc4c971a 1650w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=2500&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=739bfd045f70fe7be1a109a53494590e 2500w" />

57 </Step>

59 <Step title="Review changes">

60 When Claude wants to edit a file, it shows you a diff and asks for permission. You can accept, reject, or tell Claude what to do instead.

62 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=e005f9b41c541c5c7c59c082f7c4841c" alt="VS Code showing a diff of Claude's proposed changes with a permission prompt asking whether to make the edit" data-og-width="3292" width="3292" data-og-height="1876" height="1876" data-path="images/vs-code-edits.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=280&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=cb5d41b81087f79b842a56b5a3304660 280w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=560&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=90bb691960decdc06393c3c21cd62c75 560w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=840&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=9a11bf878ba619e850380904ff4f38e8 840w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=1100&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=6dddbf596b4f69ec6245bdc5eb6dd487 1100w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=1650&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ef2713b8cbfd2cee97af817d813d64c7 1650w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=2500&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=1f7e1c52919cdfddf295f32a2ec7ae59 2500w" />

63 </Step>

64</Steps>

66For more ideas on what you can do with Claude Code, see [Common workflows](/en/common-workflows).

68## Customize your workflow

70Once you're up and running, you can reposition the Claude panel or switch to terminal mode.

72### Change the layout

74You can drag the Claude panel to reposition it anywhere in VS Code. Grab the panel's tab or title bar and drag it to:

76* **Secondary sidebar** (default): The right side of the window

77* **Primary sidebar**: The left sidebar with icons for Explorer, Search, etc.

78* **Editor area**: Opens Claude as a tab alongside your files

80<Note>

81 The Spark icon only appears in the Activity Bar (left sidebar icons) when the Claude panel is docked to the left. Since Claude defaults to the right side, use the Editor Toolbar icon to open Claude.

82</Note>

84### Switch to terminal mode

86By default, the extension opens a graphical chat panel. If you prefer the CLI-style interface, open the [Use Terminal setting](vscode://settings/claudeCode.useTerminal) and check the box.

88You can also open VS Code settings (`Cmd+,` on Mac or `Ctrl+,` on Windows/Linux), go to Extensions → Claude Code, and check **Use Terminal**.

90## VS Code commands and shortcuts

92Open the Command Palette (`Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Windows/Linux) and type "Claude Code" to see all available VS Code commands for the Claude Code extension:

42 93

~~43### Using Third-Party Providers (Vertex and Bedrock)~~94<Note>

95 These are VS Code commands for controlling the extension. For Claude Code slash commands (like `/help` or `/compact`), not all CLI commands are available in the extension yet. See [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) for details.

96</Note>

44 97

45The VS Code extension supports using Claude Code with third-party providers like Amazon Bedrock and Google Vertex AI. When configured with these providers, the extension will not prompt for login. To use third-party providers, configure environment variables in the VS Code extension settings:98| Command | Shortcut | Description |

99| -------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------- |

100| Focus Input | `Cmd+Esc` (Mac) / `Ctrl+Esc` (Windows/Linux) | Toggle focus between editor and Claude |

101| Open in Side Bar | — | Open Claude in the left sidebar |

102| Open in Terminal | — | Open Claude in terminal mode |

103| Open in New Tab | `Cmd+Shift+Esc` (Mac) / `Ctrl+Shift+Esc` (Windows/Linux) | Open a new conversation as an editor tab |

104| Open in New Window | — | Open a new conversation in a separate window |

105| New Conversation | `Cmd+N` (Mac) / `Ctrl+N` (Windows/Linux) | Start a new conversation (when Claude is focused) |

106| Insert @-Mention Reference | `Alt+K` | Insert a reference to the current file (includes line numbers if text is selected) |

107| Show Logs | — | View extension debug logs |

108| Logout | — | Sign out of your Anthropic account |

46 109

~~471. Open VS Code settings~~110Use **Open in New Tab** or **Open in New Window** to run multiple conversations simultaneously. Each tab or window maintains its own conversation history and context.

~~482. Search for "Claude Code: Environment Variables"~~

~~493. Add the required environment variables~~

50 111

~~51#### Environment Variables~~112## Configure settings

52 113

~~54| :---------------------------- | :------------------------------------- | :--------------------- | :----------------------------------------------- |~~

65 115

~~66For detailed setup instructions and additional configuration options, see:~~116* **Extension settings**: Open with `Cmd+,` (Mac) or `Ctrl+,` (Windows/Linux), then go to Extensions → Claude Code.

67 117

~~68* [Claude Code on Amazon Bedrock](/en/amazon-bedrock)~~118 | Setting | Description |

~~69* [Claude Code on Google Vertex AI](/en/google-vertex-ai)~~119 | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

120 | Selected Model | Default model for new conversations. Change per-session with `/model`. |

121 | Use Terminal | Launch Claude in terminal mode instead of graphical panel |

122 | Initial Permission Mode | Controls approval prompts for file edits and commands. Defaults to `default` (ask before each action). |

123 | Preferred Location | Default location: sidebar (right) or panel (new tab) |

124 | Autosave | Auto-save files before Claude reads or writes them |

125 | Use Ctrl+Enter to Send | Use Ctrl/Cmd+Enter instead of Enter to send prompts |

126 | Enable New Conversation Shortcut | Enable Cmd/Ctrl+N to start a new conversation |

127 | Respect Git Ignore | Exclude .gitignore patterns from file searches |

128 | Environment Variables | Set environment variables for the Claude process. **Not recommended**—use [Claude Code settings](/en/settings) instead so configuration is shared between extension and CLI. |

129 | Disable Login Prompt | Skip authentication prompts (for third-party provider setups) |

130 | Allow Dangerously Skip Permissions | Bypass all permission prompts. **Use with extreme caution**—recommended only for isolated sandboxes with no internet access. |

131 | Claude Process Wrapper | Executable path used to launch the Claude process |

70 132

~~71### Not Yet Implemented~~133* **Claude Code settings** (`~/.claude/settings.json`): These settings are shared between the VS Code extension and the CLI. Use this file for allowed commands and directories, environment variables, hooks, and MCP servers. See the [settings documentation](/en/settings) for details.

72 134

~~73The following features are not yet available in the VS Code extension:~~135## Use third-party providers

74 136

~~75* **Full MCP server configuration**: You need to [configure MCP servers through the CLI](/en/mcp) first, then the extension will use them~~137By default, Claude Code connects directly to Anthropic's API. If your organization uses Amazon Bedrock, Google Vertex AI, or Microsoft Foundry to access Claude, configure the extension to use your provider instead:

~~76* **Subagents configuration**: Configure [subagents through the CLI](/en/sub-agents) to use them in VS Code~~

~~77* **Checkpoints**: Save and restore conversation state at specific points~~

~~78* **Advanced shortcuts**:~~

~~79 * `#` shortcut to add to memory~~

~~80 * `!` shortcut to run bash commands directly~~

~~81* **Tab completion**: File path completion with tab key~~

82 138

~~83We are working on adding these features in future updates.~~139<Steps>

140 <Step title="Disable login prompt">

141 Open the [Disable Login Prompt setting](vscode://settings/claudeCode.disableLoginPrompt) and check the box.

84 142

~~85## Security Considerations~~143 You can also open VS Code settings (`Cmd+,` on Mac or `Ctrl+,` on Windows/Linux), search for "Claude Code login", and check **Disable Login Prompt**.

144 </Step>

86 145

87When Claude Code runs in VS Code with auto-edit permissions enabled, it may be able to modify IDE configuration files that can be automatically executed by your IDE. This may increase the risk of running Claude Code in auto-edit mode and allow bypassing Claude Code's permission prompts for bash execution.146 <Step title="Configure your provider">

147 Follow the setup guide for your provider:

88 148

~~89When running in VS Code, consider:~~149 * [Claude Code on Amazon Bedrock](/en/amazon-bedrock)

150 * [Claude Code on Google Vertex AI](/en/google-vertex-ai)

151 * [Claude Code on Microsoft Foundry](/en/microsoft-foundry)

90 152

~~91* Enabling [VS Code Restricted Mode](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode) for untrusted workspaces~~153 These guides cover configuring your provider in `~/.claude/settings.json`, which ensures your settings are shared between the VS Code extension and the CLI.

~~92* Using manual approval mode for edits~~154 </Step>

~~93* Taking extra care to ensure Claude is only used with trusted prompts~~155</Steps>

94 156

~~95## Legacy CLI Integration~~157## VS Code extension vs. Claude Code CLI

96 158

97The first VS Code integration that we released allows Claude Code running in the terminal to interact with your IDE. It provides selection context sharing (current selection/tab is automatically shared with Claude Code), diff viewing in the IDE instead of terminal, file reference shortcuts (`Cmd+Option+K` on Mac or `Alt+Ctrl+K` on Windows/Linux to insert file references like @File#L1-99), and automatic diagnostic sharing (lint and syntax errors).159The extension doesn't yet have full feature parity with the CLI. If you need CLI-only features, you can run `claude` directly in VS Code's integrated terminal.

98 160

99The legacy integration auto-installs when you run `claude` from VS Code's integrated terminal. Simply run `claude` from the terminal and all features activate. For external terminals, use the `/ide` command to connect Claude Code to your VS Code instance. To configure, run `claude`, enter `/config`, and set the diff tool to `auto` for automatic IDE detection.161| Feature | CLI | VS Code Extension |

162| ----------------- | ------------------------------ | ---------------------------------------- |

163| Slash commands | [Full set](/en/slash-commands) | Subset (type `/` to see available) |

164| MCP server config | Yes | No (configure via CLI, use in extension) |

165| Checkpoints | Yes | Coming soon |

166| `!` bash shortcut | Yes | No |

167| Tab completion | Yes | No |

100 168

101Both the extension and CLI integration work with Visual Studio Code, Cursor, Windsurf, and VSCodium.169### Run CLI in VS Code

102 170

103## Troubleshooting171To use the CLI while staying in VS Code, open the integrated terminal (`` Ctrl+` `` on Windows/Linux or `` Cmd+` `` on Mac) and run `claude`. The CLI automatically integrates with your IDE for features like diff viewing and diagnostic sharing.

104 172

105### Extension Not Installing173If using an external terminal, run `/ide` inside Claude Code to connect it to VS Code.

106 174

107* Ensure you have a compatible version of VS Code (1.85.0 or later)175### Switch between extension and CLI

176

177The extension and CLI share the same conversation history. To continue an extension conversation in the CLI, run `claude --resume` in the terminal. This opens an interactive picker where you can search for and select your conversation.

178

179## Security considerations

180

181With auto-edit permissions enabled, Claude Code can modify VS Code configuration files (like `settings.json` or `tasks.json`) that VS Code may execute automatically. This could potentially bypass Claude Code's normal permission prompts.

182

183To reduce risk when working with untrusted code:

184

185* Enable [VS Code Restricted Mode](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode) for untrusted workspaces

186* Use manual approval mode instead of auto-accept for edits

187* Review changes carefully before accepting them

188

189## Fix common issues

190

191### Extension won't install

192

193* Ensure you have a compatible version of VS Code (1.98.0 or later)

108* Check that VS Code has permission to install extensions194* Check that VS Code has permission to install extensions

109* Try installing directly from the marketplace website195* Try installing directly from the Marketplace website

196

197### Spark icon not visible

198

199The Spark icon appears in the **Editor Toolbar** (top-right of editor) when you have a file open. If you don't see it:

200

2011. **Open a file**: The icon requires a file to be open—having just a folder open isn't enough

2022. **Check VS Code version**: Requires 1.98.0 or higher (Help → About)

2033. **Restart VS Code**: Run "Developer: Reload Window" from the Command Palette

2044. **Disable conflicting extensions**: Temporarily disable other AI extensions (Cline, Continue, etc.)

2055. **Check workspace trust**: The extension doesn't work in Restricted Mode

206

207Alternatively, click "✱ Claude Code" in the **Status Bar** (bottom-right corner)—this works even without a file open. You can also use the **Command Palette** (`Cmd+Shift+P` / `Ctrl+Shift+P`) and type "Claude Code".

208

209### Claude Code never responds

110 210

111### Legacy Integration Not Working211If Claude Code isn't responding to your prompts:

112 212

113* Ensure you're running Claude Code from VS Code's integrated terminal2131. **Check your internet connection**: Ensure you have a stable internet connection

2142. **Start a new conversation**: Try starting a fresh conversation to see if the issue persists

2153. **Try the CLI**: Run `claude` from the terminal to see if you get more detailed error messages

2164. **File a bug report**: If the problem continues, [file an issue on GitHub](https://github.com/anthropics/claude-code/issues) with details about the error

217

218### Standalone CLI not connecting to IDE

219

220* Ensure you're running Claude Code from VS Code's integrated terminal (not an external terminal)

114* Ensure the CLI for your IDE variant is installed:221* Ensure the CLI for your IDE variant is installed:

115 * VS Code: `code` command should be available222 * VS Code: `code` command should be available

116 * Cursor: `cursor` command should be available223 * Cursor: `cursor` command should be available

117 * Windsurf: `windsurf` command should be available224 * Windsurf: `windsurf` command should be available

118 * VSCodium: `codium` command should be available225 * VSCodium: `codium` command should be available

119* If the command isn't installed:226* If the command isn't available, install it from the Command Palette → "Shell Command: Install 'code' command in PATH"

120 1. Open command palette with `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)227

121 2. Search for "Shell Command: Install 'code' command in PATH" (or equivalent for your IDE)228## Uninstall the extension

229

230To uninstall the Claude Code extension:

231

2321. Open the Extensions view (`Cmd+Shift+X` on Mac or `Ctrl+Shift+X` on Windows/Linux)

2332. Search for "Claude Code"

2343. Click **Uninstall**

235

236To also remove extension data and reset all settings:

237

238```bash theme={null}

239rm -rf ~/.vscode/globalStorage/anthropic.claude-code

240```

241

242For additional help, see the [troubleshooting guide](/en/troubleshooting).

243

244## Next steps

245

246Now that you have Claude Code set up in VS Code:

247

248* [Explore common workflows](/en/common-workflows) to get the most out of Claude Code

249* [Set up MCP servers](/en/mcp) to extend Claude's capabilities with external tools. Configure servers using the CLI, then use them in the extension.

250* [Configure Claude Code settings](/en/settings) to customize allowed commands, hooks, and more. These settings are shared between the extension and CLI.

251

252

253---

122 254

123For additional help, see our [troubleshooting guide](/en/troubleshooting).255> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

Anthropic - Claude Code Docs Changes 2025-11-06 12:02 UTC → 2026-01-06 21:01 UTC