Documentation — Spybara

amazon-bedrock.md +7 −9

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

75 75

76##### Configuration settings explained76##### Configuration settings explained

77 77

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.78**`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 79

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:80**`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 81

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

83{83{

121 121

122<Note>122<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`).123 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>124</Note>

125 125

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

137export DISABLE_PROMPT_CACHING=1137export DISABLE_PROMPT_CACHING=1

138```138```

139 139

140<Note>140<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 141

144### 5. Output token configuration142### 5. Output token configuration

145 143

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

147 145

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

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

153 151

154**Why these values:**152**Why these values:**

155 153

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

157 155

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

159 157

claude-code-on-the-web.md +2 −2

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

473 473

474## Best practices474## Best practices

475 475

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

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

478 478

479## Related resources479## Related resources

cli-reference.md +3 −3

Details

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

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

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

68 68

~~70| :------------ | :------- | :-------------------------------------------------------------------------------------------------------------- |~~70| :------------ | :------- | :--------------------------------------------------------------------------------------------------------------------- |

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

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

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

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

75 75

76Example:76Example:

common-workflows.md +18 −22

Details

173 </Step>173 </Step>

174 174

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

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

177 177

178 ```178 ```

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

201 201

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

203 203

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

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

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

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

208 </Step>208 </Step>

209</Steps>209</Steps>

210 210

235 235

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

237 237

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

239 239

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

241 241

247 247

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

249 249

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

251 251

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

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

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

264```264```

265 265

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

267 267

268```268```

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

315 </Step>315 </Step>

316</Steps>316</Steps>

317 317

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

319 Tips:

320 319

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

322 * Request both unit and integration tests when appropriate

323 * Have Claude explain the testing strategy

324</Tip>

325 321

326***322***

327 323

336 ```332 ```

337 </Step>333 </Step>

338 334

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

340 ```336 ```

341 > create a pr 337 > create a pr

342 ```338 ```

496 Tips:492 Tips:

497 493

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

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

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

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

502</Tip>498</Tip>

503 499

504***500***

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.513 > 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 ```514 ```

519 515

520 Claude will gather relevant information from your codebase and516 Claude gathers relevant information from your codebase and

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

522 </Step>518 </Step>

523 519

524 <Step title="Refine the thinking with follow-up prompts">520 <Step title="Refine the thinking with follow-up prompts">

554</Tip>550</Tip>

555 551

556<Note>552<Note>

557 Claude will display its thinking process as italic gray text above the553 Claude displays its thinking process as italic gray text above the

558 response.554 response.

559</Note>555</Note>

560 556

822<Tip>818<Tip>

823 Tips:819 Tips:

824 820

825 * Command names are derived from the filename (e.g., `optimize.md` becomes `/optimize`)821 * 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)822 * 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 repository823 * 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 invoked824 * The Markdown file content becomes the prompt sent to Claude when the command is invoked

829</Tip>825</Tip>

850 > /fix-issue 123 846 > /fix-issue 123

851 ```847 ```

852 848

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

854 </Step>850 </Step>

855</Steps>851</Steps>

856 852

data-usage.md +1 −1

Details

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

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

19 19

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

21 21

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

23 23

desktop.md +1 −1

Details

13Claude Code on desktop provides:13Claude Code on desktop provides:

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` worktree15* **Parallel local sessions with `git` worktrees**: Run multiple Claude Code sessions simultaneously in the same repository, each with its own isolated `git` worktree

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

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

18 18

19## Installation19## Installation

devcontainer.md +1 −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>

github-actions.md +5 −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

gitlab-ci-cd.md +1 −1

Details

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)

google-vertex-ai.md +3 −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:

headless.md +1 −1

Details

109 109

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

111 111

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

113 113

114```bash theme={null}114```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 --verbose115echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explain this code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

hooks.md +5 −6

Details

258| --------------------- | ----------------------- | ------------------------------ |258| --------------------- | ----------------------- | ------------------------------ |

404 404

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

406 406

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

408 408

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

410#!/bin/bash410#!/bin/bash

590 590

591## Hook Output591## Hook Output

592 592

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

595and the user.595and the user.

596 596

779```779```

780 780

781<Note>781<Note>

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

785</Note>784</Note>

786 785

877<Note>876<Note>

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

879 878

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

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

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

883 882

hooks-guide.md +1 −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

jetbrains.md +2 −2

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

68 68

69#### General Settings69#### General Settings

70 70

~~71* **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`)

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

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

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

mcp.md +8 −8

Details

203 </>;203 </>;

204};204};

205 205

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

207 207

208## What you can do with MCP208## What you can do with MCP

209 209

211 211

212* **Implement features from issue trackers**: "Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub."212* **Implement features from issue trackers**: "Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub."

213* **Analyze monitoring data**: "Check Sentry and Statsig to check the usage of the feature described in ENG-4521."213* **Analyze monitoring data**: "Check Sentry and Statsig to check the usage of the feature described in ENG-4521."

214* **Query databases**: "Find emails of 10 random users who used feature ENG-4521, based on our Postgres database."214* **Query databases**: "Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database."

215* **Integrate designs**: "Update our standard email template based on the new Figma designs that were posted in Slack"215* **Integrate designs**: "Update our standard email template based on the new Figma designs that were posted in Slack"

216* **Automate workflows**: "Create Gmail drafts inviting these 10 users to a feedback session about the new feature."216* **Automate workflows**: "Create Gmail drafts inviting these 10 users to a feedback session about the new feature."

217 217

321 * `local` (default): Available only to you in the current project (was called `project` in older versions)321 * `local` (default): Available only to you in the current project (was called `project` in older versions)

322 * `project`: Shared with everyone in the project via `.mcp.json` file322 * `project`: Shared with everyone in the project via `.mcp.json` file

323 * `user`: Available to you across all projects (was called `global` in older versions)323 * `user`: Available to you across all projects (was called `global` in older versions)

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

325 * Configure MCP server startup timeout using the MCP\_TIMEOUT environment variable (e.g., `MCP_TIMEOUT=10000 claude` sets a 10-second timeout)325 * Configure MCP server startup timeout using the MCP\_TIMEOUT environment variable (for example, `MCP_TIMEOUT=10000 claude` sets a 10-second timeout)

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

327 * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication327 * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication

328</Tip>328</Tip>

329 329

459 459

460* **Local scope**: Personal servers, experimental configurations, or sensitive credentials specific to one project460* **Local scope**: Personal servers, experimental configurations, or sensitive credentials specific to one project

461* **Project scope**: Team-shared servers, project-specific tools, or services required for collaboration461* **Project scope**: Team-shared servers, project-specific tools, or services required for collaboration

462* **User scope**: Personal utilities needed across multiple projects, development tools, or frequently-used services462* **User scope**: Personal utilities needed across multiple projects, development tools, or frequently used services

463 463

464<Note>464<Note>

465 **Where are MCP servers stored?**465 **Where are MCP servers stored?**

663 * It reads the Claude Desktop configuration file from its standard location on those platforms663 * It reads the Claude Desktop configuration file from its standard location on those platforms

664 * Use the `--scope user` flag to add servers to your user configuration664 * Use the `--scope user` flag to add servers to your user configuration

665 * Imported servers will have the same names as in Claude Desktop665 * Imported servers will have the same names as in Claude Desktop

666 * If servers with the same names already exist, they will get a numerical suffix (e.g., `server_1`)666 * If servers with the same names already exist, they will get a numerical suffix (for example, `server_1`)

667</Tip>667</Tip>

668 668

669## Use Claude Code as an MCP server669## Use Claude Code as an MCP server

722 722

723 * The server provides access to Claude's tools like View, Edit, LS, etc.723 * The server provides access to Claude's tools like View, Edit, LS, etc.

724 * In Claude Desktop, try asking Claude to read files in a directory, make edits, and more.724 * In Claude Desktop, try asking Claude to read files in a directory, make edits, and more.

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

726</Tip>726</Tip>

727 727

728## MCP output limits and warnings728## MCP output limits and warnings

model-config.md +2 −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) |

monitoring-usage.md +58 −58

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](/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.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.

45 45

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

63</Note>63</Note>

64 64

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

66 66

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

68 68

70| ----------------------------------------------- | --------------------------------------------------------- | ------------------------------------ |70| ----------------------------------------------- | --------------------------------------------------------- | ------------------------------------ |

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

~~87### Metrics Cardinality Control~~87### Metrics cardinality control

88 88

89The following environment variables control which attributes are included in metrics to manage cardinality:89The following environment variables control which attributes are included in metrics to manage cardinality:

90 90

96 96

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

98 98

~~99### Dynamic Headers~~99### Dynamic headers

100 100

101For enterprise environments that require dynamic authentication, you can configure a script to generate headers dynamically:101For enterprise environments that require dynamic authentication, you can configure a script to generate headers dynamically:

102 102

103#### Settings Configuration103#### Settings configuration

104 104

105Add to your `.claude/settings.json`:105Add to your `.claude/settings.json`:

106 106

110}110}

111```111```

112 112

113#### Script Requirements113#### Script requirements

114 114

115The script must output valid JSON with string key-value pairs representing HTTP headers:115The script must output valid JSON with string key-value pairs representing HTTP headers:

116 116

120echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"120echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

121```121```

122 122

123#### Important Limitations123#### Important limitations

124 124

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

126 126

127For scenarios requiring frequent token refresh, use an OpenTelemetry Collector as a proxy that can refresh its own headers.127For scenarios requiring frequent token refresh, use an OpenTelemetry Collector as a proxy that can refresh its own headers.

128 128

129### Multi-Team Organization Support129### Multi-team organization support

130 130

131Organizations with multiple teams or departments can add custom attributes to distinguish between different groups using the `OTEL_RESOURCE_ATTRIBUTES` environment variable:131Organizations with multiple teams or departments can add custom attributes to distinguish between different groups using the `OTEL_RESOURCE_ATTRIBUTES` environment variable:

132 132

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

167 ```167 ```

168 168

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

170</Warning>170</Warning>

171 171

172### Example Configurations172### Example configurations

173 173

174```bash theme={null}174```bash theme={null}

175# Console debugging (1-second intervals)175# Console debugging (1-second intervals)

214export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317214export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

215```215```

216 216

217## Available Metrics and Events217## Available metrics and events

218 218

219### Standard Attributes219### Standard attributes

220 220

221All metrics and events share these standard attributes:221All metrics and events share these standard attributes:

222 222

224| ------------------- | ------------------------------------------------------------- | --------------------------------------------------- |224| ------------------- | -------------------------------------------------------------------- | --------------------------------------------------- |

230 230

231### Metrics231### Metrics

232 232

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

245 245

246### Metric Details246### Metric details

247 247

248#### Session Counter248#### Session counter

249 249

250Incremented at the start of each session.250Incremented at the start of each session.

251 251

253 253

254* All [standard attributes](#standard-attributes)254* All [standard attributes](#standard-attributes)

255 255

256#### Lines of Code Counter256#### Lines of code counter

257 257

258Incremented when code is added or removed.258Incremented when code is added or removed.

259 259

262* All [standard attributes](#standard-attributes)262* All [standard attributes](#standard-attributes)

263* `type`: (`"added"`, `"removed"`)263* `type`: (`"added"`, `"removed"`)

264 264

265#### Pull Request Counter265#### Pull request counter

266 266

267Incremented when creating pull requests via Claude Code.267Incremented when creating pull requests via Claude Code.

268 268

270 270

271* All [standard attributes](#standard-attributes)271* All [standard attributes](#standard-attributes)

272 272

273#### Commit Counter273#### Commit counter

274 274

275Incremented when creating git commits via Claude Code.275Incremented when creating git commits via Claude Code.

276 276

278 278

279* All [standard attributes](#standard-attributes)279* All [standard attributes](#standard-attributes)

280 280

281#### Cost Counter281#### Cost counter

282 282

283Incremented after each API request.283Incremented after each API request.

284 284

285**Attributes**:285**Attributes**:

286 286

287* All [standard attributes](#standard-attributes)287* All [standard attributes](#standard-attributes)

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

289 289

290#### Token Counter290#### Token counter

291 291

292Incremented after each API request.292Incremented after each API request.

293 293

295 295

296* All [standard attributes](#standard-attributes)296* All [standard attributes](#standard-attributes)

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

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

299 299

300#### Code Edit Tool Decision Counter300#### Code edit tool decision counter

301 301

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

303 303

306* All [standard attributes](#standard-attributes)306* All [standard attributes](#standard-attributes)

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

308* `decision`: User decision (`"accept"`, `"reject"`)308* `decision`: User decision (`"accept"`, `"reject"`)

309* `language`: Programming language of the edited file (e.g., `"TypeScript"`, `"Python"`, `"JavaScript"`, `"Markdown"`). Returns `"unknown"` for unrecognized file extensions.309* `language`: Programming language of the edited file (for example, `"TypeScript"`, `"Python"`, `"JavaScript"`, `"Markdown"`). Returns `"unknown"` for unrecognized file extensions.

310 310

311#### Active Time Counter311#### Active time counter

312 312

313Tracks actual time spent actively using Claude Code (not idle time). This metric is incremented during user interactions such as typing prompts or receiving responses.313Tracks actual time spent actively using Claude Code (not idle time). This metric is incremented during user interactions such as typing prompts or receiving responses.

314 314

320 320

321Claude Code exports the following events via OpenTelemetry logs/events (when `OTEL_LOGS_EXPORTER` is configured):321Claude Code exports the following events via OpenTelemetry logs/events (when `OTEL_LOGS_EXPORTER` is configured):

322 322

323#### User Prompt Event323#### User prompt event

324 324

325Logged when a user submits a prompt.325Logged when a user submits a prompt.

326 326

334* `prompt_length`: Length of the prompt334* `prompt_length`: Length of the prompt

335* `prompt`: Prompt content (redacted by default, enable with `OTEL_LOG_USER_PROMPTS=1`)335* `prompt`: Prompt content (redacted by default, enable with `OTEL_LOG_USER_PROMPTS=1`)

336 336

337#### Tool Result Event337#### Tool result event

338 338

339Logged when a tool completes execution.339Logged when a tool completes execution.

340 340

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

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

356 356

357#### API Request Event357#### API request event

358 358

359Logged for each API request to Claude.359Logged for each API request to Claude.

360 360

365* All [standard attributes](#standard-attributes)365* All [standard attributes](#standard-attributes)

366* `event.name`: `"api_request"`366* `event.name`: `"api_request"`

367* `event.timestamp`: ISO 8601 timestamp367* `event.timestamp`: ISO 8601 timestamp

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

369* `cost_usd`: Estimated cost in USD369* `cost_usd`: Estimated cost in USD

370* `duration_ms`: Request duration in milliseconds370* `duration_ms`: Request duration in milliseconds

371* `input_tokens`: Number of input tokens371* `input_tokens`: Number of input tokens

373* `cache_read_tokens`: Number of tokens read from cache373* `cache_read_tokens`: Number of tokens read from cache

374* `cache_creation_tokens`: Number of tokens used for cache creation374* `cache_creation_tokens`: Number of tokens used for cache creation

375 375

376#### API Error Event376#### API error event

377 377

378Logged when an API request to Claude fails.378Logged when an API request to Claude fails.

379 379

384* All [standard attributes](#standard-attributes)384* All [standard attributes](#standard-attributes)

385* `event.name`: `"api_error"`385* `event.name`: `"api_error"`

386* `event.timestamp`: ISO 8601 timestamp386* `event.timestamp`: ISO 8601 timestamp

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

388* `error`: Error message388* `error`: Error message

389* `status_code`: HTTP status code (if applicable)389* `status_code`: HTTP status code (if applicable)

390* `duration_ms`: Request duration in milliseconds390* `duration_ms`: Request duration in milliseconds

391* `attempt`: Attempt number (for retried requests)391* `attempt`: Attempt number (for retried requests)

392 392

393#### Tool Decision Event393#### Tool decision event

394 394

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

396 396

401* All [standard attributes](#standard-attributes)401* All [standard attributes](#standard-attributes)

402* `event.name`: `"tool_decision"`402* `event.name`: `"tool_decision"`

403* `event.timestamp`: ISO 8601 timestamp403* `event.timestamp`: ISO 8601 timestamp

404* `tool_name`: Name of the tool (e.g., "Read", "Edit", "Write", "NotebookEdit", etc.)404* `tool_name`: Name of the tool (for example, "Read", "Edit", "Write", "NotebookEdit")

405* `decision`: Either `"accept"` or `"reject"`405* `decision`: Either `"accept"` or `"reject"`

406* `source`: Decision source - `"config"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`406* `source`: Decision source - `"config"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`

407 407

408## Interpreting Metrics and Events Data408## Interpreting metrics and events data

409 409

410The metrics exported by Claude Code provide valuable insights into usage patterns and productivity. Here are some common visualizations and analyses you can create:410The metrics exported by Claude Code provide valuable insights into usage patterns and productivity. Here are some common visualizations and analyses you can create:

411 411

412### Usage Monitoring412### Usage monitoring

413 413

414| Metric | Analysis Opportunity |414| Metric | Analysis Opportunity |

415| ------------------------------------------------------------- | --------------------------------------------------------- |415| ------------------------------------------------------------- | --------------------------------------------------------- |

420 420

421### Cost Monitoring421### Cost monitoring

422 422

423The `claude_code.cost.usage` metric helps with:423The `claude_code.cost.usage` metric helps with:

424 424

429 Cost metrics are approximations. For official billing data, refer to your API provider (Claude Console, AWS Bedrock, or Google Cloud Vertex).429 Cost metrics are approximations. For official billing data, refer to your API provider (Claude Console, AWS Bedrock, or Google Cloud Vertex).

430</Note>430</Note>

431 431

432### Alerting and Segmentation432### Alerting and segmentation

433 433

434Common alerts to consider:434Common alerts to consider:

435 435

439 439

440All metrics can be segmented by `user.account_uuid`, `organization.id`, `session.id`, `model`, and `app.version`.440All metrics can be segmented by `user.account_uuid`, `organization.id`, `session.id`, `model`, and `app.version`.

441 441

442### Event Analysis442### Event analysis

443 443

444The event data provides detailed insights into Claude Code interactions:444The event data provides detailed insights into Claude Code interactions:

445 445

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

447 447

448* Most frequently used tools448* Most frequently used tools

449* Tool success rates449* Tool success rates

450* Average tool execution times450* Average tool execution times

451* Error patterns by tool type451* Error patterns by tool type

452 452

453**Performance Monitoring**: Track API request durations and tool execution times to identify performance bottlenecks.453**Performance Monitoring**: track API request durations and tool execution times to identify performance bottlenecks.

454 454

455## Backend Considerations455## Backend considerations

456 456

457Your choice of metrics and logs backends will determine the types of analyses you can perform:457Your choice of metrics and logs backends determines the types of analyses you can perform:

458 458

459### For Metrics:459### For metrics

460 460

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

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

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

464 464

465### For Events/Logs:465### For events/logs

466 466

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

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

469* **Full-featured observability platforms (e.g., Honeycomb, Datadog)**: Correlation between metrics and events469* **Full-featured observability platforms (for example, Honeycomb, Datadog)**: Correlation between metrics and events

470 470

471For organizations requiring Daily/Weekly/Monthly Active User (DAU/WAU/MAU) metrics, consider backends that support efficient unique value queries.471For organizations requiring Daily/Weekly/Monthly Active User (DAU/WAU/MAU) metrics, consider backends that support efficient unique value queries.

472 472

473## Service Information473## Service information

474 474

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

476 476

477* `service.name`: `claude-code`477* `service.name`: `claude-code`

478* `service.version`: Current Claude Code version478* `service.version`: Current Claude Code version

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

480* `os.version`: Operating system version string480* `os.version`: Operating system version string

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

482* `wsl.version`: WSL version number (only present when running on Windows Subsystem for Linux)482* `wsl.version`: WSL version number (only present when running on Windows Subsystem for Linux)

483* Meter Name: `com.anthropic.claude_code`483* Meter Name: `com.anthropic.claude_code`

484 484

485## ROI Measurement Resources485## ROI measurement resources

486 486

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

488 488

489## Security/Privacy Considerations489## Security/privacy considerations

490 490

491* Telemetry is opt-in and requires explicit configuration491* Telemetry is opt-in and requires explicit configuration

492* Sensitive information like API keys or file contents are never included in metrics or events492* Sensitive information like API keys or file contents are never included in metrics or events

overview.md +2 −2

Details

45claude45claude

46```46```

47 47

~~48You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 mins) →](/en/quickstart)~~48You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 minutes) →](/en/quickstart)

49 49

50<Tip>50<Tip>

51 See [advanced setup](/en/setup) for installation options or [troubleshooting](/en/troubleshooting) if you hit issues.51 See [advanced setup](/en/setup) for installation options or [troubleshooting](/en/troubleshooting) if you hit issues.

59 59

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

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

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

64 64

65## Why developers love Claude Code65## Why developers love Claude Code

plugin-marketplaces.md +1 −1

Details

plugins.md +1 −1

Details

341 341

3421. **Add documentation**: Include a README.md with installation and usage instructions3421. **Add documentation**: Include a README.md with installation and usage instructions

3432. **Version your plugin**: Use semantic versioning in your `plugin.json`3432. **Version your plugin**: Use semantic versioning in your `plugin.json`

3443. **Create or use a marketplace**: Distribute through plugin marketplaces for easy installation3443. **Create or use a marketplace**: Distribute through plugin marketplaces for installation

3454. **Test with others**: Have team members test the plugin before wider distribution3454. **Test with others**: Have team members test the plugin before wider distribution

346 346

347<Note>347<Note>

sandboxing.md +1 −1

Details

141 141

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

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

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.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 in cases where additional isolation is otherwise enforced.

145 145

146## Advanced usage146## Advanced usage

147 147

settings.md +22 −26

Details

71| `hooks` | Configure custom commands to run before or after tool executions. See [hooks documentation](/en/hooks) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |71| `hooks` | Configure custom commands to run before or after tool executions. See [hooks documentation](/en/hooks) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |

74| `statusLine` | Configure a custom status line to display context. See [statusLine documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |74| `statusLine` | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |

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

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

111| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |111| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |

112| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |112| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |

136}136}

137```137```

138 138

139**Filesystem access** is controlled via Read/Edit permissions:139**Filesystem and network restrictions** use standard permission rules:

140 140

141* Read deny rules block file reads in sandbox141* Use `Read` deny rules to block Claude from reading specific files or directories

142* Edit allow rules permit file writes (in addition to the defaults, e.g. the current working directory)142* Use `Edit` allow rules to let Claude write to directories beyond the current working directory

143* Edit deny rules block writes within allowed paths143* Use `Edit` deny rules to block writes to specific paths

~~144~~ 144* Use `WebFetch` allow/deny rules to control which network domains Claude can access

145**Network access** is controlled via WebFetch permissions:

~~146~~

147* WebFetch allow rules permit network domains

148* WebFetch deny rules block network domains

149 145

150### Settings precedence146### Settings precedence

151 147

152Settings are applied in order of precedence (highest to lowest):148Settings apply in order of precedence. From highest to lowest:

153 149

1541. **Enterprise managed policies** (`managed-settings.json`)1501. **Enterprise managed policies** (`managed-settings.json`)

155 * Deployed by IT/DevOps151 * Deployed by IT/DevOps

156 * Cannot be overridden152 * Can't be overridden

157 153

1582. **Command line arguments**1542. **Command line arguments**

159 * Temporary overrides for a specific session155 * Temporary overrides for a specific session

169 165

170This hierarchy ensures that enterprise security policies are always enforced while still allowing teams and individuals to customize their experience.166This hierarchy ensures that enterprise security policies are always enforced while still allowing teams and individuals to customize their experience.

171 167

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

169

172### Key points about the configuration system170### Key points about the configuration system

173 171

174* **Memory files (CLAUDE.md)**: Contain instructions and context that Claude loads at startup172* **Memory files (`CLAUDE.md`)**: Contain instructions and context that Claude loads at startup

175* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior173* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior

176* **Slash commands**: Custom commands that can be invoked during a session with `/command-name`174* **Slash commands**: Custom commands that can be invoked during a session with `/command-name`

177* **MCP servers**: Extend Claude Code with additional tools and integrations175* **MCP servers**: Extend Claude Code with additional tools and integrations

178* **Precedence**: Higher-level configurations (Enterprise) override lower-level ones (User/Project)176* **Precedence**: Higher-level configurations (Enterprise) override lower-level ones (User/Project)

179* **Inheritance**: Settings are merged, with more specific settings adding to or overriding broader ones177* **Inheritance**: Settings are merged, with more specific settings adding to or overriding broader ones

180 178

181### System prompt availability179### System prompt

182 180

183<Note>181Claude Code's internal system prompt is not published. To add custom instructions, use `CLAUDE.md` files or the `--append-system-prompt` flag.

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

185</Note>

186 182

187### Excluding sensitive files183### Excluding sensitive files

188 184

189To 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:185To 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:

190 186

191```json theme={null}187```json theme={null}

192{188{

343| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |339| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |

346| `CLAUDE_CODE_SHELL_PREFIX` | Command prefix to wrap all bash commands (e.g., for logging or auditing). Example: `/path/to/logger.sh` will execute `/path/to/logger.sh <command>` |342| `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>` |

372| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum number of characters for slash command metadata shown to [SlashCommand tool](/en/slash-commands#slashcommand-tool) (default: 15000) |368| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum number of characters for slash command metadata shown to [SlashCommand tool](/en/slash-commands#slashcommand-tool) (default: 15000) |

407 403

408The Bash tool executes shell commands with the following persistence behavior:404The Bash tool executes shell commands with the following persistence behavior:

409 405

410* **Working directory persists**: When Claude changes the working directory (e.g., `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.406* **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.

411* **Environment variables do NOT persist**: Environment variables set in one Bash command (e.g., `export MY_VAR=value`) are **not** available in subsequent Bash commands. Each Bash command runs in a fresh shell environment.407* **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.

412 408

413To make environment variables available in Bash commands, you have **three options**:409To make environment variables available in Bash commands, you have **three options**:

414 410

setup.md +5 −5

Details

5## System requirements5## System requirements

6 6

7* **Operating Systems**: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (with WSL 1, WSL 2, or Git for Windows)7* **Operating Systems**: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (with WSL 1, WSL 2, or Git for Windows)

~~8* **Hardware**: 4GB+ RAM~~8* **Hardware**: 4 GB+ RAM

~~9* **Software**: [Node.js 18+](https://nodejs.org/en/download) (only required for NPM installation)~~9* **Software**: [Node.js 18+](https://nodejs.org/en/download) (only required for npm installation)

10* **Network**: Internet connection required for authentication and AI processing10* **Network**: Internet connection required for authentication and AI processing

11* **Shell**: Works best in Bash, Zsh or Fish11* **Shell**: Works best in Bash, Zsh or Fish

12* **Location**: [Anthropic supported countries](https://www.anthropic.com/supported-countries)12* **Location**: [Anthropic supported countries](https://www.anthropic.com/supported-countries)

13 13

14### Additional dependencies14### Additional dependencies

15 15

~~16* **ripgrep**: Usually included with Claude Code. If search functionality fails, see [search troubleshooting](/en/troubleshooting#search-and-discovery-issues).~~16* **ripgrep**: Usually included with Claude Code. If search fails, see [search troubleshooting](/en/troubleshooting#search-and-discovery-issues).

17 17

18## Standard installation18## Standard installation

19 19

68 68

69Claude Code offers the following authentication options:69Claude Code offers the following authentication options:

70 70

711. **Claude Console**: The default option. Connect through the Claude Console and complete the OAuth process. Requires active billing at [console.anthropic.com](https://console.anthropic.com). A "Claude Code" workspace will be automatically created for usage tracking and cost management. Note that you cannot create API keys for the Claude Code workspace - it is dedicated exclusively for Claude Code usage.711. **Claude Console**: The default option. Connect through the Claude Console and complete the OAuth process. Requires active billing in the [Anthropic console](https://console.anthropic.com). A "Claude Code" workspace is automatically created for usage tracking and cost management. You can't create API keys for the Claude Code workspace; it's dedicated exclusively for Claude Code usage.

722. **Claude App (with Pro or Max plan)**: Subscribe to Claude's [Pro or Max plan](https://claude.com/pricing) for a unified subscription that includes both Claude Code and the web interface. Get more value at the same price point while managing your account in one place. Log in with your Claude.ai account. During launch, choose the option that matches your subscription type.722. **Claude App (with Pro or Max plan)**: Subscribe to Claude's [Pro or Max plan](https://claude.com/pricing) for a unified subscription that includes both Claude Code and the web interface. Get more value at the same price point while managing your account in one place. Log in with your Claude.ai account. During launch, choose the option that matches your subscription type.

733. **Enterprise platforms**: Configure Claude Code to use [Amazon Bedrock, Google Vertex AI, or Microsoft Foundry](/en/third-party-integrations) for enterprise deployments with your existing cloud infrastructure.733. **Enterprise platforms**: Configure Claude Code to use [Amazon Bedrock, Google Vertex AI, or Microsoft Foundry](/en/third-party-integrations) for enterprise deployments with your existing cloud infrastructure.

74 74

126```126```

127 127

128<Note>128<Note>

129 **Alpine Linux and other musl/uClibc-based distributions**: The native build requires you to install `libgcc`, `libstdc++`, and `ripgrep`. Install (Alpine: `apk add libgcc libstdc++ ripgrep`) and set `USE_BUILTIN_RIPGREP=0`.129 **Alpine Linux and other musl/uClibc-based distributions**: The native build requires `libgcc`, `libstdc++`, and `ripgrep`. For Alpine: `apk add libgcc libstdc++ ripgrep`. Set `USE_BUILTIN_RIPGREP=0`.

130</Note>130</Note>

131 131

132<Note>132<Note>

skills.md +2 −2

Details

146When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for:146When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for:

147 147

148* Read-only Skills that shouldn't modify files148* Read-only Skills that shouldn't modify files

149* Skills with limited scope (e.g., only data analysis, no file writing)149* Skills with limited scope: for example, only data analysis, no file writing

150* Security-sensitive workflows where you want to restrict capabilities150* Security-sensitive workflows where you want to restrict capabilities

151 151

152If `allowed-tools` is not specified, Claude will ask for permission to use tools as normal, following the standard permission model.152If `allowed-tools` isn't specified, Claude will ask for permission to use tools as normal, following the standard permission model.

153 153

154<Note>154<Note>

155 `allowed-tools` is only supported for Skills in Claude Code.155 `allowed-tools` is only supported for Skills in Claude Code.

slack.md +211 −0 created

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 +36 −34

Details

14| `/compact [instructions]` | Compact conversation with optional focus instructions |14| `/compact [instructions]` | Compact conversation with optional focus instructions |

15| `/config` | Open the Settings interface (Config tab) |15| `/config` | Open the Settings interface (Config tab) |

16| `/context` | Visualize current context usage as a colored grid |16| `/context` | Visualize current context usage as a colored grid |

~~17| `/cost` | Show token usage statistics (see [cost tracking guide](/en/costs#using-the-cost-command) for subscription-specific details) |~~17| `/cost` | Show token usage statistics. See [cost tracking guide](/en/costs#using-the-cost-command) for subscription-specific details. |

18| `/doctor` | Checks the health of your Claude Code installation |18| `/doctor` | Checks the health of your Claude Code installation |

19| `/exit` | Exit the REPL |19| `/exit` | Exit the REPL |

20| `/export [filename]` | Export the current conversation to a file or clipboard |20| `/export [filename]` | Export the current conversation to a file or clipboard |

21| `/help` | Get usage help |21| `/help` | Get usage help |

22| `/hooks` | Manage hook configurations for tool events |22| `/hooks` | Manage hook configurations for tool events |

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

42| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |42| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |

43| `/statusline` | Set up Claude Code's status line UI |43| `/statusline` | Set up Claude Code's status line UI |

44| `/terminal-setup` | Install Shift+Enter key binding for newlines (iTerm2 and VSCode only) |44| `/terminal-setup` | Install Shift+Enter key binding for newlines (iTerm2 and VSCode only) |

47| `/vim` | Enter vim mode for alternating insert and command modes |47| `/vim` | Enter vim mode for alternating insert and command modes |

48 48

49## Custom slash commands49## Custom slash commands

50 50

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

52 52

53### Syntax53### Syntax

54 54

71 71

72**Location**: `.claude/commands/`72**Location**: `.claude/commands/`

73 73

~~74In the following example, we create the `/optimize` command:~~74The following example creates the `/optimize` command:

75 75

76```bash theme={null}76```bash theme={null}

77# Create a project command77# Create a project command

85 85

86**Location**: `~/.claude/commands/`86**Location**: `~/.claude/commands/`

87 87

~~88In the following example, we create the `/security-review` command:~~88The following example creates the `/security-review` command:

89 89

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

91# Create a personal command91# Create a personal command

97 97

98#### Namespacing98#### Namespacing

99 99

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.100Use subdirectories to group related commands. Subdirectories appear in the command description but don't affect the command name.

101 101

102Conflicts between user and project level commands are not supported. Otherwise, multiple commands with the same base file name can coexist.102For example:

103

104* `.claude/commands/frontend/component.md` creates `/component` with description "(project:frontend)"

105* `~/.claude/commands/component.md` creates `/component` with description "(user)"

103 106

104For example, a file at `.claude/commands/frontend/component.md` creates the command `/component` with description showing "(project:frontend)".107If 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.

105Meanwhile, a file at `~/.claude/commands/component.md` creates the command `/component` with description showing "(user)".108

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

106 110

107#### Arguments111#### Arguments

108 112

310 314

311#### Naming conventions315#### Naming conventions

312 316

313* Server and prompt names are normalized317Server and prompt names are normalized:

318

314* Spaces and special characters become underscores319* Spaces and special characters become underscores

315* Names are lowercased for consistency320* Names are lowercase for consistency

316 321

317### Managing MCP connections322### Managing MCP connections

318 323

326 331

327### MCP permissions and wildcards332### MCP permissions and wildcards

328 333

329When configuring [permissions for MCP tools](/en/iam#tool-specific-permission-rules), note that **wildcards are not supported**:334Wildcards aren't supported in [permissions for MCP tools](/en/iam#tool-specific-permission-rules).

330 335

331* ✅ **Correct**: `mcp__github` (approves ALL tools from the github server)336To approve all tools from an MCP server, use the server name alone, without wildcards:

332* ✅ **Correct**: `mcp__github__get_issue` (approves specific tool)

333* ❌ **Incorrect**: `mcp__github__*` (wildcards not supported)

334 337

335To approve all tools from an MCP server, use just the server name: `mcp__servername`. To approve specific tools only, list each tool individually.338* `mcp__github` (approves all GitHub tools)

339

340To approve specific tools, list each one explicitly:

341

342* `mcp__github__get_issue`

343* `mcp__github__list_issues`

336 344

337## `SlashCommand` tool345## `SlashCommand` tool

338 346

340during a conversation. This gives Claude the ability to invoke custom commands348during a conversation. This gives Claude the ability to invoke custom commands

341on your behalf when appropriate.349on your behalf when appropriate.

342 350

343To encourage Claude to trigger `SlashCommand` tool, your instructions (prompts,351To encourage Claude to use the `SlashCommand` tool, reference the command by name, including the slash, in your prompts or `CLAUDE.md` file. For example:

344CLAUDE.md, etc.) generally need to reference the command by name with its slash.

~~345~~

346Example:

347 352

348```353```

349> Run /write-unit-test when you are about to start writing tests.354> Run /write-unit-test when you are about to start writing tests.

350```355```

351 356

352This tool puts each available custom slash command's metadata into context up to the357This tool puts each available custom slash command's metadata into context up to the character budget limit. You can use `/context` to monitor token usage and follow the operations below to manage context.

353character budget limit. You can use `/context` to monitor token usage and follow

354the operations below to manage context.

355 358

356### `SlashCommand` tool supported commands359### `SlashCommand` tool supported commands

357 360

358`SlashCommand` tool only supports custom slash commands that:361`SlashCommand` tool only supports custom slash commands that:

359 362

360* Are user-defined. Built-in commands like `/compact` and `/init` are *not* supported.363* Are user-defined. Built-in commands like `/compact` and `/init` are *not* supported.

361* Have the `description` frontmatter field populated. We use the `description` in the context.364* Have the `description` frontmatter field populated. The description is used in the context.

362 365

363For Claude Code versions >= 1.0.124, you can see which custom slash commands366For Claude Code versions >= 1.0.124, you can see which custom slash commands

364`SlashCommand` tool can invoke by running `claude --debug` and triggering a query.367`SlashCommand` tool can invoke by running `claude --debug` and triggering a query.

372# Add to deny rules: SlashCommand375# Add to deny rules: SlashCommand

373```376```

374 377

375This will also remove SlashCommand tool (and the slash command descriptions) from context.378This also removes the SlashCommand tool and command descriptions from context.

376 379

377### Disable specific commands only380### Disable specific commands only

378 381

379To prevent a specific slash command from becoming available, add382To prevent a specific slash command from becoming available, add

380`disable-model-invocation: true` to the slash command's frontmatter.383`disable-model-invocation: true` to the slash command's frontmatter.

381 384

382This will also remove the command's metadata from context.385This also removes the command's metadata from context.

383 386

384### `SlashCommand` permission rules387### `SlashCommand` permission rules

385 388

394descriptions shown to Claude. This prevents token overflow when many commands397descriptions shown to Claude. This prevents token overflow when many commands

395are available.398are available.

396 399

397The budget includes each custom slash command's name, args, and description.400The budget includes each custom slash command's name, arguments, and description.

398 401

399* **Default limit**: 15,000 characters402* **Default limit**: 15,000 characters

400* **Custom limit**: Set via `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable403* **Custom limit**: Set via `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable

401 404

402When the character budget is exceeded, Claude will see only a subset of the405When the character budget is exceeded, Claude sees only a subset of the available commands. In `/context`, a warning shows "M of N commands".

403available commands. In `/context`, a warning will show with "M of N commands".

404 406

405## Skills vs slash commands407## Skills vs slash commands

406 408

408 410

409### Use slash commands for411### Use slash commands for

410 412

411**Quick, frequently-used prompts**:413**Quick, frequently used prompts**:

412 414

413* Simple prompt snippets you use often415* Simple prompt snippets you use often

414* Quick reminders or templates416* Quick reminders or templates

415* Frequently-used instructions that fit in one file417* Frequently used instructions that fit in one file

416 418

417**Examples**:419**Examples**:

418 420

statusline.md +1 −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

sub-agents.md +12 −12

Details

27 </Card>27 </Card>

28 28

29 <Card title="Reusability" icon="rotate">29 <Card title="Reusability" icon="rotate">

~~30 Once created, subagents can be used across different projects and shared with your team for consistent workflows.~~30 Once created, you can use subagents across different projects and share them with your team for consistent workflows.

31 </Card>31 </Card>

32 32

33 <Card title="Flexible permissions" icon="shield-check">33 <Card title="Flexible permissions" icon="shield-check">

53 </Step>53 </Step>

54 54

55 <Step title="Define the subagent">55 <Step title="Define the subagent">

~~56 * **Recommended**: Generate with Claude first, then customize to make it yours~~56 * **Recommended**: generate with Claude first, then customize to make it yours

~~57 * Describe your subagent in detail and when it should be used~~57 * Describe your subagent in detail, including when Claude should use it

~~58 * Select the tools you want to grant access to (or leave blank to inherit all tools)~~58 * Select the tools you want to grant access to, or leave this blank to inherit all tools

~~59 * The interface shows all available tools, making selection easy~~59 * The interface shows all available tools

60 * If you're generating with Claude, you can also edit the system prompt in your own editor by pressing `e`60 * If you're generating with Claude, you can also edit the system prompt in your own editor by pressing `e`

61 </Step>61 </Step>

62 62

63 <Step title="Save and use">63 <Step title="Save and use">

~~64 Your subagent is now available! Claude will use it automatically when appropriate, or you can invoke it explicitly:~~64 Your subagent is now available. Claude uses it automatically when appropriate, or you can invoke it explicitly:

65 65

66 ```66 ```

67 > Use the code-reviewer subagent to check my recent changes67 > Use the code-reviewer subagent to check my recent changes

86 86

87[Plugins](/en/plugins) can provide custom subagents that integrate seamlessly with Claude Code. Plugin agents work identically to user-defined agents and appear in the `/agents` interface.87[Plugins](/en/plugins) can provide custom subagents that integrate seamlessly with Claude Code. Plugin agents work identically to user-defined agents and appear in the `/agents` interface.

88 88

~~89**Plugin agent locations**: Plugins include agents in their `agents/` directory (or custom paths specified in the plugin manifest).~~89**Plugin agent locations**: plugins include agents in their `agents/` directory (or custom paths specified in the plugin manifest).

90 90

91**Using plugin agents**:91**Using plugin agents**:

92 92

200* Edit existing custom subagents, including their tool access200* Edit existing custom subagents, including their tool access

201* Delete custom subagents201* Delete custom subagents

202* See which subagents are active when duplicates exist202* See which subagents are active when duplicates exist

203* **Easily manage tool permissions** with a complete list of available tools203* **Manage tool permissions** with a complete list of available tools

204 204

205### Direct file management205### Direct file management

206 206

324* **Mode**: Strictly read-only - cannot create, modify, or delete files324* **Mode**: Strictly read-only - cannot create, modify, or delete files

325* **Tools available**:325* **Tools available**:

326 * Glob - File pattern matching326 * Glob - File pattern matching

327 * Grep - Content searching with regex327 * Grep - Content searching with regular expressions

328 * Read - Reading file contents328 * Read - Reading file contents

329 * Bash - Read-only commands only (ls, git status, git log, git diff, find, cat, head, tail)329 * Bash - Read-only commands only (ls, git status, git log, git diff, find, cat, head, tail)

330 330

336 336

337When invoking the Explore subagent, Claude specifies a thoroughness level:337When invoking the Explore subagent, Claude specifies a thoroughness level:

338 338

339* **Quick** - Basic searches, fastest results. Good for simple lookups.339* **Quick** - Fast searches with minimal exploration. Good for targeted lookups.

340* **Medium** - Moderate exploration. Balances speed and thoroughness.340* **Medium** - Moderate exploration. Balances speed and thoroughness.

341* **Very thorough** - Comprehensive analysis across multiple locations and naming conventions. Used when the target might be in unexpected places.341* **Very thorough** - Comprehensive analysis across multiple locations and naming conventions. Used when the target might be in unexpected places.

342 342

3803. Begin review immediately3803. Begin review immediately

381 381

382Review checklist:382Review checklist:

383- Code is simple and readable383- Code is clear and readable

384- Functions and variables are well-named384- Functions and variables are well-named

385- No duplicated code385- No duplicated code

386- Proper error handling386- Proper error handling

429- Testing approach429- Testing approach

430- Prevention recommendations430- Prevention recommendations

431 431

432Focus on fixing the underlying issue, not just symptoms.432Focus on fixing the underlying issue, not the symptoms.

433```433```

434 434

435### Data scientist435### Data scientist

terminal-config.md +1 −1

Details

10 10

11### Line breaks11### Line breaks

12 12

~~13You have several options for entering linebreaks into Claude Code:~~13You have several options for entering line breaks into Claude Code:

14 14

15* **Quick escape**: Type `\` followed by Enter to create a newline15* **Quick escape**: Type `\` followed by Enter to create a newline

16* **Keyboard shortcut**: Set up a keybinding to insert a newline16* **Keyboard shortcut**: Set up a keybinding to insert a newline

third-party-integrations.md +1 −1

Details

248 248

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

250 250

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

252 252

253## Next steps253## Next steps

254 254

troubleshooting.md +16 −10

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

139| :---------------------------- | :--------------------------------------------------------------------- |139| :---------------------------- | :--------------------------------------------------------------------- |

147 147

148On Windows, `~` refers to your user home directory (e.g., `C:\Users\YourName`).148On Windows, `~` refers to your user home directory, such as `C:\Users\YourName`.

149 149

150**Enterprise managed file locations:**150**Enterprise managed file locations:**

151 151

274 274

275### Reporting Windows IDE integration issues (both native and WSL)275### Reporting Windows IDE integration issues (both native and WSL)

276 276

277If 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)277If you're experiencing IDE integration problems on Windows, [create an issue](https://github.com/anthropics/claude-code/issues) with the following information:

278 278

279### ESC key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals279* Environment type: native Windows (Git Bash) or WSL1/WSL2

280* WSL networking mode (if applicable): NAT or mirrored

281* IDE name and version

282* Claude Code extension/plugin version

283* Shell type: Bash, Zsh, PowerShell, etc.

280 284

281If 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.285### Escape key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals

286

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

282 288

283To fix this issue:289To fix this issue:

284 290

288 * Click "Configure terminal keybindings" and delete the "Switch focus to Editor" shortcut294 * Click "Configure terminal keybindings" and delete the "Switch focus to Editor" shortcut

2893. Apply the changes2953. Apply the changes

290 296

291This allows the ESC key to properly interrupt Claude Code operations.297This allows the `Esc` key to properly interrupt Claude Code operations.

292 298

293## Markdown formatting issues299## Markdown formatting issues

294 300

318 324

319**Solutions:**325**Solutions:**

320 326

3211. **Ask Claude to add language tags**: Simply request "Please add appropriate language tags to all code blocks in this markdown file."3271. **Ask Claude to add language tags**: Request "Add appropriate language tags to all code blocks in this markdown file."

322 328

3232. **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.3292. **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.

324 330

341To minimize formatting issues:347To minimize formatting issues:

342 348

343* **Be explicit in requests**: Ask for "properly formatted markdown with language-tagged code blocks"349* **Be explicit in requests**: Ask for "properly formatted markdown with language-tagged code blocks"

344* **Use project conventions**: Document your preferred markdown style in [CLAUDE.md](/en/memory)350* **Use project conventions**: Document your preferred markdown style in [`CLAUDE.md`](/en/memory)

345* **Set up validation hooks**: Use post-processing hooks to automatically verify and fix common formatting issues351* **Set up validation hooks**: Use post-processing hooks to automatically verify and fix common formatting issues

346 352

347## Getting more help353## Getting more help

vs-code.md +19 −19

Details

1# Visual Studio Code1# Visual Studio Code

2 2

~~3> Use Claude Code with Visual Studio Code through our native extension or CLI integration~~3> Use Claude Code with Visual Studio Code through the native extension or CLI integration

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="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" />

6 6

18* **Extended thinking**: Toggle extended thinking on/off using the Extended Thinking button in the bottom-right corner of the prompt input18* **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 picker19* **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 CLI20* **MCP server usage**: Use Model Context Protocol servers configured through the CLI

~~21* **Conversation history**: Easy access to past conversations~~21* **Conversation history**: Access to past conversations

22* **Multiple sessions**: Run multiple Claude Code sessions simultaneously22* **Multiple sessions**: Run multiple Claude Code sessions simultaneously

23* **Keyboard shortcuts**: Support for most shortcuts from the CLI23* **Keyboard shortcuts**: Support for most shortcuts from the CLI

24* **Slash commands**: Access most CLI slash commands directly in the extension24* **Slash commands**: Access most CLI slash commands directly in the extension

31 31

32Download and install the extension from the [Visual Studio Code Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code).32Download and install the extension from the [Visual Studio Code Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code).

33 33

~~34### How It Works~~34### How it works

35 35

36Once installed, you can start using Claude Code through the VS Code interface:36Once installed, you can start using Claude Code through the VS Code interface:

37 37

392. Prompt Claude Code in the same way you would in the terminal392. Prompt Claude Code in the same way you would in the terminal

403. Watch as Claude analyzes your code and suggests changes403. Watch as Claude analyzes your code and suggests changes

414. Review and accept edits directly in the interface414. Review and accept edits directly in the interface

~~42 * **Tip**: Drag the sidebar wider to see inline diffs, then click on them to expand for full details~~42 * **Tip**: Drag the sidebar wider to see inline diffs, then click them to expand for full details

43 43

44### Configuration44### Configuration

45 45

46The VS Code extension reads the same `settings.json` files as the CLI. See the [settings documentation](/en/settings) for details.46The VS Code extension reads the same `settings.json` files as the CLI. See the [settings documentation](/en/settings) for details.

47 47

~~48#### Third-Party Providers and Gateways~~48#### Third-party providers and gateways

49 49

50To use the VS Code extension with third-party providers (Amazon Bedrock, Google Vertex AI, Microsoft Foundry) or gateways that handle authentication:50To use the VS Code extension with third-party providers (Amazon Bedrock, Google Vertex AI, Microsoft Foundry) or gateways that handle authentication:

51 51

73* [Claude Code on Google Vertex AI](/en/google-vertex-ai)73* [Claude Code on Google Vertex AI](/en/google-vertex-ai)

74* [Claude Code on Microsoft Foundry](/en/microsoft-foundry)74* [Claude Code on Microsoft Foundry](/en/microsoft-foundry)

75 75

~~76### Not Yet Implemented~~76### Not yet implemented

77 77

~~78The following features are not yet available in the VS Code extension:~~78The following features aren't yet available in the VS Code extension:

79 79

80* **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.80* **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 work in the extension. You can also [configure MCP servers through the CLI](/en/mcp) first, then the extension will use them.

81* **Subagents configuration**: Configure [subagents through the CLI](/en/sub-agents) to use them in VS Code81* **Subagents configuration**: Configure [subagents through the CLI](/en/sub-agents) to use them in VS Code

82* **Checkpoints**: Save and restore conversation state at specific points82* **Checkpoints**: Save and restore conversation state at specific points

83* **Conversation rewinding**: The `/rewind` command is coming soon83* **Conversation rewinding**: The `/rewind` command is coming soon

87* **Tab completion**: File path completion with tab key87* **Tab completion**: File path completion with tab key

88* **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' field88* **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

89 89

~~90We are working on adding these features in future updates.~~90These features are planned for future updates.

91 91

~~92## Security Considerations~~92## Security considerations

93 93

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

95 95

99* Using manual approval mode for edits99* Using manual approval mode for edits

100* Taking extra care to ensure Claude is only used with trusted prompts100* Taking extra care to ensure Claude is only used with trusted prompts

101 101

102## Legacy CLI Integration102## Legacy CLI integration

103 103

104The 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).104The original VS Code integration 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).

105 105

106The 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.106The legacy integration auto-installs when you run `claude` from VS Code's integrated terminal. 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.

107 107

108Both the extension and CLI integration work with Visual Studio Code, Cursor, Windsurf, and VSCodium.108Both the extension and CLI integration work with Visual Studio Code, Cursor, Windsurf, and VSCodium.

109 109

110## Troubleshooting110## Troubleshooting

111 111

112### Extension Not Installing112### Extension not installing

113 113

114* Ensure you have a compatible version of VS Code (1.85.0 or later)114* Ensure you have a compatible version of VS Code (1.85.0 or later)

115* Check that VS Code has permission to install extensions115* Check that VS Code has permission to install extensions

116* Try installing directly from the Marketplace website116* Try installing directly from the Marketplace website

117 117

118### Claude Code Never Responds118### Claude Code never responds

119 119

120If Claude Code is not responding to your prompts:120If Claude Code isn't responding to your prompts:

121 121

1221. **Check your internet connection**: Ensure you have a stable internet connection1221. **Check your internet connection**: Ensure you have a stable internet connection

1232. **Start a new conversation**: Try starting a fresh conversation to see if the issue persists1232. **Start a new conversation**: Try starting a fresh conversation to see if the issue persists

1243. **Try the CLI**: Run `claude` from the terminal to see if you get more detailed error messages1243. **Try the CLI**: Run `claude` from the terminal to see if you get more detailed error messages

1254. **File a bug report**: If the problem continues, [file an issue on GitHub](https://github.com/anthropics/claude-code/issues) with details about the error1254. **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

126 126

127### Legacy Integration Not Working127### Legacy integration not working

128 128

129* Ensure you're running Claude Code from VS Code's integrated terminal129* Ensure you're running Claude Code from VS Code's integrated terminal

130* Ensure the CLI for your IDE variant is installed:130* Ensure the CLI for your IDE variant is installed:

134 * VSCodium: `codium` command should be available134 * VSCodium: `codium` command should be available

135* If the command isn't installed:135* If the command isn't installed:

136 1. Open command palette with `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)136 1. Open command palette with `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)

137 2. Search for "Shell Command: Install 'code' command in PATH" (or equivalent for your IDE)137 2. Search for `Shell Command: Install 'code' command in PATH` (or equivalent for your IDE)

138 138

139For additional help, see our [troubleshooting guide](/en/troubleshooting).139For additional help, see the [troubleshooting guide](/en/troubleshooting).

140 140

141 141

142---142---

Documentation 2025-12-06 18:02 UTC to 2025-12-08 21:01 UTC