Anthropic - Claude Code Docs Changes

amazon-bedrock.md +35 −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

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{

102export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2110export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

103```111```

104 112

105**For VS Code Extension users**: Configure environment variables in the VS Code extension settings instead of exporting them in your shell. See [Using Third-Party Providers in VS Code](/en/vs-code#using-third-party-providers-vertex-and-bedrock) for detailed instructions. All environment variables shown in this guide should work when configured through the VS Code extension settings.

~~106~~

107When enabling Bedrock for Claude Code, keep the following in mind:113When enabling Bedrock for Claude Code, keep the following in mind:

108 114

109* `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.

121 127

122<Note>128<Note>

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

124</Note>130</Note>

125 131

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

137export DISABLE_PROMPT_CACHING=1143export DISABLE_PROMPT_CACHING=1

138```144```

139 145

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

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

142</Note>

143 147

144### 5. Output token configuration148### 5. Output token configuration

145 149

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

147 151

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

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

153 157

154**Why these values:**158**Why these values:**

155 159

156* **`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.

157 161

158* **`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.

159 163

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

206</Note>210</Note>

207 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

208## Troubleshooting226## Troubleshooting

209 227

210If you encounter region issues:228If you encounter region issues:

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

226* [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)

227* [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 +5 −0

Details

85 85

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

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

90---

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

checkpointing.md +6 −1

Details

61## See also61## See also

62 62

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

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

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

68---

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

chrome.md +220 −0 added

Details

1# Use Claude Code with Chrome (beta)

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

5<Note>

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

7</Note>

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

11## What the integration enables

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

15Key capabilities include:

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

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

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

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

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

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

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

25## Prerequisites

27Before using Claude Code with Chrome, you need:

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

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

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

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

34## How the integration works

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

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

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

42<Note>

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

44</Note>

46## Set up the integration

48<Steps>

49 <Step title="Update Claude Code">

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

52 ```bash theme={null}

53 claude update

54 ```

55 </Step>

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

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

60 ```bash theme={null}

61 claude --chrome

62 ```

63 </Step>

65 <Step title="Verify the connection">

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

67 </Step>

68</Steps>

70You can also enable Chrome integration from within an existing session using the `/chrome` 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 +80 −12

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

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

110

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.

112

113#### Requirements for teleporting

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.

60 116

~~611. Click the "Open in CLI" button~~117| Requirement | Details |

~~622. Paste and run the command in your terminal in a checkout of the repo~~118| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |

~~633. Any existing local changes will be stashed, and the remote session will be loaded~~119| Clean git state | Your working directory must have no uncommitted changes. Teleport prompts you to stash changes if needed. |

~~644. Continue working locally~~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

127 185

128**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.

129 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

130<Note>190<Note>

131 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:

132 192

256* ghcr.io316* ghcr.io

257* mcr.microsoft.com317* mcr.microsoft.com

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

319* public.ecr.aws

259 320

260#### Cloud Platforms321#### Cloud Platforms

261 322

276* dot.net337* dot.net

277* visualstudio.com338* visualstudio.com

278* dev.azure.com339* dev.azure.com

340* \*.amazonaws.com

341* \*.api.aws

279* oracle.com342* oracle.com

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

281* java.com344* java.com

473 536

474## Best practices537## Best practices

475 538

4761. **Use Claude Code hooks**: Configure [sessionStart hooks](/en/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.

4772. **Document requirements**: Clearly specify dependencies and commands in your `CLAUDE.md` file. If you have an `AGENTS.md` file, you can source it in your `CLAUDE.md` using `@AGENTS.md` to maintain a single source of truth.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.

478 541

479## Related resources542## Related resources

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

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

484* [Data usage](/en/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 +60 −31

Details

5## CLI commands5## CLI commands

6 6

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

18 18

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

22 22

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

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

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

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

28| `--disallowedTools` | A list of tools that should be disallowed without prompting the user for permission, in addition to [settings.json files](/en/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |29| `--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"` |

29| `--print`, `-p` | Print response without interactive mode (see [SDK documentation](https://docs.claude.com/en/docs/agent-sdk) for programmatic usage details) | `claude -p "query"` |30| `--append-system-prompt` | Append custom text to the end of the default system prompt (works in both interactive and print modes) | `claude --append-system-prompt "Always use TypeScript"` |

30| `--system-prompt` | Replace the entire system prompt with custom text (works in both interactive and print modes; added in v2.0.14) | `claude --system-prompt "You are a Python expert"` |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"` |

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

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

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

39| `--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` |

52| `--no-chrome` | Disable [Chrome browser integration](/en/chrome) for this session | `claude --no-chrome` |

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

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

45 71

46<Tip>72<Tip>

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

53The `--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:

54 80

~~56| :------------ | :------- | :-------------------------------------------------------------------------------------------------------------- |~~82| :------------ | :------- | :--------------------------------------------------------------------------------------------------------------------- |

57| `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 |

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

~~59| `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 |

60| `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 |

61 87

62Example:88Example:

80 106

81### System prompt flags107### System prompt flags

82 108

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

84 110

~~86| :----------------------- | :--------------------------------- | :------------------ | :------------------------------------------------------------------- |~~112| :---------------------------- | :------------------------------------------ | :------------------ | :------------------------------------------------------------------- |

90 117

91**When to use each:**118**When to use each:**

92 119

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

106 ```133 ```

107 134

108<Note>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.

109 `--system-prompt` and `--system-prompt-file` are mutually exclusive. You cannot use both flags simultaneously.136 ```bash theme={null}

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

138 ```

111 139

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

113 For most use cases, `--append-system-prompt` is recommended as it preserves 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.

114</Tip>

115 141

116For detailed information about print mode (`-p`) including output formats,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.

117streaming, verbose logging, and programmatic usage, see the

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

119 143

120## See also144## See also

121 145

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

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

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

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

125* [Common workflows](/en/common-workflows) - Advanced workflows and patterns149* [Common workflows](/en/common-workflows) - Advanced workflows and patterns

126* [Settings](/en/settings) - Configuration options150* [Settings](/en/settings) - Configuration options

127* [SDK documentation](https://docs.claude.com/en/docs/agent-sdk) - Programmatic usage and integrations151* [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 +211 −208

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

219 219

220***220***

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

288</Tip>

289

290***

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/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?

283 353

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

285 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>

387

286***388***

287 389

288## Work with tests390## Work with tests

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

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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) is disabled by default in Claude Code. You can enable it on-demand by using `Tab` to toggle Thinking on, or by using prompts like "think" or "think hard". You can also enable it permanently by setting the [`MAX_THINKING_TOKENS` environment variable](/en/settings#environment-variables) in your settings.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](https://docs.claude.com/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](https://docs.claude.com/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/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/third-party-integrations#litellm), which is an open-source tool that helps companies [track spend by key](https://docs.litellm.ai/docs/proxy/virtual_keys#tracking-spend). This project is unaffiliated with Anthropic and we have not audited its security.

39 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 +20 −22

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

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/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=4672f138596e864633b4b7c7ae4ae812" alt="Claude Code data flow diagram" data-og-width="1597" width="1597" data-og-height="1285" height="1285" data-path="images/claude-code-data-flow.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?w=280&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=5d9bdaf7ea50fc38dc01bbde7b952835 280w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?w=560&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=525736e5860ac9f262de4b40c9c68a0e 560w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?w=840&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=5262f9d1a1d0cffb0d5944e49b2d72be 840w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?w=1100&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=ec74e6b2f87b667f6d0e2278c20944de 1100w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?w=1650&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=05f11b1d061b6ddbb69969d4e535547a 1650w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/claude-code-data-flow.png?w=2500&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=9b9cce0fb5989bd1d27f143825be73ff 2500w" />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

~~64<Note>~~

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

68When 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: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:

69 63

~~70* **Code storage**: Your repository is cloned to an isolated VM and automatically deleted after session completion~~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)

~~71* **Credentials**: GitHub authentication is handled through a secure proxy; your GitHub credentials never enter the sandbox~~65* **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~~66* **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~~67* **Session data:** Prompts, code changes, and outputs follow the same data policies as local Claude Code usage

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

75 68

76For security details about cloud execution, see [Security](/en/security#cloud-execution-security).69For security details about cloud execution, see [Security](/en/security#cloud-execution-security).

77 70

95 88

96All environment variables can be checked into `settings.json` ([read more](/en/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 +53 −9

Details

8 8

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

10 10

~~11## Features~~11## Installation

12 12

~~13Claude Code on desktop provides:~~13Download the Claude desktop app for your platform:

14 14

~~15* **Parallel local sessions with `git` worktrees**: Run multiple Claude Code sessions simultaneously in the same repository, each with its own isolated `git` worktree~~15<CardGroup cols={2}>

~~16* **Include `.gitignored` files in your worktrees**: Automatically copy gitignored files like `.env` to new worktrees using `.worktreeinclude`~~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* **Launch Claude Code on the web**: Kick off secure cloud sessions directly from the desktop app~~17 Universal build for Intel and Apple Silicon

18 </Card>

18 19

~~19## Installation~~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>

20 24

~~21Download and install the Claude Desktop app from [claude.ai/download](https://claude.ai/download)~~25For Windows ARM64, [download here](https://claude.ai/api/desktop/win32/arm64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs).

22 26

23<Note>27<Note>

~~24 Local sessions are not available on Windows arm64 architectures.~~28 Local sessions are not available on Windows ARM64.

25</Note>29</Note>

26 30

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

27## Using Git worktrees39## Using Git worktrees

28 40

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

53 65

54### Launch Claude Code on the web66### Launch Claude Code on the web

55 67

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

57 69

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

59 71

67 The bundled Claude Code version in Desktop may differ from the latest CLI version. Desktop prioritizes stability while the CLI may have newer features.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.

68</Note>80</Note>

69 81

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

70## Related resources108## Related resources

71 109

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

73* [Claude Desktop support articles](https://support.claude.com/en/collections/16163169-claude-desktop)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)

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

75* [Settings reference](/en/settings)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 +6 −1

Details

8 8

9<Warning>9<Warning>

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

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

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

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

14</Warning>14</Warning>

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

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

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

80---

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

discover-plugins.md +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 +14 −10

Details

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/`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/`

68 68

69<Tip>69<Tip>

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

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

72</Tip>71</Tip>

73 72

74## Upgrading from Beta73## Upgrading from Beta

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

158```157```

159 158

160### Using slash commands159### Using skills

161 160

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

163name: Code Review162name: Code Review

213 212

214### Security considerations213### Security considerations

215 214

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

217 216

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

219 218

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

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

226 225

227Always 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.

228 227

229### Optimizing performance228### Optimizing performance

230 229

267Key features:266Key features:

268 267

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

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

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

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

273 272

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

626 625

628| ------------------- | ----------------------------------------------- | -------- |627| ------------------- | ------------------------------------------------------ | -------- |

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

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

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

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

637\*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\

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

639 638

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

641 640

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

643 642

648Common arguments:647Common arguments:

649 648

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

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

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

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

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

6712. **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.

672 671

673Claude 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 +11 −6

Details

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)

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

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

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:

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/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/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/common-workflows) - Step-by-step guides for common use cases

hooks.md +214 −29

Details

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

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

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

51 55

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

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

54 58

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

142 146

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

144 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

145## Prompt-Based Hooks191## Prompt-Based Hooks

146 192

147In 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.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.

187 233

188```json theme={null}234```json theme={null}

189{235{

190 "decision": "approve" | "block",236 "ok": true | false,

191 "reason": "Explanation for the decision",237 "reason": "Explanation for the decision"

192 "continue": false, // Optional: stops Claude entirely

193 "stopReason": "Message shown to user", // Optional: custom stop message

194 "systemMessage": "Warning or context" // Optional: shown to user

195}238}

196```239```

197 240

198**Response fields:**241**Response fields:**

199 242

200* `decision`: `"approve"` allows the action, `"block"` prevents it243* `ok`: `true` allows the action, `false` prevents it

201* `reason`: Explanation shown to Claude when decision is `"block"`244* `reason`: Required when `ok` is `false`. Explanation shown to Claude

202* `continue`: (Optional) If `false`, stops Claude's execution entirely

203* `stopReason`: (Optional) Message shown when `continue` is false

204* `systemMessage`: (Optional) Additional message shown to the user

205 245

206### Supported hook events246### Supported hook events

207 247

223 "hooks": [263 "hooks": [

224 {264 {

225 "type": "prompt",265 "type": "prompt",

226 "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: {\"decision\": \"approve\" or \"block\", \"reason\": \"your explanation\"}",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.",

227 "timeout": 30267 "timeout": 30

228 }268 }

229 ]269 ]

243 "hooks": [283 "hooks": [

244 {284 {

245 "type": "prompt",285 "type": "prompt",

246 "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: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"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."

247 }287 }

248 ]288 ]

249 }289 }

258| --------------------- | ----------------------- | ------------------------------ |298| --------------------- | ----------------------- | ------------------------------ |

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

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

373 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

374### SessionStart429### SessionStart

375 430

376Runs 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

377currently 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.

378development 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>

379 437

380**Matchers:**438**Matchers:**

381 439

404 462

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

406 464

407When 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:

408 466

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

410#!/bin/bash468#!/bin/bash

452 session_id: string510 session_id: string

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

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

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

456 514

457 // Event-specific fields515 // Event-specific fields

458 hook_event_name: string516 hook_event_name: string

462 520

463### PreToolUse Input521### PreToolUse Input

464 522

465The 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

466 554

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

468{556{

480}568}

481```569```

482 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..."

616}

617```

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

483### PostToolUse Input625### PostToolUse Input

484 626

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

563}705}

564```706```

565 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

566### SessionStart Input723### SessionStart Input

567 724

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

590 747

591## Hook Output748## Hook Output

592 749

593There are two mutually-exclusive 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

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

595and the user.752and the user.

596 753

786| `Setup` | N/A, shows stderr to user only |

631 789

681 839

682Additionally, hooks can modify tool inputs before execution using `updatedInput`:840Additionally, hooks can modify tool inputs before execution using `updatedInput`:

683 841

684* `updatedInput` allows you to modify the tool's input parameters before the tool executes.842* `updatedInput` modifies the tool's input parameters before the tool executes

685* 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.

686 849

687```json theme={null}850```json theme={null}

688{851{

689 "hookSpecificOutput": {852 "hookSpecificOutput": {

690 "hookEventName": "PreToolUse",853 "hookEventName": "PreToolUse",

691 "permissionDecision": "allow"854 "permissionDecision": "allow",

692 "permissionDecisionReason": "My reason here",855 "permissionDecisionReason": "My reason here",

693 "updatedInput": {856 "updatedInput": {

694 "field_to_modify": "new value"857 "field_to_modify": "new value"

695 }858 },

859 "additionalContext": "Current environment: production. Proceed with caution."

696 }860 }

697}861}

698```862```

779```943```

780 944

781<Note>945<Note>

782 The JSON format is not required for simple use cases. To add context, you can946 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

783 just print plain text to stdout with exit code 0. Use JSON when you need to

784 block prompts or want more structured control.947 block prompts or want more structured control.

785</Note>948</Note>

786 949

799}962}

800```963```

801 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

802#### `SessionStart` Decision Control982#### `SessionStart` Decision Control

803 983

804`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.

877<Note>1057<Note>

878 For `UserPromptSubmit` hooks, you can inject context using either method:1058 For `UserPromptSubmit` hooks, you can inject context using either method:

879 1059

880 * **Plain text stdout** with exit code 0: Simplest approach—just print text1060 * **Plain text stdout** with exit code 0: Simplest approach, prints text

881 * **JSON output** with exit code 0: Use `"decision": "block"` to reject prompts,1061 * **JSON output** with exit code 0: Use `"decision": "block"` to reject prompts,

882 or `additionalContext` for structured context injection1062 or `additionalContext` for structured context injection

883 1063

1074* **Output**:1254* **Output**:

1075 * PreToolUse/PermissionRequest/PostToolUse/Stop/SubagentStop: Progress shown in verbose mode (ctrl+o)1255 * PreToolUse/PermissionRequest/PostToolUse/Stop/SubagentStop: Progress shown in verbose mode (ctrl+o)

1076 * Notification/SessionEnd: Logged to debug only (`--debug`)1256 * Notification/SessionEnd: Logged to debug only (`--debug`)

1077 * UserPromptSubmit/SessionStart: stdout added as context for Claude1257 * UserPromptSubmit/SessionStart/Setup: stdout added as context for Claude

1078 1258

1079## Debugging1259## Debugging

1080 1260

1127* Command being executed1307* Command being executed

1128* Success/failure status1308* Success/failure status

1129* 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 +8 −2

Details

47* **Stop**: Runs when Claude Code finishes responding47* **Stop**: Runs when Claude Code finishes responding

48* **SubagentStop**: Runs when subagent tasks complete48* **SubagentStop**: Runs when subagent tasks complete

49* **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

50* **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

51* **SessionEnd**: Runs when Claude Code session ends52* **SessionEnd**: Runs when Claude Code session ends

52 53

64 65

65### Step 1: Open hooks configuration66### Step 1: Open hooks configuration

66 67

~~67Run the `/hooks` [slash command](/en/slash-commands) and select~~68Run the `/hooks` command and select

68the `PreToolUse` hook event.69the `PreToolUse` hook event.

69 70

70`PreToolUse` hooks run before tool calls and can block them while providing71`PreToolUse` hooks run before tool calls and can block them while providing

92directory. This hook will then apply to all projects, not just your current93directory. This hook will then apply to all projects, not just your current

93project.94project.

94 95

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

96 97

97### Step 5: Verify your hook98### Step 5: Verify your hook

98 99

331* For comprehensive security best practices and safety guidelines, see [Security Considerations](/en/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.

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

333 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 +76 −42

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 four 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* Microsoft Foundry~~11* [Amazon Bedrock](/en/amazon-bedrock)

~~12* Google Vertex AI~~12* [Google Vertex AI](/en/google-vertex-ai)

13* [Microsoft Foundry](/en/microsoft-foundry)

13 14

~~14### Claude API authentication~~15### Claude for Teams or Enterprise (recommended)

15 16

~~16**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:**

17 33

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

192. You can add users through either method below:352. You can add users through either method below:

20 * Bulk invite users from within the Console (Console -> Settings -> Members -> Invite)36 * Bulk invite users from within the Console (Console -> Settings -> Members -> Invite)

~~21 * [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)

223. When inviting users, they need one of the following roles:383. When inviting users, they need one of the following roles:

23 * "Claude Code" role means users can only create Claude Code API keys39 * "Claude Code" role means users can only create Claude Code API keys

24 * "Developer" role means users can create any kind of API key40 * "Developer" role means users can create any kind of API key

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

46 62

~~48| :---------------- | :------------------- | :---------------- | :-------------------------------------------- |~~64| :---------------- | :--------------- | :---------------- | :-------------------------------------------- |

~~49| Read-only | File reads, LS, Grep | No | N/A |~~65| Read-only | File reads, Grep | No | N/A |

50| Bash Commands | Shell execution | Yes | Permanently per project directory and command |66| Bash Commands | Shell execution | Yes | Permanently per project directory and command |

51| File Modification | Edit/write files | Yes | Until session end |67| File Modification | Edit/write files | Yes | Until session end |

52 68

54 70

55You 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.

56 72

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

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

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

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

61* **Default mode** controls Claude's permission behavior when encountering new requests.80* **Default mode** controls Claude's permission behavior when encountering new requests.

62 81

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

64 83

~~65A 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>

66 89

67#### Permission modes90#### Permission modes

68 91

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

70 93

71| Mode | Description |94| Mode | Description |

~~72| :------------------ | :--------------------------------------------------------------------------- |~~95| :------------------ | :------------------------------------------------------------------------------------------------------------------------ |

73| `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 |

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

75| `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 |

77 101

78#### Working directories102#### Working directories

80By 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:

81 105

82* **During startup**: Use `--add-dir <path>` CLI argument106* **During startup**: Use `--add-dir <path>` CLI argument

~~83* **During session**: Use `/add-dir` slash command~~107* **During session**: Use `/add-dir` command

84* **Persistent configuration**: Add to `additionalDirectories` in [settings files](/en/settings#settings-files)108* **Persistent configuration**: Add to `additionalDirectories` in [settings files](/en/settings#settings-files)

85 109

86Files 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.

91 115

92**Bash**116**Bash**

93 117

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

119

94* `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`

95* `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`

~~96* `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.

97 127

98<Tip>128<Tip>

99 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`

102<Warning>132<Warning>

103 Important limitations of Bash permission patterns:133 Important limitations of Bash permission patterns:

104 134

105 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

106 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

107 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:

108 * Options before URL: `curl -X GET http://github.com/...` won't match138 * Options before URL: `curl -X GET http://github.com/...` won't match

109 * Different protocol: `curl https://github.com/...` won't match139 * Different protocol: `curl https://github.com/...` won't match

113 143

114 For more reliable URL filtering, consider:144 For more reliable URL filtering, consider:

115 145

116 * 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

117 * Instructing Claude Code about your allowed curl patterns via CLAUDE.md148 * Instructing Claude Code about your allowed curl patterns via CLAUDE.md

118 * 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.

119</Warning>151</Warning>

120 152

121**Read & Edit**153**Read & Edit**

122 154

123`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.

124 156

125Read & 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:

126 158

147**MCP**179**MCP**

148 180

149* `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

150* `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

151 184

152<Warning>185**Task (Subagents)**

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

154 186

155 To approve all tools from an MCP server:187Use `Task(AgentName)` rules to control which [subagents](/en/sub-agents) Claude can use:

156 188

157 * ✅ Use: `mcp__github` (approves ALL GitHub tools)189* `Task(Explore)` Matches the Explore subagent

158 * ❌ Don't use: `mcp__github__*` (wildcards are not supported)190* `Task(Plan)` Matches the Plan subagent

191* `Task(Verify)` Matches the Verify subagent

159 192

160 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:

161 194

162 * ✅ Use: `mcp__github__get_issue`195```json theme={null}

163 * ✅ Use: `mcp__github__list_issues`196{

164</Warning>197 "permissions": {

198 "deny": ["Task(Explore)"]

199 }

200}

201```

165 202

166### Additional permission control with hooks203### Additional permission control with hooks

167 204

168[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.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.

169 206

170### Enterprise managed policy settings207### Managed settings

~~171~~

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

173 208

174System 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.

~~175~~

176* macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`

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

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

~~179~~

180These policy files follow the same format as regular [settings files](/en/settings#settings-files) but cannot be overridden by user or project settings. This ensures consistent security policies across your organization.

181 210

182### Settings precedence211### Settings precedence

183 212

184When 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):

185 214

1861. Enterprise policies2151. Managed settings (`managed-settings.json`)

1872. Command line arguments2162. Command line arguments

1883. Local project settings (`.claude/settings.local.json`)2173. Local project settings (`.claude/settings.local.json`)

1894. Shared project settings (`.claude/settings.json`)2184. Shared project settings (`.claude/settings.json`)

199* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.228* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.

200* **Custom credential scripts**: The [`apiKeyHelper`](/en/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.

201* **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 +117 −12

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](https://docs.claude.com/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/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/slash-commands) - Interactive session commands265* [Skills](/en/skills) - Custom prompts and workflows

166* [Checkpointing](/en/checkpointing) - Rewind Claude's edits and restore previous states266* [Checkpointing](/en/checkpointing) - Rewind Claude's edits and restore previous states

167* [CLI reference](/en/cli-reference) - Command-line flags and options267* [CLI reference](/en/cli-reference) - Command-line flags and options

168* [Settings](/en/settings) - Configuration options268* [Settings](/en/settings) - Configuration options

169* [Memory management](/en/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 +9 −6

Details

20* **Quick launch**: Use `Cmd+Esc` (Mac) or `Ctrl+Esc` (Windows/Linux) to open Claude Code directly from your editor, or click the Claude Code button in the UI20* **Quick launch**: Use `Cmd+Esc` (Mac) or `Ctrl+Esc` (Windows/Linux) to open Claude Code directly from your editor, or click the Claude Code button in the UI

21* **Diff viewing**: Code changes can be displayed directly in the IDE diff viewer instead of the terminal21* **Diff viewing**: Code changes can be displayed directly in the IDE diff viewer instead of the terminal

22* **Selection context**: The current selection/tab in the IDE is automatically shared with Claude Code22* **Selection context**: The current selection/tab in the IDE is automatically shared with Claude Code

~~23* **File reference shortcuts**: Use `Cmd+Option+K` (Mac) or `Alt+Ctrl+K` (Linux/Windows) to insert file references (e.g., @File#L1-99)~~23* **File reference shortcuts**: Use `Cmd+Option+K` (Mac) or `Alt+Ctrl+K` (Linux/Windows) to insert file references (for example, @File#L1-99)

24* **Diagnostic sharing**: Diagnostic errors (lint, syntax, etc.) from the IDE are automatically shared with Claude as you work24* **Diagnostic sharing**: Diagnostic errors (lint, syntax, etc.) from the IDE are automatically shared with Claude as you work

25 25

26## Installation26## Installation

29 29

30Find and install the [Claude Code plugin](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) from the JetBrains marketplace and restart your IDE.30Find and install the [Claude Code plugin](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) from the JetBrains marketplace and restart your IDE.

31 31

~~32### Auto-Installation~~32If you haven't installed Claude Code yet, see [our quickstart guide](/en/quickstart) for installation instructions.

~~34The plugin may also be auto-installed when you run `claude` in the integrated terminal. The IDE must be restarted completely to take effect.~~

35 33

36<Note>34<Note>

~~37 After installing the plugin, you must restart your IDE completely for it to take effect. You may need to restart multiple times.~~35 After installing the plugin, you may need to restart your IDE completely for it to take effect.

38</Note>36</Note>

39 37

40## Usage38## Usage

70 68

71#### General Settings69#### General Settings

72 70

~~73* **Claude command**: Specify a custom command to run Claude (e.g., `claude`, `/usr/local/bin/claude`, or `npx @anthropic/claude`)~~71* **Claude command**: Specify a custom command to run Claude (for example, `claude`, `/usr/local/bin/claude`, or `npx @anthropic/claude`)

74* **Suppress notification for Claude command not found**: Skip notifications about not finding the Claude command72* **Suppress notification for Claude command not found**: Skip notifications about not finding the Claude command

75* **Enable using Option+Enter for multi-line prompts** (macOS only): When enabled, Option+Enter inserts new lines in Claude Code prompts. Disable if experiencing issues with the Option key being captured unexpectedly (requires terminal restart)73* **Enable using Option+Enter for multi-line prompts** (macOS only): When enabled, Option+Enter inserts new lines in Claude Code prompts. Disable if experiencing issues with the Option key being captured unexpectedly (requires terminal restart)

76* **Enable automatic updates**: Automatically check for and install plugin updates (applied on restart)74* **Enable automatic updates**: Automatically check for and install plugin updates (applied on restart)

148* Being aware of which files Claude Code has access to modify146* Being aware of which files Claude Code has access to modify

149 147

150For additional help, see our [troubleshooting guide](/en/troubleshooting).148For additional help, see our [troubleshooting guide](/en/troubleshooting).

149

150

151---

152

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

legal-and-compliance.md +5 −0

Details

34***34***

35 35

39---

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

llm-gateway.md +5 −0

Details

168* [Claude Code settings](/en/settings)168* [Claude Code settings](/en/settings)

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

170* [Third-party integrations overview](/en/third-party-integrations)170* [Third-party integrations overview](/en/third-party-integrations)

171

172

173---

174

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

mcp.md +260 −40

Details

2 2

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

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

6 7

7## What you can do with MCP8## What you can do with MCP

8 9

10 11

11* **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."

12* **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."

~~13* **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."

14* **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"

15* **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."

16 17

76 77

77```bash theme={null}78```bash theme={null}

78# Basic syntax79# Basic syntax

~~79claude mcp add --transport stdio <name> <command> [args...]~~80claude mcp add [options] <name> -- <command> [args...]

80 81

81# Real example: Add Airtable server82# Real example: Add Airtable server

~~82claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=YOUR_KEY \~~83claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \

83 -- npx -y airtable-mcp-server84 -- npx -y airtable-mcp-server

84```85```

85 86

86<Note>87<Note>

~~87 **Understanding the "--" parameter:**~~88 **Important: Option ordering**

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

89 91

90 For example:92 For example:

91 93

92 * `claude mcp add --transport stdio myserver -- npx server` → runs `npx server`94 * `claude mcp add --transport stdio myserver -- npx server` → runs `npx server`

~~93 * `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

94 96

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

96</Note>98</Note>

113/mcp115/mcp

114```116```

115 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

116<Tip>122<Tip>

117 Tips:123 Tips:

118 124

120 * `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)

121 * `project`: Shared with everyone in the project via `.mcp.json` file127 * `project`: Shared with everyone in the project via `.mcp.json` file

122 * `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)

123 * Set environment variables with `--env` flags (e.g., `--env KEY=value`)129 * Set environment variables with `--env` flags (for example, `--env KEY=value`)

124 * 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)

125 * 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`)

126 * 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

127</Tip>133</Tip>

128 134

208 214

209### Local scope215### Local scope

210 216

211Local-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.

212 218

213```bash theme={null}219```bash theme={null}

214# Add a local-scoped server (default)220# Add a local-scoped server (default)

245 251

246### User scope252### User scope

247 253

248User-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.

249 255

250```bash theme={null}256```bash theme={null}

251# Add a user server257# Add a user server

258 264

259* **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

260* **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

261* **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>

262 276

263### Scope hierarchy and precedence277### Scope hierarchy and precedence

264 278

454 * 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

455 * Use the `--scope user` flag to add servers to your user configuration469 * Use the `--scope user` flag to add servers to your user configuration

456 * Imported servers will have the same names as in Claude Desktop470 * Imported servers will have the same names as in Claude Desktop

457 * 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`)

458</Tip>472</Tip>

459 473

460## Use Claude Code as an MCP server474## Use Claude Code as an MCP server

513 527

514 * 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.

515 * 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.

516 * 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.

517</Tip>531</Tip>

518 532

519## MCP output limits and warnings533## MCP output limits and warnings

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

584</Tip>598</Tip>

585 599

586## 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:

607

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:

587 647

588MCP servers can expose prompts that become available as slash commands in Claude Code.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.

589 659

590### Execute MCP prompts660### Execute MCP prompts

591 661

622 * Server and prompt names are normalized (spaces become underscores)692 * Server and prompt names are normalized (spaces become underscores)

623</Tip>693</Tip>

624 694

625## Enterprise MCP configuration695## Managed MCP configuration

626 696

627For organizations that need centralized control over MCP servers, Claude Code supports enterprise-managed MCP configurations. This allows IT administrators to:697For organizations that need centralized control over MCP servers, Claude Code supports two configuration options:

698

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:

628 703

629* **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

630* **Prevent unauthorized MCP servers**: Optionally restrict users from adding their own MCP servers705* **Prevent unauthorized MCP servers**: Restrict users from adding unapproved MCP servers

631* **Disable MCP entirely**: Remove MCP functionality completely if needed706* **Disable MCP entirely**: Remove MCP functionality completely if needed

632 707

633### 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.

634 711

635System administrators can deploy an enterprise MCP configuration file alongside the managed settings file:712System administrators deploy the configuration file to a system-wide directory:

636 713

637* **macOS**: `/Library/Application Support/ClaudeCode/managed-mcp.json`714* macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`

638* **Windows**: `C:\ProgramData\ClaudeCode\managed-mcp.json`715* Linux and WSL: `/etc/claude-code/managed-mcp.json`

639* **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>

640 721

641The `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:

642 723

663}744}

664```745```

665 746

666### Restricting MCP servers with allowlists and denylists747### Option 2: Policy-based control with allowlists and denylists

667 748

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

669 750

670* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`751<Note>

671* **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.

672* **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

673 766

674```json theme={null}767```json theme={null}

675{768{

676 "allowedMcpServers": [769 "allowedMcpServers": [

770 // Allow by server name

677 { "serverName": "github" },771 { "serverName": "github" },

678 { "serverName": "sentry" },772 { "serverName": "sentry" },

679 { "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/*" }

680 ],781 ],

681 "deniedMcpServers": [782 "deniedMcpServers": [

682 { "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/*" }

683 ]791 ]

684}792}

685```793```

686 794

687**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`)

688 902

689* `undefined` (default): No restrictions - users can configure any MCP server903* `undefined` (default): No restrictions - users can configure any MCP server

690* Empty array `[]`: Complete lockdown - users cannot configure any MCP servers904* Empty array `[]`: Complete lockdown - users cannot configure any MCP servers

691* 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

692 906

693**Denylist behavior (`deniedMcpServers`)**:907#### Denylist behavior (`deniedMcpServers`)

694 908

695* `undefined` (default): No servers are blocked909* `undefined` (default): No servers are blocked

696* Empty array `[]`: No servers are blocked910* Empty array `[]`: No servers are blocked

697* List of server names: Specified servers are explicitly blocked across all scopes911* List of entries: Specified servers are explicitly blocked across all scopes

698 912

699**Important notes**:913#### Important notes

700 914

701* 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.

702* **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)

703 918

704<Note>919<Note>

705 **Enterprise configuration precedence**: The enterprise MCP configuration has the highest precedence and cannot be overridden by user, local, or project configurations.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.

706</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 +5 −0

Details

105* [Microsoft Foundry documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-azure-ai-foundry)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)106* [Microsoft Foundry models](https://ai.azure.com/explore/models)

107* [Microsoft Foundry pricing](https://azure.microsoft.com/en-us/pricing/details/ai-foundry/)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 +7 −2

Details

105You can use the following environment variables, which must be full **model105You can use the following environment variables, which must be full **model

106names** (or equivalent for your API provider), 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.

107 107

108| Env var | Description |108| Environment variable | Description |

109| -------------------------------- | --------------------------------------------------------------------------------------------- |109| -------------------------------- | --------------------------------------------------------------------------------------------- |

119 119

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

121 121

122| Env var | Description |122| Environment variable | Description |

123| ------------------------------- | ---------------------------------------------------------------------------------------------- |123| ------------------------------- | ---------------------------------------------------------------------------------------------- |

124| `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) |

128 128

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.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 −69

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## Quick Start~~9## Quick start

10 10

11Configure OpenTelemetry using environment variables:11Configure OpenTelemetry using environment variables:

12 12

39 39

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

41 41

~~42## Administrator Configuration~~42## Administrator configuration

43 43

44Administrators can configure OpenTelemetry settings for all users through the managed settings file. This allows for centralized control of telemetry settings across an organization. See the [settings precedence](/en/settings#settings-precedence) for more information about how settings are applied.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.

~~46The managed settings file is located at:~~

~~48* macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`~~

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

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

51 45

52Example managed settings configuration:46Example managed settings configuration:

53 47

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

69</Note>63</Note>

70 64

~~71## Configuration Details~~65## Configuration details

72 66

~~73### Common Configuration Variables~~67### Common configuration variables

74 68

~~76| ----------------------------------------------- | --------------------------------------------------------- | ------------------------------------ |~~70| ----------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------ |

77| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1` |71| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1` |

89| `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` |

90| `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` |

92 87

~~93### Metrics Cardinality Control~~88### Metrics cardinality control

94 89

95The 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:

96 91

102 97

103These 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.

104 99

105### Dynamic Headers100### Dynamic headers

106 101

107For 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:

108 103

109#### Settings Configuration104#### Settings configuration

110 105

111Add to your `.claude/settings.json`:106Add to your `.claude/settings.json`:

112 107

116}111}

117```112```

118 113

119#### Script Requirements114#### Script requirements

120 115

121The 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:

122 117

126echo "{\"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)\"}"

127```122```

128 123

129#### Important Limitations124#### Refresh behavior

~~130~~

131**Headers are fetched only at startup, not during runtime.** This is due to OpenTelemetry exporter architecture limitations.

132 125

133For scenarios requiring frequent token refresh, use an OpenTelemetry Collector as a proxy that can refresh its own headers.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.

134 127

135### Multi-Team Organization Support128### Multi-team organization support

136 129

137Organizations 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:

138 131

172 export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"165 export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

173 ```166 ```

174 167

175 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`.

176</Warning>169</Warning>

177 170

178### Example Configurations171### Example configurations

179 172

180```bash theme={null}173```bash theme={null}

181# Console debugging (1-second intervals)174# Console debugging (1-second intervals)

220export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317213export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

221```214```

222 215

223## Available Metrics and Events216## Available metrics and events

224 217

225### Standard Attributes218### Standard attributes

226 219

227All metrics and events share these standard attributes:220All metrics and events share these standard attributes:

228 221

230| ------------------- | ------------------------------------------------------------- | --------------------------------------------------- |223| ------------------- | -------------------------------------------------------------------- | --------------------------------------------------- |

236 229

237### Metrics230### Metrics

238 231

250| `claude_code.active_time.total` | Total active time in seconds | s |243| `claude_code.active_time.total` | Total active time in seconds | s |

251 244

252### Metric Details245### Metric details

253 246

254#### Session Counter247#### Session counter

255 248

256Incremented at the start of each session.249Incremented at the start of each session.

257 250

259 252

260* All [standard attributes](#standard-attributes)253* All [standard attributes](#standard-attributes)

261 254

262#### Lines of Code Counter255#### Lines of code counter

263 256

264Incremented when code is added or removed.257Incremented when code is added or removed.

265 258

268* All [standard attributes](#standard-attributes)261* All [standard attributes](#standard-attributes)

269* `type`: (`"added"`, `"removed"`)262* `type`: (`"added"`, `"removed"`)

270 263

271#### Pull Request Counter264#### Pull request counter

272 265

273Incremented when creating pull requests via Claude Code.266Incremented when creating pull requests via Claude Code.

274 267

276 269

277* All [standard attributes](#standard-attributes)270* All [standard attributes](#standard-attributes)

278 271

279#### Commit Counter272#### Commit counter

280 273

281Incremented when creating git commits via Claude Code.274Incremented when creating git commits via Claude Code.

282 275

284 277

285* All [standard attributes](#standard-attributes)278* All [standard attributes](#standard-attributes)

286 279

287#### Cost Counter280#### Cost counter

288 281

289Incremented after each API request.282Incremented after each API request.

290 283

291**Attributes**:284**Attributes**:

292 285

293* All [standard attributes](#standard-attributes)286* All [standard attributes](#standard-attributes)

294* `model`: Model identifier (e.g., "claude-sonnet-4-5-20250929")287* `model`: Model identifier (for example, "claude-sonnet-4-5-20250929")

295 288

296#### Token Counter289#### Token counter

297 290

298Incremented after each API request.291Incremented after each API request.

299 292

301 294

302* All [standard attributes](#standard-attributes)295* All [standard attributes](#standard-attributes)

303* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)296* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)

304* `model`: Model identifier (e.g., "claude-sonnet-4-5-20250929")297* `model`: Model identifier (for example, "claude-sonnet-4-5-20250929")

305 298

306#### Code Edit Tool Decision Counter299#### Code edit tool decision counter

307 300

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

309 302

312* All [standard attributes](#standard-attributes)305* All [standard attributes](#standard-attributes)

313* `tool`: Tool name (`"Edit"`, `"Write"`, `"NotebookEdit"`)306* `tool`: Tool name (`"Edit"`, `"Write"`, `"NotebookEdit"`)

314* `decision`: User decision (`"accept"`, `"reject"`)307* `decision`: User decision (`"accept"`, `"reject"`)

315* `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.

316 309

317#### Active Time Counter310#### Active time counter

318 311

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

320 313

326 319

327Claude 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):

328 321

329#### User Prompt Event322#### User prompt event

330 323

331Logged when a user submits a prompt.324Logged when a user submits a prompt.

332 325

340* `prompt_length`: Length of the prompt333* `prompt_length`: Length of the prompt

341* `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`)

342 335

343#### Tool Result Event336#### Tool result event

344 337

345Logged when a tool completes execution.338Logged when a tool completes execution.

346 339

360* `tool_parameters`: JSON string containing tool-specific parameters (when available)353* `tool_parameters`: JSON string containing tool-specific parameters (when available)

361 * For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `sandbox`354 * For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `sandbox`

362 355

363#### API Request Event356#### API request event

364 357

365Logged for each API request to Claude.358Logged for each API request to Claude.

366 359

371* All [standard attributes](#standard-attributes)364* All [standard attributes](#standard-attributes)

372* `event.name`: `"api_request"`365* `event.name`: `"api_request"`

373* `event.timestamp`: ISO 8601 timestamp366* `event.timestamp`: ISO 8601 timestamp

374* `model`: Model used (e.g., "claude-sonnet-4-5-20250929")367* `model`: Model used (for example, "claude-sonnet-4-5-20250929")

375* `cost_usd`: Estimated cost in USD368* `cost_usd`: Estimated cost in USD

376* `duration_ms`: Request duration in milliseconds369* `duration_ms`: Request duration in milliseconds

377* `input_tokens`: Number of input tokens370* `input_tokens`: Number of input tokens

379* `cache_read_tokens`: Number of tokens read from cache372* `cache_read_tokens`: Number of tokens read from cache

380* `cache_creation_tokens`: Number of tokens used for cache creation373* `cache_creation_tokens`: Number of tokens used for cache creation

381 374

382#### API Error Event375#### API error event

383 376

384Logged when an API request to Claude fails.377Logged when an API request to Claude fails.

385 378

390* All [standard attributes](#standard-attributes)383* All [standard attributes](#standard-attributes)

391* `event.name`: `"api_error"`384* `event.name`: `"api_error"`

392* `event.timestamp`: ISO 8601 timestamp385* `event.timestamp`: ISO 8601 timestamp

393* `model`: Model used (e.g., "claude-sonnet-4-5-20250929")386* `model`: Model used (for example, "claude-sonnet-4-5-20250929")

394* `error`: Error message387* `error`: Error message

395* `status_code`: HTTP status code (if applicable)388* `status_code`: HTTP status code (if applicable)

396* `duration_ms`: Request duration in milliseconds389* `duration_ms`: Request duration in milliseconds

397* `attempt`: Attempt number (for retried requests)390* `attempt`: Attempt number (for retried requests)

398 391

399#### Tool Decision Event392#### Tool decision event

400 393

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

402 395

407* All [standard attributes](#standard-attributes)400* All [standard attributes](#standard-attributes)

408* `event.name`: `"tool_decision"`401* `event.name`: `"tool_decision"`

409* `event.timestamp`: ISO 8601 timestamp402* `event.timestamp`: ISO 8601 timestamp

410* `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")

411* `decision`: Either `"accept"` or `"reject"`404* `decision`: Either `"accept"` or `"reject"`

412* `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"`

413 406

414## Interpreting Metrics and Events Data407## Interpreting metrics and events data

415 408

416The 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:

417 410

418### Usage Monitoring411### Usage monitoring

419 412

420| Metric | Analysis Opportunity |413| Metric | Analysis Opportunity |

421| ------------------------------------------------------------- | --------------------------------------------------------- |414| ------------------------------------------------------------- | --------------------------------------------------------- |

426 419

427### Cost Monitoring420### Cost monitoring

428 421

429The `claude_code.cost.usage` metric helps with:422The `claude_code.cost.usage` metric helps with:

430 423

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

436</Note>429</Note>

437 430

438### Alerting and Segmentation431### Alerting and segmentation

439 432

440Common alerts to consider:433Common alerts to consider:

441 434

445 438

446All 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`.

447 440

448### Event Analysis441### Event analysis

449 442

450The event data provides detailed insights into Claude Code interactions:443The event data provides detailed insights into Claude Code interactions:

451 444

452**Tool Usage Patterns**: Analyze tool result events to identify:445**Tool Usage Patterns**: analyze tool result events to identify:

453 446

454* Most frequently used tools447* Most frequently used tools

455* Tool success rates448* Tool success rates

456* Average tool execution times449* Average tool execution times

457* Error patterns by tool type450* Error patterns by tool type

458 451

459**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.

460 453

461## Backend Considerations454## Backend considerations

462 455

463Your 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:

464 457

465### For Metrics:458### For metrics

466 459

467* **Time series databases (e.g., Prometheus)**: Rate calculations, aggregated metrics460* **Time series databases (for example, Prometheus)**: Rate calculations, aggregated metrics

468* **Columnar stores (e.g., ClickHouse)**: Complex queries, unique user analysis461* **Columnar stores (for example, ClickHouse)**: Complex queries, unique user analysis

469* **Full-featured observability platforms (e.g., Honeycomb, Datadog)**: Advanced querying, visualization, alerting462* **Full-featured observability platforms (for example, Honeycomb, Datadog)**: Advanced querying, visualization, alerting

470 463

471### For Events/Logs:464### For events/logs

472 465

473* **Log aggregation systems (e.g., Elasticsearch, Loki)**: Full-text search, log analysis466* **Log aggregation systems (for example, Elasticsearch, Loki)**: Full-text search, log analysis

474* **Columnar stores (e.g., ClickHouse)**: Structured event analysis467* **Columnar stores (for example, ClickHouse)**: Structured event analysis

475* **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

476 469

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

478 471

479## Service Information472## Service information

480 473

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

482 475

483* `service.name`: `claude-code`476* `service.name`: `claude-code`

484* `service.version`: Current Claude Code version477* `service.version`: Current Claude Code version

485* `os.type`: Operating system type (e.g., `linux`, `darwin`, `windows`)478* `os.type`: Operating system type (for example, `linux`, `darwin`, `windows`)

486* `os.version`: Operating system version string479* `os.version`: Operating system version string

487* `host.arch`: Host architecture (e.g., `amd64`, `arm64`)480* `host.arch`: Host architecture (for example, `amd64`, `arm64`)

488* `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)

489* Meter Name: `com.anthropic.claude_code`482* Meter Name: `com.anthropic.claude_code`

490 483

491## ROI Measurement Resources484## ROI measurement resources

492 485

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

494 487

495## Security/Privacy Considerations488## Security/privacy considerations

496 489

497* Telemetry is opt-in and requires explicit configuration490* Telemetry is opt-in and requires explicit configuration

498* 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

501## Monitoring Claude Code on Amazon Bedrock494## Monitoring Claude Code on Amazon Bedrock

502 495

503For detailed Claude Code usage monitoring guidance for Amazon Bedrock, see [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md).496For detailed Claude Code usage monitoring guidance for Amazon Bedrock, see [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md).

497

498

499---

500

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

network-config.md +5 −0

Details

88* [Claude Code settings](/en/settings)88* [Claude Code settings](/en/settings)

89* [Environment variables reference](/en/settings#environment-variables)89* [Environment variables reference](/en/settings#environment-variables)

90* [Troubleshooting guide](/en/troubleshooting)90* [Troubleshooting guide](/en/troubleshooting)

93---

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

output-styles.md +7 −3

Details

103settings 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

104about when to use the agent.104about when to use the agent.

105 105

106### Output Styles vs. [Custom Slash Commands](/en/slash-commands)106### Output Styles vs. [Skills](/en/skills)

107 107

108You can think of output styles as "stored system prompts" and custom slash108Output 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.

109commands as "stored prompts".109

110

111---

112

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

overview.md +44 −19

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/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/setup) for installation options or [troubleshooting](/en/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/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/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

92## Additional resources108## Additional resources

93 109

94<CardGroup>110<CardGroup>

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

95 <Card title="Build with the Agent SDK" icon="code-branch" href="https://docs.claude.com/en/docs/agent-sdk/overview">115 <Card title="Build with the Agent SDK" icon="code-branch" href="https://docs.claude.com/en/docs/agent-sdk/overview">

96 Create custom AI agents with the Claude Agent SDK116 Create custom AI agents with the Claude Agent SDK

97 </Card>117 </Card>

120 Understand how Claude Code handles your data140 Understand how Claude Code handles your data

121 </Card>141 </Card>

122</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 +324 −188

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>

84 <Step title="Add and install">

85 Add the marketplace and install the plugin.

94 86

~~95When team members trust the repository folder, Claude Code automatically installs these marketplaces and any plugins specified in the `enabledPlugins` field.~~87 ```shell theme={null}

88 /plugin marketplace add ./my-marketplace

89 /plugin install review-plugin@my-plugins

90 ```

91 </Step>

96 92

~~97***~~93 <Step title="Try it out">

94 Select some code in your editor and run your new command.

98 95

~~99## Create your own marketplace~~96 ```shell theme={null}

97 /review

98 ```

99 </Step>

100</Steps>

100 101

101Build and distribute custom plugin collections for your team or community.102To learn more about what plugins can do, including hooks, agents, MCP servers, and LSP servers, see [Plugins](/en/plugins).

102 103

103### Prerequisites for marketplace creation104<Note>

105 **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.

106

107 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>

104 109

105* Git repository (GitHub, GitLab, or other git hosting)110## Create the marketplace file

106* Understanding of JSON file format

107* One or more plugins to distribute

108 111

109### Create the marketplace file112Create `.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/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).

330 362

331### List known marketplaces363### Require marketplaces for your team

332 364

333```shell List all configured marketplaces theme={null}365You can configure your repository so team members are automatically prompted to install your marketplace when they trust the project folder. Add your marketplace to `.claude/settings.json`:

334/plugin marketplace list366

367```json theme={null}

368{

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 |

404

405#### Common configurations

338 406

339### Update marketplace metadata407Disable all marketplace additions:

340 408

341```shell Refresh marketplace metadata theme={null}409```json theme={null}

342/plugin marketplace update marketplace-name410{

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

346 438

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

348 440

349```shell Remove a marketplace theme={null}441The allowlist uses exact matching. For a marketplace to be allowed, all specified fields must match exactly:

350/plugin marketplace remove marketplace-name442

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

445

446Because `strictKnownMarketplaces` is set in [managed settings](/en/settings#settings-files), individual users and project configurations cannot override these restrictions.

447

448For complete configuration details including all supported source types and comparison with `extraKnownMarketplaces`, see the [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces).

449

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

477

478For complete plugin testing workflows, see [Test your plugins locally](/en/plugins#test-your-plugins-locally). For technical troubleshooting, see [Plugins reference](/en/plugins-reference).

364 479

365#### Marketplace not loading480## 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/plugins#test-your-plugins-locally). For technical troubleshooting, see [Plugins reference](/en/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/plugins) - Installing and using plugins560* [Discover and install prebuilt plugins](/en/discover-plugins) - Installing plugins from existing marketplaces

561* [Plugins](/en/plugins) - Creating your own plugins

431* [Plugins reference](/en/plugins-reference) - Complete technical specifications and schemas562* [Plugins reference](/en/plugins-reference) - Complete technical specifications and schemas

432* [Plugin development](/en/plugins#develop-more-complex-plugins) - Creating your own plugins563* [Plugin settings](/en/settings#plugin-settings) - Plugin configuration options

433* [Settings](/en/settings#plugin-configuration) - Plugin configuration options564* [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/plugins-reference). For marketplace management, see [Plugin marketplaces](/en/plugin-marketplaces).~~34 Start with standalone configuration in `.claude/` for quick iteration, then [convert to a plugin](#convert-existing-configurations-to-plugins) when you're ready to share.

7</Tip>35</Tip>

8 36

9Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. Install plugins from [marketplaces](/en/plugin-marketplaces) to add pre-built commands, agents, hooks, Skills, and MCP servers, or create your own to automate your workflows.

11## Quickstart37## Quickstart

12 38

~~13Let's create a simple greeting plugin to get you familiar with the plugin system. We'll build a working plugin that adds a custom command, test it locally, and understand the core concepts.~~39This quickstart walks you through creating a plugin with a custom 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/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/plugin-marketplaces).212Each `SKILL.md` needs frontmatter with `name` and `description` fields, followed by instructions:

~~175~~

176### Install plugins

177 213

178#### Via interactive menu (recommended for discovery)214```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---

179 219

180```shell Open the plugin management interface theme={null}220When reviewing code, check for:

181/plugin2211. Code organization and structure

2222. Error handling

2233. 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/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:

282

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

231 286

232Plugins can include [Agent Skills](/en/skills) to extend Claude's capabilities. Skills are model-invoked—Claude autonomously uses them based on the task context.287### Share your plugins

233 288

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.289When your plugin is ready to share:

235 290

236For complete Skill authoring guidance, see [Agent Skills](/en/skills).2911. **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

237 295

238### Organize complex plugins296Once your plugin is in a marketplace, others can install it using the instructions in [Discover and install plugins](/en/discover-plugins).

239 297

240For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/plugins-reference#plugin-directory-structure).298<Note>

299 For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/plugins-reference).

300</Note>

241 301

242### Test your plugins locally302## Convert existing configurations to plugins

243 303

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.304If you already have skills or hooks in your `.claude/` directory, you can convert them into a plugin for easier sharing and distribution.

305

306### Migration steps

245 307

246<Steps>308<Steps>

247 <Step title="Set up your development structure">309 <Step title="Create the plugin structure">

248 Organize your plugin and marketplace for testing:310 Create a new plugin directory:

249 311

250 ```bash Create directory structure theme={null}312 ```bash theme={null}

251 mkdir dev-marketplace313 mkdir -p my-plugin/.claude-plugin

252 cd dev-marketplace

253 mkdir my-plugin

254 ```314 ```

255 315

256 This creates:316 Create the manifest file at `my-plugin/.claude-plugin/plugin.json`:

257 317

258 ```318 ```json my-plugin/.claude-plugin/plugin.json theme={null}

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

269 <Step title="Create the marketplace manifest">

270 ```bash Create marketplace.json theme={null}

271 mkdir .claude-plugin

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

296 ```shell Add your development marketplace theme={null}

297 /plugin marketplace add ./dev-marketplace

298 ```

299 329

300 ```shell Install your plugin theme={null}330 ```bash theme={null}

301 /plugin install my-plugin@dev-marketplace331 # Copy commands

302 ```332 cp -r .claude/commands my-plugin/

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 364

326<Note>365 <Step title="Test your migrated plugin">

327 **For multiple plugins**: Organize plugins in subdirectories like `./plugins/plugin-name` and update your marketplace.json accordingly. See [Plugin sources](/en/plugin-marketplaces#plugin-sources) for organization patterns.366 Load your plugin to verify everything works:

328</Note>

329 367

330### Debug plugin issues368 ```bash theme={null}

~~331~~ 369 claude --plugin-dir ./my-plugin

332If your plugin isn't working as expected:370 ```

~~333~~

3341. **Check the structure**: Ensure your directories are at the plugin root, not inside `.claude-plugin/`

3352. **Test components individually**: Check each command, agent, and hook separately

3363. **Use validation and debugging tools**: See [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools) for CLI commands and troubleshooting techniques

337 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/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/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/slash-commands) - Command development details402* Dive deeper into specific plugin components:

369 * [Subagents](/en/sub-agents) - Agent configuration and capabilities403 * [Skills](/en/skills): skill development details

370 * [Agent Skills](/en/skills) - Extend Claude's capabilities404 * [Subagents](/en/sub-agents): agent configuration and capabilities

371 * [Hooks](/en/hooks) - Event handling and automation405 * [Hooks](/en/hooks): event handling and automation

372 * [MCP](/en/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/plugin-marketplaces) - Creating and managing plugin catalogs

386* [Slash commands](/en/slash-commands) - Understanding custom commands

387* [Subagents](/en/sub-agents) - Creating and using specialized agents

388* [Agent Skills](/en/skills) - Extend Claude's capabilities

389* [Hooks](/en/hooks) - Automating workflows with event handlers

390* [MCP](/en/mcp) - Connecting to external tools and services

391* [Settings](/en/settings) - Configuration options for plugins

plugins-reference.md +417 −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/plugins). For plugin management across teams and communities, see [Plugin marketplaces](/en/plugin-marketplaces).~~6 Looking to install plugins? See [Discover and install plugins](/en/discover-plugins). For creating plugins, see [Plugins](/en/plugins). For distributing plugins, see [Plugin marketplaces](/en/plugin-marketplaces).

7</Tip>7</Tip>

8 8

9This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.9This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.

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/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/skills)~~

~~90* [Agent Skills overview](https://docs.claude.com/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

110* `PostToolUse`: After Claude successfully uses any tool

111* `PostToolUseFailure`: After Claude tool execution fails

123* `PermissionRequest`: When a permission dialog is shown112* `PermissionRequest`: When a permission dialog is shown

124* `PostToolUse`: After Claude uses any tool

125* `UserPromptSubmit`: When user submits a prompt113* `UserPromptSubmit`: When user submits a prompt

126* `Notification`: When Claude Code sends notifications114* `Notification`: When Claude Code sends notifications

127* `Stop`: When Claude attempts to stop115* `Stop`: When Claude attempts to stop

116* `SubagentStart`: When a subagent is started

128* `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

129* `SessionStart`: At the beginning of sessions119* `SessionStart`: At the beginning of sessions

130* `SessionEnd`: At the end of sessions120* `SessionEnd`: At the end of sessions

131* `PreCompact`: Before conversation history is compacted121* `PreCompact`: Before conversation history is compacted

133**Hook types**:123**Hook types**:

134 124

135* `command`: Execute shell commands or scripts125* `command`: Execute shell commands or scripts

136* `validation`: Validate file contents or project state126* `prompt`: Evaluate a prompt with an LLM (uses `$ARGUMENTS` placeholder for context)

137* `notification`: Send alerts or status updates127* `agent`: Run an agentic verifier with tools for complex verification tasks

138 128

139### MCP servers129### MCP servers

140 130

172* Server capabilities integrate seamlessly with Claude's existing tools162* Server capabilities integrate seamlessly with Claude's existing tools

173* Plugin servers can be configured independently of user MCP servers163* Plugin servers can be configured independently of user MCP servers

174 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

175***265***

176 266

177## Plugin manifest schema267## Plugin manifest schema

196 "keywords": ["keyword1", "keyword2"],286 "keywords": ["keyword1", "keyword2"],

197 "commands": ["./custom/commands/special.md"],287 "commands": ["./custom/commands/special.md"],

198 "agents": "./custom/agents/",288 "agents": "./custom/agents/",

289 "skills": "./custom/skills/",

199 "hooks": "./config/hooks.json",290 "hooks": "./config/hooks.json",

200 "mcpServers": "./mcp-config.json"291 "mcpServers": "./mcp-config.json",

292 "outputStyles": "./styles/",

293 "lspServers": "./.lsp.json"

201}294}

202```295```

203 296

222### Component path fields315### Component path fields

223 316

225| :----------- | :------------- | :----------------------------------- | :------------------------------------- |318| :------------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- |

230 326

231### Path behavior rules327### Path behavior rules

232 328

275 371

276***372***

277 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

278## Plugin directory structure427## Plugin directory structure

279 428

280### Standard plugin layout429### Standard plugin layout

302│ ├── hooks.json # Main hook config451│ ├── hooks.json # Main hook config

303│ └── security-hooks.json # Additional hooks452│ └── security-hooks.json # Additional hooks

304├── .mcp.json # MCP server definitions453├── .mcp.json # MCP server definitions

454├── .lsp.json # LSP server configurations

305├── scripts/ # Hook and utility scripts455├── scripts/ # Hook and utility scripts

306│ ├── security-scan.sh456│ ├── security-scan.sh

307│ ├── format-code.py457│ ├── format-code.py

317### File locations reference467### File locations reference

318 468

320| :-------------- | :--------------------------- | :------------------------------- |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 | |

327 594

328***595***

329 596

347### Common issues614### Common issues

348 615

350| :--------------------- | :------------------------------ | :--------------------------------------------------- |617| :---------------------------------- | :------------------------------ | :-------------------------------------------------------------------------------- |

354| 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

356 691

357***692***

358 693

363Follow semantic versioning for plugin releases:698Follow semantic versioning for plugin releases:

364 699

365```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***

366 721

367## See also722## See also

368 723

369- [Plugins](/en/plugins) - Tutorials and practical usage724* [Plugins](/en/plugins) - Tutorials and practical usage

370- [Plugin marketplaces](/en/plugin-marketplaces) - Creating and managing marketplaces725* [Plugin marketplaces](/en/plugin-marketplaces) - Creating and managing marketplaces

371- [Slash commands](/en/slash-commands) - Command development details726* [Skills](/en/skills) - Skill development details

372- [Subagents](/en/sub-agents) - Agent configuration and capabilities727* [Subagents](/en/sub-agents) - Agent configuration and capabilities

373- [Agent Skills](/en/skills) - Extend Claude's capabilities728* [Hooks](/en/hooks) - Event handling and automation

374- [Hooks](/en/hooks) - Event handling and automation729* [MCP](/en/mcp) - External tool integration

375- [MCP](/en/mcp) - External tool integration730* [Settings](/en/settings) - Configuration options for plugins

376- [Settings](/en/settings) - Configuration options for plugins731

377```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 +36 −17

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

18 18

19<Tabs>19<Tabs>

20 <Tab title="Native Install (Recommended)">20 <Tab title="Native Install (Recommended)">

~~21 **Homebrew (macOS, Linux):**~~

~~23 ```sh theme={null}~~

~~24 brew install --cask claude-code~~

~~25 ```~~

27 **macOS, Linux, WSL:**21 **macOS, Linux, WSL:**

28 22

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

41 ```batch theme={null}35 ```batch theme={null}

42 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd36 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

43 ```37 ```

~~44 </Tab>~~

45 38

~~46 <Tab title="NPM">~~39 <Info>

~~47 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):~~40 Native installations automatically update in the background to keep you on the latest version.

41 </Info>

42 </Tab>

48 43

44 <Tab title="Homebrew">

49 ```sh theme={null}45 ```sh theme={null}

~~50 npm install -g @anthropic-ai/claude-code~~46 brew install --cask claude-code

51 ```47 ```

49 <Info>

50 Homebrew installations do not auto-update. Run `brew upgrade claude-code` periodically to get the latest features and security fixes.

51 </Info>

52 </Tab>

54 <Tab title="WinGet">

55 ```powershell theme={null}

56 winget install Anthropic.ClaudeCode

57 ```

59 <Info>

60 WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.

61 </Info>

52 </Tab>62 </Tab>

53</Tabs>63</Tabs>

54 64

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.

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

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

319 <Card title="Claude Code on the web" icon="cloud" href="/en/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 +23 −4

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

141 155

142* Privilege Escalation via Unix Sockets: The `allowUnixSockets` configuration can inadvertently grant access to powerful system services that could lead to sandbox bypasses. For example, if it is used to allow access to `/var/run/docker.sock` this would effectively grant access to the host system through exploiting the docker socket. Users are encouraged to carefully consider any unix sockets that they allow through the sandbox.156* Privilege Escalation via Unix Sockets: The `allowUnixSockets` configuration can inadvertently grant access to powerful system services that could lead to sandbox bypasses. For example, if it is used to allow access to `/var/run/docker.sock` this would effectively grant access to the host system through exploiting the docker socket. Users are encouraged to carefully consider any unix sockets that they allow through the sandbox.

143* Filesystem Permission Escalation: Overly broad filesystem write permissions can enable privilege escalation attacks. Allowing writes to directories containing executables in `$PATH`, system configuration directories, or user shell configuration files (`.bashrc`, `.zshrc`) can lead to code execution in different security contexts when other users or system processes access these files.157* Filesystem Permission Escalation: Overly broad filesystem write permissions can enable privilege escalation attacks. Allowing writes to directories containing executables in `$PATH`, system configuration directories, or user shell configuration files (`.bashrc`, `.zshrc`) can lead to code execution in different security contexts when other users or system processes access these files.

144* Linux Sandbox Strength: The Linux implementation provides strong filesystem and network isolation but includes an `enableWeakerNestedSandbox` mode that enables it to work inside of Docker environments without privileged namespaces. This option considerably weakens security and should only be used incases where additional isolation is otherwise enforced.158* Linux Sandbox Strength: The Linux implementation provides strong filesystem and network isolation but includes an `enableWeakerNestedSandbox` mode that enables it to work inside of Docker environments without privileged namespaces. This option considerably weakens security and should only be used in cases where additional isolation is otherwise enforced.

145 159

146## Advanced usage160## Advanced usage

147 161

202* [Security](/en/security) - Comprehensive security features and best practices216* [Security](/en/security) - Comprehensive security features and best practices

203* [IAM](/en/iam) - Permission configuration and access control217* [IAM](/en/iam) - Permission configuration and access control

204* [Settings](/en/settings) - Complete configuration reference218* [Settings](/en/settings) - Complete configuration reference

205* [CLI reference](/en/cli-reference) - Command-line options including `-sb`219* [CLI reference](/en/cli-reference) - Command-line options

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 −329 deleted

File DeletedView Diff

~~1# Migrate to Claude Agent SDK~~

~~3Guide for migrating the Claude Code TypeScript and Python SDKs to the Claude Agent SDK~~

~~6## Overview~~

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

~~10## What's Changed~~

~~12| Aspect | Old | New |~~

~~13| :----------------------- | :-------------------------- | :------------------------------- |~~

~~14| **Package Name (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |~~

~~15| **Python Package** | `claude-code-sdk` | `claude-agent-sdk` |~~

~~16| **Documentation Location** | Claude Code docs | API Guide → Agent SDK section |~~

~~18<Note>~~

19**Documentation Changes:** The Agent SDK documentation has moved from the Claude Code docs to the API Guide under a dedicated [Agent SDK](/docs/en/agent-sdk/overview) section. The Claude Code docs now focus on the CLI tool and automation features.

~~20</Note>~~

~~22## Migration Steps~~

~~24### For TypeScript/JavaScript Projects~~

~~26**1. Uninstall the old package:**~~

~~28```bash~~

~~29npm uninstall @anthropic-ai/claude-code~~

~~30```~~

~~32**2. Install the new package:**~~

~~34```bash~~

~~35npm install @anthropic-ai/claude-agent-sdk~~

~~36```~~

~~38**3. Update your imports:**~~

~~40Change all imports from `@anthropic-ai/claude-code` to `@anthropic-ai/claude-agent-sdk`:~~

~~42```typescript~~

~~43// Before~~

~~44import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";~~

~~46// After~~

~~47import {~~

~~48 query,~~

~~49 tool,~~

~~50 createSdkMcpServer,~~

~~51} from "@anthropic-ai/claude-agent-sdk";~~

~~52```~~

~~54**4. Update package.json dependencies:**~~

~~56If you have the package listed in your `package.json`, update it:~~

~~58```json~~

~~59// Before~~

~~60{~~

~~61 "dependencies": {~~

~~62 "@anthropic-ai/claude-code": "^1.0.0"~~

~~63 }~~

~~64}~~

~~66// After~~

~~67{~~

~~68 "dependencies": {~~

~~69 "@anthropic-ai/claude-agent-sdk": "^0.1.0"~~

~~70 }~~

~~71}~~

~~72```~~

~~74That's it! No other code changes are required.~~

~~76### For Python Projects~~

~~78**1. Uninstall the old package:**~~

~~80```bash~~

~~81pip uninstall claude-code-sdk~~

~~82```~~

~~84**2. Install the new package:**~~

~~86```bash~~

~~87pip install claude-agent-sdk~~

~~88```~~

~~90**3. Update your imports:**~~

~~92Change all imports from `claude_code_sdk` to `claude_agent_sdk`:~~

~~94```python~~

~~95# Before~~

~~96from claude_code_sdk import query, ClaudeCodeOptions~~

~~98# After~~

~~99from claude_agent_sdk import query, ClaudeAgentOptions~~

100```

~~101~~

102**4. Update type names:**

~~103~~

104Change `ClaudeCodeOptions` to `ClaudeAgentOptions`:

~~105~~

106```python

107# Before

108from claude_agent_sdk import query, ClaudeCodeOptions

~~109~~

110options = ClaudeCodeOptions(

111 model="claude-sonnet-4-5"

112)

~~113~~

114# After

115from claude_agent_sdk import query, ClaudeAgentOptions

~~116~~

117options = ClaudeAgentOptions(

118 model="claude-sonnet-4-5"

119)

120```

~~121~~

122**5. Review [breaking changes](#breaking-changes)**

~~123~~

124Make any code changes needed to complete the migration.

~~125~~

126## Breaking changes

~~127~~

128<Warning>

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

130</Warning>

~~131~~

132### Python: ClaudeCodeOptions renamed to ClaudeAgentOptions

~~133~~

134**What changed:** The Python SDK type `ClaudeCodeOptions` has been renamed to `ClaudeAgentOptions`.

~~135~~

136**Migration:**

~~137~~

138```python

139# BEFORE (v0.0.x)

140from claude_agent_sdk import query, ClaudeCodeOptions

~~141~~

142options = ClaudeCodeOptions(

143 model="claude-sonnet-4-5",

144 permission_mode="acceptEdits"

145)

~~146~~

147# AFTER (v0.1.0)

148from claude_agent_sdk import query, ClaudeAgentOptions

~~149~~

150options = ClaudeAgentOptions(

151 model="claude-sonnet-4-5",

152 permission_mode="acceptEdits"

153)

154```

~~155~~

156**Why this changed:** The type name now matches the "Claude Agent SDK" branding and provides consistency across the SDK's naming conventions.

~~157~~

158### System prompt no longer default

~~159~~

160**What changed:** The SDK no longer uses Claude Code's system prompt by default.

~~161~~

162**Migration:**

~~163~~

164<CodeGroup>

~~165~~

166```typescript TypeScript

167// BEFORE (v0.0.x) - Used Claude Code's system prompt by default

168const result = query({ prompt: "Hello" });

~~169~~

170// AFTER (v0.1.0) - Uses empty system prompt by default

171// To get the old behavior, explicitly request Claude Code's preset:

172const result = query({

173 prompt: "Hello",

174 options: {

175 systemPrompt: { type: "preset", preset: "claude_code" }

176 }

177});

~~178~~

179// Or use a custom system prompt:

180const result = query({

181 prompt: "Hello",

182 options: {

183 systemPrompt: "You are a helpful coding assistant"

184 }

185});

186```

~~187~~

188```python Python

189# BEFORE (v0.0.x) - Used Claude Code's system prompt by default

190async for message in query(prompt="Hello"):

191 print(message)

~~192~~

193# AFTER (v0.1.0) - Uses empty system prompt by default

194# To get the old behavior, explicitly request Claude Code's preset:

195from claude_agent_sdk import query, ClaudeAgentOptions

~~196~~

197async for message in query(

198 prompt="Hello",

199 options=ClaudeAgentOptions(

200 system_prompt={"type": "preset", "preset": "claude_code"} # Use the preset

201 )

202):

203 print(message)

~~204~~

205# Or use a custom system prompt:

206async for message in query(

207 prompt="Hello",

208 options=ClaudeAgentOptions(

209 system_prompt="You are a helpful coding assistant"

210 )

211):

212 print(message)

213```

~~214~~

215</CodeGroup>

~~216~~

217**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.

~~218~~

219### Settings Sources No Longer Loaded by Default

~~220~~

221**What changed:** The SDK no longer reads from filesystem settings (CLAUDE.md, settings.json, slash commands, etc.) by default.

~~222~~

223**Migration:**

~~224~~

225<CodeGroup>

~~226~~

227```typescript TypeScript

228// BEFORE (v0.0.x) - Loaded all settings automatically

229const result = query({ prompt: "Hello" });

230// Would read from:

231// - ~/.claude/settings.json (user)

232// - .claude/settings.json (project)

233// - .claude/settings.local.json (local)

234// - CLAUDE.md files

235// - Custom slash commands

~~236~~

237// AFTER (v0.1.0) - No settings loaded by default

238// To get the old behavior:

239const result = query({

240 prompt: "Hello",

241 options: {

242 settingSources: ["user", "project", "local"]

243 }

244});

~~245~~

246// Or load only specific sources:

247const result = query({

248 prompt: "Hello",

249 options: {

250 settingSources: ["project"] // Only project settings

251 }

252});

253```

~~254~~

255```python Python

256# BEFORE (v0.0.x) - Loaded all settings automatically

257async for message in query(prompt="Hello"):

258 print(message)

259# Would read from:

260# - ~/.claude/settings.json (user)

261# - .claude/settings.json (project)

262# - .claude/settings.local.json (local)

263# - CLAUDE.md files

264# - Custom slash commands

~~265~~

266# AFTER (v0.1.0) - No settings loaded by default

267# To get the old behavior:

268from claude_agent_sdk import query, ClaudeAgentOptions

~~269~~

270async for message in query(

271 prompt="Hello",

272 options=ClaudeAgentOptions(

273 setting_sources=["user", "project", "local"]

274 )

275):

276 print(message)

~~277~~

278# Or load only specific sources:

279async for message in query(

280 prompt="Hello",

281 options=ClaudeAgentOptions(

282 setting_sources=["project"] # Only project settings

283 )

284):

285 print(message)

286```

~~287~~

288</CodeGroup>

~~289~~

290**Why this changed:** Ensures SDK applications have predictable behavior independent of local filesystem configurations. This is especially important for:

291- **CI/CD environments** - Consistent behavior without local customizations

292- **Deployed applications** - No dependency on filesystem settings

293- **Testing** - Isolated test environments

294- **Multi-tenant systems** - Prevent settings leakage between users

~~295~~

296<Note>

297**Backward compatibility:** If your application relied on filesystem settings (custom slash commands, CLAUDE.md instructions, etc.), add `settingSources: ['user', 'project', 'local']` to your options.

298</Note>

~~299~~

300## Why the Rename?

~~301~~

302The 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:

~~303~~

304- Building business agents (legal assistants, finance advisors, customer support)

305- Creating specialized coding agents (SRE bots, security reviewers, code review agents)

306- Developing custom agents for any domain with tool use, MCP integration, and more

~~307~~

308## Getting Help

~~309~~

310If you encounter any issues during migration:

~~311~~

312**For TypeScript/JavaScript:**

~~313~~

3141. Check that all imports are updated to use `@anthropic-ai/claude-agent-sdk`

3152. Verify your package.json has the new package name

3163. Run `npm install` to ensure dependencies are updated

~~317~~

318**For Python:**

~~319~~

3201. Check that all imports are updated to use `claude_agent_sdk`

3212. Verify your requirements.txt or pyproject.toml has the new package name

3223. Run `pip install claude-agent-sdk` to ensure the package is installed

~~323~~

324## Next Steps

~~325~~

326- Explore the [Agent SDK Overview](/docs/en/agent-sdk/overview) to learn about available features

327- Check out the [TypeScript SDK Reference](/docs/en/agent-sdk/typescript) for detailed API documentation

328- Review the [Python SDK Reference](/docs/en/agent-sdk/python) for Python-specific documentation

329- Learn about [Custom Tools](/docs/en/agent-sdk/custom-tools) and [MCP Integration](/docs/en/agent-sdk/mcp)

security.md +7 −2

Details

87 87

88## IDE security88## IDE security

89 89

~~90See [here](/en/vs-code#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

113 113

114### Team security114### Team security

115 115

116* Use [enterprise managed policies](/en/iam#enterprise-managed-policy-settings) to enforce organizational standards116* Use [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/monitoring-usage)119* Monitor Claude Code usage through [OpenTelemetry metrics](/en/monitoring-usage)

134* [Monitoring usage](/en/monitoring-usage) - Track and audit Claude Code activity134* [Monitoring usage](/en/monitoring-usage) - Track and audit Claude Code activity

135* [Development containers](/en/devcontainer) - Secure, isolated environments135* [Development containers](/en/devcontainer) - Secure, isolated environments

136* [Anthropic Trust Center](https://trust.anthropic.com) - Security certifications and compliance136* [Anthropic Trust Center](https://trust.anthropic.com) - Security certifications and compliance

137

138

139---

140

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

settings.md +599 −68

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/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{

58`settings.json` supports a number of options:129`settings.json` supports a number of options:

59 130

60| Key | Description | Example |131| Key | Description | Example |

61| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |132| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- |

62| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests | `/bin/generate_temp_api_key.sh` |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` |

63| `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` |

64| `companyAnnouncements` | Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |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"]` |

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

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

68| `hooks` | Configure custom commands to run before or after tool executions. See [hooks documentation](/en/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` |

71| `statusLine` | Configure a custom status line to display context. See [statusLine documentation](/en/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` |

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

74| `forceLoginOrgUUID` | Specify the UUID of an organization to automatically select it during login, bypassing the organization selection step. Requires `forceLoginMethod` to be set | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |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"` |

78| `allowedMcpServers` | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "github" }]` |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" }]` |

79| `deniedMcpServers` | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including enterprise servers. Denylist takes precedence over allowlist. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "filesystem" }]` |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" }]` |

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

80| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/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` |

81| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |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` |

82 166

83### Permission settings167### Permission settings

84 168

86| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |170| :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |

87| `allow` | Array of [permission rules](/en/iam#configuring-permissions) to allow tool use. **Note:** Bash rules use prefix matching, not regex | `[ "Bash(git diff:*)" ]` |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:*)" ]` |

88| `ask` | Array of [permission rules](/en/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:*)" ]` |

89| `deny` | Array of [permission rules](/en/iam#configuring-permissions) to deny tool use. Use this to also exclude sensitive files from Claude Code access. **Note:** Bash patterns are prefix matches and can be bypassed (see [Bash permission limitations](/en/iam#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |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/**)" ]` |

92| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed policy settings](/en/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).

93 265

94### Sandbox settings266### Sandbox settings

95 267

105| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |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` |

108| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |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` |

109| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |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` |

133}305}

134```306```

135 307

136**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

137 316

138* Read deny rules block file reads in sandbox317Claude Code adds attribution to git commits and pull requests. These are configured separately:

139* Edit allow rules permit file writes (in addition to the defaults, e.g. the current working directory)

140* Edit deny rules block writes within allowed paths

141 318

142**Network access** is controlled via WebFetch permissions: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

143 321

144* WebFetch allow rules permit network domains322| Keys | Description |

145* WebFetch deny rules block network domains323| :------- | :----------------------------------------------------------------------------------------- |

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)

331

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

333```

334

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>

355

356### File suggestion settings

357

358Configure 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.

359

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

146 407

147### Settings precedence408### Settings precedence

148 409

149Settings are applied in order of precedence (highest to lowest):410Settings apply in order of precedence. From highest to lowest:

150 411

1511. **Enterprise managed policies** (`managed-settings.json`)4121. **Managed settings** (`managed-settings.json`)

152 * Deployed by IT/DevOps413 * Policies deployed by IT/DevOps to system directories

153 * Cannot be overridden414 * Cannot be overridden by user or project settings

154 415

1552. **Command line arguments**4162. **Command line arguments**

156 * Temporary overrides for a specific session417 * Temporary overrides for a specific session

1645. **User settings** (`~/.claude/settings.json`)4255. **User settings** (`~/.claude/settings.json`)

165 * Personal global settings426 * Personal global settings

166 427

167This 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.

168 431

169### Key points about the configuration system432### Key points about the configuration system

170 433

171* **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

172* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior435* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior

173* **Slash commands**: Custom commands that can be invoked during a session with `/command-name`436* **Skills**: Custom prompts that can be invoked with `/skill-name` or loaded by Claude automatically

174* **MCP servers**: Extend Claude Code with additional tools and integrations437* **MCP servers**: Extend Claude Code with additional tools and integrations

175* **Precedence**: Higher-level configurations (Enterprise) override lower-level ones (User/Project)438* **Precedence**: Higher-level configurations (Managed) override lower-level ones (User/Project)

176* **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

177 440

178### System prompt availability441### System prompt

179 442

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

181 Unlike for claude.ai, we do not publish Claude Code's internal system prompt on this website. Use CLAUDE.md files or `--append-system-prompt` to add custom instructions to Claude Code's behavior.

182</Note>

183 444

184### Excluding sensitive files445### Excluding sensitive files

185 446

186To prevent Claude Code from accessing files containing sensitive information (e.g., API keys, secrets, environment files), use the `permissions.deny` setting in your `.claude/settings.json` file: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:

187 448

188```json theme={null}449```json theme={null}

189{450{

212 473

213## Plugin configuration474## Plugin configuration

214 475

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

216 477

217### Plugin settings478### Plugin settings

218 479

221```json theme={null}482```json theme={null}

222{483{

223 "enabledPlugins": {484 "enabledPlugins": {

224 "formatter@company-tools": true,485 "formatter@acme-tools": true,

225 "deployer@company-tools": true,486 "deployer@acme-tools": true,

226 "analyzer@security-plugins": false487 "analyzer@security-plugins": false

227 },488 },

228 "extraKnownMarketplaces": {489 "extraKnownMarketplaces": {

229 "company-tools": {490 "acme-tools": {

230 "source": "github",491 "source": "github",

231 "repo": "company/claude-plugins"492 "repo": "acme-corp/claude-plugins"

232 }493 }

233 }494 }

234}495}

272```json theme={null}533```json theme={null}

273{534{

274 "extraKnownMarketplaces": {535 "extraKnownMarketplaces": {

275 "company-tools": {536 "acme-tools": {

276 "source": {537 "source": {

277 "source": "github",538 "source": "github",

278 "repo": "company-org/claude-plugins"539 "repo": "acme-corp/claude-plugins"

279 }540 }

280 },541 },

281 "security-plugins": {542 "security-plugins": {

282 "source": {543 "source": {

283 "source": "git",544 "source": "git",

284 "url": "https://git.company.com/security/plugins.git"545 "url": "https://git.example.com/security/plugins.git"

285 }546 }

286 }547 }

287 }548 }

294* `git`: Any git URL (uses `url`)555* `git`: Any git URL (uses `url`)

295* `directory`: Local filesystem path (uses `path`, for development only)556* `directory`: Local filesystem path (uses `path`, for development only)

296 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

297### Managing plugins746### Managing plugins

298 747

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

315</Note>764</Note>

316 765

318| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |767| :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

319| `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`) |

320| `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 `) |

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

334| `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`) |

338| `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 |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 |

339| `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` |

340| `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 |

342| `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. |

343| `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) |

344| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (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`) |

345| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (e.g. when using an LLM gateway) |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>` |

802| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip AWS authentication for Bedrock (for example, when using an LLM gateway) |

803| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) |

804| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (for example, when using an LLM gateway) |

809| `CLAUDE_CONFIG_DIR` | Customize where Claude Code stores its configuration and data files |

359| `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 |

362| `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) |

363| `MAX_THINKING_TOKENS` | Enable [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) and set the token budget for the thinking process. Extended thinking improves performance on complex reasoning and coding tasks but impacts [prompt caching efficiency](https://docs.claude.com/en/docs/build-with-claude/prompt-caching#caching-with-thinking-blocks). Disabled by default. |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). |

367| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum number of characters for slash command metadata shown to [SlashCommand tool](/en/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. |

377Claude 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:

378 841

380| :------------------ | :--------------------------------------------------------------------------------- | :------------------ |843| :------------------ | :------------------------------------------------------------------------------------------------- | :------------------ |

381| **AskUserQuestion** | Asks the user multiple choice questions to gather information or clarify ambiguity | No |844| **AskUserQuestion** | Asks multiple-choice questions to gather requirements or clarify ambiguity | No |

382| **Bash** | Executes shell commands in your environment | Yes |845| **Bash** | Executes shell commands in your environment (see [Bash tool behavior](#bash-tool-behavior) below) | Yes |

383| **BashOutput** | Retrieves output from a background bash shell | No |846| **TaskOutput** | Retrieves output from a background task (bash shell or subagent) | No |

384| **Edit** | Makes targeted edits to specific files | Yes |847| **Edit** | Makes targeted edits to specific files | Yes |

385| **ExitPlanMode** | Prompts the user to exit plan mode and start coding | Yes |848| **ExitPlanMode** | Prompts the user to exit plan mode and start coding | Yes |

386| **Glob** | Finds files based on pattern matching | No |849| **Glob** | Finds files based on pattern matching | No |

387| **Grep** | Searches for patterns in file contents | No |850| **Grep** | Searches for patterns in file contents | No |

388| **KillShell** | Kills a running background bash shell by its ID | 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 |

389| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |853| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |

390| **Read** | Reads the contents of files | No |854| **Read** | Reads the contents of files | No |

391| **Skill** | Executes a skill within the main conversation | Yes |855| **Skill** | Executes a [skill](/en/skills#control-who-invokes-a-skill) within the main conversation | Yes |

392| **SlashCommand** | Runs a [custom slash command](/en/slash-commands#slashcommand-tool) | Yes |

393| **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 |

394| **TodoWrite** | Creates and manages structured task lists | No |857| **TodoWrite** | Creates and manages structured task lists | No |

395| **WebFetch** | Fetches content from a specified URL | Yes |858| **WebFetch** | Fetches content from a specified URL | Yes |

398 861

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

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

925

401### Extending tools with hooks926### Extending tools with hooks

402 927

403You can run custom commands before or after any tool executes using928You can run custom commands before or after any tool executes using

409 934

410## See also935## See also

411 936

412* [Identity and Access Management](/en/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

413* [IAM and access control](/en/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

414* [Troubleshooting](/en/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 +230 −105

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

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.

722. **Claude App (with Pro or Max plan)**: Subscribe to Claude's [Pro or Max plan](https://claude.com/pricing) for a unified subscription that includes both Claude Code and the web interface. Get more value at the same price point while managing your account in one place. Log in with your Claude.ai account. During launch, choose the option that matches your subscription type.

733. **Enterprise platforms**: Configure Claude Code to use [Amazon Bedrock, Google Vertex AI, or Microsoft Foundry](/en/third-party-integrations) for enterprise deployments with your existing cloud infrastructure.

~~75<Note>~~

~~76 Claude Code securely stores your credentials. See [Credential Management](/en/iam#credential-management) for details.~~

~~77</Note>~~

~~79## Windows setup~~

~~81**Option 1: Claude Code within WSL**~~

~~83* Both WSL 1 and WSL 2 are supported~~

~~85**Option 2: Claude Code on native Windows with Git Bash**~~

~~87* Requires [Git for Windows](https://git-scm.com/downloads/win)~~

~~88* For portable Git installations, specify the path to your `bash.exe`:~~

~~89 ```powershell theme={null}~~

~~90 $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"~~

~~91 ```~~

~~93## Alternative installation methods~~

~~95Claude Code offers multiple installation methods to suit different environments.~~

~~97If you encounter any issues during installation, consult the [troubleshooting guide](/en/troubleshooting#linux-permission-issues).~~

98 76

99<Tip>77<Tip>

100 Run `claude doctor` after installation to check your installation type and version.78 Run `claude doctor` after installation to check your installation type and version.

101</Tip>79</Tip>

102 80

103### Native installation options81<Note>

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

83</Note>

104 84

105The native installation is the recommended method and offers several benefits:85### Authentication

106 86

107* One self-contained executable87#### For individuals

108* No Node.js dependency

109* Improved auto-updater stability

110 88

111If you have an existing installation of Claude Code, use `claude install` to migrate to the native binary installation.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.

112 91

113For advanced installation options with the native installer:92#### For teams and organizations

114 93

115**macOS, Linux, WSL:**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.

116 97

117```bash theme={null}98### Install a specific version

118# Install stable version (default)

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

120 99

121# Install latest version100The 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.

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

123 101

124# Install specific version number102To install the latest version (default):

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

126```

127 103

128<Note>104<Tabs>

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`.105 <Tab title="macOS, Linux, WSL">

130</Note>106 ```bash theme={null}

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

108 ```

109 </Tab>

131 110

132<Note>111 <Tab title="Windows PowerShell">

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).112 ```powershell theme={null}

134</Note>113 irm https://claude.ai/install.ps1 | iex

114 ```

115 </Tab>

135 116

136**Windows PowerShell:**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>

137 123

138```powershell theme={null}124To install the stable version:

139# Install stable version (default)

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

141 125

142# Install latest version126<Tabs>

143& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest127 <Tab title="macOS, Linux, WSL">

128 ```bash theme={null}

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

130 ```

131 </Tab>

144 132

145# Install specific version number133 <Tab title="Windows PowerShell">

146& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58134 ```powershell theme={null}

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

136 ```

137 </Tab>

148 138

149**Windows CMD:**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>

150 145

151```batch theme={null}146To install a specific version number:

152REM Install stable version (default)

153curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

154 147

155REM Install latest version148<Tabs>

156curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd latest && del install.cmd149 <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>

157 154

158REM Install specific version number155 <Tab title="Windows PowerShell">

159curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd156 ```powershell theme={null}

160```157 & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

158 ```

159 </Tab>

161 160

162<Tip>161 <Tab title="Windows CMD">

163 Make sure that you remove any outdated aliases or symlinks before installing.162 ```batch theme={null}

164</Tip>163 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd

164 ```

165 </Tab>

166</Tabs>

165 167

166**Binary integrity and code signing**168### Binary integrity and code signing

167 169

168* 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`)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`)

169* Signed binaries are distributed for the following platforms:171* Signed binaries are distributed for the following platforms:

170 * macOS: Signed by "Anthropic PBC" and notarized by Apple172 * macOS: Signed by "Anthropic PBC" and notarized by Apple

171 * Windows: Signed by "Anthropic, PBC"173 * Windows: Signed by "Anthropic, PBC"

172 174

173### NPM installation175## NPM installation (deprecated)

174 176

175For environments where NPM is preferred or required: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**

176 180

177```sh theme={null}181```sh theme={null}

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

180 184

181<Warning>185<Warning>

182 Do NOT use `sudo npm install -g` as this can lead to permission issues and security risks.186 Do NOT use `sudo npm install -g` as this can lead to permission issues and security risks.

183 If you encounter permission errors, see [configure Claude Code](/en/troubleshooting#linux-permission-issues) for recommended solutions.187 If you encounter permission errors, see [troubleshooting permission errors](/en/troubleshooting#command-not-found-claude-or-permission-errors) for recommended solutions.

184</Warning>188</Warning>

185 189

186### Local installation190## Windows setup

187 191

188* After global install via npm, use `claude migrate-installer` to move to local192**Option 1: Claude Code within WSL**

189* Avoids autoupdater npm permission issues

190* Some users may be automatically migrated to this method

191 193

192## Running on AWS or GCP194* Both WSL 1 and WSL 2 are supported

193 195

194By default, Claude Code uses the Claude API.196**Option 2: Claude Code on native Windows with Git Bash**

195 197

196For details on running Claude Code on AWS or GCP, see [third-party integrations](/en/third-party-integrations).198* Requires [Git for Windows](https://git-scm.com/downloads/win)

199* For portable Git installations, specify the path to your `bash.exe`:

200 ```powershell theme={null}

201 $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

202 ```

197 203

198## Update Claude Code204## Update Claude Code

199 205

206* **Notifications**: You'll see a notification when updates are installed212* **Notifications**: You'll see a notification when updates are installed

207* **Applying updates**: Updates take effect the next time you start Claude Code213* **Applying updates**: Updates take effect the next time you start Claude Code

208 214

209**Disable auto-updates:**215<Note>

216 Homebrew and WinGet installations do not auto-update. Use `brew upgrade claude-code` or `winget upgrade Anthropic.ClaudeCode` to update manually.

217

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>

220

221### Configure release channel

222

223Configure which release channel Claude Code follows for both auto-updates and `claude update` with the `autoUpdatesChannel` setting:

224

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

227

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

210 239

211Set the `DISABLE_AUTOUPDATER` environment variable in your shell or [settings.json file](/en/settings):240Set the `DISABLE_AUTOUPDATER` environment variable in your shell or [settings.json file](/en/settings):

212 241

219```bash theme={null}248```bash theme={null}

220claude update249claude update

221```250```

251

252## Uninstall Claude Code

253

254If you need to uninstall Claude Code, follow the instructions for your installation method.

255

256### Native installation

257

258Remove the Claude Code binary and version files:

259

260**macOS, Linux, WSL:**

261

262```bash theme={null}

263rm -f ~/.local/bin/claude

264rm -rf ~/.local/share/claude

265```

266

267**Windows PowerShell:**

268

269```powershell theme={null}

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

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

272```

273

274**Windows CMD:**

275

276```batch theme={null}

277del "%USERPROFILE%\.local\bin\claude.exe"

278rmdir /s /q "%USERPROFILE%\.local\share\claude"

279```

280

281### Homebrew installation

282

283```bash theme={null}

284brew uninstall --cask claude-code

285```

286

287### WinGet installation

288

289```powershell theme={null}

290winget uninstall Anthropic.ClaudeCode

291```

292

293### NPM installation

294

295```bash theme={null}

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

297```

298

299### Clean up configuration files (optional)

300

301<Warning>

302 Removing configuration files will delete all your settings, allowed tools, MCP server configurations, and session history.

303</Warning>

304

305To remove Claude Code settings and cached data:

306

307**macOS, Linux, WSL:**

308

309```bash theme={null}

310# Remove user settings and state

311rm -rf ~/.claude

312rm ~/.claude.json

313

314# Remove project-specific settings (run from your project directory)

315rm -rf .claude

316rm -f .mcp.json

317```

318

319**Windows PowerShell:**

320

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

325

326# Remove project-specific settings (run from your project directory)

327Remove-Item -Path ".claude" -Recurse -Force

328Remove-Item -Path ".mcp.json" -Force

329```

330

331**Windows CMD:**

332

333```batch theme={null}

334REM Remove user settings and state

335rmdir /s /q "%USERPROFILE%\.claude"

336del "%USERPROFILE%\.claude.json"

337

338REM Remove project-specific settings (run from your project directory)

339rmdir /s /q ".claude"

340del ".mcp.json"

341```

342

343

344---

345

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/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](https://docs.claude.com/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/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](https://docs.claude.com/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/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/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="https://docs.claude.com/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="https://docs.claude.com/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="https://docs.claude.com/en/docs/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="https://docs.claude.com/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 −497 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| `/bashes` | List and manage background tasks |~~

~~12| `/bug` | Report bugs (sends conversation to Anthropic) |~~

~~13| `/clear` | Clear conversation history |~~

~~14| `/compact [instructions]` | Compact conversation with optional focus instructions |~~

~~15| `/config` | Open the Settings interface (Config tab) |~~

~~16| `/context` | Visualize current context usage as a colored grid |~~

~~17| `/cost` | Show token usage statistics (see [cost tracking guide](/en/costs#using-the-cost-command) for subscription-specific details) |~~

~~18| `/doctor` | Checks the health of your Claude Code installation |~~

~~19| `/exit` | Exit the REPL |~~

~~20| `/export [filename]` | Export the current conversation to a file or clipboard |~~

~~21| `/help` | Get usage help |~~

~~22| `/hooks` | Manage hook configurations for tool events |~~

~~23| `/ide` | Manage IDE integrations and show status |~~

~~24| `/init` | Initialize project with CLAUDE.md guide |~~

~~25| `/install-github-app` | Set up Claude GitHub Actions for a repository |~~

~~26| `/login` | Switch Anthropic accounts |~~

~~27| `/logout` | Sign out from your Anthropic account |~~

~~28| `/mcp` | Manage MCP server connections and OAuth authentication |~~

~~29| `/memory` | Edit CLAUDE.md memory files |~~

~~30| `/model` | Select or change the AI model |~~

~~31| `/output-style [style]` | Set the output style directly or from a selection menu |~~

~~32| `/permissions` | View or update [permissions](/en/iam#configuring-permissions) |~~

~~33| `/plugin` | Manage Claude Code plugins |~~

~~34| `/pr-comments` | View pull request comments |~~

~~35| `/privacy-settings` | View and update your privacy settings |~~

~~36| `/release-notes` | View release notes |~~

~~37| `/resume` | Resume a conversation |~~

~~38| `/review` | Request code review |~~

~~39| `/rewind` | Rewind the conversation and/or code |~~

~~40| `/sandbox` | Enable sandboxed bash tool with filesystem and network isolation for safer, more autonomous execution |~~

~~41| `/security-review` | Complete a security review of pending changes on the current branch |~~

~~42| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |~~

~~43| `/statusline` | Set up Claude Code's status line UI |~~

~~44| `/terminal-setup` | Install Shift+Enter key binding for newlines (iTerm2 and VSCode only) |~~

~~45| `/todos` | List current todo items |~~

~~46| `/usage` | Show plan usage limits and rate limit status (subscription plans only) |~~

~~47| `/vim` | Enter vim mode for alternating insert and command modes |~~

~~49## Custom slash commands~~

51Custom 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.

~~53### Syntax~~

~~55```~~

~~56/<command-name> [arguments]~~

~~57```~~

~~59#### Parameters~~

~~61| Parameter | Description |~~

~~62| :--------------- | :---------------------------------------------------------------- |~~

~~63| `<command-name>` | Name derived from the Markdown filename (without `.md` extension) |~~

~~64| `[arguments]` | Optional arguments passed to the command |~~

~~66### Command types~~

~~68#### Project commands~~

~~70Commands stored in your repository and shared with your team. When listed in `/help`, these commands show "(project)" after their description.~~

~~72**Location**: `.claude/commands/`~~

~~74In the following example, we create the `/optimize` command:~~

~~76```bash theme={null}~~

~~77# Create a project command~~

~~78mkdir -p .claude/commands~~

~~79echo "Analyze this code for performance issues and suggest optimizations:" > .claude/commands/optimize.md~~

~~80```~~

~~82#### Personal commands~~

~~84Commands available across all your projects. When listed in `/help`, these commands show "(user)" after their description.~~

~~86**Location**: `~/.claude/commands/`~~

~~88In the following example, we create the `/security-review` command:~~

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

~~91# Create a personal command~~

~~92mkdir -p ~/.claude/commands~~

~~93echo "Review this code for security vulnerabilities:" > ~/.claude/commands/security-review.md~~

~~94```~~

~~96### Features~~

~~98#### Namespacing~~

100Organize 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.

~~101~~

102Conflicts between user and project level commands are not supported. Otherwise, multiple commands with the same base file name can coexist.

~~103~~

104For example, a file at `.claude/commands/frontend/component.md` creates the command `/component` with description showing "(project:frontend)".

105Meanwhile, a file at `~/.claude/commands/component.md` creates the command `/component` with description showing "(user)".

~~106~~

107#### Arguments

~~108~~

109Pass dynamic values to commands using argument placeholders:

~~110~~

111##### All arguments with `$ARGUMENTS`

~~112~~

113The `$ARGUMENTS` placeholder captures all arguments passed to the command:

~~114~~

115```bash theme={null}

116# Command definition

117echo 'Fix issue #$ARGUMENTS following our coding standards' > .claude/commands/fix-issue.md

~~118~~

119# Usage

120> /fix-issue 123 high-priority

121# $ARGUMENTS becomes: "123 high-priority"

122```

~~123~~

124##### Individual arguments with `$1`, `$2`, etc.

~~125~~

126Access specific arguments individually using positional parameters (similar to shell scripts):

~~127~~

128```bash theme={null}

129# Command definition

130echo 'Review PR #$1 with priority $2 and assign to $3' > .claude/commands/review-pr.md

~~131~~

132# Usage

133> /review-pr 456 high alice

134# $1 becomes "456", $2 becomes "high", $3 becomes "alice"

135```

~~136~~

137Use positional arguments when you need to:

~~138~~

139* Access arguments individually in different parts of your command

140* Provide defaults for missing arguments

141* Build more structured commands with specific parameter roles

~~142~~

143#### Bash command execution

~~144~~

145Execute 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.

~~146~~

147For example:

~~148~~

149```markdown theme={null}

150allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)

151description: Create a git commit

~~152~~

153## Context

~~154~~

155- Current git status: !`git status`

156- Current git diff (staged and unstaged changes): !`git diff HEAD`

157- Current branch: !`git branch --show-current`

158- Recent commits: !`git log --oneline -10`

~~159~~

160## Your task

~~161~~

162Based on the above changes, create a single git commit.

163```

~~164~~

165#### File references

~~166~~

167Include file contents in commands using the `@` prefix to [reference files](/en/common-workflows#reference-files-and-directories).

~~168~~

169For example:

~~170~~

171```markdown theme={null}

172# Reference a specific file

~~173~~

174Review the implementation in @src/utils/helpers.js

~~175~~

176# Reference multiple files

~~177~~

178Compare @src/old-version.js with @src/new-version.js

179```

~~180~~

181#### Thinking mode

~~182~~

183Slash commands can trigger extended thinking by including [extended thinking keywords](/en/common-workflows#use-extended-thinking).

~~184~~

185### Frontmatter

~~186~~

187Command files support frontmatter, useful for specifying metadata about the command:

~~188~~

189| Frontmatter | Purpose | Default |

190| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------- |

191| `allowed-tools` | List of tools the command can use | Inherits from the conversation |

193| `description` | Brief description of the command | Uses the first line from the prompt |

194| `model` | Specific model string (see [Models overview](https://docs.claude.com/en/docs/about-claude/models/overview)) | Inherits from the conversation |

195| `disable-model-invocation` | Whether to prevent `SlashCommand` tool from calling this command | false |

~~196~~

197For example:

~~198~~

199```markdown theme={null}

200allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)

201argument-hint: [message]

202description: Create a git commit

203model: claude-3-5-haiku-20241022

~~204~~

205Create a git commit with message: $ARGUMENTS

206```

~~207~~

208Example using positional arguments:

~~209~~

210```markdown theme={null}

211argument-hint: [pr-number] [priority] [assignee]

212description: Review pull request

~~213~~

214Review PR #$1 with priority $2 and assign to $3.

215Focus on security, performance, and code style.

216```

~~217~~

218## Plugin commands

~~219~~

220[Plugins](/en/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/plugin-marketplaces).

~~221~~

222### How plugin commands work

~~223~~

224Plugin commands are:

~~225~~

226* **Namespaced**: Commands can use the format `/plugin-name:command-name` to avoid conflicts (plugin prefix is optional unless there are name collisions)

227* **Automatically available**: Once a plugin is installed and enabled, its commands appear in `/help`

228* **Fully integrated**: Support all command features (arguments, frontmatter, bash execution, file references)

~~229~~

230### Plugin command structure

~~231~~

232**Location**: `commands/` directory in plugin root

~~233~~

234**File format**: Markdown files with frontmatter

~~235~~

236**Basic command structure**:

~~237~~

238```markdown theme={null}

239description: Brief description of what the command does

~~240~~

241# Command Name

~~242~~

243Detailed instructions for Claude on how to execute this command.

244Include specific guidance on parameters, expected outcomes, and any special considerations.

245```

~~246~~

247**Advanced command features**:

~~248~~

249* **Arguments**: Use placeholders like `{arg1}` in command descriptions

250* **Subdirectories**: Organize commands in subdirectories for namespacing

251* **Bash integration**: Commands can execute shell scripts and programs

252* **File references**: Commands can reference and modify project files

~~253~~

254### Invocation patterns

~~255~~

256```shell Direct command (when no conflicts) theme={null}

257/command-name

258```

~~259~~

260```shell Plugin-prefixed (when needed for disambiguation) theme={null}

261/plugin-name:command-name

262```

~~263~~

264```shell With arguments (if command supports them) theme={null}

265/command-name arg1 arg2

266```

~~267~~

268## MCP slash commands

~~269~~

270MCP servers can expose prompts as slash commands that become available in Claude Code. These commands are dynamically discovered from connected MCP servers.

~~271~~

272### Command format

~~273~~

274MCP commands follow the pattern:

~~275~~

276```

277/mcp__<server-name>__<prompt-name> [arguments]

278```

~~279~~

280### Features

~~281~~

282#### Dynamic discovery

~~283~~

284MCP commands are automatically available when:

~~285~~

286* An MCP server is connected and active

287* The server exposes prompts through the MCP protocol

288* The prompts are successfully retrieved during connection

~~289~~

290#### Arguments

~~291~~

292MCP prompts can accept arguments defined by the server:

~~293~~

294```

295# Without arguments

296> /mcp__github__list_prs

~~297~~

298# With arguments

299> /mcp__github__pr_review 456

300> /mcp__jira__create_issue "Bug title" high

301```

~~302~~

303#### Naming conventions

~~304~~

305* Server and prompt names are normalized

306* Spaces and special characters become underscores

307* Names are lowercased for consistency

~~308~~

309### Managing MCP connections

~~310~~

311Use the `/mcp` command to:

~~312~~

313* View all configured MCP servers

314* Check connection status

315* Authenticate with OAuth-enabled servers

316* Clear authentication tokens

317* View available tools and prompts from each server

~~318~~

319### MCP permissions and wildcards

~~320~~

321When configuring [permissions for MCP tools](/en/iam#tool-specific-permission-rules), note that **wildcards are not supported**:

~~322~~

323* ✅ **Correct**: `mcp__github` (approves ALL tools from the github server)

324* ✅ **Correct**: `mcp__github__get_issue` (approves specific tool)

325* ❌ **Incorrect**: `mcp__github__*` (wildcards not supported)

~~326~~

327To approve all tools from an MCP server, use just the server name: `mcp__servername`. To approve specific tools only, list each tool individually.

~~328~~

329## `SlashCommand` tool

~~330~~

331The `SlashCommand` tool allows Claude to execute [custom slash commands](/en/slash-commands#custom-slash-commands) programmatically

332during a conversation. This gives Claude the ability to invoke custom commands

333on your behalf when appropriate.

~~334~~

335To encourage Claude to trigger `SlashCommand` tool, your instructions (prompts,

336CLAUDE.md, etc.) generally need to reference the command by name with its slash.

~~337~~

338Example:

~~339~~

340```

341> Run /write-unit-test when you are about to start writing tests.

342```

~~343~~

344This tool puts each available custom slash command's metadata into context up to the

345character budget limit. You can use `/context` to monitor token usage and follow

346the operations below to manage context.

~~347~~

348### `SlashCommand` tool supported commands

~~349~~

350`SlashCommand` tool only supports custom slash commands that:

~~351~~

352* Are user-defined. Built-in commands like `/compact` and `/init` are *not* supported.

353* Have the `description` frontmatter field populated. We use the `description` in the context.

~~354~~

355For Claude Code versions >= 1.0.124, you can see which custom slash commands

356`SlashCommand` tool can invoke by running `claude --debug` and triggering a query.

~~357~~

358### Disable `SlashCommand` tool

~~359~~

360To prevent Claude from executing any slash commands via the tool:

~~361~~

362```bash theme={null}

363/permissions

364# Add to deny rules: SlashCommand

365```

~~366~~

367This will also remove SlashCommand tool (and the slash command descriptions) from context.

~~368~~

369### Disable specific commands only

~~370~~

371To prevent a specific slash command from becoming available, add

372`disable-model-invocation: true` to the slash command's frontmatter.

~~373~~

374This will also remove the command's metadata from context.

~~375~~

376### `SlashCommand` permission rules

~~377~~

378The permission rules support:

~~379~~

380* **Exact match**: `SlashCommand:/commit` (allows only `/commit` with no arguments)

381* **Prefix match**: `SlashCommand:/review-pr:*` (allows `/review-pr` with any arguments)

~~382~~

383### Character budget limit

~~384~~

385The `SlashCommand` tool includes a character budget to limit the size of command

386descriptions shown to Claude. This prevents token overflow when many commands

387are available.

~~388~~

389The budget includes each custom slash command's name, args, and description.

~~390~~

391* **Default limit**: 15,000 characters

392* **Custom limit**: Set via `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable

~~393~~

394When the character budget is exceeded, Claude will see only a subset of the

395available commands. In `/context`, a warning will show with "M of N commands".

~~396~~

397## Skills vs slash commands

~~398~~

399**Slash commands** and **Agent Skills** serve different purposes in Claude Code:

~~400~~

401### Use slash commands for

~~402~~

403**Quick, frequently-used prompts**:

~~404~~

405* Simple prompt snippets you use often

406* Quick reminders or templates

407* Frequently-used instructions that fit in one file

~~408~~

409**Examples**:

~~410~~

411* `/review` → "Review this code for bugs and suggest improvements"

412* `/explain` → "Explain this code in simple terms"

413* `/optimize` → "Analyze this code for performance issues"

~~414~~

415### Use Skills for

~~416~~

417**Comprehensive capabilities with structure**:

~~418~~

419* Complex workflows with multiple steps

420* Capabilities requiring scripts or utilities

421* Knowledge organized across multiple files

422* Team workflows you want to standardize

~~423~~

424**Examples**:

~~425~~

426* PDF processing Skill with form-filling scripts and validation

427* Data analysis Skill with reference docs for different data types

428* Documentation Skill with style guides and templates

~~429~~

430### Key differences

~~431~~

432| Aspect | Slash Commands | Agent Skills |

433| -------------- | -------------------------------- | ----------------------------------- |

434| **Complexity** | Simple prompts | Complex capabilities |

435| **Structure** | Single .md file | Directory with SKILL.md + resources |

436| **Discovery** | Explicit invocation (`/command`) | Automatic (based on context) |

437| **Files** | One file only | Multiple files, scripts, templates |

438| **Scope** | Project or personal | Project or personal |

439| **Sharing** | Via git | Via git |

~~440~~

441### Example comparison

~~442~~

443**As a slash command**:

~~444~~

445```markdown theme={null}

446# .claude/commands/review.md

447Review this code for:

448- Security vulnerabilities

449- Performance issues

450- Code style violations

451```

~~452~~

453Usage: `/review` (manual invocation)

~~454~~

455**As a Skill**:

~~456~~

457```

458.claude/skills/code-review/

459├── SKILL.md (overview and workflows)

460├── SECURITY.md (security checklist)

461├── PERFORMANCE.md (performance patterns)

462├── STYLE.md (style guide reference)

463└── scripts/

464 └── run-linters.sh

465```

~~466~~

467Usage: "Can you review this code?" (automatic discovery)

~~468~~

469The Skill provides richer context, validation scripts, and organized reference material.

~~470~~

471### When to use each

~~472~~

473**Use slash commands**:

~~474~~

475* You invoke the same prompt repeatedly

476* The prompt fits in a single file

477* You want explicit control over when it runs

~~478~~

479**Use Skills**:

~~480~~

481* Claude should discover the capability automatically

482* Multiple files or scripts are needed

483* Complex workflows with validation steps

484* Team needs standardized, detailed guidance

~~485~~

486Both slash commands and Skills can coexist. Use the approach that fits your needs.

~~487~~

488Learn more about [Agent Skills](/en/skills).

~~489~~

490## See also

~~491~~

492* [Plugins](/en/plugins) - Extend Claude Code with custom commands through plugins

493* [Identity and Access Management](/en/iam) - Complete guide to permissions, including MCP tool permissions

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

495* [CLI reference](/en/cli-reference) - Command-line flags and options

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

497* [Memory management](/en/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 +457 −281

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

21Claude Code includes built-in subagents that Claude automatically uses when appropriate. Each inherits the parent conversation's permissions with additional tool restrictions.

23<Tabs>

24 <Tab title="Explore">

25 A fast, read-only agent optimized for searching and analyzing codebases.

27 * **Model**: Haiku (fast, low-latency)

28 * **Tools**: Read-only tools (denied access to Write and Edit tools)

29 * **Purpose**: File discovery, code search, codebase exploration

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.

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>

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.

19 48

~~20<CardGroup cols={2}>~~49 * **Model**: Inherits from main conversation

~~21 <Card title="Context preservation" icon="layer-group">~~50 * **Tools**: All tools

~~22 Each subagent operates in its own context, preventing pollution of the main conversation and keeping it focused on high-level objectives.~~51 * **Purpose**: Complex research, multi-step operations, code modifications

~~23 </Card>~~

24 52

~~25 <Card title="Specialized expertise" icon="brain">~~53 Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps.

~~26 Subagents can be fine-tuned with detailed instructions for specific domains, leading to higher success rates on designated tasks.~~54 </Tab>

~~27 </Card>~~

28 55

~~29 <Card title="Reusability" icon="rotate">~~56 <Tab title="Other">

~~30 Once created, subagents can be used across different projects and shared with your team for consistent workflows.~~57 Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly.

~~31 </Card>~~

32 58

~~33 <Card title="Flexible permissions" icon="shield-check">~~59 | Agent | Model | When Claude uses it |

~~34 Each subagent can have different tool access levels, allowing you to limit powerful tools to specific subagent types.~~60 | :---------------- | :------- | :------------------------------------------------------- |

~~35 </Card>~~61 | Bash | Inherits | Running terminal commands in a separate context |

~~36</CardGroup>~~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>

37 66

~~38## Quick start~~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.

39 68

~~40To create your first subagent:~~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.

53 </Step>86 </Step>

54 87

~~55 <Step title="Define the subagent">~~88 <Step title="Generate with Claude">

~~56 * **Recommended**: Generate with Claude first, then customize to make it yours~~89 Select **Generate with Claude**. When prompted, describe the subagent:

~~57 * Describe your subagent in detail and when it should be used~~90

~~58 * Select the tools you want to grant access to (or leave blank to inherit all tools)~~91 ```

~~59 * The interface shows all available tools, making selection easy~~92 A code improvement agent that scans files and suggests improvements

~~60 * If you're generating with Claude, you can also edit the system prompt in your own editor by pressing `e`~~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.

61 </Step>102 </Step>

62 103

~~63 <Step title="Save and use">~~104 <Step title="Select model">

~~64 Your subagent is now available! Claude will use it automatically when appropriate, or you can invoke it explicitly:~~105 Choose which model the subagent uses. For this example agent, select **Sonnet**, which balances capability and speed for analyzing code patterns.

106 </Step>

107

108 <Step title="Choose a color">

109 Pick a background color for the subagent. This helps you identify which subagent is running in the UI.

110 </Step>

111

112 <Step title="Save and try it out">

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

117**Use case**: This approach is useful for:

118 170

119* Quick testing of subagent configurations171**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.

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 172

124For detailed information about the JSON format and all available options, see the [CLI reference documentation](/en/cli-reference#agents-flag-format).173### Write subagent files

125 174

126### File format175Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown:

127 176

128Each subagent is defined in a Markdown file with this structure:177<Note>

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.

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

136permissionMode: default # Optional - permission mode for the subagent

137skills: skill1, skill2 # Optional - skills to auto-load

138---187---

139 188

140Your subagent's system prompt goes here. This can be multiple paragraphs189You are a code reviewer. When invoked, analyze the code and provide

141and should clearly define the subagent's role, capabilities, and approach190specific, actionable feedback on quality, security, and best practices.

142to solving problems.

~~143~~

144Include specific instructions, best practices, and any constraints

145the subagent should follow.

146```191```

147 192

148#### 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.

149 198

151| :--------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |200| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

152| `name` | Yes | Unique identifier using lowercase letters and hyphens |201| `name` | Yes | Unique identifier using lowercase letters and hyphens |

153| `description` | Yes | Natural language description of the subagent's purpose |202| `description` | Yes | When Claude should delegate to this subagent |

154| `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 |

155| `model` | No | Model to use for this subagent. Can be a model alias (`sonnet`, `opus`, `haiku`) or `'inherit'` to use the main conversation's model. If omitted, defaults to the [configured subagent model](/en/model-config) |204| `disallowedTools` | No | Tools to deny, removed from inherited or specified list |

156| `permissionMode` | No | Permission mode for the subagent. Valid values: `default`, `acceptEdits`, `bypassPermissions`, `plan`, `ignore`. Controls how the subagent handles permission requests |205| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, or `inherit`. Defaults to `inherit` |

157| `skills` | No | Comma-separated list of skill names to auto-load when the subagent starts. Skills are loaded into the subagent's context automatically |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 |

158 209

159### Model selection210### Choose a model

160 211

161The `model` field allows you to control which [AI model](/en/model-config) the subagent uses:212The `model` field controls which [AI model](/en/model-config) the subagent uses:

162 213

163* **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`

164* **`'inherit'`**: Use the same model as the main conversation (useful for consistency)215* **inherit**: Use the same model as the main conversation

165* **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.

166 272

167<Note>273<Note>

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

169</Note>275</Note>

170 276

171### Available tools277#### Conditional rules with hooks

172 278

173Subagents can be granted access to any of Claude Code's internal tools. See the [tools documentation](/en/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.

174 280

175<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:

176 **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

177</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```

296

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:

298

299```bash theme={null}

300#!/bin/bash

301# ./scripts/validate-readonly-query.sh

178 302

179You have two options for configuring tools:303INPUT=$(cat)

304COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

180 305

181* **Omit the `tools` field** to inherit all tools from the main thread (default), including MCP tools306# Block SQL write operations (case-insensitive)

308 echo "Blocked: Only SELECT queries are allowed" >&2

309 exit 2

310fi

183 311

184**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.312exit 0

313```

185 314

186## Managing subagents315See [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.

187 316

188### Using the /agents command (Recommended)317#### Disable specific subagents

189 318

190The `/agents` command provides a comprehensive interface for subagent management: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.

191 320

321```json theme={null}

322{

323 "permissions": {

324 "deny": ["Task(Explore)", "Task(my-custom-agent)"]

325 }

326}

192```327```

193/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)"

194```333```

195 334

196This opens an interactive menu where you can:335See [IAM documentation](/en/iam#tool-specific-permission-rules) for more details on permission rules.

197 336

198* View all available subagents (built-in, user, and project)337### Define hooks for subagents

199* Create new subagents with guided setup

200* Edit existing custom subagents, including their tool access

201* Delete custom subagents

202* See which subagents are active when duplicates exist

203* **Easily manage tool permissions** with a complete list of available tools

204 338

205### Direct file management339Subagents can define [hooks](/en/hooks) that run during the subagent's lifecycle. There are two ways to configure hooks:

206 340

207You 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

208 343

209```bash theme={null}344#### Hooks in subagent frontmatter

210# Create a project subagent345

211mkdir -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.

212echo '---

213name: test-runner

214description: Use proactively to run tests and fix failures

215 347

216You 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.md348| Event | Matcher input | When it fires |

349| :------------ | :------------ | :------------------------------ |

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 |

217 353

218# Create a user subagent354This example validates Bash commands with the `PreToolUse` hook and runs a linter after file edits with `PostToolUse`:

219mkdir -p ~/.claude/agents355

220# ... create subagent file356```yaml theme={null}

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

221```372```

222 373

223## Using subagents effectively374`Stop` hooks in frontmatter are automatically converted to `SubagentStop` events.

224 375

225### Automatic delegation376#### Project-level hooks for subagent events

226 377

227Claude Code proactively delegates tasks based on:378Configure 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.

228 379

229* The task description in your request380| Event | Matcher input | When it fires |

230* The `description` field in subagent configurations381| :-------------- | :-------------- | :------------------------------- |

231* Current context and available tools382| `SubagentStart` | Agent type name | When a subagent begins execution |

383| `SubagentStop` | Agent type name | When a subagent completes |

232 384

233<Tip>385This example runs setup and cleanup scripts only when the `db-agent` subagent starts and stops:

234 To encourage more proactive subagent use, include phrases like "use PROACTIVELY" or "MUST BE USED" in your `description` field.386

235</Tip>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}

408```

409

410See [Hooks](/en/hooks) for the complete hook configuration format.

411

412## Work with subagents

413

414### Understand automatic delegation

236 415

237### Explicit invocation416Claude 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.

238 417

239Request a specific subagent by mentioning it in your command:418You can also request a specific subagent explicitly:

240 419

241```420```

242> Use the test-runner subagent to fix failing tests421Use the test-runner subagent to fix failing tests

243> Have the code-reviewer subagent look at my recent changes422Have the code-reviewer subagent look at my recent changes

244> Ask the debugger subagent to investigate this error

245```423```

246 424

247## Built-in subagents425### Run subagents in foreground or background

248 426

249Claude Code includes built-in subagents that are available out of the box:427Subagents can run in the foreground (blocking) or background (concurrent):

250 428

251### General-purpose subagent429* **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.

252 431

253The general-purpose subagent is a capable agent for complex, multi-step tasks that require both exploration and action. Unlike the Explore subagent, it can modify files and execute a wider range of operations.432If a background subagent fails due to missing permissions, you can [resume it](#resume-subagents) in the foreground to retry with interactive prompts.

254 433

255**Key characteristics:**434Claude decides whether to run subagents in the foreground or background based on the task. You can also:

256 435

257* **Model**: Uses Sonnet for more capable reasoning436* Ask Claude to "run this in the background"

258* **Tools**: Has access to all tools437* Press **Ctrl+B** to background a running task

259* **Mode**: Can read and write files, execute commands, make changes

260* **Purpose**: Complex research tasks, multi-step operations, code modifications

261 438

262**When Claude uses it:**439To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/en/settings#environment-variables).

263 440

264Claude delegates to the general-purpose subagent when:441### Common patterns

265 442

266* The task requires both exploration and modification443#### Isolate high-volume operations

267* Complex reasoning is needed to interpret search results

268* Multiple strategies may be needed if initial searches fail

269* The task has multiple steps that depend on each other

270 444

271**Example scenario:**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.

272 446

273```447```

274User: Find all the places where we handle authentication and update them to use the new token format448Use a subagent to run the test suite and report only the failing tests with their error messages

~~275~~

276Claude: [Invokes general-purpose subagent]

277[Agent searches for auth-related code across codebase]

278[Agent reads and analyzes multiple files]

279[Agent makes necessary edits]

280[Returns detailed writeup of changes made]

281```449```

282 450

283### Plan subagent451#### Run parallel research

284 452

285The Plan subagent is a specialized built-in agent designed for use during plan mode. When Claude is operating in plan mode (non-execution mode), it uses the Plan subagent to conduct research and gather information about your codebase before presenting a plan.453For independent investigations, spawn multiple subagents to work simultaneously:

286 454

287**Key characteristics:**455```

456Research the authentication, database, and API modules in parallel using separate subagents

457```

288 458

289* **Model**: Uses Sonnet for more capable analysis459Each subagent explores its area independently, then Claude synthesizes the findings. This works best when the research paths don't depend on each other.

290* **Tools**: Has access to Read, Glob, Grep, and Bash tools for codebase exploration

291* **Purpose**: Searches files, analyzes code structure, and gathers context

292* **Automatic invocation**: Claude automatically uses this agent when in plan mode and needs to research the codebase

293 460

294**How it works:**461<Warning>

295When you're in plan mode and Claude needs to understand your codebase to create a plan, it delegates research tasks to the Plan subagent. This prevents infinite nesting of agents (subagents cannot spawn other subagents) while still allowing Claude to gather the necessary context.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>

296 464

297**Example scenario:**465#### Chain subagents

298 466

299```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.

300User: [In plan mode] Help me refactor the authentication module

301 468

302Claude: Let me research your authentication implementation first...469```

303[Internally invokes Plan subagent to explore auth-related files]470Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

304[Plan subagent searches codebase and returns findings]

305Claude: Based on my research, here's my proposed plan...

306```471```

307 472

308<Tip>473### Choose between subagents and main conversation

309 The Plan subagent is only used in plan mode. In normal execution mode, Claude uses the general-purpose agent or other custom subagents you've created.474

310</Tip>475Use the **main conversation** when:

311 476

312### Explore subagent477* 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

313 481

314The Explore subagent is a fast, lightweight agent optimized for searching and analyzing codebases. It operates in strict read-only mode and is designed for rapid file discovery and code exploration.482Use **subagents** when:

315 483

316**Key characteristics:**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

317 487

318* **Model**: Uses Haiku for fast, low-latency searches488Consider [Skills](/en/skills) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.

319* **Mode**: Strictly read-only - cannot create, modify, or delete files

320* **Tools available**:

321 * Glob - File pattern matching

322 * Grep - Content searching with regex

323 * Read - Reading file contents

324 * Bash - Read-only commands only (ls, git status, git log, git diff, find, cat, head, tail)

325 489

326**When Claude uses it:**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>

327 493

328Claude will delegate to the Explore subagent when it needs to search or understand a codebase but doesn't need to make changes. This is more efficient than the main agent running multiple search commands directly, as content found during the exploration process doesn't bloat the main conversation.494### Manage subagent context

329 495

330**Thoroughness levels:**496#### Resume subagents

331 497

332When invoking the Explore subagent, Claude specifies a thoroughness level: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.

333 499

334* **Quick** - Basic searches, fastest results. Good for simple lookups.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.

335* **Medium** - Moderate exploration. Balances speed and thoroughness.

336* **Very thorough** - Comprehensive analysis across multiple locations and naming conventions. Used when the target might be in unexpected places.

337 501

338**Example scenarios:**502When a subagent completes, Claude receives its agent ID. To resume a subagent, ask Claude to continue the previous work:

339 503

340```504```

341User: Where are errors from the client handled?505Use the code-reviewer subagent to review the authentication module

506[Agent completes]

342 507

343Claude: [Invokes Explore subagent with "medium" thoroughness]508Continue that code review and now analyze the authorization logic

344[Explore uses Grep to search for error handling patterns]509[Claude resumes the subagent with full context from previous conversation]

345[Explore uses Read to examine promising files]

346[Returns findings with absolute file paths]

347Claude: Client errors are handled in src/services/process.ts:712...

348```510```

349 511

350```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`.

351User: What's the codebase structure?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).

352 519

353Claude: [Invokes Explore subagent with "quick" thoroughness]520#### Auto-compaction

354[Explore uses Glob and ls to map directory structure]521

355[Returns overview of key directories and their purposes]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}

356```535```

357 536

537The `preTokens` value shows how many tokens were used before compaction occurred.

538

358## Example subagents539## Example subagents

359 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

360### Code reviewer552### Code reviewer

361 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

362```markdown theme={null}556```markdown theme={null}

363---557---

364name: code-reviewer558name: code-reviewer

3763. Begin review immediately5693. Begin review immediately

377 570

378Review checklist:571Review checklist:

379- Code is simple and readable572- Code is clear and readable

380- Functions and variables are well-named573- Functions and variables are well-named

381- No duplicated code574- No duplicated code

382- Proper error handling575- Proper error handling

395 588

396### Debugger589### Debugger

397 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

398```markdown theme={null}593```markdown theme={null}

399---594---

400name: debugger595name: debugger

425- Testing approach620- Testing approach

426- Prevention recommendations621- Prevention recommendations

427 622

428Focus on fixing the underlying issue, not just symptoms.623Focus on fixing the underlying issue, not the symptoms.

429```624```

430 625

431### Data scientist626### Data scientist

432 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

433```markdown theme={null}630```markdown theme={null}

434---631---

435name: data-scientist632name: data-scientist

463Always ensure queries are efficient and cost-effective.660Always ensure queries are efficient and cost-effective.

464```661```

465 662

466## Best practices663### Database query validator

~~467~~

468* **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.

~~469~~

470* **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.

~~471~~

472* **Write detailed prompts**: Include specific instructions, examples, and constraints in your system prompts. The more guidance you provide, the better the subagent will perform.

~~473~~

474* **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.

475 664

476* **Version control**: Check project subagents into version control so your team can benefit from and improve them collaboratively.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.

477 666

478## Advanced usage667```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---

479 679

480### Chaining subagents680You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

481 681

482For complex workflows, you can chain multiple subagents: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

483 686

484```687You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

485> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

486```688```

487 689

488### Dynamic subagent selection690Claude 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.

489 691

490Claude Code intelligently selects subagents based on context. Make your `description` fields specific and action-oriented for best results.692Create the validation script anywhere in your project. The path must match the `command` field in your hook configuration:

491 693

492### Resumable subagents694```bash theme={null}

~~493~~ 695#!/bin/bash

494Subagents can be resumed to continue previous conversations, which is particularly useful for long-running research or analysis tasks that need to be continued across multiple invocations.696# Blocks SQL write operations, allows SELECT queries

495 697

496**How it works:**698# Read JSON input from stdin

699INPUT=$(cat)

497 700

498* Each subagent execution is assigned a unique `agentId`701# Extract the command field from tool_input using jq

499* The agent's conversation is stored in a separate transcript file: `agent-{agentId}.jsonl`702COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

500* You can resume a previous agent by providing its `agentId` via the `resume` parameter

501* When resumed, the agent continues with full context from its previous conversation

502 703

503**Example workflow:**704if [ -z "$COMMAND" ]; then

705 exit 0

706fi

504 707

505Initial invocation:708# Block write operations (case-insensitive)

710 echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2

711 exit 2

712fi

506 713

714exit 0

507```715```

508> Use the code-analyzer agent to start reviewing the authentication module

509 716

510[Agent completes initial analysis and returns agentId: "abc123"]717Make the script executable:

511```

512 718

513Resume the agent:719```bash theme={null}

~~514~~ 720chmod +x ./scripts/validate-readonly-query.sh

515```

516> Resume agent abc123 and now analyze the authorization logic as well

~~517~~

518[Agent continues with full context from previous conversation]

519```721```

520 722

521**Use cases:**723The 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.

~~522~~

523* **Long-running research**: Break down large codebase analysis into multiple sessions

524* **Iterative refinement**: Continue refining a subagent's work without losing context

525* **Multi-step workflows**: Have a subagent work on related tasks sequentially while maintaining context

~~526~~

527**Technical details:**

528 724

529* Agent transcripts are stored in your project directory725## Next steps

530* Recording is disabled during resume to avoid duplicating messages

531* Both synchronous and asynchronous agents can be resumed

532* The `resume` parameter accepts the agent ID from a previous execution

533 726

534**Programmatic usage:**727Now that you understand subagents, explore these related features:

535 728

536If you're using the Agent SDK or interacting with the AgentTool directly, you can pass the `resume` parameter:729* [Distribute subagents with plugins](/en/plugins) to share subagents across teams or projects

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

537 732

538```typescript theme={null}

539{

540 "description": "Continue analysis",

541 "prompt": "Now examine the error handling patterns",

542 "subagent_type": "code-analyzer",

543 "resume": "abc123" // Agent ID from previous execution

544}

545```

546 733

547<Tip>734---

548 Keep track of agent IDs for tasks you may want to resume later. Claude Code displays the agent ID when a subagent completes its work.

549</Tip>

~~550~~

551## Performance considerations

~~552~~

553* **Context efficiency**: Agents help preserve main context, enabling longer overall sessions

554* **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.

~~555~~

556## Related documentation

557 735

558* [Plugins](/en/plugins) - Extend Claude Code with custom agents through plugins736> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

559* [Slash commands](/en/slash-commands) - Learn about other built-in commands

560* [Settings](/en/settings) - Configure Claude Code behavior

561* [Hooks](/en/hooks) - Automate workflows with event handlers

terminal-config.md +22 −6

Details

10 10

11### Line breaks11### Line breaks

12 12

~~13You have several options for entering linebreaks into Claude Code:~~13You have several options for entering line breaks into Claude Code:

14 14

15* **Quick escape**: Type `\` followed by Enter to create a newline15* **Quick escape**: Type `\` followed by Enter to create a newline

~~16* **Keyboard shortcut**: Set up a keybinding to insert a 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

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 +150 −151

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>

16 <th>Microsoft Foundry</th>27 <th>Microsoft Foundry</th>

18 </thead>29 </thead>

19 30

20 <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>

21 <tr>50 <tr>

22 <td>Regions</td>51 <td>Regions</td>

23 <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>

24 <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>

25 <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>

26 <td>Multiple Azure [regions](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/)</td>56 <td>Multiple Azure [regions](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/)</td>

32 <td>Enabled by default</td>62 <td>Enabled by default</td>

33 <td>Enabled by default</td>63 <td>Enabled by default</td>

34 <td>Enabled by default</td>64 <td>Enabled by default</td>

65 <td>Enabled by default</td>

35 </tr>66 </tr>

36 67

37 <tr>68 <tr>

38 <td>Authentication</td>69 <td>Authentication</td>

70 <td>Claude.ai SSO or email</td>

39 <td>API key</td>71 <td>API key</td>

40 <td>API key or AWS credentials</td>72 <td>API key or AWS credentials</td>

41 <td>GCP credentials</td>73 <td>GCP credentials</td>

44 76

45 <tr>77 <tr>

46 <td>Cost tracking</td>78 <td>Cost tracking</td>

~~47 <td>Dashboard</td>~~79 <td>Usage dashboard</td>

80 <td>Usage dashboard</td>

48 <td>AWS Cost Explorer</td>81 <td>AWS Cost Explorer</td>

49 <td>GCP Billing</td>82 <td>GCP Billing</td>

50 <td>Azure Cost Management</td>83 <td>Azure Cost Management</td>

51 </tr>84 </tr>

52 85

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>

93 </tr>

53 <tr>95 <tr>

54 <td>Enterprise features</td>96 <td>Enterprise features</td>

~~55 <td>Teams, usage monitoring</td>~~97 <td>Team management, SSO, usage monitoring</td>

98 <td>None</td>

56 <td>IAM policies, CloudTrail</td>99 <td>IAM policies, CloudTrail</td>

57 <td>IAM roles, Cloud Audit Logs</td>100 <td>IAM roles, Cloud Audit Logs</td>

58 <td>RBAC policies, Azure Monitor</td>101 <td>RBAC policies, Azure Monitor</td>

60 </tbody>103 </tbody>

61</table>104</table>

62 105

~~63## Cloud providers~~106Select a deployment option to view setup instructions:

~~65<CardGroup cols={3}>~~

~~66 <Card title="Amazon Bedrock" icon="aws" href="/en/amazon-bedrock">~~

~~67 Use Claude models through AWS infrastructure with API key or IAM-based authentication and AWS-native monitoring~~

~~68 </Card>~~

~~70 <Card title="Google Vertex AI" icon="google" href="/en/google-vertex-ai">~~

~~71 Access Claude models via Google Cloud Platform with enterprise-grade security and compliance~~

~~72 </Card>~~

~~74 <Card title="Microsoft Foundry" icon="microsoft" href="/en/microsoft-foundry">~~

~~75 Access Claude through Azure with API key or Microsoft Entra ID authentication and Azure billing~~

~~76 </Card>~~

~~77</CardGroup>~~

~~79## Corporate infrastructure~~

~~81<CardGroup cols={2}>~~

~~82 <Card title="Enterprise Network" icon="shield" href="/en/network-config">~~

~~83 Configure Claude Code to work with your organization's proxy servers and SSL/TLS requirements~~

~~84 </Card>~~

~~86 <Card title="LLM Gateway" icon="server" href="/en/llm-gateway">~~

~~87 Deploy centralized model access with usage tracking, budgeting, and audit logging~~

~~88 </Card>~~

~~89</CardGroup>~~

90 107

~~91## Configuration overview~~108* [Claude for Teams or Enterprise](/en/iam#claude-for-teams-or-enterprise-recommended)

109* [Anthropic Console](/en/iam#claude-console-authentication)

110* [Amazon Bedrock](/en/amazon-bedrock)

111* [Google Vertex AI](/en/google-vertex-ai)

112* [Microsoft Foundry](/en/microsoft-foundry)

92 113

~~93Claude Code supports flexible configuration options that allow you to combine different providers and infrastructure:~~114## Configure proxies and gateways

94 115

~~95<Note>~~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:

~~96 Understand the difference between:~~

97 117

~~98 * **Corporate proxy**: An HTTP/HTTPS proxy for routing traffic (set via `HTTPS_PROXY` or `HTTP_PROXY`)~~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).

~~99 * **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`)~~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).

100 120

101 Both configurations can be used in tandem.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.

102</Note>

103 122

104### Using Bedrock with corporate proxy123### Amazon Bedrock

105 124

106Route Bedrock traffic through a corporate HTTP/HTTPS proxy:125<Tabs>

126 <Tab title="Corporate proxy">

127 Route Bedrock traffic through your corporate proxy by setting the following [environment variables](/en/settings#environment-variables):

107 128

108```bash theme={null}129 ```bash theme={null}

109# Enable Bedrock130 # Enable Bedrock

110export CLAUDE_CODE_USE_BEDROCK=1131 export CLAUDE_CODE_USE_BEDROCK=1

111export AWS_REGION=us-east-1132 export AWS_REGION=us-east-1

112 133

113# Configure corporate proxy134 # Configure corporate proxy

114export HTTPS_PROXY='https://proxy.example.com:8080'135 export HTTPS_PROXY='https://proxy.example.com:8080'

115```136 ```

137 </Tab>

116 138

117### Using Bedrock with LLM Gateway139 <Tab title="LLM Gateway">

140 Route Bedrock traffic through your LLM gateway by setting the following [environment variables](/en/settings#environment-variables):

118 141

119Use a gateway service that provides Bedrock-compatible endpoints:142 ```bash theme={null}

143 # Enable Bedrock

144 export CLAUDE_CODE_USE_BEDROCK=1

120 145

121```bash theme={null}146 # Configure LLM gateway

122# Enable Bedrock147 export ANTHROPIC_BEDROCK_BASE_URL='https://your-llm-gateway.com/bedrock'

123export CLAUDE_CODE_USE_BEDROCK=1148 export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 # If gateway handles AWS auth

149 ```

150 </Tab>

151</Tabs>

124 152

125# Configure LLM gateway153### Microsoft Foundry

126export ANTHROPIC_BEDROCK_BASE_URL='https://your-llm-gateway.com/bedrock'

127export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 # If gateway handles AWS auth

128```

129 154

130### Using Foundry with corporate proxy155<Tabs>

156 <Tab title="Corporate proxy">

157 Route Foundry traffic through your corporate proxy by setting the following [environment variables](/en/settings#environment-variables):

131 158

132Route Azure traffic through a corporate HTTP/HTTPS proxy: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

133 164

134```bash theme={null}165 # Configure corporate proxy

135# Enable Microsoft Foundry166 export HTTPS_PROXY='https://proxy.example.com:8080'

136export CLAUDE_CODE_USE_FOUNDRY=1167 ```

137export ANTHROPIC_FOUNDRY_RESOURCE=your-resource168 </Tab>

138export ANTHROPIC_FOUNDRY_API_KEY=your-api-key # Or omit for Entra ID auth

139 169

140# Configure corporate proxy170 <Tab title="LLM Gateway">

141export HTTPS_PROXY='https://proxy.example.com:8080'171 Route Foundry traffic through your LLM gateway by setting the following [environment variables](/en/settings#environment-variables):

142```

143 172

144### Using Foundry with LLM Gateway173 ```bash theme={null}

174 # Enable Microsoft Foundry

175 export CLAUDE_CODE_USE_FOUNDRY=1

145 176

146Use a gateway service that provides Azure-compatible endpoints: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>

147 183

148```bash theme={null}184### Google Vertex AI

149# Enable Microsoft Foundry

150export CLAUDE_CODE_USE_FOUNDRY=1

151 185

152# Configure LLM gateway186<Tabs>

153export ANTHROPIC_FOUNDRY_BASE_URL='https://your-llm-gateway.com'187 <Tab title="Corporate proxy">

154export CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1 # If gateway handles Azure auth188 Route Vertex AI traffic through your corporate proxy by setting the following [environment variables](/en/settings#environment-variables):

155```

156 189

157### Using Vertex AI with corporate proxy190 ```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

158 195

159Route Vertex AI traffic through a corporate HTTP/HTTPS proxy:196 # Configure corporate proxy

197 export HTTPS_PROXY='https://proxy.example.com:8080'

198 ```

199 </Tab>

160 200

161```bash theme={null}201 <Tab title="LLM Gateway">

162# Enable Vertex202 Route Vertex AI traffic through your LLM gateway by setting the following [environment variables](/en/settings#environment-variables):

163export CLAUDE_CODE_USE_VERTEX=1

164export CLOUD_ML_REGION=us-east5

165export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

166 203

167# Configure corporate proxy204 ```bash theme={null}

168export HTTPS_PROXY='https://proxy.example.com:8080'205 # Enable Vertex

169```206 export CLAUDE_CODE_USE_VERTEX=1

170 207

171### Using Vertex AI with LLM Gateway208 # 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>

172 214

173Combine Google Vertex AI models with an LLM gateway for centralized management:215<Tip>

~~174~~ 216 Use `/status` in Claude Code to verify your proxy and gateway configuration is applied correctly.

175```bash theme={null}217</Tip>

176# Enable Vertex

177export CLAUDE_CODE_USE_VERTEX=1

~~178~~

179# Configure LLM gateway

180export ANTHROPIC_VERTEX_BASE_URL='https://your-llm-gateway.com/vertex'

181export CLAUDE_CODE_SKIP_VERTEX_AUTH=1 # If gateway handles GCP auth

182```

~~183~~

184### Authentication configuration

~~185~~

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

~~187~~

188## Choosing the right deployment configuration

~~189~~

190Consider these factors when selecting your deployment approach:

~~191~~

192### Direct provider access

~~193~~

194Best for organizations that:

~~195~~

196* Want the simplest setup

197* Have existing AWS or GCP infrastructure

198* Need provider-native monitoring and compliance

~~199~~

200### Corporate proxy

~~201~~

202Best for organizations that:

~~203~~

204* Have existing corporate proxy requirements

205* Need traffic monitoring and compliance

206* Must route all traffic through specific network paths

~~207~~

208### LLM Gateway

~~209~~

210Best for organizations that:

~~211~~

212* Need usage tracking across teams

213* Want to dynamically switch between models

214* Require custom rate limiting or budgets

215* Need centralized authentication management

~~216~~

217## Debugging

~~218~~

219When debugging your deployment:

~~220~~

221* Use the `claude /status` [slash command](/en/slash-commands). This command provides observability into any applied authentication, proxy, and URL settings.

222* Set environment variable `export ANTHROPIC_LOG=debug` to log requests.

223 218

224## Best practices for organizations219## Best practices for organizations

225 220

226### 1. Invest in documentation and memory221### Invest in documentation and memory

227 222

228We 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:

229 224

230* **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

231* **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

232 227

233 [Learn more](/en/memory).228Learn more in [Memory and CLAUDE.md files](/en/memory).

234 229

235### 2. Simplify deployment230### Simplify deployment

236 231

237If 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.

238 233

239### 3. Start with guided usage234### Start with guided usage

240 235

241Encourage 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.

242 237

243### 4. Configure security policies238### Configure security policies

244 239

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

246 241

247### 5. Leverage MCP for integrations242### Leverage MCP for integrations

248 243

249MCP is a great way to give Claude Code more information, such as connecting to ticket management systems or error logs. We recommend that one central team configures MCP servers and checks a `.mcp.json` configuration into the codebase so that all users benefit. [Learn more](/en/mcp).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).

250 245

251At Anthropic, we trust Claude Code to power development across every Anthropic codebase. We hope you enjoy using Claude Code as much as we do!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.

252 247

253## Next steps248## Next steps

254 249

255* [Set up Amazon Bedrock](/en/amazon-bedrock) for AWS-native deployment250Once you've chosen a deployment option and configured access for your team:

256* [Configure Google Vertex AI](/en/google-vertex-ai) for GCP deployment251

257* [Set up Microsoft Foundry](/en/microsoft-foundry) for Azure deployment2521. **Roll out to your team**: Share installation instructions and have team members [install Claude Code](/en/setup) and authenticate with their credentials.

258* [Configure Enterprise Network](/en/network-config) for network requirements2532. **Set up shared configuration**: Create a [CLAUDE.md file](/en/memory) in your repositories to help Claude Code understand your codebase and coding standards.

259* [Deploy LLM Gateway](/en/llm-gateway) for enterprise management2543. **Configure permissions**: Review [security settings](/en/security) to define what Claude Code can and cannot do in your environment.

260* [Settings](/en/settings) for configuration options and environment variables255

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 +100 −31

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

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)

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/vs-code#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/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

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/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 +295 −91

Details

~~1# Visual Studio Code~~1# Use Claude Code in VS Code

2 2

~~3> Use Claude Code with Visual Studio Code through our native extension or CLI integration~~3> Install and configure the Claude Code extension for VS Code. Get AI coding assistance with inline diffs, @-mentions, plan review, and keyboard shortcuts.

4 4

5<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=300652d5678c63905e6b0ea9e50835f8" alt="Claude Code VS Code Extension Interface" data-og-width="2500" width="2500" data-og-height="1155" height="1155" data-path="images/vs-code-extension-interface.jpg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=280&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=87630c671517a3d52e9aee627041696e 280w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=560&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=716b093879204beec8d952649ef75292 560w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=840&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=c1525d1a01513acd9d83d8b5a8fe2fc8 840w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1100&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=1d90021d58bbb51f871efec13af955c3 1100w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1650&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=7babdd25440099886f193cfa99af88ae 1650w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=2500&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=08c92eedfb56fe61a61e480fb63784b6 2500w" />5<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=300652d5678c63905e6b0ea9e50835f8" alt="VS Code editor with the Claude Code extension panel open on the right side, showing a conversation with Claude" data-og-width="2500" width="2500" data-og-height="1155" height="1155" data-path="images/vs-code-extension-interface.jpg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=280&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=87630c671517a3d52e9aee627041696e 280w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=560&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=716b093879204beec8d952649ef75292 560w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=840&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=c1525d1a01513acd9d83d8b5a8fe2fc8 840w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1100&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=1d90021d58bbb51f871efec13af955c3 1100w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1650&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=7babdd25440099886f193cfa99af88ae 1650w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=2500&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=08c92eedfb56fe61a61e480fb63784b6 2500w" />

6 6

~~7## VS Code Extension (Beta)~~7The VS Code extension provides a native graphical interface for Claude Code, integrated directly into your IDE. This is the recommended way to use Claude Code in VS Code.

8 8

9The VS Code extension, available in beta, lets you see Claude's changes in real-time through a native graphical interface integrated directly into your IDE. The VS Code extension makes it easier to access and interact with Claude Code for users who prefer a visual interface over the terminal.9With the extension, you can review and edit Claude's plans before accepting them, auto-accept edits as they're made, @-mention files with specific line ranges from your selection, access conversation history, and open multiple conversations in separate tabs or windows.

10 10

~~11### Features~~11## Prerequisites

12 12

~~13The VS Code extension provides:~~13* VS Code 1.98.0 or higher

14* An Anthropic account (you'll sign in when you first open the extension). If you're using a third-party provider like Amazon Bedrock or Google Vertex AI, see [Use third-party providers](#use-third-party-providers) instead.

14 15

~~15* **Native IDE experience**: Dedicated Claude Code sidebar panel accessed via the Spark icon~~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* **Extended thinking**: Toggle extended thinking on/off using the Extended Thinking button in the bottom-right corner of the prompt input~~

~~19* **File management**: @-mention files or attach files and images using the system file picker~~

~~20* **MCP server usage**: Use Model Context Protocol servers configured through the CLI~~

~~21* **Conversation history**: Easy access to past conversations~~

~~22* **Multiple sessions**: Run multiple Claude Code sessions simultaneously~~

~~23* **Keyboard shortcuts**: Support for most shortcuts from the CLI~~

~~24* **Slash commands**: Access most CLI slash commands directly in the extension~~

25 19

~~26### Requirements~~20## Install the extension

27 21

~~28* 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)

29 26

~~30### 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**.

31 28

~~32Download 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>

33 30

~~34### How It Works~~31## Get started

35 32

36Once 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:

37 34

~~381. Click the Spark icon in your editor's sidebar to open the Claude Code panel~~35<Steps>

~~392. Prompt Claude Code in the same way you would in the terminal~~36 <Step title="Open the Claude Code panel">

~~403. 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" />

~~414. Review and accept edits directly in the interface~~38

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

43 137

~~44### Using Third-Party Providers~~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>

45 141

46The VS Code extension supports using Claude Code with third-party providers like Amazon Bedrock, Microsoft Foundry, 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: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 |

47 153

~~481. Open VS Code settings~~154## Configure settings

~~492. Search for "Claude Code: Environment Variables"~~

~~503. Add the required environment variables~~

51 155

~~52#### Environment Variables~~156The extension has two types of settings:

53 157

~~54| Variable | Description | Required | Example |~~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.

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

68 160

~~69For detailed setup instructions and additional configuration options, see:~~161### Extension settings

70 162

~~71* [Claude Code on Amazon Bedrock](/en/amazon-bedrock)~~163| Setting | Default | Description |

~~72* [Claude Code on Microsoft Foundry](/en/microsoft-foundry)~~164| --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------- |

~~73* [Claude Code on Google Vertex AI](/en/google-vertex-ai)~~165| `selectedModel` | `default` | Model for new conversations. Change per-session with `/model`. |

166| `useTerminal` | `false` | Launch Claude in terminal mode instead of graphical panel |

167| `initialPermissionMode` | `default` | Controls approval prompts: `default` (ask each time), `plan`, `acceptEdits`, or `bypassPermissions` |

168| `preferredLocation` | `panel` | Where Claude opens: `sidebar` (right) or `panel` (new tab) |

169| `autosave` | `true` | Auto-save files before Claude reads or writes them |

170| `useCtrlEnterToSend` | `false` | Use Ctrl/Cmd+Enter instead of Enter to send prompts |

171| `enableNewConversationShortcut` | `true` | Enable Cmd/Ctrl+N to start a new conversation |

172| `hideOnboarding` | `false` | Hide the onboarding checklist (graduation cap icon) |

173| `respectGitIgnore` | `true` | Exclude .gitignore patterns from file searches |

174| `environmentVariables` | `[]` | Set environment variables for the Claude process. Use Claude Code settings instead for shared config. |

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 |

74 178

~~75### Not Yet Implemented~~179## VS Code extension vs. Claude Code CLI

76 180

~~77The following features are not yet available in the VS Code extension:~~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.

78 182

79* **MCP server and Plugin configuration UI**: Type `/mcp` to open the terminal-based MCP server configuration, or `/plugin` for Plugin configuration. Once configured, MCP servers and Plugins will work in the extension. You can also [configure MCP servers through the CLI](/en/mcp) first, then the extension will use them.183| Feature | CLI | VS Code Extension |

~~80* **Subagents configuration**: Configure [subagents through the CLI](/en/sub-agents) to use them in VS Code~~184| ------------------- | --------------------------------------------- | ---------------------------------------- |

~~81* **Checkpoints**: Save and restore conversation state at specific points~~185| Commands and skills | [All](/en/interactive-mode#built-in-commands) | Subset (type `/` to see available) |

~~82* **Conversation rewinding**: The `/rewind` command is coming soon~~186| MCP server config | Yes | No (configure via CLI, use in extension) |

~~83* **Advanced shortcuts**:~~187| Checkpoints | Yes | Coming soon |

~~84 * `#` shortcut to add to memory (not supported)~~188| `!` bash shortcut | Yes | No |

~~85 * `!` shortcut to run bash commands directly (not supported)~~189| Tab completion | Yes | No |

~~86* **Tab completion**: File path completion with tab key~~

87* **Model selection UI for older models**: To use older model versions like `claude-sonnet-4-20250514`, open VS Code settings for Claude Code (the `/General Config` command) and insert the model string directly into the 'Selected Model' field

88 190

~~89We are working on adding these features in future updates.~~191### Run CLI in VS Code

90 192

~~91## Security Considerations~~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.

92 194

93When 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.195If using an external terminal, run `/ide` inside Claude Code to connect it to VS Code.

94 196

~~95When running in VS Code, consider:~~197### Switch between extension and CLI

96 198

~~97* Enabling [VS Code Restricted Mode](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode) for untrusted workspaces~~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.

~~98* Using manual approval mode for edits~~

~~99* Taking extra care to ensure Claude is only used with trusted prompts~~

100 200

101## Legacy CLI Integration201### Include terminal output in prompts

102 202

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

104 204

105The 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.205### Monitor background processes

106 206

107Both the extension and CLI integration work with Visual Studio Code, Cursor, Windsurf, and VSCodium.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.

108 208

109## Troubleshooting209### Connect to external tools with MCP

110 210

111### Extension Not Installing211MCP (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.

112 212

113* Ensure you have a compatible version of VS Code (1.85.0 or later)213To add an MCP server, open the integrated terminal (`` Ctrl+` `` or `` Cmd+` ``) and run:

214

215```bash theme={null}

216claude mcp add --transport http github https://api.githubcopilot.com/mcp/

217```

218

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)

114* Check that VS Code has permission to install extensions290* Check that VS Code has permission to install extensions

115* 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".

116 304

117### Claude Code Never Responds305### Claude Code never responds

118 306

119If Claude Code is not responding to your prompts:307If Claude Code isn't responding to your prompts:

120 308

1211. **Check your internet connection**: Ensure you have a stable internet connection3091. **Check your internet connection**: Ensure you have a stable internet connection

1222. **Start a new conversation**: Try starting a fresh conversation to see if the issue persists3102. **Start a new conversation**: Try starting a fresh conversation to see if the issue persists

1233. **Try the CLI**: Run `claude` from the terminal to see if you get more detailed error messages3113. **Try the CLI**: Run `claude` from the terminal to see if you get more detailed error messages

1244. **File a bug report**: If the problem continues, [file an issue on GitHub](https://github.com/anthropics/claude-code/issues) with details about the error

125 312

126### Legacy Integration Not Working313If 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.

338

127 339

128* Ensure you're running Claude Code from VS Code's integrated terminal340---

129* Ensure the CLI for your IDE variant is installed:

130 * VS Code: `code` command should be available

131 * Cursor: `cursor` command should be available

132 * Windsurf: `windsurf` command should be available

133 * VSCodium: `codium` command should be available

134* If the command isn't installed:

135 1. Open command palette with `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)

136 2. Search for "Shell Command: Install 'code' command in PATH" (or equivalent for your IDE)

137 341

138For additional help, see our [troubleshooting guide](/en/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-11-24 21:01 UTC → 2026-01-21 21:05 UTC