Anthropic - Claude Code Docs Changes

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

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

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

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

232

233

234---

235

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

analytics.md +5 −0

Details

85 85

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

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

90---

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

checkpointing.md +5 −0

Details

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

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

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

68---

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

chrome.md +220 −0 added

Details

1# Use Claude Code with Chrome (beta)

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

5<Note>

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

7</Note>

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

11## What the integration enables

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

15Key capabilities include:

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

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

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

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

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

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

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

25## Prerequisites

27Before using Claude Code with Chrome, you need:

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

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

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

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

34## How the integration works

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

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

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

42<Note>

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

44</Note>

46## Set up the integration

48<Steps>

49 <Step title="Update Claude Code">

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

52 ```bash theme={null}

53 claude update

54 ```

55 </Step>

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

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

60 ```bash theme={null}

61 claude --chrome

62 ```

63 </Step>

65 <Step title="Verify the connection">

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

67 </Step>

68</Steps>

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

72## Try it out

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

76```

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

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

79```

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

83## Example workflows

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

87The following examples show common patterns for browser automation.

89### Test a local web application

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

93```

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

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

96messages appear correctly?

97```

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

100

101### Debug with console logs

102

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

104

105```

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

107the page loads.

108```

109

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

111

112### Automate form filling

113

114Speed up repetitive data entry tasks:

115

116```

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

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

119name, email, and phone fields.

120```

121

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

123

124### Draft content in Google Docs

125

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

127

128```

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

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

131```

132

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

134

135### Extract data from web pages

136

137Pull structured information from websites:

138

139```

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

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

142```

143

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

145

146### Run multi-site workflows

147

148Coordinate tasks across multiple websites:

149

150```

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

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

153note about what they do.

154```

155

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

157

158### Record a demo GIF

159

160Create shareable recordings of browser interactions:

161

162```

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

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

165```

166

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

168

169## Best practices

170

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

172

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

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

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

176

177## Troubleshooting

178

179### Extension not detected

180

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

182

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

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

1853. Check that Chrome is running

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

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

188

189### Browser not responding

190

191If Claude's browser commands stop working:

192

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

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

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

196

197### First-time setup

198

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

200

201## Enable by default

202

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

204

205<Note>

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

207</Note>

208

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

210

211## See also

212

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

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

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

216

217

218---

219

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

claude-code-on-the-web.md +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 +57 −30

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

36| `--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"` |45| `--max-budget-usd` | Maximum dollar amount to spend on API calls before stopping (print mode only) | `claude -p --max-budget-usd 5.00 "query"` |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

45 68

46<Tip>69<Tip>

47 The `--output-format json` flag is particularly useful for scripting and70 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:76The `--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 77

~~56| :------------ | :------- | :-------------------------------------------------------------------------------------------------------------- |~~79| :------------ | :------- | :--------------------------------------------------------------------------------------------------------------------- |

57| `description` | Yes | Natural language description of when the subagent should be invoked |80| `description` | Yes | Natural language description of when the subagent should be invoked |

58| `prompt` | Yes | The system prompt that guides the subagent's behavior |81| `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 |~~82| `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 |83| `model` | No | Model alias to use: `sonnet`, `opus`, or `haiku`. If omitted, uses the default subagent model |

61 84

62Example:85Example:

80 103

81### System prompt flags104### System prompt flags

82 105

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

84 107

~~86| :----------------------- | :--------------------------------- | :------------------ | :------------------------------------------------------------------- |~~109| :---------------------------- | :------------------------------------------ | :------------------ | :------------------------------------------------------------------- |

90 114

91**When to use each:**115**When to use each:**

92 116

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

106 ```130 ```

107 131

108<Note>132* **`--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.133 ```bash theme={null}

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

135 ```

111 136

112<Tip>137`--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 138

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

120## See also141## See also

121 142

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

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

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

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

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

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

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

150

151

152---

153

154> 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 +137 −99

Details

173 </Step>173 </Step>

174 174

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

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

177 177

178 ```178 ```

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

201 201

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

203 203

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

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

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

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

208 </Step>208 </Step>

209</Steps>209</Steps>

210 210

221 221

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

223 223

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.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. In Plan Mode, Claude uses [`AskUserQuestion`](/en/settings#tools-available-to-claude) to gather requirements and clarify your goals before proposing a plan.

225 225

226### When to use Plan Mode226### When to use Plan Mode

227 227

235 235

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

237 237

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

239 239

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

241 241

247 247

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

249 249

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

251 251

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

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

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

264```264```

265 265

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

267 267

268```268```

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

283 283

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

285 285

286## Let Claude interview you

287

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

289

290```

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

292```

293

294```

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

296```

297

298```

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

300```

301

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

303

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

305

306```markdown theme={null}

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

308```

309

310<Note>

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

312</Note>

313

286***314***

287 315

288## Work with tests316## Work with tests

315 </Step>343 </Step>

316</Steps>344</Steps>

317 345

318<Tip>346Claude 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 347

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

326***350***

327 351

336 ```360 ```

337 </Step>361 </Step>

338 362

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

340 ```364 ```

341 > create a pr 365 > create a pr

342 ```366 ```

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

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

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

485 * 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>486</Tip>

462 487

463***488***

496 Tips:521 Tips:

497 522

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

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

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

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

502</Tip>527</Tip>

503 528

504***529***

505 530

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

507 532

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

534

535Extended 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 536

510<Note>537<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.538 Phrases like "think", "think hard", "ultrathink", and "think more" are interpreted as regular prompt instructions and don't allocate thinking tokens.

512</Note>539</Note>

513 540

514<Steps>541### 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 542

520 Claude will gather relevant information from your codebase and543Thinking 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 544

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

525 ```546| ---------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |

526 > think about potential security vulnerabilities in this approach 547| **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 ```548| **Global default** | Use `/config` to toggle thinking mode | Sets your default across all projects.<br />Saved as `alwaysThinkingEnabled` in `~/.claude/settings.json` |

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

529 ```551To 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 552

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

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

537 554

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

539 556

540 * Planning complex architectural changes557A 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 558

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

560* Room to analyze edge cases and evaluate tradeoffs thoroughly

561* Ability to revise reasoning and self-correct mistakes

547 562

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

549 564

550 * "think" triggers basic extended thinking565* 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 thinking566* When thinking is **disabled** (via toggle or `/config`), Claude uses **0 tokens** for thinking

552 567

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).568**Limit the thinking budget:**

554</Tip>

555 569

556<Note>570* 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 the571* When set, this value limits the maximum tokens Claude can use for thinking

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

559</Note>573

574<Warning>

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

576</Warning>

560 577

561***578***

562 579

563## Resume previous conversations580## Resume previous conversations

564 581

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

583

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

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

566 586

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

568 588

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

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

591### Name your sessions

592

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

571 594

572<Steps>595<Steps>

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

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

575 claude --continue598

599 ```

600 > /rename auth-refactor

576 ```601 ```

577 602

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

579 </Step>604 </Step>

580 605

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

607 From the command line:

608

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

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

584 ```611 ```

585 612

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

587 </Step>

588 614

589 <Step title="Show conversation picker">

590 ```bash theme={null}

591 claude --resume

592 ```615 ```

616 > /resume auth-refactor

617 ```

618 </Step>

619</Steps>

593 620

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

595 622

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

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

600 </Step>626

601</Steps>627| Shortcut | Action |

628| :-------- | :------------------------------------------------ |

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

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

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

632| `P` | Preview the session content |

633| `R` | Rename the highlighted session |

634| `/` | Search to filter sessions |

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

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

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

638

639**Session organization:**

640

641The picker displays sessions with helpful metadata:

642

643* Session name or initial prompt

644* Time elapsed since last activity

645* Message count

646* Git branch (if applicable)

647

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

602 649

603<Tip>650<Tip>

604 Tips:651 Tips:

605 652

606 * Conversation history is stored locally on your machine653 * **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 conversation654 * 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 conversation655 * Use `--resume session-name` when you know which session you need

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

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

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

611 660

612 How it works:661 How it works:

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

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

635 668

636***669***

822<Tip>855<Tip>

823 Tips:856 Tips:

824 857

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

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

827 * Project commands are available to everyone who clones the repository860 * 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 invoked861 * The Markdown file content becomes the prompt sent to Claude when the command is invoked

829</Tip>862</Tip>

850 > /fix-issue 123 883 > /fix-issue 123

851 ```884 ```

852 885

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

854 </Step>887 </Step>

855</Steps>888</Steps>

856 889

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

949</Card>982</Card>

983

984

985---

986

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

costs.md +6 −1

Details

62 62

63* **Compact conversations:**63* **Compact conversations:**

64 64

~~65 * Claude uses auto-compact by default when context exceeds 95% capacity~~65 * Claude uses auto-compact by default when context reaches approximately 95% capacity. To trigger compaction earlier, set [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/en/settings#environment-variables) to a lower percentage (for example, `50`)

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

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

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

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

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

131</Note>131</Note>

132

133

134---

135

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

data-usage.md +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 custom commands, agents, hooks, and MCP servers. Plugin marketplaces are catalogs that help you discover and install these extensions without building them yourself.

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

9## How marketplaces work

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

13<Steps>

14 <Step title="Add the marketplace">

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

16 </Step>

18 <Step title="Install individual plugins">

19 Browse the catalog and install the plugins you want.

20 </Step>

21</Steps>

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

25## Official Anthropic marketplace

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

29To install a plugin from the official marketplace:

31```shell theme={null}

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

33```

35<Note>

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

37</Note>

39The official marketplace includes several categories of plugins:

41### Code intelligence

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

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

47| Language | Plugin | Binary required |

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

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

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

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

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

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

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

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

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

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

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

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

62<Note>

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

64</Note>

66### External integrations

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

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

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

72* **Design**: `figma`

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

74* **Communication**: `slack`

75* **Monitoring**: `sentry`

77### Development workflows

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

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

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

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

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

86### Output styles

88Customize how Claude responds:

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

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

93## Try it: add the demo marketplace

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

97<Steps>

98 <Step title="Add the marketplace">

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

100

101 ```shell theme={null}

102 /plugin marketplace add anthropics/claude-code

103 ```

104

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

106 </Step>

107

108 <Step title="Browse available plugins">

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

110

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

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

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

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

115

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

117 </Step>

118

119 <Step title="Install a plugin">

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

121

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

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

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

125

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

127

128 You can also install directly from the command line:

129

130 ```shell theme={null}

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

132 ```

133

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

135 </Step>

136

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

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

139

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

141

142 ```shell theme={null}

143 /commit-commands:commit

144 ```

145

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

147

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

149 </Step>

150</Steps>

151

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

153

154## Add marketplaces

155

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

157

158<Tip>

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

160</Tip>

161

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

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

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

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

166

167### Add from GitHub

168

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

170

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

172

173```shell theme={null}

174/plugin marketplace add anthropics/claude-code

175```

176

177### Add from other Git hosts

178

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

180

181Using HTTPS:

182

183```shell theme={null}

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

185```

186

187Using SSH:

188

189```shell theme={null}

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

191```

192

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

194

195```shell theme={null}

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

197```

198

199### Add from local paths

200

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

202

203```shell theme={null}

204/plugin marketplace add ./my-marketplace

205```

206

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

208

209```shell theme={null}

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

211```

212

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. See [Plugin Skills not appearing](/en/skills#plugin-skills-not-appearing-after-installation) for details.

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 custom commands, 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

github-actions.md +10 −6

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

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

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 [Slash commands](/en/slash-commands) like `/commit` are only available in interactive mode. In `-p` mode, describe the task you want to accomplish instead.

132 --output-format json \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 +159 −25

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

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, Agents, and Slash Commands

150

151In addition to settings files and plugins, hooks can be defined directly in [Skills](/en/skills), [subagents](/en/sub-agents), and [slash commands](/en/slash-commands) 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 and slash commands:**

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 and slash commands, 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| --------------------- | ----------------------- | ------------------------------ |

404 444

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

406 446

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

408 448

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

410#!/bin/bash450#!/bin/bash

452 session_id: string492 session_id: string

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

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

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

456 496

457 // Event-specific fields497 // Event-specific fields

458 hook_event_name: string498 hook_event_name: string

462 502

463### PreToolUse Input503### PreToolUse Input

464 504

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

506

507#### Bash tool

508

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

510

511```json theme={null}

512{

513 "session_id": "abc123",

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

515 "cwd": "/Users/...",

516 "permission_mode": "default",

517 "hook_event_name": "PreToolUse",

518 "tool_name": "Bash",

519 "tool_input": {

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

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

522 "timeout": 120000

523 },

524 "tool_use_id": "toolu_01ABC123..."

525}

526```

527

528| Field | Type | Description |

529| :------------------ | :------ | :-------------------------------------------- |

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

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

532| `timeout` | number | Optional timeout in milliseconds |

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

534

535#### Write tool

466 536

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

468{538{

480}550}

481```551```

482 552

553| Field | Type | Description |

554| :---------- | :----- | :--------------------------------- |

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

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

557

558#### Edit tool

559

560```json theme={null}

561{

562 "session_id": "abc123",

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

564 "cwd": "/Users/...",

565 "permission_mode": "default",

566 "hook_event_name": "PreToolUse",

567 "tool_name": "Edit",

568 "tool_input": {

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

570 "old_string": "original text",

571 "new_string": "replacement text"

572 },

573 "tool_use_id": "toolu_01ABC123..."

574}

575```

576

577| Field | Type | Description |

578| :------------ | :------ | :-------------------------------------------------- |

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

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

581| `new_string` | string | Replacement text |

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

583

584#### Read tool

585

586```json theme={null}

587{

588 "session_id": "abc123",

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

590 "cwd": "/Users/...",

591 "permission_mode": "default",

592 "hook_event_name": "PreToolUse",

593 "tool_name": "Read",

594 "tool_input": {

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

596 },

597 "tool_use_id": "toolu_01ABC123..."

598}

599```

600

601| Field | Type | Description |

602| :---------- | :----- | :----------------------------------------- |

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

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

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

606

483### PostToolUse Input607### PostToolUse Input

484 608

485The exact schema for `tool_input` and `tool_response` depends on the tool.609The exact schema for `tool_input` and `tool_response` depends on the tool.

590 714

591## Hook Output715## Hook Output

592 716

593There are two mutually-exclusive ways for hooks to return output back to Claude Code. The output717There 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 Claude718communicates whether to block and any feedback that should be shown to Claude

595and the user.719and the user.

596 720

681 805

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

683 807

684* `updatedInput` allows you to modify the tool's input parameters before the tool executes.808* `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.809* Combine with `"permissionDecision": "allow"` to modify the input and auto-approve the tool call

810* Combine with `"permissionDecision": "ask"` to modify the input and show it to the user for confirmation

811

812Hooks can also provide context to Claude using `additionalContext`:

813

814* `"hookSpecificOutput.additionalContext"` adds a string to Claude's context before the tool executes.

686 815

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

688{817{

689 "hookSpecificOutput": {818 "hookSpecificOutput": {

690 "hookEventName": "PreToolUse",819 "hookEventName": "PreToolUse",

691 "permissionDecision": "allow"820 "permissionDecision": "allow",

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

693 "updatedInput": {822 "updatedInput": {

694 "field_to_modify": "new value"823 "field_to_modify": "new value"

695 }824 },

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

696 }826 }

697}827}

698```828```

779```909```

780 910

781<Note>911<Note>

782 The JSON format is not required for simple use cases. To add context, you can912 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.913 block prompts or want more structured control.

785</Note>914</Note>

786 915

877<Note>1006<Note>

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

879 1008

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

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

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

883 1012

1127* Command being executed1256* Command being executed

1128* Success/failure status1257* Success/failure status

1129* Output or error messages1258* Output or error messages

1259

1260

1261---

1262

1263> 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 +6 −1

Details

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

93project.93project.

94 94

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

96 96

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

98 98

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

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

333 documentation.333 documentation.

334

335

336---

337

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

iam.md +73 −41

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

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`

97 125

98<Tip>126<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`127 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>130<Warning>

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

104 132

105 1. This tool uses **prefix matches**, not regex or glob patterns133 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 continuation134 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:135 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 match136 * Options before URL: `curl -X GET http://github.com/...` won't match

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

113 141

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

115 143

116 * Using the WebFetch tool with `WebFetch(domain:github.com)` permission144 * **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

145 * **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.md146 * Instructing Claude Code about your allowed curl patterns via CLAUDE.md

118 * Using hooks for custom permission validation147

148 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>149</Warning>

120 150

121**Read & Edit**151**Read & Edit**

122 152

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.153`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 154

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

126 156

147**MCP**177**MCP**

148 178

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

180* `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` server181* `mcp__puppeteer__puppeteer_navigate` Matches the `puppeteer_navigate` tool provided by the `puppeteer` server

151 182

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

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

154 184

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

156 186

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

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

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

159 190

160 To approve specific tools only, list each one:191Add 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 192

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

163 * ✅ Use: `mcp__github__list_issues`194{

164</Warning>195 "permissions": {

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

197 }

198}

199```

165 200

166### Additional permission control with hooks201### Additional permission control with hooks

167 202

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.203[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 204

170### Enterprise managed policy settings205### 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~~

174System administrators can deploy policies to:

175 206

176* macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`207For 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.

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 208

182### Settings precedence209### Settings precedence

183 210

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

185 212

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

1872. Command line arguments2142. Command line arguments

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

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

199* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.226* **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.227* **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.228* **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.

229

230

231---

232

233> 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 +74 −9

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

29| `Ctrl+B` | Background running tasks | Backgrounds bash commands and agents. Tmux users press twice |

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

34| `Option+P` (macOS) or `Alt+P` (Windows/Linux) | Switch model | Switch models without clearing your prompt |

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

37### Text editing

39| Shortcut | Description | Context |

40| :----------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------ |

41| `Ctrl+K` | Delete to end of line | Stores deleted text for pasting |

42| `Ctrl+U` | Delete entire line | Stores deleted text for pasting |

43| `Ctrl+Y` | Paste deleted text | Paste text deleted with `Ctrl+K` or `Ctrl+U` |

44| `Alt+Y` (after `Ctrl+Y`) | Cycle paste history | After pasting, cycle through previously deleted text. Requires [Option as Meta](#keyboard-shortcuts) on macOS |

45| `Alt+B` | Move cursor back one word | Word navigation. Requires [Option as Meta](#keyboard-shortcuts) on macOS |

46| `Alt+F` | Move cursor forward one word | Word navigation. Requires [Option as Meta](#keyboard-shortcuts) on macOS |

48### Theme and display

50| Shortcut | Description | Context |

51| :------- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------- |

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

54<Note>

55 Syntax highlighting is only available in the native build of Claude Code.

56</Note>

25 57

26### Multiline input58### Multiline input

27 59

~~29| :--------------- | :------------- | :-------------------------------- |~~61| :--------------- | :------------- | :------------------------------------------------------ |

35 67

36<Tip>68<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.~~69 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>70</Tip>

39 71

40### Quick commands72### Quick commands

41 73

~~43| :----------- | :--------------------------------- | :------------------------------------------------------------ |~~75| :----------- | :---------------- | :------------------------------------------------------------ |

~~44| `#` at start | Memory shortcut - add to CLAUDE.md | Prompts for file selection |~~

47| `@` | File path mention | Trigger file path autocomplete |78| `@` | File path mention | Trigger file path autocomplete |

65### Navigation (NORMAL mode)96### Navigation (NORMAL mode)

66 97

67| Command | Action |98| Command | Action |

~~68| :-------------- | :------------------------ |~~99| :-------------- | :-------------------------------------------------- |

70| `w` | Next word |101| `w` | Next word |

71| `e` | End of word |102| `e` | End of word |

75| `^` | First non-blank character |106| `^` | First non-blank character |

76| `gg` | Beginning of input |107| `gg` | Beginning of input |

77| `G` | End of input |108| `G` | End of input |

109| `f{char}` | Jump to next occurrence of character |

110| `F{char}` | Jump to previous occurrence of character |

111| `t{char}` | Jump to just before next occurrence of character |

112| `T{char}` | Jump to just after previous occurrence of character |

113| `;` | Repeat last f/F/t/T motion |

114| `,` | Repeat last f/F/t/T motion in reverse |

78 115

79### Editing (NORMAL mode)116### Editing (NORMAL mode)

80 117

87| `cc` | Change line |124| `cc` | Change line |

88| `C` | Change to end of line |125| `C` | Change to end of line |

127| `yy`/`Y` | Yank (copy) line |

128| `yw`/`ye`/`yb` | Yank word/to end/back |

129| `p` | Paste after cursor |

130| `P` | Paste before cursor |

131| `>>` | Indent line |

132| `<<` | Dedent line |

133| `J` | Join lines |

90| `.` | Repeat last change |134| `.` | Repeat last change |

91 135

136### Text objects (NORMAL mode)

137

138Text objects work with operators like `d`, `c`, and `y`:

139

140| Command | Action |

141| :-------- | :--------------------------------------- |

142| `iw`/`aw` | Inner/around word |

143| `iW`/`aW` | Inner/around WORD (whitespace-delimited) |

144| `i"`/`a"` | Inner/around double quotes |

145| `i'`/`a'` | Inner/around single quotes |

146| `i(`/`a(` | Inner/around parentheses |

147| `i[`/`a[` | Inner/around brackets |

148| `i{`/`a{` | Inner/around braces |

149

92## Command history150## Command history

93 151

94Claude Code maintains command history for the current session:152Claude Code maintains command history for the current session:

133* Background tasks have unique IDs for tracking and output retrieval191* Background tasks have unique IDs for tracking and output retrieval

134* Background tasks are automatically cleaned up when Claude Code exits192* Background tasks are automatically cleaned up when Claude Code exits

135 193

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

195

136**Common backgrounded commands:**196**Common backgrounded commands:**

137 197

138* Build tools (webpack, vite, make)198* Build tools (webpack, vite, make)

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

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

169* [Memory management](/en/memory) - Managing CLAUDE.md files229* [Memory management](/en/memory) - Managing CLAUDE.md files

230

231

232---

233

234> 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 +258 −38

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

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

647

648```json theme={null}

649{

650 "permissions": {

651 "deny": ["MCPSearch"]

652 }

653}

654```

655

586## Use MCP prompts as slash commands656## Use MCP prompts as slash commands

587 657

588MCP servers can expose prompts that become available as slash commands in Claude Code.658MCP servers can expose prompts that become available as slash commands in Claude Code.

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 +143 −20

Details

9Claude Code offers four memory locations in a hierarchical structure, each serving a different purpose:9Claude Code offers four memory locations in a hierarchical structure, each serving a different purpose:

10 10

12| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |12| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |

13| **Enterprise policy** | macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br />Linux: `/etc/claude-code/CLAUDE.md`<br />Windows: `C:\ProgramData\ClaudeCode\CLAUDE.md` | Organization-wide instructions managed by IT/DevOps | Company coding standards, security policies, compliance requirements | All users in organization |13| **Enterprise policy** | • macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br />• Linux: `/etc/claude-code/CLAUDE.md`<br />• Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | Organization-wide instructions managed by IT/DevOps | Company coding standards, security policies, compliance requirements | All users in organization |

15| **Project rules** | `./.claude/rules/*.md` | Modular, topic-specific project instructions | Language-specific guidelines, testing conventions, API standards | Team members via source control |

17 18

18All memory files are automatically loaded into Claude Code's context when launched. Files higher in the hierarchy take precedence and are loaded first, providing a foundation that more specific memories build upon.19All memory files are automatically loaded into Claude Code's context when launched. Files higher in the hierarchy take precedence and are loaded first, providing a foundation that more specific memories build upon.

19 20

21<Note>

22 CLAUDE.local.md files are automatically added to .gitignore, making them ideal for private project-specific preferences that shouldn't be checked into version control.

23</Note>

20## CLAUDE.md imports25## CLAUDE.md imports

21 26

22CLAUDE.md files can import additional files using `@path/to/import` syntax. The following example imports 3 files:27CLAUDE.md files can import additional files using `@path/to/import` syntax. The following example imports 3 files:

28- git workflow @docs/git-instructions.md33- git workflow @docs/git-instructions.md

29```34```

30 35

31Both relative and absolute paths are allowed. In particular, importing files in user's home dir is a convenient way for your team members to provide individual instructions that are not checked into the repository. Previously CLAUDE.local.md served a similar purpose, but is now deprecated in favor of imports since they work better across multiple git worktrees.36Both relative and absolute paths are allowed. In particular, importing files in user's home dir is a convenient way for your team members to provide individual instructions that are not checked into the repository. Imports are an alternative to CLAUDE.local.md that work better across multiple git worktrees.

32 37

33```38```

34# Individual Preferences39# Individual Preferences

49 54

50Claude will also discover CLAUDE.md nested in subtrees under your current working directory. Instead of loading them at launch, they are only included when Claude reads files in those subtrees.55Claude will also discover CLAUDE.md nested in subtrees under your current working directory. Instead of loading them at launch, they are only included when Claude reads files in those subtrees.

51 56

~~52## Quickly add memories with the `#` shortcut~~

~~54The fastest way to add a memory is to start your input with the `#` character:~~

~~56```~~

~~57# Always use descriptive variable names~~

~~58```~~

~~60You'll be prompted to select which memory file to store this in.~~

62## Directly edit memories with `/memory`57## Directly edit memories with `/memory`

63 58

64Use the `/memory` slash command during a session to open any memory file in your system editor for more extensive additions or organization.59Use the `/memory` slash command during a session to open any memory file in your system editor for more extensive additions or organization.

82 * CLAUDE.md memories can be used for both instructions shared with your team and for your individual preferences.77 * CLAUDE.md memories can be used for both instructions shared with your team and for your individual preferences.

83</Tip>78</Tip>

84 79

80## Modular rules with `.claude/rules/`

82For larger projects, you can organize instructions into multiple files using the `.claude/rules/` directory. This allows teams to maintain focused, well-organized rule files instead of one large CLAUDE.md.

84### Basic structure

86Place markdown files in your project's `.claude/rules/` directory:

88```

89your-project/

90├── .claude/

91│ ├── CLAUDE.md # Main project instructions

92│ └── rules/

93│ ├── code-style.md # Code style guidelines

94│ ├── testing.md # Testing conventions

95│ └── security.md # Security requirements

96```

98All `.md` files in `.claude/rules/` are automatically loaded as project memory, with the same priority as `.claude/CLAUDE.md`.

100### Path-specific rules

101

102Rules can be scoped to specific files using YAML frontmatter with the `paths` field. These conditional rules only apply when Claude is working with files matching the specified patterns.

103

104```markdown theme={null}

105---

106paths:

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

Details

107 107

108You can think of output styles as "stored system prompts" and custom slash108You can think of output styles as "stored system prompts" and custom slash

109commands as "stored prompts".109commands as "stored prompts".

110

111

112---

113

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

overview.md +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 +320 −189

Details

~~1# Plugin marketplaces~~1# Create and distribute a plugin marketplace

2 2

~~3> Create and manage plugin marketplaces to distribute Claude Code extensions across teams and communities.~~3> Build and host plugin marketplaces to distribute Claude Code extensions across teams and communities.

4 4

5Plugin marketplaces are catalogs of available plugins that make it easy to discover, install, and manage Claude Code extensions. This guide shows you how to use existing marketplaces and create your own for team distribution.5A plugin marketplace is a catalog that lets you distribute plugins to others. Marketplaces provide centralized discovery, version tracking, automatic updates, and support for multiple source types (git repositories, local paths, and more). This guide shows you how to create your own marketplace to share plugins with your team or community.

6 6

~~7## Overview~~7Looking to install plugins from an existing marketplace? See [Discover and install prebuilt plugins](/en/discover-plugins).

~~9A marketplace is a JSON file that lists available plugins and describes where to find them. Marketplaces provide:~~

~~11* **Centralized discovery**: Browse plugins from multiple sources in one place~~

~~12* **Version management**: Track and update plugin versions automatically~~

~~13* **Team distribution**: Share required plugins across your organization~~

~~14* **Flexible sources**: Support for git repositories, GitHub repos, local paths, and package managers~~

~~16### Prerequisites~~

~~18* Claude Code installed and running~~

~~19* Basic familiarity with JSON file format~~

~~20* For creating marketplaces: Git repository or local development environment~~

~~22## Add and use marketplaces~~

~~24Add marketplaces using the `/plugin marketplace` commands to access plugins from different sources:~~

~~26### Add GitHub marketplaces~~

~~28```shell Add a GitHub repository containing .claude-plugin/marketplace.json theme={null}~~

~~29/plugin marketplace add owner/repo~~

~~30```~~

31 8

~~32### Add Git repositories~~9## Overview

33 10

~~34```shell Add any git repository theme={null}~~11Creating and distributing a marketplace involves:

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

~~36```~~

37 12

~~38### Add local marketplaces for development~~131. **Creating plugins**: build one or more plugins with commands, agents, hooks, MCP servers, or LSP servers. This guide assumes you already have plugins to distribute; see [Create plugins](/en/plugins) for details on how to create them.

142. **Creating a marketplace file**: define a `marketplace.json` that lists your plugins and where to find them (see [Create the marketplace file](#create-the-marketplace-file)).

153. **Host the marketplace**: push to GitHub, GitLab, or another git host (see [Host and distribute marketplaces](#host-and-distribute-marketplaces)).

164. **Share with users**: users add your marketplace with `/plugin marketplace add` and install individual plugins (see [Discover and install plugins](/en/discover-plugins)).

39 17

~~40```shell Add local directory containing .claude-plugin/marketplace.json theme={null}~~18Once your marketplace is live, you can update it by pushing changes to your repository. Users refresh their local copy with `/plugin marketplace update`.

~~41/plugin marketplace add ./my-marketplace~~

~~42```~~

43 19

~~44```shell Add direct path to marketplace.json file theme={null}~~20## Walkthrough: create a local marketplace

~~45/plugin marketplace add ./path/to/marketplace.json~~

~~46```~~

47 21

~~48```shell Add remote marketplace.json via URL theme={null}~~22This example creates a marketplace with one plugin: a `/review` command for code reviews. You'll create the directory structure, add a slash command, create the plugin manifest and marketplace catalog, then install and test it.

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

55 25 <Step title="Create the directory structure">

~~56```shell Install from any known marketplace theme={null}~~26 ```bash theme={null}

~~57/plugin install plugin-name@marketplace-name~~27 mkdir -p my-marketplace/.claude-plugin

~~58```~~28 mkdir -p my-marketplace/plugins/review-plugin/.claude-plugin

29 mkdir -p my-marketplace/plugins/review-plugin/commands

30 ```

31 </Step>

59 32

~~60```shell Browse available plugins interactively theme={null}~~33 <Step title="Create the plugin command">

~~61/plugin~~34 Create a Markdown file that defines what the `/review` command does.

~~62```~~

63 35

~~64### Verify marketplace installation~~36 ```markdown my-marketplace/plugins/review-plugin/commands/review.md theme={null}

37 Review the code I've selected or the recent changes for:

38 - Potential bugs or edge cases

39 - Security concerns

40 - Performance issues

41 - Readability improvements

65 42

~~66After adding a marketplace:~~43 Be concise and actionable.

44 ```

45 </Step>

67 46

~~681. **List marketplaces**: Run `/plugin marketplace list` to confirm it's added~~47 <Step title="Create the plugin manifest">

~~692. **Browse plugins**: Use `/plugin` to see available plugins from your marketplace~~48 Create a `plugin.json` file that describes the plugin. The manifest goes in the `.claude-plugin/` directory.

~~703. **Test installation**: Try installing a plugin to verify the marketplace works correctly~~

71 49

~~72## Configure team marketplaces~~50 ```json my-marketplace/plugins/review-plugin/.claude-plugin/plugin.json theme={null}

51 {

52 "name": "review-plugin",

53 "description": "Adds a /review command for quick code reviews",

54 "version": "1.0.0"

55 }

56 ```

57 </Step>

73 58

~~74Set up automatic marketplace installation for team projects by specifying required marketplaces in `.claude/settings.json`:~~59 <Step title="Create the marketplace file">

60 Create the marketplace catalog that lists your plugin.

75 61

~~76```json theme={null}~~62 ```json my-marketplace/.claude-plugin/marketplace.json theme={null}

~~77{~~63 {

~~78 "extraKnownMarketplaces": {~~64 "name": "my-plugins",

~~79 "team-tools": {~~65 "owner": {

~~80 "source": {~~66 "name": "Your Name"

~~81 "source": "github",~~

~~82 "repo": "your-org/claude-plugins"~~

~~83 }~~

84 },67 },

~~85 "project-specific": {~~68 "plugins": [

~~86 "source": {~~69 {

~~87 "source": "git",~~70 "name": "review-plugin",

~~88 "url": "https://git.company.com/project-plugins.git"~~71 "source": "./plugins/review-plugin",

~~89 }~~72 "description": "Adds a /review command for quick code reviews"

90 }73 }

74 ]

91 }75 }

~~92}~~76 ```

~~93```~~77 </Step>

94 78

~~95When team members trust the repository folder, Claude Code automatically installs these marketplaces and any plugins specified in the `enabledPlugins` field.~~79 <Step title="Add and install">

80 Add the marketplace and install the plugin.

96 81

~~97***~~82 ```shell theme={null}

83 /plugin marketplace add ./my-marketplace

84 /plugin install review-plugin@my-plugins

85 ```

86 </Step>

98 87

~~99## Create your own marketplace~~88 <Step title="Try it out">

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

100 90

101Build and distribute custom plugin collections for your team or community.91 ```shell theme={null}

92 /review

93 ```

94 </Step>

95</Steps>

102 96

103### Prerequisites for marketplace creation97To learn more about what plugins can do, including hooks, agents, MCP servers, and LSP servers, see [Plugins](/en/plugins).

104 98

105* Git repository (GitHub, GitLab, or other git hosting)99<Note>

106* Understanding of JSON file format100 **How plugins are installed**: When users install a plugin, Claude Code copies the plugin directory to a cache location. This means plugins can't reference files outside their directory using paths like `../shared-utils`, because those files won't be copied.

107* One or more plugins to distribute101

102 If you need to share files across plugins, use symlinks (which are followed during copying) or restructure your marketplace so the shared directory is inside the plugin source path. See [Plugin caching and file resolution](/en/plugins-reference#plugin-caching-and-file-resolution) for details.

103</Note>

108 104

109### Create the marketplace file105## Create the marketplace file

110 106

111Create `.claude-plugin/marketplace.json` in your repository root:107Create `.claude-plugin/marketplace.json` in your repository root. This file defines your marketplace's name, owner information, and a list of plugins with their sources.

108

109Each plugin entry needs at minimum a `name` and `source` (where to fetch it from). See the [full schema](#marketplace-schema) below for all available fields.

112 110

113```json theme={null}111```json theme={null}

114{112{

115 "name": "company-tools",113 "name": "company-tools",

116 "owner": {114 "owner": {

117 "name": "DevTools Team",115 "name": "DevTools Team",

118 "email": "devtools@company.com"116 "email": "devtools@example.com"

119 },117 },

120 "plugins": [118 "plugins": [

121 {119 {

139}137}

140```138```

141 139

142### Marketplace schema140## Marketplace schema

143 141

144#### Required fields142### Required fields

145 143

147| :-------- | :----- | :--------------------------------------------- |145| :-------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |

149

150<Note>

151 **Reserved names**: The following marketplace names are reserved for official Anthropic use and cannot be used by third-party marketplaces: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `life-sciences`. Names that impersonate official marketplaces (like `official-claude-plugins` or `anthropic-tools-v2`) are also blocked.

152</Note>

153

154### Owner fields

155

157| :------ | :----- | :------- | :------------------------------- |

151 160

152#### Optional metadata161### Optional metadata

153 162

155| :--------------------- | :----- | :------------------------------------ |164| :--------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

159 168

160### Plugin entries169## Plugin entries

161 170

162<Note>171Each plugin entry in the `plugins` array describes a plugin and where to find it. You can include any field from the [plugin manifest schema](/en/plugins-reference#plugin-manifest-schema) (like `description`, `version`, `author`, `commands`, `hooks`, etc.), plus these marketplace-specific fields: `source`, `category`, `tags`, and `strict`.

163 Plugin entries are based on the *plugin manifest schema* (with all fields made optional) plus marketplace-specific fields (`source`, `category`, `tags`, `strict`), with `name` being required.

164</Note>

165 172

166**Required fields:**173### Required fields

167 174

169| :------- | :------------- | :---------------------------------------- |176| :------- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

172 179

173#### Optional plugin fields180### Optional plugin fields

174 181

175**Standard metadata fields:**182**Standard metadata fields:**

176 183

178| :------------ | :------ | :---------------------------------------------------------------- |185| :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

188| `strict` | boolean | Require plugin.json in plugin folder (default: true) <sup>1</sup> |195| `strict` | boolean | Controls whether plugins need their own `plugin.json` file. When `true` (default), the plugin source must contain a `plugin.json`, and any fields you add here in the marketplace entry get merged with it. When `false`, the plugin doesn't need its own `plugin.json`; the marketplace entry itself defines everything about the plugin. Use `false` when you want to define simple plugins entirely in your marketplace file. |

189 196

190**Component configuration fields:**197**Component configuration fields:**

191 198

198 206

199*<sup>1 - When `strict: true` (default), the plugin must include a `plugin.json` manifest file, and marketplace fields supplement those values. When `strict: false`, the plugin.json is optional. If it's missing, the marketplace entry serves as the complete plugin manifest.</sup>*207## Plugin sources

~~200~~

201### Plugin sources

202 208

203#### Relative paths209### Relative paths

204 210

205For plugins in the same repository:211For plugins in the same repository:

206 212

211}217}

212```218```

213 219

214#### GitHub repositories220<Note>

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

222</Note>

223

224### GitHub repositories

215 225

216```json theme={null}226```json theme={null}

217{227{

223}233}

224```234```

225 235

226#### Git repositories236### Git repositories

227 237

228```json theme={null}238```json theme={null}

229{239{

235}245}

236```246```

237 247

238#### Advanced plugin entries248### Advanced plugin entries

239 249

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)):250This example shows a plugin entry using many of the optional fields, including custom paths for commands, agents, hooks, and MCP servers:

241 251

242```json theme={null}252```json theme={null}

243{253{

250 "version": "2.1.0",260 "version": "2.1.0",

251 "author": {261 "author": {

252 "name": "Enterprise Team",262 "name": "Enterprise Team",

253 "email": "enterprise@company.com"263 "email": "enterprise@example.com"

254 },264 },

255 "homepage": "https://docs.company.com/plugins/enterprise-tools",265 "homepage": "https://docs.example.com/plugins/enterprise-tools",

256 "repository": "https://github.com/company/enterprise-plugin",266 "repository": "https://github.com/company/enterprise-plugin",

257 "license": "MIT",267 "license": "MIT",

258 "keywords": ["enterprise", "workflow", "automation"],268 "keywords": ["enterprise", "workflow", "automation"],

262 "./commands/enterprise/",272 "./commands/enterprise/",

263 "./commands/experimental/preview.md"273 "./commands/experimental/preview.md"

264 ],274 ],

265 "agents": [275 "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],

266 "./agents/security-reviewer.md",

267 "./agents/compliance-checker.md"

268 ],

269 "hooks": {276 "hooks": {

270 "PostToolUse": [277 "PostToolUse": [

271 {278 {

272 "matcher": "Write|Edit",279 "matcher": "Write|Edit",

273 "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"}]280 "hooks": [

281 {

282 "type": "command",

283 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"

284 }

285 ]

274 }286 }

275 ]287 ]

276 },288 },

284}296}

285```297```

286 298

287<Note>299Key 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 300

291***301* **`commands` and `agents`**: You can specify multiple directories or individual files. Paths are relative to the plugin root.

302* **`${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.

303* **`strict: false`**: Since this is set to false, the plugin doesn't need its own `plugin.json`. The marketplace entry defines everything.

292 304

293## Host and distribute marketplaces305## Host and distribute marketplaces

294 306

295Choose the best hosting strategy for your plugin distribution needs.

~~296~~

297### Host on GitHub (recommended)307### Host on GitHub (recommended)

298 308

299GitHub provides the easiest distribution method:309GitHub provides the easiest distribution method:

300 310

3011. **Create a repository**: Set up a new repository for your marketplace3111. **Create a repository**: Set up a new repository for your marketplace

3022. **Add marketplace file**: Create `.claude-plugin/marketplace.json` with your plugin definitions3122. **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`3133. **Share with teams**: Users add your marketplace with `/plugin marketplace add owner/repo`

304 314

305**Benefits**: Built-in version control, issue tracking, and team collaboration features.315**Benefits**: Built-in version control, issue tracking, and team collaboration features.

306 316

307### Host on other git services317### Host on other git services

308 318

309Any git hosting service works for marketplace distribution, using a URL to an arbitrary git repository.319Any 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 320

313```shell theme={null}321```shell theme={null}

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

315```323```

316 324

317### Use local marketplaces for development325### Private repositories

318 326

319Test your marketplace locally before distribution:327Claude 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 328

321```shell Add local marketplace for testing theme={null}329| Provider | Environment variables | Notes |

322/plugin marketplace add ./my-local-marketplace330| :-------- | :--------------------------- | :---------------------------------------- |

331| GitHub | `GITHUB_TOKEN` or `GH_TOKEN` | Personal access token or GitHub App token |

332| GitLab | `GITLAB_TOKEN` or `GL_TOKEN` | Personal access token or project token |

333| Bitbucket | `BITBUCKET_TOKEN` | App password or repository access token |

334

335Set the token in your shell configuration (for example, `.bashrc`, `.zshrc`) or pass it when running Claude Code:

336

337```bash theme={null}

338export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

323```339```

324 340

325```shell Test plugin installation theme={null}341Authentication tokens are only used when a repository requires authentication. Public repositories work without any tokens configured, even if tokens are present in your environment.

342

343<Note>

344 For CI/CD environments, configure the token as a secret environment variable. GitHub Actions automatically provides `GITHUB_TOKEN` for repositories in the same organization.

345</Note>

346

347### Test locally before distribution

348

349Test your marketplace locally before sharing:

350

351```shell theme={null}

352/plugin marketplace add ./my-local-marketplace

326/plugin install test-plugin@my-local-marketplace353/plugin install test-plugin@my-local-marketplace

327```354```

328 355

329## Manage marketplace operations356For the full range of add commands (GitHub, Git URLs, local paths, remote URLs), see [Add marketplaces](/en/discover-plugins#add-marketplaces).

357

358### Require marketplaces for your team

359

360You 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`:

361

362```json theme={null}

363{

364 "extraKnownMarketplaces": {

365 "company-tools": {

366 "source": {

367 "source": "github",

368 "repo": "your-org/claude-plugins"

369 }

370 }

371 }

372}

373```

330 374

331### List known marketplaces375You can also specify which plugins should be enabled by default:

332 376

333```shell List all configured marketplaces theme={null}377```json theme={null}

334/plugin marketplace list378{

379 "enabledPlugins": {

380 "code-formatter@company-tools": true,

381 "deployment-tools@company-tools": true

382 }

383}

335```384```

336 385

337Shows all configured marketplaces with their sources and status.386For full configuration options, see [Plugin settings](/en/settings#plugin-settings).

387

388### Managed marketplace restrictions

389

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

391

392When `strictKnownMarketplaces` is configured in managed settings, the restriction behavior depends on the value:

393

394| Value | Behavior |

395| ------------------- | ---------------------------------------------------------------- |

396| Undefined (default) | No restrictions. Users can add any marketplace |

397| Empty array `[]` | Complete lockdown. Users cannot add any new marketplaces |

398| List of sources | Users can only add marketplaces that match the allowlist exactly |

338 399

339### Update marketplace metadata400#### Common configurations

340 401

341```shell Refresh marketplace metadata theme={null}402Disable all marketplace additions:

342/plugin marketplace update marketplace-name403

404```json theme={null}

405{

406 "strictKnownMarketplaces": []

407}

408```

409

410Allow specific marketplaces only:

411

412```json theme={null}

413{

414 "strictKnownMarketplaces": [

415 {

416 "source": "github",

417 "repo": "acme-corp/approved-plugins"

418 },

419 {

420 "source": "github",

421 "repo": "acme-corp/security-tools",

422 "ref": "v2.0"

423 },

424 {

425 "source": "url",

426 "url": "https://plugins.example.com/marketplace.json"

427 }

428 ]

429}

343```430```

344 431

345Refreshes plugin listings and metadata from the marketplace source.432#### How restrictions work

433

434Restrictions are validated early in the plugin installation process, before any network requests or filesystem operations occur. This prevents unauthorized marketplace access attempts.

435

436The allowlist uses exact matching. For a marketplace to be allowed, all specified fields must match exactly:

437

438* For GitHub sources: `repo` is required, and `ref` or `path` must also match if specified in the allowlist

439* For URL sources: the full URL must match exactly

440

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

346 442

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

348 444

349```shell Remove a marketplace theme={null}445## Validation and testing

350/plugin marketplace remove marketplace-name446

447Test your marketplace before sharing.

448

449Validate your marketplace JSON syntax:

450

451```bash theme={null}

452claude plugin validate .

351```453```

352 454

353Removes the marketplace from your configuration.455Or from within Claude Code:

354 456

355<Warning>457```shell theme={null}

356 Removing a marketplace will uninstall any plugins you installed from it.458/plugin validate .

357</Warning>459```

460

461Add the marketplace for testing:

358 462

359***463```shell theme={null}

464/plugin marketplace add ./path/to/marketplace

465```

466

467Install a test plugin to verify everything works:

468

469```shell theme={null}

470/plugin install test-plugin@marketplace-name

471```

360 472

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

362 474

363### Common marketplace issues475## Troubleshooting

364 476

365#### Marketplace not loading477### Marketplace not loading

366 478

367**Symptoms**: Can't add marketplace or see plugins from it479**Symptoms**: Can't add marketplace or see plugins from it

368 480

370 482

371* Verify the marketplace URL is accessible483* Verify the marketplace URL is accessible

372* Check that `.claude-plugin/marketplace.json` exists at the specified path484* Check that `.claude-plugin/marketplace.json` exists at the specified path

373* Ensure JSON syntax is valid using `claude plugin validate`485* Ensure JSON syntax is valid using `claude plugin validate` or `/plugin validate`

374* For private repositories, confirm you have access permissions486* For private repositories, confirm you have access permissions

375 487

376#### Plugin installation failures488### Marketplace validation errors

489

490Run `claude plugin validate .` or `/plugin validate .` from your marketplace directory to check for issues. Common errors:

491

492| Error | Cause | Solution |

493| :------------------------------------------------ | :------------------------------ | :------------------------------------------------------------ |

494| `File not found: .claude-plugin/marketplace.json` | Missing manifest | Create `.claude-plugin/marketplace.json` with required fields |

495| `Invalid JSON syntax: Unexpected token...` | JSON syntax error | Check for missing commas, extra commas, or unquoted strings |

496| `Duplicate plugin name "x" found in marketplace` | Two plugins share the same name | Give each plugin a unique `name` value |

497| `plugins[0].source: Path traversal not allowed` | Source path contains `..` | Use paths relative to marketplace root without `..` |

498

499**Warnings** (non-blocking):

500

501* `Marketplace has no plugins defined`: add at least one plugin to the `plugins` array

502* `No marketplace description provided`: add `metadata.description` to help users understand your marketplace

503* `Plugin "x" uses npm source which is not yet fully implemented`: use `github` or local path sources instead

504

505### Plugin installation failures

377 506

378**Symptoms**: Marketplace appears but plugin installation fails507**Symptoms**: Marketplace appears but plugin installation fails

379 508

384* For GitHub sources, ensure repositories are public or you have access513* For GitHub sources, ensure repositories are public or you have access

385* Test plugin sources manually by cloning/downloading514* Test plugin sources manually by cloning/downloading

386 515

387### Validation and testing516### Private repository authentication fails

388 517

389Test your marketplace before sharing:518**Symptoms**: Authentication errors when installing plugins from private repositories, even with tokens configured

390 519

391```bash Validate marketplace JSON syntax theme={null}520**Solutions**:

392claude plugin validate .

393```

394 521

395```shell Add marketplace for testing theme={null}522* Verify your token is set in the current shell session: `echo $GITHUB_TOKEN`

396/plugin marketplace add ./path/to/marketplace523* Check that the token has the required permissions (read access to the repository)

397```524* For GitHub, ensure the token has the `repo` scope for private repositories

525* For GitLab, ensure the token has at least `read_repository` scope

526* Verify the token hasn't expired

527* If using multiple git providers, ensure you've set the token for the correct provider

398 528

399```shell Install test plugin theme={null}529### Plugins with relative paths fail in URL-based marketplaces

400/plugin install test-plugin@marketplace-name

401```

402 530

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).531**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 532

405***533**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 534

407## Next steps535**Solutions**:

408 536

409### For marketplace users537* **Use external sources**: Change plugin entries to use GitHub, npm, or git URL sources instead of relative paths:

538 ```json theme={null}

539 { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

540 ```

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

411* **Discover community marketplaces**: Search GitHub for Claude Code plugin collections543### 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 544

415### For marketplace creators545**Symptoms**: Plugin installs but references to files fail, especially files outside the plugin directory

416 546

417* **Build plugin collections**: Create themed marketplace around specific use cases547**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 548

422### For organizations549**Solutions**: See [Plugin caching and file resolution](/en/plugins-reference#plugin-caching-and-file-resolution) for workarounds including symlinks and directory restructuring.

423 550

424* **Private marketplaces**: Set up internal marketplaces for proprietary tools551For 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 552

428## See also553## See also

429 554

430* [Plugins](/en/plugins) - Installing and using plugins555* [Discover and install prebuilt plugins](/en/discover-plugins) - Installing plugins from existing marketplaces

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

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

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

433* [Settings](/en/settings#plugin-configuration) - Plugin configuration options559* [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces) - Managed marketplace restrictions

560

561

562---

563

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

plugins.md +273 −251

Details

~~1# Plugins~~1# Create plugins

2 2

~~3> Extend Claude Code with custom commands, agents, hooks, Skills, and MCP servers through the plugin system.~~3> Create custom plugins to extend Claude Code with slash commands, agents, hooks, Skills, and MCP servers.

5Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. This guide covers creating your own plugins with slash commands, agents, Skills, hooks, and MCP servers.

7Looking to install existing plugins? See [Discover and install plugins](/en/discover-plugins). For complete technical specifications, see [Plugins reference](/en/plugins-reference).

9## When to use plugins vs standalone configuration

11Claude Code supports two ways to add custom slash commands, agents, and hooks:

13| Approach | Slash command names | Best for |

14| :---------------------------------------------------------- | :------------------- | :---------------------------------------------------------------------------------------------- |

15| **Standalone** (`.claude/` directory) | `/hello` | Personal workflows, project-specific customizations, quick experiments |

16| **Plugins** (directories with `.claude-plugin/plugin.json`) | `/plugin-name:hello` | Sharing with teammates, distributing to community, versioned releases, reusable across projects |

18**Use standalone configuration when**:

20* You're customizing Claude Code for a single project

21* The configuration is personal and doesn't need to be shared

22* You're experimenting with slash commands or hooks before packaging them

23* You want short slash command names like `/hello` or `/review`

25**Use plugins when**:

27* You want to share functionality with your team or community

28* You need the same slash commands/agents across multiple projects

29* You want version control and easy updates for your extensions

30* You're distributing through a marketplace

31* You're okay with namespaced slash commands like `/my-plugin:hello` (namespacing prevents conflicts between plugins)

4 32

5<Tip>33<Tip>

~~6 For complete technical specifications and schemas, see [Plugins reference](/en/plugins-reference). For marketplace management, see [Plugin marketplaces](/en/plugin-marketplaces).~~34 Start with standalone configuration in `.claude/` for quick iteration, then [convert to a plugin](#convert-existing-configurations-to-plugins) when you're ready to share.

7</Tip>35</Tip>

8 36

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

11## Quickstart37## Quickstart

12 38

~~13Let's create a simple greeting plugin to get you familiar with the plugin system. We'll build a working plugin that adds a custom command, test it locally, and understand the core concepts.~~39This quickstart walks you through creating a plugin with a custom slash command. You'll create a manifest (the configuration file that defines your plugin), add a slash command, and test it locally using the `--plugin-dir` flag.

14 40

15### Prerequisites41### Prerequisites

16 42

~~17* Claude Code installed on your machine~~43* Claude Code [installed and authenticated](/en/quickstart#step-1-install-claude-code)

~~18* Basic familiarity with command-line tools~~44* Claude Code version 1.0.33 or later (run `claude --version` to check)

46<Note>

47 If you don't see the `/plugin` command, update Claude Code to the latest version. See [Troubleshooting](/en/troubleshooting) for upgrade instructions.

48</Note>

19 49

20### Create your first plugin50### Create your first plugin

21 51

22<Steps>52<Steps>

~~23 <Step title="Create the marketplace structure">~~

~~24 ```bash theme={null}~~

~~25 mkdir test-marketplace~~

~~26 cd test-marketplace~~

~~27 ```~~

~~28 </Step>~~

30 <Step title="Create the plugin directory">53 <Step title="Create the plugin directory">

54 Every plugin lives in its own directory containing a manifest and your custom commands, agents, or hooks. Create one now:

31 ```bash theme={null}56 ```bash theme={null}

32 mkdir my-first-plugin57 mkdir my-first-plugin

~~33 cd my-first-plugin~~

34 ```58 ```

35 </Step>59 </Step>

36 60

37 <Step title="Create the plugin manifest">61 <Step title="Create the plugin manifest">

~~38 ```bash Create .claude-plugin/plugin.json theme={null}~~62 The manifest file at `.claude-plugin/plugin.json` defines your plugin's identity: its name, description, and version. Claude Code uses this metadata to display your plugin in the plugin manager.

~~39 mkdir .claude-plugin~~63

~~40 cat > .claude-plugin/plugin.json << 'EOF'~~64 Create the `.claude-plugin` directory inside your plugin folder:

66 ```bash theme={null}

67 mkdir my-first-plugin/.claude-plugin

68 ```

70 Then create `my-first-plugin/.claude-plugin/plugin.json` with this content:

72 ```json my-first-plugin/.claude-plugin/plugin.json theme={null}

41 {73 {

42 "name": "my-first-plugin",74 "name": "my-first-plugin",

~~43 "description": "A simple greeting plugin to learn the basics",~~75 "description": "A greeting plugin to learn the basics",

44 "version": "1.0.0",76 "version": "1.0.0",

45 "author": {77 "author": {

46 "name": "Your Name"78 "name": "Your Name"

47 }79 }

48 }80 }

~~49 EOF~~

50 ```81 ```

83 | Field | Purpose |

84 | :------------ | :--------------------------------------------------------------------------------------------------------------------- |

85 | `name` | Unique identifier and slash command namespace. Slash commands are prefixed with this (e.g., `/my-first-plugin:hello`). |

86 | `description` | Shown in the plugin manager when browsing or installing plugins. |

87 | `version` | Track releases using [semantic versioning](/en/plugins-reference#version-management). |

88 | `author` | Optional. Helpful for attribution. |

90 For additional fields like `homepage`, `repository`, and `license`, see the [full manifest schema](/en/plugins-reference#plugin-manifest-schema).

51 </Step>91 </Step>

52 92

~~53 <Step title="Add a custom command">~~93 <Step title="Add a slash command">

~~54 ```bash Create commands/hello.md theme={null}~~94 Slash commands are Markdown files in the `commands/` directory. The filename becomes the slash command name, prefixed with the plugin's namespace (`hello.md` in a plugin named `my-first-plugin` creates `/my-first-plugin:hello`). The Markdown content tells Claude how to respond when someone runs the slash command.

~~55 mkdir commands~~95

~~56 cat > commands/hello.md << 'EOF'~~96 Create a `commands` directory in your plugin folder:

98 ```bash theme={null}

99 mkdir my-first-plugin/commands

100 ```

101

102 Then create `my-first-plugin/commands/hello.md` with this content:

103

104 ```markdown my-first-plugin/commands/hello.md theme={null}

57 ---105 ---

~~58 description: Greet the user with a personalized message~~106 description: Greet the user with a friendly message

59 ---107 ---

60 108

61 # Hello Command109 # Hello Command

62 110

~~63 Greet the user warmly and ask how you can help them today. Make the greeting personal and encouraging.~~111 Greet the user warmly and ask how you can help them today.

~~64 EOF~~

65 ```112 ```

66 </Step>113 </Step>

67 114

~~68 <Step title="Create the marketplace manifest">~~115 <Step title="Test your plugin">

~~69 ```bash Create marketplace.json theme={null}~~116 Run Claude Code with the `--plugin-dir` flag to load your plugin:

~~70 cd ..~~

~~71 mkdir .claude-plugin~~

~~72 cat > .claude-plugin/marketplace.json << 'EOF'~~

~~73 {~~

~~74 "name": "test-marketplace",~~

~~75 "owner": {~~

~~76 "name": "Test User"~~

~~77 },~~

~~78 "plugins": [~~

~~79 {~~

~~80 "name": "my-first-plugin",~~

~~81 "source": "./my-first-plugin",~~

~~82 "description": "My first test plugin"~~

~~83 }~~

~~84 ]~~

~~85 }~~

~~86 EOF~~

~~87 ```~~

~~88 </Step>~~

89 117

~~90 <Step title="Install and test your plugin">~~118 ```bash theme={null}

~~91 ```bash Start Claude Code from parent directory theme={null}~~119 claude --plugin-dir ./my-first-plugin

~~92 cd ..~~

~~93 claude~~

94 ```120 ```

95 121

~~96 ```shell Add the test marketplace theme={null}~~122 Once Claude Code starts, try your new command:

~~97 /plugin marketplace add ./test-marketplace~~123

124 ```shell theme={null}

125 /my-first-plugin:hello

98 ```126 ```

99 127

100 ```shell Install your plugin theme={null}128 You'll see Claude respond with a greeting. Run `/help` to see your command listed under the plugin namespace.

101 /plugin install my-first-plugin@test-marketplace129

130 <Note>

131 **Why namespacing?** Plugin slash commands are always namespaced (like `/greet:hello`) to prevent conflicts when multiple plugins have commands with the same name.

132

133 To change the namespace prefix, update the `name` field in `plugin.json`.

134 </Note>

135 </Step>

136

137 <Step title="Add slash command arguments">

138 Make your slash command dynamic by accepting user input. The `$ARGUMENTS` placeholder captures any text the user provides after the slash command.

139

140 Update your `hello.md` file:

141

142 ```markdown my-first-plugin/commands/hello.md theme={null}

143 ---

144 description: Greet the user with a personalized message

145 ---

146

147 # Hello Command

148

149 Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

102 ```150 ```

103 151

104 Select "Install now". You'll then need to restart Claude Code in order to use the new plugin.152 Restart Claude Code to pick up the changes, then try the command with your name:

105 153

106 ```shell Try your new command theme={null}154 ```shell theme={null}

107 /hello155 /my-first-plugin:hello Alex

108 ```156 ```

109 157

110 You'll see Claude use your greeting command! Check `/help` to see your new command listed.158 Claude will greet you by name. For more argument options like `$1`, `$2` for individual parameters, see [Slash commands](/en/slash-commands).

111 </Step>159 </Step>

112</Steps>160</Steps>

113 161

114You've successfully created and tested a plugin with these key components:162You've successfully created and tested a plugin with these key components:

115 163

116* **Plugin manifest** (`.claude-plugin/plugin.json`) - Describes your plugin's metadata164* **Plugin manifest** (`.claude-plugin/plugin.json`): describes your plugin's metadata

117* **Commands directory** (`commands/`) - Contains your custom slash commands165* **Commands directory** (`commands/`): contains your custom slash commands

118* **Test marketplace** - Allows you to test your plugin locally166* **Command arguments** (`$ARGUMENTS`): captures user input for dynamic behavior

119 167

120### Plugin structure overview168<Tip>

169 The `--plugin-dir` flag is useful for development and testing. When you're ready to share your plugin with others, see [Create and distribute a plugin marketplace](/en/plugin-marketplaces).

170</Tip>

121 171

122Your plugin follows this basic structure:172## Plugin structure overview

123 173

124```174You've created a plugin with a slash command, but plugins can include much more: custom agents, Skills, hooks, MCP servers, and LSP servers.

125my-first-plugin/

126├── .claude-plugin/

127│ └── plugin.json # Plugin metadata

128├── commands/ # Custom slash commands (optional)

129│ └── hello.md

130├── agents/ # Custom agents (optional)

131│ └── helper.md

132├── skills/ # Agent Skills (optional)

133│ └── my-skill/

134│ └── SKILL.md

135└── hooks/ # Event handlers (optional)

136 └── hooks.json

137```

138 175

139**Additional components you can add:**176<Warning>

177 **Common mistake**: Don't put `commands/`, `agents/`, `skills/`, or `hooks/` inside the `.claude-plugin/` directory. Only `plugin.json` goes inside `.claude-plugin/`. All other directories must be at the plugin root level.

178</Warning>

140 179

141* **Commands**: Create markdown files in `commands/` directory180| Directory | Location | Purpose |

142* **Agents**: Create agent definitions in `agents/` directory181| :---------------- | :---------- | :---------------------------------------------- |

143* **Skills**: Create `SKILL.md` files in `skills/` directory182| `.claude-plugin/` | Plugin root | Contains only `plugin.json` manifest (required) |

144* **Hooks**: Create `hooks/hooks.json` for event handling183| `commands/` | Plugin root | Slash commands as Markdown files |

145* **MCP servers**: Create `.mcp.json` for external tool integration184| `agents/` | Plugin root | Custom agent definitions |

185| `skills/` | Plugin root | Agent Skills with `SKILL.md` files |

186| `hooks/` | Plugin root | Event handlers in `hooks.json` |

187| `.mcp.json` | Plugin root | MCP server configurations |

188| `.lsp.json` | Plugin root | LSP server configurations for code intelligence |

146 189

147<Note>190<Note>

148 **Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, and MCP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/plugins-reference).191 **Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, MCP servers, and LSP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/plugins-reference).

149</Note>192</Note>

150 193

151***194## Develop more complex plugins

~~152~~

153## Install and manage plugins

~~154~~

155Learn how to discover, install, and manage plugins to extend your Claude Code capabilities.

156 195

157### Prerequisites196Once you're comfortable with basic plugins, you can create more sophisticated extensions.

158 197

159* Claude Code installed and running198### Add Skills to your plugin

160* Basic familiarity with command-line interfaces

161 199

162### Add marketplaces200Plugins can include [Agent Skills](/en/skills) to extend Claude's capabilities. Skills are model-invoked: Claude automatically uses them based on the task context.

163 201

164Marketplaces are catalogs of available plugins. Add them to discover and install plugins:202Add a `skills/` directory at your plugin root with Skill folders containing `SKILL.md` files:

165 203

166```shell Add a marketplace theme={null}

167/plugin marketplace add your-org/claude-plugins

168```204```

~~169~~ 205my-plugin/

170```shell Browse available plugins theme={null}206├── .claude-plugin/

171/plugin207│ └── plugin.json

208└── skills/

209 └── code-review/

210 └── SKILL.md

172```211```

173 212

174For detailed marketplace management including Git repositories, local development, and team distribution, see [Plugin marketplaces](/en/plugin-marketplaces).213Each `SKILL.md` needs frontmatter with `name` and `description` fields, followed by instructions:

175 214

176### Install plugins215```yaml theme={null}

216---

217name: code-review

218description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.

219---

177 220

178#### Via interactive menu (recommended for discovery)221When reviewing code, check for:

~~179~~ 2221. Code organization and structure

180```shell Open the plugin management interface theme={null}2232. Error handling

181/plugin2243. Security concerns

2254. Test coverage

182```226```

183 227

184Select "Browse Plugins" to see available options with descriptions, features, and installation options.228After installing the plugin, restart Claude Code to load the Skills. For complete Skill authoring guidance including progressive disclosure and tool restrictions, see [Agent Skills](/en/skills).

185 229

186#### Via direct commands (for quick installation)230### Add LSP servers to your plugin

187 231

188```shell Install a specific plugin theme={null}232<Tip>

189/plugin install formatter@your-org233 For common languages like TypeScript, Python, and Rust, install the pre-built LSP plugins from the official marketplace. Create custom LSP plugins only when you need support for languages not already covered.

190```234</Tip>

191 235

192```shell Enable a disabled plugin theme={null}236LSP (Language Server Protocol) plugins give Claude real-time code intelligence. If you need to support a language that doesn't have an official LSP plugin, you can create your own by adding an `.lsp.json` file to your plugin:

193/plugin enable plugin-name@marketplace-name

194```

195 237

196```shell Disable without uninstalling theme={null}238```json .lsp.json theme={null}

197/plugin disable plugin-name@marketplace-name239{

240 "go": {

241 "command": "gopls",

242 "args": ["serve"],

243 "extensionToLanguage": {

244 ".go": "go"

245 }

246 }

247}

198```248```

199 249

200```shell Completely remove a plugin theme={null}250Users installing your plugin must have the language server binary installed on their machine.

201/plugin uninstall plugin-name@marketplace-name

202```

203 251

204### Verify installation252For complete LSP configuration options, see [LSP servers](/en/plugins-reference#lsp-servers).

205 253

206After installing a plugin:254### Organize complex plugins

207 255

2081. **Check available commands**: Run `/help` to see new commands256For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/plugins-reference#plugin-directory-structure).

2092. **Test plugin features**: Try the plugin's commands and features

2103. **Review plugin details**: Use `/plugin` → "Manage Plugins" to see what the plugin provides

211 257

212## Set up team plugin workflows258### Test your plugins locally

213 259

214Configure plugins at the repository level to ensure consistent tooling across your team. When team members trust your repository folder, Claude Code automatically installs specified marketplaces and plugins.260Use the `--plugin-dir` flag to test plugins during development. This loads your plugin directly without requiring installation.

215 261

216**To set up team plugins:**262```bash theme={null}

263claude --plugin-dir ./my-plugin

264```

217 265

2181. Add marketplace and plugin configuration to your repository's `.claude/settings.json`266As you make changes to your plugin, restart Claude Code to pick up the updates. Test your plugin components:

2192. Team members trust the repository folder

2203. Plugins install automatically for all team members

221 267

222For complete instructions including configuration examples, marketplace setup, and rollout best practices, see [Configure team marketplaces](/en/plugin-marketplaces#how-to-configure-team-marketplaces).268* Try your commands with `/command-name`

269* Check that agents appear in `/agents`

270* Verify hooks work as expected

223 271

224***272<Tip>

273 You can load multiple plugins at once by specifying the flag multiple times:

225 274

226## Develop more complex plugins275 ```bash theme={null}

276 claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

277 ```

278</Tip>

227 279

228Once you're comfortable with basic plugins, you can create more sophisticated extensions.280### Debug plugin issues

229 281

230### Add Skills to your plugin282If your plugin isn't working as expected:

231 283

232Plugins can include [Agent Skills](/en/skills) to extend Claude's capabilities. Skills are model-invoked—Claude autonomously uses them based on the task context.2841. **Check the structure**: Ensure your directories are at the plugin root, not inside `.claude-plugin/`

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

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

233 287

234To add Skills to your plugin, create a `skills/` directory at your plugin root and add Skill folders with `SKILL.md` files. Plugin Skills are automatically available when the plugin is installed.288### Share your plugins

235 289

236For complete Skill authoring guidance, see [Agent Skills](/en/skills).290When your plugin is ready to share:

237 291

238### Organize complex plugins2921. **Add documentation**: Include a `README.md` with installation and usage instructions

2932. **Version your plugin**: Use [semantic versioning](/en/plugins-reference#version-management) in your `plugin.json`

2943. **Create or use a marketplace**: Distribute through [plugin marketplaces](/en/plugin-marketplaces) for installation

2954. **Test with others**: Have team members test the plugin before wider distribution

239 296

240For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/plugins-reference#plugin-directory-structure).297Once your plugin is in a marketplace, others can install it using the instructions in [Discover and install plugins](/en/discover-plugins).

241 298

242### Test your plugins locally299<Note>

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

301</Note>

243 302

244When developing plugins, use a local marketplace to test changes iteratively. This workflow builds on the quickstart pattern and works for plugins of any complexity.303## Convert existing configurations to plugins

245 304

246<Steps>305If you already have custom commands, Skills, or hooks in your `.claude/` directory, you can convert them into a plugin for easier sharing and distribution.

247 <Step title="Set up your development structure">

248 Organize your plugin and marketplace for testing:

249 306

250 ```bash Create directory structure theme={null}307### Migration steps

251 mkdir dev-marketplace

252 cd dev-marketplace

253 mkdir my-plugin

254 ```

255 308

256 This creates:309<Steps>

310 <Step title="Create the plugin structure">

311 Create a new plugin directory:

257 312

313 ```bash theme={null}

314 mkdir -p my-plugin/.claude-plugin

258 ```315 ```

259 dev-marketplace/

260 ├── .claude-plugin/marketplace.json (you'll create this)

261 └── my-plugin/ (your plugin under development)

262 ├── .claude-plugin/plugin.json

263 ├── commands/

264 ├── agents/

265 └── hooks/

266 ```

267 </Step>

268 316

269 <Step title="Create the marketplace manifest">317 Create the manifest file at `my-plugin/.claude-plugin/plugin.json`:

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

271 mkdir .claude-plugin319 ```json my-plugin/.claude-plugin/plugin.json theme={null}

272 cat > .claude-plugin/marketplace.json << 'EOF'

273 {

274 "name": "dev-marketplace",

275 "owner": {

276 "name": "Developer"

277 },

278 "plugins": [

279 {320 {

280 "name": "my-plugin",321 "name": "my-plugin",

281 "source": "./my-plugin",322 "description": "Migrated from standalone configuration",

282 "description": "Plugin under development"323 "version": "1.0.0"

283 }

284 ]

285 }324 }

286 EOF

287 ```325 ```

288 </Step>326 </Step>

289 327

290 <Step title="Install and test">328 <Step title="Copy your existing files">

291 ```bash Start Claude Code from parent directory theme={null}329 Copy your existing configurations to the plugin directory:

292 cd ..

293 claude

294 ```

~~295~~

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

297 /plugin marketplace add ./dev-marketplace

298 ```

299 330

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

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

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

303 334

304 Test your plugin components:335 # Copy agents (if any)

336 cp -r .claude/agents my-plugin/

305 337

306 * Try your commands with `/command-name`338 # Copy skills (if any)

307 * Check that agents appear in `/agents`339 cp -r .claude/skills my-plugin/

308 * Verify hooks work as expected340 ```

309 </Step>341 </Step>

310 342

311 <Step title="Iterate on your plugin">343 <Step title="Migrate hooks">

312 After making changes to your plugin code:344 If you have hooks in your settings, create a hooks directory:

313 345

314 ```shell Uninstall the current version theme={null}346 ```bash theme={null}

315 /plugin uninstall my-plugin@dev-marketplace347 mkdir my-plugin/hooks

316 ```348 ```

317 349

318 ```shell Reinstall to test changes theme={null}350 Create `my-plugin/hooks/hooks.json` with your hooks configuration. Copy the `hooks` object from your `.claude/settings.json` or `settings.local.json`—the format is the same:

319 /plugin install my-plugin@dev-marketplace

320 ```

321 351

322 Repeat this cycle as you develop and refine your plugin.352 ```json my-plugin/hooks/hooks.json theme={null}

353 {

354 "hooks": {

355 "PostToolUse": [

356 {

357 "matcher": "Write|Edit",

358 "hooks": [{ "type": "command", "command": "npm run lint:fix $FILE" }]

359 }

360 ]

361 }

362 }

363 ```

323 </Step>364 </Step>

324</Steps>

325 365

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

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

328</Note>

329 368

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

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

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

~~333~~

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

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

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

337 372

338### Share your plugins373 Test each component: run your commands, check agents appear in `/agents`, and verify hooks trigger correctly.

374 </Step>

375</Steps>

339 376

340When your plugin is ready to share:377### What changes when migrating

341 378

3421. **Add documentation**: Include a README.md with installation and usage instructions379| Standalone (`.claude/`) | Plugin |

3432. **Version your plugin**: Use semantic versioning in your `plugin.json`380| :---------------------------- | :------------------------------- |

3443. **Create or use a marketplace**: Distribute through plugin marketplaces for easy installation381| Only available in one project | Can be shared via marketplaces |

3454. **Test with others**: Have team members test the plugin before wider distribution382| Files in `.claude/commands/` | Files in `plugin-name/commands/` |

383| Hooks in `settings.json` | Hooks in `hooks/hooks.json` |

384| Must manually copy to share | Install with `/plugin install` |

346 385

347<Note>386<Note>

348 For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/plugins-reference).387 After migrating, you can remove the original files from `.claude/` to avoid duplicates. The plugin version will take precedence when loaded.

349</Note>388</Note>

350 389

351***

~~352~~

353## Next steps390## Next steps

354 391

355Now that you understand Claude Code's plugin system, here are suggested paths for different goals:392Now that you understand Claude Code's plugin system, here are suggested paths for different goals:

356 393

357### For plugin users394### For plugin users

358 395

359* **Discover plugins**: Browse community marketplaces for useful tools396* [Discover and install plugins](/en/discover-plugins): browse marketplaces and install plugins

360* **Team adoption**: Set up repository-level plugins for your projects397* [Configure team marketplaces](/en/discover-plugins#configure-team-marketplaces): set up repository-level plugins for your team

361* **Marketplace management**: Learn to manage multiple plugin sources

362* **Advanced usage**: Explore plugin combinations and workflows

363 398

364### For plugin developers399### For plugin developers

365 400

366* **Create your first marketplace**: [Plugin marketplaces guide](/en/plugin-marketplaces)401* [Create and distribute a marketplace](/en/plugin-marketplaces): package and share your plugins

367* **Advanced components**: Dive deeper into specific plugin components:402* [Plugins reference](/en/plugins-reference): complete technical specifications

368 * [Slash commands](/en/slash-commands) - Command development details403* Dive deeper into specific plugin components:

369 * [Subagents](/en/sub-agents) - Agent configuration and capabilities404 * [Slash commands](/en/slash-commands): command development details

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

371 * [Hooks](/en/hooks) - Event handling and automation406 * [Agent Skills](/en/skills): extend Claude's capabilities

372 * [MCP](/en/mcp) - External tool integration407 * [Hooks](/en/hooks): event handling and automation

373* **Distribution strategies**: Package and share your plugins effectively408 * [MCP](/en/mcp): external tool integration

374* **Community contribution**: Consider contributing to community plugin collections409

~~375~~ 410

376### For team leads and administrators411---

~~377~~ 412

378* **Repository configuration**: Set up automatic plugin installation for team projects413> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

379* **Plugin governance**: Establish guidelines for plugin approval and security review

380* **Marketplace maintenance**: Create and maintain organization-specific plugin catalogs

381* **Training and documentation**: Help team members adopt plugin workflows effectively

~~382~~

383## See also

~~384~~

385* [Plugin marketplaces](/en/plugin-marketplaces) - Creating and managing plugin catalogs

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

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

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

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

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

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

plugins-reference.md +391 −20

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.

120**Available events**:120**Available events**:

121 121

122* `PreToolUse`: Before Claude uses any tool122* `PreToolUse`: Before Claude uses any tool

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

124* `PostToolUseFailure`: After Claude tool execution fails

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

124* `PostToolUse`: After Claude uses any tool

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

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

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

129* `SubagentStart`: When a subagent is started

128* `SubagentStop`: When a subagent attempts to stop130* `SubagentStop`: When a subagent attempts to stop

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

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

133**Hook types**:135**Hook types**:

134 136

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

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

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

138 140

139### MCP servers141### MCP servers

140 142

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

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

174 176

177### LSP servers

178

179<Tip>

180 Looking to use LSP plugins? Install them from the official marketplace—search for "lsp" in the `/plugin` Discover tab. This section documents how to create LSP plugins for languages not covered by the official marketplace.

181</Tip>

182

183Plugins can provide [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) servers to give Claude real-time code intelligence while working on your codebase.

184

185LSP integration provides:

186

187* **Instant diagnostics**: Claude sees errors and warnings immediately after each edit

188* **Code navigation**: go to definition, find references, and hover information

189* **Language awareness**: type information and documentation for code symbols

190

191**Location**: `.lsp.json` in plugin root, or inline in `plugin.json`

192

193**Format**: JSON configuration mapping language server names to their configurations

194

195**`.lsp.json` file format**:

196

197```json theme={null}

198{

199 "go": {

200 "command": "gopls",

201 "args": ["serve"],

202 "extensionToLanguage": {

203 ".go": "go"

204 }

205 }

206}

207```

208

209**Inline in `plugin.json`**:

210

211```json theme={null}

212{

213 "name": "my-plugin",

214 "lspServers": {

215 "go": {

216 "command": "gopls",

217 "args": ["serve"],

218 "extensionToLanguage": {

219 ".go": "go"

220 }

221 }

222 }

223}

224```

225

226**Required fields:**

227

228| Field | Description |

229| :-------------------- | :------------------------------------------- |

230| `command` | The LSP binary to execute (must be in PATH) |

231| `extensionToLanguage` | Maps file extensions to language identifiers |

232

233**Optional fields:**

234

235| Field | Description |

236| :---------------------- | :-------------------------------------------------------- |

237| `args` | Command-line arguments for the LSP server |

238| `transport` | Communication transport: `stdio` (default) or `socket` |

239| `env` | Environment variables to set when starting the server |

240| `initializationOptions` | Options passed to the server during initialization |

241| `settings` | Settings passed via `workspace/didChangeConfiguration` |

242| `workspaceFolder` | Workspace folder path for the server |

243| `startupTimeout` | Max time to wait for server startup (milliseconds) |

244| `shutdownTimeout` | Max time to wait for graceful shutdown (milliseconds) |

245| `restartOnCrash` | Whether to automatically restart the server if it crashes |

246| `maxRestarts` | Maximum number of restart attempts before giving up |

247

248<Warning>

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

250</Warning>

251

252**Available LSP plugins:**

253

254| Plugin | Language server | Install command |

255| :--------------- | :------------------------- | :----------------------------------------------------------------------------------------- |

256| `pyright-lsp` | Pyright (Python) | `pip install pyright` or `npm install -g pyright` |

257| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |

258| `rust-lsp` | rust-analyzer | [See rust-analyzer installation](https://rust-analyzer.github.io/manual.html#installation) |

259

260Install the language server first, then install the plugin from the marketplace.

261

262***

263

264## Plugin installation scopes

265

266When you install a plugin, you choose a **scope** that determines where the plugin is available and who else can use it:

267

268| Scope | Settings file | Use case |

269| :-------- | :---------------------------- | :------------------------------------------------------- |

270| `user` | `~/.claude/settings.json` | Personal plugins available across all projects (default) |

271| `project` | `.claude/settings.json` | Team plugins shared via version control |

272| `local` | `.claude/settings.local.json` | Project-specific plugins, gitignored |

273| `managed` | `managed-settings.json` | Managed plugins (read-only, update only) |

274

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

276

175***277***

176 278

177## Plugin manifest schema279## Plugin manifest schema

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

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

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

301 "skills": "./custom/skills/",

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

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

304 "outputStyles": "./styles/",

305 "lspServers": "./.lsp.json"

201}306}

202```307```

203 308

222### Component path fields327### Component path fields

223 328

225| :----------- | :------------- | :----------------------------------- | :------------------------------------- |330| :------------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- |

230 338

231### Path behavior rules339### Path behavior rules

232 340

275 383

276***384***

277 385

386## Plugin caching and file resolution

387

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

389

390### How plugin caching works

391

392When you install a plugin, Claude Code copies the plugin files to a cache directory:

393

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

395* **For plugins with `.claude-plugin/plugin.json`**: The implicit root directory (the directory containing `.claude-plugin/plugin.json`) is copied recursively.

396

397### Path traversal limitations

398

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

400

401### Working with external dependencies

402

403If your plugin needs to access files outside its directory, you have two options:

404

405**Option 1: Use symlinks**

406

407Create symbolic links to external files within your plugin directory. Symlinks are honored during the copy process:

408

409```bash theme={null}

410# Inside your plugin directory

411ln -s /path/to/shared-utils ./shared-utils

412```

413

414The symlinked content will be copied into the plugin cache.

415

416**Option 2: Restructure your marketplace**

417

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

419

420```json theme={null}

421{

422 "name": "my-plugin",

423 "source": "./",

424 "description": "Plugin that needs root-level access",

425 "commands": ["./plugins/my-plugin/commands/"],

426 "agents": ["./plugins/my-plugin/agents/"],

427 "strict": false

428}

429```

430

431This approach copies the entire marketplace root, giving your plugin access to sibling directories.

432

433<Note>

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

435</Note>

436

437***

438

278## Plugin directory structure439## Plugin directory structure

279 440

280### Standard plugin layout441### Standard plugin layout

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

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

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

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

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

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

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

320| :-------------- | :--------------------------- | :------------------------------- |482| :-------------- | :--------------------------- | :------------------------------- |

489| **LSP servers** | `.lsp.json` | Language server configurations |

490

491***

492

493## CLI commands reference

494

495Claude Code provides CLI commands for non-interactive plugin management, useful for scripting and automation.

496

497### plugin install

498

499Install a plugin from available marketplaces.

500

501```bash theme={null}

502claude plugin install <plugin> [options]

503```

504

505**Arguments:**

506

507* `<plugin>`: Plugin name or `plugin-name@marketplace-name` for a specific marketplace

508

509**Options:**

510

511| Option | Description | Default |

512| :-------------------- | :------------------------------------------------ | :------ |

513| `-s, --scope <scope>` | Installation scope: `user`, `project`, or `local` | `user` |

514| `-h, --help` | Display help for command | |

515

516**Examples:**

517

518```bash theme={null}

519# Install to user scope (default)

520claude plugin install formatter@my-marketplace

521

522# Install to project scope (shared with team)

523claude plugin install formatter@my-marketplace --scope project

524

525# Install to local scope (gitignored)

526claude plugin install formatter@my-marketplace --scope local

527```

528

529### plugin uninstall

530

531Remove an installed plugin.

532

533```bash theme={null}

534claude plugin uninstall <plugin> [options]

535```

536

537**Arguments:**

538

539* `<plugin>`: Plugin name or `plugin-name@marketplace-name`

540

541**Options:**

542

543| Option | Description | Default |

544| :-------------------- | :-------------------------------------------------- | :------ |

545| `-s, --scope <scope>` | Uninstall from scope: `user`, `project`, or `local` | `user` |

546| `-h, --help` | Display help for command | |

547

548**Aliases:** `remove`, `rm`

549

550### plugin enable

551

552Enable a disabled plugin.

553

554```bash theme={null}

555claude plugin enable <plugin> [options]

556```

557

558**Arguments:**

559

560* `<plugin>`: Plugin name or `plugin-name@marketplace-name`

561

562**Options:**

563

564| Option | Description | Default |

565| :-------------------- | :--------------------------------------------- | :------ |

566| `-s, --scope <scope>` | Scope to enable: `user`, `project`, or `local` | `user` |

567| `-h, --help` | Display help for command | |

568

569### plugin disable

570

571Disable a plugin without uninstalling it.

572

573```bash theme={null}

574claude plugin disable <plugin> [options]

575```

576

577**Arguments:**

578

579* `<plugin>`: Plugin name or `plugin-name@marketplace-name`

580

581**Options:**

582

583| Option | Description | Default |

584| :-------------------- | :---------------------------------------------- | :------ |

585| `-s, --scope <scope>` | Scope to disable: `user`, `project`, or `local` | `user` |

586| `-h, --help` | Display help for command | |

587

588### plugin update

589

590Update a plugin to the latest version.

591

592```bash theme={null}

593claude plugin update <plugin> [options]

594```

595

596**Arguments:**

597

598* `<plugin>`: Plugin name or `plugin-name@marketplace-name`

599

600**Options:**

601

602| Option | Description | Default |

603| :-------------------- | :-------------------------------------------------------- | :------ |

604| `-s, --scope <scope>` | Scope to update: `user`, `project`, `local`, or `managed` | `user` |

605| `-h, --help` | Display help for command | |

327 606

328***607***

329 608

347### Common issues626### Common issues

348 627

350| :--------------------- | :------------------------------ | :--------------------------------------------------- |629| :---------------------------------- | :------------------------------ | :-------------------------------------------------------------------------------- |

354| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths |633| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths |

635| LSP `Executable not found in $PATH` | Language server not installed | Install the binary (e.g., `npm install -g typescript-language-server typescript`) |

636

637### Example error messages

638

639**Manifest validation errors**:

640

641* `Invalid JSON syntax: Unexpected token } in JSON at position 142`: check for missing commas, extra commas, or unquoted strings

642* `Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required`: a required field is missing

643* `Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...`: JSON syntax error

644

645**Plugin loading errors**:

646

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

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

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

650

651### Hook troubleshooting

652

653**Hook script not executing**:

654

6551. Check the script is executable: `chmod +x ./scripts/your-script.sh`

6562. Verify the shebang line: First line should be `#!/bin/bash` or `#!/usr/bin/env bash`

6573. Check the path uses `${CLAUDE_PLUGIN_ROOT}`: `"command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"`

6584. Test the script manually: `./scripts/your-script.sh`

659

660**Hook not triggering on expected events**:

661

6621. Verify the event name is correct (case-sensitive): `PostToolUse`, not `postToolUse`

6632. Check the matcher pattern matches your tools: `"matcher": "Write|Edit"` for file operations

6643. Confirm the hook type is valid: `command`, `prompt`, or `agent`

665

666### MCP server troubleshooting

667

668**Server not starting**:

669

6701. Check the command exists and is executable

6712. Verify all paths use `${CLAUDE_PLUGIN_ROOT}` variable

6723. Check the MCP server logs: `claude --debug` shows initialization errors

6734. Test the server manually outside of Claude Code

674

675**Server tools not appearing**:

676

6771. Ensure the server is properly configured in `.mcp.json` or `plugin.json`

6782. Verify the server implements the MCP protocol correctly

6793. Check for connection timeouts in debug output

680

681### Directory structure mistakes

682

683**Symptoms**: Plugin loads but components (commands, agents, hooks) are missing.

684

685**Correct structure**: Components must be at the plugin root, not inside `.claude-plugin/`. Only `plugin.json` belongs in `.claude-plugin/`.

686

687```

688my-plugin/

689├── .claude-plugin/

690│ └── plugin.json ← Only manifest here

691├── commands/ ← At root level

692├── agents/ ← At root level

693└── hooks/ ← At root level

694```

695

696If your components are inside `.claude-plugin/`, move them to the plugin root.

697

698**Debug checklist**:

699

7001. Run `claude --debug` and look for "loading plugin" messages

7012. Check that each component directory is listed in the debug output

7023. Verify file permissions allow reading the plugin files

356 703

357***704***

358 705

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

364 711

365```json theme={null}712```json theme={null}

713{

714 "name": "my-plugin",

715 "version": "2.1.0"

716}

717```

718

719**Version format**: `MAJOR.MINOR.PATCH`

720

721* **MAJOR**: Breaking changes (incompatible API changes)

722* **MINOR**: New features (backward-compatible additions)

723* **PATCH**: Bug fixes (backward-compatible fixes)

724

725**Best practices**:

726

727* Start at `1.0.0` for your first stable release

728* Update the version in `plugin.json` before distributing changes

729* Document changes in a `CHANGELOG.md` file

730* Use pre-release versions like `2.0.0-beta.1` for testing

731

732***

366 733

367## See also734## See also

368 735

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

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

371- [Slash commands](/en/slash-commands) - Command development details738* [Slash commands](/en/slash-commands) - Command development details

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

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

374- [Hooks](/en/hooks) - Event handling and automation741* [Hooks](/en/hooks) - Event handling and automation

375- [MCP](/en/mcp) - External tool integration742* [MCP](/en/mcp) - External tool integration

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

377```744

745

746---

747

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

quickstart.md +34 −15

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.

241Here are the most important commands for daily use:251Here are the most important commands for daily use:

242 252

244| ------------------- | --------------------------------- | ----------------------------------- |254| ------------------- | ------------------------------------------------------ | ----------------------------------- |

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

Details

66> /sandbox66> /sandbox

67```67```

68 68

~~69This activates the sandboxed bash tool with default settings, allowing access to your current working directory while blocking access to sensitive system locations.~~69This opens a menu where you can choose between sandbox modes.

71### Sandbox modes

73Claude Code offers two sandbox modes:

75**Auto-allow mode**: Bash commands will attempt to run inside the sandbox and are automatically allowed without requiring permission. Commands that cannot be sandboxed (such as those needing network access to non-allowed hosts) fall back to the regular permission flow. Explicit ask/deny rules you've configured are always respected.

77**Regular permissions mode**: All bash commands go through the standard permission flow, even when sandboxed. This provides more control but requires more approvals.

79In both modes, the sandbox enforces the same filesystem and network restrictions. The difference is only in whether sandboxed commands are auto-approved or require explicit permission.

81<Info>

82 Auto-allow mode works independently of your permission mode setting. Even if you're not in "accept edits" mode, sandboxed bash commands will run automatically when auto-allow is enabled. This means bash commands that modify files within the sandbox boundaries will execute without prompting, even when file edit tools would normally require approval.

83</Info>

70 84

71### Configure sandboxing85### Configure sandboxing

72 86

141 155

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

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

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

145 159

146## Advanced usage160## Advanced usage

147 161

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 +6 −1

Details

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 +596 −65

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) 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 rules use pattern matching and can be bypassed using shell features like command flags, variables, or redirects. For example, `Bash(curl:*)` can be bypassed with `curl -X GET` reordered to `curl http://example.com -X GET`. Do not rely on Bash deny rules as a security boundary.

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* **Slash commands**: Custom commands that can be invoked during a session with `/command-name`

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{

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 slash command metadata shown to the [Skill tool](/en/slash-commands#skill-tool) (default: 15000) |

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 or slash command](/en/slash-commands#skill-tool) 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

939* [Managed settings](/en/iam#managed-settings) - Managed policy configuration for organizations

414* [Troubleshooting](/en/troubleshooting#auto-updater-issues) - Solutions for common configuration issues940* [Troubleshooting](/en/troubleshooting#auto-updater-issues) - 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 +229 −104

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

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 [configure Claude Code](/en/troubleshooting#linux-permission-issues) 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 +357 −369

Details

2 2

3> Create, manage, and share Skills to extend Claude's capabilities in Claude Code.3> Create, manage, and share Skills to extend Claude's capabilities in Claude Code.

4 4

5This guide shows you how to create, use, and manage Agent Skills in Claude Code. Skills are modular capabilities that extend Claude's functionality through organized folders containing instructions, scripts, and resources.5This guide shows you how to create, use, and manage Agent Skills in Claude Code. For background on how Skills work across Claude products, see [What are Skills?](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).

6 6

~~7## Prerequisites~~7A Skill is a markdown file that teaches Claude how to do something specific: reviewing PRs using your team's standards, generating commit messages in your preferred format, or querying your company's database schema. When you ask Claude something that matches a Skill's purpose, Claude automatically applies it.

8 8

~~9* Claude Code version 1.0 or later~~9## Create your first Skill

~~10* Basic familiarity with [Claude Code](/en/quickstart)~~

11 10

~~12## What are Agent Skills?~~11This example creates a personal Skill that teaches Claude to explain code using visual diagrams and analogies. Unlike Claude's default explanations, this Skill ensures every explanation includes an ASCII diagram and a real-world analogy.

13 12

14Agent Skills package expertise into discoverable capabilities. Each Skill consists of a `SKILL.md` file with instructions that Claude reads when relevant, plus optional supporting files like scripts and templates.13<Steps>

14 <Step title="Check available Skills">

15 Before creating a Skill, see what Skills Claude already has access to:

15 16

16**How Skills are invoked**: Skills are **model-invoked**—Claude autonomously decides when to use them based on your request and the Skill's description. This is different from slash commands, which are **user-invoked** (you explicitly type `/command` to trigger them).17 ```

18 What Skills are available?

19 ```

17 20

~~18**Benefits**:~~21 Claude will list any Skills currently loaded. You may see none, or you may see Skills from plugins or your organization.

22 </Step>

19 23

~~20* Extend Claude's capabilities for your specific workflows~~24 <Step title="Create the Skill directory">

~~21* Share expertise across your team via git~~25 Create a directory for the Skill in your personal Skills folder. Personal Skills are available across all your projects. (You can also create [project Skills](#where-skills-live) in `.claude/skills/` to share with your team.)

~~22* Reduce repetitive prompting~~

~~23* Compose multiple Skills for complex tasks~~

24 26

~~25Learn more in the [Agent Skills overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview).~~27 ```bash theme={null}

28 mkdir -p ~/.claude/skills/explaining-code

29 ```

30 </Step>

26 31

~~27<Note>~~32 <Step title="Write SKILL.md">

28 For a deep dive into the architecture and real-world applications of Agent Skills, read our engineering blog: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).33 Every Skill needs a `SKILL.md` file. The file starts with YAML metadata between `---` markers and must include a `name` and `description`, followed by Markdown instructions that Claude follows when the Skill is active.

~~29</Note>~~

30 34

~~31## Create a Skill~~35 The `description` is especially important, because Claude uses it to decide when to apply the Skill.

32 36

~~33Skills are stored as directories containing a `SKILL.md` file.~~37 Create `~/.claude/skills/explaining-code/SKILL.md`:

34 38

~~35### Personal Skills~~39 ```yaml theme={null}

40 ---

41 name: explaining-code

42 description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"

43 ---

36 44

~~37Personal Skills are available across all your projects. Store them in `~/.claude/skills/`:~~45 When explaining code, always include:

38 46

~~39```bash theme={null}~~47 1. **Start with an analogy**: Compare the code to something from everyday life

~~40mkdir -p ~/.claude/skills/my-skill-name~~48 2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships

~~41```~~49 3. **Walk through the code**: Explain step-by-step what happens

50 4. **Highlight a gotcha**: What's a common mistake or misconception?

42 51

~~43**Use personal Skills for**:~~52 Keep explanations conversational. For complex concepts, use multiple analogies.

53 ```

54 </Step>

44 55

~~45* Your individual workflows and preferences~~56 <Step title="Load and verify the Skill">

~~46* Experimental Skills you're developing~~57 Skills are automatically loaded when created or modified. Verify the Skill appears in the list:

~~47* Personal productivity tools~~

48 58

~~49### Project Skills~~59 ```

60 What Skills are available?

61 ```

50 62

~~51Project Skills are shared with your team. Store them in `.claude/skills/` within your project:~~63 You should see `explaining-code` in the list with its description.

64 </Step>

52 65

~~53```bash theme={null}~~66 <Step title="Test the Skill">

~~54mkdir -p .claude/skills/my-skill-name~~67 Open any file in your project and ask Claude a question that matches the Skill's description:

~~55```~~

56 68

~~57**Use project Skills for**:~~69 ```

70 How does this code work?

71 ```

58 72

~~59* Team workflows and conventions~~73 Claude should ask to use the `explaining-code` Skill, then include an analogy and ASCII diagram in its explanation. If the Skill doesn't trigger, try rephrasing to include more keywords from the description, like "explain how this works."

~~60* Project-specific expertise~~74 </Step>

~~61* Shared utilities and scripts~~75</Steps>

62 76

~~63Project Skills are checked into git and automatically available to team members.~~77The rest of this guide covers how Skills work, configuration options, and troubleshooting.

64 78

~~65### Plugin Skills~~79## How Skills work

66 80

67Skills can also come from [Claude Code plugins](/en/plugins). Plugins may bundle Skills that are automatically available when the plugin is installed. These Skills work the same way as personal and project Skills.81Skills are **model-invoked**: Claude decides which Skills to use based on your request. You don't need to explicitly call a Skill. Claude automatically applies relevant Skills when your request matches their description.

68 82

~~69## Write SKILL.md~~83When you send a request, Claude follows these steps to find and use relevant Skills:

70 84

~~71Create a `SKILL.md` file with YAML frontmatter and Markdown content:~~85<Steps>

86 <Step title="Discovery">

87 At startup, Claude loads only the name and description of each available Skill. This keeps startup fast while giving Claude enough context to know when each Skill might be relevant.

88 </Step>

72 89

~~73```yaml theme={null}~~90 <Step title="Activation">

~~74name: your-skill-name~~91 When your request matches a Skill's description, Claude asks to use the Skill. You'll see a confirmation prompt before the full `SKILL.md` is loaded into context. Since Claude reads these descriptions to find relevant Skills, [write descriptions](#skill-not-triggering) that include keywords users would naturally say.

~~75description: Brief description of what this Skill does and when to use it~~92 </Step>

76 93

~~77# Your Skill Name~~94 <Step title="Execution">

95 Claude follows the Skill's instructions, loading referenced files or running bundled scripts as needed.

96 </Step>

97</Steps>

78 98

~~79## Instructions~~99### Where Skills live

~~80Provide clear, step-by-step guidance for Claude.~~

81 100

~~82## Examples~~101Where you store a Skill determines who can use it:

~~83Show concrete examples of using this Skill.~~

~~84```~~

85 102

~~86**Field requirements**:~~103| Location | Path | Applies to |

104| :--------- | :----------------------------------------------- | :-------------------------------- |

105| Enterprise | See [managed settings](/en/iam#managed-settings) | All users in your organization |

106| Personal | `~/.claude/skills/` | You, across all projects |

107| Project | `.claude/skills/` | Anyone working in this repository |

108| Plugin | Bundled with [plugins](/en/plugins) | Anyone with the plugin installed |

87 109

~~88* `name`: Must use lowercase letters, numbers, and hyphens only (max 64 characters)~~110If two Skills have the same name, the higher row wins: managed overrides personal, personal overrides project, and project overrides plugin.

~~89* `description`: Brief description of what the Skill does and when to use it (max 1024 characters)~~

90 111

~~91The `description` field is critical for Claude to discover when to use your Skill. It should include both what the Skill does and when Claude should use it.~~112#### Automatic discovery from nested directories

92 113

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

94 115

~~95## Add supporting files~~116### When to use Skills versus other options

96 117

~~97Create additional files alongside SKILL.md:~~118Claude Code offers several ways to customize behavior. The key difference: **Skills are triggered automatically by Claude** based on your request, while slash commands require you to type `/command` explicitly.

98 119

~~99```~~120| Use this | When you want to... | When it runs |

100my-skill/121| :--------------------------------------- | :------------------------------------------------------------------------- | :----------------------------------------- |

101├── SKILL.md (required)122| **Skills** | Give Claude specialized knowledge (e.g., "review PRs using our standards") | Claude chooses when relevant |

102├── reference.md (optional documentation)123| **[Slash commands](/en/slash-commands)** | Create reusable prompts (e.g., `/deploy staging`) | You type `/command` to run it |

103├── examples.md (optional examples)124| **[CLAUDE.md](/en/memory)** | Set project-wide instructions (e.g., "use TypeScript strict mode") | Loaded into every conversation |

104├── scripts/125| **[Subagents](/en/sub-agents)** | Delegate tasks to a separate context with its own tools | Claude delegates, or you invoke explicitly |

105│ └── helper.py (optional utility)126| **[Hooks](/en/hooks)** | Run scripts on events (e.g., lint on file save) | Fires on specific tool events |

106└── templates/127| **[MCP servers](/en/mcp)** | Connect Claude to external tools and data sources | Claude calls MCP tools as needed |

107 └── template.txt (optional template)

108```

109 128

110Reference these files from SKILL.md:129**Skills vs. subagents**: Skills add knowledge to the current conversation. Subagents run in a separate context with their own tools. Use Skills for guidance and standards; use subagents when you need isolation or different tool access.

111 130

112````markdown theme={null}131**Skills vs. MCP**: Skills tell Claude *how* to use tools; MCP *provides* the tools. For example, an MCP server connects Claude to your database, while a Skill teaches Claude your data model and query patterns.

113For advanced usage, see [reference.md](reference.md).

114 132

115Run the helper script:133<Note>

116```bash134 For a deep dive into the architecture and real-world applications of Agent Skills, read [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).

117python scripts/helper.py input.txt135</Note>

118```136

119````137## Configure Skills

120 138

121Claude reads these files only when needed, using progressive disclosure to manage context efficiently.139This section covers Skill file structure, supporting files, tool restrictions, and distribution options.

122 140

123## Restrict tool access with allowed-tools141### Write SKILL.md

124 142

125Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active:143The `SKILL.md` file is the only required file in a Skill. It has two parts: YAML metadata (the section between `---` markers) at the top, and Markdown instructions that tell Claude how to use the Skill:

126 144

127```yaml theme={null}145```yaml theme={null}

128---146---

129name: safe-file-reader147name: your-skill-name

130description: Read files without making changes. Use when you need read-only file access.148description: Brief description of what this Skill does and when to use it

131allowed-tools: Read, Grep, Glob

132---149---

133 150

134# Safe File Reader151# Your Skill Name

~~135~~

136This Skill provides read-only file access.

137 152

138## Instructions153## Instructions

1391. Use Read to view file contents154Provide clear, step-by-step guidance for Claude.

1402. Use Grep to search within files

1413. Use Glob to find files by pattern

142```

~~143~~

144When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for:

~~145~~

146* Read-only Skills that shouldn't modify files

147* Skills with limited scope (e.g., only data analysis, no file writing)

148* Security-sensitive workflows where you want to restrict capabilities

~~149~~

150If `allowed-tools` is not specified, Claude will ask for permission to use tools as normal, following the standard permission model.

~~151~~

152<Note>

153 `allowed-tools` is only supported for Skills in Claude Code.

154</Note>

~~155~~

156## View available Skills

~~157~~

158Skills are automatically discovered by Claude from three sources:

~~159~~

160* Personal Skills: `~/.claude/skills/`

161* Project Skills: `.claude/skills/`

162* Plugin Skills: bundled with installed plugins

~~163~~

164**To view all available Skills**, ask Claude directly:

~~165~~

166```

167What Skills are available?

168```

~~169~~

170or

~~171~~

172```

173List all available Skills

174```

~~175~~

176This will show all Skills from all sources, including plugin Skills.

~~177~~

178**To inspect a specific Skill**, you can also check the filesystem:

~~179~~

180```bash theme={null}

181# List personal Skills

182ls ~/.claude/skills/

~~183~~

184# List project Skills (if in a project directory)

185ls .claude/skills/

~~186~~

187# View a specific Skill's content

188cat ~/.claude/skills/my-skill/SKILL.md

189```

~~190~~

191## Test a Skill

~~192~~

193After creating a Skill, test it by asking questions that match your description.

~~194~~

195**Example**: If your description mentions "PDF files":

196 155

197```156## Examples

198Can you help me extract text from this PDF?157Show concrete examples of using this Skill.

199```158```

200 159

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.160#### Available metadata fields

202 161

203## Debug a Skill162You can use the following fields in the YAML frontmatter:

204 163

205If Claude doesn't use your Skill, check these common issues:164| Field | Required | Description |

165| :--------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

166| `name` | Yes | Skill name. Must use lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. |

167| `description` | Yes | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill. |

168| `allowed-tools` | No | Tools Claude can use without asking permission when this Skill is active. Supports comma-separated values or YAML-style lists. See [Restrict tool access](#restrict-tool-access-with-allowed-tools). |

169| `model` | No | [Model](https://docs.claude.com/en/docs/about-claude/models/overview) to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model. |

170| `context` | No | Set to `fork` to run the Skill in a forked sub-agent context with its own conversation history. |

171| `agent` | No | Specify which [agent type](/en/sub-agents#built-in-subagents) to use when `context: fork` is set (e.g., `Explore`, `Plan`, `general-purpose`, or a custom agent name from `.claude/agents/`). Defaults to `general-purpose` if not specified. Only applicable when combined with `context: fork`. |

172| `hooks` | No | Define hooks scoped to this Skill's lifecycle. Supports `PreToolUse`, `PostToolUse`, and `Stop` events. |

173| `user-invocable` | No | Controls whether the Skill appears in the slash command menu. Does not affect the [`Skill` tool](/en/slash-commands#skill-tool) or automatic discovery. Defaults to `true`. See [Control Skill visibility](#control-skill-visibility). |

206 174

207### Make description specific175#### Available string substitutions

208 176

209**Too vague**:177Skills support string substitution for dynamic values in the Skill content:

210 178

211```yaml theme={null}179| Variable | Description |

212description: Helps with documents180| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |

213```181| `$ARGUMENTS` | All arguments passed when invoking the Skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: <value>`. |

182| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating Skill output with sessions. |

214 183

215**Specific**:184**Example using substitutions:**

216 185

217```yaml theme={null}186```yaml theme={null}

218description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.187---

219```188name: session-logger

~~220~~ 189description: Log activity for this session

221Include both what the Skill does and when to use it in the description.190---

~~222~~

223### Verify file path

~~224~~

225**Personal Skills**: `~/.claude/skills/skill-name/SKILL.md`

226**Project Skills**: `.claude/skills/skill-name/SKILL.md`

~~227~~

228Check the file exists:

~~229~~

230```bash theme={null}

231# Personal

232ls ~/.claude/skills/my-skill/SKILL.md

~~233~~

234# Project

235ls .claude/skills/my-skill/SKILL.md

236```

~~237~~

238### Check YAML syntax

239 191

240Invalid YAML prevents the Skill from loading. Verify the frontmatter:192Log the following to logs/${CLAUDE_SESSION_ID}.log:

241 193

242```bash theme={null}194$ARGUMENTS

243cat SKILL.md | head -n 10

244```195```

245 196

246Ensure:197See the [best practices guide](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) for complete authoring guidance including validation rules.

~~247~~

248* Opening `---` on line 1

249* Closing `---` before Markdown content

250* Valid YAML syntax (no tabs, correct indentation)

~~251~~

252### View errors

~~253~~

254Run Claude Code with debug mode to see Skill loading errors:

~~255~~

256```bash theme={null}

257claude --debug

258```

259 198

260## Share Skills with your team199### Update or delete a Skill

261 200

262**Recommended approach**: Distribute Skills through [plugins](/en/plugins).201To update a Skill, edit its `SKILL.md` file directly. To remove a Skill, delete its directory. Changes take effect immediately.

263 202

264To share Skills via plugin:203### Add supporting files with progressive disclosure

265 204

2661. Create a plugin with Skills in the `skills/` directory205Skills share Claude's context window with conversation history, other Skills, and your request. To keep context focused, use **progressive disclosure**: put essential information in `SKILL.md` and detailed reference material in separate files that Claude reads only when needed.

2672. Add the plugin to a marketplace

2683. Team members install the plugin

269 206

270For complete instructions, see [Add Skills to your plugin](/en/plugins#add-skills-to-your-plugin).207This approach lets you bundle comprehensive documentation, examples, and scripts without consuming context upfront. Claude loads additional files only when the task requires them.

271 208

272You can also share Skills directly through project repositories:209<Tip>Keep `SKILL.md` under 500 lines for optimal performance. If your content exceeds this, split detailed reference material into separate files.</Tip>

273 210

274### Step 1: Add Skill to your project211#### Example: multi-file Skill structure

275 212

276Create a project Skill:213Claude discovers supporting files through links in your `SKILL.md`. The following example shows a Skill with detailed documentation in separate files and utility scripts that Claude can execute without reading:

277 214

278```bash theme={null}

279mkdir -p .claude/skills/team-skill

280# Create SKILL.md

281```215```

~~282~~ 216my-skill/

283### Step 2: Commit to git217├── SKILL.md (required - overview and navigation)

~~284~~ 218├── reference.md (detailed API docs - loaded when needed)

285```bash theme={null}219├── examples.md (usage examples - loaded when needed)

286git add .claude/skills/220└── scripts/

287git commit -m "Add team Skill for PDF processing"221 └── helper.py (utility script - executed, not loaded)

288git push

289```222```

290 223

291### Step 3: Team members get Skills automatically224The `SKILL.md` file references these supporting files so Claude knows they exist:

292 225

293When team members pull the latest changes, Skills are immediately available:226````markdown theme={null}

227## Overview

294 228

295```bash theme={null}229[Essential instructions here]

296git pull

297claude # Skills are now available

298```

299 230

300## Update a Skill231## Additional resources

301 232

302Edit SKILL.md directly:233- For complete API details, see [reference.md](reference.md)

234- For usage examples, see [examples.md](examples.md)

303 235

304```bash theme={null}236## Utility scripts

305# Personal Skill

306code ~/.claude/skills/my-skill/SKILL.md

307 237

308# Project Skill238To validate input files, run the helper script. It checks for required fields and returns any validation errors:

309code .claude/skills/my-skill/SKILL.md239```bash

240python scripts/helper.py input.txt

310```241```

242````

311 243

312Changes take effect the next time you start Claude Code. If Claude Code is already running, restart it to load the updates.244<Tip>Keep references one level deep. Link directly from `SKILL.md` to reference files. Deeply nested references (file A links to file B which links to file C) may result in Claude partially reading files.</Tip>

313 245

314## Remove a Skill246**Bundle utility scripts for zero-context execution.** Scripts in your Skill directory can be executed without loading their contents into context. Claude runs the script and only the output consumes tokens. This is useful for:

315 247

316Delete the Skill directory:248* Complex validation logic that would be verbose to describe in prose

249* Data processing that's more reliable as tested code than generated code

250* Operations that benefit from consistency across uses

317 251

318```bash theme={null}252In `SKILL.md`, tell Claude to run the script rather than read it:

319# Personal

320rm -rf ~/.claude/skills/my-skill

321 253

322# Project254```markdown theme={null}

323rm -rf .claude/skills/my-skill255Run the validation script to check the form:

324git commit -m "Remove unused Skill"256python scripts/validate_form.py input.pdf

325```257```

326 258

327## Best practices259For complete guidance on structuring Skills, see the [best practices guide](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns).

~~328~~

329### Keep Skills focused

~~330~~

331One Skill should address one capability:

~~332~~

333**Focused**:

~~334~~

335* "PDF form filling"

336* "Excel data analysis"

337* "Git commit messages"

~~338~~

339**Too broad**:

~~340~~

341* "Document processing" (split into separate Skills)

342* "Data tools" (split by data type or operation)

343 260

344### Write clear descriptions261### Restrict tool access with allowed-tools

345 262

346Help Claude discover when to use Skills by including specific triggers in your description:263Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active. You can specify tools as a comma-separated string or a YAML list:

~~347~~

348**Clear**:

349 264

350```yaml theme={null}265```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.266---

267name: reading-files-safely

268description: Read files without making changes. Use when you need read-only file access.

269allowed-tools: Read, Grep, Glob

270---

352```271```

353 272

354**Vague**:273Or use YAML-style lists for better readability:

355 274

356```yaml theme={null}275```yaml theme={null}

357description: For files276---

358```277name: reading-files-safely

~~359~~ 278description: Read files without making changes. Use when you need read-only file access.

360### Test with your team279allowed-tools:

~~361~~ 280 - Read

362Have teammates use Skills and provide feedback:281 - Grep

~~363~~ 282 - Glob

364* Does the Skill activate when expected?283---

365* Are the instructions clear?

366* Are there missing examples or edge cases?

~~367~~

368### Document Skill versions

~~369~~

370You can document Skill versions in your SKILL.md content to track changes over time. Add a version history section:

~~371~~

372```markdown theme={null}

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

380 285

381This helps team members understand what changed between versions.286When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for:

~~382~~

383## Troubleshooting

384 287

385### Claude doesn't use my Skill288* Read-only Skills that shouldn't modify files

289* Skills with limited scope: for example, only data analysis, no file writing

290* Security-sensitive workflows where you want to restrict capabilities

386 291

387**Symptom**: You ask a relevant question but Claude doesn't use your Skill.292If `allowed-tools` is omitted, the Skill doesn't restrict tools. Claude uses its standard permission model and may ask you to approve tool usage.

388 293

389**Check**: Is the description specific enough?294<Note>

295 `allowed-tools` is only supported for Skills in Claude Code.

296</Note>

390 297

391Vague descriptions make discovery difficult. Include both what the Skill does and when to use it, with key terms users would mention.298### Run Skills in a forked context

392 299

393**Too generic**:300Use `context: fork` to run a Skill in an isolated sub-agent context with its own conversation history. This is useful for Skills that perform complex multi-step operations without cluttering the main conversation:

394 301

395```yaml theme={null}302```yaml theme={null}

396description: Helps with data303---

304name: code-analysis

305description: Analyze code quality and generate detailed reports

306context: fork

307---

397```308```

398 309

399**Specific**:310### Define hooks for Skills

311

312Skills can define hooks that run during the Skill's lifecycle. Use the `hooks` field to specify `PreToolUse`, `PostToolUse`, or `Stop` handlers:

400 313

401```yaml theme={null}314```yaml theme={null}

402description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.315---

316name: secure-operations

317description: Perform operations with additional security checks

318hooks:

319 PreToolUse:

320 - matcher: "Bash"

321 hooks:

322 - type: command

323 command: "./scripts/security-check.sh $TOOL_INPUT"

324 once: true

325---

403```326```

404 327

405**Check**: Is the YAML valid?328The `once: true` option runs the hook only once per session. After the first successful execution, the hook is removed.

406 329

407Run validation to check for syntax errors:330Hooks defined in a Skill are scoped to that Skill's execution and are automatically cleaned up when the Skill finishes.

408 331

409```bash theme={null}332See [Hooks](/en/hooks) for the complete hook configuration format.

410# View frontmatter

411cat .claude/skills/my-skill/SKILL.md | head -n 15

412 333

413# Check for common issues334### Control Skill visibility

414# - Missing opening or closing ---

415# - Tabs instead of spaces

416# - Unquoted strings with special characters

417```

418 335

419**Check**: Is the Skill in the correct location?336Skills can be invoked in three ways:

420 337

421```bash theme={null}3381. **Manual invocation**: You type `/skill-name` in the prompt

422# Personal Skills3392. **Programmatic invocation**: Claude calls it via the [`Skill` tool](/en/slash-commands#skill-tool)

423ls ~/.claude/skills/*/SKILL.md3403. **Automatic discovery**: Claude reads the Skill's description and loads it when relevant to the conversation

424 341

425# Project Skills342The `user-invocable` field controls only manual invocation. When set to `false`, the Skill is hidden from the slash command menu but Claude can still invoke it programmatically or discover it automatically.

426ls .claude/skills/*/SKILL.md

427```

428 343

429### Skill has errors344To block programmatic invocation via the `Skill` tool, use `disable-model-invocation: true` instead.

430 345

431**Symptom**: The Skill loads but doesn't work correctly.346#### When to use each setting

432 347

349| :------------------------------- | :--------- | :----------- | :------------- | :-------------------------------------------------------------- |

434 353

435Claude will automatically install required dependencies (or ask for permission to install them) when it needs them.354#### Example: model-only Skill

436 355

437**Check**: Do scripts have execute permissions?356Set `user-invocable: false` to hide a Skill from the slash menu while still allowing Claude to invoke it programmatically:

438 357

439```bash theme={null}358```yaml theme={null}

440chmod +x .claude/skills/my-skill/scripts/*.py359---

360name: internal-review-standards

361description: Apply internal code review standards when reviewing pull requests

362user-invocable: false

363---

441```364```

442 365

443**Check**: Are file paths correct?366With this setting, users won't see the Skill in the `/` menu, but Claude can still invoke it via the `Skill` tool or discover it automatically based on context.

444 367

445Use forward slashes (Unix style) in all paths:368### Skills and subagents

446 369

447**Correct**: `scripts/helper.py`370There are two ways Skills and subagents can work together:

448**Wrong**: `scripts\helper.py` (Windows style)

449 371

450### Multiple Skills conflict372#### Give a subagent access to Skills

451 373

452**Symptom**: Claude uses the wrong Skill or seems confused between similar Skills.374[Subagents](/en/sub-agents) do not automatically inherit Skills from the main conversation. To give a custom subagent access to specific Skills, list them in the subagent's `skills` field:

453 375

454**Be specific in descriptions**: Help Claude choose the right Skill by using distinct trigger terms in your descriptions.376```yaml theme={null}

377# .claude/agents/code-reviewer.md

378---

379name: code-reviewer

380description: Review code for quality and best practices

381skills: pr-review, security-check

382---

383```

455 384

456Instead of:385The full content of each listed Skill is injected into the subagent's context at startup, not just made available for invocation. If the `skills` field is omitted, no Skills are loaded for that subagent.

457 386

458```yaml theme={null}387<Note>

459# Skill 1388 Built-in agents (Explore, Plan, general-purpose) do not have access to your Skills. Only custom subagents you define in `.claude/agents/` with an explicit `skills` field can use Skills.

460description: For data analysis389</Note>

461 390

462# Skill 2391#### Run a Skill in a subagent context

463description: For analyzing data

464```

465 392

466Use:393Use `context: fork` and `agent` to run a Skill in a forked subagent with its own separate context. See [Run Skills in a forked context](#run-skills-in-a-forked-context) for details.

467 394

468```yaml theme={null}395### Distribute Skills

469# Skill 1

470description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking.

471 396

472# Skill 2397You can share Skills in several ways:

473description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics.398

474```399* **Project Skills**: Commit `.claude/skills/` to version control. Anyone who clones the repository gets the Skills.

400* **Plugins**: To share Skills across multiple repositories, create a `skills/` directory in your [plugin](/en/plugins) with Skill folders containing `SKILL.md` files. Distribute through a [plugin marketplace](/en/plugin-marketplaces).

401* **Managed**: Administrators can deploy Skills organization-wide through [managed settings](/en/iam#managed-settings). See [Where Skills live](#where-skills-live) for managed Skill paths.

475 402

476## Examples403## Examples

477 404

405These examples show common Skill patterns, from minimal single-file Skills to multi-file Skills with supporting documentation and scripts.

406

478### Simple Skill (single file)407### Simple Skill (single file)

479 408

409A minimal Skill needs only a `SKILL.md` file with frontmatter and instructions. This example helps Claude generate commit messages by examining staged changes:

410

480```411```

481commit-helper/412commit-helper/

482└── SKILL.md413└── SKILL.md

506- Explain what and why, not how435- Explain what and why, not how

507```436```

508 437

509### Skill with tool permissions438### Use multiple files

~~510~~

511```

512code-reviewer/

513└── SKILL.md

514```

~~515~~

516```yaml theme={null}

517name: code-reviewer

518description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.

519allowed-tools: Read, Grep, Glob

~~520~~

521# Code Reviewer

~~522~~

523## Review checklist

524 439

5251. Code organization and structure440For complex Skills, use progressive disclosure to keep the main `SKILL.md` focused while providing detailed documentation in supporting files. This PDF processing Skill includes reference docs, utility scripts, and uses `allowed-tools` to restrict Claude to specific tools:

5262. Error handling

5273. Performance considerations

5284. Security concerns

5295. Test coverage

~~530~~

531## Instructions

~~532~~

5331. Read the target files using Read tool

5342. Search for patterns using Grep

5353. Find related files using Glob

5364. Provide detailed feedback on code quality

537```

~~538~~

539### Multi-file Skill

540 441

541```442```

542pdf-processing/443pdf-processing/

543├── SKILL.md444├── SKILL.md # Overview and quick start

544├── FORMS.md445├── FORMS.md # Form field mappings and filling instructions

545├── REFERENCE.md446├── REFERENCE.md # API details for pypdf and pdfplumber

546└── scripts/447└── scripts/

547 ├── fill_form.py448 ├── fill_form.py # Utility to populate form fields

548 └── validate.py449 └── validate.py # Checks PDFs for required fields

549```450```

550 451

551**SKILL.md**:452**`SKILL.md`**:

552 453

553````yaml theme={null}454````yaml theme={null}

554---455---

555name: pdf-processing456name: pdf-processing

556description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.457description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.

458allowed-tools: Read, Bash(python:*)

557---459---

558 460

559# PDF Processing461# PDF Processing

581````481````

582 482

583<Note>483<Note>

584 List required packages in the description. Packages must be installed in your environment before Claude can use them.484 If your Skill requires external packages, list them in the description. Packages must be installed in your environment before Claude can use them.

585</Note>485</Note>

586 486

587Claude loads additional files only when needed.487## Troubleshooting

488

489### View and test Skills

490

491To see which Skills Claude has access to, ask Claude a question like "What Skills are available?" Claude loads all available Skill names and descriptions into the context window when a conversation starts, so it can list the Skills it currently has access to.

492

493To test a specific Skill, ask Claude to do a task that matches the Skill's description. For example, if your Skill has the description "Reviews pull requests for code quality", ask Claude to "Review the changes in my current branch." Claude automatically uses the Skill when the request matches its description.

494

495### Skill not triggering

496

497The description field is how Claude decides whether to use your Skill. Vague descriptions like "Helps with documents" don't give Claude enough information to match your Skill to relevant requests.

498

499A good description answers two questions:

500

5011. **What does this Skill do?** List the specific capabilities.

5022. **When should Claude use it?** Include trigger terms users would mention.

503

504```yaml theme={null}

505description: 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.

506```

507

508This description works because it names specific actions (extract, fill, merge) and includes keywords users would say (PDF, forms, document extraction).

509

510### Skill doesn't load

511

512**Check the file path.** Skills must be in the correct directory with the exact filename `SKILL.md` (case-sensitive):

513

514| Type | Path |

515| :--------- | :---------------------------------------------------------------------- |

516| Personal | `~/.claude/skills/my-skill/SKILL.md` |

517| Project | `.claude/skills/my-skill/SKILL.md` |

518| Enterprise | See [Where Skills live](#where-skills-live) for platform-specific paths |

519| Plugin | `skills/my-skill/SKILL.md` inside the plugin directory |

520

521**Check the YAML syntax.** Invalid YAML in the frontmatter prevents the Skill from loading. The frontmatter must start with `---` on line 1 (no blank lines before it), end with `---` before the Markdown content, and use spaces for indentation (not tabs).

522

523**Run debug mode.** Use `claude --debug` to see Skill loading errors.

524

525### Skill has errors

526

527**Check dependencies are installed.** If your Skill uses external packages, they must be installed in your environment before Claude can use them.

528

529**Check script permissions.** Scripts need execute permissions: `chmod +x scripts/*.py`

530

531**Check file paths.** Use forward slashes (Unix style) in all paths. Use `scripts/helper.py`, not `scripts\helper.py`.

532

533### Multiple Skills conflict

534

535If Claude uses the wrong Skill or seems confused between similar Skills, the descriptions are probably too similar. Make each description distinct by using specific trigger terms.

536

537For example, instead of two Skills with "data analysis" in both descriptions, differentiate them: one for "sales data in Excel files and CRM exports" and another for "log files and system metrics". The more specific your trigger terms, the easier it is for Claude to match the right Skill to your request.

538

539### Plugin Skills not appearing

540

541**Symptom**: You installed a plugin from a marketplace, but its Skills don't appear when you ask Claude "What Skills are available?"

542

543**Solution**: Clear the plugin cache and reinstall:

544

545```bash theme={null}

546rm -rf ~/.claude/plugins/cache

547```

548

549Then restart Claude Code and reinstall the plugin:

550

551```shell theme={null}

552/plugin install plugin-name@marketplace-name

553```

554

555This forces Claude Code to re-download and re-register the plugin's Skills.

556

557**If Skills still don't appear**, verify the plugin's directory structure is correct. Skills must be in a `skills/` directory at the plugin root:

558

559```

560my-plugin/

561├── .claude-plugin/

562│ └── plugin.json

563└── skills/

564 └── my-skill/

565 └── SKILL.md

566```

588 567

589## Next steps568## Next steps

590 569

605 Create your first Skill584 Create your first Skill

606 </Card>585 </Card>

607</CardGroup>586</CardGroup>

587

588

589---

590

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

slack.md +211 −0 added

Details

1# Claude Code in Slack

3> Delegate coding tasks directly from your Slack workspace

5Claude Code in Slack brings the power of Claude Code directly into your Slack workspace. When you mention `@Claude` with a coding task, Claude automatically detects the intent and creates a Claude Code session on the web, allowing you to delegate development work without leaving your team conversations.

7This integration is built on the existing Claude for Slack app but adds intelligent routing to Claude Code on the web for coding-related requests.

9## Use cases

11* **Bug investigation and fixes**: Ask Claude to investigate and fix bugs as soon as they're reported in Slack channels.

12* **Quick code reviews and modifications**: Have Claude implement small features or refactor code based on team feedback.

13* **Collaborative debugging**: When team discussions provide crucial context (e.g., error reproductions or user reports), Claude can use that information to inform its debugging approach.

14* **Parallel task execution**: Kick off coding tasks in Slack while you continue other work, receiving notifications when complete.

16## Prerequisites

18Before using Claude Code in Slack, ensure you have the following:

20| Requirement | Details |

21| :--------------------- | :----------------------------------------------------------------------------- |

22| Claude Plan | Pro, Max, Team, or Enterprise with Claude Code access (premium seats) |

23| Claude Code on the web | Access to [Claude Code on the web](/en/claude-code-on-the-web) must be enabled |

24| GitHub Account | Connected to Claude Code on the web with at least one repository authenticated |

25| Slack Authentication | Your Slack account linked to your Claude account via the Claude app |

27## Setting up Claude Code in Slack

29<Steps>

30 <Step title="Install the Claude App in Slack">

31 A workspace administrator must install the Claude app from the Slack App Marketplace. Visit the [Slack App Marketplace](https://slack.com/marketplace/A08SF47R6P4) and click "Add to Slack" to begin the installation process.

32 </Step>

34 <Step title="Connect your Claude account">

35 After the app is installed, authenticate your individual Claude account:

37 1. Open the Claude app in Slack by clicking on "Claude" in your Apps section

38 2. Navigate to the App Home tab

39 3. Click "Connect" to link your Slack account with your Claude account

40 4. Complete the authentication flow in your browser

41 </Step>

43 <Step title="Configure Claude Code on the web">

44 Ensure your Claude Code on the web is properly configured:

46 * Visit [claude.ai/code](https://claude.ai/code) and sign in with the same account you connected to Slack

47 * Connect your GitHub account if not already connected

48 * Authenticate at least one repository that you want Claude to work with

49 </Step>

51 <Step title="Choose your routing mode">

52 After connecting your accounts, configure how Claude handles your messages in Slack. Navigate to the Claude App Home in Slack to find the **Routing Mode** setting.

54 | Mode | Behavior |

55 | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

56 | **Code only** | Claude routes all @mentions to Claude Code sessions. Best for teams using Claude in Slack exclusively for development tasks. |

57 | **Code + Chat** | Claude analyzes each message and intelligently routes between Claude Code (for coding tasks) and Claude Chat (for writing, analysis, and general questions). Best for teams who want a single @Claude entry point for all types of work. |

59 <Note>

60 In Code + Chat mode, if Claude routes a message to Chat but you wanted a coding session, you can click "Retry as Code" to create a Claude Code session instead. Similarly, if it's routed to Code but you wanted a Chat session, you can choose that option in that thread.

61 </Note>

62 </Step>

63</Steps>

65## How it works

67### Automatic detection

69When you mention @Claude in a Slack channel or thread, Claude automatically analyzes your message to determine if it's a coding task. If Claude detects coding intent, it will route your request to Claude Code on the web instead of responding as a regular chat assistant.

71You can also explicitly tell Claude to handle a request as a coding task, even if it doesn't automatically detect it.

73<Note>

74 Claude Code in Slack only works in channels (public or private). It does not work in direct messages (DMs).

75</Note>

77### Context gathering

79**From threads**: When you @mention Claude in a thread, it gathers context from all messages in that thread to understand the full conversation.

81**From channels**: When mentioned directly in a channel, Claude looks at recent channel messages for relevant context.

83This context helps Claude understand the problem, select the appropriate repository, and inform its approach to the task.

85<Warning>

86 When @Claude is invoked in Slack, Claude is given access to the conversation context to better understand your request. Claude may follow directions from other messages in the context, so users should make sure to only use Claude in trusted Slack conversations.

87</Warning>

89### Session flow

911. **Initiation**: You @mention Claude with a coding request

922. **Detection**: Claude analyzes your message and detects coding intent

933. **Session creation**: A new Claude Code session is created on claude.ai/code

944. **Progress updates**: Claude posts status updates to your Slack thread as work progresses

955. **Completion**: When finished, Claude @mentions you with a summary and action buttons

966. **Review**: Click "View Session" to see the full transcript, or "Create PR" to open a pull request

98## User interface elements

100### App Home

101

102The App Home tab shows your connection status and allows you to connect or disconnect your Claude account from Slack.

103

104### Message actions

105

106* **View Session**: Opens the full Claude Code session in your browser where you can see all work performed, continue the session, or make additional requests.

107* **Create PR**: Creates a pull request directly from the session's changes.

108* **Retry as Code**: If Claude initially responds as a chat assistant but you wanted a coding session, click this button to retry the request as a Claude Code task.

109* **Change Repo**: Allows you to select a different repository if Claude chose incorrectly.

110

111### Repository selection

112

113Claude automatically selects a repository based on context from your Slack conversation. If multiple repositories could apply, Claude may display a dropdown allowing you to choose the correct one.

114

115## Access and permissions

116

117### User-level access

118

119| Access Type | Requirement |

120| :------------------- | :-------------------------------------------------------------- |

121| Claude Code Sessions | Each user runs sessions under their own Claude account |

122| Usage & Rate Limits | Sessions count against the individual user's plan limits |

123| Repository Access | Users can only access repositories they've personally connected |

124| Session History | Sessions appear in your Claude Code history on claude.ai/code |

125

126### Workspace admin permissions

127

128Slack workspace administrators control whether the Claude app can be installed in the workspace. Individual users then authenticate with their own Claude accounts to use the integration.

129

130## What's accessible where

131

132**In Slack**: You'll see status updates, completion summaries, and action buttons. The full transcript is preserved and always accessible.

133

134**On the web**: The complete Claude Code session with full conversation history, all code changes, file operations, and the ability to continue the session or create pull requests.

135

136## Best practices

137

138### Writing effective requests

139

140* **Be specific**: Include file names, function names, or error messages when relevant.

141* **Provide context**: Mention the repository or project if it's not clear from the conversation.

142* **Define success**: Explain what "done" looks like—should Claude write tests? Update documentation? Create a PR?

143* **Use threads**: Reply in threads when discussing bugs or features so Claude can gather the full context.

144

145### When to use Slack vs. web

146

147**Use Slack when**: Context already exists in a Slack discussion, you want to kick off a task asynchronously, or you're collaborating with teammates who need visibility.

148

149**Use the web directly when**: You need to upload files, want real-time interaction during development, or are working on longer, more complex tasks.

150

151## Troubleshooting

152

153### Sessions not starting

154

1551. Verify your Claude account is connected in the Claude App Home

1562. Check that you have Claude Code on the web access enabled

1573. Ensure you have at least one GitHub repository connected to Claude Code

158

159### Repository not showing

160

1611. Connect the repository in Claude Code on the web at [claude.ai/code](https://claude.ai/code)

1622. Verify your GitHub permissions for that repository

1633. Try disconnecting and reconnecting your GitHub account

164

165### Wrong repository selected

166

1671. Click the "Change Repo" button to select a different repository

1682. Include the repository name in your request for more accurate selection

169

170### Authentication errors

171

1721. Disconnect and reconnect your Claude account in the App Home

1732. Ensure you're signed into the correct Claude account in your browser

1743. Check that your Claude plan includes Claude Code access

175

176### Session expiration

177

1781. Sessions remain accessible in your Claude Code history on the web

1792. You can continue or reference past sessions from [claude.ai/code](https://claude.ai/code)

180

181## Current limitations

182

183* **GitHub only**: Currently supports repositories on GitHub.

184* **One PR at a time**: Each session can create one pull request.

185* **Rate limits apply**: Sessions use your individual Claude plan's rate limits.

186* **Web access required**: Users must have Claude Code on the web access; those without it will only get standard Claude chat responses.

187

188## Related resources

189

190<CardGroup>

191 <Card title="Claude Code on the web" icon="globe" href="/en/claude-code-on-the-web">

192 Learn more about Claude Code on the web

193 </Card>

194

195 <Card title="Claude for Slack" icon="slack" href="https://claude.com/claude-and-slack">

196 General Claude for Slack documentation

197 </Card>

198

199 <Card title="Slack App Marketplace" icon="store" href="https://slack.com/marketplace/A08SF47R6P4">

200 Install the Claude app from the Slack Marketplace

201 </Card>

202

203 <Card title="Claude Help Center" icon="circle-question" href="https://support.claude.com">

204 Get additional support

205 </Card>

206</CardGroup>

207

208

209---

210

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

slash-commands.md +116 −64

Details

5## Built-in slash commands5## Built-in slash commands

6 6

7| Command | Purpose |7| Command | Purpose |

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

9| `/add-dir` | Add additional working directories |9| `/add-dir` | Add additional working directories |

10| `/agents` | Manage custom AI subagents for specialized tasks |10| `/agents` | Manage custom AI subagents for specialized tasks |

11| `/bashes` | List and manage background tasks |11| `/bashes` | List and manage background tasks |

12| `/bug` | Report bugs (sends conversation to Anthropic) |12| `/bug` | Report bugs (sends conversation to Anthropic) |

13| `/clear` | Clear conversation history |13| `/clear` | Clear conversation history |

14| `/compact [instructions]` | Compact conversation with optional focus instructions |14| `/compact [instructions]` | Compact conversation with optional focus instructions |

16| `/context` | Visualize current context usage as a colored grid |16| `/context` | Visualize current context usage as a colored grid |

~~17| `/cost` | Show token usage statistics (see [cost tracking guide](/en/costs#using-the-cost-command) for subscription-specific details) |~~17| `/cost` | Show token usage statistics. See [cost tracking guide](/en/costs#using-the-cost-command) for subscription-specific details. |

19| `/exit` | Exit the REPL |19| `/exit` | Exit the REPL |

20| `/export [filename]` | Export the current conversation to a file or clipboard |20| `/export [filename]` | Export the current conversation to a file or clipboard |

21| `/help` | Get usage help |21| `/help` | Get usage help |

22| `/hooks` | Manage hook configurations for tool events |22| `/hooks` | Manage hook configurations for tool events |

23| `/ide` | Manage IDE integrations and show status |23| `/ide` | Manage IDE integrations and show status |

25| `/install-github-app` | Set up Claude GitHub Actions for a repository |25| `/install-github-app` | Set up Claude GitHub Actions for a repository |

26| `/login` | Switch Anthropic accounts |26| `/login` | Switch Anthropic accounts |

27| `/logout` | Sign out from your Anthropic account |27| `/logout` | Sign out from your Anthropic account |

28| `/mcp` | Manage MCP server connections and OAuth authentication |28| `/mcp` | Manage MCP server connections and OAuth authentication |

30| `/model` | Select or change the AI model |30| `/model` | Select or change the AI model |

31| `/output-style [style]` | Set the output style directly or from a selection menu |31| `/output-style [style]` | Set the output style directly or from a selection menu |

32| `/permissions` | View or update [permissions](/en/iam#configuring-permissions) |32| `/permissions` | View or update [permissions](/en/iam#configuring-permissions) |

33| `/plan` | Enter plan mode directly from the prompt |

33| `/plugin` | Manage Claude Code plugins |34| `/plugin` | Manage Claude Code plugins |

34| `/pr-comments` | View pull request comments |35| `/pr-comments` | View pull request comments |

35| `/privacy-settings` | View and update your privacy settings |36| `/privacy-settings` | View and update your privacy settings |

36| `/release-notes` | View release notes |37| `/release-notes` | View release notes |

39| `/remote-env` | Configure remote session environment (claude.ai subscribers) |

40| `/resume [session]` | Resume a conversation by ID or name, or open the session picker |

38| `/review` | Request code review |41| `/review` | Request code review |

39| `/rewind` | Rewind the conversation and/or code |42| `/rewind` | Rewind the conversation and/or code |

40| `/sandbox` | Enable sandboxed bash tool with filesystem and network isolation for safer, more autonomous execution |43| `/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 |44| `/security-review` | Complete a security review of pending changes on the current branch |

45| `/stats` | Visualize daily usage, session history, streaks, and model preferences. Press `r` to cycle date ranges (Last 7 days, Last 30 days, All time) |

42| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |46| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |

43| `/statusline` | Set up Claude Code's status line UI |47| `/statusline` | Set up Claude Code's status line UI |

51| `/todos` | List current TODO items |

52| `/usage` | For subscription plans only: show plan usage limits and rate limit status |

47| `/vim` | Enter vim mode for alternating insert and command modes |53| `/vim` | Enter vim mode for alternating insert and command modes |

48 54

49## Custom slash commands55## Custom slash commands

50 56

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

59<Tip>

60 Slash command autocomplete works anywhere in your input, not just at the beginning. Type `/` at any position to see available commands.

61</Tip>

52 62

53### Syntax63### Syntax

54 64

71 81

72**Location**: `.claude/commands/`82**Location**: `.claude/commands/`

73 83

~~74In the following example, we create the `/optimize` command:~~84The following example creates the `/optimize` command:

75 85

76```bash theme={null}86```bash theme={null}

77# Create a project command87# Create a project command

85 95

86**Location**: `~/.claude/commands/`96**Location**: `~/.claude/commands/`

87 97

~~88In the following example, we create the `/security-review` command:~~98The following example creates the `/security-review` command:

89 99

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

91# Create a personal command101# Create a personal command

97 107

98#### Namespacing108#### Namespacing

99 109

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.110Use subdirectories to group related commands. Subdirectories appear in the command description but don't affect the command name.

111

112For example:

113

114* `.claude/commands/frontend/component.md` creates `/component` with description "(project:frontend)"

115* `~/.claude/commands/component.md` creates `/component` with description "(user)"

101 116

102Conflicts between user and project level commands are not supported. Otherwise, multiple commands with the same base file name can coexist.117If a project command and user command share the same name, the project command takes precedence and the user command is silently ignored. For example, if both `.claude/commands/deploy.md` and `~/.claude/commands/deploy.md` exist, `/deploy` runs the project version.

103 118

104For example, a file at `.claude/commands/frontend/component.md` creates the command `/component` with description showing "(project:frontend)".119Commands in different subdirectories can share names since the subdirectory appears in the description to distinguish them. For example, `.claude/commands/frontend/test.md` and `.claude/commands/backend/test.md` both create `/test`, but show as "(project:frontend)" and "(project:backend)" respectively.

105Meanwhile, a file at `~/.claude/commands/component.md` creates the command `/component` with description showing "(user)".

106 120

107#### Arguments121#### Arguments

108 122

192| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------- |206| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------- |

209| `context` | Set to `fork` to run the command in a forked sub-agent context with its own conversation history. | Inline (no fork) |

210| `agent` | Specify which [agent type](/en/sub-agents#built-in-subagents) to use when `context: fork` is set. Only applicable when combined with `context: fork`. | `general-purpose` |

214| `hooks` | Define hooks scoped to this command's execution. See [Define hooks for commands](#define-hooks-for-commands). | None |

198 215

199For example:216For example:

200 217

221Focus on security, performance, and code style.238Focus on security, performance, and code style.

222```239```

223 240

241#### Define hooks for commands

242

243Slash commands can define hooks that run during the command's execution. Use the `hooks` field to specify `PreToolUse`, `PostToolUse`, or `Stop` handlers:

244

245```markdown theme={null}

246---

247description: Deploy to staging with validation

248hooks:

249 PreToolUse:

250 - matcher: "Bash"

251 hooks:

252 - type: command

253 command: "./scripts/validate-deploy.sh"

254 once: true

255---

256

257Deploy the current branch to staging environment.

258```

259

260The `once: true` option runs the hook only once per session. After the first successful execution, the hook is removed.

261

262Hooks defined in a command are scoped to that command's execution and are automatically cleaned up when the command finishes.

263

264See [Hooks](/en/hooks) for the complete hook configuration format.

265

224## Plugin commands266## Plugin commands

225 267

226[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).268[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).

310 352

311#### Naming conventions353#### Naming conventions

312 354

313* Server and prompt names are normalized355Server and prompt names are normalized:

356

314* Spaces and special characters become underscores357* Spaces and special characters become underscores

315* Names are lowercased for consistency358* Names are lowercase for consistency

316 359

317### Managing MCP connections360### Managing MCP connections

318 361

326 369

327### MCP permissions and wildcards370### MCP permissions and wildcards

328 371

329When configuring [permissions for MCP tools](/en/iam#tool-specific-permission-rules), note that **wildcards are not supported**:372To approve all tools from an MCP server, use either the server name alone or wildcard syntax:

330 373

331* ✅ **Correct**: `mcp__github` (approves ALL tools from the github server)374* `mcp__github` (approves all GitHub tools)

332* ✅ **Correct**: `mcp__github__get_issue` (approves specific tool)375* `mcp__github__*` (wildcard syntax, also approves all GitHub tools)

333* ❌ **Incorrect**: `mcp__github__*` (wildcards not supported)

334 376

335To approve all tools from an MCP server, use just the server name: `mcp__servername`. To approve specific tools only, list each tool individually.377To approve specific tools, list each one explicitly:

336 378

337## `SlashCommand` tool379* `mcp__github__get_issue`

380* `mcp__github__list_issues`

338 381

339The `SlashCommand` tool allows Claude to execute [custom slash commands](/en/slash-commands#custom-slash-commands) programmatically382See [MCP permission rules](/en/iam#tool-specific-permission-rules) for more details.

340during a conversation. This gives Claude the ability to invoke custom commands

341on your behalf when appropriate.

342 383

343To encourage Claude to trigger `SlashCommand` tool, your instructions (prompts,384## `Skill` tool

344CLAUDE.md, etc.) generally need to reference the command by name with its slash.

345 385

346Example:386<Note>

387 In earlier versions of Claude Code, slash command invocation was provided by a separate `SlashCommand` tool. This has been merged into the `Skill` tool.

388</Note>

347 389

348```390The `Skill` tool allows Claude to programmatically invoke both [custom slash commands](/en/slash-commands#custom-slash-commands) and [Agent Skills](/en/skills) during a conversation. This gives Claude the ability to use these capabilities on your behalf when appropriate.

349> Run /write-unit-test when you are about to start writing tests.

350```

351 391

352This tool puts each available custom slash command's metadata into context up to the392### What the `Skill` tool can invoke

353character budget limit. You can use `/context` to monitor token usage and follow

354the operations below to manage context.

355 393

356### `SlashCommand` tool supported commands394The `Skill` tool provides access to:

357 395

358`SlashCommand` tool only supports custom slash commands that:396| Type | Location | Requirements |

397| :-------------------- | :------------------------------------------- | :--------------------------------------------- |

398| Custom slash commands | `.claude/commands/` or `~/.claude/commands/` | Must have `description` frontmatter |

399| Agent Skills | `.claude/skills/` or `~/.claude/skills/` | Must not have `disable-model-invocation: true` |

359 400

360* Are user-defined. Built-in commands like `/compact` and `/init` are *not* supported.401Built-in commands like `/compact` and `/init` are *not* available through this tool.

361* Have the `description` frontmatter field populated. We use the `description` in the context.

362 402

363For Claude Code versions >= 1.0.124, you can see which custom slash commands403### Encourage Claude to use specific commands

364`SlashCommand` tool can invoke by running `claude --debug` and triggering a query.

365 404

366### Disable `SlashCommand` tool405To encourage Claude to use the `Skill` tool, reference the command by name, including the slash, in your prompts or `CLAUDE.md` file:

406

407```

408> Run /write-unit-test when you are about to start writing tests.

409```

367 410

368To prevent Claude from executing any slash commands via the tool:411This tool puts each available command's metadata into context up to the character budget limit. Use `/context` to monitor token usage.

412

413To see which commands and Skills are available to the `Skill` tool, run `claude --debug` and trigger a query.

414

415### Disable the `Skill` tool

416

417To prevent Claude from programmatically invoking any commands or Skills:

369 418

370```bash theme={null}419```bash theme={null}

371/permissions420/permissions

372# Add to deny rules: SlashCommand421# Add to deny rules: Skill

373```422```

374 423

375This will also remove SlashCommand tool (and the slash command descriptions) from context.424This removes the `Skill` tool and all command/Skill descriptions from context.

376 425

377### Disable specific commands only426### Disable specific commands or Skills

378 427

379To prevent a specific slash command from becoming available, add428To prevent a specific command or Skill from being invoked programmatically via the `Skill` tool, add `disable-model-invocation: true` to its frontmatter. This also removes the item's metadata from context.

380`disable-model-invocation: true` to the slash command's frontmatter.

381 429

382This will also remove the command's metadata from context.430<Note>

431 The `user-invocable` field in Skills only controls menu visibility, not `Skill` tool access. Use `disable-model-invocation: true` to block programmatic invocation. See [Control Skill visibility](/en/skills#control-skill-visibility) for details.

432</Note>

383 433

384### `SlashCommand` permission rules434### `Skill` permission rules

385 435

386The permission rules support:436The permission rules support:

387 437

388* **Exact match**: `SlashCommand:/commit` (allows only `/commit` with no arguments)438* **Exact match**: `Skill(commit)` (allows only `commit` with no arguments)

389* **Prefix match**: `SlashCommand:/review-pr:*` (allows `/review-pr` with any arguments)439* **Prefix match**: `Skill(review-pr:*)` (allows `review-pr` with any arguments)

390 440

391### Character budget limit441### Character budget limit

392 442

393The `SlashCommand` tool includes a character budget to limit the size of command443The `Skill` tool includes a character budget to limit context usage. This prevents token overflow when many commands and Skills are available.

394descriptions shown to Claude. This prevents token overflow when many commands

395are available.

396 444

397The budget includes each custom slash command's name, args, and description.445The budget includes each item's name, arguments, and description.

398 446

399* **Default limit**: 15,000 characters447* **Default limit**: 15,000 characters

400* **Custom limit**: Set via `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable448* **Custom limit**: Set via `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable. The name is retained for backwards compatibility.

401 449

402When the character budget is exceeded, Claude will see only a subset of the450When the budget is exceeded, Claude sees only a subset of available items. In `/context`, a warning shows how many are included.

403available commands. In `/context`, a warning will show with "M of N commands".

404 451

405## Skills vs slash commands452## Skills vs slash commands

406 453

408 455

409### Use slash commands for456### Use slash commands for

410 457

411**Quick, frequently-used prompts**:458**Quick, frequently used prompts**:

412 459

413* Simple prompt snippets you use often460* Simple prompt snippets you use often

414* Quick reminders or templates461* Quick reminders or templates

415* Frequently-used instructions that fit in one file462* Frequently used instructions that fit in one file

416 463

417**Examples**:464**Examples**:

418 465

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

504* [Settings](/en/settings) - Configuration options551* [Settings](/en/settings) - Configuration options

505* [Memory management](/en/memory) - Managing Claude's memory across sessions552* [Memory management](/en/memory) - Managing Claude's memory across sessions

553

554

555---

556

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

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 +437 −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>

19 45

~~20<CardGroup cols={2}>~~46 <Tab title="General-purpose">

~~21 <Card title="Context preservation" icon="layer-group">~~47 A capable agent for complex, multi-step tasks that require both exploration and action.

~~22 Each subagent operates in its own context, preventing pollution of the main conversation and keeping it focused on high-level objectives.~~

~~23 </Card>~~

24 48

~~25 <Card title="Specialized expertise" icon="brain">~~49 * **Model**: Inherits from main conversation

~~26 Subagents can be fine-tuned with detailed instructions for specific domains, leading to higher success rates on designated tasks.~~50 * **Tools**: All tools

~~27 </Card>~~51 * **Purpose**: Complex research, multi-step operations, code modifications

28 52

~~29 <Card title="Reusability" icon="rotate">~~53 Claude delegates to general-purpose when the task requires both exploration and modification, complex reasoning to interpret results, or multiple dependent steps.

~~30 Once created, subagents can be used across different projects and shared with your team for consistent workflows.~~54 </Tab>

~~31 </Card>~~

32 55

~~33 <Card title="Flexible permissions" icon="shield-check">~~56 <Tab title="Other">

~~34 Each subagent can have different tool access levels, allowing you to limit powerful tools to specific subagent types.~~57 Claude Code includes additional helper agents for specific tasks. These are typically invoked automatically, so you don't need to use them directly.

~~35 </Card>~~

~~36</CardGroup>~~

37 58

~~38## Quick start~~59 | Agent | Model | When Claude uses it |

60 | :---------------- | :------- | :------------------------------------------------------- |

61 | Bash | Inherits | Running terminal commands in a separate context |

62 | statusline-setup | Sonnet | When you run `/statusline` to configure your status line |

63 | Claude Code Guide | Haiku | When you ask questions about Claude Code features |

64 </Tab>

65</Tabs>

39 66

~~40To create your first subagent:~~67Beyond these built-in subagents, you can create your own with custom prompts, tool restrictions, permission modes, hooks, and skills. The following sections show how to get started and customize subagents.

69## Quickstart: create your first subagent

71Subagents are defined in Markdown files with YAML frontmatter. You can [create them manually](#write-subagent-files) or use the `/agents` slash 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.

61 </Step>98 </Step>

62 99

~~63 <Step title="Save and use">~~100 <Step title="Select tools">

~~64 Your subagent is now available! Claude will use it automatically when appropriate, or you can invoke it explicitly:~~101 For a read-only reviewer, deselect everything except **Read-only tools**. If you keep all tools selected, the subagent inherits all tools available to the main conversation.

102 </Step>

103

104 <Step title="Select model">

105 Choose which model the subagent uses. For this example agent, select **Sonnet**, which balances capability and speed for analyzing code patterns.

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 170

117**Use case**: This approach is useful for:171**Plugin subagents** come from [plugins](/en/plugins) you've installed. They appear in `/agents` alongside your custom subagents. See the [plugin components reference](/en/plugins-reference#agents) for details on creating plugin subagents.

118 172

119* Quick testing of subagent configurations173### Write subagent files

120* Session-specific subagents that don't need to be saved

121* Automation scripts that need custom subagents

122* Sharing subagent definitions in documentation or scripts

123 174

124For detailed information about the JSON format and all available options, see the [CLI reference documentation](/en/cli-reference#agents-flag-format).175Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown:

125 176

126### File format177<Note>

~~127~~ 178 Subagents are loaded at session start. If you create a subagent by manually adding a file, restart your session or use `/agents` to load it immediately.

128Each subagent is defined in a Markdown file with this structure:179</Note>

129 180

130```markdown theme={null}181```markdown theme={null}

131---182---

132name: your-sub-agent-name183name: code-reviewer

133description: Description of when this subagent should be invoked184description: Reviews code for quality and best practices

134tools: tool1, tool2, tool3 # Optional - inherits all tools if omitted185tools: Read, Glob, Grep

135model: sonnet # Optional - specify model alias or 'inherit'186model: sonnet

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

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 (useful for consistency)

165* **Omitted**: If not specified, uses the default model configured for subagents (`sonnet`)216* **Omitted**: If not specified, uses the default model configured for subagents (`sonnet`)

166 217

167<Note>218### Control subagent capabilities

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.

169</Note>

170 219

171### Available tools220You can control what subagents can do through tool access, permission modes, and conditional rules.

172 221

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.222#### Available tools

174 223

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

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

177</Tip>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

178 238

179You have two options for configuring tools:239The `permissionMode` field controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation but can override the mode.

180 240

181* **Omit the `tools` field** to inherit all tools from the main thread (default), including MCP tools241| Mode | Behavior |

182* **Specify individual tools** as a comma-separated list for more granular control (can be edited manually or via `/agents`)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) |

183 248

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

250 Use `bypassPermissions` with caution. It skips all permission checks, allowing the subagent to execute any operation without approval.

251</Warning>

185 252

186## Managing subagents253If the parent uses `bypassPermissions`, this takes precedence and cannot be overridden.

187 254

188### Using the /agents command (Recommended)255#### Conditional rules with hooks

189 256

190The `/agents` command provides a comprehensive interface for subagent management:257For 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.

191 258

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

260

261```yaml theme={null}

262---

263name: db-reader

264description: Execute read-only database queries

265tools: Bash

266hooks:

267 PreToolUse:

268 - matcher: "Bash"

269 hooks:

270 - type: command

271 command: "./scripts/validate-readonly-query.sh"

272---

192```273```

193/agents274

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

276

277```bash theme={null}

278#!/bin/bash

279# ./scripts/validate-readonly-query.sh

280

281INPUT=$(cat)

282COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

283

284# Block SQL write operations (case-insensitive)

286 echo "Blocked: Only SELECT queries are allowed" >&2

287 exit 2

288fi

289

290exit 0

194```291```

195 292

196This opens an interactive menu where you can:293See [Hook input](/en/hooks#pretooluse-input) for the complete input schema and [exit codes](/en/hooks#exit-codes) for how exit codes affect behavior.

197 294

198* View all available subagents (built-in, user, and project)295#### Disable specific 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 296

205### Direct file management297You 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.

206 298

207You can also manage subagents by working directly with their files:299```json theme={null}

300{

301 "permissions": {

302 "deny": ["Task(Explore)", "Task(my-custom-agent)"]

303 }

304}

305```

306

307This works for both built-in and custom subagents. You can also use the `--disallowedTools` CLI flag:

208 308

209```bash theme={null}309```bash theme={null}

210# Create a project subagent310claude --disallowedTools "Task(Explore)"

211mkdir -p .claude/agents311```

212echo '---

213name: test-runner

214description: Use proactively to run tests and fix failures

215 312

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.md313See [IAM documentation](/en/iam#tool-specific-permission-rules) for more details on permission rules.

217 314

218# Create a user subagent315### Define hooks for subagents

219mkdir -p ~/.claude/agents316

220# ... create subagent file317Subagents can define [hooks](/en/hooks) that run during the subagent's lifecycle. There are two ways to configure hooks:

318

3191. **In the subagent's frontmatter**: Define hooks that run only while that subagent is active

3202. **In `settings.json`**: Define hooks that run in the main session when subagents start or stop

321

322#### Hooks in subagent frontmatter

323

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

325

326| Event | Matcher input | When it fires |

327| :------------ | :------------ | :------------------------------ |

328| `PreToolUse` | Tool name | Before the subagent uses a tool |

329| `PostToolUse` | Tool name | After the subagent uses a tool |

330| `Stop` | (none) | When the subagent finishes |

331

332This example validates Bash commands with the `PreToolUse` hook and runs a linter after file edits with `PostToolUse`:

333

334```yaml theme={null}

335---

336name: code-reviewer

337description: Review code changes with automatic linting

338hooks:

339 PreToolUse:

340 - matcher: "Bash"

341 hooks:

342 - type: command

343 command: "./scripts/validate-command.sh $TOOL_INPUT"

344 PostToolUse:

345 - matcher: "Edit|Write"

346 hooks:

347 - type: command

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

349---

221```350```

222 351

223## Using subagents effectively352`Stop` hooks in frontmatter are automatically converted to `SubagentStop` events.

224 353

225### Automatic delegation354#### Project-level hooks for subagent events

226 355

227Claude Code proactively delegates tasks based on:356Configure 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 357

229* The task description in your request358| Event | Matcher input | When it fires |

230* The `description` field in subagent configurations359| :-------------- | :-------------- | :------------------------------- |

231* Current context and available tools360| `SubagentStart` | Agent type name | When a subagent begins execution |

361| `SubagentStop` | Agent type name | When a subagent completes |

232 362

233<Tip>363This 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.364

235</Tip>365```json theme={null}

366{

367 "hooks": {

368 "SubagentStart": [

369 {

370 "matcher": "db-agent",

371 "hooks": [

372 { "type": "command", "command": "./scripts/setup-db-connection.sh" }

373 ]

374 }

375 ],

376 "SubagentStop": [

377 {

378 "matcher": "db-agent",

379 "hooks": [

380 { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }

381 ]

382 }

383 ]

384 }

385}

386```

387

388See [Hooks](/en/hooks) for the complete hook configuration format.

389

390## Work with subagents

391

392### Understand automatic delegation

236 393

237### Explicit invocation394Claude 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 395

239Request a specific subagent by mentioning it in your command:396You can also request a specific subagent explicitly:

240 397

241```398```

242> Use the test-runner subagent to fix failing tests399Use the test-runner subagent to fix failing tests

243> Have the code-reviewer subagent look at my recent changes400Have the code-reviewer subagent look at my recent changes

244> Ask the debugger subagent to investigate this error

245```401```

246 402

247## Built-in subagents403### Run subagents in foreground or background

248 404

249Claude Code includes built-in subagents that are available out of the box:405Subagents can run in the foreground (blocking) or background (concurrent):

250 406

251### General-purpose subagent407* **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.

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

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.410If a background subagent fails due to missing permissions, you can [resume it](#resume-subagents) in the foreground to retry with interactive prompts.

254 411

255**Key characteristics:**412Claude decides whether to run subagents in the foreground or background based on the task. You can also:

256 413

257* **Model**: Uses Sonnet for more capable reasoning414* Ask Claude to "run this in the background"

258* **Tools**: Has access to all tools415* 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 416

262**When Claude uses it:**417To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/en/settings#environment-variables).

263 418

264Claude delegates to the general-purpose subagent when:419### Common patterns

265 420

266* The task requires both exploration and modification421#### 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 422

271**Example scenario:**423One 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 424

273```425```

274User: Find all the places where we handle authentication and update them to use the new token format426Use 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```427```

282 428

283### Plan subagent429#### Run parallel research

284 430

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.431For independent investigations, spawn multiple subagents to work simultaneously:

286 432

287**Key characteristics:**433```

434Research the authentication, database, and API modules in parallel using separate subagents

435```

288 436

289* **Model**: Uses Sonnet for more capable analysis437Each 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 438

294**How it works:**439<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.440 When subagents complete, their results return to your main conversation. Running many subagents that each return detailed results can consume significant context.

441</Warning>

296 442

297**Example scenario:**443#### Chain subagents

298 444

299```445For 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 446

302Claude: Let me research your authentication implementation first...447```

303[Internally invokes Plan subagent to explore auth-related files]448Use 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```449```

307 450

308<Tip>451### 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.

310</Tip>

311 452

312### Explore subagent453Use the **main conversation** when:

313 454

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.455* The task needs frequent back-and-forth or iterative refinement

456* Multiple phases share significant context (planning → implementation → testing)

457* You're making a quick, targeted change

458* Latency matters. Subagents start fresh and may need time to gather context

315 459

316**Key characteristics:**460Use **subagents** when:

317 461

318* **Model**: Uses Haiku for fast, low-latency searches462* The task produces verbose output you don't need in your main context

319* **Mode**: Strictly read-only - cannot create, modify, or delete files463* You want to enforce specific tool restrictions or permissions

320* **Tools available**:464* The work is self-contained and can return a summary

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 465

326**When Claude uses it:**466Consider [Skills](/en/skills) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.

327 467

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

469 Subagents cannot spawn other subagents. If your workflow requires nested delegation, use [Skills](/en/skills) or [chain subagents](#chain-subagents) from the main conversation.

470</Note>

329 471

330**Thoroughness levels:**472### Manage subagent context

331 473

332When invoking the Explore subagent, Claude specifies a thoroughness level:474#### Resume subagents

333 475

334* **Quick** - Basic searches, fastest results. Good for simple lookups.476Each 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.

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 477

338**Example scenarios:**478Resumed 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.

339 479

340```480When a subagent completes, Claude receives its agent ID. To resume a subagent, ask Claude to continue the previous work:

341User: Where are errors from the client handled?

342 481

343Claude: [Invokes Explore subagent with "medium" thoroughness]

344[Explore uses Grep to search for error handling patterns]

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

483Use the code-reviewer subagent to review the authentication module

484[Agent completes]

349 485

486Continue that code review and now analyze the authorization logic

487[Claude resumes the subagent with full context from previous conversation]

350```488```

351User: What's the codebase structure?

352 489

353Claude: [Invokes Explore subagent with "quick" thoroughness]490You 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`.

354[Explore uses Glob and ls to map directory structure]491

355[Returns overview of key directories and their purposes]492For programmatic usage, see [Subagents in the Agent SDK](/en/agent-sdk/subagents).

493

494Subagent transcripts persist independently of the main conversation:

495

496* **Main conversation compaction**: When the main conversation compacts, subagent transcripts are unaffected. They're stored in separate files.

497* **Session persistence**: Subagent transcripts persist within their session. You can [resume a subagent](#resume-subagents) after restarting Claude Code by resuming the same session.

498* **Automatic cleanup**: Transcripts are cleaned up based on the `cleanupPeriodDays` setting (default: 30 days).

499

500#### Auto-compaction

501

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

503

504Compaction events are logged in subagent transcript files:

505

506```json theme={null}

507{

508 "type": "system",

509 "subtype": "compact_boundary",

510 "compactMetadata": {

511 "trigger": "auto",

512 "preTokens": 167189

513 }

514}

356```515```

357 516

517The `preTokens` value shows how many tokens were used before compaction occurred.

518

358## Example subagents519## Example subagents

359 520

521These examples demonstrate effective patterns for building subagents. Use them as starting points, or generate a customized version with Claude.

522

523<Tip>

524 **Best practices:**

525

526 * **Design focused subagents:** each subagent should excel at one specific task

527 * **Write detailed descriptions:** Claude uses the description to decide when to delegate

528 * **Limit tool access:** grant only necessary permissions for security and focus

529 * **Check into version control:** share project subagents with your team

530</Tip>

531

360### Code reviewer532### Code reviewer

361 533

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

535

362```markdown theme={null}536```markdown theme={null}

363---537---

364name: code-reviewer538name: code-reviewer

3763. Begin review immediately5493. Begin review immediately

377 550

378Review checklist:551Review checklist:

379- Code is simple and readable552- Code is clear and readable

380- Functions and variables are well-named553- Functions and variables are well-named

381- No duplicated code554- No duplicated code

382- Proper error handling555- Proper error handling

395 568

396### Debugger569### Debugger

397 570

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

572

398```markdown theme={null}573```markdown theme={null}

399---574---

400name: debugger575name: debugger

425- Testing approach600- Testing approach

426- Prevention recommendations601- Prevention recommendations

427 602

428Focus on fixing the underlying issue, not just symptoms.603Focus on fixing the underlying issue, not the symptoms.

429```604```

430 605

431### Data scientist606### Data scientist

432 607

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

609

433```markdown theme={null}610```markdown theme={null}

434---611---

435name: data-scientist612name: data-scientist

463Always ensure queries are efficient and cost-effective.640Always ensure queries are efficient and cost-effective.

464```641```

465 642

466## Best practices643### Database query validator

467 644

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

469 646

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.647```markdown theme={null}

~~471~~ 648---

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.649name: db-reader

~~473~~ 650description: Execute read-only database queries. Use when analyzing data or generating reports.

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.651tools: Bash

~~475~~ 652hooks:

476* **Version control**: Check project subagents into version control so your team can benefit from and improve them collaboratively.653 PreToolUse:

~~477~~ 654 - matcher: "Bash"

478## Advanced usage655 hooks:

656 - type: command

657 command: "./scripts/validate-readonly-query.sh"

658---

479 659

480### Chaining subagents660You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

481 661

482For complex workflows, you can chain multiple subagents:662When asked to analyze data:

6631. Identify which tables contain the relevant data

6642. Write efficient SELECT queries with appropriate filters

6653. Present results clearly with context

483 666

667You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

484```668```

485> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

486```

~~487~~

488### Dynamic subagent selection

489 669

490Claude Code intelligently selects subagents based on context. Make your `description` fields specific and action-oriented for best results.670Claude 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.

491 671

492### Resumable subagents672Create the validation script anywhere in your project. The path must match the `command` field in your hook configuration:

493 673

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.674```bash theme={null}

~~495~~ 675#!/bin/bash

496**How it works:**676# Blocks SQL write operations, allows SELECT queries

497 677

498* Each subagent execution is assigned a unique `agentId`678# Read JSON input from stdin

499* The agent's conversation is stored in a separate transcript file: `agent-{agentId}.jsonl`679INPUT=$(cat)

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 680

503**Example workflow:**681# Extract the command field from tool_input using jq

682COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

504 683

505Initial invocation:684if [ -z "$COMMAND" ]; then

685 exit 0

686fi

506 687

507```688# Block write operations (case-insensitive)

690 echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2

691 exit 2

692fi

509 693

510[Agent completes initial analysis and returns agentId: "abc123"]694exit 0

511```695```

512 696

513Resume the agent:697Make the script executable:

~~514~~

515```

516> Resume agent abc123 and now analyze the authorization logic as well

517 698

518[Agent continues with full context from previous conversation]699```bash theme={null}

700chmod +x ./scripts/validate-readonly-query.sh

519```701```

520 702

521**Use cases:**703The 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#exit-codes) 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 704

527**Technical details:**705## Next steps

528 706

529* Agent transcripts are stored in your project directory707Now that you understand subagents, explore these related features:

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 708

534**Programmatic usage:**709* [Distribute subagents with plugins](/en/plugins) to share subagents across teams or projects

710* [Run Claude Code programmatically](/en/headless) with the Agent SDK for CI/CD and automation

711* [Use MCP servers](/en/mcp) to give subagents access to external tools and data

535 712

536If you're using the Agent SDK or interacting with the AgentTool directly, you can pass the `resume` parameter:

537 713

538```typescript theme={null}714---

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

547<Tip>

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 715

558* [Plugins](/en/plugins) - Extend Claude Code with custom agents through plugins716> 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 +89 −29

Details

50```50```

51 51

52<Warning>52<Warning>

53 Avoid disabling Windows PATH importing (`appendWindowsPath = false`) as this breaks the ability to easily call Windows executables from WSL. Similarly, avoid uninstalling Node.js from Windows if you use it for Windows development.53 Avoid disabling Windows PATH importing (`appendWindowsPath = false`) as this breaks the ability to call Windows executables from WSL. Similarly, avoid uninstalling Node.js from Windows if you use it for Windows development.

54</Warning>54</Warning>

55 55

56### Linux and Mac installation issues: permission or command not found errors56### Linux and Mac installation issues: permission or command not found errors

57 57

58When installing Claude Code with npm, `PATH` problems may prevent access to `claude`.58When installing Claude Code with npm, `PATH` problems may prevent access to `claude`.

~~59You may also encounter permission errors if your npm global prefix is not user writable (eg. `/usr`, or `/usr/local`).~~59You may also encounter permission errors if your npm global prefix is not user writable (for example, `/usr`, or `/usr/local`).

60 60

61#### Recommended solution: Native Claude Code installation61#### Recommended solution: Native Claude Code installation

62 62

63Claude Code has a native installation that doesn't depend on npm or Node.js.63Claude Code has a native installation that doesn't depend on npm or Node.js.

64 64

~~65<Note>~~

~~66 The native Claude Code installer is currently in beta.~~

~~67</Note>~~

69Use the following command to run the native installer.65Use the following command to run the native installer.

70 66

71**macOS, Linux, WSL:**67**macOS, Linux, WSL:**

95 91

96```92```

97 93

~~98This command installs the appropriate build of Claude Code for your operating system and architecture and adds a symlink to the installation at `~/.local/bin/claude`.~~94This command installs the appropriate build of Claude Code for your operating system and architecture and adds a symlink to the installation at `~/.local/bin/claude` (or `%USERPROFILE%\.local\bin\claude.exe` on Windows).

99 95

100<Tip>96<Tip>

101 Make sure that you have the installation directory in your system PATH.97 Make sure that you have the installation directory in your system PATH.

102</Tip>98</Tip>

103 99

104#### Alternative solution: Migrate to local installation100### Windows: "Claude Code on Windows requires git-bash"

105 101

106Alternatively, if Claude Code will run, you can migrate to a local installation:102Claude Code on native Windows requires [Git for Windows](https://git-scm.com/downloads/win) which includes Git Bash. If Git is installed but not detected:

107 103

108```bash theme={null}1041. Set the path explicitly in PowerShell before running Claude:

109claude migrate-installer105 ```powershell theme={null}

110```106 $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

107 ```

111 108

112This moves Claude Code to `~/.claude/local/` and sets up an alias in your shell configuration. No `sudo` is required for future updates.1092. Or add it to your system environment variables permanently through System Properties → Environment Variables.

113 110

114After migration, restart your shell, and then verify your installation:111If Git is installed in a non-standard location, adjust the path accordingly.

115 112

116On macOS/Linux/WSL:113### Windows: "installMethod is native, but claude command not found"

117 114

118```bash theme={null}115If you see this error after installation, the `claude` command isn't in your PATH. Add it manually:

119which claude # Should show an alias to ~/.claude/local/claude

120```

121 116

122On Windows:117<Steps>

118 <Step title="Open Environment Variables">

119 Press `Win + R`, type `sysdm.cpl`, and press Enter. Click **Advanced** → **Environment Variables**.

120 </Step>

123 121

124```powershell theme={null}122 <Step title="Edit User PATH">

125where claude # Should show path to claude executable123 Under "User variables", select **Path** and click **Edit**. Click **New** and add:

126```124

125 ```

126 %USERPROFILE%\.local\bin

127 ```

128 </Step>

129

130 <Step title="Restart your terminal">

131 Close and reopen PowerShell or CMD for changes to take effect.

132 </Step>

133</Steps>

127 134

128Verify installation:135Verify installation:

129 136

155 162

156This removes your stored authentication information and forces a clean login.163This removes your stored authentication information and forces a clean login.

157 164

165## Configuration file locations

166

167Claude Code stores configuration in several locations:

168

169| File | Purpose |

170| :---------------------------- | :------------------------------------------------------- |

171| `~/.claude/settings.json` | User settings (permissions, hooks, model overrides) |

172| `.claude/settings.json` | Project settings (checked into source control) |

173| `.claude/settings.local.json` | Local project settings (not committed) |

174| `~/.claude.json` | Global state (theme, OAuth, MCP servers, allowed tools) |

175| `.mcp.json` | Project MCP servers (checked into source control) |

176| `managed-settings.json` | [Managed settings](/en/settings#settings-files) |

177| `managed-mcp.json` | [Managed MCP servers](/en/mcp#managed-mcp-configuration) |

178

179On Windows, `~` refers to your user home directory, such as `C:\Users\YourName`.

180

181**Managed file locations:**

182

183* macOS: `/Library/Application Support/ClaudeCode/`

184* Linux/WSL: `/etc/claude-code/`

185* Windows: `C:\Program Files\ClaudeCode\`

186

187For details on configuring these files, see [Settings](/en/settings) and [MCP](/en/mcp).

188

189### Resetting configuration

190

191To reset Claude Code to default settings, you can remove the configuration files:

192

193```bash theme={null}

194# Reset all user settings and state

195rm ~/.claude.json

196rm -rf ~/.claude/

197

198# Reset project-specific settings

199rm -rf .claude/

200rm .mcp.json

201```

202

203<Warning>

204 This will remove all your settings, allowed tools, MCP server configurations, and session history.

205</Warning>

206

158## Performance and stability207## Performance and stability

159 208

160### High CPU or memory usage209### High CPU or memory usage

252 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.301 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.

253</Note>302</Note>

254 303

255For additional JetBrains configuration tips, see our [IDE integration guide](/en/vs-code#jetbrains-plugin-settings).304For additional JetBrains configuration tips, see our [JetBrains IDE guide](/en/jetbrains#plugin-settings).

256 305

257### Reporting Windows IDE integration issues (both native and WSL)306### Reporting Windows IDE integration issues (both native and WSL)

258 307

259If you're experiencing IDE integration problems on Windows, please [create an issue](https://github.com/anthropics/claude-code/issues) with the following information: whether you are native (git bash), or WSL1/WSL2, WSL networking mode (NAT or mirrored), IDE name/version, Claude Code extension/plugin version, and shell type (bash/zsh/etc)308If you're experiencing IDE integration problems on Windows, [create an issue](https://github.com/anthropics/claude-code/issues) with the following information:

260 309

261### ESC key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals310* Environment type: native Windows (Git Bash) or WSL1/WSL2

311* WSL networking mode (if applicable): NAT or mirrored

312* IDE name and version

313* Claude Code extension/plugin version

314* Shell type: Bash, Zsh, PowerShell, etc.

262 315

263If you're using Claude Code in JetBrains terminals and the ESC key doesn't interrupt the agent as expected, this is likely due to a keybinding clash with JetBrains' default shortcuts.316### Escape key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals

317

318If you're using Claude Code in JetBrains terminals and the `Esc` key doesn't interrupt the agent as expected, this is likely due to a keybinding clash with JetBrains' default shortcuts.

264 319

265To fix this issue:320To fix this issue:

266 321

270 * Click "Configure terminal keybindings" and delete the "Switch focus to Editor" shortcut325 * Click "Configure terminal keybindings" and delete the "Switch focus to Editor" shortcut

2713. Apply the changes3263. Apply the changes

272 327

273This allows the ESC key to properly interrupt Claude Code operations.328This allows the `Esc` key to properly interrupt Claude Code operations.

274 329

275## Markdown formatting issues330## Markdown formatting issues

276 331

300 355

301**Solutions:**356**Solutions:**

302 357

3031. **Ask Claude to add language tags**: Simply request "Please add appropriate language tags to all code blocks in this markdown file."3581. **Ask Claude to add language tags**: Request "Add appropriate language tags to all code blocks in this markdown file."

304 359

3052. **Use post-processing hooks**: Set up automatic formatting hooks to detect and add missing language tags. See the [markdown formatting hook example](/en/hooks-guide#markdown-formatting-hook) for implementation details.3602. **Use post-processing hooks**: Set up automatic formatting hooks to detect and add missing language tags. See the [markdown formatting hook example](/en/hooks-guide#markdown-formatting-hook) for implementation details.

306 361

323To minimize formatting issues:378To minimize formatting issues:

324 379

325* **Be explicit in requests**: Ask for "properly formatted markdown with language-tagged code blocks"380* **Be explicit in requests**: Ask for "properly formatted markdown with language-tagged code blocks"

326* **Use project conventions**: Document your preferred markdown style in [CLAUDE.md](/en/memory)381* **Use project conventions**: Document your preferred markdown style in [`CLAUDE.md`](/en/memory)

327* **Set up validation hooks**: Use post-processing hooks to automatically verify and fix common formatting issues382* **Set up validation hooks**: Use post-processing hooks to automatically verify and fix common formatting issues

328 383

329## Getting more help384## Getting more help

3342. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues3892. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues

3353. Run `/doctor` to check the health of your Claude Code installation3903. Run `/doctor` to check the health of your Claude Code installation

3364. Ask Claude directly about its capabilities and features - Claude has built-in access to its documentation3914. Ask Claude directly about its capabilities and features - Claude has built-in access to its documentation

392

393

394---

395

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

vs-code.md +201 −84

Details

~~1# Visual Studio Code~~1# Use Claude Code in VS Code

2 2

~~3> Use Claude Code with Visual Studio Code through our native extension or CLI integration~~3> Install and configure the Claude Code extension for VS Code. Get AI coding assistance with inline diffs, @-mentions, plan review, and keyboard shortcuts.

4 4

5<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=300652d5678c63905e6b0ea9e50835f8" alt="Claude Code VS Code Extension Interface" data-og-width="2500" width="2500" data-og-height="1155" height="1155" data-path="images/vs-code-extension-interface.jpg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=280&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=87630c671517a3d52e9aee627041696e 280w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=560&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=716b093879204beec8d952649ef75292 560w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=840&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=c1525d1a01513acd9d83d8b5a8fe2fc8 840w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1100&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=1d90021d58bbb51f871efec13af955c3 1100w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1650&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=7babdd25440099886f193cfa99af88ae 1650w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=2500&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=08c92eedfb56fe61a61e480fb63784b6 2500w" />5<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=300652d5678c63905e6b0ea9e50835f8" alt="VS Code editor with the Claude Code extension panel open on the right side, showing a conversation with Claude" data-og-width="2500" width="2500" data-og-height="1155" height="1155" data-path="images/vs-code-extension-interface.jpg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=280&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=87630c671517a3d52e9aee627041696e 280w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=560&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=716b093879204beec8d952649ef75292 560w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=840&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=c1525d1a01513acd9d83d8b5a8fe2fc8 840w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1100&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=1d90021d58bbb51f871efec13af955c3 1100w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1650&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=7babdd25440099886f193cfa99af88ae 1650w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=2500&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=08c92eedfb56fe61a61e480fb63784b6 2500w" />

6 6

~~7## VS Code Extension (Beta)~~7The VS Code extension provides a native graphical interface for Claude Code, integrated directly into your IDE. This is the recommended way to use Claude Code in VS Code.

8 8

9The VS Code extension, available in beta, lets you see Claude's changes in real-time through a native graphical interface integrated directly into your IDE. The VS Code extension makes it easier to access and interact with Claude Code for users who prefer a visual interface over the terminal.9With the extension, you can review and edit Claude's plans before accepting them, auto-accept edits as they're made, @-mention files with specific line ranges from your selection, access conversation history, and open multiple conversations in separate tabs or windows.

10 10

~~11### Features~~11## Prerequisites

12 12

~~13The VS Code extension provides:~~13* VS Code 1.98.0 or higher

14* An Anthropic account (you'll sign in when you first open the extension). If you're using a third-party provider like Amazon Bedrock or Google Vertex AI, see [Use third-party providers](#use-third-party-providers) instead.

14 15

~~15* **Native IDE experience**: Dedicated Claude Code sidebar panel accessed via the Spark icon~~16You don't need to install the Claude Code CLI first. However, some features like MCP server configuration require the CLI. See [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) for details.

~~16* **Plan mode with editing**: Review and edit Claude's plans before accepting them~~

~~17* **Auto-accept edits mode**: Automatically apply Claude's changes as they're made~~

~~18* **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 17

~~26### Requirements~~18## Install the extension

27 19

~~28* VS Code 1.98.0 or higher~~20Click the link for your IDE to install directly:

29 21

~~30### Installation~~22* [Install for VS Code](vscode:extension/anthropic.claude-code)

23* [Install for Cursor](cursor:extension/anthropic.claude-code)

31 24

~~32Download and install the extension from the [Visual Studio Code Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code).~~25Or in VS Code, press `Cmd+Shift+X` (Mac) or `Ctrl+Shift+X` (Windows/Linux) to open the Extensions view, search for "Claude Code", and click **Install**.

33 26

~~34### How It Works~~27<Note>You may need to restart VS Code or run "Developer: Reload Window" from the Command Palette after installation.</Note>

29## Get started

35 30

36Once installed, you can start using Claude Code through the VS Code interface:31Once installed, you can start using Claude Code through the VS Code interface:

37 32

~~381. Click the Spark icon in your editor's sidebar to open the Claude Code panel~~33<Steps>

~~392. Prompt Claude Code in the same way you would in the terminal~~34 <Step title="Open the Claude Code panel">

~~403. Watch as Claude analyzes your code and suggests changes~~35 Throughout VS Code, the Spark icon indicates Claude Code: <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=a734d84e785140016672f08e0abb236c" alt="Spark icon" style={{display: "inline", height: "0.85em", verticalAlign: "middle"}} data-og-width="16" width="16" data-og-height="16" height="16" data-path="images/vs-code-spark-icon.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=280&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=9a45aad9a84b9fa1701ac99a1f9aa4e9 280w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=560&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=3f4cb9254c4d4e93989c4b6bf9292f4b 560w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=840&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=e75ccc9faa3e572db8f291ceb65bb264 840w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=1100&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=f147bd81a381a62539a4ce361fac41c7 1100w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=1650&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=78fe68efaee5d6e844bbacab1b442ed5 1650w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=2500&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=efb8dbe1dfa722d094edc6ad2ad4bedb 2500w" />

~~414. Review and accept edits directly in the interface~~36

~~42 * **Tip**: Drag the sidebar wider to see inline diffs, then click on them to expand for full details~~37 The quickest way to open Claude is to click the Spark icon in the **Editor Toolbar** (top-right corner of the editor). The icon only appears when you have a file open.

39 <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=eb4540325d94664c51776dbbfec4cf02" alt="VS Code editor showing the Spark icon in the Editor Toolbar" data-og-width="2796" width="2796" data-og-height="734" height="734" data-path="images/vs-code-editor-icon.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=280&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=56f218d5464359d6480cfe23f70a923e 280w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=560&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=344a8db024b196c795a80dc85cacb8d1 560w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=840&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=f30bf834ee0625b2a4a635d552d87163 840w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=1100&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=81fdf984840e43a9f08ae42729d1484d 1100w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=1650&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=8b60fb32de54717093d512afaa99785c 1650w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=2500&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=893e6bda8f2e9d42c8a294d394f0b736 2500w" />

41 Other ways to open Claude Code:

43 * **Command Palette**: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux), type "Claude Code", and select an option like "Open in New Tab"

44 * **Status Bar**: Click **✱ Claude Code** in the bottom-right corner of the window. This works even when no file is open.

46 You can drag the Claude panel to reposition it anywhere in VS Code. See [Customize your workflow](#customize-your-workflow) for details.

47 </Step>

49 <Step title="Send a prompt">

50 Ask Claude to help with your code or files, whether that's explaining how something works, debugging an issue, or making changes.

52 <Tip>Select text in the editor and press `Alt+K` to insert an @-mention with the file path and line numbers directly into your prompt.</Tip>

54 Here's an example of asking about a particular line in a file:

56 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ede3ed8d8d5f940e01c5de636d009cfd" alt="VS Code editor with lines 2-3 selected in a Python file, and the Claude Code panel showing a question about those lines with an @-mention reference" data-og-width="3288" width="3288" data-og-height="1876" height="1876" data-path="images/vs-code-send-prompt.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=280&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=f40bde7b2c245fe8f0f5b784e8106492 280w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=560&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=fad66a27a9a6faa23b05370aa4f398b2 560w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=840&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=4539c8a3823ca80a5c8771f6c088ce9e 840w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=1100&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=fae8ebf300c7853409a562ffa46d9c71 1100w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=1650&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=22e4462bb8cf0c0ca20f8102bc4c971a 1650w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=2500&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=739bfd045f70fe7be1a109a53494590e 2500w" />

57 </Step>

59 <Step title="Review changes">

60 When Claude wants to edit a file, it shows you a diff and asks for permission. You can accept, reject, or tell Claude what to do instead.

62 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=e005f9b41c541c5c7c59c082f7c4841c" alt="VS Code showing a diff of Claude's proposed changes with a permission prompt asking whether to make the edit" data-og-width="3292" width="3292" data-og-height="1876" height="1876" data-path="images/vs-code-edits.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=280&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=cb5d41b81087f79b842a56b5a3304660 280w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=560&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=90bb691960decdc06393c3c21cd62c75 560w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=840&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=9a11bf878ba619e850380904ff4f38e8 840w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=1100&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=6dddbf596b4f69ec6245bdc5eb6dd487 1100w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=1650&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ef2713b8cbfd2cee97af817d813d64c7 1650w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=2500&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=1f7e1c52919cdfddf295f32a2ec7ae59 2500w" />

63 </Step>

64</Steps>

66For more ideas on what you can do with Claude Code, see [Common workflows](/en/common-workflows).

68## Customize your workflow

70Once you're up and running, you can reposition the Claude panel or switch to terminal mode.

72### Change the layout

74You can drag the Claude panel to reposition it anywhere in VS Code. Grab the panel's tab or title bar and drag it to:

76* **Secondary sidebar** (default): The right side of the window

77* **Primary sidebar**: The left sidebar with icons for Explorer, Search, etc.

78* **Editor area**: Opens Claude as a tab alongside your files

80<Note>

81 The Spark icon only appears in the Activity Bar (left sidebar icons) when the Claude panel is docked to the left. Since Claude defaults to the right side, use the Editor Toolbar icon to open Claude.

82</Note>

84### Switch to terminal mode

86By default, the extension opens a graphical chat panel. If you prefer the CLI-style interface, open the [Use Terminal setting](vscode://settings/claudeCode.useTerminal) and check the box.

88You can also open VS Code settings (`Cmd+,` on Mac or `Ctrl+,` on Windows/Linux), go to Extensions → Claude Code, and check **Use Terminal**.

90## VS Code commands and shortcuts

43 91

~~44### Using Third-Party Providers~~92Open the Command Palette (`Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Windows/Linux) and type "Claude Code" to see all available VS Code commands for the Claude Code extension:

45 93

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

95 These are VS Code commands for controlling the extension. For Claude Code slash commands (like `/help` or `/compact`), not all CLI commands are available in the extension yet. See [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) for details.

96</Note>

47 97

~~481. Open VS Code settings~~98| Command | Shortcut | Description |

~~492. Search for "Claude Code: Environment Variables"~~99| -------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------- |

~~503. Add the required environment variables~~100| Focus Input | `Cmd+Esc` (Mac) / `Ctrl+Esc` (Windows/Linux) | Toggle focus between editor and Claude |

101| Open in Side Bar | — | Open Claude in the left sidebar |

102| Open in Terminal | — | Open Claude in terminal mode |

103| Open in New Tab | `Cmd+Shift+Esc` (Mac) / `Ctrl+Shift+Esc` (Windows/Linux) | Open a new conversation as an editor tab |

104| Open in New Window | — | Open a new conversation in a separate window |

105| New Conversation | `Cmd+N` (Mac) / `Ctrl+N` (Windows/Linux) | Start a new conversation (when Claude is focused) |

106| Insert @-Mention Reference | `Alt+K` | Insert a reference to the current file (includes line numbers if text is selected) |

107| Show Logs | — | View extension debug logs |

108| Logout | — | Sign out of your Anthropic account |

51 109

~~52#### Environment Variables~~110Use **Open in New Tab** or **Open in New Window** to run multiple conversations simultaneously. Each tab or window maintains its own conversation history and context.

53 111

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

68 113

~~69For detailed setup instructions and additional configuration options, see:~~114The extension has two types of settings:

70 115

~~71* [Claude Code on Amazon Bedrock](/en/amazon-bedrock)~~116* **Extension settings**: Open with `Cmd+,` (Mac) or `Ctrl+,` (Windows/Linux), then go to Extensions → Claude Code.

~~72* [Claude Code on Microsoft Foundry](/en/microsoft-foundry)~~

~~73* [Claude Code on Google Vertex AI](/en/google-vertex-ai)~~

74 117

~~75### Not Yet Implemented~~118 | Setting | Description |

119 | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

120 | Selected Model | Default model for new conversations. Change per-session with `/model`. |

121 | Use Terminal | Launch Claude in terminal mode instead of graphical panel |

122 | Initial Permission Mode | Controls approval prompts for file edits and commands. Defaults to `default` (ask before each action). |

123 | Preferred Location | Default location: sidebar (right) or panel (new tab) |

124 | Autosave | Auto-save files before Claude reads or writes them |

125 | Use Ctrl+Enter to Send | Use Ctrl/Cmd+Enter instead of Enter to send prompts |

126 | Enable New Conversation Shortcut | Enable Cmd/Ctrl+N to start a new conversation |

127 | Respect Git Ignore | Exclude .gitignore patterns from file searches |

128 | Environment Variables | Set environment variables for the Claude process. **Not recommended**—use [Claude Code settings](/en/settings) instead so configuration is shared between extension and CLI. |

129 | Disable Login Prompt | Skip authentication prompts (for third-party provider setups) |

130 | Allow Dangerously Skip Permissions | Bypass all permission prompts. **Use with extreme caution**—recommended only for isolated sandboxes with no internet access. |

131 | Claude Process Wrapper | Executable path used to launch the Claude process |

76 132

~~77The following features are not yet available in the VS Code extension:~~133* **Claude Code settings** (`~/.claude/settings.json`): These settings are shared between the VS Code extension and the CLI. Use this file for allowed commands and directories, environment variables, hooks, and MCP servers. See the [settings documentation](/en/settings) for details.

78 134

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.135## Use third-party providers

~~80* **Subagents configuration**: Configure [subagents through the CLI](/en/sub-agents) to use them in VS Code~~

~~81* **Checkpoints**: Save and restore conversation state at specific points~~

~~82* **Conversation rewinding**: The `/rewind` command is coming soon~~

~~83* **Advanced shortcuts**:~~

~~84 * `#` shortcut to add to memory (not supported)~~

~~85 * `!` shortcut to run bash commands directly (not supported)~~

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

~~89We are working on adding these features in future updates.~~137By default, Claude Code connects directly to Anthropic's API. If your organization uses Amazon Bedrock, Google Vertex AI, or Microsoft Foundry to access Claude, configure the extension to use your provider instead:

90 138

~~91## Security Considerations~~139<Steps>

140 <Step title="Disable login prompt">

141 Open the [Disable Login Prompt setting](vscode://settings/claudeCode.disableLoginPrompt) and check the box.

92 142

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.143 You can also open VS Code settings (`Cmd+,` on Mac or `Ctrl+,` on Windows/Linux), search for "Claude Code login", and check **Disable Login Prompt**.

144 </Step>

94 145

~~95When running in VS Code, consider:~~146 <Step title="Configure your provider">

147 Follow the setup guide for your provider:

96 148

~~97* Enabling [VS Code Restricted Mode](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode) for untrusted workspaces~~149 * [Claude Code on Amazon Bedrock](/en/amazon-bedrock)

~~98* Using manual approval mode for edits~~150 * [Claude Code on Google Vertex AI](/en/google-vertex-ai)

~~99* Taking extra care to ensure Claude is only used with trusted prompts~~151 * [Claude Code on Microsoft Foundry](/en/microsoft-foundry)

100 152

101## Legacy CLI Integration153 These guides cover configuring your provider in `~/.claude/settings.json`, which ensures your settings are shared between the VS Code extension and the CLI.

154 </Step>

155</Steps>

102 156

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).157## VS Code extension vs. Claude Code CLI

104 158

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.159The extension doesn't yet have full feature parity with the CLI. If you need CLI-only features, you can run `claude` directly in VS Code's integrated terminal.

106 160

107Both the extension and CLI integration work with Visual Studio Code, Cursor, Windsurf, and VSCodium.161| Feature | CLI | VS Code Extension |

162| ----------------- | ------------------------------ | ---------------------------------------- |

163| Slash commands | [Full set](/en/slash-commands) | Subset (type `/` to see available) |

164| MCP server config | Yes | No (configure via CLI, use in extension) |

165| Checkpoints | Yes | Coming soon |

166| `!` bash shortcut | Yes | No |

167| Tab completion | Yes | No |

108 168

109## Troubleshooting169### Run CLI in VS Code

110 170

111### Extension Not Installing171To 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.

112 172

113* Ensure you have a compatible version of VS Code (1.85.0 or later)173If using an external terminal, run `/ide` inside Claude Code to connect it to VS Code.

174

175### Switch between extension and CLI

176

177The extension and CLI share the same conversation history. To continue an extension conversation in the CLI, run `claude --resume` in the terminal. This opens an interactive picker where you can search for and select your conversation.

178

179## Security considerations

180

181With auto-edit permissions enabled, Claude Code can modify VS Code configuration files (like `settings.json` or `tasks.json`) that VS Code may execute automatically. This could potentially bypass Claude Code's normal permission prompts.

182

183To reduce risk when working with untrusted code:

184

185* Enable [VS Code Restricted Mode](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode) for untrusted workspaces

186* Use manual approval mode instead of auto-accept for edits

187* Review changes carefully before accepting them

188

189## Fix common issues

190

191### Extension won't install

192

193* Ensure you have a compatible version of VS Code (1.98.0 or later)

114* Check that VS Code has permission to install extensions194* Check that VS Code has permission to install extensions

115* Try installing directly from the Marketplace website195* Try installing directly from the Marketplace website

116 196

117### Claude Code Never Responds197### Spark icon not visible

198

199The Spark icon appears in the **Editor Toolbar** (top-right of editor) when you have a file open. If you don't see it:

200

2011. **Open a file**: The icon requires a file to be open—having just a folder open isn't enough

2022. **Check VS Code version**: Requires 1.98.0 or higher (Help → About)

2033. **Restart VS Code**: Run "Developer: Reload Window" from the Command Palette

2044. **Disable conflicting extensions**: Temporarily disable other AI extensions (Cline, Continue, etc.)

2055. **Check workspace trust**: The extension doesn't work in Restricted Mode

206

207Alternatively, click "✱ Claude Code" in the **Status Bar** (bottom-right corner)—this works even without a file open. You can also use the **Command Palette** (`Cmd+Shift+P` / `Ctrl+Shift+P`) and type "Claude Code".

118 208

119If Claude Code is not responding to your prompts:209### Claude Code never responds

210

211If Claude Code isn't responding to your prompts:

120 212

1211. **Check your internet connection**: Ensure you have a stable internet connection2131. **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 persists2142. **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 messages2153. **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 error2164. **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 217

126### Legacy Integration Not Working218### Standalone CLI not connecting to IDE

127 219

128* Ensure you're running Claude Code from VS Code's integrated terminal220* Ensure you're running Claude Code from VS Code's integrated terminal (not an external terminal)

129* Ensure the CLI for your IDE variant is installed:221* Ensure the CLI for your IDE variant is installed:

130 * VS Code: `code` command should be available222 * VS Code: `code` command should be available

131 * Cursor: `cursor` command should be available223 * Cursor: `cursor` command should be available

132 * Windsurf: `windsurf` command should be available224 * Windsurf: `windsurf` command should be available

133 * VSCodium: `codium` command should be available225 * VSCodium: `codium` command should be available

134* If the command isn't installed:226* If the command isn't available, install it from the Command Palette → "Shell Command: Install 'code' command in PATH"

135 1. Open command palette with `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)227

136 2. Search for "Shell Command: Install 'code' command in PATH" (or equivalent for your IDE)228## Uninstall the extension

229

230To uninstall the Claude Code extension:

231

2321. Open the Extensions view (`Cmd+Shift+X` on Mac or `Ctrl+Shift+X` on Windows/Linux)

2332. Search for "Claude Code"

2343. Click **Uninstall**

235

236To also remove extension data and reset all settings:

237

238```bash theme={null}

239rm -rf ~/.vscode/globalStorage/anthropic.claude-code

240```

241

242For additional help, see the [troubleshooting guide](/en/troubleshooting).

243

244## Next steps

245

246Now that you have Claude Code set up in VS Code:

247

248* [Explore common workflows](/en/common-workflows) to get the most out of Claude Code

249* [Set up MCP servers](/en/mcp) to extend Claude's capabilities with external tools. Configure servers using the CLI, then use them in the extension.

250* [Configure Claude Code settings](/en/settings) to customize allowed commands, hooks, and more. These settings are shared between the extension and CLI.

251

252

253---

137 254

138For additional help, see our [troubleshooting guide](/en/troubleshooting).255> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

Anthropic - Claude Code Docs Changes 2025-11-24 21:01 UTC → 2026-01-19 00:05 UTC