Anthropic - Claude Code Docs Changes

amazon-bedrock.md +37 −12

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

58 66

59#### Advanced credential configuration67#### Advanced credential configuration

60 68

61Claude Code supports automatic credential refresh for AWS SSO and corporate identity providers. Add these settings to your Claude Code settings file (see [Settings](/en/docs/claude-code/settings) for file locations).69Claude Code supports automatic credential refresh for AWS SSO and corporate identity providers. Add these settings to your Claude Code settings file (see [Settings](/en/settings) for file locations).

62 70

63When Claude Code detects that your AWS credentials are expired (either locally based on their timestamp or when Bedrock returns a credential error), it will automatically run your configured `awsAuthRefresh` and/or `awsCredentialExport` commands to obtain new credentials before retrying the request.71When Claude Code detects that your AWS credentials are expired (either locally based on their timestamp or when Bedrock returns a credential error), it will automatically run your configured `awsAuthRefresh` and/or `awsCredentialExport` commands to obtain new credentials before retrying the request.

64 72

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{

106 114

107* `AWS_REGION` is a required environment variable. Claude Code does not read from the `.aws` config file for this setting.115* `AWS_REGION` is a required environment variable. Claude Code does not read from the `.aws` config file for this setting.

108* When using Bedrock, the `/login` and `/logout` commands are disabled since authentication is handled through AWS credentials.116* When using Bedrock, the `/login` and `/logout` commands are disabled since authentication is handled through AWS credentials.

109* You can use settings files for environment variables like `AWS_PROFILE` that you don't want to leak to other processes. See [Settings](/en/docs/claude-code/settings) for more information.117* You can use settings files for environment variables like `AWS_PROFILE` that you don't want to leak to other processes. See [Settings](/en/settings) for more information.

110 118

111### 4. Model configuration119### 4. Model configuration

112 120

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

203 We recommend creating a dedicated AWS account for Claude Code to simplify cost tracking and access control.209 We recommend creating a dedicated AWS account for Claude Code to simplify cost tracking and access control.

204</Note>210</Note>

205 211

212## AWS Guardrails

213

214[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) let you implement content filtering for Claude Code. Create a Guardrail in the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/), publish a version, then add the Guardrail headers to your [settings file](/en/settings). Enable Cross-Region inference on your Guardrail if you're using cross-region inference profiles.

215

216Example configuration:

217

218```json theme={null}

219{

220 "env": {

221 "ANTHROPIC_CUSTOM_HEADERS": "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id\nX-Amzn-Bedrock-GuardrailVersion: 1"

222 }

223}

224```

225

206## Troubleshooting226## Troubleshooting

207 227

208If you encounter region issues:228If you encounter region issues:

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

224* [Bedrock inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)244* [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)245* [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)

246

247

248---

249

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

analytics.md +7 −2

Details

83 83

84## Related resources84## Related resources

85 85

~~86* [Monitoring usage with OpenTelemetry](/en/docs/claude-code/monitoring-usage) for custom metrics and alerting~~86* [Monitoring usage with OpenTelemetry](/en/monitoring-usage) for custom metrics and alerting

~~87* [Identity and access management](/en/docs/claude-code/iam) for role configuration~~87* [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 +8 −3

Details

60 60

61## See also61## See also

62 62

~~63* [Interactive mode](/en/docs/claude-code/interactive-mode) - Keyboard shortcuts and session controls~~63* [Interactive mode](/en/interactive-mode) - Keyboard shortcuts and session controls

~~64* [Slash commands](/en/docs/claude-code/slash-commands) - Accessing checkpoints using `/rewind`~~64* [Built-in commands](/en/interactive-mode#built-in-commands) - Accessing checkpoints using `/rewind`

~~65* [CLI reference](/en/docs/claude-code/cli-reference) - Command-line options~~65* [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` 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 +98 −21

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

18 18

~~19Claude Code is also available on the Claude iOS app. This is perfect for:~~19Claude Code is also available on the Claude iOS app for kicking off tasks on the go and monitoring work in progress.

20 20

~~21* **On the go**: Kick off tasks while commuting or away from laptop~~21You can move between local and remote development: [send tasks from your terminal to run on the web](#from-terminal-to-web) with the `&` prefix, or [teleport web sessions back to your terminal](#from-web-to-terminal) to continue locally.

~~22* **Monitoring**: Watch the trajectory and steer the agent's work~~

~~24Developers can also move Claude Code sessions from the Claude app to their terminal to continue tasks locally.~~

25 22

26## Who can use Claude Code on the web?23## Who can use Claude Code on the web?

27 24

29 26

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

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

32 29* **Team premium seat users**

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

34 31

35## Getting started32## Getting started

36 33

54 51

55## Moving tasks between web and terminal52## Moving tasks between web and terminal

56 53

54You can start tasks on the web and continue them in your terminal, or send tasks from your terminal to run on the web. Web sessions persist even if you close your laptop, and you can monitor them from anywhere including the Claude iOS app.

56<Note>

57 Session handoff is one-way: you can pull web sessions into your terminal, but you can't push an existing terminal session to the web. The [`&` prefix](#from-terminal-to-web) creates a *new* web session with your current conversation context.

58</Note>

60### From terminal to web

62Start a message with `&` inside Claude Code to send a task to run on the web:

64```

65& Fix the authentication bug in src/auth/login.ts

66```

68This creates a new web session on claude.ai with your current conversation context. The task runs in the cloud while you continue working locally. Use `/tasks` to check progress, or open the session on claude.ai or the Claude iOS app to interact directly. From there you can steer Claude, provide feedback, or answer questions just like any other conversation.

70You can also start a web session directly from the command line:

72```bash theme={null}

73claude --remote "Fix the authentication bug in src/auth/login.ts"

74```

76#### Tips for background tasks

78**Plan locally, execute remotely**: For complex tasks, start Claude in plan mode to collaborate on the approach before sending work to the web:

80```bash theme={null}

81claude --permission-mode plan

82```

84In plan mode, Claude can only read files and explore the codebase. Once you're satisfied with the plan, send it to the web for autonomous execution:

86```

87& Execute the migration plan we discussed

88```

90This pattern gives you control over the strategy while letting Claude execute autonomously in the cloud.

92**Run tasks in parallel**: Each `&` command creates its own web session that runs independently. You can kick off multiple tasks and they'll all run simultaneously in separate sessions:

94```

95& Fix the flaky test in auth.spec.ts

96& Update the API documentation

97& Refactor the logger to use structured output

98```

100Monitor all sessions with `/tasks`. When a session completes, you can create a PR from the web interface or [teleport](#from-web-to-terminal) the session to your terminal to continue working.

101

57### From web to terminal102### From web to terminal

58 103

~~59After starting a task on the web:~~104There are several ways to pull a web session into your terminal:

105

106* **Using `/teleport`**: From within Claude Code, run `/teleport` (or `/tp`) to see an interactive picker of your web sessions. If you have uncommitted changes, you'll be prompted to stash them first.

107* **Using `--teleport`**: From the command line, run `claude --teleport` for an interactive session picker, or `claude --teleport <session-id>` to resume a specific session directly.

108* **From `/tasks`**: Run `/tasks` to see your background sessions, then press `t` to teleport into one

109* **From the web interface**: Click "Open in CLI" to copy a command you can paste into your terminal

60 110

~~611. Click the "Open in CLI" button~~111When you teleport a session, Claude verifies you're in the correct repository, fetches and checks out the branch from the remote session, and loads the full conversation history into your terminal.

~~622. Paste and run the command in your terminal in a checkout of the repo~~112

~~633. Any existing local changes will be stashed, and the remote session will be loaded~~113#### Requirements for teleporting

~~644. Continue working locally~~114

115Teleport checks these requirements before resuming a session. If any requirement isn't met, you'll see an error or be prompted to resolve the issue.

116

117| Requirement | Details |

118| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |

119| Clean git state | Your working directory must have no uncommitted changes. Teleport prompts you to stash changes if needed. |

120| Correct repository | You must run `--teleport` from a checkout of the same repository, not a fork. |

121| Branch available | The branch from the web session must have been pushed to the remote. Teleport automatically fetches and checks it out. |

122| Same account | You must be authenticated to the same Claude.ai account used in the web session. |

65 123

66## Cloud environment124## Cloud environment

67 125

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

93 151

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

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

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

155* **PHP**: Version 8.4.14

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

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

98* **Rust**: Rust toolchain with cargo158* **Rust**: Rust toolchain with cargo

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

100 160

161#### Databases

162

163The universal image includes the following databases:

164

165* **PostgreSQL**: Version 16

166* **Redis**: Version 7.0

167

101### Environment configuration168### Environment configuration

102 169

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

118 185

119**To update an existing environment:** Select the current environment, to the right of the environment name, and select the settings button. This will open a dialog where you can update the environment name, network access, and environment variables.186**To update an existing environment:** Select the current environment, to the right of the environment name, and select the settings button. This will open a dialog where you can update the environment name, network access, and environment variables.

120 187

188**To select your default environment from the terminal:** If you have multiple environments configured, run `/remote-env` to choose which one to use when starting web sessions from your terminal with `&` or `--remote`. With a single environment, this command shows your current configuration.

189

121<Note>190<Note>

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

123 192

129 198

130### Dependency management199### Dependency management

131 200

132Configure automatic dependency installation using [SessionStart hooks](/en/docs/claude-code/hooks#sessionstart). This can be configured in your repository's `.claude/settings.json` file:201Configure automatic dependency installation using [SessionStart hooks](/en/hooks#sessionstart). This can be configured in your repository's `.claude/settings.json` file:

133 202

134```json theme={null}203```json theme={null}

135{204{

178 247

179#### Persisting environment variables248#### Persisting environment variables

180 249

181SessionStart hooks can persist environment variables for subsequent bash commands by writing to the file specified in the `CLAUDE_ENV_FILE` environment variable. For details, see [SessionStart hooks](/en/docs/claude-code/hooks#sessionstart) in the hooks reference.250SessionStart hooks can persist environment variables for subsequent bash commands by writing to the file specified in the `CLAUDE_ENV_FILE` environment variable. For details, see [SessionStart hooks](/en/hooks#sessionstart) in the hooks reference.

182 251

183## Network access and security252## Network access and security

184 253

247* ghcr.io316* ghcr.io

248* mcr.microsoft.com317* mcr.microsoft.com

249* \*.data.mcr.microsoft.com318* \*.data.mcr.microsoft.com

319* public.ecr.aws

250 320

251#### Cloud Platforms321#### Cloud Platforms

252 322

267* dot.net337* dot.net

268* visualstudio.com338* visualstudio.com

269* dev.azure.com339* dev.azure.com

340* \*.amazonaws.com

341* \*.api.aws

270* oracle.com342* oracle.com

271* [www.oracle.com](http://www.oracle.com)343* [www.oracle.com](http://www.oracle.com)

272* java.com344* java.com

464 536

465## Best practices537## Best practices

466 538

4671. **Use Claude Code hooks**: Configure [sessionStart hooks](/en/docs/claude-code/hooks#sessionstart) to automate environment setup and dependency installation.5391. **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.5402. **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 541

470## Related resources542## Related resources

471 543

472* [Hooks configuration](/en/docs/claude-code/hooks)544* [Hooks configuration](/en/hooks)

473* [Settings reference](/en/docs/claude-code/settings)545* [Settings reference](/en/settings)

474* [Security](/en/docs/claude-code/security)546* [Security](/en/security)

475* [Data usage](/en/docs/claude-code/data-usage)547* [Data usage](/en/data-usage)

548

549

550---

551

552> 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 +97 −30

Details

5## CLI commands5## CLI commands

6 6

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

18 18

19## CLI flags19## CLI flags

20 20

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| `--agents` | Define custom [subagents](/en/docs/claude-code/sub-agents) dynamically via JSON (see below for format) | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |26| `--agent` | Specify an agent for the current session (overrides the `agent` setting) | `claude --agent my-custom-agent` |

27| `--allowedTools` | A list of tools that should be allowed without prompting the user for permission, in addition to [settings.json files](/en/docs/claude-code/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Read"` |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"}}'` |

28| `--disallowedTools` | A list of tools that should be disallowed without prompting the user for permission, in addition to [settings.json files](/en/docs/claude-code/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |28| `--allow-dangerously-skip-permissions` | Enable permission bypassing as an option without immediately activating it. Allows composing with `--permission-mode` (use with caution) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

29| `--print`, `-p` | Print response without interactive mode (see [SDK documentation](/en/docs/claude-code/sdk) for programmatic usage details) | `claude -p "query"` |29| `--allowedTools` | Tools that execute without prompting for permission. See [permission rule syntax](/en/settings#permission-rule-syntax) for pattern matching. To restrict which tools are available, use `--tools` instead | `"Bash(git log:*)" "Bash(git diff:*)" "Read"` |

31| `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |31| `--append-system-prompt-file` | Load additional system prompt text from a file and append to the default prompt (print mode only) | `claude -p --append-system-prompt-file ./extra-rules.txt "query"` |

33| `--chrome` | Enable [Chrome browser integration](/en/chrome) for web automation and testing | `claude --chrome` |

34| `--continue`, `-c` | Load the most recent conversation in the current directory | `claude --continue` |

35| `--dangerously-skip-permissions` | Skip all permission prompts (use with caution) | `claude --dangerously-skip-permissions` |

36| `--debug` | Enable debug mode with optional category filtering (for example, `"api,hooks"` or `"!statsig,!file"`) | `claude --debug "api,mcp"` |

37| `--disable-slash-commands` | Disable all skills and slash commands for this session | `claude --disable-slash-commands` |

38| `--disallowedTools` | Tools that are removed from the model's context and cannot be used | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |

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

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

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

42| `--init` | Run [Setup hooks](/en/hooks#setup) and start interactive mode | `claude --init` |

43| `--init-only` | Run [Setup hooks](/en/hooks#setup) and exit (no interactive session) | `claude --init-only` |

33| `--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"` |44| `--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"` |

35| `--max-turns` | Limit the number of agentic turns in non-interactive mode | `claude -p --max-turns 3 "query"` |46| `--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"` |

47| `--maintenance` | Run [Setup hooks](/en/hooks#setup) with maintenance trigger and exit | `claude --maintenance` |

48| `--max-budget-usd` | Maximum dollar amount to spend on API calls before stopping (print mode only) | `claude -p --max-budget-usd 5.00 "query"` |

49| `--max-turns` | Limit the number of agentic turns (print mode only). Exits with an error when the limit is reached. No limit by default | `claude -p --max-turns 3 "query"` |

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

36| `--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` |51| `--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` |

53| `--no-session-persistence` | Disable session persistence so sessions are not saved to disk and cannot be resumed (print mode only) | `claude -p --no-session-persistence "query"` |

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

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

60| `--resume`, `-r` | Resume a specific session by ID or name, or show an interactive picker to choose a session | `claude --resume auth-refactor` |

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

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

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

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

65| `--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"` |

66| `--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"` |

67| `--teleport` | Resume a [web session](/en/claude-code-on-the-web) in your local terminal | `claude --teleport` |

68| `--tools` | Restrict which built-in tools Claude can use (works in both interactive and print modes). Use `""` to disable all, `"default"` for all, or tool names like `"Bash,Edit,Read"` | `claude --tools "Bash,Edit,Read"` |

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

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

42 71

43<Tip>72<Tip>

44 The `--output-format json` flag is particularly useful for scripting and73 The `--output-format json` flag is particularly useful for scripting and

50The `--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:79The `--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:

51 80

~~53| :------------ | :------- | :-------------------------------------------------------------------------------------------------------------- |~~82| :------------ | :------- | :--------------------------------------------------------------------------------------------------------------------- |

54| `description` | Yes | Natural language description of when the subagent should be invoked |83| `description` | Yes | Natural language description of when the subagent should be invoked |

55| `prompt` | Yes | The system prompt that guides the subagent's behavior |84| `prompt` | Yes | The system prompt that guides the subagent's behavior |

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

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

58 87

59Example:88Example:

73}'102}'

74```103```

75 104

~~76For more details on creating and using subagents, see the [subagents documentation](/en/docs/claude-code/sub-agents).~~105For more details on creating and using subagents, see the [subagents documentation](/en/sub-agents).

106

107### System prompt flags

108

109Claude Code provides four flags for customizing the system prompt, each serving a different purpose:

110

112| :---------------------------- | :------------------------------------------ | :------------------ | :------------------------------------------------------------------- |

77 117

~~78For detailed information about print mode (`-p`) including output formats,~~118**When to use each:**

~~79streaming, verbose logging, and programmatic usage, see the~~119

~~80[SDK documentation](/en/docs/claude-code/sdk).~~120* **`--system-prompt`**: Use when you need complete control over Claude's system prompt. This removes all default Claude Code instructions, giving you a blank slate.

121 ```bash theme={null}

122 claude --system-prompt "You are a Python expert who only writes type-annotated code"

123 ```

124

125* **`--system-prompt-file`**: Use when you want to load a custom prompt from a file, useful for team consistency or version-controlled prompt templates.

126 ```bash theme={null}

127 claude -p --system-prompt-file ./prompts/code-review.txt "Review this PR"

128 ```

129

130* **`--append-system-prompt`**: Use when you want to add specific instructions while keeping Claude Code's default capabilities intact. This is the safest option for most use cases.

131 ```bash theme={null}

132 claude --append-system-prompt "Always use TypeScript and include JSDoc comments"

133 ```

134

135* **`--append-system-prompt-file`**: Use when you want to append instructions from a file while keeping Claude Code's defaults. Useful for version-controlled additions.

136 ```bash theme={null}

137 claude -p --append-system-prompt-file ./prompts/style-rules.txt "Review this PR"

138 ```

139

140`--system-prompt` and `--system-prompt-file` are mutually exclusive. The append flags can be used together with either replacement flag.

141

142For most use cases, `--append-system-prompt` or `--append-system-prompt-file` is recommended as they preserve Claude Code's built-in capabilities while adding your custom requirements. Use `--system-prompt` or `--system-prompt-file` only when you need complete control over the system prompt.

81 143

82## See also144## See also

83 145

~~84* [Interactive mode](/en/docs/claude-code/interactive-mode) - Shortcuts, input modes, and interactive features~~146* [Chrome extension](/en/chrome) - Browser automation and web testing

~~85* [Slash commands](/en/docs/claude-code/slash-commands) - Interactive session commands~~147* [Interactive mode](/en/interactive-mode) - Shortcuts, input modes, and interactive features

~~86* [Quickstart guide](/en/docs/claude-code/quickstart) - Getting started with Claude Code~~148* [Quickstart guide](/en/quickstart) - Getting started with Claude Code

~~87* [Common workflows](/en/docs/claude-code/common-workflows) - Advanced workflows and patterns~~149* [Common workflows](/en/common-workflows) - Advanced workflows and patterns

~~88* [Settings](/en/docs/claude-code/settings) - Configuration options~~150* [Settings](/en/settings) - Configuration options

~~89* [SDK documentation](/en/docs/claude-code/sdk) - Programmatic usage and integrations~~151* [SDK documentation](https://docs.claude.com/en/docs/agent-sdk) - Programmatic usage and integrations

152

153

154---

155

156> 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 +214 −211

Details

1# Common workflows1# Common workflows

2 2

~~3> Learn about common workflows with Claude Code.~~3> Step-by-step guides for exploring codebases, fixing bugs, refactoring, testing, and other everyday tasks with Claude Code.

4 4

~~5Each task in this document includes clear instructions, example commands, and best practices to help you get the most from Claude Code.~~5This page covers practical workflows for everyday development: exploring unfamiliar code, debugging, refactoring, writing tests, creating PRs, and managing sessions. Each section includes example prompts you can adapt to your own projects.

6 6

7## Understand new codebases7## Understand new codebases

8 8

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

214 * Create project-specific subagents in `.claude/agents/` for team sharing214 * Create project-specific subagents in `.claude/agents/` for team sharing

215 * Use descriptive `description` fields to enable automatic delegation215 * Use descriptive `description` fields to enable automatic delegation

216 * Limit tool access to what each subagent actually needs216 * Limit tool access to what each subagent actually needs

217 * Check the [subagents documentation](/en/docs/claude-code/sub-agents) for detailed examples217 * Check the [subagents documentation](/en/sub-agents) for detailed examples

218</Tip>

219

220***

221

222## Create custom skills and commands

223

224Skills extend Claude's capabilities with reusable prompts and workflows. Create a skill once, then invoke it with `/skill-name` or let Claude use it automatically when relevant.

225

226For the full reference, see the [Skills documentation](/en/skills).

227

228### Create a skill Claude can use automatically

229

230This skill teaches Claude how to analyze code performance. Because it has a description and no restrictions, Claude can load it automatically when you ask about optimization.

231

232<Steps>

233 <Step title="Create a skills directory in your project">

234 ```bash theme={null}

235 mkdir -p .claude/skills/optimize

236 ```

237 </Step>

238

239 <Step title="Create a SKILL.md file with frontmatter and instructions">

240 Create `.claude/skills/optimize/SKILL.md` with the following content:

241

242 ```markdown .claude/skills/optimize/SKILL.md theme={null}

243 ---

244 name: optimize

245 description: Analyze code performance and suggest optimizations

246 ---

247

248 Analyze the performance of this code and suggest three specific optimizations.

249 ```

250 </Step>

251

252 <Step title="Use your custom skill">

253 Claude uses it automatically when relevant, or you can invoke it directly:

254

255 ```

256 /optimize src/utils/parser.js

257 ```

258 </Step>

259</Steps>

260

261### Create a skill for manual invocation

262

263This skill runs tests and shows coverage. The `disable-model-invocation: true` field means Claude can't invoke it automatically—only you can trigger it with `/test-coverage`.

264

265<Steps>

266 <Step title="Create a skill file">

267 Create `.claude/commands/test-coverage.md` with the following content:

268

269 ```markdown .claude/commands/test-coverage.md theme={null}

270 ---

271 description: Run tests with coverage report

272 disable-model-invocation: true

273 ---

274

275 Run the test suite with coverage enabled and summarize the results.

276 ```

277 </Step>

278

279 <Step title="Use your skill">

280 ```

281 /test-coverage

282 ```

283 </Step>

284</Steps>

285

286<Tip>

287 Skills can be scoped to a project, personal directory, or organization. They can also accept arguments with `$ARGUMENTS`. See the [Skills documentation](/en/skills) for details.

218</Tip>288</Tip>

219 289

220***290***

221 291

222## Use Plan Mode for safe code analysis292## Use Plan Mode for safe code analysis

223 293

224Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely.294Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely. In Plan Mode, Claude uses [`AskUserQuestion`](/en/settings#tools-available-to-claude) to gather requirements and clarify your goals before proposing a plan.

225 295

226### When to use Plan Mode296### When to use Plan Mode

227 297

235 305

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

237 307

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`.308If 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 309

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

241 311

247 317

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

249 319

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

251 321

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

253claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"323claude --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.333> I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.

264```334```

265 335

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

267 337

268```338```

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

281}351}

282```352```

283 353

284See [settings documentation](/en/docs/claude-code/settings#available-settings) for more configuration options.354See [settings documentation](/en/settings#available-settings) for more configuration options.

355

356## Let Claude interview you

357

358For large features, start with a minimal spec and let Claude interview you to fill in the details:

359

360```

361> Interview me about this feature before you start: user notification system

362```

363

364```

365> Help me think through the requirements for authentication by asking questions

366```

367

368```

369> Ask me clarifying questions to build out this spec: payment processing

370```

371

372Claude uses the [`AskUserQuestion`](/en/settings#tools-available-to-claude) tool to ask you multiple-choice questions for gathering requirements, clarifying ambiguity, and understanding your preferences before writing any code. This collaborative approach produces better specs than trying to anticipate every requirement upfront.

373

374<Tip>

375 When you select "Type something" to provide a custom answer, press **Ctrl+G** to open your default text editor for longer responses.

376</Tip>

377

378This behavior is most active in Plan Mode. To encourage it in other modes, add guidance to your `CLAUDE.md` file:

379

380```markdown theme={null}

381Always ask clarifying questions when there are multiple valid approaches to a task.

382```

383

384<Note>

385 If you're building applications with the Agent SDK and want to surface clarifying questions to your users programmatically, see [Handle approvals and user input](https://platform.claude.com/docs/en/agent-sdk/user-input#handle-clarifying-questions).

386</Note>

285 387

286***388***

287 389

315 </Step>417 </Step>

316</Steps>418</Steps>

317 419

318<Tip>420Claude 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 421

321 * Ask for tests that cover edge cases and error conditions422For 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 423

326***424***

327 425

336 ```434 ```

337 </Step>435 </Step>

338 436

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

340 ```438 ```

341 > create a pr 439 > create a pr

342 ```440 ```

458 * Include screenshots of errors, UI designs, or diagrams for better context556 * Include screenshots of errors, UI designs, or diagrams for better context

459 * You can work with multiple images in a conversation557 * You can work with multiple images in a conversation

460 * Image analysis works with diagrams, screenshots, mockups, and more558 * Image analysis works with diagrams, screenshots, mockups, and more

559 * When Claude references images (for example, `[Image #1]`), `Cmd+Click` (Mac) or `Ctrl+Click` (Windows/Linux) the link to open the image in your default viewer

461</Tip>560</Tip>

462 561

463***562***

488 > Show me the data from @github:repos/owner/repo/issues587 > Show me the data from @github:repos/owner/repo/issues

489 ```588 ```

490 589

491 This fetches data from connected MCP servers using the format @server:resource. See [MCP resources](/en/docs/claude-code/mcp#use-mcp-resources) for details.590 This fetches data from connected MCP servers using the format @server:resource. See [MCP resources](/en/mcp#use-mcp-resources) for details.

492 </Step>591 </Step>

493</Steps>592</Steps>

494 593

496 Tips:595 Tips:

497 596

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

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

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

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

502</Tip>601</Tip>

503 602

504***603***

505 604

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

606

607[Extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) is enabled by default, reserving a portion of the output token budget (up to 31,999 tokens) 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 608

508Suppose you're working on complex architectural decisions, challenging bugs, or planning multi-step implementations that require deep reasoning.609Extended 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 610

510<Note>611<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/docs/claude-code/settings#environment-variables) in your settings.612 Phrases like "think", "think hard", "ultrathink", and "think more" are interpreted as regular prompt instructions and don't allocate thinking tokens.

512</Note>613</Note>

513 614

514<Steps>615### Configure thinking mode

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 616

520 Claude will gather relevant information from your codebase and617Thinking is enabled by default, but you can adjust or disable it.

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

522 </Step>

523 618

524 <Step title="Refine the thinking with follow-up prompts">619| Scope | How to configure | Details |

525 ```620| ---------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |

526 > think about potential security vulnerabilities in this approach 621| **Toggle shortcut** | Press `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle thinking on/off for the current session. May require [terminal configuration](/en/terminal-config) to enable Option key shortcuts |

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

623| **Limit token budget** | Set [`MAX_THINKING_TOKENS`](/en/settings#environment-variables) environment variable | Limit the thinking budget to a specific number of tokens. Example: `export MAX_THINKING_TOKENS=10000` |

528 624

529 ```625To view Claude's thinking process, press `Ctrl+O` to toggle verbose mode and see the internal reasoning displayed as gray italic text.

530 > think hard about edge cases we should handle

531 ```

532 </Step>

533</Steps>

534 626

535<Tip>627### How extended thinking token budgets work

536 Tips to get the most value out of extended thinking:

537 628

538 [Extended thinking](/en/docs/build-with-claude/extended-thinking) is most valuable for complex tasks such as:629Extended thinking uses a **token budget** that controls how much internal reasoning Claude can perform before responding.

539 630

540 * Planning complex architectural changes631A larger thinking token budget provides:

541 * Debugging intricate issues

542 * Creating implementation plans for new features

543 * Understanding complex codebases

544 * Evaluating tradeoffs between different approaches

545 632

546 Use `Tab` to toggle Thinking on and off during a session.633* More space to explore multiple solution approaches step-by-step

634* Room to analyze edge cases and evaluate tradeoffs thoroughly

635* Ability to revise reasoning and self-correct mistakes

547 636

548 The way you prompt for thinking results in varying levels of thinking depth:637Token budgets for thinking mode:

549 638

550 * "think" triggers basic extended thinking639* When thinking is **enabled**, Claude can use up to **31,999 tokens** from your output budget for internal reasoning

551 * intensifying phrases such as "keep hard", "think more", "think a lot", or "think longer" triggers deeper thinking640* When thinking is **disabled** (via toggle or `/config`), Claude uses **0 tokens** for thinking

552 641

553 For more extended thinking prompting tips, see [Extended thinking tips](/en/docs/build-with-claude/prompt-engineering/extended-thinking-tips).642**Limit the thinking budget:**

554</Tip>

555 643

556<Note>644* Use the [`MAX_THINKING_TOKENS` environment variable](/en/settings#environment-variables) to cap the thinking budget

557 Claude will display its thinking process as italic gray text above the645* When set, this value limits the maximum tokens Claude can use for thinking

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

559</Note>647

648<Warning>

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

650</Warning>

560 651

561***652***

562 653

563## Resume previous conversations654## Resume previous conversations

564 655

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

657

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

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

660

661From inside an active session, use `/resume` to switch to a different conversation.

662

663Sessions are stored per project directory. The `/resume` picker shows sessions from the same git repository, including worktrees.

566 664

567Claude Code provides two options for resuming previous conversations:665### Name your sessions

568 666

569* `--continue` to automatically continue the most recent conversation667Give sessions descriptive names to find them later. This is a best practice when working on multiple tasks or features.

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

571 668

572<Steps>669<Steps>

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

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

575 claude --continue672

673 ```

674 > /rename auth-refactor

576 ```675 ```

577 676

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

579 </Step>678 </Step>

580 679

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

681 From the command line:

682

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

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

584 ```685 ```

585 686

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

587 </Step>

588 688

589 <Step title="Show conversation picker">

590 ```bash theme={null}

591 claude --resume

592 ```689 ```

690 > /resume auth-refactor

691 ```

692 </Step>

693</Steps>

593 694

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

595 696

596 * Session summary (or initial prompt)697The `/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 698

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

600 </Step>700

601</Steps>701| Shortcut | Action |

702| :-------- | :------------------------------------------------ |

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

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

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

706| `P` | Preview the session content |

707| `R` | Rename the highlighted session |

708| `/` | Search to filter sessions |

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

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

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

712

713**Session organization:**

714

715The picker displays sessions with helpful metadata:

716

717* Session name or initial prompt

718* Time elapsed since last activity

719* Message count

720* Git branch (if applicable)

721

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

602 723

603<Tip>724<Tip>

604 Tips:725 Tips:

605 726

606 * Conversation history is stored locally on your machine727 * **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 conversation728 * Use `--continue` for quick access to your most recent conversation in the current directory

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

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

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

732 * 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 original733 * The resumed conversation starts with the same model and configuration as the original

611 734

612 How it works:735 How it works:

615 2. **Message Deserialization**: When resuming, the entire message history is restored to maintain context738 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 preserved739 3. **Tool State**: Tool usage and results from the previous conversation are preserved

617 4. **Context Restoration**: The conversation resumes with all previous context intact740 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>741</Tip>

635 742

636***743***

789 896

790***897***

791 898

792## Create custom slash commands

~~793~~

794Claude Code supports custom slash commands that you can create to quickly execute specific prompts or tasks.

~~795~~

796For more details, see the [Slash commands](/en/docs/claude-code/slash-commands) reference page.

~~797~~

798### Create project-specific commands

~~799~~

800Suppose you want to create reusable slash commands for your project that all team members can use.

~~801~~

802<Steps>

803 <Step title="Create a commands directory in your project">

804 ```bash theme={null}

805 mkdir -p .claude/commands

806 ```

807 </Step>

~~808~~

809 <Step title="Create a Markdown file for each command">

810 ```bash theme={null}

811 echo "Analyze the performance of this code and suggest three specific optimizations:" > .claude/commands/optimize.md

812 ```

813 </Step>

~~814~~

815 <Step title="Use your custom command in Claude Code">

816 ```

817 > /optimize

818 ```

819 </Step>

820</Steps>

~~821~~

822<Tip>

823 Tips:

~~824~~

825 * Command names are derived from the filename (e.g., `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)

827 * 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 invoked

829</Tip>

~~830~~

831### Add command arguments with \$ARGUMENTS

~~832~~

833Suppose you want to create flexible slash commands that can accept additional input from users.

~~834~~

835<Steps>

836 <Step title="Create a command file with the $ARGUMENTS placeholder">

837 ```bash theme={null}

838 echo 'Find and fix issue #$ARGUMENTS. Follow these steps: 1.

839 Understand the issue described in the ticket 2. Locate the relevant code in

840 our codebase 3. Implement a solution that addresses the root cause 4. Add

841 appropriate tests 5. Prepare a concise PR description' >

842 .claude/commands/fix-issue.md

843 ```

844 </Step>

~~845~~

846 <Step title="Use the command with an issue number">

847 In your Claude session, use the command with arguments.

~~848~~

849 ```

850 > /fix-issue 123

851 ```

~~852~~

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

854 </Step>

855</Steps>

~~856~~

857<Tip>

858 Tips:

~~859~~

860 * The \$ARGUMENTS placeholder is replaced with any text that follows the command

861 * You can position \$ARGUMENTS anywhere in your command template

862 * Other useful applications: generating test cases for specific functions, creating documentation for components, reviewing code in particular files, or translating content to specified languages

863</Tip>

~~864~~

865### Create personal slash commands

~~866~~

867Suppose you want to create personal slash commands that work across all your projects.

~~868~~

869<Steps>

870 <Step title="Create a commands directory in your home folder">

871 ```bash theme={null}

872 mkdir -p ~/.claude/commands

873 ```

874 </Step>

~~875~~

876 <Step title="Create a Markdown file for each command">

877 ```bash theme={null}

878 echo "Review this code for security vulnerabilities, focusing on:" >

879 ~/.claude/commands/security-review.md

880 ```

881 </Step>

~~882~~

883 <Step title="Use your personal custom command">

884 ```

885 > /security-review

886 ```

887 </Step>

888</Steps>

~~889~~

890<Tip>

891 Tips:

~~892~~

893 * Personal commands show "(user)" in their description when listed with `/help`

894 * Personal commands are only available to you and not shared with your team

895 * Personal commands work across all your projects

896 * You can use these for consistent workflows across different codebases

897</Tip>

~~898~~

899***

~~900~~

901## Ask Claude about its capabilities899## Ask Claude about its capabilities

902 900

903Claude has built-in access to its documentation and can answer questions about its own features and limitations.901Claude has built-in access to its documentation and can answer questions about its own features and limitations.

913```911```

914 912

915```913```

916> what slash commands are available?914> what skills are available?

917```915```

918 916

919```917```

947<Card title="Claude Code reference implementation" icon="code" href="https://github.com/anthropics/claude-code/tree/main/.devcontainer">945<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.946 Clone our development container reference implementation.

949</Card>947</Card>

948

949

950---

951

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

costs.md +108 −56

Details

1# Manage costs effectively1# Manage costs effectively

2 2

~~3> Learn how to track and optimize token usage and costs when using Claude Code.~~3> Track token usage, set team spend limits, and reduce Claude Code costs with context management, model selection, extended thinking settings, and preprocessing hooks.

4 4

~~5Claude Code consumes tokens for each interaction. The average cost is \$6 per developer per day, with daily costs remaining below \$12 for 90% of users.~~5Claude Code consumes tokens for each interaction. Costs vary based on codebase size, query complexity, and conversation length. The average cost is \$6 per developer per day, with daily costs remaining below \$12 for 90% of users.

6 6

7For team usage, Claude Code charges by API token consumption. On average, Claude Code costs \~\$100-200/developer per month with Sonnet 4.5 though there is large variance depending on how many instances users are running and whether they're using it in automation.7For team usage, Claude Code charges by API token consumption. On average, Claude Code costs \~\$100-200/developer per month with Sonnet 4.5 though there is large variance depending on how many instances users are running and whether they're using it in automation.

8 8

9This page covers how to [track your costs](#track-your-costs), [manage costs for teams](#managing-costs-for-teams), and [reduce token usage](#reduce-token-usage).

9## Track your costs11## Track your costs

10 12

11### Using the `/cost` command13### Using the `/cost` command

12 14

13<Note>15<Note>

~~14 The `/cost` command is not intended for Claude Max and Pro subscribers.~~16 The `/cost` command shows API token usage and is intended for API users. Claude Max and Pro subscribers have usage included in their subscription, so `/cost` data isn't relevant for billing purposes. Subscribers can use `/stats` to view usage patterns.

15</Note>17</Note>

16 18

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

23Total code changes: 0 lines added, 0 lines removed25Total code changes: 0 lines added, 0 lines removed

24```26```

25 27

~~26### Additional tracking options~~28## Managing costs for teams

27 29

28Check [historical usage](https://support.claude.com/en/articles/9534590-cost-and-usage-reporting-in-console) in the Claude Console (requires Admin or Billing role) and set [workspace spend limits](https://support.claude.com/en/articles/9796807-creating-and-managing-workspaces) for the Claude Code workspace (requires Admin role).30When using Claude API, you can [set workspace spend limits](https://platform.claude.com/docs/en/build-with-claude/workspaces#workspace-limits) on the total Claude Code workspace spend. Admins can [view cost and usage reporting](https://platform.claude.com/docs/en/build-with-claude/workspaces#usage-and-cost-tracking) in the Console.

29 31

30<Note>32<Note>

31 When you first authenticate Claude Code with your Claude Console account, a workspace called "Claude Code" is automatically created for you. This workspace provides centralized cost tracking and management for all Claude Code usage in your organization. You cannot create API keys for this workspace - it is exclusively for Claude Code authentication and usage.33 When you first authenticate Claude Code with your Claude Console account, a workspace called "Claude Code" is automatically created for you. This workspace provides centralized cost tracking and management for all Claude Code usage in your organization. You cannot create API keys for this workspace; it is exclusively for Claude Code authentication and usage.

32</Note>34</Note>

33 35

~~34## Managing costs for teams~~36On Bedrock, Vertex, and Foundry, Claude Code does not send metrics from your cloud. To get cost metrics, several large enterprises reported using [LiteLLM](/en/llm-gateway#litellm-configuration), 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.

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

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/docs/claude-code/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.

39 37

40### Rate limit recommendations38### Rate limit recommendations

41 39

60 58

61## Reduce token usage59## Reduce token usage

62 60

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

64 62

~~65 * Claude uses auto-compact by default when context exceeds 95% capacity~~63The following strategies help you keep context small and reduce per-message costs.

~~66 * Toggle auto-compact: Run `/config` and navigate to "Auto-compact enabled"~~

~~67 * Use `/compact` manually when context gets large~~

~~68 * Add custom instructions: `/compact Focus on code samples and API usage`~~

~~69 * Customize compaction by adding to CLAUDE.md:~~

70 64

~~71 ```markdown theme={null}~~65### Manage context proactively

~~72 # Summary instructions~~

73 66

~~74 When you are using compact, please focus on test output and code changes~~67Use `/cost` to check your current token usage, or [configure your status line](/en/statusline#context-window-usage) to display it continuously.

~~75 ```~~

76 68

~~77* **Write specific queries:** Avoid vague requests that trigger unnecessary scanning~~69* **Clear between tasks**: Use `/clear` to start fresh when switching to unrelated work. Stale context wastes tokens on every subsequent message. Use `/rename` before clearing so you can easily find the session later, then `/resume` to return to it.

70* **Add custom compaction instructions**: `/compact Focus on code samples and API usage` tells Claude what to preserve during summarization.

78 71

~~79* **Break down complex tasks:** Split large tasks into focused interactions~~72You can also customize compaction behavior in your CLAUDE.md:

80 73

~~81* **Clear history between tasks:** Use `/clear` to reset context~~74```markdown theme={null}

75# Compact instructions

82 76

~~83Costs can vary significantly based on:~~77When you are using compact, please focus on test output and code changes

78```

84 79

~~85* Size of codebase being analyzed~~80### Choose the right model

~~86* Complexity of queries~~

~~87* Number of files being searched or modified~~

~~88* Length of conversation history~~

~~89* Frequency of compacting conversations~~

90 81

~~91## Background token usage~~82Sonnet handles most coding tasks well and costs less than Opus. Reserve Opus for complex architectural decisions or multi-step reasoning. Use `/model` to switch models mid-session, or set a default in `/config`. For simple subagent tasks, specify `model: haiku` in your [subagent configuration](/en/sub-agents#choose-a-model).

92 83

~~93Claude Code uses tokens for some background functionality even when idle:~~84### Reduce MCP server overhead

94 85

~~95* **Conversation summarization**: Background jobs that summarize previous conversations for the `claude --resume` feature~~86Each MCP server adds tool definitions to your context, even when idle. Run `/context` to see what's consuming space.

~~96* **Command processing**: Some commands like `/cost` may generate requests to check status~~

97 87

~~98These background processes consume a small amount of tokens (typically under \$0.04 per session) even without active interaction.~~88* **Prefer CLI tools when available**: Tools like `gh`, `aws`, `gcloud`, and `sentry-cli` are more context-efficient than MCP servers because they don't add persistent tool definitions. Claude can run CLI commands directly without the overhead.

89* **Disable unused servers**: Run `/mcp` to see configured servers and disable any you're not actively using.

90* **Tool search is automatic**: When MCP tool descriptions exceed 10% of your context window, Claude Code automatically defers them and loads tools on-demand via [tool search](/en/mcp#scale-with-mcp-tool-search). Since deferred tools only enter context when actually used, a lower threshold means fewer idle tool definitions consuming space. Set a lower threshold with `ENABLE_TOOL_SEARCH=auto:<N>` (for example, `auto:5` triggers when tools exceed 5% of your context window).

99 91

100## Tracking version changes and updates92### Offload processing to hooks and skills

101 93

102### Current version information94Custom [hooks](/en/hooks) can preprocess data before Claude sees it. Instead of Claude reading a 10,000-line log file to find errors, a hook can grep for `ERROR` and return only matching lines, reducing context from tens of thousands of tokens to hundreds.

103 95

104To check your current Claude Code version and installation details:96A [skill](/en/skills) can give Claude domain knowledge so it doesn't have to explore. For example, a "codebase-overview" skill could describe your project's architecture, key directories, and naming conventions. When Claude invokes the skill, it gets this context immediately instead of spending tokens reading multiple files to understand the structure.

105 97

106```bash theme={null}98For example, this PreToolUse hook filters test output to show only failures:

107claude doctor

108```

109 99

110This command shows your version, installation type, and system information.100<Tabs>

101 <Tab title="settings.json">

102 Add this to your [settings.json](/en/settings#settings-files) to run the hook before every Bash command:

111 103

112### Understanding changes in Claude Code behavior104 ```json theme={null}

105 {

106 "hooks": {

107 "PreToolUse": [

108 {

109 "matcher": "Bash",

110 "hooks": [

111 {

112 "type": "command",

113 "command": "~/.claude/hooks/filter-test-output.sh"

114 }

115 ]

116 }

117 ]

118 }

119 }

120 ```

121 </Tab>

122

123 <Tab title="filter-test-output.sh">

124 The hook calls this script, which checks if the command is a test runner and modifies it to show only failures:

125

126 ```bash theme={null}

127 #!/bin/bash

128 input=$(cat)

129 cmd=$(echo "$input" | jq -r '.tool_input.command')

130

131 # If running tests, filter to show only failures

132 if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then

133 filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"

134 echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"updatedInput\":{\"command\":\"$filtered_cmd\"}}}"

135 else

136 echo "{}"

137 fi

138 ```

139 </Tab>

140</Tabs>

113 141

114Claude Code regularly receives updates that may change how features work, including cost reporting:142### Move instructions from CLAUDE.md to skills

115 143

116* **Version tracking**: Use `claude doctor` to see your current version144Your [CLAUDE.md](/en/memory) file is loaded into context at session start. If it contains detailed instructions for specific workflows (like PR reviews or database migrations), those tokens are present even when you're doing unrelated work. [Skills](/en/skills) load on-demand only when invoked, so moving specialized instructions into skills keeps your base context smaller. Aim to keep CLAUDE.md under \~500 lines by including only essentials.

117* **Behavior changes**: Features like `/cost` may display information differently across versions

118* **Documentation access**: Claude always has access to the latest documentation, which can help explain current feature behavior

119 145

120### When cost reporting changes146### Adjust extended thinking

121 147

122If you notice changes in how costs are displayed (such as the `/cost` command showing different information):148Extended thinking is enabled by default with a budget of 31,999 tokens because it significantly improves performance on complex planning and reasoning tasks. However, thinking tokens are billed as output tokens, so for simpler tasks where deep reasoning isn't needed, you can reduce costs by disabling it in `/config` or lowering the budget (for example, `MAX_THINKING_TOKENS=8000`).

123 149

1241. **Verify your version**: Run `claude doctor` to confirm your current version150### Delegate verbose operations to subagents

1252. **Consult documentation**: Ask Claude directly about current feature behavior, as it has access to up-to-date documentation

1263. **Contact support**: For specific billing questions, contact Anthropic support through your Console account

127 151

128<Note>152Running tests, fetching documentation, or processing log files can consume significant context. Delegate these to [subagents](/en/sub-agents#isolate-high-volume-operations) so the verbose output stays in the subagent's context while only a summary returns to your main conversation.

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

130 establish usage patterns before wider rollout.154### Write specific prompts

131</Note>155

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

157

158### Work efficiently on complex tasks

159

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

161

162* **Use plan mode for complex tasks**: Press Shift+Tab to enter [plan mode](/en/common-workflows#use-plan-mode-for-safe-code-analysis) before implementation. Claude explores the codebase and proposes an approach for your approval, preventing expensive re-work when the initial direction is wrong.

163* **Course-correct early**: If Claude starts heading the wrong direction, press Escape to stop immediately. Use `/rewind` or double-tap Escape to restore conversation and code to a previous checkpoint.

164* **Give verification targets**: Include test cases, paste screenshots, or define expected output in your prompt. When Claude can verify its own work, it catches issues before you need to request fixes.

165* **Test incrementally**: Write one file, test it, then continue. This catches issues early when they're cheap to fix.

166

167## Background token usage

168

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

170

171* **Conversation summarization**: Background jobs that summarize previous conversations for the `claude --resume` feature

172* **Command processing**: Some commands like `/cost` may generate requests to check status

173

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

175

176## Understanding changes in Claude Code behavior

177

178Claude Code regularly receives updates that may change how features work, including cost reporting. Run `claude --version` to check your current version. For specific billing questions, contact Anthropic support through your [Console account](https://platform.claude.com/login). For team deployments, start with a small pilot group to establish usage patterns before wider rollout.

179

180

181---

182

183> 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 +24 −26

Details

7### Data training policy7### Data training policy

8 8

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

~~10Starting August 28, 2025, we're giving you the choice to allow your data to be used to improve future Claude models.~~10We give you the choice to allow your data to be used to improve future Claude models. We will train new models using data from Free, Pro, and Max accounts when this setting is on (including when you use Claude Code from these accounts).

11 11

~~12We will train new models using data from Free, Pro, and Max accounts when this setting is on (including when you use Claude Code from these accounts).~~12**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)).

~~14* If you're a current user, you can select your preference now and your selection will immediately go into effect.~~

~~15 This setting will only apply to new or resumed chats and coding sessions on Claude. Previous chats with no additional activity will not be used for model training.~~

~~16* You have until October 8, 2025 to make your selection.~~

~~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.~~

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

21 13

22### Development Partner Program14### Development Partner Program

23 15

39 31

40* Users who allow data use for model improvement: 5-year retention period to support model development and safety improvements32* 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 period33* 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).~~34* Privacy settings can be changed at any time at [claude.ai/settings/data-privacy-controls](https://claude.ai/settings/data-privacy-controls).

43 35

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

45 37

51 43

52For full details, please review our [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) (for Team, Enterprise, and API users) or [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) (for Free, Pro, and Max users) and [Privacy Policy](https://www.anthropic.com/legal/privacy).44For full details, please review our [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) (for Team, Enterprise, and API users) or [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) (for Free, Pro, and Max users) and [Privacy Policy](https://www.anthropic.com/legal/privacy).

53 45

~~54## Data flow and dependencies~~46## Data access

48For all first party users, you can learn more about what data is logged for [local Claude Code](#local-claude-code-data-flow-and-dependencies) and [remote Claude Code](#cloud-execution-data-flow-and-dependencies). Note for remote Claude Code, Claude accesses the repository where you initiate your Claude Code session. Claude does not access repositories that you have connected but have not started a session in.

50## Local Claude Code: Data flow and dependencies

52The 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.

55 53

56<img src="https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=4b30069d702719e7bfb974eaaafab21c" 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/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?w=280&fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=067676caa12f89051cb193e6b3f7d0a0 280w, https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?w=560&fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=5506197deff927f54f2fb5a349f358a8 560w, https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?w=840&fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=bb4febe7974dde5b76b88744f89ab472 840w, https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?w=1100&fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=b51af3074f87b33ccc342aaad655dcbf 1100w, https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?w=1650&fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=8fd96f1dde615877d4e4bbe1874af12d 1650w, https://mintcdn.com/anthropic-claude-docs/LF5WV0SNF6oudpT5/images/claude-code-data-flow.png?w=2500&fit=max&auto=format&n=LF5WV0SNF6oudpT5&q=85&s=056deded541ec30e9b67a67d620f6aaf 2500w" />54<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 55

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.56Claude 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 57

60Claude Code is built on Anthropic's APIs. For details regarding our API's security controls, including our API logging procedures, please refer to compliance artifacts offered in the [Anthropic Trust Center](https://trust.anthropic.com).58Claude Code is built on Anthropic's APIs. For details regarding our API's security controls, including our API logging procedures, please refer to compliance artifacts offered in the [Anthropic Trust Center](https://trust.anthropic.com).

61 59

~~62### Cloud execution~~60### Cloud execution: Data flow and dependencies

63 61

~~64<Note>~~62When using [Claude Code on the web](/en/claude-code-on-the-web), sessions run in Anthropic-managed virtual machines instead of locally. In cloud environments:

~~65 The above data flow diagram and description applies to Claude Code CLI running locally on your machine. For cloud-based sessions using Claude Code on the web, see the section below.~~

~~66</Note>~~

67 63

~~68When using [Claude Code on the web](/en/docs/claude-code/claude-code-on-the-web), sessions run in Anthropic-managed virtual machines instead of locally. In cloud environments:~~64* **Code and data storage:** Your repository is cloned to an isolated VM. Code and session data are subject to the retention and usage policies for your account type (see Data retention section above)

65* **Credentials:** GitHub authentication is handled through a secure proxy; your GitHub credentials never enter the sandbox

66* **Network traffic:** All outbound traffic goes through a security proxy for audit logging and abuse prevention

67* **Session data:** Prompts, code changes, and outputs follow the same data policies as local Claude Code usage

69 68

~~70* **Code storage**: Your repository is cloned to an isolated VM and automatically deleted after session completion~~69For security details about cloud execution, see [Security](/en/security#cloud-execution-security).

~~71* **Credentials**: GitHub authentication is handled through a secure proxy; your GitHub credentials never enter the sandbox~~

~~72* **Network traffic**: All outbound traffic goes through a security proxy for audit logging and abuse prevention~~

~~73* **Data retention**: Code and session data are subject to the retention and usage policies for your account type~~

~~74* **Session data**: Prompts, code changes, and outputs follow the same data policies as local Claude Code usage~~

~~76For security details about cloud execution, see [Security](/en/docs/claude-code/security#cloud-execution-security).~~

77 70

78## Telemetry services71## Telemetry services

79 72

95 88

~~96All environment variables can be checked into `settings.json` ([read more](/en/docs/claude-code/settings)).~~89All environment variables can be checked into `settings.json` ([read more](/en/settings)).

92---

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

desktop.md +119 −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## Installation

13Download the Claude desktop app for your platform:

15<CardGroup cols={2}>

16 <Card title="macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">

17 Universal build for Intel and Apple Silicon

18 </Card>

20 <Card title="Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code&utm_medium=docs">

21 For x64 processors

22 </Card>

23</CardGroup>

25For Windows ARM64, [download here](https://claude.ai/api/desktop/win32/arm64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs).

27<Note>

28 Local sessions are not available on Windows ARM64.

29</Note>

31## Features

33Claude Code on desktop provides:

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

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

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

39## Using Git worktrees

41Claude 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.

43<Note>

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

45</Note>

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

49When 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.

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

53```

54.env

55.env.local

56.env.*

57**/.claude/settings.local.json

58```

60The 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.

62<Tip>

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

64</Tip>

66### Launch Claude Code on the web

68From the desktop app, you can kick off Claude Code sessions that run on Anthropic's secure cloud infrastructure.

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

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

74## Bundled Claude Code version

76Claude 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.

78<Note>

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

80</Note>

82## Environment configuration

84For 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.

86### Custom environment variables

88Select "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.

90<Note>

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

93 ```

94 API_KEY=your_api_key

95 DEBUG=true

97 # Multiline values - wrap in quotes

98 CERT="-----BEGIN CERT-----

99 MIIE...

100 -----END CERT-----"

101 ```

102</Note>

103

104## Enterprise configuration

105

106Organizations 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).

107

108## Related resources

109

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

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

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

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

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

115

116

117---

118

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

devcontainer.md +8 −3

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>

73## Related resources73## Related resources

74 74

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/docs/claude-code/security)~~76* [Claude Code security best practices](/en/security)

~~77* [Enterprise network configuration](/en/docs/claude-code/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 +378 −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 skills, 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

213### Add from remote URLs

214

215Add a remote `marketplace.json` file via URL:

216

217```shell theme={null}

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

219```

220

221<Note>

222 URL-based marketplaces have some limitations compared to Git-based marketplaces. If you encounter "path not found" errors when installing plugins, see [Troubleshooting](/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces).

223</Note>

224

225## Install plugins

226

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

228

229```shell theme={null}

230/plugin install plugin-name@marketplace-name

231```

232

233To 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:

234

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

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

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

238

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

240

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

242

243<Warning>

244 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.

245</Warning>

246

247## Manage installed plugins

248

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

250

251You can also manage plugins with direct commands.

252

253Disable a plugin without uninstalling:

254

255```shell theme={null}

256/plugin disable plugin-name@marketplace-name

257```

258

259Re-enable a disabled plugin:

260

261```shell theme={null}

262/plugin enable plugin-name@marketplace-name

263```

264

265Completely remove a plugin:

266

267```shell theme={null}

268/plugin uninstall plugin-name@marketplace-name

269```

270

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

272

273```shell theme={null}

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

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

276```

277

278## Manage marketplaces

279

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

281

282### Use the interactive interface

283

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

285

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

287* Add new marketplaces

288* Update marketplace listings to fetch the latest plugins

289* Remove marketplaces you no longer need

290

291### Use CLI commands

292

293You can also manage marketplaces with direct commands.

294

295List all configured marketplaces:

296

297```shell theme={null}

298/plugin marketplace list

299```

300

301Refresh plugin listings from a marketplace:

302

303```shell theme={null}

304/plugin marketplace update marketplace-name

305```

306

307Remove a marketplace:

308

309```shell theme={null}

310/plugin marketplace remove marketplace-name

311```

312

313<Warning>

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

315</Warning>

316

317### Configure auto-updates

318

319Claude 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.

320

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

322

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

3242. Select **Marketplaces**

3253. Choose a marketplace from the list

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

327

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

329

330To 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.

331

332To keep plugin auto-updates enabled while disabling Claude Code auto-updates, set `FORCE_AUTOUPDATE_PLUGINS=true` along with `DISABLE_AUTOUPDATER`:

333

334```shell theme={null}

335export DISABLE_AUTOUPDATER=true

336export FORCE_AUTOUPDATE_PLUGINS=true

337```

338

339This is useful when you want to manage Claude Code updates manually but still receive automatic plugin updates.

340

341## Configure team marketplaces

342

343Team 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.

344

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

346

347## Troubleshooting

348

349### /plugin command not recognized

350

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

352

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

3542. **Update Claude Code**:

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

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

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

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

359

360### Common issues

361

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

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

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

365* **Plugin skills not appearing**: Clear the cache with `rm -rf ~/.claude/plugins/cache`, restart Claude Code, and reinstall the plugin.

366

367For 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).

368

369## Next steps

370

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

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

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

374

375

376---

377

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

features-overview.md +239 −0 added

Details

1# Extend Claude Code

3> Understand when to use CLAUDE.md, Skills, subagents, hooks, MCP, and plugins.

5Claude Code combines a model that reasons about your code with [built-in tools](/en/how-claude-code-works#tools) for file operations, search, execution, and web access. The built-in tools cover most coding tasks. This guide covers the extension layer: features you add to customize what Claude knows, connect it to external services, and automate workflows.

7<Note>

8 For how the core agentic loop works, see [How Claude Code works](/en/how-claude-code-works).

9</Note>

11**New to Claude Code?** Start with [CLAUDE.md](/en/memory) for project conventions. Add other extensions as you need them.

13## Overview

15Extensions plug into different parts of the agentic loop:

17* **[CLAUDE.md](/en/memory)** adds persistent context Claude sees every session

18* **[Skills](/en/skills)** add reusable knowledge and invocable workflows

19* **[MCP](/en/mcp)** connects Claude to external services and tools

20* **[Subagents](/en/sub-agents)** run their own loops in isolated context, returning summaries

21* **[Hooks](/en/hooks)** run outside the loop entirely as deterministic scripts

22* **[Plugins](/en/plugins)** and **[marketplaces](/en/plugin-marketplaces)** package and distribute these features

24[Skills](/en/skills) are the most flexible extension. A skill is a markdown file containing knowledge, workflows, or instructions. You can invoke skills with a slash command like `/deploy`, or Claude can load them automatically when relevant. Skills can run in your current conversation or in an isolated context via subagents.

26## Match features to your goal

28Features range from always-on context that Claude sees every session, to on-demand capabilities you or Claude can invoke, to background automation that runs on specific events. The table below shows what's available and when each one makes sense.

31| ------------- | ---------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------- |

35| **MCP** | Connect to external services | External data or actions | Query your database, post to Slack, control a browser |

38**[Plugins](/en/plugins)** are the packaging layer. A plugin bundles skills, hooks, subagents, and MCP servers into a single installable unit. Plugin skills are namespaced (like `/my-plugin:review`) so multiple plugins can coexist. Use plugins when you want to reuse the same setup across multiple repositories or distribute to others via a **[marketplace](/en/plugin-marketplaces)**.

40### Compare similar features

42Some features can seem similar. Here's how to tell them apart.

44<Tabs>

45 <Tab title="Skill vs Subagent">

46 Skills and subagents solve different problems:

48 * **Skills** are reusable content you can load into any context

49 * **Subagents** are isolated workers that run separately from your main conversation

51 | Aspect | Skill | Subagent |

52 | --------------- | ---------------------------------------------- | ---------------------------------------------------------------- |

53 | **What it is** | Reusable instructions, knowledge, or workflows | Isolated worker with its own context |

54 | **Key benefit** | Share content across contexts | Context isolation. Work happens separately, only summary returns |

55 | **Best for** | Reference material, invocable workflows | Tasks that read many files, parallel work, specialized workers |

57 **Skills can be reference or action.** Reference skills provide knowledge Claude uses throughout your session (like your API style guide). Action skills tell Claude to do something specific (like `/deploy` that runs your deployment workflow).

59 **Use a subagent** when you need context isolation. The subagent might read dozens of files or run extensive searches, but your main conversation only receives a summary. Custom subagents can have their own instructions and can preload skills.

61 **They can combine.** A subagent can preload specific skills (`skills:` field). A skill can run in isolated context using `context: fork`. See [Skills](/en/skills) for details.

62 </Tab>

64 <Tab title="CLAUDE.md vs Skill">

65 Both store instructions, but they load differently and serve different purposes.

67 | Aspect | CLAUDE.md | Skill |

68 | ------------------------- | ---------------------------- | --------------------------------------- |

69 | **Loads** | Every session, automatically | On demand |

70 | **Can include files** | Yes, with `@path` imports | Yes, with `@path` imports |

71 | **Can trigger workflows** | No | Yes, with `/<name>` |

72 | **Best for** | "Always do X" rules | Reference material, invocable workflows |

74 **Put it in CLAUDE.md** if Claude should always know it: coding conventions, build commands, project structure, "never do X" rules.

76 **Put it in a skill** if it's reference material Claude needs sometimes (API docs, style guides) or a workflow you trigger with `/<name>` (deploy, review, release).

78 **Rule of thumb:** Keep CLAUDE.md under \~500 lines. If it's growing, move reference content to skills.

79 </Tab>

81 <Tab title="MCP vs Skill">

82 MCP connects Claude to external services. Skills extend what Claude knows, including how to use those services effectively.

84 | Aspect | MCP | Skill |

85 | -------------- | ---------------------------------------------------- | ------------------------------------------------------- |

86 | **What it is** | Protocol for connecting to external services | Knowledge, workflows, and reference material |

87 | **Provides** | Tools and data access | Knowledge, workflows, reference material |

88 | **Examples** | Slack integration, database queries, browser control | Code review checklist, deploy workflow, API style guide |

90 These solve different problems and work well together:

92 **MCP** gives Claude the ability to interact with external systems. Without MCP, Claude can't query your database or post to Slack.

94 **Skills** give Claude knowledge about how to use those tools effectively, plus workflows you can trigger with `/<name>`. A skill might include your team's database schema and query patterns, or a `/post-to-slack` workflow with your team's message formatting rules.

96 Example: An MCP server connects Claude to your database. A skill teaches Claude your data model, common query patterns, and which tables to use for different tasks.

97 </Tab>

98</Tabs>

100### Combine features

101

102Each extension solves a different problem: CLAUDE.md handles always-on context, skills handle on-demand knowledge and workflows, MCP handles external connections, subagents handle isolation, and hooks handle automation. Real setups combine them based on your workflow.

103

104For example, you might use CLAUDE.md for project conventions, a skill for your deployment workflow, MCP to connect to your database, and a hook to run linting after every edit. Each feature handles what it's best at.

105

106| Pattern | How it works | Example |

107| ---------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |

108| **Skill + MCP** | MCP provides the connection; a skill teaches Claude how to use it well | MCP connects to your database, a skill documents your schema and query patterns |

109| **Skill + Subagent** | A skill spawns subagents for parallel work | `/review` skill kicks off security, performance, and style subagents that work in isolated context |

110| **CLAUDE.md + Skills** | CLAUDE.md holds always-on rules; skills hold reference material loaded on demand | CLAUDE.md says "follow our API conventions," a skill contains the full API style guide |

111| **Hook + MCP** | A hook triggers external actions through MCP | Post-edit hook sends a Slack notification when Claude modifies critical files |

112

113## Understand context costs

114

115Every feature you add consumes some of Claude's context. Too much can fill up your context window, but it can also add noise that makes Claude less effective; skills may not trigger correctly, or Claude may lose track of your conventions. Understanding these trade-offs helps you build an effective setup.

116

117### Context cost by feature

118

119Each feature has a different loading strategy and context cost:

120

122| --------------- | ------------------------- | --------------------------------------------- | -------------------------------------------- |

128

129\*By default, skill descriptions load at session start so Claude can decide when to use them. Set `disable-model-invocation: true` in a skill's frontmatter to hide it from Claude entirely until you invoke it manually. This reduces context cost to zero for skills you only trigger yourself.

130

131### Understand how features load

132

133Each feature loads at different points in your session. The tabs below explain when each one loads and what goes into context.

134

135<img src="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=bd2e24b8e6a99b31ecfffb63f5b23bf5" alt="Context loading: CLAUDE.md and MCP load at session start and stay in every request. Skills load descriptions at start, full content on invocation. Subagents get isolated context. Hooks run externally." data-og-width="720" width="720" data-og-height="410" height="410" data-path="images/context-loading.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?w=280&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=aebaadd1f484f285dd9cb4e0ea6d49b9 280w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?w=560&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=030c9b46126d750de315612560082727 560w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?w=840&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=6c73f8b0389da4f3190843140c810fe9 840w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?w=1100&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=9844c55d08d2c386672447f2e8518669 1100w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?w=1650&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=21a9522d0e4bd10ced146aab850ede76 1650w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?w=2500&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=d318525915aee1a1a6a4215cfaa61fb9 2500w" />

136

137<Tabs>

138 <Tab title="CLAUDE.md">

139 **When:** Session start

140

141 **What loads:** Full content of all CLAUDE.md files (managed, user, and project levels).

142

143 **Inheritance:** Claude reads CLAUDE.md files from your working directory up to the root, and discovers nested ones in subdirectories as it accesses those files. See [How Claude looks up memories](/en/memory#how-claude-looks-up-memories) for details.

144

145 <Tip>Keep CLAUDE.md under \~500 lines. Move reference material to skills, which load on-demand.</Tip>

146 </Tab>

147

148 <Tab title="Skills">

149 Skills are extra capabilities in Claude's toolkit. They can be reference material (like an API style guide) or invocable workflows you trigger with `/<name>` (like `/deploy`). Some are built-in; you can also create your own. Claude uses skills when appropriate, or you can invoke one directly.

150

151 **When:** Depends on the skill's configuration. By default, descriptions load at session start and full content loads when used. For user-only skills (`disable-model-invocation: true`), nothing loads until you invoke them.

152

153 **What loads:** For model-invocable skills, Claude sees names and descriptions in every request. When you invoke a skill with `/<name>` or Claude loads it automatically, the full content loads into your conversation.

154

155 **How Claude chooses skills:** Claude matches your task against skill descriptions to decide which are relevant. If descriptions are vague or overlap, Claude may load the wrong skill or miss one that would help. To tell Claude to use a specific skill, invoke it with `/<name>`. Skills with `disable-model-invocation: true` are invisible to Claude until you invoke them.

156

157 **Context cost:** Low until used. User-only skills have zero cost until invoked.

158

159 **In subagents:** Skills work differently in subagents. Instead of on-demand loading, skills passed to a subagent are fully preloaded into its context at launch. Subagents don't inherit skills from the main session; you must specify them explicitly.

160

161 <Tip>Use `disable-model-invocation: true` for skills with side effects. This saves context and ensures only you trigger them.</Tip>

162 </Tab>

163

164 <Tab title="MCP servers">

165 **When:** Session start.

166

167 **What loads:** All tool definitions and JSON schemas from connected servers.

168

169 **Context cost:** [Tool search](/en/mcp#scale-with-mcp-tool-search) (enabled by default) loads MCP tools up to 10% of context and defers the rest until needed.

170

171 **Reliability note:** MCP connections can fail silently mid-session. If a server disconnects, its tools disappear without warning. Claude may try to use a tool that no longer exists. If you notice Claude failing to use an MCP tool it previously could access, check the connection with `/mcp`.

172

173 <Tip>Run `/mcp` to see token costs per server. Disconnect servers you're not actively using.</Tip>

174 </Tab>

175

176 <Tab title="Subagents">

177 **When:** On demand, when you or Claude spawns one for a task.

178

179 **What loads:** Fresh, isolated context containing:

180

181 * The system prompt (shared with parent for cache efficiency)

182 * Full content of skills listed in the agent's `skills:` field

183 * CLAUDE.md and git status (inherited from parent)

184 * Whatever context the lead agent passes in the prompt

185

186 **Context cost:** Isolated from main session. Subagents don't inherit your conversation history or invoked skills.

187

188 <Tip>Use subagents for work that doesn't need your full conversation context. Their isolation prevents bloating your main session.</Tip>

189 </Tab>

190

191 <Tab title="Hooks">

192 **When:** On trigger. Hooks can run before or after tool executions, at session start, before compaction, and at other lifecycle events. See [Hooks](/en/hooks) for the full list.

193

194 **What loads:** Nothing by default. Hooks run as external scripts.

195

196 **Context cost:** Zero, unless the hook returns output that gets added as messages to your conversation.

197

198 <Tip>Hooks are ideal for side effects (linting, logging) that don't need to affect Claude's context.</Tip>

199 </Tab>

200</Tabs>

201

202## Learn more

203

204Each feature has its own guide with setup instructions, examples, and configuration options.

205

206<CardGroup cols={2}>

207 <Card title="CLAUDE.md" icon="file-lines" href="/en/memory">

208 Store project context, conventions, and instructions

209 </Card>

210

211 <Card title="Skills" icon="brain" href="/en/skills">

212 Give Claude domain expertise and reusable workflows

213 </Card>

214

215 <Card title="Subagents" icon="users" href="/en/sub-agents">

216 Offload work to isolated context

217 </Card>

218

219 <Card title="MCP" icon="plug" href="/en/mcp">

220 Connect Claude to external services

221 </Card>

222

223 <Card title="Hooks" icon="bolt" href="/en/hooks">

224 Run scripts on Claude Code events

225 </Card>

226

227 <Card title="Plugins" icon="puzzle-piece" href="/en/plugins">

228 Bundle and share feature sets

229 </Card>

230

231 <Card title="Marketplaces" icon="store" href="/en/plugin-marketplaces">

232 Host and distribute plugin collections

233 </Card>

234</CardGroup>

235

236

237---

238

239> 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 +21 −13

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/docs/claude-code/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

153 # Responds to @claude mentions in comments156 # Responds to @claude mentions in comments

154```157```

155 158

156### Using slash commands159### Using skills

157 160

158```yaml theme={null}161```yaml theme={null}

159name: Code Review162name: Code Review

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

263Key features:266Key features:

264 267

265* **Unified prompt interface** - Use `prompt` for all instructions268* **Unified prompt interface** - Use `prompt` for all instructions

266* **Slash commands** - Pre-built prompts like `/review` or `/fix`269* **Commands** - Prebuilt prompts like `/review` or `/fix`

267* **CLI passthrough** - Any Claude Code CLI argument via `claude_args`270* **CLI passthrough** - Any Claude Code CLI argument via `claude_args`

268* **Flexible triggers** - Works with any GitHub event271* **Flexible triggers** - Works with any GitHub event

269 272

621The Claude Code Action v1 uses a simplified configuration:624The Claude Code Action v1 uses a simplified configuration:

622 625

624| ------------------- | ----------------------------------------------- | -------- |627| ------------------- | ------------------------------------------------------ | -------- |

625| `prompt` | Instructions for Claude (text or slash command) | No\* |628| `prompt` | Instructions for Claude (text or skill like `/review`) | No\* |

626| `claude_args` | CLI arguments passed to Claude Code | No |629| `claude_args` | CLI arguments passed to Claude Code | No |

627| `anthropic_api_key` | Claude API key | Yes\*\* |630| `anthropic_api_key` | Claude API key | Yes\*\* |

628| `github_token` | GitHub token for API access | No |631| `github_token` | GitHub token for API access | No |

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

663 666

664You can configure Claude's behavior in two ways:667You can configure Claude's behavior in two ways:

665 668

6661. **CLAUDE.md**: Define coding standards, review criteria, and project-specific rules in a `CLAUDE.md` file at the root of your repository. Claude will follow these guidelines when creating PRs and responding to requests. Check out our [Memory documentation](/en/docs/claude-code/memory) for more details.6691. **CLAUDE.md**: Define coding standards, review criteria, and project-specific rules in a `CLAUDE.md` file at the root of your repository. Claude will follow these guidelines when creating PRs and responding to requests. Check out our [Memory documentation](/en/memory) for more details.

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 +13 −8

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/docs/claude-code/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?

77 before_script:77 before_script:

78 - apk update78 - apk update

79 - apk add --no-cache git curl bash79 - apk add --no-cache git curl bash

~~80 - npm install -g @anthropic-ai/claude-code~~80 - curl -fsSL https://claude.ai/install.sh | bash

81 script:81 script:

82 # Optional: start a GitLab MCP server if your setup provides one82 # Optional: start a GitLab MCP server if your setup provides one

83 - /bin/gitlab-mcp-server || true83 - /bin/gitlab-mcp-server || true

255 before_script:255 before_script:

256 - apk update256 - apk update

257 - apk add --no-cache git curl bash257 - apk add --no-cache git curl bash

258 - npm install -g @anthropic-ai/claude-code258 - curl -fsSL https://claude.ai/install.sh | bash

259 script:259 script:

260 - /bin/gitlab-mcp-server || true260 - /bin/gitlab-mcp-server || true

261 - >261 - >

289 before_script:289 before_script:

290 - apk add --no-cache bash curl jq git python3 py3-pip290 - apk add --no-cache bash curl jq git python3 py3-pip

291 - pip install --no-cache-dir awscli291 - pip install --no-cache-dir awscli

292 - npm install -g @anthropic-ai/claude-code292 - curl -fsSL https://claude.ai/install.sh | bash

293 # Exchange GitLab OIDC token for AWS credentials293 # Exchange GitLab OIDC token for AWS credentials

294 - export AWS_WEB_IDENTITY_TOKEN_FILE="${CI_JOB_JWT_FILE:-/tmp/oidc_token}"294 - export AWS_WEB_IDENTITY_TOKEN_FILE="${CI_JOB_JWT_FILE:-/tmp/oidc_token}"

295 - if [ -n "${CI_JOB_JWT_V2}" ]; then printf "%s" "$CI_JOB_JWT_V2" > "$AWS_WEB_IDENTITY_TOKEN_FILE"; fi295 - if [ -n "${CI_JOB_JWT_V2}" ]; then printf "%s" "$CI_JOB_JWT_V2" > "$AWS_WEB_IDENTITY_TOKEN_FILE"; fi

339 rules:339 rules:

340 - if: '$CI_PIPELINE_SOURCE == "web"'340 - if: '$CI_PIPELINE_SOURCE == "web"'

341 before_script:341 before_script:

342 - apt-get update && apt-get install -y git nodejs npm && apt-get clean342 - apt-get update && apt-get install -y git && apt-get clean

343 - npm install -g @anthropic-ai/claude-code343 - curl -fsSL https://claude.ai/install.sh | bash

344 # Authenticate to Google Cloud via WIF (no downloaded keys)344 # Authenticate to Google Cloud via WIF (no downloaded keys)

345 - >345 - >

346 gcloud auth login --cred-file=<(cat <<EOF346 gcloud auth login --cred-file=<(cat <<EOF

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 +92 −141

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/docs/claude-code/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" \

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

92```

124 93

125# Automated incident response agent94The `--allowedTools` flag uses [permission rule syntax](/en/settings#permission-rule-syntax). The `:*` suffix enables prefix matching, so `Bash(git diff:*)` allows any command starting with `git diff`.

126investigate_incident() {

127 local incident_description="$1"

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

129 95

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

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

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

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

134 --mcp-config monitoring-tools.json

135}

136 99

137# Usage100### Customize the system prompt

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

139```

140 101

141### Automated Security Review102Use `--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 103

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

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

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

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

108```

147 109

148 gh pr diff "$pr_number" | claude -p \110See [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 111

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

155audit_pr 123 > security-report.json

156```

157 113

158### Multi-turn Legal Assistant114Use `--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 115

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

161# Legal document review with session persistence117# First request

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

163 119

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

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

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

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

168```123```

169 124

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

171 126

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

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

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

130```

173 131

174 ```bash theme={null}132## 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 133

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

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

136 Build your first agent with Python or TypeScript

137 </Card>

182 138

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

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

185 echo "Error occurred:" >&2141 </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 142

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

144 Use the Agent SDK in GitHub workflows

145 </Card>

194 146

195 ```bash theme={null}147 <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"148 Use the Agent SDK in GitLab pipelines

197 ```149 </Card>

150</CardGroup>

198 151

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

200 152

201## Related Resources153---

202 154

203* [CLI usage and controls](/en/docs/claude-code/cli-reference) - Complete CLI documentation155> 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/docs/claude-code/common-workflows) - Step-by-step guides for common use cases

hooks.md +470 −56

Details

3> This page provides reference documentation for implementing hooks in Claude Code.3> This page provides reference documentation for implementing hooks in Claude Code.

4 4

5<Tip>5<Tip>

~~6 For a quickstart guide with examples, see [Get started with Claude Code hooks](/en/docs/claude-code/hooks-guide).~~6 For a quickstart guide with examples, see [Get started with Claude Code hooks](/en/hooks-guide).

7</Tip>7</Tip>

8 8

9## Configuration9## Configuration

10 10

~~11Claude Code hooks are configured in your [settings files](/en/docs/claude-code/settings):~~11Claude Code hooks are configured in your [settings files](/en/settings):

12 12

13* `~/.claude/settings.json` - User settings13* `~/.claude/settings.json` - User settings

14* `.claude/settings.json` - Project settings14* `.claude/settings.json` - Project settings

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

~~16* Enterprise managed policy settings~~16* Managed policy settings

18<Note>

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

20</Note>

17 21

18### Structure22### Structure

19 23

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

45 `matcher` blank.49 `matcher` blank.

~~46* **hooks**: Array of commands to execute when the pattern matches~~50* **hooks**: Array of hooks to execute when the pattern matches

~~47 * `type`: Currently only `"command"` is supported~~51 * `type`: Hook execution type - `"command"` for bash commands or `"prompt"` for LLM-based evaluation

~~48 * `command`: The bash command to execute (can use `$CLAUDE_PROJECT_DIR`~~52 * `command`: (For `type: "command"`) The bash command to execute (can use `$CLAUDE_PROJECT_DIR` environment variable)

~~49 environment variable)~~53 * `prompt`: (For `type: "prompt"`) The prompt to send to the LLM for evaluation

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

~~51 canceling that specific command.~~55

52 56For events like `UserPromptSubmit`, `Stop`, `SubagentStop`, and `Setup`

~~53For events like `UserPromptSubmit`, `Notification`, `Stop`, and `SubagentStop`~~

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

55 58

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

96 99

97### Plugin hooks100### Plugin hooks

98 101

99[Plugins](/en/docs/claude-code/plugins) can provide hooks that integrate seamlessly with your user and project hooks. Plugin hooks are automatically merged with your configuration when plugins are enabled.102[Plugins](/en/plugins) can provide hooks that integrate seamlessly with your user and project hooks. Plugin hooks are automatically merged with your configuration when plugins are enabled.

100 103

101**How plugin hooks work**:104**How plugin hooks work**:

102 105

141* `${CLAUDE_PROJECT_DIR}`: Project root directory (same as for project hooks)144* `${CLAUDE_PROJECT_DIR}`: Project root directory (same as for project hooks)

142* All standard environment variables are available145* All standard environment variables are available

143 146

144See the [plugin components reference](/en/docs/claude-code/plugins-reference#hooks) for details on creating plugin hooks.147See the [plugin components reference](/en/plugins-reference#hooks) for details on creating plugin hooks.

148

149### Hooks in skills and agents

150

151In addition to settings files and plugins, hooks can be defined directly in [skills](/en/skills) and [subagents](/en/sub-agents) using frontmatter. These hooks are scoped to the component's lifecycle and only run when that component is active.

152

153**Supported events**: `PreToolUse`, `PostToolUse`, and `Stop`

154

155**Example in a Skill**:

156

157```yaml theme={null}

158---

159name: secure-operations

160description: Perform operations with security checks

161hooks:

162 PreToolUse:

163 - matcher: "Bash"

164 hooks:

165 - type: command

166 command: "./scripts/security-check.sh"

167---

168```

169

170**Example in an agent**:

171

172```yaml theme={null}

173---

174name: code-reviewer

175description: Review code changes

176hooks:

177 PostToolUse:

178 - matcher: "Edit|Write"

179 hooks:

180 - type: command

181 command: "./scripts/run-linter.sh"

182---

183```

184

185Component-scoped hooks follow the same configuration format as settings-based hooks but are automatically cleaned up when the component finishes executing.

186

187**Additional option for skills:**

188

189* `once`: Set to `true` to run the hook only once per session. After the first successful execution, the hook is removed. Note: This option is currently only supported for skills, not for agents.

190

191## Prompt-Based Hooks

192

193In addition to bash command hooks (`type: "command"`), Claude Code supports prompt-based hooks (`type: "prompt"`) that use an LLM to evaluate whether to allow or block an action. Prompt-based hooks are currently only supported for `Stop` and `SubagentStop` hooks, where they enable intelligent, context-aware decisions.

194

195### How prompt-based hooks work

196

197Instead of executing a bash command, prompt-based hooks:

198

1991. Send the hook input and your prompt to a fast LLM (Haiku)

2002. The LLM responds with structured JSON containing a decision

2013. Claude Code processes the decision automatically

202

203### Configuration

204

205```json theme={null}

206{

207 "hooks": {

208 "Stop": [

209 {

210 "hooks": [

211 {

212 "type": "prompt",

213 "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."

214 }

215 ]

216 }

217 ]

218 }

219}

220```

221

222**Fields:**

223

224* `type`: Must be `"prompt"`

225* `prompt`: The prompt text to send to the LLM

226 * Use `$ARGUMENTS` as a placeholder for the hook input JSON

227 * If `$ARGUMENTS` is not present, input JSON is appended to the prompt

228* `timeout`: (Optional) Timeout in seconds (default: 30 seconds)

229

230### Response schema

231

232The LLM must respond with JSON containing:

233

234```json theme={null}

235{

236 "ok": true | false,

237 "reason": "Explanation for the decision"

238}

239```

240

241**Response fields:**

242

243* `ok`: `true` allows the action, `false` prevents it

244* `reason`: Required when `ok` is `false`. Explanation shown to Claude

245

246### Supported hook events

247

248Prompt-based hooks work with any hook event, but are most useful for:

249

250* **Stop**: Intelligently decide if Claude should continue working

251* **SubagentStop**: Evaluate if a subagent has completed its task

252* **UserPromptSubmit**: Validate user prompts with LLM assistance

253* **PreToolUse**: Make context-aware permission decisions

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

255

256### Example: Intelligent Stop hook

257

258```json theme={null}

259{

260 "hooks": {

261 "Stop": [

262 {

263 "hooks": [

264 {

265 "type": "prompt",

266 "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",

267 "timeout": 30

268 }

269 ]

270 }

271 ]

272 }

273}

274```

275

276### Example: SubagentStop with custom logic

277

278```json theme={null}

279{

280 "hooks": {

281 "SubagentStop": [

282 {

283 "hooks": [

284 {

285 "type": "prompt",

286 "prompt": "Evaluate if this subagent should stop. Input: $ARGUMENTS\n\nCheck if:\n- The subagent completed its assigned task\n- Any errors occurred that need fixing\n- Additional context gathering is needed\n\nReturn: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"explanation\"} to continue."

287 }

288 ]

289 }

290 ]

291 }

292}

293```

294

295### Comparison with bash command hooks

296

297| Feature | Bash Command Hooks | Prompt-Based Hooks |

298| --------------------- | ----------------------- | ------------------------------ |

299| **Execution** | Runs bash script | Queries LLM |

300| **Decision logic** | You implement in code | LLM evaluates context |

301| **Setup complexity** | Requires script file | Configure prompt |

302| **Context awareness** | Limited to script logic | Natural language understanding |

303| **Performance** | Fast (local execution) | Slower (API call) |

304| **Use case** | Deterministic rules | Context-aware decisions |

305

306### Best practices

307

308* **Be specific in prompts**: Clearly state what you want the LLM to evaluate

309* **Include decision criteria**: List the factors the LLM should consider

310* **Test your prompts**: Verify the LLM makes correct decisions for your use cases

311* **Set appropriate timeouts**: Default is 30 seconds, adjust if needed

312* **Use for complex decisions**: Bash hooks are better for simple, deterministic rules

313

314See the [plugin components reference](/en/plugins-reference#hooks) for details on creating plugin hooks.

145 315

146## Hook Events316## Hook Events

147 317

151 321

152**Common matchers:**322**Common matchers:**

153 323

154* `Task` - Subagent tasks (see [subagents documentation](/en/docs/claude-code/sub-agents))324* `Task` - Subagent tasks (see [subagents documentation](/en/sub-agents))

155* `Bash` - Shell commands325* `Bash` - Shell commands

156* `Glob` - File pattern matching326* `Glob` - File pattern matching

157* `Grep` - Content search327* `Grep` - Content search

160* `Write` - File writing330* `Write` - File writing

161* `WebFetch`, `WebSearch` - Web operations331* `WebFetch`, `WebSearch` - Web operations

162 332

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

334

335### PermissionRequest

336

337Runs when the user is shown a permission dialog.

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

339

340Recognizes the same matcher values as PreToolUse.

341

163### PostToolUse342### PostToolUse

164 343

165Runs immediately after a tool completes successfully.344Runs immediately after a tool completes successfully.

168 347

169### Notification348### Notification

170 349

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

351

352**Common matchers:**

353

354* `permission_prompt` - Permission requests from Claude Code

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

356* `auth_success` - Authentication success notifications

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

358

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

172 360

1731. Claude needs your permission to use a tool. Example: "Claude needs your361**Example: Different notifications for different types**

174 permission to use Bash"362

1752. The prompt input has been idle for at least 60 seconds. "Claude is waiting363```json theme={null}

176 for your input"364{

365 "hooks": {

366 "Notification": [

367 {

368 "matcher": "permission_prompt",

369 "hooks": [

370 {

371 "type": "command",

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

373 }

374 ]

375 },

376 {

377 "matcher": "idle_prompt",

378 "hooks": [

379 {

380 "type": "command",

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

382 }

383 ]

384 }

385 ]

386 }

387}

388```

177 389

178### UserPromptSubmit390### UserPromptSubmit

179 391

199* `manual` - Invoked from `/compact`411* `manual` - Invoked from `/compact`

200* `auto` - Invoked from auto-compact (due to full context window)412* `auto` - Invoked from auto-compact (due to full context window)

201 413

414### Setup

415

416Runs when Claude Code is invoked with repository setup and maintenance flags (`--init`, `--init-only`, or `--maintenance`). Use this hook for operations you don't want on every session—such as installing dependencies, running migrations, or periodic maintenance tasks.

417

418<Note>

419 Use **Setup** hooks for one-time or occasional operations (dependency installation, migrations, cleanup). Use **SessionStart** hooks for things you want on every session (loading context, setting environment variables). Setup hooks require explicit flags because running them automatically would slow down every session start.

420</Note>

421

422**Matchers:**

423

424* `init` - Invoked from `--init` or `--init-only` flags

425* `maintenance` - Invoked from `--maintenance` flag

426

427Setup hooks have access to the `CLAUDE_ENV_FILE` environment variable for persisting environment variables, similar to SessionStart hooks.

428

202### SessionStart429### SessionStart

203 430

204Runs when Claude Code starts a new session or resumes an existing session (which431Runs when Claude Code starts a new session or resumes an existing session (which

205currently does start a new session under the hood). Useful for loading in432currently does start a new session under the hood). Useful for loading development context like existing issues or recent changes to your codebase, or setting up environment variables.

206development context like existing issues or recent changes to your codebase, installing dependencies, or setting up environment variables.433

434<Note>

435 For one-time operations like installing dependencies or running migrations, use [Setup hooks](#setup) instead. SessionStart runs on every session, so keep these hooks fast.

436</Note>

207 437

208**Matchers:**438**Matchers:**

209 439

232 462

233**Example: Persisting all environment changes from the hook**463**Example: Persisting all environment changes from the hook**

234 464

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

236 466

237```bash theme={null}467```bash theme={null}

238#!/bin/bash468#!/bin/bash

280 session_id: string510 session_id: string

281 transcript_path: string // Path to conversation JSON511 transcript_path: string // Path to conversation JSON

282 cwd: string // The current working directory when the hook is invoked512 cwd: string // The current working directory when the hook is invoked

283 permission_mode: string // Current permission mode: "default", "plan", "acceptEdits", or "bypassPermissions"513 permission_mode: string // Current permission mode: "default", "plan", "acceptEdits", "dontAsk", or "bypassPermissions"

284 514

285 // Event-specific fields515 // Event-specific fields

286 hook_event_name: string516 hook_event_name: string

290 520

291### PreToolUse Input521### PreToolUse Input

292 522

293The exact schema for `tool_input` depends on the tool.523The exact schema for `tool_input` depends on the tool. Here are examples for commonly hooked tools.

524

525#### Bash tool

526

527The Bash tool is the most commonly hooked tool for command validation:

528

529```json theme={null}

530{

531 "session_id": "abc123",

532 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

533 "cwd": "/Users/...",

534 "permission_mode": "default",

535 "hook_event_name": "PreToolUse",

536 "tool_name": "Bash",

537 "tool_input": {

538 "command": "psql -c 'SELECT * FROM users'",

539 "description": "Query the users table",

540 "timeout": 120000

541 },

542 "tool_use_id": "toolu_01ABC123..."

543}

544```

545

546| Field | Type | Description |

547| :------------------ | :------ | :-------------------------------------------- |

548| `command` | string | The shell command to execute |

549| `description` | string | Optional description of what the command does |

550| `timeout` | number | Optional timeout in milliseconds |

551| `run_in_background` | boolean | Whether to run the command in background |

552

553#### Write tool

294 554

295```json theme={null}555```json theme={null}

296{556{

303 "tool_input": {563 "tool_input": {

304 "file_path": "/path/to/file.txt",564 "file_path": "/path/to/file.txt",

305 "content": "file content"565 "content": "file content"

306 }566 },

567 "tool_use_id": "toolu_01ABC123..."

568}

569```

570

571| Field | Type | Description |

572| :---------- | :----- | :--------------------------------- |

573| `file_path` | string | Absolute path to the file to write |

574| `content` | string | Content to write to the file |

575

576#### Edit tool

577

578```json theme={null}

579{

580 "session_id": "abc123",

581 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

582 "cwd": "/Users/...",

583 "permission_mode": "default",

584 "hook_event_name": "PreToolUse",

585 "tool_name": "Edit",

586 "tool_input": {

587 "file_path": "/path/to/file.txt",

588 "old_string": "original text",

589 "new_string": "replacement text"

590 },

591 "tool_use_id": "toolu_01ABC123..."

592}

593```

594

595| Field | Type | Description |

596| :------------ | :------ | :-------------------------------------------------- |

597| `file_path` | string | Absolute path to the file to edit |

598| `old_string` | string | Text to find and replace |

599| `new_string` | string | Replacement text |

600| `replace_all` | boolean | Whether to replace all occurrences (default: false) |

601

602#### Read tool

603

604```json theme={null}

605{

606 "session_id": "abc123",

607 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

608 "cwd": "/Users/...",

609 "permission_mode": "default",

610 "hook_event_name": "PreToolUse",

611 "tool_name": "Read",

612 "tool_input": {

613 "file_path": "/path/to/file.txt"

614 },

615 "tool_use_id": "toolu_01ABC123..."

307}616}

308```617```

309 618

619| Field | Type | Description |

620| :---------- | :----- | :----------------------------------------- |

621| `file_path` | string | Absolute path to the file to read |

622| `offset` | number | Optional line number to start reading from |

623| `limit` | number | Optional number of lines to read |

624

310### PostToolUse Input625### PostToolUse Input

311 626

312The exact schema for `tool_input` and `tool_response` depends on the tool.627The exact schema for `tool_input` and `tool_response` depends on the tool.

326 "tool_response": {641 "tool_response": {

327 "filePath": "/path/to/file.txt",642 "filePath": "/path/to/file.txt",

328 "success": true643 "success": true

329 }644 },

645 "tool_use_id": "toolu_01ABC123..."

330}646}

331```647```

332 648

339 "cwd": "/Users/...",655 "cwd": "/Users/...",

340 "permission_mode": "default",656 "permission_mode": "default",

341 "hook_event_name": "Notification",657 "hook_event_name": "Notification",

342 "message": "Task completed successfully"658 "message": "Claude needs your permission to use Bash",

659 "notification_type": "permission_prompt"

343}660}

344```661```

345 662

388}705}

389```706```

390 707

708### Setup Input

709

710```json theme={null}

711{

712 "session_id": "abc123",

713 "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

714 "cwd": "/Users/...",

715 "permission_mode": "default",

716 "hook_event_name": "Setup",

717 "trigger": "init"

718}

719```

720

721The `trigger` field will be either `"init"` (from `--init` or `--init-only`) or `"maintenance"` (from `--maintenance`).

722

391### SessionStart Input723### SessionStart Input

392 724

393```json theme={null}725```json theme={null}

415 747

416## Hook Output748## Hook Output

417 749

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

419communicates whether to block and any feedback that should be shown to Claude751communicates whether to block and any feedback that should be shown to Claude

420and the user.752and the user.

421 753

423 755

424Hooks communicate status through exit codes, stdout, and stderr:756Hooks communicate status through exit codes, stdout, and stderr:

425 757

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

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

428 added to the context.760 added to the context. JSON output in `stdout` is parsed for structured control

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

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

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

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

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

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

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

433 768

434<Warning>769<Warning>

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

439#### Exit Code 2 Behavior774#### Exit Code 2 Behavior

440 775

441| Hook Event | Behavior |776| Hook Event | Behavior |

442| ------------------ | ------------------------------------------------------------------ |777| ------------------- | ------------------------------------------------------------------ |

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

786| `Setup` | N/A, shows stderr to user only |

452 789

453### Advanced: JSON Output790### Advanced: JSON Output

454 791

455Hooks can return structured JSON in `stdout` for more sophisticated control:792Hooks can return structured JSON in `stdout` for more sophisticated control.

793

794<Warning>

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

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

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

798</Warning>

456 799

457#### Common JSON Fields800#### Common JSON Fields

458 801

496 839

497Additionally, hooks can modify tool inputs before execution using `updatedInput`:840Additionally, hooks can modify tool inputs before execution using `updatedInput`:

498 841

499* `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.842* `updatedInput` modifies the tool's input parameters before the tool executes

500* This is most useful with `"permissionDecision": "allow"` to modify and approve tool calls.843* Combine with `"permissionDecision": "allow"` to modify the input and auto-approve the tool call

844* Combine with `"permissionDecision": "ask"` to modify the input and show it to the user for confirmation

845

846Hooks can also provide context to Claude using `additionalContext`:

847

848* `"hookSpecificOutput.additionalContext"` adds a string to Claude's context before the tool executes.

501 849

502```json theme={null}850```json theme={null}

503{851{

504 "hookSpecificOutput": {852 "hookSpecificOutput": {

505 "hookEventName": "PreToolUse",853 "hookEventName": "PreToolUse",

506 "permissionDecision": "allow"854 "permissionDecision": "allow",

507 "permissionDecisionReason": "My reason here",855 "permissionDecisionReason": "My reason here",

508 "updatedInput": {856 "updatedInput": {

509 "field_to_modify": "new value"857 "field_to_modify": "new value"

510 }858 },

859 "additionalContext": "Current environment: production. Proceed with caution."

511 }860 }

512}861}

513```862```

519 `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively.868 `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively.

520</Note>869</Note>

521 870

871#### `PermissionRequest` Decision Control

872

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

874

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

876* 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.

877

878```json theme={null}

879{

880 "hookSpecificOutput": {

881 "hookEventName": "PermissionRequest",

882 "decision": {

883 "behavior": "allow",

884 "updatedInput": {

885 "command": "npm run lint"

886 }

887 }

888 }

889}

890```

891

522#### `PostToolUse` Decision Control892#### `PostToolUse` Decision Control

523 893

524`PostToolUse` hooks can provide feedback to Claude after tool execution.894`PostToolUse` hooks can provide feedback to Claude after tool execution.

540 910

541#### `UserPromptSubmit` Decision Control911#### `UserPromptSubmit` Decision Control

542 912

543`UserPromptSubmit` hooks can control whether a user prompt is processed.913`UserPromptSubmit` hooks can control whether a user prompt is processed and add context.

914

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

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

917

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

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

920

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

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

544 923

545* `"block"` prevents the prompt from being processed. The submitted prompt is924Both methods work with exit code 0. Plain stdout is shown as hook output in

546 erased from context. `"reason"` is shown to the user but not added to context.925the transcript; `additionalContext` is added more discretely.

547* `undefined` allows the prompt to proceed normally. `"reason"` is ignored.926

548* `"hookSpecificOutput.additionalContext"` adds the string to the context if not927**Blocking prompts:**

549 blocked.928

929* `"decision": "block"` prevents the prompt from being processed. The submitted

930 prompt is erased from context. `"reason"` is shown to the user but not added

931 to context.

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

550 933

551```json theme={null}934```json theme={null}

552{935{

559}942}

560```943```

561 944

945<Note>

946 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

947 block prompts or want more structured control.

948</Note>

949

562#### `Stop`/`SubagentStop` Decision Control950#### `Stop`/`SubagentStop` Decision Control

563 951

564`Stop` and `SubagentStop` hooks can control whether Claude must continue.952`Stop` and `SubagentStop` hooks can control whether Claude must continue.

574}962}

575```963```

576 964

965#### `Setup` Decision Control

966

967`Setup` hooks allow you to load context and configure the environment during repository initialization or maintenance.

968

969* `"hookSpecificOutput.additionalContext"` adds the string to the context.

970* Multiple hooks' `additionalContext` values are concatenated.

971* Setup hooks have access to `CLAUDE_ENV_FILE` for persisting environment variables.

972

973```json theme={null}

974{

975 "hookSpecificOutput": {

976 "hookEventName": "Setup",

977 "additionalContext": "Repository initialized with custom configuration"

978 }

979}

980```

981

577#### `SessionStart` Decision Control982#### `SessionStart` Decision Control

578 983

579`SessionStart` hooks allow you to load in context at the start of a session.984`SessionStart` hooks allow you to load in context at the start of a session.

652<Note>1057<Note>

653 For `UserPromptSubmit` hooks, you can inject context using either method:1058 For `UserPromptSubmit` hooks, you can inject context using either method:

654 1059

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

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

1062 or `additionalContext` for structured context injection

1063

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

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

657</Note>1066</Note>

658 1067

659```python theme={null}1068```python theme={null}

730 output = {1139 output = {

731 "decision": "approve",1140 "decision": "approve",

732 "reason": "Documentation file auto-approved",1141 "reason": "Documentation file auto-approved",

733 "suppressOutput": True # Don't show in transcript mode1142 "suppressOutput": True # Don't show in verbose mode

734 }1143 }

735 print(json.dumps(output))1144 print(json.dumps(output))

736 sys.exit(0)1145 sys.exit(0)

742## Working with MCP Tools1151## Working with MCP Tools

743 1152

744Claude Code hooks work seamlessly with1153Claude Code hooks work seamlessly with

745[Model Context Protocol (MCP) tools](/en/docs/claude-code/mcp). When MCP servers1154[Model Context Protocol (MCP) tools](/en/mcp). When MCP servers

746provide tools, they appear with a special naming pattern that you can match in1155provide tools, they appear with a special naming pattern that you can match in

747your hooks.1156your hooks.

748 1157

788## Examples1197## Examples

789 1198

790<Tip>1199<Tip>

791 For practical examples including code formatting, notifications, and file protection, see [More Examples](/en/docs/claude-code/hooks-guide#more-examples) in the get started guide.1200 For practical examples including code formatting, notifications, and file protection, see [More Examples](/en/hooks-guide#more-examples) in the get started guide.

792</Tip>1201</Tip>

793 1202

794## Security Considerations1203## Security Considerations

843 * 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.1252 * 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.

844* **Input**: JSON via stdin1253* **Input**: JSON via stdin

845* **Output**:1254* **Output**:

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

847 * Notification/SessionEnd: Logged to debug only (`--debug`)1256 * Notification/SessionEnd: Logged to debug only (`--debug`)

848 * UserPromptSubmit/SessionStart: stdout added as context for Claude1257 * UserPromptSubmit/SessionStart/Setup: stdout added as context for Claude

849 1258

850## Debugging1259## Debugging

851 1260

892[DEBUG] Hook command completed with status 0: <Your stdout>1301[DEBUG] Hook command completed with status 0: <Your stdout>

893```1302```

894 1303

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

896 1305

897* Which hook is running1306* Which hook is running

898* Command being executed1307* Command being executed

899* Success/failure status1308* Success/failure status

900* Output or error messages1309* Output or error messages

1310

1311

1312---

1313

1314> 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 +14 −7

Details

8the LLM to choose to run them.8the LLM to choose to run them.

9 9

10<Tip>10<Tip>

~~11 For reference documentation on hooks, see [Hooks reference](/en/docs/claude-code/hooks).~~11 For reference documentation on hooks, see [Hooks reference](/en/hooks).

12</Tip>12</Tip>

13 13

14Example use cases for hooks include:14Example use cases for hooks include:

31 You must consider the security implication of hooks as you add them, because hooks run automatically during the agent loop with your current environment's credentials.31 You must consider the security implication of hooks as you add them, because hooks run automatically during the agent loop with your current environment's credentials.

32 For example, malicious hooks code can exfiltrate your data. Always review your hooks implementation before registering them.32 For example, malicious hooks code can exfiltrate your data. Always review your hooks implementation before registering them.

33 33

~~34 For full security best practices, see [Security Considerations](/en/docs/claude-code/hooks#security-considerations) in the hooks reference documentation.~~34 For full security best practices, see [Security Considerations](/en/hooks#security-considerations) in the hooks reference documentation.

35</Warning>35</Warning>

36 36

37## Hook Events Overview37## Hook Events Overview

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

46* **Stop**: Runs when Claude Code finishes responding47* **Stop**: Runs when Claude Code finishes responding

47* **SubagentStop**: Runs when subagent tasks complete48* **SubagentStop**: Runs when subagent tasks complete

48* **PreCompact**: Runs before Claude Code is about to run a compact operation49* **PreCompact**: Runs before Claude Code is about to run a compact operation

50* **Setup**: Runs when Claude Code is invoked with `--init`, `--init-only`, or `--maintenance` flags

49* **SessionStart**: Runs when Claude Code starts a new session or resumes an existing session51* **SessionStart**: Runs when Claude Code starts a new session or resumes an existing session

50* **SessionEnd**: Runs when Claude Code session ends52* **SessionEnd**: Runs when Claude Code session ends

51 53

63 65

64### Step 1: Open hooks configuration66### Step 1: Open hooks configuration

65 67

~~66Run the `/hooks` [slash command](/en/docs/claude-code/slash-commands) and select~~68Run the `/hooks` command and select

67the `PreToolUse` hook event.69the `PreToolUse` hook event.

68 70

69`PreToolUse` hooks run before tool calls and can block them while providing71`PreToolUse` hooks run before tool calls and can block them while providing

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

92project.94project.

93 95

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

95 97

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

97 99

326 328

327## Learn more329## Learn more

328 330

329* For reference documentation on hooks, see [Hooks reference](/en/docs/claude-code/hooks).331* For reference documentation on hooks, see [Hooks reference](/en/hooks).

330* For comprehensive security best practices and safety guidelines, see [Security Considerations](/en/docs/claude-code/hooks#security-considerations) in the hooks reference documentation.332* 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/docs/claude-code/hooks#debugging) in the hooks reference333* For troubleshooting steps and debugging techniques, see [Debugging](/en/hooks#debugging) in the hooks reference

332 documentation.334 documentation.

335

336

337---

338

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

how-claude-code-works.md +239 −0 added

Details

1# How Claude Code works

3> Understand the agentic loop, built-in tools, and how Claude Code interacts with your project.

5Claude Code is an agentic assistant that runs in your terminal. While it excels at coding, it can help with anything you can do from the command line: writing docs, running builds, searching files, researching topics, and more.

7This guide covers the core architecture, built-in capabilities, and [tips for working effectively](#work-effectively-with-claude-code). For step-by-step walkthroughs, see [Common workflows](/en/common-workflows). For extensibility features like skills, MCP, and hooks, see [Extend Claude Code](/en/features-overview).

9## The agentic loop

11When you give Claude a task, it works through three phases: **gather context**, **take action**, and **verify results**. These phases blend together. Claude uses tools throughout, whether searching files to understand your code, editing to make changes, or running tests to check its work.

13<img src="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=e30acfc80d6ff01ec877dd19c7af58b2" alt="The agentic loop: Your prompt leads to Claude gathering context, taking action, verifying results, and repeating until task complete. You can interrupt at any point." data-og-width="720" width="720" data-og-height="280" height="280" data-path="images/agentic-loop.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=280&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=8620f6ebce761a1e8bbf7f0a0255cc15 280w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=560&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=7b46b5ff4454aa4a03725eee625b39a0 560w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=840&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=7fa0397bc37d147e3bf3bb6296c6477f 840w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=1100&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=73b2a7040c4c93821c4d5bbee9f4a2d4 1100w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=1650&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=17703cbeb6f59b40a00ab24f56d5f8f9 1650w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=2500&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=20dedb60b95d45a1bd60a0cccaf3e1ff 2500w" />

15The loop adapts to what you ask. A question about your codebase might only need context gathering. A bug fix cycles through all three phases repeatedly. A refactor might involve extensive verification. Claude decides what each step requires based on what it learned from the previous step, chaining dozens of actions together and course-correcting along the way.

17You're part of this loop too. You can interrupt at any point to steer Claude in a different direction, provide additional context, or ask it to try a different approach. Claude works autonomously but stays responsive to your input.

19The agentic loop is powered by two components: [models](#models) that reason and [tools](#tools) that act. Claude Code serves as the **agentic harness** around Claude: it provides the tools, context management, and execution environment that turn a language model into a capable coding agent.

21### Models

23Claude Code uses Claude models to understand your code and reason about tasks. Claude can read code in any language, understand how components connect, and figure out what needs to change to accomplish your goal. For complex tasks, it breaks work into steps, executes them, and adjusts based on what it learns.

25[Multiple models](/en/model-config) are available with different tradeoffs. Sonnet handles most coding tasks well. Opus provides stronger reasoning for complex architectural decisions. Switch with `/model` during a session or start with `claude --model <name>`.

27When this guide says "Claude chooses" or "Claude decides," it's the model doing the reasoning.

29### Tools

31Tools are what make Claude Code agentic. Without tools, Claude can only respond with text. With tools, Claude can act: read your code, edit files, run commands, search the web, and interact with external services. Each tool use returns information that feeds back into the loop, informing Claude's next decision.

33The built-in tools generally fall into four categories, each representing a different kind of agency.

35| Category | What Claude can do |

36| ------------------- | ------------------------------------------------------------------- |

37| **File operations** | Read files, edit code, create new files, rename and reorganize |

38| **Search** | Find files by pattern, search content with regex, explore codebases |

39| **Execution** | Run shell commands, start servers, run tests, use git |

40| **Web** | Search the web, fetch documentation, look up error messages |

42These are the primary capabilities. Claude also has tools for spawning subagents, asking you questions, and other orchestration tasks. See [Tools available to Claude](/en/settings#tools-available-to-claude) for the complete list.

44Claude chooses which tools to use based on your prompt and what it learns along the way. When you say "fix the failing tests," Claude might:

461. Run the test suite to see what's failing

472. Read the error output

483. Search for the relevant source files

494. Read those files to understand the code

505. Edit the files to fix the issue

516. Run the tests again to verify

53Each tool use gives Claude new information that informs the next step. This is the agentic loop in action.

55**Extending the base capabilities:** The built-in tools are the foundation. You can extend what Claude knows with [skills](/en/skills), connect to external services with [MCP](/en/mcp), automate workflows with [hooks](/en/hooks), and offload tasks to [subagents](/en/sub-agents). These extensions form a layer on top of the core agentic loop. See [Extend Claude Code](/en/features-overview) for guidance on choosing the right extension for your needs.

57## What Claude can access

59This guide focuses on the terminal. Claude Code also runs in [VS Code, JetBrains IDEs, and other environments](/en/ide-integrations).

61When you run `claude` in a directory, Claude Code gains access to:

63* **Your project.** Files in your directory and subdirectories, plus files elsewhere with your permission.

64* **Your terminal.** Any command you could run: build tools, git, package managers, system utilities, scripts. If you can do it from the command line, Claude can too.

65* **Your git state.** Current branch, uncommitted changes, and recent commit history.

66* **Your [CLAUDE.md](/en/memory).** A markdown file where you store project-specific instructions, conventions, and context that Claude should know every session.

67* **Extensions you configure.** [MCP servers](/en/mcp) for external services, [skills](/en/skills) for workflows, [subagents](/en/sub-agents) for delegated work, and [Claude in Chrome](/en/chrome) for browser interaction.

69Because Claude sees your whole project, it can work across it. When you ask Claude to "fix the authentication bug," it searches for relevant files, reads multiple files to understand context, makes coordinated edits across them, runs tests to verify the fix, and commits the changes if you ask. This is different from inline code assistants that only see the current file.

71## Work with sessions

73Claude Code saves your conversation locally as you work. Each message, tool use, and result is stored, which enables [rewinding](#undo-changes-with-checkpoints), [resuming, and forking](#resume-or-fork-sessions) sessions. Before Claude makes code changes, it also snapshots the affected files so you can revert if needed.

75**Sessions are ephemeral.** Unlike claude.ai, Claude Code has no persistent memory between sessions. Each new session starts fresh. Claude doesn't "learn" your preferences over time or remember what you worked on last week. If you want Claude to know something across sessions, put it in your [CLAUDE.md](/en/memory).

77### Work across branches

79Each Claude Code conversation is a session tied to your current directory. When you resume, you only see sessions from that directory.

81Claude sees your current branch's files. When you switch branches, Claude sees the new branch's files, but your conversation history stays the same. Claude remembers what you discussed even after switching.

83Since sessions are tied to directories, you can run parallel Claude sessions by using [git worktrees](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), which create separate directories for individual branches.

85### Resume or fork sessions

87When you resume a session with `claude --continue` or `claude --resume`, you pick up where you left off using the same session ID. New messages append to the existing conversation. Your full conversation history is restored, but session-scoped permissions are not. You'll need to re-approve those.

89<img src="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=f671b603cc856119c95475b9084ebfef" alt="Session continuity: resume continues the same session, fork creates a new branch with a new ID." data-og-width="560" width="560" data-og-height="280" height="280" data-path="images/session-continuity.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=280&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=bddf1f33d419a27d7427acdf06058804 280w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=560&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=417478eb9b86003b8eebaac058a8618a 560w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=840&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=1d89d26e2c0487f067d187c3fa5f7170 840w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=1100&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=8ea739a1f7860e4edbbcf74d444e37b2 1100w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=1650&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=9cb5095d6a8920f04c3b78d31a69c809 1650w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=2500&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=d67e1744e4878813d20c6c3f39d9459d 2500w" />

91To branch off and try a different approach without affecting the original session, use the `--fork-session` flag:

93```bash theme={null}

94claude --continue --fork-session

95```

97This creates a new session ID while preserving the conversation history up to that point. The original session remains unchanged. Like resume, forked sessions don't inherit session-scoped permissions.

99**Same session in multiple terminals**: If you resume the same session in multiple terminals, both terminals write to the same session file. Messages from both get interleaved, like two people writing in the same notebook. Nothing corrupts, but the conversation becomes jumbled. Each terminal only sees its own messages during the session, but if you resume that session later, you'll see everything interleaved. For parallel work from the same starting point, use `--fork-session` to give each terminal its own clean session.

100

101### The context window

102

103Claude's context window holds your conversation history, file contents, command outputs, [CLAUDE.md](/en/memory), loaded skills, and system instructions. As you work, context fills up. Claude compacts automatically, but instructions from early in the conversation can get lost. Put persistent rules in CLAUDE.md, and run `/context` to see what's using space.

104

105#### When context fills up

106

107Claude Code manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved; detailed instructions from early in the conversation may be lost. Put persistent rules in CLAUDE.md rather than relying on conversation history.

108

109To control what's preserved during compaction, add a "Compact Instructions" section to CLAUDE.md or run `/compact` with a focus (like `/compact focus on the API changes`).

110

111Run `/context` to see what's using space. MCP servers add tool definitions to every request, so a few servers can consume significant context before you start working. Run `/mcp` to check per-server costs.

112

113#### Manage context with skills and subagents

114

115Beyond compaction, you can use other features to control what loads into context.

116

117[Skills](/en/skills) load on demand. Claude sees skill descriptions at session start, but the full content only loads when a skill is used. For skills you invoke manually, set `disable-model-invocation: true` to keep descriptions out of context until you need them.

118

119[Subagents](/en/sub-agents) get their own fresh context, completely separate from your main conversation. Their work doesn't bloat your context. When done, they return a summary. This isolation is why subagents help with long sessions.

120

121See [context costs](/en/features-overview#understand-context-costs) for what each feature costs, and [reduce token usage](/en/costs#reduce-token-usage) for tips on managing context.

122

123## Stay safe with checkpoints and permissions

124

125Claude has two safety mechanisms: checkpoints let you undo file changes, and permissions control what Claude can do without asking.

126

127### Undo changes with checkpoints

128

129**Every file edit is reversible.** Before Claude edits any file, it snapshots the current contents. If something goes wrong, press `Esc` twice to rewind to a previous state, or ask Claude to undo.

130

131Checkpoints are local to your session, separate from git. They only cover file changes. Actions that affect remote systems (databases, APIs, deployments) can't be checkpointed, which is why Claude asks before running commands with external side effects.

132

133### Control what Claude can do

134

135Press `Shift+Tab` to cycle through permission modes:

136

137* **Default**: Claude asks before file edits and shell commands

138* **Auto-accept edits**: Claude edits files without asking, still asks for commands

139* **Plan mode**: Claude uses read-only tools only, creating a plan you can approve before execution

140

141You can also allow specific commands in `.claude/settings.json` so Claude doesn't ask each time. This is useful for trusted commands like `npm test` or `git status`. Settings can be scoped from organization-wide policies down to personal preferences. See [Permissions](/en/iam) for details.

142

143***

144

145## Work effectively with Claude Code

146

147These tips help you get better results from Claude Code.

148

149### Ask Claude Code for help

150

151Claude Code can teach you how to use it. Ask questions like "how do I set up hooks?" or "what's the best way to structure my CLAUDE.md?" and Claude will explain.

152

153Built-in commands also guide you through setup:

154

155* `/init` walks you through creating a CLAUDE.md for your project

156* `/agents` helps you configure custom subagents

157* `/doctor` diagnoses common issues with your installation

158

159### It's a conversation

160

161Claude Code is conversational. You don't need perfect prompts. Start with what you want, then refine:

162

163```

164> Fix the login bug

165

166[Claude investigates, tries something]

167

168> That's not quite right. The issue is in the session handling.

169

170[Claude adjusts approach]

171```

172

173When the first attempt isn't right, you don't start over. You iterate.

174

175#### Interrupt and steer

176

177You can interrupt Claude at any point. If it's going down the wrong path, just type your correction and press Enter. Claude will stop what it's doing and adjust its approach based on your input. You don't have to wait for it to finish or start over.

178

179### Be specific upfront

180

181The more precise your initial prompt, the fewer corrections you'll need. Reference specific files, mention constraints, and point to example patterns.

182

183```

184> The checkout flow is broken for users with expired cards.

185> Check src/payments/ for the issue, especially token refresh.

186> Write a failing test first, then fix it.

187```

188

189Vague prompts like "fix the login bug" work, but you'll spend more time steering. Specific prompts like the above often succeed on the first attempt.

190

191### Give Claude something to verify against

192

193Claude performs better when it can check its own work. Include test cases, paste screenshots of expected UI, or define the output you want.

194

195```

196> Implement validateEmail. Test cases: 'user@example.com' → true,

197> 'invalid' → false, 'user@.com' → false. Run the tests after.

198```

199

200For visual work, paste a screenshot of the design and ask Claude to compare its implementation against it.

201

202### Explore before implementing

203

204For complex problems, separate research from coding. Use plan mode (`Shift+Tab` twice) to analyze the codebase first:

205

206```

207> Read src/auth/ and understand how we handle sessions.

208> Then create a plan for adding OAuth support.

209```

210

211Review the plan, refine it through conversation, then let Claude implement. This two-phase approach produces better results than jumping straight to code.

212

213### Delegate, don't dictate

214

215Think of delegating to a capable colleague. Give context and direction, then trust Claude to figure out the details:

216

217```

218> The checkout flow is broken for users with expired cards.

219> The relevant code is in src/payments/. Can you investigate and fix it?

220```

221

222You don't need to specify which files to read or what commands to run. Claude figures that out.

223

224## What's next

225

226<CardGroup cols={2}>

227 <Card title="Extend with features" icon="puzzle-piece" href="/en/features-overview">

228 Add Skills, MCP connections, and custom commands

229 </Card>

230

231 <Card title="Common workflows" icon="graduation-cap" href="/en/common-workflows">

232 Step-by-step guides for typical tasks

233 </Card>

234</CardGroup>

235

236

237---

238

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

iam.md +87 −52

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 these ways:

8 8

~~9* Claude API via the Claude Console~~9* [Claude for Teams or Enterprise](/en/setup#for-teams-and-organizations) (recommended)

~~10* Amazon Bedrock~~10* [Claude Console with team billing](/en/setup#for-teams-and-organizations)

~~11* Google Vertex AI~~11* [Amazon Bedrock](/en/amazon-bedrock)

12* [Google Vertex AI](/en/google-vertex-ai)

13* [Microsoft Foundry](/en/microsoft-foundry)

12 14

~~13### Claude API authentication~~15### Claude for Teams or Enterprise (recommended)

14 16

~~15**To set up Claude Code access for your team via Claude API:**~~17[Claude for Teams](https://claude.com/pricing#team-&-enterprise) and [Claude for Enterprise](https://anthropic.com/contact-sales) provide the best experience for organizations using Claude Code. Team members get access to both Claude Code and Claude on the web with centralized billing and team management.

19* **Claude for Teams**: Self-service plan with collaboration features, admin tools, and billing management. Best for smaller teams.

20* **Claude for Enterprise**: Adds SSO, domain capture, role-based permissions, compliance API, and managed policy settings for organization-wide Claude Code configurations. Best for larger organizations with security and compliance requirements.

22**To set up Claude Code access:**

241. Subscribe to [Claude for Teams](https://claude.com/pricing#team-&-enterprise) or contact sales for [Claude for Enterprise](https://anthropic.com/contact-sales)

252. Invite team members from the admin dashboard

263. Team members install Claude Code and log in with their Claude.ai accounts

28### Claude Console authentication

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

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

16 33

171. Use your existing Claude Console account or create a new Claude Console account341. Use your existing Claude Console account or create a new Claude Console account

182. You can add users through either method below:352. You can add users through either method below:

19 * Bulk invite users from within the Console (Console -> Settings -> Members -> Invite)36 * Bulk invite users from within the Console (Console -> Settings -> Members -> Invite)

~~20 * [Set up SSO](https://support.claude.com/en/articles/10280258-setting-up-single-sign-on-on-the-api-console)~~37 * [Set up SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)

213. When inviting users, they need one of the following roles:383. When inviting users, they need one of the following roles:

22 * "Claude Code" role means users can only create Claude Code API keys39 * "Claude Code" role means users can only create Claude Code API keys

23 * "Developer" role means users can create any kind of API key40 * "Developer" role means users can create any kind of API key

244. Each invited user needs to complete these steps:414. Each invited user needs to complete these steps:

25 * Accept the Console invite42 * Accept the Console invite

~~26 * [Check system requirements](/en/docs/claude-code/setup#system-requirements)~~43 * [Check system requirements](/en/setup#system-requirements)

~~27 * [Install Claude Code](/en/docs/claude-code/setup#installation)~~44 * [Install Claude Code](/en/setup#installation)

28 * Login with Console account credentials45 * Login with Console account credentials

29 46

30### Cloud provider authentication47### Cloud provider authentication

31 48

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

33 50

~~341. Follow the [Bedrock docs](/en/docs/claude-code/amazon-bedrock) or [Vertex docs](/en/docs/claude-code/google-vertex-ai)~~511. 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/docs/claude-code/settings).~~522. 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/docs/claude-code/setup#installation)~~533. Users can [install Claude Code](/en/setup#installation)

37 54

38## Access control and permissions55## Access control and permissions

39 56

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

45 62

~~47| :---------------- | :------------------- | :---------------- | :-------------------------------------------- |~~64| :---------------- | :--------------- | :---------------- | :-------------------------------------------- |

~~48| Read-only | File reads, LS, Grep | No | N/A |~~65| Read-only | File reads, Grep | No | N/A |

49| Bash Commands | Shell execution | Yes | Permanently per project directory and command |66| Bash Commands | Shell execution | Yes | Permanently per project directory and command |

50| File Modification | Edit/write files | Yes | Until session end |67| File Modification | Edit/write files | Yes | Until session end |

51 68

53 70

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

55 72

~~56* **Allow** rules will allow Claude Code to use the specified tool without further manual approval.~~73* **Allow** rules let Claude Code use the specified tool without manual approval.

~~57* **Ask** rules will ask the user for confirmation whenever Claude Code tries to use the specified tool. Ask rules take precedence over allow rules.~~74* **Ask** rules prompt for confirmation whenever Claude Code tries to use the specified tool.

~~58* **Deny** rules will prevent Claude Code from using the specified tool. Deny rules take precedence over allow and ask rules.~~75* **Deny** rules prevent Claude Code from using the specified tool.

77Rules are evaluated in order: **deny → ask → allow**. The first matching rule wins, so deny rules always take precedence.

59* **Additional directories** extend Claude's file access to directories beyond the initial working directory.79* **Additional directories** extend Claude's file access to directories beyond the initial working directory.

60* **Default mode** controls Claude's permission behavior when encountering new requests.80* **Default mode** controls Claude's permission behavior when encountering new requests.

61 81

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

63 83

~~64A rule that is just the tool name matches any use of that tool. For example, adding `Bash` to the list of allow rules would allow Claude Code to use the Bash tool without requiring user approval.~~84A rule that is just the tool name matches any use of that tool. For example, adding `Bash` to the allow list allows Claude Code to use the Bash tool without requiring user approval. Note that `Bash(*)` does **not** match all Bash commands. Use `Bash` without parentheses to match all uses.

86<Note>

87 For a quick reference on permission rule syntax including wildcards, see [Permission rule syntax](/en/settings#permission-rule-syntax) in the settings documentation.

88</Note>

65 89

66#### Permission modes90#### Permission modes

67 91

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

69 93

70| Mode | Description |94| Mode | Description |

~~71| :------------------ | :--------------------------------------------------------------------------- |~~95| :------------------ | :------------------------------------------------------------------------------------------------------------------------ |

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

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

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

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

76 101

77#### Working directories102#### Working directories

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

80 105

81* **During startup**: Use `--add-dir <path>` CLI argument106* **During startup**: Use `--add-dir <path>` CLI argument

~~82* **During session**: Use `/add-dir` slash command~~107* **During session**: Use `/add-dir` command

~~83* **Persistent configuration**: Add to `additionalDirectories` in [settings files](/en/docs/claude-code/settings#settings-files)~~108* **Persistent configuration**: Add to `additionalDirectories` in [settings files](/en/settings#settings-files)

84 109

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

86 111

90 115

91**Bash**116**Bash**

92 117

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

119

93* `Bash(npm run build)` Matches the exact Bash command `npm run build`120* `Bash(npm run build)` Matches the exact Bash command `npm run build`

94* `Bash(npm run test:*)` Matches Bash commands starting with `npm run test`121* `Bash(npm run test:*)` Matches Bash commands starting with `npm run test`

~~95* `Bash(curl http://site.com/:*)` Matches curl commands that start with exactly `curl http://site.com/`~~122* `Bash(npm *)` Matches any command starting with `npm ` (e.g., `npm install`, `npm run build`)

123* `Bash(* install)` Matches any command ending with ` install` (e.g., `npm install`, `yarn install`)

124* `Bash(git * main)` Matches commands like `git checkout main`, `git merge main`

125

126The key difference between `:*` and `*`: the `:*` suffix enforces a word boundary, requiring the prefix to be followed by a space or end-of-string. For example, `Bash(ls:*)` matches `ls -la` but not `lsof`. In contrast, `Bash(ls*)` with a bare `*` matches both `ls -la` and `lsof` because `*` has no word boundary constraint.

96 127

97<Tip>128<Tip>

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

101<Warning>132<Warning>

102 Important limitations of Bash permission patterns:133 Important limitations of Bash permission patterns:

103 134

104 1. This tool uses **prefix matches**, not regex or glob patterns135 1. The `:*` wildcard only works at the end of a pattern for prefix matching

105 2. The wildcard `:*` only works at the end of a pattern to match any continuation136 2. The `*` wildcard can appear at any position and matches any sequence of characters

106 3. Patterns like `Bash(curl http://github.com/:*)` can be bypassed in many ways:137 3. Patterns like `Bash(curl http://github.com/:*)` can be bypassed in many ways:

107 * Options before URL: `curl -X GET http://github.com/...` won't match138 * Options before URL: `curl -X GET http://github.com/...` won't match

108 * Different protocol: `curl https://github.com/...` won't match139 * Different protocol: `curl https://github.com/...` won't match

112 143

113 For more reliable URL filtering, consider:144 For more reliable URL filtering, consider:

114 145

115 * Using the WebFetch tool with `WebFetch(domain:github.com)` permission146 * **Restrict Bash network tools**: Use deny rules to block `curl`, `wget`, and similar commands, then use the WebFetch tool with `WebFetch(domain:github.com)` permission for allowed domains

147 * **Use PreToolUse hooks**: Implement a hook that validates URLs in Bash commands and blocks disallowed domains

116 * Instructing Claude Code about your allowed curl patterns via CLAUDE.md148 * Instructing Claude Code about your allowed curl patterns via CLAUDE.md

117 * Using hooks for custom permission validation149

150 Note that using WebFetch alone does not prevent network access. If Bash is allowed, Claude can still use `curl`, `wget`, or other tools to reach any URL.

118</Warning>151</Warning>

119 152

120**Read & Edit**153**Read & Edit**

121 154

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

123 156

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

125 158

146**MCP**179**MCP**

147 180

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

182* `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` server183* `mcp__puppeteer__puppeteer_navigate` Matches the `puppeteer_navigate` tool provided by the `puppeteer` server

150 184

151<Warning>185**Task (Subagents)**

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

153 186

154 To approve all tools from an MCP server:187Use `Task(AgentName)` rules to control which [subagents](/en/sub-agents) Claude can use:

155 188

156 * ✅ Use: `mcp__github` (approves ALL GitHub tools)189* `Task(Explore)` Matches the Explore subagent

157 * ❌ Don't use: `mcp__github__*` (wildcards are not supported)190* `Task(Plan)` Matches the Plan subagent

191* `Task(Verify)` Matches the Verify subagent

158 192

159 To approve specific tools only, list each one:193Add these rules to the `deny` array in your [settings](/en/settings#permission-settings) or use the `--disallowedTools` CLI flag to disable specific agents. For example, to disable the Explore agent:

160 194

161 * ✅ Use: `mcp__github__get_issue`195```json theme={null}

162 * ✅ Use: `mcp__github__list_issues`196{

163</Warning>197 "permissions": {

198 "deny": ["Task(Explore)"]

199 }

200}

201```

164 202

165### Additional permission control with hooks203### Additional permission control with hooks

166 204

167[Claude Code hooks](/en/docs/claude-code/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.205[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~~

169### Enterprise managed policy settings

170 206

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.207### Managed settings

172 208

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

~~174~~

175* macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`

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

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

~~178~~

179These policy files follow the same format as regular [settings files](/en/docs/claude-code/settings#settings-files) but cannot be overridden by user or project settings. This ensures consistent security policies across your organization.

180 210

181### Settings precedence211### Settings precedence

182 212

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

184 214

1851. Enterprise policies2151. Managed settings (`managed-settings.json`)

1862. Command line arguments2162. Command line arguments

1873. Local project settings (`.claude/settings.local.json`)2173. Local project settings (`.claude/settings.local.json`)

1884. Shared project settings (`.claude/settings.json`)2184. Shared project settings (`.claude/settings.json`)

195Claude Code securely manages your authentication credentials:225Claude Code securely manages your authentication credentials:

196 226

197* **Storage location**: On macOS, API keys, OAuth tokens, and other credentials are stored in the encrypted macOS Keychain.227* **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.228* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.

199* **Custom credential scripts**: The [`apiKeyHelper`](/en/docs/claude-code/settings#available-settings) setting can be configured to run a shell script that returns an API key.229* **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.230* **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.

231

232

233---

234

235> 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 +121 −16

Details

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.

10 **macOS users**: Option/Alt key shortcuts (`Alt+B`, `Alt+F`, `Alt+Y`, `Alt+M`, `Alt+P`) require configuring Option as Meta in your terminal:

12 * **iTerm2**: Settings → Profiles → Keys → Set Left/Right Option key to "Esc+"

13 * **Terminal.app**: Settings → Profiles → Keyboard → Check "Use Option as Meta Key"

14 * **VS Code**: Settings → Profiles → Keys → Set Left/Right Option key to "Esc+"

16 See [Terminal configuration](/en/terminal-config) for details.

9</Note>17</Note>

10 18

11### General controls19### General controls

12 20

~~14| :------------------------------------------- | :----------------------------------------------------------------------- | :---------------------------------------------------------- |~~22| :------------------------------------------------ | :--------------------------------- | :-------------------------------------------------------------------------------------------- |

25| `Ctrl+G` | Open in default text editor | Edit your prompt or custom response in your default text editor |

30| `Ctrl+B` | Background running tasks | Backgrounds bash commands and agents. Tmux users press twice |

31| `Left/Right arrows` | Cycle through dialog tabs | Navigate between tabs in permission dialogs and menus |

~~23| `Tab` | Toggle [extended thinking](/en/docs/build-with-claude/extended-thinking) | Switch between Thinking on and Thinking off |~~

35| `Option+P` (macOS) or `Alt+P` (Windows/Linux) | Switch model | Switch models without clearing your prompt |

36| `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle extended thinking | Enable or disable extended thinking mode. Run `/terminal-setup` first to enable this shortcut |

38### Text editing

40| Shortcut | Description | Context |

41| :----------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------ |

42| `Ctrl+K` | Delete to end of line | Stores deleted text for pasting |

43| `Ctrl+U` | Delete entire line | Stores deleted text for pasting |

44| `Ctrl+Y` | Paste deleted text | Paste text deleted with `Ctrl+K` or `Ctrl+U` |

45| `Alt+Y` (after `Ctrl+Y`) | Cycle paste history | After pasting, cycle through previously deleted text. Requires [Option as Meta](#keyboard-shortcuts) on macOS |

46| `Alt+B` | Move cursor back one word | Word navigation. Requires [Option as Meta](#keyboard-shortcuts) on macOS |

47| `Alt+F` | Move cursor forward one word | Word navigation. Requires [Option as Meta](#keyboard-shortcuts) on macOS |

49### Theme and display

51| Shortcut | Description | Context |

52| :------- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------- |

53| `Ctrl+T` | Toggle syntax highlighting for code blocks | Only works inside the `/theme` picker menu. Controls whether code in Claude's responses uses syntax coloring |

55<Note>

56 Syntax highlighting is only available in the native build of Claude Code.

57</Note>

25 58

26### Multiline input59### Multiline input

27 60

~~29| :--------------- | :------------- | :-------------------------------- |~~62| :--------------- | :------------- | :------------------------------------------------------ |

35 68

36<Tip>69<Tip>

~~37 Configure your preferred line break behavior in terminal settings. Run `/terminal-setup` to install Shift+Enter binding for iTerm2 and VS Code terminals.~~70 Shift+Enter works without configuration in iTerm2, WezTerm, Ghostty, and Kitty. For other terminals (VS Code, Alacritty, Zed, Warp), run `/terminal-setup` to install the binding.

38</Tip>71</Tip>

39 72

40### Quick commands73### Quick commands

41 74

~~43| :----------- | :--------------------------------- | :------------------------------------------------------------ |~~76| :----------- | :---------------- | :------------------------------------------------------------------- |

~~45| `/` at start | Slash command | See [slash commands](/en/docs/claude-code/slash-commands) |~~

47| `@` | File path mention | Trigger file path autocomplete |79| `@` | File path mention | Trigger file path autocomplete |

48 80

81## Built-in commands

83Built-in commands are shortcuts for common actions. The table below covers commonly used commands but not all available options. Type `/` in Claude Code to see the full list, or type `/` followed by any letters to filter.

85To create your own commands you can invoke with `/`, see [skills](/en/skills).

87| Command | Purpose |

88| :------------------------ | :-------------------------------------------------------------------------------------------------------------------------- |

89| `/clear` | Clear conversation history |

90| `/compact [instructions]` | Compact conversation with optional focus instructions |

91| `/config` | Open the Settings interface (Config tab) |

92| `/context` | Visualize current context usage as a colored grid |

93| `/cost` | Show token usage statistics. See [cost tracking guide](/en/costs#using-the-cost-command) for subscription-specific details. |

94| `/doctor` | Checks the health of your Claude Code installation |

95| `/exit` | Exit the REPL |

96| `/export [filename]` | Export the current conversation to a file or clipboard |

97| `/help` | Get usage help |

98| `/init` | Initialize project with `CLAUDE.md` guide |

99| `/mcp` | Manage MCP server connections and OAuth authentication |

100| `/memory` | Edit `CLAUDE.md` memory files |

101| `/model` | Select or change the AI model |

102| `/permissions` | View or update [permissions](/en/iam#configuring-permissions) |

103| `/plan` | Enter plan mode directly from the prompt |

104| `/rename <name>` | Rename the current session for easier identification |

105| `/resume [session]` | Resume a conversation by ID or name, or open the session picker |

106| `/rewind` | Rewind the conversation and/or code |

107| `/stats` | Visualize daily usage, session history, streaks, and model preferences |

108| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |

109| `/statusline` | Set up Claude Code's status line UI |

110| `/tasks` | List and manage background tasks |

111| `/teleport` | Resume a remote session from claude.ai (subscribers only) |

112| `/theme` | Change the color theme |

113| `/todos` | List current TODO items |

114| `/usage` | For subscription plans only: show plan usage limits and rate limit status |

115

116### MCP prompts

117

118MCP servers can expose prompts that appear as commands. These use the format `/mcp__<server>__<prompt>` and are dynamically discovered from connected servers. See [MCP prompts](/en/mcp#use-mcp-prompts-as-commands) for details.

119

49## Vim editor mode120## Vim editor mode

50 121

51Enable vim-style editing with `/vim` command or configure permanently via `/config`.122Enable vim-style editing with `/vim` command or configure permanently via `/config`.

65### Navigation (NORMAL mode)136### Navigation (NORMAL mode)

66 137

67| Command | Action |138| Command | Action |

~~68| :-------------- | :------------------------ |~~139| :-------------- | :-------------------------------------------------- |

70| `w` | Next word |141| `w` | Next word |

71| `e` | End of word |142| `e` | End of word |

75| `^` | First non-blank character |146| `^` | First non-blank character |

76| `gg` | Beginning of input |147| `gg` | Beginning of input |

77| `G` | End of input |148| `G` | End of input |

149| `f{char}` | Jump to next occurrence of character |

150| `F{char}` | Jump to previous occurrence of character |

151| `t{char}` | Jump to just before next occurrence of character |

152| `T{char}` | Jump to just after previous occurrence of character |

153| `;` | Repeat last f/F/t/T motion |

154| `,` | Repeat last f/F/t/T motion in reverse |

78 155

79### Editing (NORMAL mode)156### Editing (NORMAL mode)

80 157

87| `cc` | Change line |164| `cc` | Change line |

88| `C` | Change to end of line |165| `C` | Change to end of line |

167| `yy`/`Y` | Yank (copy) line |

168| `yw`/`ye`/`yb` | Yank word/to end/back |

169| `p` | Paste after cursor |

170| `P` | Paste before cursor |

171| `>>` | Indent line |

172| `<<` | Dedent line |

173| `J` | Join lines |

90| `.` | Repeat last change |174| `.` | Repeat last change |

91 175

176### Text objects (NORMAL mode)

177

178Text objects work with operators like `d`, `c`, and `y`:

179

180| Command | Action |

181| :-------- | :--------------------------------------- |

182| `iw`/`aw` | Inner/around word |

183| `iW`/`aW` | Inner/around WORD (whitespace-delimited) |

184| `i"`/`a"` | Inner/around double quotes |

185| `i'`/`a'` | Inner/around single quotes |

186| `i(`/`a(` | Inner/around parentheses |

187| `i[`/`a[` | Inner/around brackets |

188| `i{`/`a{` | Inner/around braces |

189

92## Command history190## Command history

93 191

94Claude Code maintains command history for the current session:192Claude Code maintains command history for the current session:

129 227

130**Key features:**228**Key features:**

131 229

132* Output is buffered and Claude can retrieve it using the BashOutput tool230* Output is buffered and Claude can retrieve it using the TaskOutput tool

133* Background tasks have unique IDs for tracking and output retrieval231* Background tasks have unique IDs for tracking and output retrieval

134* Background tasks are automatically cleaned up when Claude Code exits232* Background tasks are automatically cleaned up when Claude Code exits

135 233

234To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/en/settings#environment-variables) for details.

235

136**Common backgrounded commands:**236**Common backgrounded commands:**

137 237

138* Build tools (webpack, vite, make)238* Build tools (webpack, vite, make)

162 262

163## See also263## See also

164 264

165* [Slash commands](/en/docs/claude-code/slash-commands) - Interactive session commands265* [Skills](/en/skills) - Custom prompts and workflows

166* [Checkpointing](/en/docs/claude-code/checkpointing) - Rewind Claude's edits and restore previous states266* [Checkpointing](/en/checkpointing) - Rewind Claude's edits and restore previous states

167* [CLI reference](/en/docs/claude-code/cli-reference) - Command-line flags and options267* [CLI reference](/en/cli-reference) - Command-line flags and options

168* [Settings](/en/docs/claude-code/settings) - Configuration options268* [Settings](/en/settings) - Configuration options

169* [Memory management](/en/docs/claude-code/memory) - Managing CLAUDE.md files269* [Memory management](/en/memory) - Managing CLAUDE.md files

270

271

272---

273

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

jetbrains.md +12 −9

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)

104### WSL Configuration102### WSL Configuration

105 103

106<Warning>104<Warning>

107 WSL users may need additional configuration for IDE detection to work properly. See our [WSL troubleshooting guide](/en/docs/claude-code/troubleshooting#jetbrains-ide-not-detected-on-wsl2) for detailed setup instructions.105 WSL users may need additional configuration for IDE detection to work properly. See our [WSL troubleshooting guide](/en/troubleshooting#jetbrains-ide-not-detected-on-wsl2) for detailed setup instructions.

108</Warning>106</Warning>

109 107

110WSL configuration may require:108WSL configuration may require:

127* Verify the plugin is installed and enabled125* Verify the plugin is installed and enabled

128* Restart the IDE completely126* Restart the IDE completely

129* Check that you're running Claude Code from the integrated terminal127* Check that you're running Claude Code from the integrated terminal

130* For WSL users, see the [WSL troubleshooting guide](/en/docs/claude-code/troubleshooting#jetbrains-ide-not-detected-on-wsl2)128* For WSL users, see the [WSL troubleshooting guide](/en/troubleshooting#jetbrains-ide-not-detected-on-wsl2)

131 129

132### Command Not Found130### Command Not Found

133 131

147* Taking extra care to ensure Claude is only used with trusted prompts145* Taking extra care to ensure Claude is only used with trusted prompts

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/docs/claude-code/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 +41 −11

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/docs/claude-code/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

141 166

142* [LiteLLM documentation](https://docs.litellm.ai/)167* [LiteLLM documentation](https://docs.litellm.ai/)

143* [Claude Code settings](/en/docs/claude-code/settings)168* [Claude Code settings](/en/settings)

144* [Enterprise network configuration](/en/docs/claude-code/network-config)169* [Enterprise network configuration](/en/network-config)

145* [Third-party integrations overview](/en/docs/claude-code/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 +288 −42

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

77 77

78```bash theme={null}78```bash theme={null}

79# Basic syntax79# Basic syntax

~~80claude mcp add --transport stdio <name> <command> [args...]~~80claude mcp add [options] <name> -- <command> [args...]

81 81

82# Real example: Add Airtable server82# Real example: Add Airtable server

~~83claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=YOUR_KEY \~~83claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \

84 -- npx -y airtable-mcp-server84 -- npx -y airtable-mcp-server

85```85```

86 86

87<Note>87<Note>

~~88 **Understanding the "--" parameter:**~~88 **Important: Option ordering**

89 The `--` (double dash) separates Claude's own CLI flags from the command and arguments that get passed to the MCP server. Everything before `--` are options for Claude (like `--env`, `--scope`), and everything after `--` is the actual command to run the MCP server.89

90 All options (`--transport`, `--env`, `--scope`, `--header`) must come **before** the server name. The `--` (double dash) then separates the server name from the command and arguments that get passed to the MCP server.

90 91

91 For example:92 For example:

92 93

93 * `claude mcp add --transport stdio myserver -- npx server` → runs `npx server`94 * `claude mcp add --transport stdio myserver -- npx server` → runs `npx server`

~~94 * `claude mcp add --transport stdio myserver --env KEY=value -- python server.py --port 8080` → runs `python server.py --port 8080` with `KEY=value` in environment~~95 * `claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080` → runs `python server.py --port 8080` with `KEY=value` in environment

95 96

96 This prevents conflicts between Claude's flags and the server's flags.97 This prevents conflicts between Claude's flags and the server's flags.

97</Note>98</Note>

114/mcp115/mcp

115```116```

116 117

118### Dynamic tool updates

119

120Claude Code supports MCP `list_changed` notifications, allowing MCP servers to dynamically update their available tools, prompts, and resources without requiring you to disconnect and reconnect. When an MCP server sends a `list_changed` notification, Claude Code automatically refreshes the available capabilities from that server.

121

117<Tip>122<Tip>

118 Tips:123 Tips:

119 124

121 * `local` (default): Available only to you in the current project (was called `project` in older versions)126 * `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` file127 * `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)128 * `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`)129 * 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)130 * 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`)131 * 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 authentication132 * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication

128</Tip>133</Tip>

129 134

140 145

141### Plugin-provided MCP servers146### Plugin-provided MCP servers

142 147

143[Plugins](/en/docs/claude-code/plugins) can bundle MCP servers, automatically providing tools and integrations when the plugin is enabled. Plugin MCP servers work identically to user-configured servers.148[Plugins](/en/plugins) can bundle MCP servers, automatically providing tools and integrations when the plugin is enabled. Plugin MCP servers work identically to user-configured servers.

144 149

145**How plugin MCP servers work**:150**How plugin MCP servers work**:

146 151

201* **Automatic setup**: No manual MCP configuration needed206* **Automatic setup**: No manual MCP configuration needed

202* **Team consistency**: Everyone gets the same tools when plugin is installed207* **Team consistency**: Everyone gets the same tools when plugin is installed

203 208

204See the [plugin components reference](/en/docs/claude-code/plugins-reference#mcp-servers) for details on bundling MCP servers with plugins.209See the [plugin components reference](/en/plugins-reference#mcp-servers) for details on bundling MCP servers with plugins.

205 210

206## MCP installation scopes211## MCP installation scopes

207 212

209 214

210### Local scope215### Local scope

211 216

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.217Local-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 218

214```bash theme={null}219```bash theme={null}

215# Add a local-scoped server (default)220# Add a local-scoped server (default)

246 251

247### User scope252### User scope

248 253

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.254User-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 255

251```bash theme={null}256```bash theme={null}

252# Add a user server257# Add a user server

259 264

260* **Local scope**: Personal servers, experimental configurations, or sensitive credentials specific to one project265* **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 collaboration266* **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 services267* **User scope**: Personal utilities needed across multiple projects, development tools, or frequently used services

268

269<Note>

270 **Where are MCP servers stored?**

271

272 * **User and local scope**: `~/.claude.json` (in the `mcpServers` field or under project paths)

273 * **Project scope**: `.mcp.json` in your project root (checked into source control)

274 * **Managed**: `managed-mcp.json` in system directories (see [Managed MCP configuration](#managed-mcp-configuration))

275</Note>

263 276

264### Scope hierarchy and precedence277### Scope hierarchy and precedence

265 278

455 * It reads the Claude Desktop configuration file from its standard location on those platforms468 * 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 configuration469 * Use the `--scope user` flag to add servers to your user configuration

457 * Imported servers will have the same names as in Claude Desktop470 * 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`)471 * If servers with the same names already exist, they will get a numerical suffix (for example, `server_1`)

459</Tip>472</Tip>

460 473

461## Use Claude Code as an MCP server474## Use Claude Code as an MCP server

482}495}

483```496```

484 497

498<Warning>

499 **Configuring the executable path**: The `command` field must reference the Claude Code executable. If the `claude` command is not in your system's PATH, you'll need to specify the full path to the executable.

500

501 To find the full path:

502

503 ```bash theme={null}

504 which claude

505 ```

506

507 Then use the full path in your configuration:

508

509 ```json theme={null}

510 {

511 "mcpServers": {

512 "claude-code": {

513 "type": "stdio",

514 "command": "/full/path/to/claude",

515 "args": ["mcp", "serve"],

516 "env": {}

517 }

518 }

519 }

520 ```

521

522 Without the correct executable path, you'll encounter errors like `spawn claude ENOENT`.

523</Warning>

524

485<Tip>525<Tip>

486 Tips:526 Tips:

487 527

488 * The server provides access to Claude's tools like View, Edit, LS, etc.528 * The server provides access to Claude's tools like View, Edit, LS, etc.

489 * In Claude Desktop, try asking Claude to read files in a directory, make edits, and more.529 * In Claude Desktop, try asking Claude to read files in a directory, make edits, and more.

490 * 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.530 * 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.

491</Tip>531</Tip>

492 532

493## MCP output limits and warnings533## MCP output limits and warnings

557 * Resources can contain any type of content that the MCP server provides (text, JSON, structured data, etc.)597 * Resources can contain any type of content that the MCP server provides (text, JSON, structured data, etc.)

558</Tip>598</Tip>

559 599

560## Use MCP prompts as slash commands600## Scale with MCP Tool Search

601

602When you have many MCP servers configured, tool definitions can consume a significant portion of your context window. MCP Tool Search solves this by dynamically loading tools on-demand instead of preloading all of them.

603

604### How it works

605

606Claude Code automatically enables Tool Search when your MCP tool descriptions would consume more than 10% of the context window. You can [adjust this threshold](#configure-tool-search) or disable tool search entirely. When triggered:

561 607

562MCP servers can expose prompts that become available as slash commands in Claude Code.6081. MCP tools are deferred rather than loaded into context upfront

6092. Claude uses a search tool to discover relevant MCP tools when needed

6103. Only the tools Claude actually needs are loaded into context

6114. MCP tools continue to work exactly as before from your perspective

612

613### For MCP server authors

614

615If you're building an MCP server, the server instructions field becomes more useful with Tool Search enabled. Server instructions help Claude understand when to search for your tools, similar to how [skills](/en/skills) work.

616

617Add clear, descriptive server instructions that explain:

618

619* What category of tasks your tools handle

620* When Claude should search for your tools

621* Key capabilities your server provides

622

623### Configure tool search

624

625Tool search runs in auto mode by default, meaning it activates only when your MCP tool definitions exceed the context threshold. If you have few tools, they load normally without tool search. This feature requires models that support `tool_reference` blocks: Sonnet 4 and later, or Opus 4 and later. Haiku models do not support tool search.

626

627Control tool search behavior with the `ENABLE_TOOL_SEARCH` environment variable:

628

629| Value | Behavior |

630| :--------- | :--------------------------------------------------------------------------------- |

631| `auto` | Activates when MCP tools exceed 10% of context (default) |

632| `auto:<N>` | Activates at custom threshold, where `<N>` is a percentage (e.g., `auto:5` for 5%) |

633| `true` | Always enabled |

634| `false` | Disabled, all MCP tools loaded upfront |

635

636```bash theme={null}

637# Use a custom 5% threshold

638ENABLE_TOOL_SEARCH=auto:5 claude

639

640# Disable tool search entirely

641ENABLE_TOOL_SEARCH=false claude

642```

643

644Or set the value in your [settings.json `env` field](/en/settings#available-settings).

645

646You can also disable the MCPSearch tool specifically using the `disallowedTools` setting:

647

648```json theme={null}

649{

650 "permissions": {

651 "deny": ["MCPSearch"]

652 }

653}

654```

655

656## Use MCP prompts as commands

657

658MCP servers can expose prompts that become available as commands in Claude Code.

563 659

564### Execute MCP prompts660### Execute MCP prompts

565 661

596 * Server and prompt names are normalized (spaces become underscores)692 * Server and prompt names are normalized (spaces become underscores)

597</Tip>693</Tip>

598 694

599## Enterprise MCP configuration695## Managed MCP configuration

696

697For organizations that need centralized control over MCP servers, Claude Code supports two configuration options:

600 698

601For organizations that need centralized control over MCP servers, Claude Code supports enterprise-managed MCP configurations. This allows IT administrators to:6991. **Exclusive control with `managed-mcp.json`**: Deploy a fixed set of MCP servers that users cannot modify or extend

7002. **Policy-based control with allowlists/denylists**: Allow users to add their own servers, but restrict which ones are permitted

701

702These options allow IT administrators to:

602 703

603* **Control which MCP servers employees can access**: Deploy a standardized set of approved MCP servers across the organization704* **Control which MCP servers employees can access**: Deploy a standardized set of approved MCP servers across the organization

604* **Prevent unauthorized MCP servers**: Optionally restrict users from adding their own MCP servers705* **Prevent unauthorized MCP servers**: Restrict users from adding unapproved MCP servers

605* **Disable MCP entirely**: Remove MCP functionality completely if needed706* **Disable MCP entirely**: Remove MCP functionality completely if needed

606 707

607### Setting up enterprise MCP configuration708### Option 1: Exclusive control with managed-mcp.json

709

710When 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.

608 711

609System administrators can deploy an enterprise MCP configuration file alongside the managed settings file:712System administrators deploy the configuration file to a system-wide directory:

610 713

611* **macOS**: `/Library/Application Support/ClaudeCode/managed-mcp.json`714* macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`

612* **Windows**: `C:\ProgramData\ClaudeCode\managed-mcp.json`715* Linux and WSL: `/etc/claude-code/managed-mcp.json`

613* **Linux**: `/etc/claude-code/managed-mcp.json`716* Windows: `C:\Program Files\ClaudeCode\managed-mcp.json`

717

718<Note>

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

720</Note>

614 721

615The `managed-mcp.json` file uses the same format as a standard `.mcp.json` file:722The `managed-mcp.json` file uses the same format as a standard `.mcp.json` file:

616 723

637}744}

638```745```

639 746

640### Restricting MCP servers with allowlists and denylists747### Option 2: Policy-based control with allowlists and denylists

641 748

642In 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:749Instead 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).

643 750

644* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`751<Note>

645* **Windows**: `C:\ProgramData\ClaudeCode\managed-settings.json`752 **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.

646* **Linux**: `/etc/claude-code/managed-settings.json`753</Note>

754

755#### Restriction options

756

757Each entry in the allowlist or denylist can restrict servers in three ways:

758

7591. **By server name** (`serverName`): Matches the configured name of the server

7602. **By command** (`serverCommand`): Matches the exact command and arguments used to start stdio servers

7613. **By URL pattern** (`serverUrl`): Matches remote server URLs with wildcard support

762

763**Important**: Each entry must have exactly one of `serverName`, `serverCommand`, or `serverUrl`.

764

765#### Example configuration

647 766

648```json theme={null}767```json theme={null}

649{768{

650 "allowedMcpServers": [769 "allowedMcpServers": [

770 // Allow by server name

651 { "serverName": "github" },771 { "serverName": "github" },

652 { "serverName": "sentry" },772 { "serverName": "sentry" },

653 { "serverName": "company-internal" }773

774 // Allow by exact command (for stdio servers)

775 { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },

776 { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

777

778 // Allow by URL pattern (for remote servers)

779 { "serverUrl": "https://mcp.company.com/*" },

780 { "serverUrl": "https://*.internal.corp/*" }

654 ],781 ],

655 "deniedMcpServers": [782 "deniedMcpServers": [

656 { "serverName": "filesystem" }783 // Block by server name

784 { "serverName": "dangerous-server" },

785

786 // Block by exact command (for stdio servers)

787 { "serverCommand": ["npx", "-y", "unapproved-package"] },

788

789 // Block by URL pattern (for remote servers)

790 { "serverUrl": "https://*.untrusted.com/*" }

657 ]791 ]

658}792}

659```793```

660 794

661**Allowlist behavior (`allowedMcpServers`)**:795#### How command-based restrictions work

796

797**Exact matching**:

798

799* Command arrays must match **exactly** - both the command and all arguments in the correct order

800* Example: `["npx", "-y", "server"]` will NOT match `["npx", "server"]` or `["npx", "-y", "server", "--flag"]`

801

802**Stdio server behavior**:

803

804* When the allowlist contains **any** `serverCommand` entries, stdio servers **must** match one of those commands

805* Stdio servers cannot pass by name alone when command restrictions are present

806* This ensures administrators can enforce which commands are allowed to run

807

808**Non-stdio server behavior**:

809

810* Remote servers (HTTP, SSE, WebSocket) use URL-based matching when `serverUrl` entries exist in the allowlist

811* If no URL entries exist, remote servers fall back to name-based matching

812* Command restrictions do not apply to remote servers

813

814#### How URL-based restrictions work

815

816URL patterns support wildcards using `*` to match any sequence of characters. This is useful for allowing entire domains or subdomains.

817

818**Wildcard examples**:

819

820* `https://mcp.company.com/*` - Allow all paths on a specific domain

821* `https://*.example.com/*` - Allow any subdomain of example.com

822* `http://localhost:*/*` - Allow any port on localhost

823

824**Remote server behavior**:

825

826* When the allowlist contains **any** `serverUrl` entries, remote servers **must** match one of those URL patterns

827* Remote servers cannot pass by name alone when URL restrictions are present

828* This ensures administrators can enforce which remote endpoints are allowed

829

830<Accordion title="Example: URL-only allowlist">

831 ```json theme={null}

832 {

833 "allowedMcpServers": [

834 { "serverUrl": "https://mcp.company.com/*" },

835 { "serverUrl": "https://*.internal.corp/*" }

836 ]

837 }

838 ```

839

840 **Result**:

841

842 * HTTP server at `https://mcp.company.com/api`: ✅ Allowed (matches URL pattern)

843 * HTTP server at `https://api.internal.corp/mcp`: ✅ Allowed (matches wildcard subdomain)

844 * HTTP server at `https://external.com/mcp`: ❌ Blocked (doesn't match any URL pattern)

845 * Stdio server with any command: ❌ Blocked (no name or command entries to match)

846</Accordion>

847

848<Accordion title="Example: Command-only allowlist">

849 ```json theme={null}

850 {

851 "allowedMcpServers": [

852 { "serverCommand": ["npx", "-y", "approved-package"] }

853 ]

854 }

855 ```

856

857 **Result**:

858

859 * Stdio server with `["npx", "-y", "approved-package"]`: ✅ Allowed (matches command)

860 * Stdio server with `["node", "server.js"]`: ❌ Blocked (doesn't match command)

861 * HTTP server named "my-api": ❌ Blocked (no name entries to match)

862</Accordion>

863

864<Accordion title="Example: Mixed name and command allowlist">

865 ```json theme={null}

866 {

867 "allowedMcpServers": [

868 { "serverName": "github" },

869 { "serverCommand": ["npx", "-y", "approved-package"] }

870 ]

871 }

872 ```

873

874 **Result**:

875

876 * Stdio server named "local-tool" with `["npx", "-y", "approved-package"]`: ✅ Allowed (matches command)

877 * Stdio server named "local-tool" with `["node", "server.js"]`: ❌ Blocked (command entries exist but doesn't match)

878 * Stdio server named "github" with `["node", "server.js"]`: ❌ Blocked (stdio servers must match commands when command entries exist)

879 * HTTP server named "github": ✅ Allowed (matches name)

880 * HTTP server named "other-api": ❌ Blocked (name doesn't match)

881</Accordion>

882

883<Accordion title="Example: Name-only allowlist">

884 ```json theme={null}

885 {

886 "allowedMcpServers": [

887 { "serverName": "github" },

888 { "serverName": "internal-tool" }

889 ]

890 }

891 ```

892

893 **Result**:

894

895 * Stdio server named "github" with any command: ✅ Allowed (no command restrictions)

896 * Stdio server named "internal-tool" with any command: ✅ Allowed (no command restrictions)

897 * HTTP server named "github": ✅ Allowed (matches name)

898 * Any server named "other": ❌ Blocked (name doesn't match)

899</Accordion>

900

901#### Allowlist behavior (`allowedMcpServers`)

662 902

663* `undefined` (default): No restrictions - users can configure any MCP server903* `undefined` (default): No restrictions - users can configure any MCP server

664* Empty array `[]`: Complete lockdown - users cannot configure any MCP servers904* Empty array `[]`: Complete lockdown - users cannot configure any MCP servers

665* List of server names: Users can only configure the specified servers905* List of entries: Users can only configure servers that match by name, command, or URL pattern

666 906

667**Denylist behavior (`deniedMcpServers`)**:907#### Denylist behavior (`deniedMcpServers`)

668 908

669* `undefined` (default): No servers are blocked909* `undefined` (default): No servers are blocked

670* Empty array `[]`: No servers are blocked910* Empty array `[]`: No servers are blocked

671* List of server names: Specified servers are explicitly blocked across all scopes911* List of entries: Specified servers are explicitly blocked across all scopes

672 912

673**Important notes**:913#### Important notes

674 914

675* These restrictions apply to all scopes: user, project, local, and even enterprise servers from `managed-mcp.json`915* **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 managed servers themselves.

676* **Denylist takes absolute precedence**: If a server appears in both lists, it will be blocked916* **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

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

677 918

678<Note>919<Note>

679 **Enterprise configuration precedence**: The enterprise MCP configuration has the highest precedence and cannot be overridden by user, local, or project configurations when `useEnterpriseMcpConfigOnly` is enabled.920 **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 managed servers are actually loaded.

680</Note>921</Note>

922

923

924---

925

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

memory.md +144 −21

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| **Managed 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` command during a session to open any memory file in your system editor for more extensive additions or organization.

65 60

66## Set up project memory61## Set up project memory

67 62

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:

107 - "src/api/**/*.ts"

108---

109

110# API Development Rules

111

112- All API endpoints must include input validation

113- Use the standard error response format

114- Include OpenAPI documentation comments

115```

116

117Rules without a `paths` field are loaded unconditionally and apply to all files.

118

119### Glob patterns

120

121The `paths` field supports standard glob patterns:

122

123| Pattern | Matches |

124| ---------------------- | ---------------------------------------- |

125| `**/*.ts` | All TypeScript files in any directory |

126| `src/**/*` | All files under `src/` directory |

127| `*.md` | Markdown files in the project root |

128| `src/components/*.tsx` | React components in a specific directory |

129

130You can specify multiple patterns:

131

132```markdown theme={null}

133---

134paths:

135 - "src/**/*.ts"

136 - "lib/**/*.ts"

137 - "tests/**/*.test.ts"

138---

139```

140

141Brace expansion is supported for matching multiple extensions or directories:

142

143```markdown theme={null}

144---

145paths:

146 - "src/**/*.{ts,tsx}"

147 - "{src,lib}/**/*.ts"

148---

149

150# TypeScript/React Rules

151```

152

153This expands `src/**/*.{ts,tsx}` to match both `.ts` and `.tsx` files.

154

155### Subdirectories

156

157Rules can be organized into subdirectories for better structure:

158

159```

160.claude/rules/

161├── frontend/

162│ ├── react.md

163│ └── styles.md

164├── backend/

165│ ├── api.md

166│ └── database.md

167└── general.md

168```

169

170All `.md` files are discovered recursively.

171

172### Symlinks

173

174The `.claude/rules/` directory supports symlinks, allowing you to share common rules across multiple projects:

175

176```bash theme={null}

177# Symlink a shared rules directory

178ln -s ~/shared-claude-rules .claude/rules/shared

179

180# Symlink individual rule files

181ln -s ~/company-standards/security.md .claude/rules/security.md

182```

183

184Symlinks are resolved and their contents are loaded normally. Circular symlinks are detected and handled gracefully.

185

186### User-level rules

187

188You can create personal rules that apply to all your projects in `~/.claude/rules/`:

189

190```

191~/.claude/rules/

192├── preferences.md # Your personal coding preferences

193└── workflows.md # Your preferred workflows

194```

195

196User-level rules are loaded before project rules, giving project rules higher priority.

197

198<Tip>

199 Best practices for `.claude/rules/`:

200

201 * **Keep rules focused**: Each file should cover one topic (e.g., `testing.md`, `api-design.md`)

202 * **Use descriptive filenames**: The filename should indicate what the rules cover

203 * **Use conditional rules sparingly**: Only add `paths` frontmatter when rules truly apply to specific file types

204 * **Organize with subdirectories**: Group related rules (e.g., `frontend/`, `backend/`)

205</Tip>

206

85## Organization-level memory management207## Organization-level memory management

86 208

~~87Enterprise organizations can deploy centrally managed CLAUDE.md files that apply to all users.~~209Organizations can deploy centrally managed CLAUDE.md files that apply to all users.

88 210

89To set up organization-level memory management:211To set up organization-level memory management:

90 212

~~911. Create the enterprise memory file in the appropriate location for your operating system:~~2131. Create the managed memory file at the **Managed 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 214

972. Deploy via your configuration management system (MDM, Group Policy, Ansible, etc.) to ensure consistent distribution across all developer machines.2152. Deploy via your configuration management system (MDM, Group Policy, Ansible, etc.) to ensure consistent distribution across all developer machines.

98 216

101* **Be specific**: "Use 2-space indentation" is better than "Format code properly".219* **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.220* **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.221* **Review periodically**: Update memories as your project evolves to ensure Claude is always using the most up to date information and context.

222

223

224---

225

226> 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 +24 −16

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

95You can see which model you're currently using in several ways:98You can see which model you're currently using in several ways:

96 99

~~971. In [status line](/en/docs/claude-code/statusline) (if configured)~~1001. In [status line](/en/statusline) (if configured)

982. In `/status`, which also displays your account information.1012. In `/status`, which also displays your account information.

99 102

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

109| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | The model to use for `haiku`, or [background functionality](/en/docs/claude-code/costs#background-token-usage) |112| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | The model to use for `haiku`, or [background functionality](/en/costs#background-token-usage) |

111 114

112Note: `ANTHROPIC_SMALL_FAST_MODEL` is deprecated in favor of115Note: `ANTHROPIC_SMALL_FAST_MODEL` is deprecated in favor of

113`ANTHROPIC_DEFAULT_HAIKU_MODEL`.116`ANTHROPIC_DEFAULT_HAIKU_MODEL`.

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/docs/claude-code/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 +9 −4

Details

5Claude Code supports various enterprise network and security configurations through environment variables. This includes routing traffic through corporate proxy servers, trusting custom Certificate Authorities (CA), and authenticating with mutual Transport Layer Security (mTLS) certificates for enhanced security.5Claude Code supports various enterprise network and security configurations through environment variables. This includes routing traffic through corporate proxy servers, trusting custom Certificate Authorities (CA), and authenticating with mutual Transport Layer Security (mTLS) certificates for enhanced security.

6 6

7<Note>7<Note>

~~8 All environment variables shown on this page can also be configured in [`settings.json`](/en/docs/claude-code/settings).~~8 All environment variables shown on this page can also be configured in [`settings.json`](/en/settings).

9</Note>9</Note>

10 10

11## Proxy configuration11## Proxy configuration

85 85

86## Additional resources86## Additional resources

87 87

~~88* [Claude Code settings](/en/docs/claude-code/settings)~~88* [Claude Code settings](/en/settings)

~~89* [Environment variables reference](/en/docs/claude-code/settings#environment-variables)~~89* [Environment variables reference](/en/settings#environment-variables)

~~90* [Troubleshooting guide](/en/docs/claude-code/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 +63 −134

Details

1# Output styles1# Output styles

2 2

~~3> [DEPRECATED] Adapt Claude Code for uses beyond software engineering~~3> Adapt Claude Code for uses beyond software engineering

~~5<Warning>~~

~~6 Output styles are **DEPRECATED.** On **November 5, 2025** or later, we'll~~

~~7 automatically convert your **user-level** output style files to plugins and~~

~~8 stop supporting the output styles feature. Use~~

~~9 [plugins](/en/docs/claude-code/plugins) instead. ([example~~

~~10 plugin](https://github.com/anthropics/claude-code/tree/main/plugins/explanatory-output-style)~~

~~11 for the built-in Explanatory output style)~~

~~12</Warning>~~

~~14## Deprecation timeline~~

~~16As of **November 5, 2025**, Claude Code will:~~

~~18* Automatically convert user-level output style files~~

~~19 (`~/.claude/output-styles`) to plugins~~

~~20* Stop supporting the output styles feature~~

~~21* Remove the `/output-style` command and related functionality~~

~~23**What you need to do:**~~

~~25* Migrate to plugins before November 5, 2025 for a smoother transition~~

~~26* Review the migration guide below to understand your options~~

~~28## Alternative: Use plugins instead~~

~~30Plugins provide more powerful and flexible ways to customize Claude Code's~~

~~31behavior. The~~

~~32[`explanatory-output-style` plugin](https://github.com/anthropics/claude-code/tree/main/plugins/explanatory-output-style)~~

~~33recreates the deprecated Explanatory output style functionality.~~

~~35### Example: Explanatory Output Style Plugin~~

~~37The `explanatory-output-style` plugin uses a SessionStart hook to inject~~

~~38additional context that encourages Claude to provide educational insights.~~

~~39Here's what it does:~~

~~41* Provides educational insights about implementation choices~~

~~42* Explains codebase patterns and decisions~~

~~43* Balances task completion with learning opportunities~~

~~45### Installing a plugin~~

~~47To install a plugin like `explanatory-output-style`:~~

~~49```shell Add the marketplace (if not already added) theme={null}~~

~~50/plugin marketplace add anthropics/claude-code~~

~~51```~~

~~53```shell Install the plugin theme={null}~~

~~54/plugin install explanatory-output-style@claude-code-plugins~~

~~55```~~

~~57```shell Restart Claude Code to activate the plugin theme={null}~~

~~58/exit~~

~~59```~~

~~61```shell Disable the plugin theme={null}~~

~~62/plugin manage explanatory-output-style@claude-code-plugins~~

~~641. Press enter when you see claude-code-marketplace~~

~~652. Press space when you see explanatory-output-style to toggle enabled~~

~~663. Press down to "Apply changes", then press enter~~

~~67 You should see "Disabled 1 plugin. Restart Claude Code to apply changes."~~

~~69/exit~~

~~70```~~

~~72For more details on plugins, see the~~

~~73[Plugins documentation](/en/docs/claude-code/plugins).~~

~~75## Migration guide~~

~~77Output styles directly modified Claude Code's system prompt. Here's how to~~

~~78achieve similar effects with hooks and subagents, both available through Claude~~

~~79Code plugins:~~

~~81### Use SessionStart hooks for context injection~~

~~83If you used output styles to add context at the start of sessions, use~~

~~84[SessionStart hooks](/en/docs/claude-code/hooks#sessionstart) instead.~~

~~86The hook's output (stdout) is added to the conversation context. You can also:~~

~~88* Run scripts that dynamically generate context~~

~~89* Load project-specific information~~

~~91<Note>~~

~~92 SessionStart hooks, just like CLAUDE.md, do not change the system prompt.~~

~~93</Note>~~

~~95### Use Subagents for different system prompts~~

~~97If you used output styles to change Claude's behavior for specific tasks, use~~

~~98[Subagents](/en/docs/claude-code/sub-agents) instead.~~

100Subagents are specialized AI assistants with:

~~101~~

102* Custom system prompts (must be in a separate context window from main loop)

103* Specific tool access permissions

104* Optional model to use, if not the main loop model

~~105~~

106***

~~107~~

108## Reference: Original output styles documentation

~~109~~

110<Note>

111 The content below is preserved for reference only. Output styles are

112 deprecated and will be removed on November 5, 2025. Please migrate to plugins,

113 hooks, or subagents.

114</Note>

115 4

116Output styles allow you to use Claude Code as any type of agent while keeping5Output styles allow you to use Claude Code as any type of agent while keeping

117its core capabilities, such as running local scripts, reading/writing files, and6its core capabilities, such as running local scripts, reading/writing files, and

118tracking TODOs.7tracking TODOs.

119 8

120### Built-in output styles9## Built-in output styles

121 10

122Claude Code's **Default** output style is the existing system prompt, designed11Claude Code's **Default** output style is the existing system prompt, designed

123to help you complete software engineering tasks efficiently.12to help you complete software engineering tasks efficiently.

134 pieces of code yourself. Claude Code will add `TODO(human)` markers in your23 pieces of code yourself. Claude Code will add `TODO(human)` markers in your

135 code for you to implement.24 code for you to implement.

136 25

137### How output styles work26## How output styles work

138 27

139Output styles directly modify Claude Code's system prompt.28Output styles directly modify Claude Code's system prompt.

140 29

141* Non-default output styles exclude instructions specific to code generation and30* All output styles exclude instructions for efficient output (such as

142 efficient output normally built into Claude Code (such as responding concisely31 responding concisely).

143 and verifying code with tests).32* Custom output styles exclude instructions for coding (such as verifying code

144* Instead, these output styles have their own custom instructions added to the33 with tests), unless `keep-coding-instructions` is true.

34* All output styles have their own custom instructions added to the end of the

145 system prompt.35 system prompt.

36* All output styles trigger reminders for Claude to adhere to the output style

37 instructions during the conversation.

146 38

147### Change your output style39## Change your output style

148 40

149You can either:41You can either:

150 42

151* Run `/output-style` to access the menu and select your output style (this can43* Run `/output-style` to access a menu and select your output style (this can

152 also be accessed from the `/config` menu)44 also be accessed from the `/config` menu)

153 45

154* Run `/output-style [style]`, such as `/output-style explanatory`, to directly46* Run `/output-style [style]`, such as `/output-style explanatory`, to directly

155 switch to a style47 switch to a style

156 48

157These changes apply to the [local project level](/en/docs/claude-code/settings)49These changes apply to the [local project level](/en/settings) and are saved in

158and 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.

53## Create a custom output style

159 54

160You can also create your own output style Markdown files and save them either at55Custom output styles are Markdown files with frontmatter and the text that will

161the user level (`~/.claude/output-styles`) or the project level56be added to the system prompt:

162(`.claude/output-styles`).

163 57

164### Comparisons to related features58```markdown theme={null}

59---

60name: My Custom Style

61description:

62 A brief description of what this style does, to be displayed to the user

63---

165 64

166#### Output Styles vs. CLAUDE.md vs. --append-system-prompt65# Custom Style Instructions

167 66

168Output styles completely “turn off” the parts of Claude Code’s default system67You are an interactive CLI tool that helps users with software engineering

68tasks. [Your custom instructions here...]

70## Specific Behaviors

72[Define how the assistant should behave in this style...]

73```

75You can save these files at the user level (`~/.claude/output-styles`) or

76project level (`.claude/output-styles`).

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 |

89## Comparisons to related features

91### Output Styles vs. CLAUDE.md vs. --append-system-prompt

93Output styles completely "turn off" the parts of Claude Code's default system

169prompt specific to software engineering. Neither CLAUDE.md nor94prompt specific to software engineering. Neither CLAUDE.md nor

170`--append-system-prompt` edit Claude Code’s default system prompt. CLAUDE.md95`--append-system-prompt` edit Claude Code's default system prompt. CLAUDE.md

171adds the contents as a user message *following* Claude Code’s default system96adds the contents as a user message *following* Claude Code's default system

172prompt. `--append-system-prompt` appends the content to the system prompt.97prompt. `--append-system-prompt` appends the content to the system prompt.

173 98

174#### Output Styles vs. [Agents](/en/docs/claude-code/sub-agents)99### Output Styles vs. [Agents](/en/sub-agents)

175 100

176Output styles directly affect the main agent loop and only affect the system101Output styles directly affect the main agent loop and only affect the system

177prompt. Agents are invoked to handle specific tasks and can include additional102prompt. Agents are invoked to handle specific tasks and can include additional

178settings like the model to use, the tools they have available, and some context103settings like the model to use, the tools they have available, and some context

179about when to use the agent.104about when to use the agent.

180 105

181#### Output Styles vs. [Custom Slash Commands](/en/docs/claude-code/slash-commands)106### Output Styles vs. [Skills](/en/skills)

107

108Output styles modify how Claude responds (formatting, tone, structure) and are always active once selected. Skills are task-specific prompts that you invoke with `/skill-name` or that Claude loads automatically when relevant. Use output styles for consistent formatting preferences; use skills for reusable workflows and tasks.

109

110

111---

182 112

183You can think of output styles as “stored system prompts” and custom slash113> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

184commands as “stored prompts”.

overview.md +59 −30

Details

6 6

7Prerequisites:7Prerequisites:

8 8

~~9* A [Claude.ai](https://claude.ai) (recommended) or [Claude Console](https://console.anthropic.com/) account~~9* A [Claude subscription](https://claude.com/pricing) (Pro, Max, Teams, or Enterprise) or [Claude Console](https://console.anthropic.com/) account

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

23 **Windows PowerShell:**

25 ```powershell theme={null}

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

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

35 <Info>

36 Native installations automatically update in the background to keep you on the latest version.

37 </Info>

18 </Tab>38 </Tab>

19 39

20 <Tab title="Homebrew">40 <Tab title="Homebrew">

~~21 ```bash theme={null}~~41 ```sh theme={null}

22 brew install --cask claude-code42 brew install --cask claude-code

23 ```43 ```

~~24 </Tab>~~

25 44

~~26 <Tab title="Windows">~~45 <Info>

~~27 ```powershell theme={null}~~46 Homebrew installations do not auto-update. Run `brew upgrade claude-code` periodically to get the latest features and security fixes.

~~28 irm https://claude.ai/install.ps1 | iex~~47 </Info>

~~29 ```~~

30 </Tab>48 </Tab>

31 49

~~32 <Tab title="NPM">~~50 <Tab title="WinGet">

~~33 ```bash theme={null}~~51 ```powershell theme={null}

~~34 npm install -g @anthropic-ai/claude-code~~52 winget install Anthropic.ClaudeCode

35 ```53 ```

36 54

~~37 Requires [Node.js 18+](https://nodejs.org/en/download/)~~55 <Info>

56 WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.

57 </Info>

38 </Tab>58 </Tab>

39</Tabs>59</Tabs>

40 60

45claude65claude

46```66```

47 67

~~48You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 mins) →](/en/docs/claude-code/quickstart)~~68You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 minutes) →](/en/quickstart)

49 69

50<Tip>70<Tip>

~~51 See [advanced setup](/en/docs/claude-code/setup) for installation options or [troubleshooting](/en/docs/claude-code/troubleshooting) if you hit issues.~~71 See [advanced setup](/en/setup) for installation options, manual updates, or uninstallation instructions. Visit [troubleshooting](/en/troubleshooting) if you hit issues.

52</Tip>72</Tip>

53 73

~~54<Note>~~

55 **New VS Code Extension (Beta)**: Prefer a graphical interface? Our new [VS Code extension](/en/docs/claude-code/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 you74## What Claude Code does for you

59 75

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.76* **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.77* **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/docs/claude-code/mcp) can pull from external datasources like Google Drive, Figma, and Slack.78* **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.79* **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 80

65## Why developers love Claude Code81## Why developers love Claude Code

66 82

67* **Works in your terminal**: Not another chat window. Not another IDE. Claude Code meets you where you already work, with the tools you already love.83* **Works in your terminal**: Not another chat window. Not another IDE. Claude Code meets you where you already work, with the tools you already love.

68* **Takes action**: Claude Code can directly edit files, run commands, and create commits. Need more? [MCP](/en/docs/claude-code/mcp) lets Claude read your design docs in Google Drive, update your tickets in Jira, or use *your* custom developer tooling.84* **Takes action**: Claude Code can directly edit files, run commands, and create commits. Need more? [MCP](/en/mcp) lets Claude read your design docs in Google Drive, update your tickets in Jira, or use *your* custom developer tooling.

69* **Unix philosophy**: Claude Code is composable and scriptable. `tail -f app.log | claude -p "Slack me if you see any anomalies appear in this log stream"` *works*. Your CI can run `claude -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review"`.85* **Unix philosophy**: Claude Code is composable and scriptable. `tail -f app.log | claude -p "Slack me if you see any anomalies appear in this log stream"` *works*. Your CI can run `claude -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review"`.

70* **Enterprise-ready**: Use the Claude API, or host on AWS or GCP. Enterprise-grade [security](/en/docs/claude-code/security), [privacy](/en/docs/claude-code/data-usage), and [compliance](https://trust.anthropic.com/) is built-in.86* **Enterprise-ready**: Use the Claude API, or host on AWS or GCP. Enterprise-grade [security](/en/security), [privacy](/en/data-usage), and [compliance](https://trust.anthropic.com/) is built-in.

71 87

72## Next steps88## Next steps

73 89

74<CardGroup>90<CardGroup>

~~75 <Card title="Quickstart" icon="rocket" href="/en/docs/claude-code/quickstart">~~91 <Card title="Quickstart" icon="rocket" href="/en/quickstart">

76 See Claude Code in action with practical examples92 See Claude Code in action with practical examples

77 </Card>93 </Card>

78 94

~~79 <Card title="Common workflows" icon="graduation-cap" href="/en/docs/claude-code/common-workflows">~~95 <Card title="Common workflows" icon="graduation-cap" href="/en/common-workflows">

80 Step-by-step guides for common workflows96 Step-by-step guides for common workflows

81 </Card>97 </Card>

82 98

~~83 <Card title="Troubleshooting" icon="wrench" href="/en/docs/claude-code/troubleshooting">~~99 <Card title="Troubleshooting" icon="wrench" href="/en/troubleshooting">

84 Solutions for common issues with Claude Code100 Solutions for common issues with Claude Code

85 </Card>101 </Card>

86 102

~~87 <Card title="IDE setup" icon="laptop" href="/en/docs/claude-code/ide-integrations">~~103 <Card title="IDE setup" icon="laptop" href="/en/vs-code">

88 Add Claude Code to your IDE104 Add Claude Code to your IDE

89 </Card>105 </Card>

90</CardGroup>106</CardGroup>

92## Additional resources108## Additional resources

93 109

94<CardGroup>110<CardGroup>

~~95 <Card title="Host on AWS or GCP" icon="cloud" href="/en/docs/claude-code/third-party-integrations">~~111 <Card title="About Claude Code" icon="sparkles" href="https://claude.com/product/claude-code">

112 Learn more about Claude Code on claude.com

113 </Card>

114

115 <Card title="Build with the Agent SDK" icon="code-branch" href="https://docs.claude.com/en/docs/agent-sdk/overview">

116 Create custom AI agents with the Claude Agent SDK

117 </Card>

118

119 <Card title="Host on AWS or GCP" icon="cloud" href="/en/third-party-integrations">

96 Configure Claude Code with Amazon Bedrock or Google Vertex AI120 Configure Claude Code with Amazon Bedrock or Google Vertex AI

97 </Card>121 </Card>

98 122

~~99 <Card title="Settings" icon="gear" href="/en/docs/claude-code/settings">~~123 <Card title="Settings" icon="gear" href="/en/settings">

100 Customize Claude Code for your workflow124 Customize Claude Code for your workflow

101 </Card>125 </Card>

102 126

103 <Card title="Commands" icon="terminal" href="/en/docs/claude-code/cli-reference">127 <Card title="Commands" icon="terminal" href="/en/cli-reference">

104 Learn about CLI commands and controls128 Learn about CLI commands and controls

105 </Card>129 </Card>

106 130

108 Clone our development container reference implementation132 Clone our development container reference implementation

109 </Card>133 </Card>

110 134

111 <Card title="Security" icon="shield" href="/en/docs/claude-code/security">135 <Card title="Security" icon="shield" href="/en/security">

112 Discover Claude Code's safeguards and best practices for safe usage136 Discover Claude Code's safeguards and best practices for safe usage

113 </Card>137 </Card>

114 138

115 <Card title="Privacy and data usage" icon="lock" href="/en/docs/claude-code/data-usage">139 <Card title="Privacy and data usage" icon="lock" href="/en/data-usage">

116 Understand how Claude Code handles your data140 Understand how Claude Code handles your data

117 </Card>141 </Card>

118</CardGroup>142</CardGroup>

143

144

145---

146

147> 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 +325 −189

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```~~

31 8

~~32### Add Git repositories~~9## Overview

33 10

~~34```shell Add any git repository theme={null}~~11Creating and distributing a marketplace involves:

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

~~36```~~

37 12

~~38### Add local marketplaces for development~~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.

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

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

39 17

~~40```shell Add local directory containing .claude-plugin/marketplace.json 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`.

~~41/plugin marketplace add ./my-marketplace~~

~~42```~~

43 19

~~44```shell Add direct path to marketplace.json file theme={null}~~20## Walkthrough: create a local marketplace

~~45/plugin marketplace add ./path/to/marketplace.json~~

~~46```~~

47 21

~~48```shell Add remote marketplace.json via URL theme={null}~~22This example creates a marketplace with one plugin: a `/review` skill for code reviews. You'll create the directory structure, add a skill, create the plugin manifest and marketplace catalog, then install and test it.

~~49/plugin marketplace add https://url.of/marketplace.json~~

~~50```~~

~~52### Install plugins from marketplaces~~

53 23

~~54Once you've added marketplaces, install plugins directly:~~24<Steps>

25 <Step title="Create the directory structure">

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/skills/review

30 ```

31 </Step>

55 32

~~56```shell Install from any known marketplace theme={null}~~33 <Step title="Create the skill">

~~57/plugin install plugin-name@marketplace-name~~34 Create a `SKILL.md` file that defines what the `/review` skill does.

~~58```~~

59 35

~~60```shell Browse available plugins interactively theme={null}~~36 ```markdown my-marketplace/plugins/review-plugin/skills/review/SKILL.md theme={null}

~~61/plugin~~37 ---

~~62```~~38 description: Review code for bugs, security, and performance

39 disable-model-invocation: true

40 ---

63 41

~~64### Verify marketplace installation~~42 Review the code I've selected or the recent changes for:

43 - Potential bugs or edge cases

44 - Security concerns

45 - Performance issues

46 - Readability improvements

65 47

~~66After adding a marketplace:~~48 Be concise and actionable.

49 ```

50 </Step>

67 51

~~681. **List marketplaces**: Run `/plugin marketplace list` to confirm it's added~~52 <Step title="Create the plugin manifest">

~~692. **Browse plugins**: Use `/plugin` to see available plugins from your marketplace~~53 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 54

~~72## Configure team marketplaces~~55 ```json my-marketplace/plugins/review-plugin/.claude-plugin/plugin.json theme={null}

56 {

57 "name": "review-plugin",

58 "description": "Adds a /review skill for quick code reviews",

59 "version": "1.0.0"

60 }

61 ```

62 </Step>

73 63

~~74Set up automatic marketplace installation for team projects by specifying required marketplaces in `.claude/settings.json`:~~64 <Step title="Create the marketplace file">

65 Create the marketplace catalog that lists your plugin.

75 66

~~76```json theme={null}~~67 ```json my-marketplace/.claude-plugin/marketplace.json theme={null}

~~77{~~68 {

~~78 "extraKnownMarketplaces": {~~69 "name": "my-plugins",

~~79 "team-tools": {~~70 "owner": {

~~80 "source": {~~71 "name": "Your Name"

~~81 "source": "github",~~

~~82 "repo": "your-org/claude-plugins"~~

~~83 }~~

84 },72 },

~~85 "project-specific": {~~73 "plugins": [

~~86 "source": {~~74 {

~~87 "source": "git",~~75 "name": "review-plugin",

~~88 "url": "https://git.company.com/project-plugins.git"~~76 "source": "./plugins/review-plugin",

~~89 }~~77 "description": "Adds a /review skill for quick code reviews"

90 }78 }

79 ]

91 }80 }

~~92}~~81 ```

~~93```~~82 </Step>

94 83

~~95When team members trust the repository folder, Claude Code automatically installs these marketplaces and any plugins specified in the `enabledPlugins` field.~~84 <Step title="Add and install">

85 Add the marketplace and install the plugin.

96 86

~~97***~~87 ```shell theme={null}

88 /plugin marketplace add ./my-marketplace

89 /plugin install review-plugin@my-plugins

90 ```

91 </Step>

98 92

~~99## Create your own marketplace~~93 <Step title="Try it out">

94 Select some code in your editor and run your new command.

100 95

101Build and distribute custom plugin collections for your team or community.96 ```shell theme={null}

97 /review

98 ```

99 </Step>

100</Steps>

102 101

103### Prerequisites for marketplace creation102To learn more about what plugins can do, including hooks, agents, MCP servers, and LSP servers, see [Plugins](/en/plugins).

104 103

105* Git repository (GitHub, GitLab, or other git hosting)104<Note>

106* Understanding of JSON file format105 **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 distribute

108 106

109### Create the marketplace file107 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.

108</Note>

109

110## Create the marketplace file

111

112Create `.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.

110 113

111Create `.claude-plugin/marketplace.json` in your repository root:114Each 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 115

113```json theme={null}116```json theme={null}

114{117{

115 "name": "company-tools",118 "name": "company-tools",

116 "owner": {119 "owner": {

117 "name": "DevTools Team",120 "name": "DevTools Team",

118 "email": "devtools@company.com"121 "email": "devtools@example.com"

119 },122 },

120 "plugins": [123 "plugins": [

121 {124 {

139}142}

140```143```

141 144

142### Marketplace schema145## Marketplace schema

143 146

144#### Required fields147### Required fields

145 148

147| :-------- | :----- | :--------------------------------------------- |150| :-------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |

154

155<Note>

156 **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.

157</Note>

158

159### Owner fields

151 160

162| :------ | :----- | :------- | :------------------------------- |

165

166### Optional metadata

153 167

155| :--------------------- | :----- | :------------------------------------ |169| :--------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

159 173

160### Plugin entries174## Plugin entries

161 175

162<Note>176Each 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 177

166**Required fields:**178### Required fields

167 179

169| :------- | :------------- | :---------------------------------------- |181| :------- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

172 184

173#### Optional plugin fields185### Optional plugin fields

174 186

175**Standard metadata fields:**187**Standard metadata fields:**

176 188

178| :------------ | :------ | :---------------------------------------------------------------- |190| :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

188| `strict` | boolean | Require plugin.json in plugin folder (default: true) <sup>1</sup> |200| `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 201

190**Component configuration fields:**202**Component configuration fields:**

191 203

198 211

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>*212## Plugin sources

~~200~~

201### Plugin sources

202 213

203#### Relative paths214### Relative paths

204 215

205For plugins in the same repository:216For plugins in the same repository:

206 217

211}222}

212```223```

213 224

214#### GitHub repositories225<Note>

226 Relative paths only work when users add your marketplace via Git (GitHub, GitLab, or git URL). If users add your marketplace via a direct URL to the `marketplace.json` file, relative paths will not resolve correctly. For URL-based distribution, use GitHub, npm, or git URL sources instead. See [Troubleshooting](#plugins-with-relative-paths-fail-in-url-based-marketplaces) for details.

227</Note>

228

229### GitHub repositories

215 230

216```json theme={null}231```json theme={null}

217{232{

223}238}

224```239```

225 240

226#### Git repositories241### Git repositories

227 242

228```json theme={null}243```json theme={null}

229{244{

235}250}

236```251```

237 252

238#### Advanced plugin entries253### Advanced plugin entries

239 254

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/docs/claude-code/plugins-reference#environment-variables)):255This example shows a plugin entry using many of the optional fields, including custom paths for commands, agents, hooks, and MCP servers:

241 256

242```json theme={null}257```json theme={null}

243{258{

250 "version": "2.1.0",265 "version": "2.1.0",

251 "author": {266 "author": {

252 "name": "Enterprise Team",267 "name": "Enterprise Team",

253 "email": "enterprise@company.com"268 "email": "enterprise@example.com"

254 },269 },

255 "homepage": "https://docs.company.com/plugins/enterprise-tools",270 "homepage": "https://docs.example.com/plugins/enterprise-tools",

256 "repository": "https://github.com/company/enterprise-plugin",271 "repository": "https://github.com/company/enterprise-plugin",

257 "license": "MIT",272 "license": "MIT",

258 "keywords": ["enterprise", "workflow", "automation"],273 "keywords": ["enterprise", "workflow", "automation"],

262 "./commands/enterprise/",277 "./commands/enterprise/",

263 "./commands/experimental/preview.md"278 "./commands/experimental/preview.md"

264 ],279 ],

265 "agents": [280 "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],

266 "./agents/security-reviewer.md",

267 "./agents/compliance-checker.md"

268 ],

269 "hooks": {281 "hooks": {

270 "PostToolUse": [282 "PostToolUse": [

271 {283 {

272 "matcher": "Write|Edit",284 "matcher": "Write|Edit",

273 "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"}]285 "hooks": [

286 {

287 "type": "command",

288 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"

289 }

290 ]

274 }291 }

275 ]292 ]

276 },293 },

284}301}

285```302```

286 303

287<Note>304Key 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 305

291***306* **`commands` and `agents`**: You can specify multiple directories or individual files. Paths are relative to the plugin root.

307* **`${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.

308* **`strict: false`**: Since this is set to false, the plugin doesn't need its own `plugin.json`. The marketplace entry defines everything.

292 309

293## Host and distribute marketplaces310## Host and distribute marketplaces

294 311

295Choose the best hosting strategy for your plugin distribution needs.

~~296~~

297### Host on GitHub (recommended)312### Host on GitHub (recommended)

298 313

299GitHub provides the easiest distribution method:314GitHub provides the easiest distribution method:

300 315

3011. **Create a repository**: Set up a new repository for your marketplace3161. **Create a repository**: Set up a new repository for your marketplace

3022. **Add marketplace file**: Create `.claude-plugin/marketplace.json` with your plugin definitions3172. **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`3183. **Share with teams**: Users add your marketplace with `/plugin marketplace add owner/repo`

304 319

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

306 321

307### Host on other git services322### Host on other git services

308 323

309Any git hosting service works for marketplace distribution, using a URL to an arbitrary git repository.324Any 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 325

313```shell theme={null}326```shell theme={null}

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

315```328```

316 329

317### Use local marketplaces for development330### Private repositories

318 331

319Test your marketplace locally before distribution:332Claude Code supports installing plugins from private repositories. Set the appropriate authentication token in your environment, and Claude Code will use it when authentication is required.

320 333

321```shell Add local marketplace for testing theme={null}334| Provider | Environment variables | Notes |

322/plugin marketplace add ./my-local-marketplace335| :-------- | :--------------------------- | :---------------------------------------- |

336| GitHub | `GITHUB_TOKEN` or `GH_TOKEN` | Personal access token or GitHub App token |

337| GitLab | `GITLAB_TOKEN` or `GL_TOKEN` | Personal access token or project token |

338| Bitbucket | `BITBUCKET_TOKEN` | App password or repository access token |

339

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

341

342```bash theme={null}

343export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

323```344```

324 345

325```shell Test plugin installation theme={null}346Authentication tokens are only used when a repository requires authentication. Public repositories work without any tokens configured, even if tokens are present in your environment.

347

348<Note>

349 For CI/CD environments, configure the token as a secret environment variable. GitHub Actions automatically provides `GITHUB_TOKEN` for repositories in the same organization.

350</Note>

351

352### Test locally before distribution

353

354Test your marketplace locally before sharing:

355

356```shell theme={null}

357/plugin marketplace add ./my-local-marketplace

326/plugin install test-plugin@my-local-marketplace358/plugin install test-plugin@my-local-marketplace

327```359```

328 360

329## Manage marketplace operations361For the full range of add commands (GitHub, Git URLs, local paths, remote URLs), see [Add marketplaces](/en/discover-plugins#add-marketplaces).

362

363### Require marketplaces for your team

330 364

331### List known marketplaces365You 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`:

332 366

333```shell List all configured marketplaces theme={null}367```json theme={null}

334/plugin marketplace list368{

369 "extraKnownMarketplaces": {

370 "company-tools": {

371 "source": {

372 "source": "github",

373 "repo": "your-org/claude-plugins"

374 }

375 }

376 }

377}

335```378```

336 379

337Shows all configured marketplaces with their sources and status.380You can also specify which plugins should be enabled by default:

381

382```json theme={null}

383{

384 "enabledPlugins": {

385 "code-formatter@company-tools": true,

386 "deployment-tools@company-tools": true

387 }

388}

389```

390

391For full configuration options, see [Plugin settings](/en/settings#plugin-settings).

392

393### Managed marketplace restrictions

394

395For organizations requiring strict control over plugin sources, administrators can restrict which plugin marketplaces users are allowed to add using the [`strictKnownMarketplaces`](/en/settings#strictknownmarketplaces) setting in managed settings.

396

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

398

399| Value | Behavior |

400| ------------------- | ---------------------------------------------------------------- |

401| Undefined (default) | No restrictions. Users can add any marketplace |

402| Empty array `[]` | Complete lockdown. Users cannot add any new marketplaces |

403| List of sources | Users can only add marketplaces that match the allowlist exactly |

338 404

339### Update marketplace metadata405#### Common configurations

340 406

341```shell Refresh marketplace metadata theme={null}407Disable all marketplace additions:

342/plugin marketplace update marketplace-name408

409```json theme={null}

410{

411 "strictKnownMarketplaces": []

412}

413```

414

415Allow specific marketplaces only:

416

417```json theme={null}

418{

419 "strictKnownMarketplaces": [

420 {

421 "source": "github",

422 "repo": "acme-corp/approved-plugins"

423 },

424 {

425 "source": "github",

426 "repo": "acme-corp/security-tools",

427 "ref": "v2.0"

428 },

429 {

430 "source": "url",

431 "url": "https://plugins.example.com/marketplace.json"

432 }

433 ]

434}

343```435```

344 436

345Refreshes plugin listings and metadata from the marketplace source.437#### How restrictions work

438

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

440

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

442

443* For GitHub sources: `repo` is required, and `ref` or `path` must also match if specified in the allowlist

444* For URL sources: the full URL must match exactly

346 445

347### Remove a marketplace446Because `strictKnownMarketplaces` is set in [managed settings](/en/settings#settings-files), individual users and project configurations cannot override these restrictions.

348 447

349```shell Remove a marketplace theme={null}448For complete configuration details including all supported source types and comparison with `extraKnownMarketplaces`, see the [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces).

350/plugin marketplace remove marketplace-name449

450## Validation and testing

451

452Test your marketplace before sharing.

453

454Validate your marketplace JSON syntax:

455

456```bash theme={null}

457claude plugin validate .

351```458```

352 459

353Removes the marketplace from your configuration.460Or from within Claude Code:

354 461

355<Warning>462```shell theme={null}

356 Removing a marketplace will uninstall any plugins you installed from it.463/plugin validate .

357</Warning>464```

358 465

359***466Add the marketplace for testing:

360 467

361## Troubleshooting marketplaces468```shell theme={null}

469/plugin marketplace add ./path/to/marketplace

470```

362 471

363### Common marketplace issues472Install a test plugin to verify everything works:

473

474```shell theme={null}

475/plugin install test-plugin@marketplace-name

476```

364 477

365#### Marketplace not loading478For complete plugin testing workflows, see [Test your plugins locally](/en/plugins#test-your-plugins-locally). For technical troubleshooting, see [Plugins reference](/en/plugins-reference).

479

480## Troubleshooting

481

482### Marketplace not loading

366 483

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

368 485

370 487

371* Verify the marketplace URL is accessible488* Verify the marketplace URL is accessible

372* Check that `.claude-plugin/marketplace.json` exists at the specified path489* Check that `.claude-plugin/marketplace.json` exists at the specified path

373* Ensure JSON syntax is valid using `claude plugin validate`490* Ensure JSON syntax is valid using `claude plugin validate` or `/plugin validate`

374* For private repositories, confirm you have access permissions491* For private repositories, confirm you have access permissions

375 492

376#### Plugin installation failures493### Marketplace validation errors

494

495Run `claude plugin validate .` or `/plugin validate .` from your marketplace directory to check for issues. Common errors:

496

497| Error | Cause | Solution |

498| :------------------------------------------------ | :------------------------------ | :------------------------------------------------------------ |

499| `File not found: .claude-plugin/marketplace.json` | Missing manifest | Create `.claude-plugin/marketplace.json` with required fields |

500| `Invalid JSON syntax: Unexpected token...` | JSON syntax error | Check for missing commas, extra commas, or unquoted strings |

501| `Duplicate plugin name "x" found in marketplace` | Two plugins share the same name | Give each plugin a unique `name` value |

502| `plugins[0].source: Path traversal not allowed` | Source path contains `..` | Use paths relative to marketplace root without `..` |

503

504**Warnings** (non-blocking):

505

506* `Marketplace has no plugins defined`: add at least one plugin to the `plugins` array

507* `No marketplace description provided`: add `metadata.description` to help users understand your marketplace

508* `Plugin "x" uses npm source which is not yet fully implemented`: use `github` or local path sources instead

509

510### Plugin installation failures

377 511

378**Symptoms**: Marketplace appears but plugin installation fails512**Symptoms**: Marketplace appears but plugin installation fails

379 513

384* For GitHub sources, ensure repositories are public or you have access518* For GitHub sources, ensure repositories are public or you have access

385* Test plugin sources manually by cloning/downloading519* Test plugin sources manually by cloning/downloading

386 520

387### Validation and testing521### Private repository authentication fails

388 522

389Test your marketplace before sharing:523**Symptoms**: Authentication errors when installing plugins from private repositories, even with tokens configured

390 524

391```bash Validate marketplace JSON syntax theme={null}525**Solutions**:

392claude plugin validate .

393```

394 526

395```shell Add marketplace for testing theme={null}527* Verify your token is set in the current shell session: `echo $GITHUB_TOKEN`

396/plugin marketplace add ./path/to/marketplace528* Check that the token has the required permissions (read access to the repository)

397```529* For GitHub, ensure the token has the `repo` scope for private repositories

530* For GitLab, ensure the token has at least `read_repository` scope

531* Verify the token hasn't expired

532* If using multiple git providers, ensure you've set the token for the correct provider

398 533

399```shell Install test plugin theme={null}534### Plugins with relative paths fail in URL-based marketplaces

400/plugin install test-plugin@marketplace-name

401```

402 535

403For complete plugin testing workflows, see [Test your plugins locally](/en/docs/claude-code/plugins#test-your-plugins-locally). For technical troubleshooting, see [Plugins reference](/en/docs/claude-code/plugins-reference).536**Symptoms**: Added a marketplace via URL (such as `https://example.com/marketplace.json`), but plugins with relative path sources like `"./plugins/my-plugin"` fail to install with "path not found" errors.

404 537

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

406 539

407## Next steps540**Solutions**:

408 541

409### For marketplace users542* **Use external sources**: Change plugin entries to use GitHub, npm, or git URL sources instead of relative paths:

543 ```json theme={null}

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

545 ```

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

410 547

411* **Discover community marketplaces**: Search GitHub for Claude Code plugin collections548### Files not found after installation

412* **Contribute feedback**: Report issues and suggest improvements to marketplace maintainers

413* **Share useful marketplaces**: Help your team discover valuable plugin collections

414 549

415### For marketplace creators550**Symptoms**: Plugin installs but references to files fail, especially files outside the plugin directory

416 551

417* **Build plugin collections**: Create themed marketplace around specific use cases552**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.

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 553

422### For organizations554**Solutions**: See [Plugin caching and file resolution](/en/plugins-reference#plugin-caching-and-file-resolution) for workarounds including symlinks and directory restructuring.

423 555

424* **Private marketplaces**: Set up internal marketplaces for proprietary tools556For additional debugging tools and common issues, see [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools).

425* **Governance policies**: Establish guidelines for plugin approval and security review

426* **Training resources**: Help teams discover and adopt useful plugins effectively

427 557

428## See also558## See also

429 559

430* [Plugins](/en/docs/claude-code/plugins) - Installing and using plugins560* [Discover and install prebuilt plugins](/en/discover-plugins) - Installing plugins from existing marketplaces

431* [Plugins reference](/en/docs/claude-code/plugins-reference) - Complete technical specifications and schemas561* [Plugins](/en/plugins) - Creating your own plugins

432* [Plugin development](/en/docs/claude-code/plugins#develop-more-complex-plugins) - Creating your own plugins562* [Plugins reference](/en/plugins-reference) - Complete technical specifications and schemas

433* [Settings](/en/docs/claude-code/settings#plugin-configuration) - Plugin configuration options563* [Plugin settings](/en/settings#plugin-settings) - Plugin configuration options

564* [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces) - Managed marketplace restrictions

565

566

567---

568

569> 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 −253

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 skills, agents, hooks, 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 skills, agents, 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 skills, agents, and hooks:

13| Approach | Skill 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 skills or hooks before packaging them

23* You want short skill 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 skills/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 skills 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/docs/claude-code/plugins-reference). For marketplace management, see [Plugin marketplaces](/en/docs/claude-code/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/docs/claude-code/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 skill. You'll create a manifest (the configuration file that defines your plugin), add a skill, 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 skills, 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 skill namespace. Skills 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 skill">

~~54 ```bash Create commands/hello.md theme={null}~~94 Skills live in the `skills/` directory. Each skill is a folder containing a `SKILL.md` file. The folder name becomes the skill name, prefixed with the plugin's namespace (`hello/` in a plugin named `my-first-plugin` creates `/my-first-plugin:hello`).

~~55 mkdir commands~~

~~56 cat > commands/hello.md << 'EOF'~~

~~57 ---~~

~~58 description: Greet the user with a personalized message~~

~~59 ---~~

60 95

~~61 # Hello Command~~96 Create a skill directory in your plugin folder:

62 97

~~63 Greet the user warmly and ask how you can help them today. Make the greeting personal and encouraging.~~98 ```bash theme={null}

~~64 EOF~~99 mkdir -p my-first-plugin/skills/hello

65 ```100 ```

~~66 </Step>~~

67 101

~~68 <Step title="Create the marketplace manifest">~~102 Then create `my-first-plugin/skills/hello/SKILL.md` with this content:

~~69 ```bash Create marketplace.json theme={null}~~103

~~70 cd ..~~104 ```markdown my-first-plugin/skills/hello/SKILL.md theme={null}

~~71 mkdir .claude-plugin~~105 ---

~~72 cat > .claude-plugin/marketplace.json << 'EOF'~~106 description: Greet the user with a friendly message

~~73 {~~107 disable-model-invocation: true

~~74 "name": "test-marketplace",~~108 ---

~~75 "owner": {~~109

~~76 "name": "Test User"~~110 Greet the user warmly and ask how you can help them today.

~~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 ```111 ```

88 </Step>112 </Step>

89 113

~~90 <Step title="Install and test your plugin">~~114 <Step title="Test your plugin">

~~91 ```bash Start Claude Code from parent directory theme={null}~~115 Run Claude Code with the `--plugin-dir` flag to load your plugin:

~~92 cd ..~~116

~~93 claude~~117 ```bash theme={null}

118 claude --plugin-dir ./my-first-plugin

94 ```119 ```

95 120

~~96 ```shell Add the test marketplace theme={null}~~121 Once Claude Code starts, try your new command:

~~97 /plugin marketplace add ./test-marketplace~~122

123 ```shell theme={null}

124 /my-first-plugin:hello

98 ```125 ```

99 126

100 ```shell Install your plugin theme={null}127 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-marketplace128

129 <Note>

130 **Why namespacing?** Plugin skills are always namespaced (like `/greet:hello`) to prevent conflicts when multiple plugins have skills with the same name.

131

132 To change the namespace prefix, update the `name` field in `plugin.json`.

133 </Note>

134 </Step>

135

136 <Step title="Add skill arguments">

137 Make your skill dynamic by accepting user input. The `$ARGUMENTS` placeholder captures any text the user provides after the skill name.

138

139 Update your `hello.md` file:

140

141 ```markdown my-first-plugin/commands/hello.md theme={null}

142 ---

143 description: Greet the user with a personalized message

144 ---

145

146 # Hello Command

147

148 Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

102 ```149 ```

103 150

104 Select "Install now". You'll then need to restart Claude Code in order to use the new plugin.151 Restart Claude Code to pick up the changes, then try the command with your name:

105 152

106 ```shell Try your new command theme={null}153 ```shell theme={null}

107 /hello154 /my-first-plugin:hello Alex

108 ```155 ```

109 156

110 You'll see Claude use your greeting command! Check `/help` to see your new command listed.157 Claude will greet you by name. For more on passing arguments to skills, see [Skills](/en/skills#pass-arguments-to-skills).

111 </Step>158 </Step>

112</Steps>159</Steps>

113 160

114You've successfully created and tested a plugin with these key components:161You've successfully created and tested a plugin with these key components:

115 162

116* **Plugin manifest** (`.claude-plugin/plugin.json`) - Describes your plugin's metadata163* **Plugin manifest** (`.claude-plugin/plugin.json`): describes your plugin's metadata

117* **Commands directory** (`commands/`) - Contains your custom slash commands164* **Commands directory** (`commands/`): contains your custom skills

118* **Test marketplace** - Allows you to test your plugin locally165* **Skill arguments** (`$ARGUMENTS`): captures user input for dynamic behavior

119 166

120### Plugin structure overview167<Tip>

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

169</Tip>

121 170

122Your plugin follows this basic structure:171## Plugin structure overview

123 172

124```173You've created a plugin with a skill, but plugins can include much more: custom agents, 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 174

139**Additional components you can add:**175<Warning>

176 **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.

177</Warning>

140 178

141* **Commands**: Create markdown files in `commands/` directory179| Directory | Location | Purpose |

142* **Agents**: Create agent definitions in `agents/` directory180| :---------------- | :---------- | :---------------------------------------------- |

143* **Skills**: Create `SKILL.md` files in `skills/` directory181| `.claude-plugin/` | Plugin root | Contains only `plugin.json` manifest (required) |

144* **Hooks**: Create `hooks/hooks.json` for event handling182| `commands/` | Plugin root | Skills as Markdown files |

145* **MCP servers**: Create `.mcp.json` for external tool integration183| `agents/` | Plugin root | Custom agent definitions |

184| `skills/` | Plugin root | Agent Skills with `SKILL.md` files |

185| `hooks/` | Plugin root | Event handlers in `hooks.json` |

186| `.mcp.json` | Plugin root | MCP server configurations |

187| `.lsp.json` | Plugin root | LSP server configurations for code intelligence |

146 188

147<Note>189<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/docs/claude-code/plugins-reference).190 **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>191</Note>

150 192

151***193## 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 194

157### Prerequisites195Once you're comfortable with basic plugins, you can create more sophisticated extensions.

158 196

159* Claude Code installed and running197### Add Skills to your plugin

160* Basic familiarity with command-line interfaces

161 198

162### Add marketplaces199Plugins 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 200

164Marketplaces are catalogs of available plugins. Add them to discover and install plugins:201Add a `skills/` directory at your plugin root with Skill folders containing `SKILL.md` files:

165 202

166```shell Add a marketplace theme={null}

167/plugin marketplace add your-org/claude-plugins

168```203```

~~169~~ 204my-plugin/

170```shell Browse available plugins theme={null}205├── .claude-plugin/

171/plugin206│ └── plugin.json

207└── skills/

208 └── code-review/

209 └── SKILL.md

172```210```

173 211

174For detailed marketplace management including Git repositories, local development, and team distribution, see [Plugin marketplaces](/en/docs/claude-code/plugin-marketplaces).212Each `SKILL.md` needs frontmatter with `name` and `description` fields, followed by instructions:

175 213

176### Install plugins214```yaml theme={null}

215---

216name: code-review

217description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.

218---

177 219

178#### Via interactive menu (recommended for discovery)220When reviewing code, check for:

~~179~~ 2211. Code organization and structure

180```shell Open the plugin management interface theme={null}2222. Error handling

181/plugin2233. Security concerns

2244. Test coverage

182```225```

183 226

184Select "Browse Plugins" to see available options with descriptions, features, and installation options.227After 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 228

186#### Via direct commands (for quick installation)229### Add LSP servers to your plugin

187 230

188```shell Install a specific plugin theme={null}231<Tip>

189/plugin install formatter@your-org232 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```233</Tip>

191 234

192```shell Enable a disabled plugin theme={null}235LSP (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 236

196```shell Disable without uninstalling theme={null}237```json .lsp.json theme={null}

197/plugin disable plugin-name@marketplace-name238{

239 "go": {

240 "command": "gopls",

241 "args": ["serve"],

242 "extensionToLanguage": {

243 ".go": "go"

244 }

245 }

246}

198```247```

199 248

200```shell Completely remove a plugin theme={null}249Users installing your plugin must have the language server binary installed on their machine.

201/plugin uninstall plugin-name@marketplace-name

202```

203 250

204### Verify installation251For complete LSP configuration options, see [LSP servers](/en/plugins-reference#lsp-servers).

205 252

206After installing a plugin:253### Organize complex plugins

207 254

2081. **Check available commands**: Run `/help` to see new commands255For 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 256

212## Set up team plugin workflows257### Test your plugins locally

213 258

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.259Use the `--plugin-dir` flag to test plugins during development. This loads your plugin directly without requiring installation.

215 260

216**To set up team plugins:**261```bash theme={null}

262claude --plugin-dir ./my-plugin

263```

217 264

2181. Add marketplace and plugin configuration to your repository's `.claude/settings.json`265As 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 266

222For complete instructions including configuration examples, marketplace setup, and rollout best practices, see [Configure team marketplaces](/en/docs/claude-code/plugin-marketplaces#how-to-configure-team-marketplaces).267* Try your commands with `/command-name`

268* Check that agents appear in `/agents`

269* Verify hooks work as expected

223 270

224***271<Tip>

272 You can load multiple plugins at once by specifying the flag multiple times:

225 273

226## Develop more complex plugins274 ```bash theme={null}

275 claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

276 ```

277</Tip>

227 278

228Once you're comfortable with basic plugins, you can create more sophisticated extensions.279### Debug plugin issues

229 280

230### Add Skills to your plugin281If your plugin isn't working as expected:

231 282

232Plugins can include [Agent Skills](/en/docs/claude-code/skills) to extend Claude's capabilities. Skills are model-invoked—Claude autonomously uses them based on the task context.2831. **Check the structure**: Ensure your directories are at the plugin root, not inside `.claude-plugin/`

2842. **Test components individually**: Check each command, agent, and hook separately

2853. **Use validation and debugging tools**: See [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools) for CLI commands and troubleshooting techniques

233 286

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.287### Share your plugins

235 288

236For complete Skill authoring guidance, see [Agent Skills](/en/docs/claude-code/skills).289When your plugin is ready to share:

237 290

238### Organize complex plugins2911. **Add documentation**: Include a `README.md` with installation and usage instructions

2922. **Version your plugin**: Use [semantic versioning](/en/plugins-reference#version-management) in your `plugin.json`

2933. **Create or use a marketplace**: Distribute through [plugin marketplaces](/en/plugin-marketplaces) for installation

2944. **Test with others**: Have team members test the plugin before wider distribution

239 295

240For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/docs/claude-code/plugins-reference#plugin-directory-structure).296Once your plugin is in a marketplace, others can install it using the instructions in [Discover and install plugins](/en/discover-plugins).

241 297

242### Test your plugins locally298<Note>

299 For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/plugins-reference).

300</Note>

243 301

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.302## Convert existing configurations to plugins

245 303

246<Steps>304If you already have 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 305

250 ```bash Create directory structure theme={null}306### Migration steps

251 mkdir dev-marketplace

252 cd dev-marketplace

253 mkdir my-plugin

254 ```

255 307

256 This creates:308<Steps>

309 <Step title="Create the plugin structure">

310 Create a new plugin directory:

257 311

312 ```bash theme={null}

313 mkdir -p my-plugin/.claude-plugin

258 ```314 ```

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 315

269 <Step title="Create the marketplace manifest">316 Create the manifest file at `my-plugin/.claude-plugin/plugin.json`:

270 ```bash Create marketplace.json theme={null}317

271 mkdir .claude-plugin318 ```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 {319 {

280 "name": "my-plugin",320 "name": "my-plugin",

281 "source": "./my-plugin",321 "description": "Migrated from standalone configuration",

282 "description": "Plugin under development"322 "version": "1.0.0"

283 }

284 ]

285 }323 }

286 EOF

287 ```324 ```

288 </Step>325 </Step>

289 326

290 <Step title="Install and test">327 <Step title="Copy your existing files">

291 ```bash Start Claude Code from parent directory theme={null}328 Copy your existing configurations to the plugin directory:

292 cd ..

293 claude

294 ```

295 329

296 ```shell Add your development marketplace theme={null}330 ```bash theme={null}

297 /plugin marketplace add ./dev-marketplace331 # Copy commands

298 ```332 cp -r .claude/commands my-plugin/

~~299~~

300 ```shell Install your plugin theme={null}

301 /plugin install my-plugin@dev-marketplace

302 ```

303 333

304 Test your plugin components:334 # Copy agents (if any)

335 cp -r .claude/agents my-plugin/

305 336

306 * Try your commands with `/command-name`337 # Copy skills (if any)

307 * Check that agents appear in `/agents`338 cp -r .claude/skills my-plugin/

308 * Verify hooks work as expected339 ```

309 </Step>340 </Step>

310 341

311 <Step title="Iterate on your plugin">342 <Step title="Migrate hooks">

312 After making changes to your plugin code:343 If you have hooks in your settings, create a hooks directory:

313 344

314 ```shell Uninstall the current version theme={null}345 ```bash theme={null}

315 /plugin uninstall my-plugin@dev-marketplace346 mkdir my-plugin/hooks

316 ```347 ```

317 348

318 ```shell Reinstall to test changes theme={null}349 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 350

322 Repeat this cycle as you develop and refine your plugin.351 ```json my-plugin/hooks/hooks.json theme={null}

352 {

353 "hooks": {

354 "PostToolUse": [

355 {

356 "matcher": "Write|Edit",

357 "hooks": [{ "type": "command", "command": "npm run lint:fix $FILE" }]

358 }

359 ]

360 }

361 }

362 ```

323 </Step>363 </Step>

324</Steps>

~~325~~

326<Note>

327 **For multiple plugins**: Organize plugins in subdirectories like `./plugins/plugin-name` and update your marketplace.json accordingly. See [Plugin sources](/en/docs/claude-code/plugin-marketplaces#plugin-sources) for organization patterns.

328</Note>

329 364

330### Debug plugin issues365 <Step title="Test your migrated plugin">

~~331~~ 366 Load your plugin to verify everything works:

332If your plugin isn't working as expected:

333 367

3341. **Check the structure**: Ensure your directories are at the plugin root, not inside `.claude-plugin/`368 ```bash theme={null}

3352. **Test components individually**: Check each command, agent, and hook separately369 claude --plugin-dir ./my-plugin

3363. **Use validation and debugging tools**: See [Debugging and development tools](/en/docs/claude-code/plugins-reference#debugging-and-development-tools) for CLI commands and troubleshooting techniques370 ```

337 371

338### Share your plugins372 Test each component: run your commands, check agents appear in `/agents`, and verify hooks trigger correctly.

373 </Step>

374</Steps>

339 375

340When your plugin is ready to share:376### What changes when migrating

341 377

3421. **Add documentation**: Include a README.md with installation and usage instructions378| Standalone (`.claude/`) | Plugin |

3432. **Version your plugin**: Use semantic versioning in your `plugin.json`379| :---------------------------- | :------------------------------- |

3443. **Create or use a marketplace**: Distribute through plugin marketplaces for easy installation380| Only available in one project | Can be shared via marketplaces |

3454. **Test with others**: Have team members test the plugin before wider distribution381| Files in `.claude/commands/` | Files in `plugin-name/commands/` |

382| Hooks in `settings.json` | Hooks in `hooks/hooks.json` |

383| Must manually copy to share | Install with `/plugin install` |

346 384

347<Note>385<Note>

348 For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/docs/claude-code/plugins-reference).386 After migrating, you can remove the original files from `.claude/` to avoid duplicates. The plugin version will take precedence when loaded.

349</Note>387</Note>

350 388

351***

~~352~~

353## Next steps389## Next steps

354 390

355Now that you understand Claude Code's plugin system, here are suggested paths for different goals:391Now that you understand Claude Code's plugin system, here are suggested paths for different goals:

356 392

357### For plugin users393### For plugin users

358 394

359* **Discover plugins**: Browse community marketplaces for useful tools395* [Discover and install plugins](/en/discover-plugins): browse marketplaces and install plugins

360* **Team adoption**: Set up repository-level plugins for your projects396* [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 397

364### For plugin developers398### For plugin developers

365 399

366* **Create your first marketplace**: [Plugin marketplaces guide](/en/docs/claude-code/plugin-marketplaces)400* [Create and distribute a marketplace](/en/plugin-marketplaces): package and share your plugins

367* **Advanced components**: Dive deeper into specific plugin components:401* [Plugins reference](/en/plugins-reference): complete technical specifications

368 * [Slash commands](/en/docs/claude-code/slash-commands) - Command development details402* Dive deeper into specific plugin components:

369 * [Subagents](/en/docs/claude-code/sub-agents) - Agent configuration and capabilities403 * [Skills](/en/skills): skill development details

370 * [Agent Skills](/en/docs/claude-code/skills) - Extend Claude's capabilities404 * [Subagents](/en/sub-agents): agent configuration and capabilities

371 * [Hooks](/en/docs/claude-code/hooks) - Event handling and automation405 * [Hooks](/en/hooks): event handling and automation

372 * [MCP](/en/docs/claude-code/mcp) - External tool integration406 * [MCP](/en/mcp): external tool integration

373* **Distribution strategies**: Package and share your plugins effectively407

374* **Community contribution**: Consider contributing to community plugin collections408

~~375~~ 409---

376### For team leads and administrators410

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

378* **Repository configuration**: Set up automatic plugin installation for team projects

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/docs/claude-code/plugin-marketplaces) - Creating and managing plugin catalogs

386* [Slash commands](/en/docs/claude-code/slash-commands) - Understanding custom commands

387* [Subagents](/en/docs/claude-code/sub-agents) - Creating and using specialized agents

388* [Agent Skills](/en/docs/claude-code/skills) - Extend Claude's capabilities

389* [Hooks](/en/docs/claude-code/hooks) - Automating workflows with event handlers

390* [MCP](/en/docs/claude-code/mcp) - Connecting to external tools and services

391* [Settings](/en/docs/claude-code/settings) - Configuration options for plugins

plugins-reference.md +418 −59

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/docs/claude-code/plugins). For plugin management across teams and communities, see [Plugin marketplaces](/en/docs/claude-code/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.

10 10

11## Plugin components reference11## Plugin components reference

12 12

~~13This section documents the five types of components that plugins can provide.~~13This section documents the types of components that plugins can provide.

14 14

~~15### Commands~~15### Skills

17Plugins add skills to Claude Code, creating `/name` shortcuts that you or Claude can invoke.

19**Location**: `skills/` or `commands/` directory in plugin root

21**File format**: Skills are directories with `SKILL.md`; commands are simple markdown files

16 22

~~17Plugins add custom slash commands that integrate seamlessly with Claude Code's command system.~~23**Skill structure**:

25```

26skills/

27├── pdf-processor/

28│ ├── SKILL.md

29│ ├── reference.md (optional)

30│ └── scripts/ (optional)

31└── code-reviewer/

32 └── SKILL.md

33```

18 34

~~19**Location**: `commands/` directory in plugin root~~35**Integration behavior**:

20 36

~~21**File format**: Markdown files with frontmatter~~37* Skills and commands are automatically discovered when the plugin is installed

38* Claude can invoke them automatically based on task context

39* Skills can include supporting files alongside SKILL.md

22 40

~~23For complete details on plugin command structure, invocation patterns, and features, see [Plugin commands](/en/docs/claude-code/slash-commands#plugin-commands).~~41For complete details, see [Skills](/en/skills).

24 42

25### Agents43### Agents

26 44

58* Agents can be invoked manually by users76* Agents can be invoked manually by users

59* Plugin agents work alongside built-in Claude agents77* Plugin agents work alongside built-in Claude agents

60 78

~~61### Skills~~

~~63Plugins can provide Agent Skills that extend Claude's capabilities. Skills are model-invoked—Claude autonomously decides when to use them based on the task context.~~

~~65**Location**: `skills/` directory in plugin root~~

~~67**File format**: Directories containing `SKILL.md` files with frontmatter~~

~~69**Skill structure**:~~

~~71```~~

~~72skills/~~

~~73├── pdf-processor/~~

~~74│ ├── SKILL.md~~

~~75│ ├── reference.md (optional)~~

~~76│ └── scripts/ (optional)~~

~~77└── code-reviewer/~~

~~78 └── SKILL.md~~

~~79```~~

~~81**Integration behavior**:~~

~~83* Plugin Skills are automatically discovered when the plugin is installed~~

~~84* Claude autonomously invokes Skills based on matching task context~~

~~85* Skills can include supporting files alongside SKILL.md~~

~~87For SKILL.md format and complete Skill authoring guidance, see:~~

~~89* [Use Skills in Claude Code](/en/docs/claude-code/skills)~~

~~90* [Agent Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure)~~

92### Hooks79### Hooks

93 80

94Plugins can provide event handlers that respond to Claude Code events automatically.81Plugins can provide event handlers that respond to Claude Code events automatically.

120**Available events**:107**Available events**:

121 108

122* `PreToolUse`: Before Claude uses any tool109* `PreToolUse`: Before Claude uses any tool

123* `PostToolUse`: After Claude uses any tool110* `PostToolUse`: After Claude successfully uses any tool

111* `PostToolUseFailure`: After Claude tool execution fails

112* `PermissionRequest`: When a permission dialog is shown

124* `UserPromptSubmit`: When user submits a prompt113* `UserPromptSubmit`: When user submits a prompt

125* `Notification`: When Claude Code sends notifications114* `Notification`: When Claude Code sends notifications

126* `Stop`: When Claude attempts to stop115* `Stop`: When Claude attempts to stop

116* `SubagentStart`: When a subagent is started

127* `SubagentStop`: When a subagent attempts to stop117* `SubagentStop`: When a subagent attempts to stop

118* `Setup`: When `--init`, `--init-only`, or `--maintenance` flags are used

128* `SessionStart`: At the beginning of sessions119* `SessionStart`: At the beginning of sessions

129* `SessionEnd`: At the end of sessions120* `SessionEnd`: At the end of sessions

130* `PreCompact`: Before conversation history is compacted121* `PreCompact`: Before conversation history is compacted

132**Hook types**:123**Hook types**:

133 124

134* `command`: Execute shell commands or scripts125* `command`: Execute shell commands or scripts

135* `validation`: Validate file contents or project state126* `prompt`: Evaluate a prompt with an LLM (uses `$ARGUMENTS` placeholder for context)

136* `notification`: Send alerts or status updates127* `agent`: Run an agentic verifier with tools for complex verification tasks

137 128

138### MCP servers129### MCP servers

139 130

171* Server capabilities integrate seamlessly with Claude's existing tools162* Server capabilities integrate seamlessly with Claude's existing tools

172* Plugin servers can be configured independently of user MCP servers163* Plugin servers can be configured independently of user MCP servers

173 164

165### LSP servers

166

167<Tip>

168 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.

169</Tip>

170

171Plugins 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.

172

173LSP integration provides:

174

175* **Instant diagnostics**: Claude sees errors and warnings immediately after each edit

176* **Code navigation**: go to definition, find references, and hover information

177* **Language awareness**: type information and documentation for code symbols

178

179**Location**: `.lsp.json` in plugin root, or inline in `plugin.json`

180

181**Format**: JSON configuration mapping language server names to their configurations

182

183**`.lsp.json` file format**:

184

185```json theme={null}

186{

187 "go": {

188 "command": "gopls",

189 "args": ["serve"],

190 "extensionToLanguage": {

191 ".go": "go"

192 }

193 }

194}

195```

196

197**Inline in `plugin.json`**:

198

199```json theme={null}

200{

201 "name": "my-plugin",

202 "lspServers": {

203 "go": {

204 "command": "gopls",

205 "args": ["serve"],

206 "extensionToLanguage": {

207 ".go": "go"

208 }

209 }

210 }

211}

212```

213

214**Required fields:**

215

216| Field | Description |

217| :-------------------- | :------------------------------------------- |

218| `command` | The LSP binary to execute (must be in PATH) |

219| `extensionToLanguage` | Maps file extensions to language identifiers |

220

221**Optional fields:**

222

223| Field | Description |

224| :---------------------- | :-------------------------------------------------------- |

225| `args` | Command-line arguments for the LSP server |

226| `transport` | Communication transport: `stdio` (default) or `socket` |

227| `env` | Environment variables to set when starting the server |

228| `initializationOptions` | Options passed to the server during initialization |

229| `settings` | Settings passed via `workspace/didChangeConfiguration` |

230| `workspaceFolder` | Workspace folder path for the server |

231| `startupTimeout` | Max time to wait for server startup (milliseconds) |

232| `shutdownTimeout` | Max time to wait for graceful shutdown (milliseconds) |

233| `restartOnCrash` | Whether to automatically restart the server if it crashes |

234| `maxRestarts` | Maximum number of restart attempts before giving up |

235

236<Warning>

237 **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.

238</Warning>

239

240**Available LSP plugins:**

241

242| Plugin | Language server | Install command |

243| :--------------- | :------------------------- | :----------------------------------------------------------------------------------------- |

244| `pyright-lsp` | Pyright (Python) | `pip install pyright` or `npm install -g pyright` |

245| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |

246| `rust-lsp` | rust-analyzer | [See rust-analyzer installation](https://rust-analyzer.github.io/manual.html#installation) |

247

248Install the language server first, then install the plugin from the marketplace.

249

250***

251

252## Plugin installation scopes

253

254When you install a plugin, you choose a **scope** that determines where the plugin is available and who else can use it:

255

256| Scope | Settings file | Use case |

257| :-------- | :---------------------------- | :------------------------------------------------------- |

258| `user` | `~/.claude/settings.json` | Personal plugins available across all projects (default) |

259| `project` | `.claude/settings.json` | Team plugins shared via version control |

260| `local` | `.claude/settings.local.json` | Project-specific plugins, gitignored |

261| `managed` | `managed-settings.json` | Managed plugins (read-only, update only) |

262

263Plugins 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).

264

174***265***

175 266

176## Plugin manifest schema267## Plugin manifest schema

195 "keywords": ["keyword1", "keyword2"],286 "keywords": ["keyword1", "keyword2"],

196 "commands": ["./custom/commands/special.md"],287 "commands": ["./custom/commands/special.md"],

197 "agents": "./custom/agents/",288 "agents": "./custom/agents/",

289 "skills": "./custom/skills/",

198 "hooks": "./config/hooks.json",290 "hooks": "./config/hooks.json",

199 "mcpServers": "./mcp-config.json"291 "mcpServers": "./mcp-config.json",

292 "outputStyles": "./styles/",

293 "lspServers": "./.lsp.json"

200}294}

201```295```

202 296

221### Component path fields315### Component path fields

222 316

224| :----------- | :------------- | :----------------------------------- | :------------------------------------- |318| :------------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- |

229 326

230### Path behavior rules327### Path behavior rules

231 328

274 371

275***372***

276 373

374## Plugin caching and file resolution

375

376For 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.

377

378### How plugin caching works

379

380When you install a plugin, Claude Code copies the plugin files to a cache directory:

381

382* **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.

383* **For plugins with `.claude-plugin/plugin.json`**: The implicit root directory (the directory containing `.claude-plugin/plugin.json`) is copied recursively.

384

385### Path traversal limitations

386

387Plugins 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.

388

389### Working with external dependencies

390

391If your plugin needs to access files outside its directory, you have two options:

392

393**Option 1: Use symlinks**

394

395Create symbolic links to external files within your plugin directory. Symlinks are honored during the copy process:

396

397```bash theme={null}

398# Inside your plugin directory

399ln -s /path/to/shared-utils ./shared-utils

400```

401

402The symlinked content will be copied into the plugin cache.

403

404**Option 2: Restructure your marketplace**

405

406Set 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:

407

408```json theme={null}

409{

410 "name": "my-plugin",

411 "source": "./",

412 "description": "Plugin that needs root-level access",

413 "commands": ["./plugins/my-plugin/commands/"],

414 "agents": ["./plugins/my-plugin/agents/"],

415 "strict": false

416}

417```

418

419This approach copies the entire marketplace root, giving your plugin access to sibling directories.

420

421<Note>

422 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.

423</Note>

424

425***

426

277## Plugin directory structure427## Plugin directory structure

278 428

279### Standard plugin layout429### Standard plugin layout

301│ ├── hooks.json # Main hook config451│ ├── hooks.json # Main hook config

302│ └── security-hooks.json # Additional hooks452│ └── security-hooks.json # Additional hooks

303├── .mcp.json # MCP server definitions453├── .mcp.json # MCP server definitions

454├── .lsp.json # LSP server configurations

304├── scripts/ # Hook and utility scripts455├── scripts/ # Hook and utility scripts

305│ ├── security-scan.sh456│ ├── security-scan.sh

306│ ├── format-code.py457│ ├── format-code.py

316### File locations reference467### File locations reference

317 468

319| :-------------- | :--------------------------- | :------------------------------- |470| :-------------- | :--------------------------- | :---------------------------------------------------------- |

477| **LSP servers** | `.lsp.json` | Language server configurations |

478

479***

480

481## CLI commands reference

482

483Claude Code provides CLI commands for non-interactive plugin management, useful for scripting and automation.

484

485### plugin install

486

487Install a plugin from available marketplaces.

488

489```bash theme={null}

490claude plugin install <plugin> [options]

491```

492

493**Arguments:**

494

495* `<plugin>`: Plugin name or `plugin-name@marketplace-name` for a specific marketplace

496

497**Options:**

498

499| Option | Description | Default |

500| :-------------------- | :------------------------------------------------ | :------ |

501| `-s, --scope <scope>` | Installation scope: `user`, `project`, or `local` | `user` |

502| `-h, --help` | Display help for command | |

503

504**Examples:**

505

506```bash theme={null}

507# Install to user scope (default)

508claude plugin install formatter@my-marketplace

509

510# Install to project scope (shared with team)

511claude plugin install formatter@my-marketplace --scope project

512

513# Install to local scope (gitignored)

514claude plugin install formatter@my-marketplace --scope local

515```

516

517### plugin uninstall

518

519Remove an installed plugin.

520

521```bash theme={null}

522claude plugin uninstall <plugin> [options]

523```

524

525**Arguments:**

526

527* `<plugin>`: Plugin name or `plugin-name@marketplace-name`

528

529**Options:**

530

531| Option | Description | Default |

532| :-------------------- | :-------------------------------------------------- | :------ |

533| `-s, --scope <scope>` | Uninstall from scope: `user`, `project`, or `local` | `user` |

534| `-h, --help` | Display help for command | |

535

536**Aliases:** `remove`, `rm`

537

538### plugin enable

539

540Enable a disabled plugin.

541

542```bash theme={null}

543claude plugin enable <plugin> [options]

544```

545

546**Arguments:**

547

548* `<plugin>`: Plugin name or `plugin-name@marketplace-name`

549

550**Options:**

551

552| Option | Description | Default |

553| :-------------------- | :--------------------------------------------- | :------ |

554| `-s, --scope <scope>` | Scope to enable: `user`, `project`, or `local` | `user` |

555| `-h, --help` | Display help for command | |

556

557### plugin disable

558

559Disable a plugin without uninstalling it.

560

561```bash theme={null}

562claude plugin disable <plugin> [options]

563```

564

565**Arguments:**

566

567* `<plugin>`: Plugin name or `plugin-name@marketplace-name`

568

569**Options:**

570

571| Option | Description | Default |

572| :-------------------- | :---------------------------------------------- | :------ |

573| `-s, --scope <scope>` | Scope to disable: `user`, `project`, or `local` | `user` |

574| `-h, --help` | Display help for command | |

575

576### plugin update

577

578Update a plugin to the latest version.

579

580```bash theme={null}

581claude plugin update <plugin> [options]

582```

583

584**Arguments:**

585

586* `<plugin>`: Plugin name or `plugin-name@marketplace-name`

587

588**Options:**

589

590| Option | Description | Default |

591| :-------------------- | :-------------------------------------------------------- | :------ |

592| `-s, --scope <scope>` | Scope to update: `user`, `project`, `local`, or `managed` | `user` |

593| `-h, --help` | Display help for command | |

326 594

327***595***

328 596

346### Common issues614### Common issues

347 615

349| :--------------------- | :------------------------------ | :--------------------------------------------------- |617| :---------------------------------- | :------------------------------ | :-------------------------------------------------------------------------------- |

353| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths |621| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths |

623| LSP `Executable not found in $PATH` | Language server not installed | Install the binary (e.g., `npm install -g typescript-language-server typescript`) |

624

625### Example error messages

626

627**Manifest validation errors**:

628

629* `Invalid JSON syntax: Unexpected token } in JSON at position 142`: check for missing commas, extra commas, or unquoted strings

630* `Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required`: a required field is missing

631* `Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...`: JSON syntax error

632

633**Plugin loading errors**:

634

635* `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

636* `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

637* `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

638

639### Hook troubleshooting

640

641**Hook script not executing**:

642

6431. Check the script is executable: `chmod +x ./scripts/your-script.sh`

6442. Verify the shebang line: First line should be `#!/bin/bash` or `#!/usr/bin/env bash`

6453. Check the path uses `${CLAUDE_PLUGIN_ROOT}`: `"command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"`

6464. Test the script manually: `./scripts/your-script.sh`

647

648**Hook not triggering on expected events**:

649

6501. Verify the event name is correct (case-sensitive): `PostToolUse`, not `postToolUse`

6512. Check the matcher pattern matches your tools: `"matcher": "Write|Edit"` for file operations

6523. Confirm the hook type is valid: `command`, `prompt`, or `agent`

653

654### MCP server troubleshooting

655

656**Server not starting**:

657

6581. Check the command exists and is executable

6592. Verify all paths use `${CLAUDE_PLUGIN_ROOT}` variable

6603. Check the MCP server logs: `claude --debug` shows initialization errors

6614. Test the server manually outside of Claude Code

662

663**Server tools not appearing**:

664

6651. Ensure the server is properly configured in `.mcp.json` or `plugin.json`

6662. Verify the server implements the MCP protocol correctly

6673. Check for connection timeouts in debug output

668

669### Directory structure mistakes

670

671**Symptoms**: Plugin loads but components (commands, agents, hooks) are missing.

672

673**Correct structure**: Components must be at the plugin root, not inside `.claude-plugin/`. Only `plugin.json` belongs in `.claude-plugin/`.

674

675```

676my-plugin/

677├── .claude-plugin/

678│ └── plugin.json ← Only manifest here

679├── commands/ ← At root level

680├── agents/ ← At root level

681└── hooks/ ← At root level

682```

683

684If your components are inside `.claude-plugin/`, move them to the plugin root.

685

686**Debug checklist**:

687

6881. Run `claude --debug` and look for "loading plugin" messages

6892. Check that each component directory is listed in the debug output

6903. Verify file permissions allow reading the plugin files

355 691

356***692***

357 693

362Follow semantic versioning for plugin releases:698Follow semantic versioning for plugin releases:

363 699

364```json theme={null}700```json theme={null}

701{

702 "name": "my-plugin",

703 "version": "2.1.0"

704}

705```

706

707**Version format**: `MAJOR.MINOR.PATCH`

708

709* **MAJOR**: Breaking changes (incompatible API changes)

710* **MINOR**: New features (backward-compatible additions)

711* **PATCH**: Bug fixes (backward-compatible fixes)

712

713**Best practices**:

714

715* Start at `1.0.0` for your first stable release

716* Update the version in `plugin.json` before distributing changes

717* Document changes in a `CHANGELOG.md` file

718* Use pre-release versions like `2.0.0-beta.1` for testing

719

720***

365 721

366## See also722## See also

367 723

368- [Plugins](/en/docs/claude-code/plugins) - Tutorials and practical usage724* [Plugins](/en/plugins) - Tutorials and practical usage

369- [Plugin marketplaces](/en/docs/claude-code/plugin-marketplaces) - Creating and managing marketplaces725* [Plugin marketplaces](/en/plugin-marketplaces) - Creating and managing marketplaces

370- [Slash commands](/en/docs/claude-code/slash-commands) - Command development details726* [Skills](/en/skills) - Skill development details

371- [Subagents](/en/docs/claude-code/sub-agents) - Agent configuration and capabilities727* [Subagents](/en/sub-agents) - Agent configuration and capabilities

372- [Agent Skills](/en/docs/claude-code/skills) - Extend Claude's capabilities728* [Hooks](/en/hooks) - Event handling and automation

373- [Hooks](/en/docs/claude-code/hooks) - Event handling and automation729* [MCP](/en/mcp) - External tool integration

374- [MCP](/en/docs/claude-code/mcp) - External tool integration730* [Settings](/en/settings) - Configuration options for plugins

375- [Settings](/en/docs/claude-code/settings) - Configuration options for plugins731

376```732

733---

734

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

quickstart.md +58 −39

Details

10 10

11* A terminal or command prompt open11* A terminal or command prompt open

12* A code project to work with12* A code project to work with

~~13* A [Claude.ai](https://claude.ai) (recommended) or [Claude Console](https://console.anthropic.com/) account~~13* A [Claude subscription](https://claude.com/pricing) (Pro, Max, Teams, or Enterprise) or [Claude Console](https://console.anthropic.com/) account

14 14

15## Step 1: Install Claude Code15## Step 1: Install Claude Code

16 16

~~17### NPM Install~~17To install Claude Code, use one of the following methods:

18 18

~~19If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):~~19<Tabs>

20 <Tab title="Native Install (Recommended)">

21 **macOS, Linux, WSL:**

20 22

~~21```sh theme={null}~~23 ```bash theme={null}

~~22npm install -g @anthropic-ai/claude-code~~24 curl -fsSL https://claude.ai/install.sh | bash

~~23```~~25 ```

~~25### Native Install~~

26 26

~~27<Tip>~~27 **Windows PowerShell:**

~~28 Alternatively, try our new native install, now in beta.~~

~~29</Tip>~~

30 28

~~31**Homebrew (macOS, Linux):**~~29 ```powershell theme={null}

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

31 ```

32 32

~~33```sh theme={null}~~33 **Windows CMD:**

~~34brew install --cask claude-code~~

~~35```~~

36 34

~~37**macOS, Linux, WSL:**~~35 ```batch theme={null}

36 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

37 ```

38 38

~~39```bash theme={null}~~39 <Info>

~~40curl -fsSL https://claude.ai/install.sh | bash~~40 Native installations automatically update in the background to keep you on the latest version.

~~41```~~41 </Info>

42 </Tab>

42 43

~~43**Windows PowerShell:**~~44 <Tab title="Homebrew">

45 ```sh theme={null}

46 brew install --cask claude-code

47 ```

44 48

~~45```powershell theme={null}~~49 <Info>

~~46irm https://claude.ai/install.ps1 | iex~~50 Homebrew installations do not auto-update. Run `brew upgrade claude-code` periodically to get the latest features and security fixes.

~~47```~~51 </Info>

52 </Tab>

48 53

~~49**Windows CMD:**~~54 <Tab title="WinGet">

55 ```powershell theme={null}

56 winget install Anthropic.ClaudeCode

57 ```

50 58

~~51```batch theme={null}~~59 <Info>

~~52curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd~~60 WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.

~~53```~~61 </Info>

62 </Tab>

63</Tabs>

54 64

55## Step 2: Log in to your account65## Step 2: Log in to your account

56 66

66# Follow the prompts to log in with your account76# Follow the prompts to log in with your account

67```77```

68 78

~~69You can log in using either account type:~~79You can log in using any of these account types:

70 80

~~71* [Claude.ai](https://claude.ai) (subscription plans - recommended)~~81* [Claude Pro, Max, Teams, or Enterprise](https://claude.com/pricing) (recommended)

72* [Claude Console](https://console.anthropic.com/) (API access with pre-paid credits)82* [Claude Console](https://console.anthropic.com/) (API access with pre-paid credits)

73 83

74Once logged in, your credentials are stored and you won't need to log in again.84Once logged in, your credentials are stored and you won't need to log in again.

93You'll see the Claude Code welcome screen with your session information, recent conversations, and latest updates. Type `/help` for available commands or `/resume` to continue a previous conversation.103You'll see the Claude Code welcome screen with your session information, recent conversations, and latest updates. Type `/help` for available commands or `/resume` to continue a previous conversation.

94 104

95<Tip>105<Tip>

~~96 After logging in (Step 2), your credentials are stored on your system. Learn more in [Credential Management](/en/docs/claude-code/iam#credential-management).~~106 After logging in (Step 2), your credentials are stored on your system. Learn more in [Credential Management](/en/iam#credential-management).

97</Tip>107</Tip>

98 108

99## Step 4: Ask your first question109## Step 4: Ask your first question

125```135```

126 136

127```137```

128> how do I use slash commands in Claude Code?138> how do I create custom skills in Claude Code?

129```139```

130 140

131```141```

241Here are the most important commands for daily use:251Here are the most important commands for daily use:

242 252

244| ------------------- | --------------------------------- | ----------------------------------- |254| ------------------- | ------------------------------------------------------ | ----------------------------------- |

254 264

255See the [CLI reference](/en/docs/claude-code/cli-reference) for a complete list of commands.265See the [CLI reference](/en/cli-reference) for a complete list of commands.

256 266

257## Pro tips for beginners267## Pro tips for beginners

258 268

295 * Press `?` to see all available keyboard shortcuts305 * Press `?` to see all available keyboard shortcuts

296 * Use Tab for command completion306 * Use Tab for command completion

297 * Press ↑ for command history307 * Press ↑ for command history

298 * Type `/` to see all slash commands308 * Type `/` to see all commands and skills

299 </Accordion>309 </Accordion>

300</AccordionGroup>310</AccordionGroup>

301 311

304Now that you've learned the basics, explore more advanced features:314Now that you've learned the basics, explore more advanced features:

305 315

306<CardGroup cols={3}>316<CardGroup cols={3}>

307 <Card title="Common workflows" icon="graduation-cap" href="/en/docs/claude-code/common-workflows">317 <Card title="Common workflows" icon="graduation-cap" href="/en/common-workflows">

308 Step-by-step guides for common tasks318 Step-by-step guides for common tasks

309 </Card>319 </Card>

310 320

311 <Card title="CLI reference" icon="terminal" href="/en/docs/claude-code/cli-reference">321 <Card title="CLI reference" icon="terminal" href="/en/cli-reference">

312 Master all commands and options322 Master all commands and options

313 </Card>323 </Card>

314 324

315 <Card title="Configuration" icon="gear" href="/en/docs/claude-code/settings">325 <Card title="Configuration" icon="gear" href="/en/settings">

316 Customize Claude Code for your workflow326 Customize Claude Code for your workflow

317 </Card>327 </Card>

318 328

319 <Card title="Claude Code on the web" icon="cloud" href="/en/docs/claude-code/claude-code-on-the-web">329 <Card title="Claude Code on the web" icon="cloud" href="/en/claude-code-on-the-web">

320 Run tasks asynchronously in the cloud330 Run tasks asynchronously in the cloud

321 </Card>331 </Card>

332

333 <Card title="About Claude Code" icon="sparkles" href="https://claude.com/product/claude-code">

334 Learn more on claude.com

335 </Card>

322</CardGroup>336</CardGroup>

323 337

324## Getting help338## Getting help

326* **In Claude Code**: Type `/help` or ask "how do I..."340* **In Claude Code**: Type `/help` or ask "how do I..."

327* **Documentation**: You're here! Browse other guides341* **Documentation**: You're here! Browse other guides

328* **Community**: Join our [Discord](https://www.anthropic.com/discord) for tips and support342* **Community**: Join our [Discord](https://www.anthropic.com/discord) for tips and support

343

344

345---

346

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

sandboxing.md +36 −13

Details

60 60

61### Enable sandboxing61### Enable sandboxing

62 62

~~63You can enable sandboxing by running the `/sandbox` slash command:~~63You can enable sandboxing by running the `/sandbox` command:

64 64

65```65```

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

~~73Customize sandbox behavior through your `settings.json` file. See [Settings](/en/docs/claude-code/settings#sandbox-settings) for complete configuration reference.~~87Customize sandbox behavior through your `settings.json` file. See [Settings](/en/settings#sandbox-settings) for complete configuration reference.

74 88

75<Tip>89<Tip>

76 Not all commands are compatible with sandboxing out of the box. Some notes that may help you make the most out of the sandbox:90 Not all commands are compatible with sandboxing out of the box. Some notes that may help you make the most out of the sandbox:

82 96

83<Note>97<Note>

84 Claude Code includes an intentional escape hatch mechanism that allows commands to run outside the sandbox when necessary. When a command fails due to sandbox restrictions (such as network connectivity issues or incompatible tools), Claude is prompted to analyze the failure and may retry the command with the `dangerouslyDisableSandbox` parameter. Commands that use this parameter go through the normal Claude Code permissions flow requiring user permission to execute. This allows Claude Code to handle edge cases where certain tools or network operations cannot function within sandbox constraints.98 Claude Code includes an intentional escape hatch mechanism that allows commands to run outside the sandbox when necessary. When a command fails due to sandbox restrictions (such as network connectivity issues or incompatible tools), Claude is prompted to analyze the failure and may retry the command with the `dangerouslyDisableSandbox` parameter. Commands that use this parameter go through the normal Claude Code permissions flow requiring user permission to execute. This allows Claude Code to handle edge cases where certain tools or network operations cannot function within sandbox constraints.

100 You can disable this escape hatch by setting `"allowUnsandboxedCommands": false` in your [sandbox settings](/en/settings#sandbox-settings). When disabled, the `dangerouslyDisableSandbox` parameter is completely ignored and all commands must run sandboxed or be explicitly listed in `excludedCommands`.

85</Note>101</Note>

86 102

87## Security benefits103## Security benefits

94 110

95* Cannot modify critical config files such as `~/.bashrc`111* Cannot modify critical config files such as `~/.bashrc`

96* Cannot modify system-level files in `/bin/`112* Cannot modify system-level files in `/bin/`

~~97* Cannot read files that are denied in your [Claude permission settings](/en/docs/claude-code/iam#configuring-permissions)~~113* Cannot read files that are denied in your [Claude permission settings](/en/iam#configuring-permissions)

98 114

99**Network protection:**115**Network protection:**

100 116

139 155

140* 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.

141* 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.

142* 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.

143 159

144## Advanced usage160## Advanced usage

145 161

155```json theme={null}171```json theme={null}

156{172{

157 "sandbox": {173 "sandbox": {

174 "network": {

158 "httpProxyPort": 8080,175 "httpProxyPort": 8080,

159 "socksProxyPort": 8081,176 "socksProxyPort": 8081

177 }

160 }178 }

161}179}

162```180```

165 183

166The sandboxed bash tool works alongside:184The sandboxed bash tool works alongside:

167 185

168* **IAM policies**: Combine with [permission settings](/en/docs/claude-code/iam) for defense-in-depth186* **IAM policies**: Combine with [permission settings](/en/iam) for defense-in-depth

169* **Development containers**: Use with [devcontainers](/en/docs/claude-code/devcontainer) for additional isolation187* **Development containers**: Use with [devcontainers](/en/devcontainer) for additional isolation

170* **Enterprise policies**: Enforce sandbox configurations through [managed settings](/en/docs/claude-code/settings#settings-precedence)188* **Enterprise policies**: Enforce sandbox configurations through [managed settings](/en/settings#settings-precedence)

171 189

172## Best practices190## Best practices

173 191

195 213

196## See also214## See also

197 215

198* [Security](/en/docs/claude-code/security) - Comprehensive security features and best practices216* [Security](/en/security) - Comprehensive security features and best practices

199* [IAM](/en/docs/claude-code/iam) - Permission configuration and access control217* [IAM](/en/iam) - Permission configuration and access control

200* [Settings](/en/docs/claude-code/settings) - Complete configuration reference218* [Settings](/en/settings) - Complete configuration reference

201* [CLI reference](/en/docs/claude-code/cli-reference) - Command-line options including `-sb`219* [CLI reference](/en/cli-reference) - Command-line options

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](/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/docs/claude-code/troubleshooting) guide for common issues.

~~321~~

322## Next Steps

~~323~~

324* Explore the [Agent SDK Overview](/en/api/agent-sdk/overview) to learn about available features

325* Check out the [TypeScript SDK Reference](/en/api/agent-sdk/typescript) for detailed API documentation

326* Review the [Python SDK Reference](/en/api/agent-sdk/python) for Python-specific documentation

327* Learn about [Custom Tools](/en/api/agent-sdk/custom-tools) and [MCP Integration](/en/api/agent-sdk/mcp)

security.md +20 −15

Details

14 14

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

16 16

~~17For detailed permission configuration, see [Identity and Access Management](/en/docs/claude-code/iam).~~17For detailed permission configuration, see [Identity and Access Management](/en/iam).

18 18

19### Built-in protections19### Built-in protections

20 20

21To mitigate risks in agentic systems:21To mitigate risks in agentic systems:

22 22

23* **Sandboxed bash tool**: [Sandbox](/en/docs/claude-code/sandboxing) bash commands with filesystem and network isolation, reducing permission prompts while maintaining security. Enable with `/sandbox` to define boundaries where Claude Code can work autonomously23* **Sandboxed bash tool**: [Sandbox](/en/sandboxing) bash commands with filesystem and network isolation, reducing permission prompts while maintaining security. Enable with `/sandbox` to define boundaries where Claude Code can work autonomously

24* **Write access restriction**: Claude Code can only write to the folder where it was started and its subfolders—it cannot modify files in parent directories without explicit permission. While Claude Code can read files outside the working directory (useful for accessing system libraries and dependencies), write operations are strictly confined to the project scope, creating a clear security boundary24* **Write access restriction**: Claude Code can only write to the folder where it was started and its subfolders—it cannot modify files in parent directories without explicit permission. While Claude Code can read files outside the working directory (useful for accessing system libraries and dependencies), write operations are strictly confined to the project scope, creating a clear security boundary

25* **Prompt fatigue mitigation**: Support for allowlisting frequently used safe commands per-user, per-codebase, or per-organization25* **Prompt fatigue mitigation**: Support for allowlisting frequently used safe commands per-user, per-codebase, or per-organization

26* **Accept Edits mode**: Batch accept multiple edits while maintaining permission prompts for commands with side effects26* **Accept Edits mode**: Batch accept multiple edits while maintaining permission prompts for commands with side effects

38* **Permission system**: Sensitive operations require explicit approval38* **Permission system**: Sensitive operations require explicit approval

39* **Context-aware analysis**: Detects potentially harmful instructions by analyzing the full request39* **Context-aware analysis**: Detects potentially harmful instructions by analyzing the full request

40* **Input sanitization**: Prevents command injection by processing user inputs40* **Input sanitization**: Prevents command injection by processing user inputs

41* **Command blocklist**: Blocks risky commands that fetch arbitrary content from the web like `curl` and `wget` by default. When explicitly allowed, be aware of [permission pattern limitations](/en/docs/claude-code/iam#tool-specific-permission-rules)41* **Command blocklist**: Blocks risky commands that fetch arbitrary content from the web like `curl` and `wget` by default. When explicitly allowed, be aware of [permission pattern limitations](/en/iam#tool-specific-permission-rules)

42 42

43### Privacy safeguards43### Privacy safeguards

44 44

59* **Command injection detection**: Suspicious bash commands require manual approval even if previously allowlisted59* **Command injection detection**: Suspicious bash commands require manual approval even if previously allowlisted

60* **Fail-closed matching**: Unmatched commands default to requiring manual approval60* **Fail-closed matching**: Unmatched commands default to requiring manual approval

61* **Natural language descriptions**: Complex bash commands include explanations for user understanding61* **Natural language descriptions**: Complex bash commands include explanations for user understanding

~~62* **Secure credential storage**: API keys and tokens are encrypted. See [Credential Management](/en/docs/claude-code/iam#credential-management)~~62* **Secure credential storage**: API keys and tokens are encrypted. See [Credential Management](/en/iam#credential-management)

63 63

64<Warning>64<Warning>

65 **Windows WebDAV security risk**: We recommend against enabling WebDAV when running Claude Code on Windows. [WebDAV has been deprecated by Microsoft](https://learn.microsoft.com/en-us/windows/whats-new/deprecated-features#:~:text=The%20Webclient%20$WebDAV$%20service%20is%20deprecated) due to security risks. Enabling WebDAV may allow Claude Code to trigger network requests to remote hosts, bypassing the permission system.65 **Windows WebDAV security risk**: When running Claude Code on Windows, we recommend against enabling WebDAV or allowing Claude Code to access paths such as `\\*` that may contain WebDAV subdirectories. [WebDAV has been deprecated by Microsoft](https://learn.microsoft.com/en-us/windows/whats-new/deprecated-features#:~:text=The%20Webclient%20$WebDAV$%20service%20is%20deprecated) due to security risks. Enabling WebDAV may allow Claude Code to trigger network requests to remote hosts, bypassing the permission system.

66</Warning>66</Warning>

67 67

68**Best practices for working with untrusted content**:68**Best practices for working with untrusted content**:

87 87

88## IDE security88## IDE security

89 89

~~90See [here](/en/docs/claude-code/ide-integrations#security) for more information on the security of running Claude Code in an IDE.~~90See [VS Code security and privacy](/en/vs-code#security-and-privacy) for more information on running Claude Code in an IDE.

91 91

92## Cloud execution security92## Cloud execution security

93 93

~~94When using [Claude Code on the web](/en/docs/claude-code/claude-code-on-the-web), additional security controls are in place:~~94When using [Claude Code on the web](/en/claude-code-on-the-web), additional security controls are in place:

95 95

96* **Isolated virtual machines**: Each cloud session runs in an isolated, Anthropic-managed VM96* **Isolated virtual machines**: Each cloud session runs in an isolated, Anthropic-managed VM

97* **Network access controls**: Network access is limited by default and can be configured to be disabled or allow only specific domains97* **Network access controls**: Network access is limited by default and can be configured to be disabled or allow only specific domains

100* **Audit logging**: All operations in cloud environments are logged for compliance and audit purposes100* **Audit logging**: All operations in cloud environments are logged for compliance and audit purposes

101* **Automatic cleanup**: Cloud environments are automatically terminated after session completion101* **Automatic cleanup**: Cloud environments are automatically terminated after session completion

102 102

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

104 104

105## Security best practices105## Security best practices

106 106

108 108

109* Review all suggested changes before approval109* Review all suggested changes before approval

110* Use project-specific permission settings for sensitive repositories110* Use project-specific permission settings for sensitive repositories

111* Consider using [devcontainers](/en/docs/claude-code/devcontainer) for additional isolation111* Consider using [devcontainers](/en/devcontainer) for additional isolation

112* Regularly audit your permission settings with `/permissions`112* Regularly audit your permission settings with `/permissions`

113 113

114### Team security114### Team security

115 115

116* Use [enterprise managed policies](/en/docs/claude-code/iam#enterprise-managed-policy-settings) to enforce organizational standards116* Use [managed settings](/en/iam#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/docs/claude-code/monitoring-usage)119* Monitor Claude Code usage through [OpenTelemetry metrics](/en/monitoring-usage)

120 120

121### Reporting security issues121### Reporting security issues

122 122

129 129

130## Related resources130## Related resources

131 131

132* [Sandboxing](/en/docs/claude-code/sandboxing) - Filesystem and network isolation for bash commands132* [Sandboxing](/en/sandboxing) - Filesystem and network isolation for bash commands

133* [Identity and Access Management](/en/docs/claude-code/iam) - Configure permissions and access controls133* [Identity and Access Management](/en/iam) - Configure permissions and access controls

134* [Monitoring usage](/en/docs/claude-code/monitoring-usage) - Track and audit Claude Code activity134* [Monitoring usage](/en/monitoring-usage) - Track and audit Claude Code activity

135* [Development containers](/en/docs/claude-code/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 +634 −89

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**Managed 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. **Managed** (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**: For organizations that need centralized control, Claude Code supports `managed-settings.json` and `managed-mcp.json` files that can be deployed to system directories:

~~18 managed policy settings**. These take precedence over user and project~~83

~~19 settings. System administrators can deploy policies to:~~84 * macOS: `/Library/Application Support/ClaudeCode/`

~~20 * macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`~~85 * Linux and WSL: `/etc/claude-code/`

~~21 * Linux and WSL: `/etc/claude-code/managed-settings.json`~~86 * Windows: `C:\Program Files\ClaudeCode\`

~~22 * Windows: `C:\ProgramData\ClaudeCode\managed-settings.json`~~87

~~23* Enterprise deployments can also configure **managed MCP servers** that override~~88 <Note>

~~24 user-configured servers. See [Enterprise MCP configuration](/en/docs/claude-code/mcp#enterprise-mcp-configuration):~~89 These are system-wide paths (not user home directories like `~/Library/...`) that require administrator privileges. They are designed to be deployed by IT administrators.

~~25 * macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`~~90 </Note>

~~26 * Linux and WSL: `/etc/claude-code/managed-mcp.json`~~91

~~27 * Windows: `C:\ProgramData\ClaudeCode\managed-mcp.json`~~92 See [Managed settings](/en/iam#managed-settings) and [Managed MCP configuration](/en/mcp#managed-mcp-configuration) for details.

94 <Note>

95 Managed deployments can also restrict **plugin marketplace additions** using

96 `strictKnownMarketplaces`. For more information, see [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions).

97 </Note>

98* **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 99

29```JSON Example settings.json theme={null}100```JSON Example settings.json theme={null}

30{101{

44 "env": {115 "env": {

45 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",116 "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

46 "OTEL_METRICS_EXPORTER": "otlp"117 "OTEL_METRICS_EXPORTER": "otlp"

~~47 }~~118 },

119 "companyAnnouncements": [

120 "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",

121 "Reminder: Code reviews required for all PRs",

122 "New security policy in effect"

123 ]

48}124}

49```125```

50 126

53`settings.json` supports a number of options:129`settings.json` supports a number of options:

54 130

55| Key | Description | Example |131| Key | Description | Example |

56| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |132| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- |

57| `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` |133| `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` |

58| `cleanupPeriodDays` | How long to locally retain chat transcripts based on last activity date (default: 30 days) | `20` |134| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup. Setting to `0` immediately deletes all sessions. (default: 30 days) | `20` |

135| `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"]` |

59| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |136| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |

60| `includeCoAuthoredBy` | Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |137| `attribution` | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

138| `includeCoAuthoredBy` | **Deprecated**: Use `attribution` instead. Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |

62| `hooks` | Configure custom commands to run before or after tool executions. See [hooks documentation](hooks) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |140| `hooks` | Configure custom commands to run before or after tool executions. See [hooks documentation](/en/hooks) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |

142| `allowManagedHooksOnly` | (Managed settings only) Prevent loading of user, project, and plugin hooks. Only allows managed hooks and SDK hooks. See [Hook configuration](#hook-configuration) | `true` |

65| `statusLine` | Configure a custom status line to display context. See [statusLine documentation](statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |144| `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` |

66| `outputStyle` | Configure an output style to adjust the system prompt. See [output styles documentation](output-styles) | `"Explanatory"` |145| `statusLine` | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |

146| `fileSuggestion` | Configure a custom script for `@` file autocomplete. See [File suggestion settings](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

147| `respectGitignore` | Control whether the `@` file picker respects `.gitignore` patterns. When `true` (default), files matching `.gitignore` patterns are excluded from suggestions | `false` |

148| `outputStyle` | Configure an output style to adjust the system prompt. See [output styles documentation](/en/output-styles) | `"Explanatory"` |

68| `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"` |150| `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"` |

72| `useEnterpriseMcpConfigOnly` | When set in managed-settings.json, restricts MCP servers to only those defined in managed-mcp.json. See [Enterprise MCP configuration](/en/docs/claude-code/mcp#enterprise-mcp-configuration) | `true` |154| `allowedMcpServers` | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration) | `[{ "serverName": "github" }]` |

73| `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/docs/claude-code/mcp#enterprise-mcp-configuration) | `[{ "serverName": "github" }]` |155| `deniedMcpServers` | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including managed servers. Denylist takes precedence over allowlist. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration) | `[{ "serverName": "filesystem" }]` |

74| `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/docs/claude-code/mcp#enterprise-mcp-configuration) | `[{ "serverName": "filesystem" }]` |156| `strictKnownMarketplaces` | When set in managed-settings.json, allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

75| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/docs/claude-code/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |157| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

76| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/docs/claude-code/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |158| `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| `alwaysThinkingEnabled` | Enable [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) by default for all sessions. Typically configured via the `/config` command rather than editing directly | `true` |

160| `plansDirectory` | Customize where plan files are stored. Path is relative to project root. Default: `~/.claude/plans` | `"./plans"` |

161| `showTurnDuration` | Show turn duration messages after responses (e.g., "Cooked for 1m 6s"). Set to `false` to hide these messages | `true` |

162| `language` | Configure Claude's preferred response language (e.g., `"japanese"`, `"spanish"`, `"french"`). Claude will respond in this language by default | `"japanese"` |

163| `autoUpdatesChannel` | Release channel to follow for updates. Use `"stable"` for a version that is typically about one week old and skips versions with major regressions, or `"latest"` (default) for the most recent release | `"stable"` |

164| `spinnerTipsEnabled` | Show tips in the spinner while Claude is working. Set to `false` to disable tips (default: `true`) | `false` |

165| `terminalProgressBarEnabled` | Enable the terminal progress bar that shows progress in supported terminals like Windows Terminal and iTerm2 (default: `true`) | `false` |

77 166

78### Permission settings167### Permission settings

79 168

81| :----------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |170| :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |

82| `allow` | Array of [permission rules](/en/docs/claude-code/iam#configuring-permissions) to allow tool use. **Note:** Bash rules use prefix matching, not regex | `[ "Bash(git diff:*)" ]` |171| `allow` | Array of permission rules to allow tool use. See [Permission rule syntax](#permission-rule-syntax) below for pattern matching details | `[ "Bash(git diff:*)" ]` |

83| `ask` | Array of [permission rules](/en/docs/claude-code/iam#configuring-permissions) to ask for confirmation upon tool use. | `[ "Bash(git push:*)" ]` |172| `ask` | Array of permission rules to ask for confirmation upon tool use. See [Permission rule syntax](#permission-rule-syntax) below | `[ "Bash(git push:*)" ]` |

84| `deny` | Array of [permission rules](/en/docs/claude-code/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/docs/claude-code/iam#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |173| `deny` | Array of permission rules to deny tool use. Use this to exclude sensitive files from Claude Code access. See [Permission rule syntax](#permission-rule-syntax) and [Bash permission limitations](/en/iam#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |

87| `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"` |176| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed settings](/en/iam#managed-settings) | `"disable"` |

177

178### Permission rule syntax

179

180Permission rules follow the format `Tool` or `Tool(specifier)`. Understanding the syntax helps you write rules that match exactly what you intend.

181

182#### Rule evaluation order

183

184When multiple rules could match the same tool use, rules are evaluated in this order:

185

1861. **Deny** rules are checked first

1872. **Ask** rules are checked second

1883. **Allow** rules are checked last

189

190The first matching rule determines the behavior. This means deny rules always take precedence over allow rules, even if both match the same command.

191

192#### Matching all uses of a tool

193

194To match all uses of a tool, use just the tool name without parentheses:

195

196| Rule | Effect |

197| :--------- | :--------------------------------- |

198| `Bash` | Matches **all** Bash commands |

199| `WebFetch` | Matches **all** web fetch requests |

200| `Read` | Matches **all** file reads |

201

202<Warning>

203 `Bash(*)` does **not** match all Bash commands. The `*` wildcard only matches within the specifier context. To allow or deny all uses of a tool, use just the tool name: `Bash`, not `Bash(*)`.

204</Warning>

205

206#### Using specifiers for fine-grained control

207

208Add a specifier in parentheses to match specific tool uses:

209

210| Rule | Effect |

211| :----------------------------- | :------------------------------------------------------- |

212| `Bash(npm run build)` | Matches the exact command `npm run build` |

213| `Read(./.env)` | Matches reading the `.env` file in the current directory |

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

215

216#### Wildcard patterns

217

218Two wildcard syntaxes are available for Bash rules:

219

221| :------- | :------------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------- |

224

225**Prefix matching with `:*`**

226

227The `:*` suffix matches any command that starts with the specified prefix. This works with multi-word commands. The following configuration allows npm and git commit commands while blocking git push and rm -rf:

228

229```json theme={null}

230{

231 "permissions": {

232 "allow": [

233 "Bash(npm run:*)",

234 "Bash(git commit:*)",

235 "Bash(docker compose:*)"

236 ],

237 "deny": [

238 "Bash(git push:*)",

239 "Bash(rm -rf:*)"

240 ]

241 }

242}

243```

244

245**Glob matching with `*`**

246

247The `*` wildcard can appear at the beginning, middle, or end of a pattern. The following configuration allows any git command targeting main (like `git checkout main`, `git merge main`) and any version check command (like `node --version`, `npm --version`):

248

249```json theme={null}

250{

251 "permissions": {

252 "allow": [

253 "Bash(git * main)",

254 "Bash(* --version)"

255 ]

256 }

257}

258```

259

260<Warning>

261 Bash permission patterns that try to constrain command arguments are fragile. For example, `Bash(curl http://github.com/:*)` intends to restrict curl to GitHub URLs, but won't match `curl -X GET http://github.com/...` (flags before URL), `curl https://github.com/...` (different protocol), or commands using shell variables. Do not rely on argument-constraining patterns as a security boundary. See [Bash permission limitations](/en/iam#tool-specific-permission-rules) for alternatives.

262</Warning>

263

264For detailed information about tool-specific permission patterns—including Read, Edit, WebFetch, MCP, Task rules, and Bash permission limitations—see [Tool-specific permission rules](/en/iam#tool-specific-permission-rules).

88 265

89### Sandbox settings266### Sandbox settings

90 267

~~91Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See [Sandboxing](/en/docs/claude-code/sandboxing) for details.~~268Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See [Sandboxing](/en/sandboxing) for details.

92 269

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

94 271

~~96| :-------------------------- | :------------------------------------------------------------------------------------------------------------ | :------------------------ |~~273| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------ |

277| `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` |

102| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |280| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |

103| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |281| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |

127}305}

128```306```

129 307

130**Filesystem access** is controlled via Read/Edit permissions:308**Filesystem and network restrictions** use standard permission rules:

309

310* Use `Read` deny rules to block Claude from reading specific files or directories

311* Use `Edit` allow rules to let Claude write to directories beyond the current working directory

312* Use `Edit` deny rules to block writes to specific paths

313* Use `WebFetch` allow/deny rules to control which network domains Claude can access

314

315### Attribution settings

316

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

318

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

320* Pull request descriptions are plain text

321

322| Keys | Description |

323| :------- | :----------------------------------------------------------------------------------------- |

324| `commit` | Attribution for git commits, including any trailers. Empty string hides commit attribution |

325| `pr` | Attribution for pull request descriptions. Empty string hides pull request attribution |

326

327**Default commit attribution:**

328

329```

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

131 331

132* Read deny rules block file reads in sandbox332 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

133* Edit allow rules permit file writes (in addition to the defaults, e.g. the current working directory)333```

134* Edit deny rules block writes within allowed paths334

335**Default pull request attribution:**

336

337```

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

339```

340

341**Example:**

342

343```json theme={null}

344{

345 "attribution": {

346 "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",

347 "pr": ""

348 }

349}

350```

351

352<Note>

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

354</Note>

135 355

136**Network access** is controlled via WebFetch permissions:356### File suggestion settings

137 357

138* WebFetch allow rules permit network domains358Configure 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.

139* WebFetch deny rules block network domains359

360```json theme={null}

361{

362 "fileSuggestion": {

363 "type": "command",

364 "command": "~/.claude/file-suggestion.sh"

365 }

366}

367```

368

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

370

371```json theme={null}

372{"query": "src/comp"}

373```

374

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

376

377```

378src/components/Button.tsx

379src/components/Modal.tsx

380src/components/Form.tsx

381```

382

383**Example:**

384

385```bash theme={null}

386#!/bin/bash

387query=$(cat | jq -r '.query')

388your-repo-file-index --query "$query" | head -20

389```

390

391### Hook configuration

392

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

394

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

396

397* Managed hooks and SDK hooks are loaded

398* User hooks, project hooks, and plugin hooks are blocked

399

400**Configuration:**

401

402```json theme={null}

403{

404 "allowManagedHooksOnly": true

405}

406```

140 407

141### Settings precedence408### Settings precedence

142 409

143Settings are applied in order of precedence (highest to lowest):410Settings apply in order of precedence. From highest to lowest:

144 411

1451. **Enterprise managed policies** (`managed-settings.json`)4121. **Managed settings** (`managed-settings.json`)

146 * Deployed by IT/DevOps413 * Policies deployed by IT/DevOps to system directories

147 * Cannot be overridden414 * Cannot be overridden by user or project settings

148 415

1492. **Command line arguments**4162. **Command line arguments**

150 * Temporary overrides for a specific session417 * Temporary overrides for a specific session

1585. **User settings** (`~/.claude/settings.json`)4255. **User settings** (`~/.claude/settings.json`)

159 * Personal global settings426 * Personal global settings

160 427

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

429

430For 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.

162 431

163### Key points about the configuration system432### Key points about the configuration system

164 433

165* **Memory files (CLAUDE.md)**: Contain instructions and context that Claude loads at startup434* **Memory files (`CLAUDE.md`)**: Contain instructions and context that Claude loads at startup

166* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior435* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior

167* **Slash commands**: Custom commands that can be invoked during a session with `/command-name`436* **Skills**: Custom prompts that can be invoked with `/skill-name` or loaded by Claude automatically

168* **MCP servers**: Extend Claude Code with additional tools and integrations437* **MCP servers**: Extend Claude Code with additional tools and integrations

169* **Precedence**: Higher-level configurations (Enterprise) override lower-level ones (User/Project)438* **Precedence**: Higher-level configurations (Managed) override lower-level ones (User/Project)

170* **Inheritance**: Settings are merged, with more specific settings adding to or overriding broader ones439* **Inheritance**: Settings are merged, with more specific settings adding to or overriding broader ones

171 440

172### System prompt availability441### System prompt

173 442

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

175 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.

176</Note>

177 444

178### Excluding sensitive files445### Excluding sensitive files

179 446

180To 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:447To 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:

181 448

182```json theme={null}449```json theme={null}

183{450{

202* **User subagents**: `~/.claude/agents/` - Available across all your projects469* **User subagents**: `~/.claude/agents/` - Available across all your projects

203* **Project subagents**: `.claude/agents/` - Specific to your project and can be shared with your team470* **Project subagents**: `.claude/agents/` - Specific to your project and can be shared with your team

204 471

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

206 473

207## Plugin configuration474## Plugin configuration

208 475

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

210 477

211### Plugin settings478### Plugin settings

212 479

215```json theme={null}482```json theme={null}

216{483{

217 "enabledPlugins": {484 "enabledPlugins": {

218 "formatter@company-tools": true,485 "formatter@acme-tools": true,

219 "deployer@company-tools": true,486 "deployer@acme-tools": true,

220 "analyzer@security-plugins": false487 "analyzer@security-plugins": false

221 },488 },

222 "extraKnownMarketplaces": {489 "extraKnownMarketplaces": {

223 "company-tools": {490 "acme-tools": {

224 "source": "github",491 "source": "github",

225 "repo": "company/claude-plugins"492 "repo": "acme-corp/claude-plugins"

226 }493 }

227 }494 }

228}495}

266```json theme={null}533```json theme={null}

267{534{

268 "extraKnownMarketplaces": {535 "extraKnownMarketplaces": {

269 "company-tools": {536 "acme-tools": {

270 "source": {537 "source": {

271 "source": "github",538 "source": "github",

272 "repo": "company-org/claude-plugins"539 "repo": "acme-corp/claude-plugins"

273 }540 }

274 },541 },

275 "security-plugins": {542 "security-plugins": {

276 "source": {543 "source": {

277 "source": "git",544 "source": "git",

278 "url": "https://git.company.com/security/plugins.git"545 "url": "https://git.example.com/security/plugins.git"

279 }546 }

280 }547 }

281 }548 }

288* `git`: Any git URL (uses `url`)555* `git`: Any git URL (uses `url`)

289* `directory`: Local filesystem path (uses `path`, for development only)556* `directory`: Local filesystem path (uses `path`, for development only)

290 557

558#### `strictKnownMarketplaces`

559

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

561

562**Managed settings file locations**:

563

564* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`

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

566* **Windows**: `C:\Program Files\ClaudeCode\managed-settings.json`

567

568**Key characteristics**:

569

570* Only available in managed settings (`managed-settings.json`)

571* Cannot be overridden by user or project settings (highest precedence)

572* Enforced BEFORE network/filesystem operations (blocked sources never execute)

573* Uses exact matching for source specifications (including `ref`, `path` for git sources)

574

575**Allowlist behavior**:

576

577* `undefined` (default): No restrictions - users can add any marketplace

578* Empty array `[]`: Complete lockdown - users cannot add any new marketplaces

579* List of sources: Users can only add marketplaces that match exactly

580

581**All supported source types**:

582

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

584

5851. **GitHub repositories**:

586

587```json theme={null}

588{ "source": "github", "repo": "acme-corp/approved-plugins" }

589{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }

590{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }

591```

592

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

594

5952. **Git repositories**:

596

597```json theme={null}

598{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }

599{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }

600{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }

601```

602

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

604

6053. **URL-based marketplaces**:

606

607```json theme={null}

608{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }

609{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

610```

611

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

613

614<Note>

615 URL-based marketplaces only download the `marketplace.json` file. They do not download plugin files from the server. Plugins in URL-based marketplaces must use external sources (GitHub, npm, or git URLs) rather than relative paths. For plugins with relative paths, use a Git-based marketplace instead. See [Troubleshooting](/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces) for details.

616</Note>

617

6184. **NPM packages**:

619

620```json theme={null}

621{ "source": "npm", "package": "@acme-corp/claude-plugins" }

622{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

623```

624

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

626

6275. **File paths**:

628

629```json theme={null}

630{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }

631{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

632```

633

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

635

6366. **Directory paths**:

637

638```json theme={null}

639{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }

640{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

641```

642

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

644

645**Configuration examples**:

646

647Example - Allow specific marketplaces only:

648

649```json theme={null}

650{

651 "strictKnownMarketplaces": [

652 {

653 "source": "github",

654 "repo": "acme-corp/approved-plugins"

655 },

656 {

657 "source": "github",

658 "repo": "acme-corp/security-tools",

659 "ref": "v2.0"

660 },

661 {

662 "source": "url",

663 "url": "https://plugins.example.com/marketplace.json"

664 },

665 {

666 "source": "npm",

667 "package": "@acme-corp/compliance-plugins"

668 }

669 ]

670}

671```

672

673Example - Disable all marketplace additions:

674

675```json theme={null}

676{

677 "strictKnownMarketplaces": []

678}

679```

680

681**Exact matching requirements**:

682

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

684

685* The `repo` or `url` must match exactly

686* The `ref` field must match exactly (or both be undefined)

687* The `path` field must match exactly (or both be undefined)

688

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

690

691```json theme={null}

692// These are DIFFERENT sources:

693{ "source": "github", "repo": "acme-corp/plugins" }

694{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

695

696// These are also DIFFERENT:

697{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }

698{ "source": "github", "repo": "acme-corp/plugins" }

699```

700

701**Comparison with `extraKnownMarketplaces`**:

702

703| Aspect | `strictKnownMarketplaces` | `extraKnownMarketplaces` |

704| --------------------- | ------------------------------------ | ------------------------------------ |

705| **Purpose** | Organizational policy enforcement | Team convenience |

706| **Settings file** | `managed-settings.json` only | Any settings file |

707| **Behavior** | Blocks non-allowlisted additions | Auto-installs missing marketplaces |

708| **When enforced** | Before network/filesystem operations | After user trust prompt |

709| **Can be overridden** | No (highest precedence) | Yes (by higher precedence settings) |

710| **Source format** | Direct source object | Named marketplace with nested source |

711| **Use case** | Compliance, security restrictions | Onboarding, standardization |

712

713**Format difference**:

714

715`strictKnownMarketplaces` uses direct source objects:

716

717```json theme={null}

718{

719 "strictKnownMarketplaces": [

720 { "source": "github", "repo": "acme-corp/plugins" }

721 ]

722}

723```

724

725`extraKnownMarketplaces` requires named marketplaces:

726

727```json theme={null}

728{

729 "extraKnownMarketplaces": {

730 "acme-tools": {

731 "source": { "source": "github", "repo": "acme-corp/plugins" }

732 }

733 }

734}

735```

736

737**Important notes**:

738

739* Restrictions are checked BEFORE any network requests or filesystem operations

740* When blocked, users see clear error messages indicating the source is blocked by managed policy

741* The restriction applies only to adding NEW marketplaces; previously installed marketplaces remain accessible

742* Managed settings have the highest precedence and cannot be overridden

743

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

745

291### Managing plugins746### Managing plugins

292 747

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

298* View plugin details (commands, agents, hooks provided)753* View plugin details (commands, agents, hooks provided)

299* Add/remove marketplaces754* Add/remove marketplaces

300 755

301Learn more about the plugin system in the [plugins documentation](/en/docs/claude-code/plugins).756Learn more about the plugin system in the [plugins documentation](/en/plugins).

302 757

303## Environment variables758## Environment variables

304 759

309</Note>764</Note>

310 765

312| :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |767| :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

313| `ANTHROPIC_API_KEY` | API key sent as `X-Api-Key` header, typically for the Claude SDK (for interactive usage, run `/login`) |768| `ANTHROPIC_API_KEY` | API key sent as `X-Api-Key` header, typically for the Claude SDK (for interactive usage, run `/login`) |

314| `ANTHROPIC_AUTH_TOKEN` | Custom value for the `Authorization` header (the value you set here will be prefixed with `Bearer `) |769| `ANTHROPIC_AUTH_TOKEN` | Custom value for the `Authorization` header (the value you set here will be prefixed with `Bearer `) |

319| `ANTHROPIC_MODEL` | Name of the model setting to use (see [Model Configuration](/en/docs/claude-code/model-config#environment-variables)) |774| `ANTHROPIC_FOUNDRY_API_KEY` | API key for Microsoft Foundry authentication (see [Microsoft Foundry](/en/microsoft-foundry)) |

320| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Name of [Haiku-class model for background tasks](/en/docs/claude-code/costs) |775| `ANTHROPIC_MODEL` | Name of the model setting to use (see [Model Configuration](/en/model-config#environment-variables)) |

776| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Name of [Haiku-class model for background tasks](/en/costs) |

322| `AWS_BEARER_TOKEN_BEDROCK` | Bedrock API key for authentication (see [Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) |778| `AWS_BEARER_TOKEN_BEDROCK` | Bedrock API key for authentication (see [Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) |

782| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Set the percentage of context capacity (1-100) at which auto-compaction triggers. By default, auto-compaction triggers at approximately 95% capacity. Use lower values like `50` to compact earlier. Values above the default threshold have no effect. Applies to both main conversations and subagents. This percentage aligns with the `context_window.used_percentage` field available in [status line](/en/statusline) |

327| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Interval in milliseconds at which credentials should be refreshed (when using `apiKeyHelper`) |784| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Interval in milliseconds at which credentials should be refreshed (when using `apiKeyHelper`) |

788| `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 |

789| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Set to `1` to disable all background task functionality, including the `run_in_background` parameter on Bash and subagent tools, auto-backgrounding, and the Ctrl+B shortcut |

790| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Time in milliseconds to wait after the query loop becomes idle before automatically exiting. Useful for automated workflows and scripts using SDK mode |

791| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | Set to `true` to allow the proxy to perform DNS resolution instead of the caller. Opt-in for environments where the proxy should handle hostname resolution |

792| `CLAUDE_CODE_TMPDIR` | Override the temp directory used for internal temp files. Claude Code appends `/claude/` to this path. Default: `/tmp` on Unix/macOS, `os.tmpdir()` on Windows |

331| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |793| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |

332| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |794| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |

795| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override the default token limit for file reads. Useful when you need to read larger files in full |

796| `CLAUDE_CODE_HIDE_ACCOUNT_INFO` | Set to `1` to hide your email address and organization name from the Claude Code UI. Useful when streaming or recording |

334| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Set the maximum number of output tokens for most requests |798| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Set the maximum number of output tokens for most requests. Default: 32,000. Maximum: 64,000. Increasing this value reduces the effective context window available before [auto-compaction](/en/costs#reduce-token-usage) triggers. |

335| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip AWS authentication for Bedrock (e.g. when using an LLM gateway) |799| `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) |

336| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (e.g. when using an LLM gateway) |800| `CLAUDE_CODE_SHELL` | Override automatic shell detection. Useful when your login shell differs from your preferred working shell (for example, `bash` vs `zsh`) |

337| `CLAUDE_CODE_SUBAGENT_MODEL` | See [Model configuration](/en/docs/claude-code/model-config) |801| `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>` |

340| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic updates. This takes precedence over the `autoUpdates` configuration setting. |804| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (for example, when using an LLM gateway) |

805| `CLAUDE_CODE_SUBAGENT_MODEL` | See [Model configuration](/en/model-config) |

806| `CLAUDE_CODE_USE_BEDROCK` | Use [Bedrock](/en/amazon-bedrock) |

807| `CLAUDE_CODE_USE_FOUNDRY` | Use [Microsoft Foundry](/en/microsoft-foundry) |

808| `CLAUDE_CODE_USE_VERTEX` | Use [Vertex](/en/google-vertex-ai) |

809| `CLAUDE_CONFIG_DIR` | Customize where Claude Code stores its configuration and data files |

810| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic updates. |

349| `DISABLE_TELEMETRY` | Set to `1` to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands) |819| `DISABLE_TELEMETRY` | Set to `1` to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands) |

820| `ENABLE_TOOL_SEARCH` | Controls [MCP tool search](/en/mcp#scale-with-mcp-tool-search). Values: `auto` (default, enables at 10% context), `auto:N` (custom threshold, e.g., `auto:5` for 5%), `true` (always on), `false` (disabled) |

821| `FORCE_AUTOUPDATE_PLUGINS` | Set to `true` to force plugin auto-updates even when the main auto-updater is disabled via `DISABLE_AUTOUPDATER` |

824| `IS_DEMO` | Set to `true` to enable demo mode: hides email and organization from the UI, skips onboarding, and hides internal commands. Useful for streaming or recording sessions |

352| `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) |825| `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) |

353| `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. |826| `MAX_THINKING_TOKENS` | Override the [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) token budget. Thinking is enabled at max budget (31,999 tokens) by default. Use this to limit the budget (for example, `MAX_THINKING_TOKENS=10000`) or disable thinking entirely (`MAX_THINKING_TOKENS=0`). 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). |

357| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum number of characters for slash command metadata shown to [SlashCommand tool](/en/docs/claude-code/slash-commands#slashcommand-tool) (default: 15000) |830| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum number of characters for skill metadata shown to the [Skill tool](/en/skills#control-who-invokes-a-skill) (default: 15000). Legacy name kept for backwards compatibility. |

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

368 841

370| :--------------- | :----------------------------------------------------------------------------------- | :------------------ |843| :------------------ | :------------------------------------------------------------------------------------------------- | :------------------ |

371| **Bash** | Executes shell commands in your environment | Yes |844| **AskUserQuestion** | Asks multiple-choice questions to gather requirements or clarify ambiguity | No |

845| **Bash** | Executes shell commands in your environment (see [Bash tool behavior](#bash-tool-behavior) below) | Yes |

846| **TaskOutput** | Retrieves output from a background task (bash shell or subagent) | No |

372| **Edit** | Makes targeted edits to specific files | Yes |847| **Edit** | Makes targeted edits to specific files | Yes |

848| **ExitPlanMode** | Prompts the user to exit plan mode and start coding | Yes |

373| **Glob** | Finds files based on pattern matching | No |849| **Glob** | Finds files based on pattern matching | No |

374| **Grep** | Searches for patterns in file contents | No |850| **Grep** | Searches for patterns in file contents | No |

851| **KillShell** | Kills a running background bash shell by its ID | No |

852| **MCPSearch** | Searches for and loads MCP tools when [tool search](/en/mcp#scale-with-mcp-tool-search) is enabled | No |

375| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |853| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |

376| **NotebookRead** | Reads and displays Jupyter notebook contents | No |

377| **Read** | Reads the contents of files | No |854| **Read** | Reads the contents of files | No |

378| **SlashCommand** | Runs a [custom slash command](/en/docs/claude-code/slash-commands#slashcommand-tool) | Yes |855| **Skill** | Executes a [skill](/en/skills#control-who-invokes-a-skill) within the main conversation | Yes |

379| **Task** | Runs a sub-agent to handle complex, multi-step tasks | No |856| **Task** | Runs a sub-agent to handle complex, multi-step tasks | No |

380| **TodoWrite** | Creates and manages structured task lists | No |857| **TodoWrite** | Creates and manages structured task lists | No |

381| **WebFetch** | Fetches content from a specified URL | Yes |858| **WebFetch** | Fetches content from a specified URL | Yes |

382| **WebSearch** | Performs web searches with domain filtering | Yes |859| **WebSearch** | Performs web searches with domain filtering | Yes |

383| **Write** | Creates or overwrites files | Yes |860| **Write** | Creates or overwrites files | Yes |

384 861

385Permission rules can be configured using `/allowed-tools` or in [permission settings](/en/docs/claude-code/settings#available-settings). Also see [Tool-specific permission rules](/en/docs/claude-code/iam#tool-specific-permission-rules).862Permission 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).

863

864### Bash tool behavior

865

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

867

868* **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.

869* **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.

870

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

872

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

874

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

876

877```bash theme={null}

878conda activate myenv

879# or: source /path/to/venv/bin/activate

880claude

881```

882

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

884

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

886

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

888

889```bash theme={null}

890export CLAUDE_ENV_FILE=/path/to/env-setup.sh

891claude

892```

893

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

895

896```bash theme={null}

897conda activate myenv

898# or: source /path/to/venv/bin/activate

899# or: export MY_VAR=value

900```

901

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

903

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

905

906Configure in `.claude/settings.json`:

907

908```json theme={null}

909{

910 "hooks": {

911 "SessionStart": [{

912 "matcher": "startup",

913 "hooks": [{

914 "type": "command",

915 "command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""

916 }]

917 }]

918 }

919}

920```

921

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

923

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

386 925

387### Extending tools with hooks926### Extending tools with hooks

388 927

389You can run custom commands before or after any tool executes using928You can run custom commands before or after any tool executes using

390[Claude Code hooks](/en/docs/claude-code/hooks-guide).929[Claude Code hooks](/en/hooks-guide).

391 930

392For example, you could automatically run a Python formatter after Claude931For example, you could automatically run a Python formatter after Claude

393modifies Python files, or prevent modifications to production configuration932modifies Python files, or prevent modifications to production configuration

395 934

396## See also935## See also

397 936

398* [Identity and Access Management](/en/docs/claude-code/iam#configuring-permissions) - Learn about Claude Code's permission system937* [Identity and Access Management](/en/iam#configuring-permissions) - Permission system overview and how allow/ask/deny rules interact

399* [IAM and access control](/en/docs/claude-code/iam#enterprise-managed-policy-settings) - Enterprise policy management938* [Tool-specific permission rules](/en/iam#tool-specific-permission-rules) - Detailed patterns for Bash, Read, Edit, WebFetch, MCP, and Task tools, including security limitations

400* [Troubleshooting](/en/docs/claude-code/troubleshooting#auto-updater-issues) - Solutions for common configuration issues939* [Managed settings](/en/iam#managed-settings) - Managed policy configuration for organizations

940* [Troubleshooting](/en/troubleshooting) - Solutions for common configuration issues

941

942

943---

944

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

setup.md +231 −99

Details

4 4

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 13.0+, 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* **Network**: Internet connection required (see [network configuration](/en/network-config#network-access-requirements))

~~10* **Network**: Internet connection required for authentication and AI processing~~10* **Shell**: Works best in Bash or Zsh

~~11* **Shell**: Works best in Bash, Zsh or Fish~~

12* **Location**: [Anthropic supported countries](https://www.anthropic.com/supported-countries)11* **Location**: [Anthropic supported countries](https://www.anthropic.com/supported-countries)

13 12

14### Additional dependencies13### Additional dependencies

15 14

~~16* **ripgrep**: Usually included with Claude Code. If search functionality fails, see [search troubleshooting](/en/docs/claude-code/troubleshooting#search-and-discovery-issues).~~15* **ripgrep**: Usually included with Claude Code. If search fails, see [search troubleshooting](/en/troubleshooting#search-and-discovery-issues).

16* **[Node.js 18+](https://nodejs.org/en/download)**: Only required for [deprecated npm installation](#npm-installation-deprecated)

17 17

~~18## Standard installation~~18## Installation

19 19

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

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}~~

~~27 brew install --cask claude-code~~

~~28 ```~~

30 **macOS, Linux, WSL:**24 **macOS, Linux, WSL:**

31 25

32 ```bash theme={null}26 ```bash theme={null}

44 ```batch 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>~~

48 41

~~49 <Tab title="NPM">~~42 <Info>

~~50 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):~~43 Native installations automatically update in the background to keep you on the latest version.

44 </Info>

45 </Tab>

51 46

47 <Tab title="Homebrew">

52 ```sh theme={null}48 ```sh theme={null}

~~53 npm install -g @anthropic-ai/claude-code~~49 brew install --cask claude-code

54 ```50 ```

52 <Info>

53 Homebrew installations do not auto-update. Run `brew upgrade claude-code` periodically to get the latest features and security fixes.

54 </Info>

55 </Tab>55 </Tab>

~~56</Tabs>~~

57 56

~~58<Note>~~57 <Tab title="WinGet">

~~59 Some users may be automatically migrated to an improved installation method.~~58 ```powershell theme={null}

~~60</Note>~~59 winget install Anthropic.ClaudeCode

60 ```

62 <Info>

63 WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.

64 </Info>

65 </Tab>

66</Tabs>

61 67

62After the installation process completes, navigate to your project and start Claude Code:68After the installation process completes, navigate to your project and start Claude Code:

63 69

66claude72claude

67```73```

68 74

~~69Claude Code offers the following authentication options:~~75If you encounter any issues during installation, consult the [troubleshooting guide](/en/troubleshooting).

70 76

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.77<Tip>

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.78 Run `claude doctor` after installation to check your installation type and version.

733. **Enterprise platforms**: Configure Claude Code to use [Amazon Bedrock or Google Vertex AI](/en/docs/claude-code/third-party-integrations) for enterprise deployments with your existing cloud infrastructure.79</Tip>

74 80

75<Note>81<Note>

~~76 Claude Code securely stores your credentials. See [Credential Management](/en/docs/claude-code/iam#credential-management) for details.~~82 **Alpine Linux and other musl/uClibc-based distributions**: The native installer requires `libgcc`, `libstdc++`, and `ripgrep`. For Alpine: `apk add libgcc libstdc++ ripgrep`. Set `USE_BUILTIN_RIPGREP=0`.

77</Note>83</Note>

78 84

85### Authentication

87#### For individuals

891. **Claude Pro or Max plan** (recommended): Subscribe to Claude's [Pro or Max plan](https://claude.ai/pricing) for a unified subscription that includes both Claude Code and Claude on the web. Manage your account in one place and log in with your Claude.ai account.

902. **Claude Console**: Connect through the [Claude Console](https://console.anthropic.com) and complete the OAuth process. Requires active billing in the Anthropic Console. 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.

92#### For teams and organizations

941. **Claude for Teams or Enterprise** (recommended): Subscribe to [Claude for Teams](https://claude.com/pricing#team-&-enterprise) or [Claude for Enterprise](https://anthropic.com/contact-sales) for centralized billing, team management, and access to both Claude Code and Claude on the web. Team members log in with their Claude.ai accounts.

952. **Claude Console with team billing**: Set up a shared [Claude Console](https://console.anthropic.com) organization with team billing. Invite team members and assign roles for usage tracking.

963. **Cloud providers**: Configure Claude Code to use [Amazon Bedrock, Google Vertex AI, or Microsoft Foundry](/en/third-party-integrations) for deployments with your existing cloud infrastructure.

98### Install a specific version

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

101

102To install the latest version (default):

103

104<Tabs>

105 <Tab title="macOS, Linux, WSL">

106 ```bash theme={null}

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

108 ```

109 </Tab>

110

111 <Tab title="Windows PowerShell">

112 ```powershell theme={null}

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

114 ```

115 </Tab>

116

117 <Tab title="Windows CMD">

118 ```batch theme={null}

119 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

120 ```

121 </Tab>

122</Tabs>

123

124To install the stable version:

125

126<Tabs>

127 <Tab title="macOS, Linux, WSL">

128 ```bash theme={null}

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

130 ```

131 </Tab>

132

133 <Tab title="Windows PowerShell">

134 ```powershell theme={null}

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

136 ```

137 </Tab>

138

139 <Tab title="Windows CMD">

140 ```batch theme={null}

141 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd

142 ```

143 </Tab>

144</Tabs>

145

146To install a specific version number:

147

148<Tabs>

149 <Tab title="macOS, Linux, WSL">

150 ```bash theme={null}

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

152 ```

153 </Tab>

154

155 <Tab title="Windows PowerShell">

156 ```powershell theme={null}

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

158 ```

159 </Tab>

160

161 <Tab title="Windows CMD">

162 ```batch theme={null}

163 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd

164 ```

165 </Tab>

166</Tabs>

167

168### Binary integrity and code signing

169

170* 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`)

171* Signed binaries are distributed for the following platforms:

172 * macOS: Signed by "Anthropic PBC" and notarized by Apple

173 * Windows: Signed by "Anthropic, PBC"

174

175## NPM installation (deprecated)

176

177NPM installation is deprecated. Use the [native installation](#installation) method when possible. To migrate an existing npm installation to native, run `claude install`.

178

179**Global npm installation**

180

181```sh theme={null}

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

183```

184

185<Warning>

186 Do NOT use `sudo npm install -g` as this can lead to permission issues and security risks.

187 If you encounter permission errors, see [troubleshooting permission errors](/en/troubleshooting#command-not-found-claude-or-permission-errors) for recommended solutions.

188</Warning>

189

79## Windows setup190## Windows setup

80 191

81**Option 1: Claude Code within WSL**192**Option 1: Claude Code within WSL**

90 $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"201 $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

91 ```202 ```

92 203

~~93## Alternative installation methods~~204## Update Claude Code

94 205

~~95Claude Code offers multiple installation methods to suit different environments.~~206### Auto updates

96 207

~~97If you encounter any issues during installation, consult the [troubleshooting guide](/en/docs/claude-code/troubleshooting#linux-permission-issues).~~208Claude Code automatically keeps itself up to date to ensure you have the latest features and security fixes.

98 209

~~99<Tip>~~210* **Update checks**: Performed on startup and periodically while running

100 Run `claude doctor` after installation to check your installation type and version.211* **Update process**: Downloads and installs automatically in the background

101</Tip>212* **Notifications**: You'll see a notification when updates are installed

213* **Applying updates**: Updates take effect the next time you start Claude Code

102 214

103### Native installation options215<Note>

216 Homebrew and WinGet installations do not auto-update. Use `brew upgrade claude-code` or `winget upgrade Anthropic.ClaudeCode` to update manually.

104 217

105The native installation is the recommended method and offers several benefits:218 **Known issue:** Claude Code may notify you of updates before the new version is available in these package managers. If an upgrade fails, wait and try again later.

219</Note>

106 220

107* One self-contained executable221### Configure release channel

108* No Node.js dependency

109* Improved auto-updater stability

110 222

111If you have an existing installation of Claude Code, use `claude install` to migrate to the native binary installation.223Configure which release channel Claude Code follows for both auto-updates and `claude update` with the `autoUpdatesChannel` setting:

112 224

113For advanced installation options with the native installer:225* `"latest"` (default): Receive new features as soon as they're released

226* `"stable"`: Use a version that is typically about one week old, skipping releases with major regressions

114 227

115**macOS, Linux, WSL:**228Configure this via `/config` → **Auto-update channel**, or add it to your [settings.json file](/en/settings):

229

230```json theme={null}

231{

232 "autoUpdatesChannel": "stable"

233}

234```

235

236For enterprise deployments, you can enforce a consistent release channel across your organization using [managed settings](/en/iam#managed-settings).

237

238### Disable auto-updates

239

240Set the `DISABLE_AUTOUPDATER` environment variable in your shell or [settings.json file](/en/settings):

116 241

117```bash theme={null}242```bash theme={null}

118# Install stable version (default)243export DISABLE_AUTOUPDATER=1

119curl -fsSL https://claude.ai/install.sh | bash244```

120 245

121# Install latest version246### Update manually

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

123 247

124# Install specific version number248```bash theme={null}

125curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58249claude update

126```250```

127 251

128<Note>252## Uninstall Claude Code

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`.

130</Note>

131 253

132<Note>254If you need to uninstall Claude Code, follow the instructions for your installation method.

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>

135 255

136**Windows PowerShell:**256### Native installation

137 257

138```powershell theme={null}258Remove the Claude Code binary and version files:

139# Install stable version (default)259

140irm https://claude.ai/install.ps1 | iex260**macOS, Linux, WSL:**

261

262```bash theme={null}

263rm -f ~/.local/bin/claude

264rm -rf ~/.local/share/claude

265```

141 266

142# Install latest version267**Windows PowerShell:**

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

144 268

145# Install specific version number269```powershell theme={null}

146& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58270Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force

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

147```272```

148 273

149**Windows CMD:**274**Windows CMD:**

150 275

151```batch theme={null}276```batch theme={null}

152REM Install stable version (default)277del "%USERPROFILE%\.local\bin\claude.exe"

153curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd278rmdir /s /q "%USERPROFILE%\.local\share\claude"

279```

154 280

155REM Install latest version281### Homebrew installation

156curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd latest && del install.cmd

157 282

158REM Install specific version number283```bash theme={null}

159curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd284brew uninstall --cask claude-code

160```285```

161 286

162<Tip>287### WinGet installation

163 Make sure that you remove any outdated aliases or symlinks before installing.

164</Tip>

165 288

166### NPM installation289```powershell theme={null}

290winget uninstall Anthropic.ClaudeCode

291```

167 292

168For environments where NPM is preferred or required:293### NPM installation

169 294

170```sh theme={null}295```bash theme={null}

171npm install -g @anthropic-ai/claude-code296npm uninstall -g @anthropic-ai/claude-code

172```297```

173 298

299### Clean up configuration files (optional)

300

174<Warning>301<Warning>

175 Do NOT use `sudo npm install -g` as this can lead to permission issues and security risks.302 Removing configuration files will delete all your settings, allowed tools, MCP server configurations, and session history.

176 If you encounter permission errors, see [configure Claude Code](/en/docs/claude-code/troubleshooting#linux-permission-issues) for recommended solutions.

177</Warning>303</Warning>

178 304

179### Local installation305To remove Claude Code settings and cached data:

~~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 GCP

186 306

187By default, Claude Code uses the Claude API.307**macOS, Linux, WSL:**

188 308

189For details on running Claude Code on AWS or GCP, see [third-party integrations](/en/docs/claude-code/third-party-integrations).309```bash theme={null}

310# Remove user settings and state

311rm -rf ~/.claude

312rm ~/.claude.json

190 313

191## Update Claude Code314# Remove project-specific settings (run from your project directory)

315rm -rf .claude

316rm -f .mcp.json

317```

192 318

193### Auto updates319**Windows PowerShell:**

194 320

195Claude Code automatically keeps itself up to date to ensure you have the latest features and security fixes.321```powershell theme={null}

322# Remove user settings and state

323Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force

324Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

196 325

197* **Update checks**: Performed on startup and periodically while running326# Remove project-specific settings (run from your project directory)

198* **Update process**: Downloads and installs automatically in the background327Remove-Item -Path ".claude" -Recurse -Force

199* **Notifications**: You'll see a notification when updates are installed328Remove-Item -Path ".mcp.json" -Force

200* **Applying updates**: Updates take effect the next time you start Claude Code329```

201 330

202**Disable auto-updates:**331**Windows CMD:**

203 332

204Set the `DISABLE_AUTOUPDATER` environment variable in your shell or [settings.json file](/en/docs/claude-code/settings):333```batch theme={null}

334REM Remove user settings and state

335rmdir /s /q "%USERPROFILE%\.claude"

336del "%USERPROFILE%\.claude.json"

205 337

206```bash theme={null}338REM Remove project-specific settings (run from your project directory)

207export DISABLE_AUTOUPDATER=1339rmdir /s /q ".claude"

340del ".mcp.json"

208```341```

209 342

210### Update manually

211 343

212```bash theme={null}344---

213claude update345

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

skills.md +465 −421

Details

~~1# Agent Skills~~1# Extend Claude with skills

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. Includes custom slash commands.

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.5Skills extend what Claude can do. Create a `SKILL.md` file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with `/skill-name`.

~~7## Prerequisites~~

~~9* Claude Code version 1.0 or later~~

~~10* Basic familiarity with [Claude Code](/en/docs/claude-code/quickstart)~~

~~12## What are Agent Skills?~~

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.

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

~~18**Benefits**:~~

~~20* Extend Claude's capabilities for your specific workflows~~

~~21* Share expertise across your team via git~~

~~22* Reduce repetitive prompting~~

~~23* Compose multiple Skills for complex tasks~~

~~25Learn more in the [Agent Skills overview](/en/docs/agents-and-tools/agent-skills/overview).~~

26 6

27<Note>7<Note>

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).8 For built-in commands like `/help` and `/compact`, see [interactive mode](/en/interactive-mode#built-in-commands).

10 **Custom slash commands have been merged into skills.** A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Your existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to [control whether you or Claude invokes them](#control-who-invokes-a-skill), and the ability for Claude to load them automatically when relevant.

29</Note>11</Note>

30 12

~~31## Create a Skill~~13Claude Code skills follow the [Agent Skills](https://agentskills.io) open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like [invocation control](#control-who-invokes-a-skill), [subagent execution](#run-skills-in-a-subagent), and [dynamic context injection](#inject-dynamic-context).

32 14

~~33Skills are stored as directories containing a `SKILL.md` file.~~15## Getting started

34 16

~~35### Personal Skills~~17### Create your first skill

36 18

~~37Personal Skills are available across all your projects. Store them in `~/.claude/skills/`:~~19This example creates a skill that teaches Claude to explain code using visual diagrams and analogies. Since it uses default frontmatter, Claude can load it automatically when you ask how something works, or you can invoke it directly with `/explain-code`.

38 20

~~39```bash theme={null}~~21<Steps>

~~40mkdir -p ~/.claude/skills/my-skill-name~~22 <Step title="Create the skill directory">

~~41```~~23 Create a directory for the skill in your personal skills folder. Personal skills are available across all your projects.

42 24

~~43**Use personal Skills for**:~~25 ```bash theme={null}

26 mkdir -p ~/.claude/skills/explain-code

27 ```

28 </Step>

44 29

~~45* Your individual workflows and preferences~~30 <Step title="Write SKILL.md">

~~46* Experimental Skills you're developing~~31 Every skill needs a `SKILL.md` file with two parts: YAML frontmatter (between `---` markers) that tells Claude when to use the skill, and markdown content with instructions Claude follows when the skill is invoked. The `name` field becomes the `/slash-command`, and the `description` helps Claude decide when to load it automatically.

~~47* Personal productivity tools~~

48 32

~~49### Project Skills~~33 Create `~/.claude/skills/explain-code/SKILL.md`:

50 34

~~51Project Skills are shared with your team. Store them in `.claude/skills/` within your project:~~35 ```yaml theme={null}

36 ---

37 name: explain-code

38 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?"

39 ---

52 40

~~53```bash theme={null}~~41 When explaining code, always include:

~~54mkdir -p .claude/skills/my-skill-name~~

~~55```~~

~~57**Use project Skills for**:~~

58 42

~~59* Team workflows and conventions~~43 1. **Start with an analogy**: Compare the code to something from everyday life

~~60* Project-specific expertise~~44 2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships

~~61* Shared utilities and scripts~~45 3. **Walk through the code**: Explain step-by-step what happens

46 4. **Highlight a gotcha**: What's a common mistake or misconception?

62 47

~~63Project Skills are checked into git and automatically available to team members.~~48 Keep explanations conversational. For complex concepts, use multiple analogies.

49 ```

50 </Step>

64 51

~~65### Plugin Skills~~52 <Step title="Test the skill">

53 You can test it two ways:

66 54

67Skills can also come from [Claude Code plugins](/en/docs/claude-code/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.55 **Let Claude invoke it automatically** by asking something that matches the description:

68 56

~~69## Write SKILL.md~~57 ```

58 How does this code work?

59 ```

70 60

~~71Create a `SKILL.md` file with YAML frontmatter and Markdown content:~~61 **Or invoke it directly** with the skill name:

~~73```yaml theme={null}~~

~~74name: your-skill-name~~

~~75description: Brief description of what this Skill does and when to use it~~

76 62

~~77# Your Skill Name~~63 ```

64 /explain-code src/auth/login.ts

65 ```

78 66

~~79## Instructions~~67 Either way, Claude should include an analogy and ASCII diagram in its explanation.

~~80Provide clear, step-by-step guidance for Claude.~~68 </Step>

69</Steps>

81 70

~~82## Examples~~71### Where skills live

~~83Show concrete examples of using this Skill.~~

~~84```~~

85 72

~~86**Field requirements**:~~73Where you store a skill determines who can use it:

87 74

~~88* `name`: Must use lowercase letters, numbers, and hyphens only (max 64 characters)~~75| Location | Path | Applies to |

~~89* `description`: Brief description of what the Skill does and when to use it (max 1024 characters)~~76| :--------- | :----------------------------------------------- | :----------------------------- |

77| Enterprise | See [managed settings](/en/iam#managed-settings) | All users in your organization |

78| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | All your projects |

79| Project | `.claude/skills/<skill-name>/SKILL.md` | This project only |

80| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Where plugin is enabled |

90 81

~~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.~~82Project skills override personal skills with the same name. If you have files in `.claude/commands/`, those work the same way but a skill takes precedence over a command with the same name.

92 83

~~93See the [best practices guide](/en/docs/agents-and-tools/agent-skills/best-practices) for complete authoring guidance including validation rules.~~84#### Automatic discovery from nested directories

94 85

~~95## Add supporting files~~86When you work with files in subdirectories, Claude Code automatically discovers skills from nested `.claude/skills/` directories. For example, if you're editing a file in `packages/frontend/`, Claude Code also looks for skills in `packages/frontend/.claude/skills/`. This supports monorepo setups where packages have their own skills.

96 87

~~97Create additional files alongside SKILL.md:~~88Each skill is a directory with `SKILL.md` as the entrypoint:

98 89

99```90```

100my-skill/91my-skill/

101├── SKILL.md (required)92├── SKILL.md # Main instructions (required)

102├── reference.md (optional documentation)93├── template.md # Template for Claude to fill in

103├── examples.md (optional examples)94├── examples/

104├── scripts/95│ └── sample.md # Example output showing expected format

105│ └── helper.py (optional utility)96└── scripts/

106└── templates/97 └── validate.sh # Script Claude can execute

107 └── template.txt (optional template)

108```98```

109 99

110Reference these files from SKILL.md:100The `SKILL.md` contains the main instructions and is required. Other files are optional and let you build more powerful skills: templates for Claude to fill in, example outputs showing the expected format, scripts Claude can execute, or detailed reference documentation. Reference these files from your `SKILL.md` so Claude knows what they contain and when to load them. See [Add supporting files](#add-supporting-files) for more details.

111 101

112````markdown theme={null}102<Note>

113For advanced usage, see [reference.md](reference.md).103 Files in `.claude/commands/` still work and support the same [frontmatter](#frontmatter-reference). Skills are recommended since they support additional features like supporting files.

104</Note>

114 105

115Run the helper script:106## Configure skills

116```bash107

117python scripts/helper.py input.txt108Skills are configured through YAML frontmatter at the top of `SKILL.md` and the markdown content that follows.

118```

119````

120 109

121Claude reads these files only when needed, using progressive disclosure to manage context efficiently.110### Types of skill content

122 111

123## Restrict tool access with allowed-tools112Skill files can contain any instructions, but thinking about how you want to invoke them helps guide what to include:

124 113

125Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active:114**Reference content** adds knowledge Claude applies to your current work. Conventions, patterns, style guides, domain knowledge. This content runs inline so Claude can use it alongside your conversation context.

126 115

127```yaml theme={null}116```yaml theme={null}

128---117---

129name: safe-file-reader118name: api-conventions

130description: Read files without making changes. Use when you need read-only file access.119description: API design patterns for this codebase

131allowed-tools: Read, Grep, Glob

132---120---

133 121

134# Safe File Reader122When writing API endpoints:

~~135~~ 123- Use RESTful naming conventions

136This Skill provides read-only file access.124- Return consistent error formats

~~137~~ 125- Include request validation

138## Instructions

1391. Use Read to view file contents

1402. Use Grep to search within files

1413. Use Glob to find files by pattern

142```126```

143 127

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:128**Task content** gives Claude step-by-step instructions for a specific action, like deployments, commits, or code generation. These are often actions you want to invoke directly with `/skill-name` rather than letting Claude decide when to run them. Add `disable-model-invocation: true` to prevent Claude from triggering it automatically.

~~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 129

170or130```yaml theme={null}

131---

132name: deploy

133description: Deploy the application to production

134context: fork

135disable-model-invocation: true

136---

171 137

172```138Deploy the application:

173List all available Skills1391. Run the test suite

1402. Build the application

1413. Push to the deployment target

174```142```

175 143

176This will show all Skills from all sources, including plugin Skills.144Your `SKILL.md` can contain anything, but thinking through how you want the skill invoked (by you, by Claude, or both) and where you want it to run (inline or in a subagent) helps guide what to include. For complex skills, you can also [add supporting files](#add-supporting-files) to keep the main skill focused.

177 145

178**To inspect a specific Skill**, you can also check the filesystem:146### Frontmatter reference

179 147

180```bash theme={null}148Beyond the markdown content, you can configure skill behavior using YAML frontmatter fields between `---` markers at the top of your `SKILL.md` file:

181# List personal Skills

182ls ~/.claude/skills/

183 149

184# List project Skills (if in a project directory)150```yaml theme={null}

185ls .claude/skills/151---

152name: my-skill

153description: What this skill does

154disable-model-invocation: true

155allowed-tools: Read, Grep

156---

186 157

187# View a specific Skill's content158Your skill instructions here...

188cat ~/.claude/skills/my-skill/SKILL.md

189```159```

190 160

191## Test a Skill161All fields are optional. Only `description` is recommended so Claude knows when to use the skill.

~~192~~

193After creating a Skill, test it by asking questions that match your description.

194 162

195**Example**: If your description mentions "PDF files":163| Field | Required | Description |

164| :------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |

165| `name` | No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). |

166| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. |

167| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |

168| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Default: `false`. |

169| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |

170| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. |

171| `model` | No | Model to use when this skill is active. |

172| `context` | No | Set to `fork` to run in a forked subagent context. |

173| `agent` | No | Which subagent type to use when `context: fork` is set. |

174| `hooks` | No | Hooks scoped to this skill's lifecycle. See [Hooks](/en/hooks) for configuration format. |

196 175

197```176#### Available string substitutions

198Can you help me extract text from this PDF?

199```

200 177

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.178Skills support string substitution for dynamic values in the skill content:

202 179

203## Debug a Skill180| Variable | Description |

181| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |

182| `$ARGUMENTS` | All arguments passed when invoking the skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: <value>`. |

183| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |

204 184

205If Claude doesn't use your Skill, check these common issues:185**Example using substitutions:**

~~206~~

207### Make description specific

~~208~~

209**Too vague**:

210 186

211```yaml theme={null}187```yaml theme={null}

212description: Helps with documents188---

213```189name: session-logger

190description: Log activity for this session

191---

214 192

215**Specific**:193Log the following to logs/${CLAUDE_SESSION_ID}.log:

216 194

217```yaml theme={null}195$ARGUMENTS

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```196```

220 197

221Include both what the Skill does and when to use it in the description.198### Add supporting files

~~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 199

228Check the file exists:200Skills can include multiple files in their directory. This keeps `SKILL.md` focused on the essentials while letting Claude access detailed reference material only when needed. Large reference docs, API specifications, or example collections don't need to load into context every time the skill runs.

~~229~~

230```bash theme={null}

231# Personal

232ls ~/.claude/skills/my-skill/SKILL.md

233 201

234# Project

235ls .claude/skills/my-skill/SKILL.md

236```202```

~~237~~ 203my-skill/

238### Check YAML syntax204├── SKILL.md (required - overview and navigation)

~~239~~ 205├── reference.md (detailed API docs - loaded when needed)

240Invalid YAML prevents the Skill from loading. Verify the frontmatter:206├── examples.md (usage examples - loaded when needed)

~~241~~ 207└── scripts/

242```bash theme={null}208 └── helper.py (utility script - executed, not loaded)

243cat SKILL.md | head -n 10

244```209```

245 210

246Ensure:211Reference supporting files from `SKILL.md` so Claude knows what each file contains and when to load it:

~~247~~

248* Opening `---` on line 1

249* Closing `---` before Markdown content

250* Valid YAML syntax (no tabs, correct indentation)

~~251~~

252### View errors

253 212

254Run Claude Code with debug mode to see Skill loading errors:213```markdown theme={null}

214## Additional resources

255 215

256```bash theme={null}216- For complete API details, see [reference.md](reference.md)

257claude --debug217- For usage examples, see [examples.md](examples.md)

258```218```

259 219

260## Share Skills with your team220<Tip>Keep `SKILL.md` under 500 lines. Move detailed reference material to separate files.</Tip>

261 221

262**Recommended approach**: Distribute Skills through [plugins](/en/docs/claude-code/plugins).222### Control who invokes a skill

263 223

264To share Skills via plugin:224By default, both you and Claude can invoke any skill. You can type `/skill-name` to invoke it directly, and Claude can load it automatically when relevant to your conversation. Two frontmatter fields let you restrict this:

265 225

2661. Create a plugin with Skills in the `skills/` directory226* **`disable-model-invocation: true`**: Only you can invoke the skill. Use this for workflows with side effects or that you want to control timing, like `/commit`, `/deploy`, or `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready.

2672. Add the plugin to a marketplace

2683. Team members install the plugin

269 227

270For complete instructions, see [Add Skills to your plugin](/en/docs/claude-code/plugins#add-skills-to-your-plugin).228* **`user-invocable: false`**: Only Claude can invoke the skill. Use this for background knowledge that isn't actionable as a command. A `legacy-system-context` skill explains how an old system works. Claude should know this when relevant, but `/legacy-system-context` isn't a meaningful action for users to take.

271 229

272You can also share Skills directly through project repositories:230This example creates a deploy skill that only you can trigger. The `disable-model-invocation: true` field prevents Claude from running it automatically:

273 231

274### Step 1: Add Skill to your project232```yaml theme={null}

~~275~~ 233---

276Create a project Skill:234name: deploy

~~277~~ 235description: Deploy the application to production

278```bash theme={null}236disable-model-invocation: true

279mkdir -p .claude/skills/team-skill237---

280# Create SKILL.md

281```

282 238

283### Step 2: Commit to git239Deploy $ARGUMENTS to production:

284 240

285```bash theme={null}2411. Run the test suite

286git add .claude/skills/2422. Build the application

287git commit -m "Add team Skill for PDF processing"2433. Push to the deployment target

288git push2444. Verify the deployment succeeded

289```245```

290 246

291### Step 3: Team members get Skills automatically247Here's how the two fields affect invocation and context loading:

292 248

~~294~~ 250| :------------------------------- | :------------- | :---------------- | :----------------------------------------------------------- |

295```bash theme={null}251| (default) | Yes | Yes | Description always in context, full skill loads when invoked |

298```

299 254

300## Update a Skill255<Note>

256 In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked. [Subagents with preloaded skills](/en/sub-agents#preload-skills-into-subagents) work differently: the full skill content is injected at startup.

257</Note>

301 258

302Edit SKILL.md directly:259### Restrict tool access

303 260

304```bash theme={null}261Use the `allowed-tools` field to limit which tools Claude can use when a skill is active. This skill creates a read-only mode where Claude can explore files but not modify them:

305# Personal Skill

306code ~/.claude/skills/my-skill/SKILL.md

307 262

308# Project Skill263```yaml theme={null}

309code .claude/skills/my-skill/SKILL.md264---

265name: safe-reader

266description: Read files without making changes

267allowed-tools: Read, Grep, Glob

268---

310```269```

311 270

312Changes take effect the next time you start Claude Code. If Claude Code is already running, restart it to load the updates.271### Pass arguments to skills

313 272

314## Remove a Skill273Both you and Claude can pass arguments when invoking a skill. Arguments are available via the `$ARGUMENTS` placeholder.

315 274

316Delete the Skill directory:275This skill fixes a GitHub issue by number. The `$ARGUMENTS` placeholder gets replaced with whatever follows the skill name:

317 276

318```bash theme={null}277```yaml theme={null}

319# Personal278---

320rm -rf ~/.claude/skills/my-skill279name: fix-issue

~~321~~ 280description: Fix a GitHub issue

322# Project281disable-model-invocation: true

323rm -rf .claude/skills/my-skill282---

324git commit -m "Remove unused Skill"

325```

~~326~~

327## Best practices

~~328~~

329### Keep Skills focused

330 283

331One Skill should address one capability:284Fix GitHub issue $ARGUMENTS following our coding standards.

332 285

333**Focused**:2861. Read the issue description

2872. Understand the requirements

2883. Implement the fix

2894. Write tests

2905. Create a commit

291```

334 292

335* "PDF form filling"293When you run `/fix-issue 123`, Claude receives "Fix GitHub issue 123 following our coding standards..."

336* "Excel data analysis"

337* "Git commit messages"

338 294

339**Too broad**:295If you invoke a skill with arguments but the skill doesn't include `$ARGUMENTS`, Claude Code appends `ARGUMENTS: <your input>` to the end of the skill content so Claude still sees what you typed.

340 296

341* "Document processing" (split into separate Skills)297## Advanced patterns

342* "Data tools" (split by data type or operation)

343 298

344### Write clear descriptions299### Inject dynamic context

345 300

346Help Claude discover when to use Skills by including specific triggers in your description:301The `!`command\`\` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself.

347 302

348**Clear**:303This skill summarizes a pull request by fetching live PR data with the GitHub CLI. The `!`gh pr diff\`\` and other commands run first, and their output gets inserted into the prompt:

349 304

350```yaml theme={null}305```yaml theme={null}

351description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.306---

352```307name: pr-summary

308description: Summarize changes in a pull request

309context: fork

310agent: Explore

311allowed-tools: Bash(gh:*)

312---

353 313

354**Vague**:314## Pull request context

315- PR diff: !`gh pr diff`

316- PR comments: !`gh pr view --comments`

317- Changed files: !`gh pr diff --name-only`

355 318

356```yaml theme={null}319## Your task

357description: For files320Summarize this pull request...

358```321```

359 322

360### Test with your team323When this skill runs:

361 324

362Have teammates use Skills and provide feedback:3251. Each `!`command\`\` executes immediately (before Claude sees anything)

3262. The output replaces the placeholder in the skill content

3273. Claude receives the fully-rendered prompt with actual PR data

363 328

364* Does the Skill activate when expected?329This is preprocessing, not something Claude executes. Claude only sees the final result.

365* Are the instructions clear?

366* Are there missing examples or edge cases?

367 330

368### Document Skill versions331<Tip>

332 To enable [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) in a skill, include the word "ultrathink" anywhere in your skill content.

333</Tip>

369 334

370You can document Skill versions in your SKILL.md content to track changes over time. Add a version history section:335### Run skills in a subagent

371 336

372```markdown theme={null}337Add `context: fork` to your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives the subagent. It won't have access to your conversation history.

373# My Skill

~~374~~

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

380 338

381This helps team members understand what changed between versions.339<Warning>

~~382~~ 340 `context: fork` only makes sense for skills with explicit instructions. If your skill contains guidelines like "use these API conventions" without a task, the subagent receives the guidelines but no actionable prompt, and returns without meaningful output.

383## Troubleshooting341</Warning>

384 342

385### Claude doesn't use my Skill343Skills and [subagents](/en/sub-agents) work together in two directions:

386 344

346| :--------------------------- | :---------------------------------------- | :-------------------------- | :--------------------------- |

388 349

389**Check**: Is the description specific enough?350With `context: fork`, you write the task in your skill and pick an agent type to execute it. For the inverse (defining a custom subagent that uses skills as reference material), see [Subagents](/en/sub-agents#preload-skills-into-subagents).

390 351

391Vague descriptions make discovery difficult. Include both what the Skill does and when to use it, with key terms users would mention.352#### Example: Research skill using Explore agent

392 353

393**Too generic**:354This skill runs research in a forked Explore agent. The skill content becomes the task, and the agent provides read-only tools optimized for codebase exploration:

394 355

395```yaml theme={null}356```yaml theme={null}

396description: Helps with data357---

397```358name: deep-research

359description: Research a topic thoroughly

360context: fork

361agent: Explore

362---

398 363

399**Specific**:364Research $ARGUMENTS thoroughly:

400 365

401```yaml theme={null}3661. Find relevant files using Glob and Grep

402description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.3672. Read and analyze the code

3683. Summarize findings with specific file references

403```369```

404 370

405**Check**: Is the YAML valid?371When this skill runs:

~~406~~

407Run validation to check for syntax errors:

408 372

409```bash theme={null}3731. A new isolated context is created

410# View frontmatter3742. The subagent receives the skill content as its prompt ("Research \$ARGUMENTS thoroughly...")

411cat .claude/skills/my-skill/SKILL.md | head -n 153753. The `agent` field determines the execution environment (model, tools, and permissions)

~~412~~ 3764. Results are summarized and returned to your main conversation

413# Check for common issues

414# - Missing opening or closing ---

415# - Tabs instead of spaces

416# - Unquoted strings with special characters

417```

418 377

419**Check**: Is the Skill in the correct location?378The `agent` field specifies which subagent configuration to use. Options include built-in agents (`Explore`, `Plan`, `general-purpose`) or any custom subagent from `.claude/agents/`. If omitted, uses `general-purpose`.

~~420~~

421```bash theme={null}

422# Personal Skills

423ls ~/.claude/skills/*/SKILL.md

424 379

425# Project Skills380### Restrict Claude's skill access

426ls .claude/skills/*/SKILL.md

427```

428 381

429### Skill has errors382By default, Claude can invoke any skill that doesn't have `disable-model-invocation: true` set. Built-in commands like `/compact` and `/init` are not available through the Skill tool.

430 383

431**Symptom**: The Skill loads but doesn't work correctly.384Three ways to control which skills Claude can invoke:

432 385

433**Check**: Are dependencies available?386**Disable all skills** by denying the Skill tool in `/permissions`:

434 387

435Claude will automatically install required dependencies (or ask for permission to install them) when it needs them.388```

389# Add to deny rules:

390Skill

391```

436 392

437**Check**: Do scripts have execute permissions?393**Allow or deny specific skills** using [permission rules](/en/iam):

438 394

439```bash theme={null}

440chmod +x .claude/skills/my-skill/scripts/*.py

441```395```

396# Allow only specific skills

397Skill(commit)

398Skill(review-pr:*)

442 399

443**Check**: Are file paths correct?400# Deny specific skills

401Skill(deploy:*)

402```

444 403

445Use forward slashes (Unix style) in all paths:404Permission syntax: `Skill(name)` for exact match, `Skill(name:*)` for prefix match with any arguments.

446 405

447**Correct**: `scripts/helper.py`406**Hide individual skills** by adding `disable-model-invocation: true` to their frontmatter. This removes the skill from Claude's context entirely.

448**Wrong**: `scripts\helper.py` (Windows style)

449 407

450### Multiple Skills conflict408<Note>

409 The `user-invocable` field only controls menu visibility, not Skill tool access. Use `disable-model-invocation: true` to block programmatic invocation.

410</Note>

451 411

452**Symptom**: Claude uses the wrong Skill or seems confused between similar Skills.412## Share skills

453 413

454**Be specific in descriptions**: Help Claude choose the right Skill by using distinct trigger terms in your descriptions.414Skills can be distributed at different scopes depending on your audience:

455 415

456Instead of:416* **Project skills**: Commit `.claude/skills/` to version control

417* **Plugins**: Create a `skills/` directory in your [plugin](/en/plugins)

418* **Managed**: Deploy organization-wide through [managed settings](/en/iam#managed-settings)

457 419

458```yaml theme={null}420### Generate visual output

459# Skill 1

460description: For data analysis

461 421

462# Skill 2422Skills can bundle and run scripts in any language, giving Claude capabilities beyond what's possible in a single prompt. One powerful pattern is generating visual output: interactive HTML files that open in your browser for exploring data, debugging, or creating reports.

463description: For analyzing data

464```

465 423

466Use:424This example creates a codebase explorer: an interactive tree view where you can expand and collapse directories, see file sizes at a glance, and identify file types by color.

467 425

468```yaml theme={null}426Create the Skill directory:

469# Skill 1

470description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking.

471 427

472# Skill 2428```bash theme={null}

473description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics.429mkdir -p ~/.claude/skills/codebase-visualizer/scripts

474```430```

475 431

476## Examples432Create `~/.claude/skills/codebase-visualizer/SKILL.md`. The description tells Claude when to activate this Skill, and the instructions tell Claude to run the bundled script:

477 433

478### Simple Skill (single file)434````yaml theme={null}

~~479~~

480```

481commit-helper/

482└── SKILL.md

483```

~~484~~

485```yaml theme={null}

486---435---

487name: generating-commit-messages436name: codebase-visualizer

488description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.437description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.

438allowed-tools: Bash(python:*)

489---439---

490 440

491# Generating Commit Messages441# Codebase Visualizer

~~492~~

493## Instructions

494 442

4951. Run `git diff --staged` to see changes443Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.

4962. I'll suggest a commit message with:

497 - Summary under 50 characters

498 - Detailed description

499 - Affected components

500 444

501## Best practices445## Usage

502 446

503- Use present tense447Run the visualization script from your project root:

504- Explain what and why, not how

505```

506 448

507### Skill with tool permissions449```bash

~~508~~ 450python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .

509```

510code-reviewer/

511└── SKILL.md

512```451```

513 452

514```yaml theme={null}453This creates `codebase-map.html` in the current directory and opens it in your default browser.

515name: code-reviewer

516description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.

517allowed-tools: Read, Grep, Glob

518 454

519# Code Reviewer455## What the visualization shows

520 456

521## Review checklist457- **Collapsible directories**: Click folders to expand/collapse

~~522~~ 458- **File sizes**: Displayed next to each file

5231. Code organization and structure459- **Colors**: Different colors for different file types

5242. Error handling460- **Directory totals**: Shows aggregate size of each folder

5253. Performance considerations461````

5264. Security concerns

5275. Test coverage

~~528~~

529## Instructions

~~530~~

5311. Read the target files using Read tool

5322. Search for patterns using Grep

5333. Find related files using Glob

5344. Provide detailed feedback on code quality

535```

~~536~~

537### Multi-file Skill

538 462

539```463Create `~/.claude/skills/codebase-visualizer/scripts/visualize.py`. This script scans a directory tree and generates a self-contained HTML file with:

540pdf-processing/464

541├── SKILL.md465* A **summary sidebar** showing file count, directory count, total size, and number of file types

542├── FORMS.md466* A **bar chart** breaking down the codebase by file type (top 8 by size)

543├── REFERENCE.md467* A **collapsible tree** where you can expand and collapse directories, with color-coded file type indicators

544└── scripts/468

545 ├── fill_form.py469The script requires Python but uses only built-in libraries, so there are no packages to install:

546 └── validate.py470

547```471```python expandable theme={null}

472#!/usr/bin/env python3

473"""Generate an interactive collapsible tree visualization of a codebase."""

474

475import json

476import sys

477import webbrowser

478from pathlib import Path

479from collections import Counter

480

481IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'}

482

483def scan(path: Path, stats: dict) -> dict:

484 result = {"name": path.name, "children": [], "size": 0}

485 try:

486 for item in sorted(path.iterdir()):

487 if item.name in IGNORE or item.name.startswith('.'):

488 continue

489 if item.is_file():

490 size = item.stat().st_size

491 ext = item.suffix.lower() or '(no ext)'

492 result["children"].append({"name": item.name, "size": size, "ext": ext})

493 result["size"] += size

494 stats["files"] += 1

495 stats["extensions"][ext] += 1

496 stats["ext_sizes"][ext] += size

497 elif item.is_dir():

498 stats["dirs"] += 1

499 child = scan(item, stats)

500 if child["children"]:

501 result["children"].append(child)

502 result["size"] += child["size"]

503 except PermissionError:

504 pass

505 return result

506

507def generate_html(data: dict, stats: dict, output: Path) -> None:

508 ext_sizes = stats["ext_sizes"]

509 total_size = sum(ext_sizes.values()) or 1

510 sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8]

511 colors = {

512 '.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8',

513 '.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26',

514 '.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e',

515 '.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25',

516 }

517 lang_bars = "".join(

518 f'<div class="bar-row"><span class="bar-label">{ext}</span>'

519 f'<div class="bar" style="width:{(size/total_size)*100}%;background:{colors.get(ext,"#6b7280")}"></div>'

520 f'<span class="bar-pct">{(size/total_size)*100:.1f}%</span></div>'

521 for ext, size in sorted_exts

522 )

523 def fmt(b):

524 if b < 1024: return f"{b} B"

525 if b < 1048576: return f"{b/1024:.1f} KB"

526 return f"{b/1048576:.1f} MB"

527

528 html = f'''<!DOCTYPE html>

529<html><head>

530 <meta charset="utf-8"><title>Codebase Explorer</title>

531 <style>

532 body {{ font: 14px/1.5 system-ui, sans-serif; margin: 0; background: #1a1a2e; color: #eee; }}

533 .container {{ display: flex; height: 100vh; }}

534 .sidebar {{ width: 280px; background: #252542; padding: 20px; border-right: 1px solid #3d3d5c; overflow-y: auto; flex-shrink: 0; }}

535 .main {{ flex: 1; padding: 20px; overflow-y: auto; }}

536 h1 {{ margin: 0 0 10px 0; font-size: 18px; }}

537 h2 {{ margin: 20px 0 10px 0; font-size: 14px; color: #888; text-transform: uppercase; }}

538 .stat {{ display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #3d3d5c; }}

539 .stat-value {{ font-weight: bold; }}

540 .bar-row {{ display: flex; align-items: center; margin: 6px 0; }}

541 .bar-label {{ width: 55px; font-size: 12px; color: #aaa; }}

542 .bar {{ height: 18px; border-radius: 3px; }}

543 .bar-pct {{ margin-left: 8px; font-size: 12px; color: #666; }}

544 .tree {{ list-style: none; padding-left: 20px; }}

545 details {{ cursor: pointer; }}

546 summary {{ padding: 4px 8px; border-radius: 4px; }}

547 summary:hover {{ background: #2d2d44; }}

548 .folder {{ color: #ffd700; }}

549 .file {{ display: flex; align-items: center; padding: 4px 8px; border-radius: 4px; }}

550 .file:hover {{ background: #2d2d44; }}

551 .size {{ color: #888; margin-left: auto; font-size: 12px; }}

552 .dot {{ width: 8px; height: 8px; border-radius: 50%; margin-right: 8px; }}

553 </style>

554</head><body>

555 <div class="container">

556 <div class="sidebar">

557 <h1>📊 Summary</h1>

558 <div class="stat"><span>Files</span><span class="stat-value">{stats["files"]:,}</span></div>

559 <div class="stat"><span>Directories</span><span class="stat-value">{stats["dirs"]:,}</span></div>

560 <div class="stat"><span>Total size</span><span class="stat-value">{fmt(data["size"])}</span></div>

561 <div class="stat"><span>File types</span><span class="stat-value">{len(stats["extensions"])}</span></div>

562 <h2>By file type</h2>

563 {lang_bars}

564 </div>

565 <div class="main">

566 <h1>📁 {data["name"]}</h1>

567 <ul class="tree" id="root"></ul>

568 </div>

569 </div>

570 <script>

571 const data = {json.dumps(data)};

572 const colors = {json.dumps(colors)};

573 function fmt(b) {{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; }}

574 function render(node, parent) {{

575 if (node.children) {{

576 const det = document.createElement('details');

577 det.open = parent === document.getElementById('root');

578 det.innerHTML = `<summary><span class="folder">📁 ${{node.name}}</span><span class="size">${{fmt(node.size)}}</span></summary>`;

579 const ul = document.createElement('ul'); ul.className = 'tree';

580 node.children.sort((a,b) => (b.children?1:0)-(a.children?1:0) || a.name.localeCompare(b.name));

581 node.children.forEach(c => render(c, ul));

582 det.appendChild(ul);

583 const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);

584 }} else {{

585 const li = document.createElement('li'); li.className = 'file';

586 li.innerHTML = `<span class="dot" style="background:${{colors[node.ext]||'#6b7280'}}"></span>${{node.name}}<span class="size">${{fmt(node.size)}}</span>`;

587 parent.appendChild(li);

588 }}

589 }}

590 data.children.forEach(c => render(c, document.getElementById('root')));

591 </script>

592</body></html>'''

593 output.write_text(html)

594

595if __name__ == '__main__':

596 target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()

597 stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()}

598 data = scan(target, stats)

599 out = Path('codebase-map.html')

600 generate_html(data, stats, out)

601 print(f'Generated {out.absolute()}')

602 webbrowser.open(f'file://{out.absolute()}')

603```

604

605To test, open Claude Code in any project and ask "Visualize this codebase." Claude runs the script, generates `codebase-map.html`, and opens it in your browser.

606

607This pattern works for any visual output: dependency graphs, test coverage reports, API documentation, or database schema visualizations. The bundled script does the heavy lifting while Claude handles orchestration.

548 608

549**SKILL.md**:609## Troubleshooting

550 610

551````yaml theme={null}611### Skill not triggering

552name: pdf-processing

553description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.

554 612

555# PDF Processing613If Claude doesn't use your skill when expected:

556 614

557## Quick start6151. Check the description includes keywords users would naturally say

6162. Verify the skill appears in `What skills are available?`

6173. Try rephrasing your request to match the description more closely

6184. Invoke it directly with `/skill-name` if the skill is user-invocable

558 619

559Extract text:620### Skill triggers too often

560```python

561import pdfplumber

562with pdfplumber.open("doc.pdf") as pdf:

563 text = pdf.pages[0].extract_text()

564```

565 621

566For form filling, see [FORMS.md](FORMS.md).622If Claude uses your skill when you don't want it:

567For detailed API reference, see [REFERENCE.md](REFERENCE.md).

568 623

569## Requirements6241. Make the description more specific

6252. Add `disable-model-invocation: true` if you only want manual invocation

570 626

571Packages must be installed in your environment:627### Claude doesn't see all my skills

572```bash

573pip install pypdf pdfplumber

574```

575````

576 628

577<Note>629Skill descriptions are loaded into context so Claude knows what's available. If you have many skills, they may exceed the character budget (default 15,000 characters). Run `/context` to check for a warning about excluded skills.

578 List required packages in the description. Packages must be installed in your environment before Claude can use them.

579</Note>

580 630

581Claude loads additional files only when needed.631To increase the limit, set the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable.

582 632

583## Next steps633## Related resources

584 634

585<CardGroup cols={2}>635* **[Subagents](/en/sub-agents)**: delegate tasks to specialized agents

586 <Card title="Authoring best practices" icon="lightbulb" href="/en/docs/agents-and-tools/agent-skills/best-practices">636* **[Plugins](/en/plugins)**: package and distribute skills with other extensions

587 Write Skills that Claude can use effectively637* **[Hooks](/en/hooks)**: automate workflows around tool events

588 </Card>638* **[Memory](/en/memory)**: manage CLAUDE.md files for persistent context

639* **[Interactive mode](/en/interactive-mode#built-in-commands)**: built-in commands and shortcuts

640* **[Permissions](/en/iam)**: control tool and skill access

589 641

590 <Card title="Agent Skills overview" icon="book" href="/en/docs/agents-and-tools/agent-skills/overview">

591 Learn how Skills work across Claude products

592 </Card>

593 642

594 <Card title="Use Skills in the Agent SDK" icon="cube" href="/en/api/agent-sdk/skills">643---

595 Use Skills programmatically with TypeScript and Python

596 </Card>

597 644

598 <Card title="Get started with Agent Skills" icon="rocket" href="/en/docs/agents-and-tools/agent-skills/quickstart">645> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

599 Create your first Skill

600 </Card>

601</CardGroup>

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 +0 −482 deleted

File DeletedView Diff

~~1# Slash commands~~

~~3> Control Claude's behavior during an interactive session with slash commands.~~

~~5## Built-in slash commands~~

~~7| Command | Purpose |~~

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

~~9| `/add-dir` | Add additional working directories |~~

~~10| `/agents` | Manage custom AI subagents for specialized tasks |~~

~~11| `/bug` | Report bugs (sends conversation to Anthropic) |~~

~~12| `/clear` | Clear conversation history |~~

~~13| `/compact [instructions]` | Compact conversation with optional focus instructions |~~

~~14| `/config` | Open the Settings interface (Config tab) |~~

~~15| `/cost` | Show token usage statistics (see [cost tracking guide](/en/docs/claude-code/costs#using-the-cost-command) for subscription-specific details) |~~

~~16| `/doctor` | Checks the health of your Claude Code installation |~~

~~17| `/help` | Get usage help |~~

~~18| `/init` | Initialize project with CLAUDE.md guide |~~

~~19| `/login` | Switch Anthropic accounts |~~

~~20| `/logout` | Sign out from your Anthropic account |~~

~~21| `/mcp` | Manage MCP server connections and OAuth authentication |~~

~~22| `/memory` | Edit CLAUDE.md memory files |~~

~~23| `/model` | Select or change the AI model |~~

~~24| `/permissions` | View or update [permissions](/en/docs/claude-code/iam#configuring-permissions) |~~

~~25| `/pr_comments` | View pull request comments |~~

~~26| `/review` | Request code review |~~

~~27| `/sandbox` | Enable sandboxed bash tool with filesystem and network isolation for safer, more autonomous execution |~~

~~28| `/rewind` | Rewind the conversation and/or code |~~

~~29| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |~~

~~30| `/terminal-setup` | Install Shift+Enter key binding for newlines (iTerm2 and VSCode only) |~~

~~31| `/usage` | Show plan usage limits and rate limit status (subscription plans only) |~~

~~32| `/vim` | Enter vim mode for alternating insert and command modes |~~

~~34## Custom slash commands~~

36Custom 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.

~~38### Syntax~~

~~40```~~

~~41/<command-name> [arguments]~~

~~42```~~

~~44#### Parameters~~

~~46| Parameter | Description |~~

~~47| :--------------- | :---------------------------------------------------------------- |~~

~~48| `<command-name>` | Name derived from the Markdown filename (without `.md` extension) |~~

~~49| `[arguments]` | Optional arguments passed to the command |~~

~~51### Command types~~

~~53#### Project commands~~

~~55Commands stored in your repository and shared with your team. When listed in `/help`, these commands show "(project)" after their description.~~

~~57**Location**: `.claude/commands/`~~

~~59In the following example, we create the `/optimize` command:~~

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

~~62# Create a project command~~

~~63mkdir -p .claude/commands~~

~~64echo "Analyze this code for performance issues and suggest optimizations:" > .claude/commands/optimize.md~~

~~65```~~

~~67#### Personal commands~~

~~69Commands available across all your projects. When listed in `/help`, these commands show "(user)" after their description.~~

~~71**Location**: `~/.claude/commands/`~~

~~73In the following example, we create the `/security-review` command:~~

~~75```bash theme={null}~~

~~76# Create a personal command~~

~~77mkdir -p ~/.claude/commands~~

~~78echo "Review this code for security vulnerabilities:" > ~/.claude/commands/security-review.md~~

~~79```~~

~~81### Features~~

~~83#### Namespacing~~

85Organize 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.

~~87Conflicts between user and project level commands are not supported. Otherwise, multiple commands with the same base file name can coexist.~~

~~89For example, a file at `.claude/commands/frontend/component.md` creates the command `/component` with description showing "(project:frontend)".~~

~~90Meanwhile, a file at `~/.claude/commands/component.md` creates the command `/component` with description showing "(user)".~~

~~92#### Arguments~~

~~94Pass dynamic values to commands using argument placeholders:~~

~~96##### All arguments with `$ARGUMENTS`~~

~~98The `$ARGUMENTS` placeholder captures all arguments passed to the command:~~

100```bash theme={null}

101# Command definition

102echo 'Fix issue #$ARGUMENTS following our coding standards' > .claude/commands/fix-issue.md

~~103~~

104# Usage

105> /fix-issue 123 high-priority

106# $ARGUMENTS becomes: "123 high-priority"

107```

~~108~~

109##### Individual arguments with `$1`, `$2`, etc.

~~110~~

111Access specific arguments individually using positional parameters (similar to shell scripts):

~~112~~

113```bash theme={null}

114# Command definition

115echo 'Review PR #$1 with priority $2 and assign to $3' > .claude/commands/review-pr.md

~~116~~

117# Usage

118> /review-pr 456 high alice

119# $1 becomes "456", $2 becomes "high", $3 becomes "alice"

120```

~~121~~

122Use positional arguments when you need to:

~~123~~

124* Access arguments individually in different parts of your command

125* Provide defaults for missing arguments

126* Build more structured commands with specific parameter roles

~~127~~

128#### Bash command execution

~~129~~

130Execute bash commands before the slash command runs using the `!` prefix. The output is included in the command context. You *must* include `allowed-tools` with the `Bash` tool, but you can choose the specific bash commands to allow.

~~131~~

132For example:

~~133~~

134```markdown theme={null}

135allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)

136description: Create a git commit

~~137~~

138## Context

~~139~~

140- Current git status: !`git status`

141- Current git diff (staged and unstaged changes): !`git diff HEAD`

142- Current branch: !`git branch --show-current`

143- Recent commits: !`git log --oneline -10`

~~144~~

145## Your task

~~146~~

147Based on the above changes, create a single git commit.

148```

~~149~~

150#### File references

~~151~~

152Include file contents in commands using the `@` prefix to [reference files](/en/docs/claude-code/common-workflows#reference-files-and-directories).

~~153~~

154For example:

~~155~~

156```markdown theme={null}

157# Reference a specific file

~~158~~

159Review the implementation in @src/utils/helpers.js

~~160~~

161# Reference multiple files

~~162~~

163Compare @src/old-version.js with @src/new-version.js

164```

~~165~~

166#### Thinking mode

~~167~~

168Slash commands can trigger extended thinking by including [extended thinking keywords](/en/docs/claude-code/common-workflows#use-extended-thinking).

~~169~~

170### Frontmatter

~~171~~

172Command files support frontmatter, useful for specifying metadata about the command:

~~173~~

174| Frontmatter | Purpose | Default |

175| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------- |

176| `allowed-tools` | List of tools the command can use | Inherits from the conversation |

178| `description` | Brief description of the command | Uses the first line from the prompt |

179| `model` | Specific model string (see [Models overview](/en/docs/about-claude/models/overview)) | Inherits from the conversation |

180| `disable-model-invocation` | Whether to prevent `SlashCommand` tool from calling this command | false |

~~181~~

182For example:

~~183~~

184```markdown theme={null}

185allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)

186argument-hint: [message]

187description: Create a git commit

188model: claude-3-5-haiku-20241022

~~189~~

190Create a git commit with message: $ARGUMENTS

191```

~~192~~

193Example using positional arguments:

~~194~~

195```markdown theme={null}

196argument-hint: [pr-number] [priority] [assignee]

197description: Review pull request

~~198~~

199Review PR #$1 with priority $2 and assign to $3.

200Focus on security, performance, and code style.

201```

~~202~~

203## Plugin commands

~~204~~

205[Plugins](/en/docs/claude-code/plugins) can provide custom slash commands that integrate seamlessly with Claude Code. Plugin commands work exactly like user-defined commands but are distributed through [plugin marketplaces](/en/docs/claude-code/plugin-marketplaces).

~~206~~

207### How plugin commands work

~~208~~

209Plugin commands are:

~~210~~

211* **Namespaced**: Commands can use the format `/plugin-name:command-name` to avoid conflicts (plugin prefix is optional unless there are name collisions)

212* **Automatically available**: Once a plugin is installed and enabled, its commands appear in `/help`

213* **Fully integrated**: Support all command features (arguments, frontmatter, bash execution, file references)

~~214~~

215### Plugin command structure

~~216~~

217**Location**: `commands/` directory in plugin root

~~218~~

219**File format**: Markdown files with frontmatter

~~220~~

221**Basic command structure**:

~~222~~

223```markdown theme={null}

224description: Brief description of what the command does

~~225~~

226# Command Name

~~227~~

228Detailed instructions for Claude on how to execute this command.

229Include specific guidance on parameters, expected outcomes, and any special considerations.

230```

~~231~~

232**Advanced command features**:

~~233~~

234* **Arguments**: Use placeholders like `{arg1}` in command descriptions

235* **Subdirectories**: Organize commands in subdirectories for namespacing

236* **Bash integration**: Commands can execute shell scripts and programs

237* **File references**: Commands can reference and modify project files

~~238~~

239### Invocation patterns

~~240~~

241```shell Direct command (when no conflicts) theme={null}

242/command-name

243```

~~244~~

245```shell Plugin-prefixed (when needed for disambiguation) theme={null}

246/plugin-name:command-name

247```

~~248~~

249```shell With arguments (if command supports them) theme={null}

250/command-name arg1 arg2

251```

~~252~~

253## MCP slash commands

~~254~~

255MCP servers can expose prompts as slash commands that become available in Claude Code. These commands are dynamically discovered from connected MCP servers.

~~256~~

257### Command format

~~258~~

259MCP commands follow the pattern:

~~260~~

261```

262/mcp__<server-name>__<prompt-name> [arguments]

263```

~~264~~

265### Features

~~266~~

267#### Dynamic discovery

~~268~~

269MCP commands are automatically available when:

~~270~~

271* An MCP server is connected and active

272* The server exposes prompts through the MCP protocol

273* The prompts are successfully retrieved during connection

~~274~~

275#### Arguments

~~276~~

277MCP prompts can accept arguments defined by the server:

~~278~~

279```

280# Without arguments

281> /mcp__github__list_prs

~~282~~

283# With arguments

284> /mcp__github__pr_review 456

285> /mcp__jira__create_issue "Bug title" high

286```

~~287~~

288#### Naming conventions

~~289~~

290* Server and prompt names are normalized

291* Spaces and special characters become underscores

292* Names are lowercased for consistency

~~293~~

294### Managing MCP connections

~~295~~

296Use the `/mcp` command to:

~~297~~

298* View all configured MCP servers

299* Check connection status

300* Authenticate with OAuth-enabled servers

301* Clear authentication tokens

302* View available tools and prompts from each server

~~303~~

304### MCP permissions and wildcards

~~305~~

306When configuring [permissions for MCP tools](/en/docs/claude-code/iam#tool-specific-permission-rules), note that **wildcards are not supported**:

~~307~~

308* ✅ **Correct**: `mcp__github` (approves ALL tools from the github server)

309* ✅ **Correct**: `mcp__github__get_issue` (approves specific tool)

310* ❌ **Incorrect**: `mcp__github__*` (wildcards not supported)

~~311~~

312To approve all tools from an MCP server, use just the server name: `mcp__servername`. To approve specific tools only, list each tool individually.

~~313~~

314## `SlashCommand` tool

~~315~~

316The `SlashCommand` tool allows Claude to execute [custom slash commands](/en/docs/claude-code/slash-commands#custom-slash-commands) programmatically

317during a conversation. This gives Claude the ability to invoke custom commands

318on your behalf when appropriate.

~~319~~

320To encourage Claude to trigger `SlashCommand` tool, your instructions (prompts,

321CLAUDE.md, etc.) generally need to reference the command by name with its slash.

~~322~~

323Example:

~~324~~

325```

326> Run /write-unit-test when you are about to start writing tests.

327```

~~328~~

329This tool puts each available custom slash command's metadata into context up to the

330character budget limit. You can use `/context` to monitor token usage and follow

331the operations below to manage context.

~~332~~

333### `SlashCommand` tool supported commands

~~334~~

335`SlashCommand` tool only supports custom slash commands that:

~~336~~

337* Are user-defined. Built-in commands like `/compact` and `/init` are *not* supported.

338* Have the `description` frontmatter field populated. We use the `description` in the context.

~~339~~

340For Claude Code versions >= 1.0.124, you can see which custom slash commands

341`SlashCommand` tool can invoke by running `claude --debug` and triggering a query.

~~342~~

343### Disable `SlashCommand` tool

~~344~~

345To prevent Claude from executing any slash commands via the tool:

~~346~~

347```bash theme={null}

348/permissions

349# Add to deny rules: SlashCommand

350```

~~351~~

352This will also remove SlashCommand tool (and the slash command descriptions) from context.

~~353~~

354### Disable specific commands only

~~355~~

356To prevent a specific slash command from becoming available, add

357`disable-model-invocation: true` to the slash command's frontmatter.

~~358~~

359This will also remove the command's metadata from context.

~~360~~

361### `SlashCommand` permission rules

~~362~~

363The permission rules support:

~~364~~

365* **Exact match**: `SlashCommand:/commit` (allows only `/commit` with no arguments)

366* **Prefix match**: `SlashCommand:/review-pr:*` (allows `/review-pr` with any arguments)

~~367~~

368### Character budget limit

~~369~~

370The `SlashCommand` tool includes a character budget to limit the size of command

371descriptions shown to Claude. This prevents token overflow when many commands

372are available.

~~373~~

374The budget includes each custom slash command's name, args, and description.

~~375~~

376* **Default limit**: 15,000 characters

377* **Custom limit**: Set via `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable

~~378~~

379When the character budget is exceeded, Claude will see only a subset of the

380available commands. In `/context`, a warning will show with "M of N commands".

~~381~~

382## Skills vs slash commands

~~383~~

384**Slash commands** and **Agent Skills** serve different purposes in Claude Code:

~~385~~

386### Use slash commands for

~~387~~

388**Quick, frequently-used prompts**:

~~389~~

390* Simple prompt snippets you use often

391* Quick reminders or templates

392* Frequently-used instructions that fit in one file

~~393~~

394**Examples**:

~~395~~

396* `/review` → "Review this code for bugs and suggest improvements"

397* `/explain` → "Explain this code in simple terms"

398* `/optimize` → "Analyze this code for performance issues"

~~399~~

400### Use Skills for

~~401~~

402**Comprehensive capabilities with structure**:

~~403~~

404* Complex workflows with multiple steps

405* Capabilities requiring scripts or utilities

406* Knowledge organized across multiple files

407* Team workflows you want to standardize

~~408~~

409**Examples**:

~~410~~

411* PDF processing Skill with form-filling scripts and validation

412* Data analysis Skill with reference docs for different data types

413* Documentation Skill with style guides and templates

~~414~~

415### Key differences

~~416~~

417| Aspect | Slash Commands | Agent Skills |

418| -------------- | -------------------------------- | ----------------------------------- |

419| **Complexity** | Simple prompts | Complex capabilities |

420| **Structure** | Single .md file | Directory with SKILL.md + resources |

421| **Discovery** | Explicit invocation (`/command`) | Automatic (based on context) |

422| **Files** | One file only | Multiple files, scripts, templates |

423| **Scope** | Project or personal | Project or personal |

424| **Sharing** | Via git | Via git |

~~425~~

426### Example comparison

~~427~~

428**As a slash command**:

~~429~~

430```markdown theme={null}

431# .claude/commands/review.md

432Review this code for:

433- Security vulnerabilities

434- Performance issues

435- Code style violations

436```

~~437~~

438Usage: `/review` (manual invocation)

~~439~~

440**As a Skill**:

~~441~~

442```

443.claude/skills/code-review/

444├── SKILL.md (overview and workflows)

445├── SECURITY.md (security checklist)

446├── PERFORMANCE.md (performance patterns)

447├── STYLE.md (style guide reference)

448└── scripts/

449 └── run-linters.sh

450```

~~451~~

452Usage: "Can you review this code?" (automatic discovery)

~~453~~

454The Skill provides richer context, validation scripts, and organized reference material.

~~455~~

456### When to use each

~~457~~

458**Use slash commands**:

~~459~~

460* You invoke the same prompt repeatedly

461* The prompt fits in a single file

462* You want explicit control over when it runs

~~463~~

464**Use Skills**:

~~465~~

466* Claude should discover the capability automatically

467* Multiple files or scripts are needed

468* Complex workflows with validation steps

469* Team needs standardized, detailed guidance

~~470~~

471Both slash commands and Skills can coexist. Use the approach that fits your needs.

~~472~~

473Learn more about [Agent Skills](/en/docs/claude-code/skills).

~~474~~

475## See also

~~476~~

477* [Plugins](/en/docs/claude-code/plugins) - Extend Claude Code with custom commands through plugins

478* [Identity and Access Management](/en/docs/claude-code/iam) - Complete guide to permissions, including MCP tool permissions

479* [Interactive mode](/en/docs/claude-code/interactive-mode) - Shortcuts, input modes, and interactive features

480* [CLI reference](/en/docs/claude-code/cli-reference) - Command-line flags and options

481* [Settings](/en/docs/claude-code/settings) - Configuration options

482* [Memory management](/en/docs/claude-code/memory) - Managing Claude's memory across sessions

statusline.md +69 −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 "used_percentage": 42.5,

67 "remaining_percentage": 57.5,

68 "current_usage": {

69 "input_tokens": 8500,

70 "output_tokens": 1200,

71 "cache_creation_input_tokens": 5000,

72 "cache_read_input_tokens": 2000

73 }

61 }74 }

62}75}

63```76```

181get_duration() { echo "$input" | jq -r '.cost.total_duration_ms'; }194get_duration() { echo "$input" | jq -r '.cost.total_duration_ms'; }

182get_lines_added() { echo "$input" | jq -r '.cost.total_lines_added'; }195get_lines_added() { echo "$input" | jq -r '.cost.total_lines_added'; }

183get_lines_removed() { echo "$input" | jq -r '.cost.total_lines_removed'; }196get_lines_removed() { echo "$input" | jq -r '.cost.total_lines_removed'; }

197get_input_tokens() { echo "$input" | jq -r '.context_window.total_input_tokens'; }

198get_output_tokens() { echo "$input" | jq -r '.context_window.total_output_tokens'; }

199get_context_window_size() { echo "$input" | jq -r '.context_window.context_window_size'; }

184 200

185# Use the helpers201# Use the helpers

186MODEL=$(get_model_name)202MODEL=$(get_model_name)

188echo "[$MODEL] 📁 ${DIR##*/}"204echo "[$MODEL] 📁 ${DIR##*/}"

189```205```

190 206

207### Context Window Usage

208

209Display the percentage of context window consumed. The `context_window` object contains:

210

211* `total_input_tokens` / `total_output_tokens`: Cumulative totals across the entire session

212* `used_percentage`: Pre-calculated percentage of context window used (0-100)

213* `remaining_percentage`: Pre-calculated percentage of context window remaining (0-100)

214* `current_usage`: Current context window usage from the last API call (may be `null` if no messages yet)

215 * `input_tokens`: Input tokens in current context

216 * `output_tokens`: Output tokens generated

217 * `cache_creation_input_tokens`: Tokens written to cache

218 * `cache_read_input_tokens`: Tokens read from cache

219

220You can use the pre-calculated `used_percentage` and `remaining_percentage` fields directly, or calculate from `current_usage` for more control.

221

222**Simple approach using pre-calculated percentages:**

223

224```bash theme={null}

225#!/bin/bash

226input=$(cat)

227

228MODEL=$(echo "$input" | jq -r '.model.display_name')

229PERCENT_USED=$(echo "$input" | jq -r '.context_window.used_percentage // 0')

230

231echo "[$MODEL] Context: ${PERCENT_USED}%"

232```

233

234**Advanced approach with manual calculation:**

235

236```bash theme={null}

237#!/bin/bash

238input=$(cat)

239

240MODEL=$(echo "$input" | jq -r '.model.display_name')

241CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')

242USAGE=$(echo "$input" | jq '.context_window.current_usage')

243

244if [ "$USAGE" != "null" ]; then

245 # Calculate current context from current_usage fields

246 CURRENT_TOKENS=$(echo "$USAGE" | jq '.input_tokens + .cache_creation_input_tokens + .cache_read_input_tokens')

247 PERCENT_USED=$((CURRENT_TOKENS * 100 / CONTEXT_SIZE))

248 echo "[$MODEL] Context: ${PERCENT_USED}%"

249else

250 echo "[$MODEL] Context: 0%"

251fi

252```

253

191## Tips254## Tips

192 255

193* Keep your status line concise - it should fit on one line256* Keep your status line concise - it should fit on one line

200 263

201* If your status line doesn't appear, check that your script is executable (`chmod +x`)264* If your status line doesn't appear, check that your script is executable (`chmod +x`)

202* Ensure your script outputs to stdout (not stderr)265* Ensure your script outputs to stdout (not stderr)

266

267

268---

269

270> 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 +504 −155

Details

~~1# Subagents~~1# Create custom subagents

2 2

3> Create and use specialized AI subagents in Claude Code for task-specific workflows and improved context management.3> Create and use specialized AI subagents in Claude Code for task-specific workflows and improved context management.

4 4

5Custom subagents in Claude Code are specialized AI assistants that can be invoked to handle specific types of tasks. They enable more efficient problem-solving by providing task-specific configurations with customized system prompts, tools and a separate context window.5Subagents are specialized AI assistants that handle specific types of tasks. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently and returns results.

6 6

~~7## What are subagents?~~7Subagents help you:

8 8

~~9Subagents are pre-configured AI personalities that Claude Code can delegate tasks to. Each subagent:~~9* **Preserve context** by keeping exploration and implementation out of your main conversation

10* **Enforce constraints** by limiting which tools a subagent can use

11* **Reuse configurations** across projects with user-level subagents

12* **Specialize behavior** with focused system prompts for specific domains

13* **Control costs** by routing tasks to faster, cheaper models like Haiku

10 14

~~11* Has a specific purpose and expertise area~~15Claude uses each subagent's description to decide when to delegate tasks. When you create a subagent, write a clear description so Claude knows when to use it.

~~12* Uses its own context window separate from the main conversation~~

~~13* Can be configured with specific tools it's allowed to use~~

~~14* Includes a custom system prompt that guides its behavior~~

15 16

~~16When Claude Code encounters a task that matches a subagent's expertise, it can delegate that task to the specialized subagent, which works independently and returns results.~~17Claude Code includes several built-in subagents like **Explore**, **Plan**, and **general-purpose**. You can also create custom subagents to handle specific tasks. This page covers the [built-in subagents](#built-in-subagents), [how to create your own](#quickstart-create-your-first-subagent), [full configuration options](#configure-subagents), [patterns for working with subagents](#work-with-subagents), and [example subagents](#example-subagents).

17 18

~~18## Key benefits~~19## Built-in subagents

19 20

~~20<CardGroup cols={2}>~~21Claude Code includes built-in subagents that Claude automatically uses when appropriate. Each inherits the parent conversation's permissions with additional tool restrictions.

~~21 <Card title="Context preservation" icon="layer-group">~~

~~22 Each subagent operates in its own context, preventing pollution of the main conversation and keeping it focused on high-level objectives.~~

~~23 </Card>~~

24 22

~~25 <Card title="Specialized expertise" icon="brain">~~23<Tabs>

~~26 Subagents can be fine-tuned with detailed instructions for specific domains, leading to higher success rates on designated tasks.~~24 <Tab title="Explore">

~~27 </Card>~~25 A fast, read-only agent optimized for searching and analyzing codebases.

28 26

~~29 <Card title="Reusability" icon="rotate">~~27 * **Model**: Haiku (fast, low-latency)

~~30 Once created, subagents can be used across different projects and shared with your team for consistent workflows.~~28 * **Tools**: Read-only tools (denied access to Write and Edit tools)

~~31 </Card>~~29 * **Purpose**: File discovery, code search, codebase exploration

32 30

~~33 <Card title="Flexible permissions" icon="shield-check">~~31 Claude delegates to Explore when it needs to search or understand a codebase without making changes. This keeps exploration results out of your main conversation context.

~~34 Each subagent can have different tool access levels, allowing you to limit powerful tools to specific subagent types.~~

~~35 </Card>~~

~~36</CardGroup>~~

37 32

~~38## Quick start~~33 When invoking Explore, Claude specifies a thoroughness level: **quick** for targeted lookups, **medium** for balanced exploration, or **very thorough** for comprehensive analysis.

34 </Tab>

39 35

~~40To create your first subagent:~~36 <Tab title="Plan">

37 A research agent used during [plan mode](/en/common-workflows#use-plan-mode-for-safe-code-analysis) to gather context before presenting a plan.

39 * **Model**: Inherits from main conversation

40 * **Tools**: Read-only tools (denied access to Write and Edit tools)

41 * **Purpose**: Codebase research for planning

43 When you're in plan mode and Claude needs to understand your codebase, it delegates research to the Plan subagent. This prevents infinite nesting (subagents cannot spawn other subagents) while still gathering necessary context.

44 </Tab>

46 <Tab title="General-purpose">

47 A capable agent for complex, multi-step tasks that require both exploration and action.

49 * **Model**: Inherits from main conversation

50 * **Tools**: All tools

51 * **Purpose**: Complex research, multi-step operations, code modifications

53 Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps.

54 </Tab>

56 <Tab title="Other">

57 Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly.

59 | Agent | Model | When Claude uses it |

60 | :---------------- | :------- | :------------------------------------------------------- |

61 | Bash | Inherits | Running terminal commands in a separate context |

62 | statusline-setup | Sonnet | When you run `/statusline` to configure your status line |

63 | Claude Code Guide | Haiku | When you ask questions about Claude Code features |

64 </Tab>

65</Tabs>

67Beyond these built-in subagents, you can create your own with custom prompts, tool restrictions, permission modes, hooks, and skills. The following sections show how to get started and customize subagents.

69## Quickstart: create your first subagent

71Subagents are defined in Markdown files with YAML frontmatter. You can [create them manually](#write-subagent-files) or use the `/agents` command.

73This walkthrough guides you through creating a user-level subagent with the `/agent` command. The subagent reviews code and suggests improvements for the codebase.

41 74

42<Steps>75<Steps>

43 <Step title="Open the subagents interface">76 <Step title="Open the subagents interface">

~~44 Run the following command:~~77 In Claude Code, run:

45 78

46 ```79 ```

47 /agents80 /agents

48 ```81 ```

49 </Step>82 </Step>

50 83

~~51 <Step title="Select 'Create New Agent'">~~84 <Step title="Create a new user-level agent">

~~52 Choose whether to create a project-level or user-level subagent~~85 Select **Create new agent**, then choose **User-level**. This saves the subagent to `~/.claude/agents/` so it's available in all your projects.

86 </Step>

88 <Step title="Generate with Claude">

89 Select **Generate with Claude**. When prompted, describe the subagent:

91 ```

92 A code improvement agent that scans files and suggests improvements

93 for readability, performance, and best practices. It should explain

94 each issue, show the current code, and provide an improved version.

95 ```

97 Claude generates the system prompt and configuration. Press `e` to open it in your editor if you want to customize it.

98 </Step>

100 <Step title="Select tools">

101 For a read-only reviewer, deselect everything except **Read-only tools**. If you keep all tools selected, the subagent inherits all tools available to the main conversation.

102 </Step>

103

104 <Step title="Select model">

105 Choose which model the subagent uses. For this example agent, select **Sonnet**, which balances capability and speed for analyzing code patterns.

53 </Step>106 </Step>

54 107

~~55 <Step title="Define the subagent">~~108 <Step title="Choose a color">

~~56 * **Recommended**: Generate with Claude first, then customize to make it yours~~109 Pick a background color for the subagent. This helps you identify which subagent is running in the UI.

~~57 * Describe your subagent in detail and when it should be used~~

~~58 * Select the tools you want to grant access to (or leave blank to inherit all tools)~~

~~59 * The interface shows all available tools, making selection easy~~

~~60 * If you're generating with Claude, you can also edit the system prompt in your own editor by pressing `e`~~

61 </Step>110 </Step>

62 111

~~63 <Step title="Save and use">~~112 <Step title="Save and try it out">

~~64 Your subagent is now available! Claude will use it automatically when appropriate, or you can invoke it explicitly:~~113 Save the subagent. It's available immediately (no restart needed). Try it:

65 114

66 ```115 ```

~~67 > Use the code-reviewer subagent to check my recent changes~~116 Use the code-improver agent to suggest improvements in this project

68 ```117 ```

118

119 Claude delegates to your new subagent, which scans the codebase and returns improvement suggestions.

69 </Step>120 </Step>

70</Steps>121</Steps>

71 122

~~72## Subagent configuration~~123You now have a subagent you can use in any project on your machine to analyze codebases and suggest improvements.

73 124

~~74### File locations~~125You can also create subagents manually as Markdown files, define them via CLI flags, or distribute them through plugins. The following sections cover all configuration options.

75 126

~~76Subagents are stored as Markdown files with YAML frontmatter in two possible locations:~~127## Configure subagents

77 128

~~79| :-------------------- | :------------------ | :---------------------------- | :------- |~~

82 130

~~83When subagent names conflict, project-level subagents take precedence over user-level subagents.~~131The `/agents` command provides an interactive interface for managing subagents. Run `/agents` to:

84 132

~~85### Plugin agents~~133* View all available subagents (built-in, user, project, and plugin)

134* Create new subagents with guided setup or Claude generation

135* Edit existing subagent configuration and tool access

136* Delete custom subagents

137* See which subagents are active when duplicates exist

86 138

87[Plugins](/en/docs/claude-code/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.139This is the recommended way to create and manage subagents. For manual creation or automation, you can also add subagent files directly.

88 140

~~89**Plugin agent locations**: Plugins include agents in their `agents/` directory (or custom paths specified in the plugin manifest).~~141### Choose the subagent scope

90 142

~~91**Using plugin agents**:~~143Subagents are Markdown files with YAML frontmatter. Store them in different locations depending on scope. When multiple subagents share the same name, the higher-priority location wins.

92 144

~~94* Can be invoked explicitly: "Use the code-reviewer agent from the security-plugin"~~146| :--------------------------- | :---------------------- | :---------- | :------------------------------------ |

97 151

~~98See the [plugin components reference](/en/docs/claude-code/plugins-reference#agents) for details on creating plugin agents.~~152**Project subagents** (`.claude/agents/`) are ideal for subagents specific to a codebase. Check them into version control so your team can use and improve them collaboratively.

99 153

100### CLI-based configuration154**User subagents** (`~/.claude/agents/`) are personal subagents available in all your projects.

101 155

102You can also define subagents dynamically using the `--agents` CLI flag, which accepts a JSON object:156**CLI-defined subagents** are passed as JSON when launching Claude Code. They exist only for that session and aren't saved to disk, making them useful for quick testing or automation scripts:

103 157

104```bash theme={null}158```bash theme={null}

105claude --agents '{159claude --agents '{

112}'166}'

113```167```

114 168

115**Priority**: CLI-defined subagents have lower priority than project-level subagents but higher priority than user-level subagents.169The `--agents` flag accepts JSON with the same fields as [frontmatter](#supported-frontmatter-fields). Use `prompt` for the system prompt (equivalent to the markdown body in file-based subagents). See the [CLI reference](/en/cli-reference#agents-flag-format) for the full JSON format.

116 170

117**Use case**: This approach is useful for:171**Plugin subagents** come from [plugins](/en/plugins) you've installed. They appear in `/agents` alongside your custom subagents. See the [plugin components reference](/en/plugins-reference#agents) for details on creating plugin subagents.

118 172

119* Quick testing of subagent configurations173### Write subagent files

120* Session-specific subagents that don't need to be saved

121* Automation scripts that need custom subagents

122* Sharing subagent definitions in documentation or scripts

123 174

124For detailed information about the JSON format and all available options, see the [CLI reference documentation](/en/docs/claude-code/cli-reference#agents-flag-format).175Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown:

125 176

126### File format177<Note>

~~127~~ 178 Subagents are loaded at session start. If you create a subagent by manually adding a file, restart your session or use `/agents` to load it immediately.

128Each subagent is defined in a Markdown file with this structure:179</Note>

129 180

130```markdown theme={null}181```markdown theme={null}

131---182---

132name: your-sub-agent-name183name: code-reviewer

133description: Description of when this subagent should be invoked184description: Reviews code for quality and best practices

134tools: tool1, tool2, tool3 # Optional - inherits all tools if omitted185tools: Read, Glob, Grep

135model: sonnet # Optional - specify model alias or 'inherit'186model: sonnet

136---187---

137 188

138Your subagent's system prompt goes here. This can be multiple paragraphs189You are a code reviewer. When invoked, analyze the code and provide

139and should clearly define the subagent's role, capabilities, and approach190specific, actionable feedback on quality, security, and best practices.

140to solving problems.

~~141~~

142Include specific instructions, best practices, and any constraints

143the subagent should follow.

144```191```

145 192

146#### Configuration fields193The frontmatter defines the subagent's metadata and configuration. The body becomes the system prompt that guides the subagent's behavior. Subagents receive only this system prompt (plus basic environment details like working directory), not the full Claude Code system prompt.

194

195#### Supported frontmatter fields

196

197The following fields can be used in the YAML frontmatter. Only `name` and `description` are required.

147 198

149| :------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |200| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

150| `name` | Yes | Unique identifier using lowercase letters and hyphens |201| `name` | Yes | Unique identifier using lowercase letters and hyphens |

151| `description` | Yes | Natural language description of the subagent's purpose |202| `description` | Yes | When Claude should delegate to this subagent |

152| `tools` | No | Comma-separated list of specific tools. If omitted, inherits all tools from the main thread |203| `tools` | No | [Tools](#available-tools) the subagent can use. Inherits all tools if omitted |

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/docs/claude-code/model-config) |204| `disallowedTools` | No | Tools to deny, removed from inherited or specified list |

205| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, or `inherit`. Defaults to `inherit` |

206| `permissionMode` | No | [Permission mode](#permission-modes): `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan` |

207| `skills` | No | [Skills](/en/skills) to load into the subagent's context at startup. The full skill content is injected, not just made available for invocation. Subagents don't inherit skills from the parent conversation |

208| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) scoped to this subagent |

154 209

155### Model selection210### Choose a model

156 211

157The `model` field allows you to control which [AI model](/en/docs/claude-code/model-config) the subagent uses:212The `model` field controls which [AI model](/en/model-config) the subagent uses:

158 213

159* **Model alias**: Use one of the available aliases: `sonnet`, `opus`, or `haiku`214* **Model alias**: Use one of the available aliases: `sonnet`, `opus`, or `haiku`

160* **`'inherit'`**: Use the same model as the main conversation (useful for consistency)215* **inherit**: Use the same model as the main conversation

161* **Omitted**: If not specified, uses the default model configured for subagents (`sonnet`)216* **Omitted**: If not specified, defaults to `inherit` (uses the same model as the main conversation)

217

218### Control subagent capabilities

219

220You can control what subagents can do through tool access, permission modes, and conditional rules.

221

222#### Available tools

223

224Subagents can use any of Claude Code's [internal tools](/en/settings#tools-available-to-claude). By default, subagents inherit all tools from the main conversation, including MCP tools.

225

226To restrict tools, use the `tools` field (allowlist) or `disallowedTools` field (denylist):

227

228```yaml theme={null}

229---

230name: safe-researcher

231description: Research agent with restricted capabilities

232tools: Read, Grep, Glob, Bash

233disallowedTools: Write, Edit

234---

235```

236

237#### Permission modes

238

239The `permissionMode` field controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation but can override the mode.

240

241| Mode | Behavior |

242| :------------------ | :----------------------------------------------------------------- |

243| `default` | Standard permission checking with prompts |

244| `acceptEdits` | Auto-accept file edits |

245| `dontAsk` | Auto-deny permission prompts (explicitly allowed tools still work) |

246| `bypassPermissions` | Skip all permission checks |

247| `plan` | Plan mode (read-only exploration) |

248

249<Warning>

250 Use `bypassPermissions` with caution. It skips all permission checks, allowing the subagent to execute any operation without approval.

251</Warning>

252

253If the parent uses `bypassPermissions`, this takes precedence and cannot be overridden.

254

255#### Preload skills into subagents

256

257Use the `skills` field to inject skill content into a subagent's context at startup. This gives the subagent domain knowledge without requiring it to discover and load skills during execution.

258

259```yaml theme={null}

260---

261name: api-developer

262description: Implement API endpoints following team conventions

263skills:

264 - api-conventions

265 - error-handling-patterns

266---

267

268Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

269```

270

271The full content of each skill is injected into the subagent's context, not just made available for invocation. Subagents don't inherit skills from the parent conversation; you must list them explicitly.

162 272

163<Note>273<Note>

164 Using `'inherit'` is particularly useful when you want your subagents to adapt to the model choice of the main conversation, ensuring consistent capabilities and response style throughout your session.274 This is the inverse of [running a skill in a subagent](/en/skills#run-skills-in-a-subagent). With `skills` in a subagent, the subagent controls the system prompt and loads skill content. With `context: fork` in a skill, the skill content is injected into the agent you specify. Both use the same underlying system.

165</Note>275</Note>

166 276

167### Available tools277#### Conditional rules with hooks

168 278

169Subagents can be granted access to any of Claude Code's internal tools. See the [tools documentation](/en/docs/claude-code/settings#tools-available-to-claude) for a complete list of available tools.279For more dynamic control over tool usage, use `PreToolUse` hooks to validate operations before they execute. This is useful when you need to allow some operations of a tool while blocking others.

170 280

171<Tip>281This example creates a subagent that only allows read-only database queries. The `PreToolUse` hook runs the script specified in `command` before each Bash command executes:

172 **Recommended:** Use the `/agents` command to modify tool access - it provides an interactive interface that lists all available tools, including any connected MCP server tools, making it easier to select the ones you need.282

173</Tip>283```yaml theme={null}

284---

285name: db-reader

286description: Execute read-only database queries

287tools: Bash

288hooks:

289 PreToolUse:

290 - matcher: "Bash"

291 hooks:

292 - type: command

293 command: "./scripts/validate-readonly-query.sh"

294---

295```

174 296

175You have two options for configuring tools:297Claude Code [passes hook input as JSON](/en/hooks#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the Bash command, and [exits with code 2](/en/hooks#exit-code-2-behavior) to block write operations:

176 298

177* **Omit the `tools` field** to inherit all tools from the main thread (default), including MCP tools299```bash theme={null}

178* **Specify individual tools** as a comma-separated list for more granular control (can be edited manually or via `/agents`)300#!/bin/bash

301# ./scripts/validate-readonly-query.sh

302

303INPUT=$(cat)

304COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

179 305

180**MCP Tools**: Subagents can access MCP tools from configured MCP servers. When the `tools` field is omitted, subagents inherit all MCP tools available to the main thread.306# Block SQL write operations (case-insensitive)

308 echo "Blocked: Only SELECT queries are allowed" >&2

309 exit 2

310fi

181 311

182## Managing subagents312exit 0

313```

183 314

184### Using the /agents command (Recommended)315See [Hook input](/en/hooks#pretooluse-input) for the complete input schema and [exit codes](/en/hooks#simple-exit-code) for how exit codes affect behavior.

185 316

186The `/agents` command provides a comprehensive interface for subagent management:317#### Disable specific subagents

187 318

319You can prevent Claude from using specific subagents by adding them to the `deny` array in your [settings](/en/settings#permission-settings). Use the format `Task(subagent-name)` where `subagent-name` matches the subagent's name field.

320

321```json theme={null}

322{

323 "permissions": {

324 "deny": ["Task(Explore)", "Task(my-custom-agent)"]

325 }

326}

188```327```

189/agents328

329This works for both built-in and custom subagents. You can also use the `--disallowedTools` CLI flag:

330

331```bash theme={null}

332claude --disallowedTools "Task(Explore)"

190```333```

191 334

192This opens an interactive menu where you can:335See [IAM documentation](/en/iam#tool-specific-permission-rules) for more details on permission rules.

193 336

194* View all available subagents (built-in, user, and project)337### Define hooks for subagents

195* Create new subagents with guided setup

196* Edit existing custom subagents, including their tool access

197* Delete custom subagents

198* See which subagents are active when duplicates exist

199* **Easily manage tool permissions** with a complete list of available tools

200 338

201### Direct file management339Subagents can define [hooks](/en/hooks) that run during the subagent's lifecycle. There are two ways to configure hooks:

202 340

203You can also manage subagents by working directly with their files:3411. **In the subagent's frontmatter**: Define hooks that run only while that subagent is active

3422. **In `settings.json`**: Define hooks that run in the main session when subagents start or stop

204 343

205```bash theme={null}344#### Hooks in subagent frontmatter

206# Create a project subagent345

207mkdir -p .claude/agents346Define hooks directly in the subagent's markdown file. These hooks only run while that specific subagent is active and are cleaned up when it finishes.

208echo '---347

209name: test-runner348| Event | Matcher input | When it fires |

210description: Use proactively to run tests and fix failures349| :------------ | :------------ | :------------------------------ |

350| `PreToolUse` | Tool name | Before the subagent uses a tool |

351| `PostToolUse` | Tool name | After the subagent uses a tool |

352| `Stop` | (none) | When the subagent finishes |

353

354This example validates Bash commands with the `PreToolUse` hook and runs a linter after file edits with `PostToolUse`:

355

356```yaml theme={null}

211---357---

358name: code-reviewer

359description: Review code changes with automatic linting

360hooks:

361 PreToolUse:

362 - matcher: "Bash"

363 hooks:

364 - type: command

365 command: "./scripts/validate-command.sh $TOOL_INPUT"

366 PostToolUse:

367 - matcher: "Edit|Write"

368 hooks:

369 - type: command

370 command: "./scripts/run-linter.sh"

371---

372```

373

374`Stop` hooks in frontmatter are automatically converted to `SubagentStop` events.

375

376#### Project-level hooks for subagent events

212 377

213You are a test automation expert. When you see code changes, proactively run the appropriate tests. If tests fail, analyze the failures and fix them while preserving the original test intent.' > .claude/agents/test-runner.md378Configure hooks in `settings.json` that respond to subagent lifecycle events in the main session. Use the `matcher` field to target specific agent types by name.

214 379

215# Create a user subagent380| Event | Matcher input | When it fires |

216mkdir -p ~/.claude/agents381| :-------------- | :-------------- | :------------------------------- |

217# ... create subagent file382| `SubagentStart` | Agent type name | When a subagent begins execution |

383| `SubagentStop` | Agent type name | When a subagent completes |

384

385This example runs setup and cleanup scripts only when the `db-agent` subagent starts and stops:

386

387```json theme={null}

388{

389 "hooks": {

390 "SubagentStart": [

391 {

392 "matcher": "db-agent",

393 "hooks": [

394 { "type": "command", "command": "./scripts/setup-db-connection.sh" }

395 ]

396 }

397 ],

398 "SubagentStop": [

399 {

400 "matcher": "db-agent",

401 "hooks": [

402 { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }

403 ]

404 }

405 ]

406 }

407}

218```408```

219 409

220## Using subagents effectively410See [Hooks](/en/hooks) for the complete hook configuration format.

221 411

222### Automatic delegation412## Work with subagents

223 413

224Claude Code proactively delegates tasks based on:414### Understand automatic delegation

225 415

226* The task description in your request416Claude automatically delegates tasks based on the task description in your request, the `description` field in subagent configurations, and current context. To encourage proactive delegation, include phrases like "use proactively" in your subagent's description field.

227* The `description` field in subagent configurations

228* Current context and available tools

229 417

230<Tip>418You can also request a specific subagent explicitly:

231 To encourage more proactive subagent use, include phrases like "use PROACTIVELY" or "MUST BE USED" in your `description` field.419

232</Tip>420```

421Use the test-runner subagent to fix failing tests

422Have the code-reviewer subagent look at my recent changes

423```

424

425### Run subagents in foreground or background

426

427Subagents can run in the foreground (blocking) or background (concurrent):

428

429* **Foreground subagents** block the main conversation until complete. Permission prompts and clarifying questions (like [`AskUserQuestion`](/en/settings#tools-available-to-claude)) are passed through to you.

430* **Background subagents** run concurrently while you continue working. They inherit the parent's permissions and auto-deny anything not pre-approved. If a background subagent needs a permission it doesn't have or needs to ask clarifying questions, that tool call fails but the subagent continues. MCP tools are not available in background subagents.

431

432If a background subagent fails due to missing permissions, you can [resume it](#resume-subagents) in the foreground to retry with interactive prompts.

433

434Claude decides whether to run subagents in the foreground or background based on the task. You can also:

435

436* Ask Claude to "run this in the background"

437* Press **Ctrl+B** to background a running task

438

439To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/en/settings#environment-variables).

440

441### Common patterns

442

443#### Isolate high-volume operations

444

445One of the most effective uses for subagents is isolating operations that produce large amounts of output. Running tests, fetching documentation, or processing log files can consume significant context. By delegating these to a subagent, the verbose output stays in the subagent's context while only the relevant summary returns to your main conversation.

446

447```

448Use a subagent to run the test suite and report only the failing tests with their error messages

449```

450

451#### Run parallel research

452

453For independent investigations, spawn multiple subagents to work simultaneously:

454

455```

456Research the authentication, database, and API modules in parallel using separate subagents

457```

458

459Each subagent explores its area independently, then Claude synthesizes the findings. This works best when the research paths don't depend on each other.

460

461<Warning>

462 When subagents complete, their results return to your main conversation. Running many subagents that each return detailed results can consume significant context.

463</Warning>

464

465#### Chain subagents

466

467For multi-step workflows, ask Claude to use subagents in sequence. Each subagent completes its task and returns results to Claude, which then passes relevant context to the next subagent.

468

469```

470Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

471```

472

473### Choose between subagents and main conversation

474

475Use the **main conversation** when:

476

477* The task needs frequent back-and-forth or iterative refinement

478* Multiple phases share significant context (planning → implementation → testing)

479* You're making a quick, targeted change

480* Latency matters. Subagents start fresh and may need time to gather context

481

482Use **subagents** when:

483

484* The task produces verbose output you don't need in your main context

485* You want to enforce specific tool restrictions or permissions

486* The work is self-contained and can return a summary

233 487

234### Explicit invocation488Consider [Skills](/en/skills) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.

235 489

236Request a specific subagent by mentioning it in your command:490<Note>

491 Subagents cannot spawn other subagents. If your workflow requires nested delegation, use [Skills](/en/skills) or [chain subagents](#chain-subagents) from the main conversation.

492</Note>

493

494### Manage subagent context

495

496#### Resume subagents

497

498Each subagent invocation creates a new instance with fresh context. To continue an existing subagent's work instead of starting over, ask Claude to resume it.

499

500Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh.

501

502When a subagent completes, Claude receives its agent ID. To resume a subagent, ask Claude to continue the previous work:

237 503

238```504```

239> Use the test-runner subagent to fix failing tests505Use the code-reviewer subagent to review the authentication module

240> Have the code-reviewer subagent look at my recent changes506[Agent completes]

241> Ask the debugger subagent to investigate this error507

508Continue that code review and now analyze the authorization logic

509[Claude resumes the subagent with full context from previous conversation]

510```

511

512You can also ask Claude for the agent ID if you want to reference it explicitly, or find IDs in the transcript files at `~/.claude/projects/{project}/{sessionId}/subagents/`. Each transcript is stored as `agent-{agentId}.jsonl`.

513

514Subagent transcripts persist independently of the main conversation:

515

516* **Main conversation compaction**: When the main conversation compacts, subagent transcripts are unaffected. They're stored in separate files.

517* **Session persistence**: Subagent transcripts persist within their session. You can [resume a subagent](#resume-subagents) after restarting Claude Code by resuming the same session.

518* **Automatic cleanup**: Transcripts are cleaned up based on the `cleanupPeriodDays` setting (default: 30 days).

519

520#### Auto-compaction

521

522Subagents support automatic compaction using the same logic as the main conversation. By default, auto-compaction triggers at approximately 95% capacity. To trigger compaction earlier, set `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` to a lower percentage (for example, `50`). See [environment variables](/en/settings#environment-variables) for details.

523

524Compaction events are logged in subagent transcript files:

525

526```json theme={null}

527{

528 "type": "system",

529 "subtype": "compact_boundary",

530 "compactMetadata": {

531 "trigger": "auto",

532 "preTokens": 167189

533 }

534}

242```535```

243 536

537The `preTokens` value shows how many tokens were used before compaction occurred.

538

244## Example subagents539## Example subagents

245 540

541These examples demonstrate effective patterns for building subagents. Use them as starting points, or generate a customized version with Claude.

542

543<Tip>

544 **Best practices:**

545

546 * **Design focused subagents:** each subagent should excel at one specific task

547 * **Write detailed descriptions:** Claude uses the description to decide when to delegate

548 * **Limit tool access:** grant only necessary permissions for security and focus

549 * **Check into version control:** share project subagents with your team

550</Tip>

551

246### Code reviewer552### Code reviewer

247 553

554A read-only subagent that reviews code without modifying it. This example shows how to design a focused subagent with limited tool access (no Edit or Write) and a detailed prompt that specifies exactly what to look for and how to format output.

555

248```markdown theme={null}556```markdown theme={null}

249---557---

250name: code-reviewer558name: code-reviewer

2613. Begin review immediately5693. Begin review immediately

262 570

263Review checklist:571Review checklist:

264- Code is simple and readable572- Code is clear and readable

265- Functions and variables are well-named573- Functions and variables are well-named

266- No duplicated code574- No duplicated code

267- Proper error handling575- Proper error handling

280 588

281### Debugger589### Debugger

282 590

591A subagent that can both analyze and fix issues. Unlike the code reviewer, this one includes Edit because fixing bugs requires modifying code. The prompt provides a clear workflow from diagnosis to verification.

592

283```markdown theme={null}593```markdown theme={null}

284---594---

285name: debugger595name: debugger

310- Testing approach620- Testing approach

311- Prevention recommendations621- Prevention recommendations

312 622

313Focus on fixing the underlying issue, not just symptoms.623Focus on fixing the underlying issue, not the symptoms.

314```624```

315 625

316### Data scientist626### Data scientist

317 627

628A domain-specific subagent for data analysis work. This example shows how to create subagents for specialized workflows outside of typical coding tasks. It explicitly sets `model: sonnet` for more capable analysis.

629

318```markdown theme={null}630```markdown theme={null}

319---631---

320name: data-scientist632name: data-scientist

348Always ensure queries are efficient and cost-effective.660Always ensure queries are efficient and cost-effective.

349```661```

350 662

351## Best practices663### Database query validator

664

665A subagent that allows Bash access but validates commands to permit only read-only SQL queries. This example shows how to use `PreToolUse` hooks for conditional validation when you need finer control than the `tools` field provides.

666

667```markdown theme={null}

668---

669name: db-reader

670description: Execute read-only database queries. Use when analyzing data or generating reports.

671tools: Bash

672hooks:

673 PreToolUse:

674 - matcher: "Bash"

675 hooks:

676 - type: command

677 command: "./scripts/validate-readonly-query.sh"

678---

679

680You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

352 681

353* **Start with Claude-generated agents**: We highly recommend generating your initial subagent with Claude and then iterating on it to make it personally yours. This approach gives you the best results - a solid foundation that you can customize to your specific needs.682When asked to analyze data:

6831. Identify which tables contain the relevant data

6842. Write efficient SELECT queries with appropriate filters

6853. Present results clearly with context

354 686

355* **Design focused subagents**: Create subagents with single, clear responsibilities rather than trying to make one subagent do everything. This improves performance and makes subagents more predictable.687You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

688```

356 689

357* **Write detailed prompts**: Include specific instructions, examples, and constraints in your system prompts. The more guidance you provide, the better the subagent will perform.690Claude Code [passes hook input as JSON](/en/hooks#pretooluse-input) via stdin to hook commands. The validation script reads this JSON, extracts the command being executed, and checks it against a list of SQL write operations. If a write operation is detected, the script [exits with code 2](/en/hooks#exit-code-2-behavior) to block execution and returns an error message to Claude via stderr.

358 691

359* **Limit tool access**: Only grant tools that are necessary for the subagent's purpose. This improves security and helps the subagent focus on relevant actions.692Create the validation script anywhere in your project. The path must match the `command` field in your hook configuration:

693

694```bash theme={null}

695#!/bin/bash

696# Blocks SQL write operations, allows SELECT queries

360 697

361* **Version control**: Check project subagents into version control so your team can benefit from and improve them collaboratively.698# Read JSON input from stdin

699INPUT=$(cat)

362 700

363## Advanced usage701# Extract the command field from tool_input using jq

702COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

364 703

365### Chaining subagents704if [ -z "$COMMAND" ]; then

705 exit 0

706fi

366 707

367For complex workflows, you can chain multiple subagents:708# Block write operations (case-insensitive)

710 echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2

711 exit 2

712fi

368 713

714exit 0

369```715```

370> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them716

717Make the script executable:

718

719```bash theme={null}

720chmod +x ./scripts/validate-readonly-query.sh

371```721```

372 722

373### Dynamic subagent selection723The hook receives JSON via stdin with the Bash command in `tool_input.command`. Exit code 2 blocks the operation and feeds the error message back to Claude. See [Hooks](/en/hooks#simple-exit-code) for details on exit codes and [Hook input](/en/hooks#pretooluse-input) for the complete input schema.

374 724

375Claude Code intelligently selects subagents based on context. Make your `description` fields specific and action-oriented for best results.725## Next steps

376 726

377## Performance considerations727Now that you understand subagents, explore these related features:

378 728

379* **Context efficiency**: Agents help preserve main context, enabling longer overall sessions729* [Distribute subagents with plugins](/en/plugins) to share subagents across teams or projects

380* **Latency**: Subagents start off with a clean slate each time they are invoked and may add latency as they gather context that they require to do their job effectively.730* [Run Claude Code programmatically](/en/headless) with the Agent SDK for CI/CD and automation

731* [Use MCP servers](/en/mcp) to give subagents access to external tools and data

381 732

382## Related documentation

383 733

384* [Plugins](/en/docs/claude-code/plugins) - Extend Claude Code with custom agents through plugins734---

385* [Slash commands](/en/docs/claude-code/slash-commands) - Learn about other built-in commands735

386* [Settings](/en/docs/claude-code/settings) - Configure Claude Code behavior736> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

387* [Hooks](/en/docs/claude-code/hooks) - Automate workflows with event handlers

terminal-config.md +24 −8

Details

6 6

7Claude cannot control the theme of your terminal. That's handled by your terminal application. You can match Claude Code's theme to your terminal any time via the `/config` command.7Claude cannot control the theme of your terminal. That's handled by your terminal application. You can match Claude Code's theme to your terminal any time via the `/config` command.

8 8

9For additional customization of the Claude Code interface itself, you can configure a [custom status line](/en/docs/claude-code/statusline) to display contextual information like the current model, working directory, or git branch at the bottom of your terminal.9For additional customization of the Claude Code interface itself, you can configure a [custom status line](/en/statusline) to display contextual information like the current model, working directory, or git branch at the bottom of your terminal.

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 newline~~16* **Shift+Enter**: Works out of the box in iTerm2, WezTerm, Ghostty, and Kitty

17* **Keyboard shortcut**: Set up a keybinding to insert a newline in other terminals

17 18

~~18#### Set up Shift+Enter (VS Code or iTerm2):~~19**Set up Shift+Enter for other terminals**

19 20

~~20Run `/terminal-setup` within Claude Code to automatically configure Shift+Enter.~~21Run `/terminal-setup` within Claude Code to automatically configure Shift+Enter for VS Code, Alacritty, Zed, and Warp.

21 22

~~22#### Set up Option+Enter (VS Code, iTerm2 or macOS Terminal.app):~~23<Note>

24 The `/terminal-setup` command is only visible in terminals that require manual configuration. If you're using iTerm2, WezTerm, Ghostty, or Kitty, you won't see this command because Shift+Enter already works natively.

25</Note>

27**Set up Option+Enter (VS Code, iTerm2 or macOS Terminal.app)**

23 28

24**For Mac Terminal.app:**29**For Mac Terminal.app:**

25 30

48 53

49#### Custom notification hooks54#### Custom notification hooks

50 55

~~51For advanced notification handling, you can create [notification hooks](/en/docs/claude-code/hooks#notification) to run your own logic.~~56For advanced notification handling, you can create [notification hooks](/en/hooks#notification) to run your own logic.

52 57

53### Handling large inputs58### Handling large inputs

54 59

65The supported subset includes:70The supported subset includes:

66 71

67* Mode switching: `Esc` (to NORMAL), `i`/`I`, `a`/`A`, `o`/`O` (to INSERT)72* 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`~~73* Navigation: `h`/`j`/`k`/`l`, `w`/`e`/`b`, `0`/`$`/`^`, `gg`/`G`, `f`/`F`/`t`/`T` with `;`/`,` repeat

69* Editing: `x`, `dw`/`de`/`db`/`dd`/`D`, `cw`/`ce`/`cb`/`cc`/`C`, `.` (repeat)74* Editing: `x`, `dw`/`de`/`db`/`dd`/`D`, `cw`/`ce`/`cb`/`cc`/`C`, `.` (repeat)

75* Yank/paste: `yy`/`Y`, `yw`/`ye`/`yb`, `p`/`P`

76* Text objects: `iw`/`aw`, `iW`/`aW`, `i"`/`a"`, `i'`/`a'`, `i(`/`a(`, `i[`/`a[`, `i{`/`a{`

77* Indentation: `>>`/`<<`

78* Line operations: `J` (join lines)

80See [Interactive mode](/en/interactive-mode#vim-editor-mode) for the complete reference.

83---

85> 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 +160 −123

Details

2 2

3> Learn how Claude Code can integrate with various third-party services and infrastructure to meet enterprise deployment requirements.3> Learn how Claude Code can integrate with various third-party services and infrastructure to meet enterprise deployment requirements.

4 4

~~5This page provides an overview of available deployment options and helps you choose the right configuration for your organization.~~5Organizations can deploy Claude Code through Anthropic directly or through a cloud provider. This page helps you choose the right configuration.

6 6

~~7## Provider comparison~~7## Compare deployment options

9For most organizations, Claude for Teams or Claude for Enterprise provides the best experience. Team members get access to both Claude Code and Claude on the web with a single subscription, centralized billing, and no infrastructure setup required.

11**Claude for Teams** is self-service and includes collaboration features, admin tools, and billing management. Best for smaller teams that need to get started quickly.

13**Claude for Enterprise** adds SSO and domain capture, role-based permissions, compliance API access, and managed policy settings for deploying organization-wide Claude Code configurations. Best for larger organizations with security and compliance requirements.

15Learn more about [Team plans](https://support.claude.com/en/articles/9266767-what-is-the-team-plan) and [Enterprise plans](https://support.claude.com/en/articles/9797531-what-is-the-enterprise-plan).

17If your organization has specific infrastructure requirements, compare the options below:

8 18

9<table>19<table>

10 <thead>20 <thead>

11 <tr>21 <tr>

12 <th>Feature</th>22 <th>Feature</th>

~~13 <th>Anthropic</th>~~23 <th>Claude for Teams/Enterprise</th>

24 <th>Anthropic Console</th>

14 <th>Amazon Bedrock</th>25 <th>Amazon Bedrock</th>

15 <th>Google Vertex AI</th>26 <th>Google Vertex AI</th>

27 <th>Microsoft Foundry</th>

16 </tr>28 </tr>

17 </thead>29 </thead>

18 30

19 <tbody>31 <tbody>

32 <tr>

33 <td>Best for</td>

34 <td>Most organizations (recommended)</td>

35 <td>Individual developers</td>

36 <td>AWS-native deployments</td>

37 <td>GCP-native deployments</td>

38 <td>Azure-native deployments</td>

39 </tr>

41 <tr>

42 <td>Billing</td>

43 <td><strong>Teams:</strong> \$150/seat (Premium) with PAYG available<br /><strong>Enterprise:</strong> <a href="https://claude.com/contact-sales">Contact Sales</a></td>

44 <td>PAYG</td>

45 <td>PAYG through AWS</td>

46 <td>PAYG through GCP</td>

47 <td>PAYG through Azure</td>

48 </tr>

20 <tr>50 <tr>

21 <td>Regions</td>51 <td>Regions</td>

22 <td>Supported [countries](https://www.anthropic.com/supported-countries)</td>52 <td>Supported [countries](https://www.anthropic.com/supported-countries)</td>

53 <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>54 <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>55 <td>Multiple GCP [regions](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations)</td>

56 <td>Multiple Azure [regions](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/)</td>

25 </tr>57 </tr>

26 58

27 <tr>59 <tr>

29 <td>Enabled by default</td>61 <td>Enabled by default</td>

30 <td>Enabled by default</td>62 <td>Enabled by default</td>

31 <td>Enabled by default</td>63 <td>Enabled by default</td>

64 <td>Enabled by default</td>

65 <td>Enabled by default</td>

32 </tr>66 </tr>

33 67

34 <tr>68 <tr>

35 <td>Authentication</td>69 <td>Authentication</td>

70 <td>Claude.ai SSO or email</td>

36 <td>API key</td>71 <td>API key</td>

~~37 <td>AWS credentials (IAM)</td>~~72 <td>API key or AWS credentials</td>

~~38 <td>GCP credentials (OAuth/Service Account)</td>~~73 <td>GCP credentials</td>

74 <td>API key or Microsoft Entra ID</td>

39 </tr>75 </tr>

40 76

41 <tr>77 <tr>

42 <td>Cost tracking</td>78 <td>Cost tracking</td>

~~43 <td>Dashboard</td>~~79 <td>Usage dashboard</td>

80 <td>Usage dashboard</td>

44 <td>AWS Cost Explorer</td>81 <td>AWS Cost Explorer</td>

45 <td>GCP Billing</td>82 <td>GCP Billing</td>

83 <td>Azure Cost Management</td>

84 </tr>

86 <tr>

87 <td>Includes Claude on web</td>

88 <td>Yes</td>

89 <td>No</td>

90 <td>No</td>

91 <td>No</td>

92 <td>No</td>

46 </tr>93 </tr>

47 94

48 <tr>95 <tr>

49 <td>Enterprise features</td>96 <td>Enterprise features</td>

~~50 <td>Teams, usage monitoring</td>~~97 <td>Team management, SSO, usage monitoring</td>

98 <td>None</td>

51 <td>IAM policies, CloudTrail</td>99 <td>IAM policies, CloudTrail</td>

52 <td>IAM roles, Cloud Audit Logs</td>100 <td>IAM roles, Cloud Audit Logs</td>

101 <td>RBAC policies, Azure Monitor</td>

53 </tr>102 </tr>

54 </tbody>103 </tbody>

55</table>104</table>

56 105

~~57## Cloud providers~~106Select a deployment option to view setup instructions:

~~59<CardGroup cols={2}>~~

~~60 <Card title="Amazon Bedrock" icon="aws" href="/en/docs/claude-code/amazon-bedrock">~~

~~61 Use Claude models through AWS infrastructure with IAM-based authentication and AWS-native monitoring~~

~~62 </Card>~~

63 107

~~64 <Card title="Google Vertex AI" icon="google" href="/en/docs/claude-code/google-vertex-ai">~~108* [Claude for Teams or Enterprise](/en/iam#claude-for-teams-or-enterprise-recommended)

~~65 Access Claude models via Google Cloud Platform with enterprise-grade security and compliance~~109* [Anthropic Console](/en/iam#claude-console-authentication)

~~66 </Card>~~110* [Amazon Bedrock](/en/amazon-bedrock)

~~67</CardGroup>~~111* [Google Vertex AI](/en/google-vertex-ai)

112* [Microsoft Foundry](/en/microsoft-foundry)

68 113

~~69## Corporate infrastructure~~114## Configure proxies and gateways

70 115

~~71<CardGroup cols={2}>~~116Most organizations can use a cloud provider directly without additional configuration. However, you may need to configure a corporate proxy or LLM gateway if your organization has specific network or management requirements. These are different configurations that can be used together:

~~72 <Card title="Enterprise Network" icon="shield" href="/en/docs/claude-code/network-config">~~

~~73 Configure Claude Code to work with your organization's proxy servers and SSL/TLS requirements~~

~~74 </Card>~~

75 117

~~76 <Card title="LLM Gateway" icon="server" href="/en/docs/claude-code/llm-gateway">~~118* **Corporate proxy**: Routes traffic through an HTTP/HTTPS proxy. Use this if your organization requires all outbound traffic to pass through a proxy server for security monitoring, compliance, or network policy enforcement. Configure with the `HTTPS_PROXY` or `HTTP_PROXY` environment variables. Learn more in [Enterprise network configuration](/en/network-config).

~~77 Deploy centralized model access with usage tracking, budgeting, and audit logging~~119* **LLM Gateway**: A service that sits between Claude Code and the cloud provider to handle authentication and routing. Use this if you need centralized usage tracking across teams, custom rate limiting or budgets, or centralized authentication management. Configure with the `ANTHROPIC_BASE_URL`, `ANTHROPIC_BEDROCK_BASE_URL`, or `ANTHROPIC_VERTEX_BASE_URL` environment variables. Learn more in [LLM gateway configuration](/en/llm-gateway).

~~78 </Card>~~

~~79</CardGroup>~~

80 120

~~81## Configuration overview~~121The following examples show the environment variables to set in your shell or shell profile (`.bashrc`, `.zshrc`). See [Settings](/en/settings) for other configuration methods.

82 122

~~83Claude Code supports flexible configuration options that allow you to combine different providers and infrastructure:~~123### Amazon Bedrock

84 124

~~85<Note>~~125<Tabs>

~~86 Understand the difference between:~~126 <Tab title="Corporate proxy">

127 Route Bedrock traffic through your corporate proxy by setting the following [environment variables](/en/settings#environment-variables):

87 128

~~88 * **Corporate proxy**: An HTTP/HTTPS proxy for routing traffic (set via `HTTPS_PROXY` or `HTTP_PROXY`)~~129 ```bash theme={null}

~~89 * **LLM Gateway**: A service that handles authentication and provides provider-compatible endpoints (set via `ANTHROPIC_BASE_URL`, `ANTHROPIC_BEDROCK_BASE_URL`, or `ANTHROPIC_VERTEX_BASE_URL`)~~130 # Enable Bedrock

131 export CLAUDE_CODE_USE_BEDROCK=1

132 export AWS_REGION=us-east-1

90 133

~~91 Both configurations can be used in tandem.~~134 # Configure corporate proxy

~~92</Note>~~135 export HTTPS_PROXY='https://proxy.example.com:8080'

136 ```

137 </Tab>

93 138

~~94### Using Bedrock with corporate proxy~~139 <Tab title="LLM Gateway">

140 Route Bedrock traffic through your LLM gateway by setting the following [environment variables](/en/settings#environment-variables):

95 141

~~96Route Bedrock traffic through a corporate HTTP/HTTPS proxy:~~142 ```bash theme={null}

143 # Enable Bedrock

144 export CLAUDE_CODE_USE_BEDROCK=1

97 145

~~98```bash theme={null}~~146 # Configure LLM gateway

~~99# Enable Bedrock~~147 export ANTHROPIC_BEDROCK_BASE_URL='https://your-llm-gateway.com/bedrock'

100export CLAUDE_CODE_USE_BEDROCK=1148 export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 # If gateway handles AWS auth

101export AWS_REGION=us-east-1149 ```

150 </Tab>

151</Tabs>

102 152

103# Configure corporate proxy153### Microsoft Foundry

104export HTTPS_PROXY='https://proxy.example.com:8080'

105```

106 154

107### Using Bedrock with LLM Gateway155<Tabs>

156 <Tab title="Corporate proxy">

157 Route Foundry traffic through your corporate proxy by setting the following [environment variables](/en/settings#environment-variables):

108 158

109Use a gateway service that provides Bedrock-compatible endpoints:159 ```bash theme={null}

160 # Enable Microsoft Foundry

161 export CLAUDE_CODE_USE_FOUNDRY=1

162 export ANTHROPIC_FOUNDRY_RESOURCE=your-resource

163 export ANTHROPIC_FOUNDRY_API_KEY=your-api-key # Or omit for Entra ID auth

110 164

111```bash theme={null}165 # Configure corporate proxy

112# Enable Bedrock166 export HTTPS_PROXY='https://proxy.example.com:8080'

113export CLAUDE_CODE_USE_BEDROCK=1167 ```

168 </Tab>

114 169

115# Configure LLM gateway170 <Tab title="LLM Gateway">

116export ANTHROPIC_BEDROCK_BASE_URL='https://your-llm-gateway.com/bedrock'171 Route Foundry traffic through your LLM gateway by setting the following [environment variables](/en/settings#environment-variables):

117export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 # If gateway handles AWS auth

118```

119 172

120### Using Vertex AI with corporate proxy173 ```bash theme={null}

174 # Enable Microsoft Foundry

175 export CLAUDE_CODE_USE_FOUNDRY=1

121 176

122Route Vertex AI traffic through a corporate HTTP/HTTPS proxy:177 # Configure LLM gateway

178 export ANTHROPIC_FOUNDRY_BASE_URL='https://your-llm-gateway.com'

179 export CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1 # If gateway handles Azure auth

180 ```

181 </Tab>

182</Tabs>

123 183

124```bash theme={null}184### Google Vertex AI

125# Enable Vertex

126export CLAUDE_CODE_USE_VERTEX=1

127export CLOUD_ML_REGION=us-east5

128export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

129 185

130# Configure corporate proxy186<Tabs>

131export HTTPS_PROXY='https://proxy.example.com:8080'187 <Tab title="Corporate proxy">

132```188 Route Vertex AI traffic through your corporate proxy by setting the following [environment variables](/en/settings#environment-variables):

133 189

134### Using Vertex AI with LLM Gateway190 ```bash theme={null}

191 # Enable Vertex

192 export CLAUDE_CODE_USE_VERTEX=1

193 export CLOUD_ML_REGION=us-east5

194 export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

135 195

136Combine Google Vertex AI models with an LLM gateway for centralized management:196 # Configure corporate proxy

197 export HTTPS_PROXY='https://proxy.example.com:8080'

198 ```

199 </Tab>

137 200

138```bash theme={null}201 <Tab title="LLM Gateway">

139# Enable Vertex202 Route Vertex AI traffic through your LLM gateway by setting the following [environment variables](/en/settings#environment-variables):

140export CLAUDE_CODE_USE_VERTEX=1

141 203

142# Configure LLM gateway204 ```bash theme={null}

143export ANTHROPIC_VERTEX_BASE_URL='https://your-llm-gateway.com/vertex'205 # Enable Vertex

144export CLAUDE_CODE_SKIP_VERTEX_AUTH=1 # If gateway handles GCP auth206 export CLAUDE_CODE_USE_VERTEX=1

145```

146 207

147### Authentication configuration208 # Configure LLM gateway

209 export ANTHROPIC_VERTEX_BASE_URL='https://your-llm-gateway.com/vertex'

210 export CLAUDE_CODE_SKIP_VERTEX_AUTH=1 # If gateway handles GCP auth

211 ```

212 </Tab>

213</Tabs>

148 214

149Claude Code uses the `ANTHROPIC_AUTH_TOKEN` for the `Authorization` header when needed. The `SKIP_AUTH` flags (`CLAUDE_CODE_SKIP_BEDROCK_AUTH`, `CLAUDE_CODE_SKIP_VERTEX_AUTH`) are used in LLM gateway scenarios where the gateway handles provider authentication.215<Tip>

~~150~~ 216 Use `/status` in Claude Code to verify your proxy and gateway configuration is applied correctly.

151## Choosing the right deployment configuration217</Tip>

~~152~~

153Consider these factors when selecting your deployment approach:

~~154~~

155### Direct provider access

~~156~~

157Best for organizations that:

~~158~~

159* Want the simplest setup

160* Have existing AWS or GCP infrastructure

161* Need provider-native monitoring and compliance

~~162~~

163### Corporate proxy

~~164~~

165Best for organizations that:

~~166~~

167* Have existing corporate proxy requirements

168* Need traffic monitoring and compliance

169* Must route all traffic through specific network paths

~~170~~

171### LLM Gateway

~~172~~

173Best for organizations that:

~~174~~

175* Need usage tracking across teams

176* Want to dynamically switch between models

177* Require custom rate limiting or budgets

178* Need centralized authentication management

~~179~~

180## Debugging

~~181~~

182When debugging your deployment:

~~183~~

184* Use the `claude /status` [slash command](/en/docs/claude-code/slash-commands). This command provides observability into any applied authentication, proxy, and URL settings.

185* Set environment variable `export ANTHROPIC_LOG=debug` to log requests.

186 218

187## Best practices for organizations219## Best practices for organizations

188 220

189### 1. Invest in documentation and memory221### Invest in documentation and memory

190 222

191We strongly recommend investing in documentation so that Claude Code understands your codebase. Organizations can deploy CLAUDE.md files at multiple levels:223We strongly recommend investing in documentation so that Claude Code understands your codebase. Organizations can deploy CLAUDE.md files at multiple levels:

192 224

193* **Organization-wide**: Deploy to system directories like `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS) for company-wide standards225* **Organization-wide**: Deploy to system directories like `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS) for company-wide standards

194* **Repository-level**: Create `CLAUDE.md` files in repository roots containing project architecture, build commands, and contribution guidelines. Check these into source control so all users benefit226* **Repository-level**: Create `CLAUDE.md` files in repository roots containing project architecture, build commands, and contribution guidelines. Check these into source control so all users benefit

195 227

196 [Learn more](/en/docs/claude-code/memory).228Learn more in [Memory and CLAUDE.md files](/en/memory).

197 229

198### 2. Simplify deployment230### Simplify deployment

199 231

200If you have a custom development environment, we find that creating a "one click" way to install Claude Code is key to growing adoption across an organization.232If you have a custom development environment, we find that creating a "one click" way to install Claude Code is key to growing adoption across an organization.

201 233

202### 3. Start with guided usage234### Start with guided usage

203 235

204Encourage new users to try Claude Code for codebase Q\&A, or on smaller bug fixes or feature requests. Ask Claude Code to make a plan. Check Claude's suggestions and give feedback if it's off-track. Over time, as users understand this new paradigm better, then they'll be more effective at letting Claude Code run more agentically.236Encourage new users to try Claude Code for codebase Q\&A, or on smaller bug fixes or feature requests. Ask Claude Code to make a plan. Check Claude's suggestions and give feedback if it's off-track. Over time, as users understand this new paradigm better, then they'll be more effective at letting Claude Code run more agentically.

205 237

206### 4. Configure security policies238### Configure security policies

207 239

208Security teams can configure managed permissions for what Claude Code is and is not allowed to do, which cannot be overwritten by local configuration. [Learn more](/en/docs/claude-code/security).240Security teams can configure managed permissions for what Claude Code is and is not allowed to do, which cannot be overwritten by local configuration. [Learn more](/en/security).

209 241

210### 5. Leverage MCP for integrations242### Leverage MCP for integrations

211 243

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/docs/claude-code/mcp).244MCP 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 245

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!246At 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 247

216## Next steps248## Next steps

217 249

218* [Set up Amazon Bedrock](/en/docs/claude-code/amazon-bedrock) for AWS-native deployment250Once you've chosen a deployment option and configured access for your team:

219* [Configure Google Vertex AI](/en/docs/claude-code/google-vertex-ai) for GCP deployment251

220* [Configure Enterprise Network](/en/docs/claude-code/network-config) for network requirements2521. **Roll out to your team**: Share installation instructions and have team members [install Claude Code](/en/setup) and authenticate with their credentials.

221* [Deploy LLM Gateway](/en/docs/claude-code/llm-gateway) for enterprise management2532. **Set up shared configuration**: Create a [CLAUDE.md file](/en/memory) in your repositories to help Claude Code understand your codebase and coding standards.

222* [Settings](/en/docs/claude-code/settings) for configuration options and environment variables2543. **Configure permissions**: Review [security settings](/en/security) to define what Claude Code can and cannot do in your environment.

255

256

257---

258

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

troubleshooting.md +104 −35

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

136### Repeated permission prompts143### Repeated permission prompts

137 144

138If you find yourself repeatedly approving the same commands, you can allow specific tools145If you find yourself repeatedly approving the same commands, you can allow specific tools

139to run without approval using the `/permissions` command. See [Permissions docs](/en/docs/claude-code/iam#configuring-permissions).146to run without approval using the `/permissions` command. See [Permissions docs](/en/iam#configuring-permissions).

140 147

141### Authentication issues148### Authentication issues

142 149

1462. Close Claude Code1532. Close Claude Code

1473. Restart with `claude` and complete the authentication process again1543. Restart with `claude` and complete the authentication process again

148 155

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

157

149If problems persist, try:158If problems persist, try:

150 159

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

155 164

156This removes your stored authentication information and forces a clean login.165This removes your stored authentication information and forces a clean login.

157 166

167## Configuration file locations

168

169Claude Code stores configuration in several locations:

170

171| File | Purpose |

172| :---------------------------- | :------------------------------------------------------- |

173| `~/.claude/settings.json` | User settings (permissions, hooks, model overrides) |

174| `.claude/settings.json` | Project settings (checked into source control) |

175| `.claude/settings.local.json` | Local project settings (not committed) |

176| `~/.claude.json` | Global state (theme, OAuth, MCP servers, allowed tools) |

177| `.mcp.json` | Project MCP servers (checked into source control) |

178| `managed-settings.json` | [Managed settings](/en/settings#settings-files) |

179| `managed-mcp.json` | [Managed MCP servers](/en/mcp#managed-mcp-configuration) |

180

181On Windows, `~` refers to your user home directory, such as `C:\Users\YourName`.

182

183**Managed file locations:**

184

185* macOS: `/Library/Application Support/ClaudeCode/`

186* Linux/WSL: `/etc/claude-code/`

187* Windows: `C:\Program Files\ClaudeCode\`

188

189For details on configuring these files, see [Settings](/en/settings) and [MCP](/en/mcp).

190

191### Resetting configuration

192

193To reset Claude Code to default settings, you can remove the configuration files:

194

195```bash theme={null}

196# Reset all user settings and state

197rm ~/.claude.json

198rm -rf ~/.claude/

199

200# Reset project-specific settings

201rm -rf .claude/

202rm .mcp.json

203```

204

205<Warning>

206 This will remove all your settings, allowed tools, MCP server configurations, and session history.

207</Warning>

208

158## Performance and stability209## Performance and stability

159 210

160### High CPU or memory usage211### High CPU or memory usage

174 225

175### Search and discovery issues226### Search and discovery issues

176 227

177If Search tool, `@file` mentions, custom agents, and custom slash commands aren't working, install system `ripgrep`:228If Search tool, `@file` mentions, custom agents, and custom skills aren't working, install system `ripgrep`:

178 229

179```bash theme={null}230```bash theme={null}

180# macOS (Homebrew) 231# macOS (Homebrew)

193pacman -S ripgrep244pacman -S ripgrep

194```245```

195 246

196Then set `USE_BUILTIN_RIPGREP=0` in your [environment](/en/docs/claude-code/settings#environment-variables).247Then set `USE_BUILTIN_RIPGREP=0` in your [environment](/en/settings#environment-variables).

197 248

198### Slow or incomplete search results on WSL249### Slow or incomplete search results on WSL

199 250

252 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.303 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.

253</Note>304</Note>

254 305

255For additional JetBrains configuration tips, see our [IDE integration guide](/en/docs/claude-code/ide-integrations#jetbrains-plugin-settings).306For additional JetBrains configuration tips, see our [JetBrains IDE guide](/en/jetbrains#plugin-settings).

256 307

257### Reporting Windows IDE integration issues (both native and WSL)308### Reporting Windows IDE integration issues (both native and WSL)

258 309

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)310If you're experiencing IDE integration problems on Windows, [create an issue](https://github.com/anthropics/claude-code/issues) with the following information:

260 311

261### ESC key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals312* Environment type: native Windows (Git Bash) or WSL1/WSL2

313* WSL networking mode (if applicable): NAT or mirrored

314* IDE name and version

315* Claude Code extension/plugin version

316* Shell type: Bash, Zsh, PowerShell, etc.

262 317

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.318### Escape key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals

319

320If 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 321

265To fix this issue:322To fix this issue:

266 323

270 * Click "Configure terminal keybindings" and delete the "Switch focus to Editor" shortcut327 * Click "Configure terminal keybindings" and delete the "Switch focus to Editor" shortcut

2713. Apply the changes3283. Apply the changes

272 329

273This allows the ESC key to properly interrupt Claude Code operations.330This allows the `Esc` key to properly interrupt Claude Code operations.

274 331

275## Markdown formatting issues332## Markdown formatting issues

276 333

300 357

301**Solutions:**358**Solutions:**

302 359

3031. **Ask Claude to add language tags**: Simply request "Please add appropriate language tags to all code blocks in this markdown file."3601. **Ask Claude to add language tags**: Request "Add appropriate language tags to all code blocks in this markdown file."

304 361

3052. **Use post-processing hooks**: Set up automatic formatting hooks to detect and add missing language tags. See the [markdown formatting hook example](/en/docs/claude-code/hooks-guide#markdown-formatting-hook) for implementation details.3622. **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 363

3073. **Manual verification**: After generating markdown files, review them for proper code block formatting and request corrections if needed.3643. **Manual verification**: After generating markdown files, review them for proper code block formatting and request corrections if needed.

308 365

316 373

3172. **Use formatting tools**: Set up hooks to run markdown formatters like `prettier` or custom formatting scripts on generated markdown files.3742. **Use formatting tools**: Set up hooks to run markdown formatters like `prettier` or custom formatting scripts on generated markdown files.

318 375

3193. **Specify formatting preferences**: Include formatting requirements in your prompts or project [memory](/en/docs/claude-code/memory) files.3763. **Specify formatting preferences**: Include formatting requirements in your prompts or project [memory](/en/memory) files.

320 377

321### Best practices for markdown generation378### Best practices for markdown generation

322 379

323To minimize formatting issues:380To minimize formatting issues:

324 381

325* **Be explicit in requests**: Ask for "properly formatted markdown with language-tagged code blocks"382* **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/docs/claude-code/memory)383* **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 issues384* **Set up validation hooks**: Use post-processing hooks to automatically verify and fix common formatting issues

328 385

329## Getting more help386## Getting more help

332 389

3331. Use the `/bug` command within Claude Code to report problems directly to Anthropic3901. Use the `/bug` command within Claude Code to report problems directly to Anthropic

3342. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues3912. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues

3353. Run `/doctor` to check the health of your Claude Code installation3923. Run `/doctor` to diagnose issues. It checks:

393 * Installation type, version, and search functionality

394 * Auto-update status and available versions

395 * Invalid settings files (malformed JSON, incorrect types)

396 * MCP server configuration errors

397 * Keybinding configuration problems

398 * Context usage warnings (large CLAUDE.md files, high MCP token usage, unreachable permission rules)

399 * Plugin and agent loading errors

3364. Ask Claude directly about its capabilities and features - Claude has built-in access to its documentation4004. Ask Claude directly about its capabilities and features - Claude has built-in access to its documentation

401

402

403---

404

405> 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 +301 −82

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/anthropic-claude-docs/Xfpgr-ckk38MZnw3/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=Xfpgr-ckk38MZnw3&q=85&s=600835067c8b03557a0529978e3f0261" 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/anthropic-claude-docs/Xfpgr-ckk38MZnw3/images/vs-code-extension-interface.jpg?w=280&fit=max&auto=format&n=Xfpgr-ckk38MZnw3&q=85&s=c11a25932f84ca58124a368156b476d2 280w, https://mintcdn.com/anthropic-claude-docs/Xfpgr-ckk38MZnw3/images/vs-code-extension-interface.jpg?w=560&fit=max&auto=format&n=Xfpgr-ckk38MZnw3&q=85&s=3642697ed4d8a6c02396c403bf7aae44 560w, https://mintcdn.com/anthropic-claude-docs/Xfpgr-ckk38MZnw3/images/vs-code-extension-interface.jpg?w=840&fit=max&auto=format&n=Xfpgr-ckk38MZnw3&q=85&s=fb3cb16e752060fbeb0f5e8ba775798b 840w, https://mintcdn.com/anthropic-claude-docs/Xfpgr-ckk38MZnw3/images/vs-code-extension-interface.jpg?w=1100&fit=max&auto=format&n=Xfpgr-ckk38MZnw3&q=85&s=1c6073edc8fcfcbc8e237cbf5f25cdc6 1100w, https://mintcdn.com/anthropic-claude-docs/Xfpgr-ckk38MZnw3/images/vs-code-extension-interface.jpg?w=1650&fit=max&auto=format&n=Xfpgr-ckk38MZnw3&q=85&s=152628678fe3301018b79e932706c430 1650w, https://mintcdn.com/anthropic-claude-docs/Xfpgr-ckk38MZnw3/images/vs-code-extension-interface.jpg?w=2500&fit=max&auto=format&n=Xfpgr-ckk38MZnw3&q=85&s=7ac83b2db00366c9a745380571a748ab 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~~16<Tip>

~~16* **Plan mode with editing**: Review and edit Claude's plans before accepting them~~17 The extension includes the CLI (command-line interface), which you can access from VS Code's integrated terminal for advanced features. See [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) for details.

~~17* **Auto-accept edits mode**: Automatically apply Claude's changes as they're made~~18</Tip>

~~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 19

~~25### Requirements~~20## Install the extension

26 21

~~27* VS Code 1.98.0 or higher~~22Click the link for your IDE to install directly:

24* [Install for VS Code](vscode:extension/anthropic.claude-code)

25* [Install for Cursor](cursor:extension/anthropic.claude-code)

28 26

~~29### Installation~~27Or 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**.

30 28

~~31Download and install the extension from the [Visual Studio Code Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code).~~29<Note>If the extension doesn't appear after installation, restart VS Code or run "Developer: Reload Window" from the Command Palette.</Note>

32 30

~~33### How It Works~~31## Get started

34 32

35Once installed, you can start using Claude Code through the VS Code interface:33Once installed, you can start using Claude Code through the VS Code interface:

36 34

~~371. Click the Spark icon in your editor's sidebar to open the Claude Code panel~~35<Steps>

~~382. Prompt Claude Code in the same way you would in the terminal~~36 <Step title="Open the Claude Code panel">

~~393. Watch as Claude analyzes your code and suggests changes~~37 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~~38

~~41 * **Tip**: Drag the sidebar wider to see inline diffs, then click on them to expand for full details~~39 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.

41 <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" />

43 Other ways to open Claude Code:

45 * **Command Palette**: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux), type "Claude Code", and select an option like "Open in New Tab"

46 * **Status Bar**: Click **✱ Claude Code** in the bottom-right corner of the window. This works even when no file is open.

48 You can drag the Claude panel to reposition it anywhere in VS Code. See [Customize your workflow](#customize-your-workflow) for details.

49 </Step>

51 <Step title="Send a prompt">

52 Ask Claude to help with your code or files, whether that's explaining how something works, debugging an issue, or making changes.

54 <Tip>Claude automatically sees your selected text. Press `Option+K` (Mac) / `Alt+K` (Windows/Linux) to also insert an @-mention reference (like `@file.ts#5-10`) into your prompt.</Tip>

56 Here's an example of asking about a particular line in a file:

58 <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" />

59 </Step>

61 <Step title="Review changes">

62 When Claude wants to edit a file, it shows a side-by-side comparison of the original and proposed changes, then asks for permission. You can accept, reject, or tell Claude what to do instead.

64 <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" />

65 </Step>

66</Steps>

68For more ideas on what you can do with Claude Code, see [Common workflows](/en/common-workflows).

70<Tip>

71 The extension includes two built-in tutorials:

73 * **VS Code walkthrough**: Run "Claude Code: Open Walkthrough" from the Command Palette for a guided tour of the basics.

74 * **Interactive checklist**: Click the graduation cap icon in the Claude panel header to work through features like writing code, using Plan mode, and setting up rules.

75</Tip>

77## Use the prompt box

79The prompt box supports several features:

81* **Permission modes**: Click the mode indicator at the bottom of the prompt box to switch modes. In normal mode, Claude asks permission before each action. In Plan mode, Claude describes what it will do and waits for approval before making changes. In auto-accept mode, Claude makes edits without asking. Set the default in VS Code settings under `claudeCode.initialPermissionMode`.

82* **Command menu**: Click `/` or type `/` to open the command menu. Options include attaching files, switching models, toggling extended thinking, and viewing account usage. The Customize section provides access to MCP servers, hooks, memory, permissions, and plugins. Items with a terminal icon open in the integrated terminal.

83* **Context indicator**: The prompt box shows how much of Claude's context window you're using. Claude automatically compacts when needed, or you can run `/compact` manually.

84* **Extended thinking**: Lets Claude spend more time reasoning through complex problems. Toggle it on via the command menu (`/`). See [Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) for details.

85* **Multi-line input**: Press `Shift+Enter` to add a new line without sending.

87### Reference files and folders

89Use @-mentions to give Claude context about specific files or folders. When you type `@` followed by a file or folder name, Claude reads that content and can answer questions about it or make changes to it. Claude Code supports fuzzy matching, so you can type partial names to find what you need:

91```

92> Explain the logic in @auth (fuzzy matches auth.js, AuthService.ts, etc.)

93> What's in @src/components/ (include a trailing slash for folders)

94```

96When you select text in the editor, Claude can see your highlighted code automatically. The prompt box footer shows how many lines are selected. Press `Option+K` (Mac) / `Alt+K` (Windows/Linux) to insert an @-mention with the file path and line numbers (e.g., `@app.ts#5-10`). Click the selection indicator to toggle whether Claude can see your highlighted text - the eye-slash icon means the selection is hidden from Claude.

98You can also hold `Shift` while dragging files into the prompt box to add them as attachments. Click the X on any attachment to remove it from context.

100### Resume past conversations

101

102Click the dropdown at the top of the Claude Code panel to access your conversation history. You can search by keyword or browse by time (Today, Yesterday, Last 7 days, etc.). Click any conversation to resume it with the full message history. For more on resuming sessions, see [Common workflows](/en/common-workflows#resume-previous-conversations).

103

104## Customize your workflow

105

106Once you're up and running, you can reposition the Claude panel, run multiple sessions, or switch to terminal mode.

107

108### Choose where Claude lives

109

110You can drag the Claude panel to reposition it anywhere in VS Code. Grab the panel's tab or title bar and drag it to:

111

112* **Secondary sidebar**: The right side of the window. Keeps Claude visible while you code.

113* **Primary sidebar**: The left sidebar with icons for Explorer, Search, etc.

114* **Editor area**: Opens Claude as a tab alongside your files. Useful for side tasks.

115

116<Tip>

117 Use the sidebar for your main Claude session and open additional tabs for side tasks. Claude remembers your preferred location. Note that the Spark icon only appears in the Activity Bar when the Claude panel is docked to the left. Since Claude defaults to the right side, use the Editor Toolbar icon to open Claude.

118</Tip>

119

120### Run multiple conversations

121

122Use **Open in New Tab** or **Open in New Window** from the Command Palette to start additional conversations. Each conversation maintains its own history and context, allowing you to work on different tasks in parallel.

123

124When using tabs, a small colored dot on the spark icon indicates status: blue means a permission request is pending, orange means Claude finished while the tab was hidden.

125

126### Switch to terminal mode

127

128By 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.

129

130You can also open VS Code settings (`Cmd+,` on Mac or `Ctrl+,` on Windows/Linux), go to Extensions → Claude Code, and check **Use Terminal**.

131

132## VS Code commands and shortcuts

133

134Open 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.

135

136Some shortcuts depend on which panel is "focused" (receiving keyboard input). When your cursor is in a code file, the editor is focused. When your cursor is in Claude's prompt box, Claude is focused. Use `Cmd+Esc` / `Ctrl+Esc` to toggle between them.

137

138<Note>

139 These are VS Code commands for controlling the extension. Not all built-in Claude Code commands are available in the extension. See [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) for details.

140</Note>

141

142| Command | Shortcut | Description |

143| -------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------ |

144| Focus Input | `Cmd+Esc` (Mac) / `Ctrl+Esc` (Windows/Linux) | Toggle focus between editor and Claude |

145| Open in Side Bar | - | Open Claude in the left sidebar |

146| Open in Terminal | - | Open Claude in terminal mode |

147| Open in New Tab | `Cmd+Shift+Esc` (Mac) / `Ctrl+Shift+Esc` (Windows/Linux) | Open a new conversation as an editor tab |

148| Open in New Window | - | Open a new conversation in a separate window |

149| New Conversation | `Cmd+N` (Mac) / `Ctrl+N` (Windows/Linux) | Start a new conversation (requires Claude to be focused) |

150| Insert @-Mention Reference | `Option+K` (Mac) / `Alt+K` (Windows/Linux) | Insert a reference to the current file and selection (requires editor to be focused) |

151| Show Logs | - | View extension debug logs |

152| Logout | - | Sign out of your Anthropic account |

42 153

~~43### Using Third-Party Providers (Vertex and Bedrock)~~154## Configure settings

44 155

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:156The extension has two types of settings:

46 157

~~471. Open VS Code settings~~158* **Extension settings** in VS Code: Control the extension's behavior within VS Code. Open with `Cmd+,` (Mac) or `Ctrl+,` (Windows/Linux), then go to Extensions → Claude Code. You can also type `/` and select **General Config** to open settings.

~~482. Search for "Claude Code: Environment Variables"~~159* **Claude Code settings** in `~/.claude/settings.json`: Shared between the extension and CLI. Use for allowed commands, environment variables, hooks, and MCP servers. See [Settings](/en/settings) for details.

~~493. Add the required environment variables~~

50 160

~~51#### Environment Variables~~161### Extension settings

52 162

~~54| :---------------------------- | :------------------------------------- | :--------------------- | :----------------------------------------------- |~~164| --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------- |

175| `disableLoginPrompt` | `false` | Skip authentication prompts (for third-party provider setups) |

176| `allowDangerouslySkipPermissions` | `false` | Bypass all permission prompts. **Use with extreme caution.** |

177| `claudeProcessWrapper` | - | Executable path used to launch the Claude process |

65 178

~~66For detailed setup instructions and additional configuration options, see:~~179## VS Code extension vs. Claude Code CLI

67 180

~~68* [Claude Code on Amazon Bedrock](/en/docs/claude-code/amazon-bedrock)~~181Claude Code is available as both a VS Code extension (graphical panel) and a CLI (command-line interface in the terminal). Some features are only available in the CLI. If you need a CLI-only feature, run `claude` in VS Code's integrated terminal.

~~69* [Claude Code on Google Vertex AI](/en/docs/claude-code/google-vertex-ai)~~

70 182

~~71### Not Yet Implemented~~183| Feature | CLI | VS Code Extension |

184| ------------------- | --------------------------------------------- | ---------------------------------------- |

185| Commands and skills | [All](/en/interactive-mode#built-in-commands) | Subset (type `/` to see available) |

186| MCP server config | Yes | No (configure via CLI, use in extension) |

187| Checkpoints | Yes | Coming soon |

188| `!` bash shortcut | Yes | No |

189| Tab completion | Yes | No |

72 190

~~73The following features are not yet available in the VS Code extension:~~191### Run CLI in VS Code

74 192

~~75* **Full MCP server configuration**: You need to [configure MCP servers through the CLI](/en/docs/claude-code/mcp) first, then the extension will use them~~193To 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.

~~76* **Subagents configuration**: Configure [subagents through the CLI](/en/docs/claude-code/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 194

~~83We are working on adding these features in future updates.~~195If using an external terminal, run `/ide` inside Claude Code to connect it to VS Code.

84 196

~~85## Security Considerations~~197### Switch between extension and CLI

86 198

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.199The 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.

88 200

~~89When running in VS Code, consider:~~201### Include terminal output in prompts

90 202

~~91* Enabling [VS Code Restricted Mode](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode) for untrusted workspaces~~203Reference terminal output in your prompts using `@terminal:name` where `name` is the terminal's title. This lets Claude see command output, error messages, or logs without copy-pasting.

~~92* Using manual approval mode for edits~~

~~93* Taking extra care to ensure Claude is only used with trusted prompts~~

94 204

~~95## Legacy CLI Integration~~205### Monitor background processes

96 206

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).207When Claude runs long-running commands, the extension shows progress in the status bar. However, visibility for background tasks is limited compared to the CLI. For better visibility, have Claude output the command so you can run it in VS Code's integrated terminal.

98 208

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.209### Connect to external tools with MCP

100 210

101Both the extension and CLI integration work with Visual Studio Code, Cursor, Windsurf, and VSCodium.211MCP (Model Context Protocol) servers give Claude access to external tools, databases, and APIs. Configure them via CLI, then use them in both extension and CLI.

102 212

103## Troubleshooting213To add an MCP server, open the integrated terminal (`` Ctrl+` `` or `` Cmd+` ``) and run:

104 214

105### Extension Not Installing215```bash theme={null}

216claude mcp add --transport http github https://api.githubcopilot.com/mcp/

217```

106 218

107* Ensure you have a compatible version of VS Code (1.85.0 or later)219Once configured, ask Claude to use the tools (e.g., "Review PR #456"). Some servers require authentication: run `claude` in the terminal, then type `/mcp` to authenticate. See the [MCP documentation](/en/mcp) for available servers.

220

221## Work with git

222

223Claude Code integrates with git to help with version control workflows directly in VS Code. Ask Claude to commit changes, create pull requests, or work across branches.

224

225### Create commits and pull requests

226

227Claude can stage changes, write commit messages, and create pull requests based on your work:

228

229```

230> commit my changes with a descriptive message

231> create a pr for this feature

232> summarize the changes I've made to the auth module

233```

234

235When creating pull requests, Claude generates descriptions based on the actual code changes and can add context about testing or implementation decisions.

236

237### Use git worktrees for parallel tasks

238

239Git worktrees allow multiple Claude Code sessions to work on separate branches simultaneously, each with isolated files:

240

241```bash theme={null}

242# Create a worktree for a new feature

243git worktree add ../project-feature-a -b feature-a

244

245# Run Claude Code in each worktree

246cd ../project-feature-a && claude

247```

248

249Each worktree maintains independent file state while sharing git history. This prevents Claude instances from interfering with each other when working on different tasks.

250

251For detailed git workflows including PR reviews and branch management, see [Common workflows](/en/common-workflows#create-pull-requests).

252

253## Use third-party providers

254

255By 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:

256

257<Steps>

258 <Step title="Disable login prompt">

259 Open the [Disable Login Prompt setting](vscode://settings/claudeCode.disableLoginPrompt) and check the box.

260

261 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**.

262 </Step>

263

264 <Step title="Configure your provider">

265 Follow the setup guide for your provider:

266

267 * [Claude Code on Amazon Bedrock](/en/amazon-bedrock)

268 * [Claude Code on Google Vertex AI](/en/google-vertex-ai)

269 * [Claude Code on Microsoft Foundry](/en/microsoft-foundry)

270

271 These guides cover configuring your provider in `~/.claude/settings.json`, which ensures your settings are shared between the VS Code extension and the CLI.

272 </Step>

273</Steps>

274

275## Security and privacy

276

277Your code stays private. Claude Code processes your code to provide assistance but does not use it to train models. For details on data handling and how to opt out of logging, see [Data and privacy](/en/data-usage).

278

279With auto-edit permissions enabled, Claude Code can modify VS Code configuration files (like `settings.json` or `tasks.json`) that VS Code may execute automatically. To reduce risk when working with untrusted code:

280

281* Enable [VS Code Restricted Mode](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode) for untrusted workspaces

282* Use manual approval mode instead of auto-accept for edits

283* Review changes carefully before accepting them

284

285## Fix common issues

286

287### Extension won't install

288

289* Ensure you have a compatible version of VS Code (1.98.0 or later)

108* Check that VS Code has permission to install extensions290* Check that VS Code has permission to install extensions

109* Try installing directly from the marketplace website291* Try installing directly from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code)

292

293### Spark icon not visible

294

295The Spark icon appears in the **Editor Toolbar** (top-right of editor) when you have a file open. If you don't see it:

296

2971. **Open a file**: The icon requires a file to be open. Having just a folder open isn't enough.

2982. **Check VS Code version**: Requires 1.98.0 or higher (Help → About)

2993. **Restart VS Code**: Run "Developer: Reload Window" from the Command Palette

3004. **Disable conflicting extensions**: Temporarily disable other AI extensions (Cline, Continue, etc.)

3015. **Check workspace trust**: The extension doesn't work in Restricted Mode

302

303Alternatively, 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".

304

305### Claude Code never responds

306

307If Claude Code isn't responding to your prompts:

308

3091. **Check your internet connection**: Ensure you have a stable internet connection

3102. **Start a new conversation**: Try starting a fresh conversation to see if the issue persists

3113. **Try the CLI**: Run `claude` from the terminal to see if you get more detailed error messages

312

313If problems persist, [file an issue on GitHub](https://github.com/anthropics/claude-code/issues) with details about the error.

314

315## Uninstall the extension

316

317To uninstall the Claude Code extension:

318

3191. Open the Extensions view (`Cmd+Shift+X` on Mac or `Ctrl+Shift+X` on Windows/Linux)

3202. Search for "Claude Code"

3213. Click **Uninstall**

322

323To also remove extension data and reset all settings:

324

325```bash theme={null}

326rm -rf ~/.vscode/globalStorage/anthropic.claude-code

327```

328

329For additional help, see the [troubleshooting guide](/en/troubleshooting).

330

331## Next steps

332

333Now that you have Claude Code set up in VS Code:

334

335* [Explore common workflows](/en/common-workflows) to get the most out of Claude Code

336* [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.

337* [Configure Claude Code settings](/en/settings) to customize allowed commands, hooks, and more. These settings are shared between the extension and CLI.

110 338

111### Legacy Integration Not Working

112 339

113* Ensure you're running Claude Code from VS Code's integrated terminal340---

114* Ensure the CLI for your IDE variant is installed:

115 * VS Code: `code` command should be available

116 * Cursor: `cursor` command should be available

117 * Windsurf: `windsurf` command should be available

118 * VSCodium: `codium` command should be available

119* If the command isn't installed:

120 1. Open command palette with `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)

121 2. Search for "Shell Command: Install 'code' command in PATH" (or equivalent for your IDE)

122 341

123For additional help, see our [troubleshooting guide](/en/docs/claude-code/troubleshooting).342> 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-10-30 18:02 UTC → 2026-01-21 21:05 UTC