Anthropic - Claude Code Docs Changes 2025-11-17 03:24 UTC → 2025-12-18 15:02 UTC

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 Bedrock10* Access to desired Claude models (for example, Claude Sonnet 4.5) in Bedrock

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

12* Appropriate IAM permissions12* Appropriate IAM permissions

13 13 

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

49```49```

50 50 

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

52 

53```bash theme={null}

54aws login

55```

56 

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

58 

59**Option E: Bedrock API keys**

52 60 

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

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

75 83 

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

77 85 

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

79 87 

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

81 89 

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

83{91{

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

103```111```

104 112 

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

106 

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

108 114 

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

120| Small/fast model | `us.anthropic.claude-haiku-4-5-20251001-v1:0` |126| Small/fast model | `us.anthropic.claude-haiku-4-5-20251001-v1:0` |

121 127 

122<Note>128<Note>

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

124</Note>130</Note>

125 131 

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

137export DISABLE_PROMPT_CACHING=1143export DISABLE_PROMPT_CACHING=1

138```144```

139 145 

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

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

142</Note>

143 147 

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

145 149 

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

147 151 

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

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

153 157 

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

155 159 

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

157 161 

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

159 163 

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

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

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

232 

233 

234---

235 

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

85 85 

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

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

88 

89 

90---

91 

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

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

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

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

66 

67 

68---

69 

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

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

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

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

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

485 

486 

487---

488 

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

5## CLI commands5## CLI commands

6 6 

7| Command | Description | Example |7| Command | Description | Example |

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

9| `claude` | Start interactive REPL | `claude` |9| `claude` | Start interactive REPL | `claude` |

10| `claude "query"` | Start REPL with initial prompt | `claude "explain this project"` |10| `claude "query"` | Start REPL with initial prompt | `claude "explain this project"` |

11| `claude -p "query"` | Query via SDK, then exit | `claude -p "explain this function"` |11| `claude -p "query"` | Query via SDK, then exit | `claude -p "explain this function"` |

12| `cat file \| claude -p "query"` | Process piped content | `cat logs.txt \| claude -p "explain"` |12| `cat file \| claude -p "query"` | Process piped content | `cat logs.txt \| claude -p "explain"` |

13| `claude -c` | Continue most recent conversation | `claude -c` |13| `claude -c` | Continue most recent conversation | `claude -c` |

14| `claude -c -p "query"` | Continue via SDK | `claude -c -p "Check for type errors"` |14| `claude -c -p "query"` | Continue via SDK | `claude -c -p "Check for type errors"` |

15| `claude -r "<session-id>" "query"` | Resume session by ID | `claude -r "abc123" "Finish this PR"` |15| `claude -r "<session>" "query"` | Resume session by ID or name | `claude -r "auth-refactor" "Finish this PR"` |

16| `claude update` | Update to latest version | `claude update` |16| `claude update` | Update to latest version | `claude update` |

17| `claude mcp` | Configure Model Context Protocol (MCP) servers | See the [Claude Code MCP documentation](/en/mcp). |17| `claude mcp` | Configure Model Context Protocol (MCP) servers | See the [Claude Code MCP documentation](/en/mcp). |

18 18 

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

22 22 

23| Flag | Description | Example |23| Flag | Description | Example |

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

25| `--add-dir` | Add additional working directories for Claude to access (validates each path exists as a directory) | `claude --add-dir ../apps ../lib` |25| `--add-dir` | Add additional working directories for Claude to access (validates each path exists as a directory) | `claude --add-dir ../apps ../lib` |

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

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

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

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

29| `--print`, `-p` | Print response without interactive mode (see [SDK documentation](https://docs.claude.com/en/docs/agent-sdk) for programmatic usage details) | `claude -p "query"` |30| `--betas` | Beta headers to include in API requests (API key users only) | `claude --betas interleaved-thinking` |

30| `--system-prompt` | Replace the entire system prompt with custom text (works in both interactive and print modes; added in v2.0.14) | `claude --system-prompt "You are a Python expert"` |31| `--continue`, `-c` | Load the most recent conversation in the current directory | `claude --continue` |

31| `--system-prompt-file` | Load system prompt from a file, replacing the default prompt (print mode only; added in v1.0.54) | `claude -p --system-prompt-file ./custom-prompt.txt "query"` |32| `--dangerously-skip-permissions` | Skip permission prompts (use with caution) | `claude --dangerously-skip-permissions` |

32| `--append-system-prompt` | Append custom text to the end of the default system prompt (works in both interactive and print modes; added in v1.0.55) | `claude --append-system-prompt "Always use TypeScript"` |33| `--debug` | Enable debug mode with optional category filtering (for example, `"api,hooks"` or `"!statsig,!file"`) | `claude --debug "api,mcp"` |

33| `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |34| `--disallowedTools` | Tools that are removed from the model's context and cannot be used | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |

34| `--input-format` | Specify input format for print mode (options: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` |35| `--fallback-model` | Enable automatic fallback to specified model when default model is overloaded (print mode only) | `claude -p --fallback-model sonnet "query"` |

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

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

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

36| `--verbose` | Enable verbose logging, shows full turn-by-turn output (helpful for debugging in both print and interactive modes) | `claude --verbose` |39| `--input-format` | Specify input format for print mode (options: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` |

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

37| `--max-turns` | Limit the number of agentic turns in non-interactive mode | `claude -p --max-turns 3 "query"` |41| `--max-turns` | Limit the number of agentic turns in non-interactive mode | `claude -p --max-turns 3 "query"` |

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

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

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

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

40| `--permission-prompt-tool` | Specify an MCP tool to handle permission prompts in non-interactive mode | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |46| `--permission-prompt-tool` | Specify an MCP tool to handle permission prompts in non-interactive mode | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

41| `--resume` | Resume a specific session by ID, or by choosing in interactive mode | `claude --resume abc123 "query"` |47| `--plugin-dir` | Load plugins from directories for this session only (repeatable) | `claude --plugin-dir ./my-plugins` |

42| `--continue` | Load the most recent conversation in the current directory | `claude --continue` |48| `--print`, `-p` | Print response without interactive mode (see [SDK documentation](https://docs.claude.com/en/docs/agent-sdk) for programmatic usage details) | `claude -p "query"` |

43| `--dangerously-skip-permissions` | Skip permission prompts (use with caution) | `claude --dangerously-skip-permissions` |49| `--resume`, `-r` | Resume a specific session by ID or name, or show an interactive picker to choose a session | `claude --resume auth-refactor` |

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

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

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

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

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

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

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

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

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

44 59 

45<Tip>60<Tip>

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

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

53 68 

54| Field | Required | Description |69| Field | Required | Description |

55| :------------ | :------- | :-------------------------------------------------------------------------------------------------------------- |70| :------------ | :------- | :--------------------------------------------------------------------------------------------------------------------- |

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

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

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

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

60 75 

61Example:76Example:

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

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

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

142 

143 

144---

145 

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

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

505 501 

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

503 

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

507 505 

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

509 507 

510<Note>508<Note>

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

512</Note>510</Note>

513 511 

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

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

516 ```

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

518 ```

519 513 

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

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

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

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

523 518 

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

525 ```

526 > think about potential security vulnerabilities in this approach

527 ```

528 520 

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

530 > think hard about edge cases we should handle

531 ```

532 </Step>

533</Steps>

534 522 

535<Tip>523```

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

525```

537 526 

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

539 528 

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

541 * Debugging intricate issues

542 * Creating implementation plans for new features

543 * Understanding complex codebases

544 * Evaluating tradeoffs between different approaches

545 530 

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

547 532 

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

549 534 

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

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

552 536 

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

554</Tip>

555 538 

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

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

558 response.541A larger thinking token budget provides:

559</Note>542 

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

544* Room to analyze edge cases and evaluate tradeoffs thoroughly

545* Ability to revise reasoning and self-correct mistakes

546 

547Token budgets for thinking mode:

548 

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

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

551 

552**Custom token budgets:**

553 

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

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

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

557 

558<Warning>

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

560</Warning>

560 561 

561***562***

562 563 

563## Resume previous conversations564## Resume previous conversations

564 565 

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

567 

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

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

566 570 

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

568 572 

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

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

575### Name your sessions

576 

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

571 578 

572<Steps>579<Steps>

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

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

575 claude --continue582 

583 ```

584 > /rename auth-refactor

576 ```585 ```

577 586 

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

579 </Step>588 </Step>

580 589 

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

591 From the command line:

592 

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

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

584 ```595 ```

585 596 

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

587 </Step>

588 598 

589 <Step title="Show conversation picker">

590 ```bash theme={null}

591 claude --resume

592 ```599 ```

600 > /resume auth-refactor

601 ```

602 </Step>

603</Steps>

593 604 

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

595 606 

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

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

598 608 

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

600 </Step>610 

601</Steps>611| Shortcut | Action |

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

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

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

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

616| `P` | Preview the session content |

617| `R` | Rename the highlighted session |

618| `/` | Search to filter sessions |

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

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

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

622 

623**Session organization:**

624 

625The picker displays sessions with helpful metadata:

626 

627* Session name or initial prompt

628* Time elapsed since last activity

629* Message count

630* Git branch (if applicable)

631 

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

602 633 

603<Tip>634<Tip>

604 Tips:635 Tips:

605 636 

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

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

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

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

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

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

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

611 644 

612 How it works:645 How it works:

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

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

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

618 

619 Examples:

620 

621 ```bash theme={null}

622 # Continue most recent conversation

623 claude --continue

624 

625 # Continue most recent conversation with a specific prompt

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

627 

628 # Show conversation picker

629 claude --resume

630 

631 # Continue most recent conversation in non-interactive mode

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

633 ```

634</Tip>651</Tip>

635 652 

636***653***

822<Tip>839<Tip>

823 Tips:840 Tips:

824 841 

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

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

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

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

829</Tip>846</Tip>

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

851 ```868 ```

852 869 

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

854 </Step>871 </Step>

855</Steps>872</Steps>

856 873 

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

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

949</Card>966</Card>

967 

968 

969---

970 

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

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

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

131</Note>131</Note>

132 

133 

134---

135 

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

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 

94| **Claude API (`/bug` reports)** | Default on.<br />`DISABLE_BUG_COMMAND=1` to disable. | Default off.<br />`CLAUDE_CODE_USE_VERTEX` must be 1. | Default off.<br />`CLAUDE_CODE_USE_BEDROCK` must be 1. |94| **Claude API (`/bug` reports)** | Default on.<br />`DISABLE_BUG_COMMAND=1` to disable. | Default off.<br />`CLAUDE_CODE_USE_VERTEX` must be 1. | Default off.<br />`CLAUDE_CODE_USE_BEDROCK` must be 1. |

95 95 

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

97 

98 

99---

100 

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

1# Claude Code on desktop

2 

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

4 

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

6 

7## Claude Code on desktop (Preview)

8 

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

10 

11## Features

12 

13Claude Code on desktop provides:

14 

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

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

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

18 

19## Installation

20 

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

22 

23<Note>

24 Local sessions are not available on Windows arm64 architectures.

25</Note>

26 

27## Using Git worktrees

28 

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

30 

31<Note>

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

33</Note>

34 

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

36 

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

38 

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

40 

41```

42.env

43.env.local

44.env.*

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

46```

47 

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

49 

50<Tip>

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

52</Tip>

53 

54### Launch Claude Code on the web

55 

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

57 

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

59 

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

61 

62## Bundled Claude Code version

63 

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

65 

66<Note>

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

68</Note>

69 

70### Enterprise configuration

71 

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

73 

74## Related resources

75 

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

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

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

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

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

81 

82 

83---

84 

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

8 8 

9<Warning>9<Warning>

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

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

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

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

14</Warning>14</Warning>

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

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

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

78 

79 

80---

81 

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

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

12</Note>12</Note>

13 13 

14<Info>

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

16</Info>

17 

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

15 19 

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

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

64 68 

65<Tip>69<Tip>

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

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

68</Tip>71</Tip>

69 72 

70## Upgrading from Beta73## Upgrading from Beta

186 with:189 with:

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

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

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

190```193```

191 194 

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

209 212 

210### Security considerations213### Security considerations

211 214 

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

213 216 

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

215 218 

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

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

222 225 

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

224 227 

225### Optimizing performance228### Optimizing performance

226 229 

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

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

635 638 

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

637 640 

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

639 642 

644Common arguments:647Common arguments:

645 648 

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

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

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

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

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

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

668 671 

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

673 

674 

675---

676 

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

379 379 

380### Security considerations380### Security considerations

381 381 

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

383 383 

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

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

460 460 

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

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

463 

464 

465---

466 

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

8 8 

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

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

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

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

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

14 14 

44 44 

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

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

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

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

49 49 

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

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

100 100 

101<Note>101<Note>

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

103</Note>103</Note>

104 104 

105To customize models:105To customize models:

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

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

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

160 

161 

162---

163 

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

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

22 22 

23| Flag | Description | Example |23| Flag | Description | Example |

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

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

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

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

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

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

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

31| `--allowedTools` | Space-separated list of allowed tools, or <br /><br /> string of comma-separated list of allowed tools | `claude --allowedTools mcp__slack mcp__filesystem`<br /><br />`claude --allowedTools "Bash(npm install),mcp__filesystem"` |31| `--allowedTools` | Tools that execute without prompting for permission (use `--tools` to restrict available tools) | `claude --allowedTools mcp__slack mcp__filesystem`<br /><br />`claude --allowedTools "Bash(npm install),mcp__filesystem"` |

32| `--disallowedTools` | Space-separated list of denied tools, or <br /><br /> string of comma-separated list of denied tools | `claude --disallowedTools mcp__splunk mcp__github`<br /><br />`claude --disallowedTools "Bash(git commit),mcp__github"` |32| `--disallowedTools` | Tools removed from the model's context (cannot be used) | `claude --disallowedTools mcp__splunk mcp__github`<br /><br />`claude --disallowedTools "Bash(git commit),mcp__github"` |

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

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

35 35 

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

202 202 

203* [CLI usage and controls](/en/cli-reference) - Complete CLI documentation203* [CLI usage and controls](/en/cli-reference) - Complete CLI documentation

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

205 

206 

207---

208 

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

38```38```

39 39 

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

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

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

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

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

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

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

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

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

214 215 

215### Example: Intelligent Stop hook216### Example: Intelligent Stop hook

216 217 

257| --------------------- | ----------------------- | ------------------------------ |258| --------------------- | ----------------------- | ------------------------------ |

258| **Execution** | Runs bash script | Queries LLM |259| **Execution** | Runs bash script | Queries LLM |

259| **Decision logic** | You implement in code | LLM evaluates context |260| **Decision logic** | You implement in code | LLM evaluates context |

260| **Setup complexity** | Requires script file | Just configure prompt |261| **Setup complexity** | Requires script file | Configure prompt |

261| **Context awareness** | Limited to script logic | Natural language understanding |262| **Context awareness** | Limited to script logic | Natural language understanding |

262| **Performance** | Fast (local execution) | Slower (API call) |263| **Performance** | Fast (local execution) | Slower (API call) |

263| **Use case** | Deterministic rules | Context-aware decisions |264| **Use case** | Deterministic rules | Context-aware decisions |

403 404 

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

405 406 

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

407 408 

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

409#!/bin/bash410#!/bin/bash

474 "tool_input": {475 "tool_input": {

475 "file_path": "/path/to/file.txt",476 "file_path": "/path/to/file.txt",

476 "content": "file content"477 "content": "file content"

477 }478 },

479 "tool_use_id": "toolu_01ABC123..."

478}480}

479```481```

480 482 

497 "tool_response": {499 "tool_response": {

498 "filePath": "/path/to/file.txt",500 "filePath": "/path/to/file.txt",

499 "success": true501 "success": true

500 }502 },

503 "tool_use_id": "toolu_01ABC123..."

501}504}

502```505```

503 506 

587 590 

588## Hook Output591## Hook Output

589 592 

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

591communicates whether to block and any feedback that should be shown to Claude594communicates whether to block and any feedback that should be shown to Claude

592and the user.595and the user.

593 596 

614#### Exit Code 2 Behavior617#### Exit Code 2 Behavior

615 618 

616| Hook Event | Behavior |619| Hook Event | Behavior |

617| ------------------ | ------------------------------------------------------------------ |620| ------------------- | ------------------------------------------------------------------ |

618| `PreToolUse` | Blocks the tool call, shows stderr to Claude |621| `PreToolUse` | Blocks the tool call, shows stderr to Claude |

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

619| `PostToolUse` | Shows stderr to Claude (tool already ran) |623| `PostToolUse` | Shows stderr to Claude (tool already ran) |

620| `Notification` | N/A, shows stderr to user only |624| `Notification` | N/A, shows stderr to user only |

621| `UserPromptSubmit` | Blocks prompt processing, erases prompt, shows stderr to user only |625| `UserPromptSubmit` | Blocks prompt processing, erases prompt, shows stderr to user only |

775```779```

776 780 

777<Note>781<Note>

778 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

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

780 block prompts or want more structured control.783 block prompts or want more structured control.

781</Note>784</Note>

782 785 

873<Note>876<Note>

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

875 878 

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

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

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

879 882 

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

1069* **Input**: JSON via stdin1072* **Input**: JSON via stdin

1070* **Output**:1073* **Output**:

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

1072 * Notification/SessionEnd: Logged to debug only (`--debug`)1075 * Notification/SessionEnd: Logged to debug only (`--debug`)

1073 * UserPromptSubmit/SessionStart: stdout added as context for Claude1076 * UserPromptSubmit/SessionStart: stdout added as context for Claude

1074 1077 

1123* Command being executed1126* Command being executed

1124* Success/failure status1127* Success/failure status

1125* Output or error messages1128* Output or error messages

1129 

1130 

1131---

1132 

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

40workflow:40workflow:

41 41 

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

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

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

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

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

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

92project.93project.

93 94 

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

95 96 

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

97 98 

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

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

332 documentation.333 documentation.

334 

335 

336---

337 

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

4 4 

5## Authentication methods5## Authentication methods

6 6 

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

8 8 

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

10* Amazon Bedrock10* Amazon Bedrock

11* Microsoft Foundry

11* Google Vertex AI12* Google Vertex AI

12 13 

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

29 30 

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

31 32 

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

33 34 

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

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

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

37 38 

166 167 

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

168 169 

169### Enterprise managed policy settings170### Enterprise managed settings

170 171 

171For enterprise deployments of Claude Code, we support enterprise managed policy settings that take precedence over user and project settings. This allows system administrators to enforce security policies that users cannot override.172For enterprise deployments of Claude Code, administrators can configure and distribute settings to their organization through the [Claude.ai admin console](https://claude.ai/admin-settings/claude-code). These settings are fetched automatically when users authenticate and cannot be overridden locally. This feature is available to Claude for Enterprise customers. If you don't see this option in your admin console, contact your Anthropic account team to have the feature enabled.

172 173 

173System administrators can deploy policies to:174For organizations that prefer file-based policy distribution, Claude Code also supports `managed-settings.json` files that can be deployed to [system directories](/en/settings#settings-files). These policy files follow the same format as regular settings files and cannot be overridden by user or project settings.

174 

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

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

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

178 

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

180 175 

181### Settings precedence176### Settings precedence

182 177 

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

184 179 

1851. Enterprise policies1801. Managed settings (via Claude.ai admin console)

1862. Command line arguments1812. File-based managed settings (`managed-settings.json`)

1873. Local project settings (`.claude/settings.local.json`)1823. Command line arguments

1884. Shared project settings (`.claude/settings.json`)1834. Local project settings (`.claude/settings.local.json`)

1895. User settings (`~/.claude/settings.json`)1845. Shared project settings (`.claude/settings.json`)

1856. User settings (`~/.claude/settings.json`)

190 186 

191This hierarchy ensures that organizational policies are always enforced while still allowing flexibility at the project and user levels where appropriate.187This hierarchy ensures that organizational policies are always enforced while still allowing flexibility at the project and user levels where appropriate.

192 188 

195Claude Code securely manages your authentication credentials:191Claude Code securely manages your authentication credentials:

196 192 

197* **Storage location**: On macOS, API keys, OAuth tokens, and other credentials are stored in the encrypted macOS Keychain.193* **Storage location**: On macOS, API keys, OAuth tokens, and other credentials are stored in the encrypted macOS Keychain.

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

199* **Custom credential scripts**: The [`apiKeyHelper`](/en/settings#available-settings) setting can be configured to run a shell script that returns an API key.195* **Custom credential scripts**: The [`apiKeyHelper`](/en/settings#available-settings) setting can be configured to run a shell script that returns an API key.

200* **Refresh intervals**: By default, `apiKeyHelper` is called after 5 minutes or on HTTP 401 response. Set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals.196* **Refresh intervals**: By default, `apiKeyHelper` is called after 5 minutes or on HTTP 401 response. Set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals.

197 

198 

199---

200 

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

5## Keyboard shortcuts5## Keyboard shortcuts

6 6 

7<Note>7<Note>

8 Keyboard shortcuts may vary by platform and terminal. Press `?` to see available shortcuts for your environment.8 Keyboard shortcuts may vary by platform and terminal. Press `?` to see available shortcuts for your environment. For example, Option key combinations on macOS may require configuring your terminal to use Option as a meta/escape key.

9</Note>9</Note>

10 10 

11### General controls11### General controls

12 12 

13| Shortcut | Description | Context |13| Shortcut | Description | Context |

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

15| `Ctrl+C` | Cancel current input or generation | Standard interrupt |15| `Ctrl+C` | Cancel current input or generation | Standard interrupt |

16| `Ctrl+D` | Exit Claude Code session | EOF signal |16| `Ctrl+D` | Exit Claude Code session | EOF signal |

17| `Ctrl+L` | Clear terminal screen | Keeps conversation history |17| `Ctrl+L` | Clear terminal screen | Keeps conversation history |

20| `Ctrl+V` (macOS/Linux) or `Alt+V` (Windows) | Paste image from clipboard | Pastes an image or path to an image file |20| `Ctrl+V` (macOS/Linux) or `Alt+V` (Windows) | Paste image from clipboard | Pastes an image or path to an image file |

21| `Up/Down arrows` | Navigate command history | Recall previous inputs |21| `Up/Down arrows` | Navigate command history | Recall previous inputs |

22| `Esc` + `Esc` | Rewind the code/conversation | Restore the code and/or conversation to a previous point |22| `Esc` + `Esc` | Rewind the code/conversation | Restore the code and/or conversation to a previous point |

23| `Tab` | Toggle [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) | Switch between Thinking on and Thinking off |

24| `Shift+Tab` or `Alt+M` (some configurations) | Toggle permission modes | Switch between Auto-Accept Mode, Plan Mode, and normal mode |23| `Shift+Tab` or `Alt+M` (some configurations) | Toggle permission modes | Switch between Auto-Accept Mode, Plan Mode, and normal mode |

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

25 25 

26### Multiline input26### Multiline input

27 27 

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

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

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

170 

171 

172---

173 

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

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

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

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

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

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

25 25 

26## Installation26## Installation

29 29 

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

31 31 

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

33 

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

35 33 

36<Note>34<Note>

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

38</Note>36</Note>

39 37 

40## Usage38## Usage

70 68 

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

72 70 

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

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

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

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

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

149 147 

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

149 

150 

151---

152 

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

34***34***

35 35 

36© Anthropic PBC. All rights reserved. Use is subject to applicable Anthropic Terms of Service.36© Anthropic PBC. All rights reserved. Use is subject to applicable Anthropic Terms of Service.

37 

38 

39---

40 

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

29 29 

30Failure to forward headers or preserve body fields may result in reduced functionality or inability to use Claude Code features.30Failure to forward headers or preserve body fields may result in reduced functionality or inability to use Claude Code features.

31 31 

32<Note>

33 Claude Code determines which features to enable based on the API format. When using the Anthropic Messages format with Bedrock or Vertex, you may need to set environment variable `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`.

34</Note>

35 

32## Configuration36## Configuration

33 37 

34### Model selection38### Model selection

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

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

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

171 

172 

173---

174 

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

3> Learn how to connect Claude Code to your tools with the Model Context Protocol.3> Learn how to connect Claude Code to your tools with the Model Context Protocol.

4 4 

5 5 

6Claude Code can connect to hundreds of external tools and data sources through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open-source standard for AI-tool integrations. MCP servers give Claude Code access to your tools, databases, and APIs.6Claude Code can connect to hundreds of external tools and data sources through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open source standard for AI-tool integrations. MCP servers give Claude Code access to your tools, databases, and APIs.

7 7 

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

9 9 

11 11 

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

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

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

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

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

17 17 

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

122 * `project`: Shared with everyone in the project via `.mcp.json` file122 * `project`: Shared with everyone in the project via `.mcp.json` file

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

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

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

126 * Claude Code will display a warning when MCP tool output exceeds 10,000 tokens. To increase this limit, set the `MAX_MCP_OUTPUT_TOKENS` environment variable (e.g., `MAX_MCP_OUTPUT_TOKENS=50000`)126 * Claude Code will display a warning when MCP tool output exceeds 10,000 tokens. To increase this limit, set the `MAX_MCP_OUTPUT_TOKENS` environment variable (for example, `MAX_MCP_OUTPUT_TOKENS=50000`)

127 * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication127 * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication

128</Tip>128</Tip>

129 129 

209 209 

210### Local scope210### Local scope

211 211 

212Local-scoped servers represent the default configuration level and are stored in your project-specific user settings. These servers remain private to you and are only accessible when working within the current project directory. This scope is ideal for personal development servers, experimental configurations, or servers containing sensitive credentials that shouldn't be shared.212Local-scoped servers represent the default configuration level and are stored in `~/.claude.json` under your project's path. These servers remain private to you and are only accessible when working within the current project directory. This scope is ideal for personal development servers, experimental configurations, or servers containing sensitive credentials that shouldn't be shared.

213 213 

214```bash theme={null}214```bash theme={null}

215# Add a local-scoped server (default)215# Add a local-scoped server (default)

246 246 

247### User scope247### User scope

248 248 

249User-scoped servers provide cross-project accessibility, making them available across all projects on your machine while remaining private to your user account. This scope works well for personal utility servers, development tools, or services you frequently use across different projects.249User-scoped servers are stored in `~/.claude.json` and provide cross-project accessibility, making them available across all projects on your machine while remaining private to your user account. This scope works well for personal utility servers, development tools, or services you frequently use across different projects.

250 250 

251```bash theme={null}251```bash theme={null}

252# Add a user server252# Add a user server

259 259 

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

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

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

263 

264<Note>

265 **Where are MCP servers stored?**

266 

267 * **User and local scope**: `~/.claude.json` (in the `mcpServers` field or under project paths)

268 * **Project scope**: `.mcp.json` in your project root (checked into source control)

269 * **Enterprise managed**: `managed-mcp.json` in system directories (see [Enterprise MCP configuration](#enterprise-mcp-configuration))

270</Note>

263 271 

264### Scope hierarchy and precedence272### Scope hierarchy and precedence

265 273 

455 * It reads the Claude Desktop configuration file from its standard location on those platforms463 * It reads the Claude Desktop configuration file from its standard location on those platforms

456 * Use the `--scope user` flag to add servers to your user configuration464 * Use the `--scope user` flag to add servers to your user configuration

457 * Imported servers will have the same names as in Claude Desktop465 * Imported servers will have the same names as in Claude Desktop

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

459</Tip>467</Tip>

460 468 

461## Use Claude Code as an MCP server469## Use Claude Code as an MCP server

514 522 

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

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

517 * Note that this MCP server is simply exposing Claude Code's tools to your MCP client, so your own client is responsible for implementing user confirmation for individual tool calls.525 * Note that this MCP server is only exposing Claude Code's tools to your MCP client, so your own client is responsible for implementing user confirmation for individual tool calls.

518</Tip>526</Tip>

519 527 

520## MCP output limits and warnings528## MCP output limits and warnings

633 641 

634### Setting up enterprise MCP configuration642### Setting up enterprise MCP configuration

635 643 

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

637 645 

638* **macOS**: `/Library/Application Support/ClaudeCode/managed-mcp.json`646* macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`

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

640* **Linux**: `/etc/claude-code/managed-mcp.json`648* Windows: `C:\Program Files\ClaudeCode\managed-mcp.json`

649 

650<Note>

651 These are system-wide paths (not user home directories like `~/Library/...`) that require administrator privileges. They are designed to be deployed by IT administrators.

652</Note>

641 653 

642The `managed-mcp.json` file uses the same format as a standard `.mcp.json` file:654The `managed-mcp.json` file uses the same format as a standard `.mcp.json` file:

643 655 

666 678 

667### Restricting MCP servers with allowlists and denylists679### Restricting MCP servers with allowlists and denylists

668 680 

669In addition to providing enterprise-managed servers, administrators can control which MCP servers users are allowed to configure using `allowedMcpServers` and `deniedMcpServers` in the `managed-settings.json` file:681In addition to providing enterprise-managed servers, administrators can control which MCP servers users are allowed to configure using `allowedMcpServers` and `deniedMcpServers` in the [managed settings file](/en/settings#settings-files):

670 682 

671* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`683#### Restriction options

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

673* **Linux**: `/etc/claude-code/managed-settings.json`685Each entry in the allowlist or denylist can restrict servers in two ways:

686 

6871. **By server name** (`serverName`): Matches the configured name of the server

6882. **By command** (`serverCommand`): Matches the exact command and arguments used to start stdio servers

689 

690**Important**: Each entry must have **either** `serverName` **or** `serverCommand`, not both.

691 

692#### Example configuration

674 693 

675```json theme={null}694```json theme={null}

676{695{

677 "allowedMcpServers": [696 "allowedMcpServers": [