Anthropic - Claude Code Docs Changes 2026-02-11 21:10 UTC → 2026-02-27 00:08 UTC

36 36 

37Both agent teams and [subagents](/en/sub-agents) let you parallelize work, but they operate differently. Choose based on whether your workers need to communicate with each other:37Both agent teams and [subagents](/en/sub-agents) let you parallelize work, but they operate differently. Choose based on whether your workers need to communicate with each other:

38 38 

39<Frame caption="Subagents only report results back to the main agent and never talk to each other. In agent teams, teammates share a task list, claim work, and communicate directly with each other.">

40 <img src="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png?fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=2f8db9b4f3705dd3ab931fbe2d96e42a" className="dark:hidden" alt="Diagram comparing subagent and agent team architectures. Subagents are spawned by the main agent, do work, and report results back. Agent teams coordinate through a shared task list, with teammates communicating directly with each other." data-og-width="4245" width="4245" data-og-height="1615" height="1615" data-path="images/subagents-vs-agent-teams-light.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png?w=280&fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=a2cfe413c2084b477be40ac8723d9d40 280w, https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png?w=560&fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=c642c09a4c211b10b35eee7d7d0d149f 560w, https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png?w=840&fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=40d286f77c8a4075346b4fcaa2b36248 840w, https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png?w=1100&fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=923986caa23c0ef2c27d7e45f4dce6d1 1100w, https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png?w=1650&fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=17a730a070db6d71d029a98b074c68e8 1650w, https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png?w=2500&fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=e402533fc9e8b5e8d26a835cc4aa1742 2500w" />

41 

42 <img src="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-dark.png?fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=d573a037540f2ada6a9ae7d8285b46fd" className="hidden dark:block" alt="Diagram comparing subagent and agent team architectures. Subagents are spawned by the main agent, do work, and report results back. Agent teams coordinate through a shared task list, with teammates communicating directly with each other." data-og-width="4245" width="4245" data-og-height="1615" height="1615" data-path="images/subagents-vs-agent-teams-dark.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-dark.png?w=280&fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=06ca5b18b232855acc488357d8d01fa7 280w, https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-dark.png?w=560&fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=3d34daee83994781eb74b74d1ed511c4 560w, https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-dark.png?w=840&fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=82ea35ac837de7d674002de69689b9cf 840w, https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-dark.png?w=1100&fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=3653085214a9fc65d1f589044894a296 1100w, https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-dark.png?w=1650&fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=8e74b42694e428570e876d34f29e6ad6 1650w, https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-dark.png?w=2500&fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=3be00c56c6a0dcccbe15640020be0128 2500w" />

43</Frame>

44 

39| | Subagents | Agent teams |45| | Subagents | Agent teams |

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

41| **Context** | Own context window; results return to the caller | Own context window; fully independent |47| **Context** | Own context window; results return to the caller | Own context window; fully independent |

64 70 

65This example works well because the three roles are independent and can explore the problem without waiting on each other:71This example works well because the three roles are independent and can explore the problem without waiting on each other:

66 72 

67```73```text theme={null}

68I'm designing a CLI tool that helps developers track TODO comments across74I'm designing a CLI tool that helps developers track TODO comments across

69their codebase. Create an agent team to explore this from different angles: one75their codebase. Create an agent team to explore this from different angles: one

70teammate on UX, one on technical architecture, one playing devil's advocate.76teammate on UX, one on technical architecture, one playing devil's advocate.

72 78 

73From there, Claude creates a team with a [shared task list](/en/interactive-mode#task-list), spawns teammates for each perspective, has them explore the problem, synthesizes findings, and attempts to [clean up the team](#clean-up-the-team) when finished.79From there, Claude creates a team with a [shared task list](/en/interactive-mode#task-list), spawns teammates for each perspective, has them explore the problem, synthesizes findings, and attempts to [clean up the team](#clean-up-the-team) when finished.

74 80 

75The lead's terminal lists all teammates and what they're working on. Use Shift+Up/Down to select a teammate and message them directly.81The lead's terminal lists all teammates and what they're working on. Use Shift+Down to cycle through teammates and message them directly. After the last teammate, Shift+Down wraps back to the lead.

76 82 

77If you want each teammate in its own split pane, see [Choose a display mode](#choose-a-display-mode).83If you want each teammate in its own split pane, see [Choose a display mode](#choose-a-display-mode).

78 84 

84 90 

85Agent teams support two display modes:91Agent teams support two display modes:

86 92 

87* **In-process**: all teammates run inside your main terminal. Use Shift+Up/Down to select a teammate and type to message them directly. Works in any terminal, no extra setup required.93* **In-process**: all teammates run inside your main terminal. Use Shift+Down to cycle through teammates and type to message them directly. Works in any terminal, no extra setup required.

88* **Split panes**: each teammate gets its own pane. You can see everyone's output at once and click into a pane to interact directly. Requires tmux, or iTerm2.94* **Split panes**: each teammate gets its own pane. You can see everyone's output at once and click into a pane to interact directly. Requires tmux, or iTerm2.

89 95 

90<Note>96<Note>

114 120 

115Claude decides the number of teammates to spawn based on your task, or you can specify exactly what you want:121Claude decides the number of teammates to spawn based on your task, or you can specify exactly what you want:

116 122 

117```123```text theme={null}

118Create a team with 4 teammates to refactor these modules in parallel.124Create a team with 4 teammates to refactor these modules in parallel.

119Use Sonnet for each teammate.125Use Sonnet for each teammate.

120```126```

123 129 

124For complex or risky tasks, you can require teammates to plan before implementing. The teammate works in read-only plan mode until the lead approves their approach:130For complex or risky tasks, you can require teammates to plan before implementing. The teammate works in read-only plan mode until the lead approves their approach:

125 131 

126```132```text theme={null}

127Spawn an architect teammate to refactor the authentication module.133Spawn an architect teammate to refactor the authentication module.

128Require plan approval before they make any changes.134Require plan approval before they make any changes.

129```135```

132 138 

133The lead makes approval decisions autonomously. To influence the lead's judgment, give it criteria in your prompt, such as "only approve plans that include test coverage" or "reject plans that modify the database schema."139The lead makes approval decisions autonomously. To influence the lead's judgment, give it criteria in your prompt, such as "only approve plans that include test coverage" or "reject plans that modify the database schema."

134 140 

135### Use delegate mode

136 

137Without delegate mode, the lead sometimes starts implementing tasks itself instead of waiting for teammates. Delegate mode prevents this by restricting the lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks.

138 

139This is useful when you want the lead to focus entirely on orchestration, such as breaking down work, assigning tasks, and synthesizing results, without touching code directly.

140 

141To enable it, start a team first, then press Shift+Tab to cycle into delegate mode.

142 

143### Talk to teammates directly141### Talk to teammates directly

144 142 

145Each teammate is a full, independent Claude Code session. You can message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach.143Each teammate is a full, independent Claude Code session. You can message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach.

146 144 

147* **In-process mode**: use Shift+Up/Down to select a teammate, then type to send them a message. Press Enter to view a teammate's session, then Escape to interrupt their current turn. Press Ctrl+T to toggle the task list.145* **In-process mode**: use Shift+Down to cycle through teammates, then type to send them a message. Press Enter to view a teammate's session, then Escape to interrupt their current turn. Press Ctrl+T to toggle the task list.

148* **Split-pane mode**: click into a teammate's pane to interact with their session directly. Each teammate has a full view of their own terminal.146* **Split-pane mode**: click into a teammate's pane to interact with their session directly. Each teammate has a full view of their own terminal.

149 147 

150### Assign and claim tasks148### Assign and claim tasks

162 160 

163To gracefully end a teammate's session:161To gracefully end a teammate's session:

164 162 

165```163```text theme={null}

166Ask the researcher teammate to shut down164Ask the researcher teammate to shut down

167```165```

168 166 

172 170 

173When you're done, ask the lead to clean up:171When you're done, ask the lead to clean up:

174 172 

175```173```text theme={null}

176Clean up the team174Clean up the team

177```175```

178 176 

255 253 

256A single reviewer tends to gravitate toward one type of issue at a time. Splitting review criteria into independent domains means security, performance, and test coverage all get thorough attention simultaneously. The prompt assigns each teammate a distinct lens so they don't overlap:254A single reviewer tends to gravitate toward one type of issue at a time. Splitting review criteria into independent domains means security, performance, and test coverage all get thorough attention simultaneously. The prompt assigns each teammate a distinct lens so they don't overlap:

257 255 

258```256```text theme={null}

259Create an agent team to review PR #142. Spawn three reviewers:257Create an agent team to review PR #142. Spawn three reviewers:

260- One focused on security implications258- One focused on security implications

261- One checking performance impact259- One checking performance impact

269 267 

270When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. The prompt fights this by making teammates explicitly adversarial: each one's job is not only to investigate its own theory but to challenge the others'.268When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. The prompt fights this by making teammates explicitly adversarial: each one's job is not only to investigate its own theory but to challenge the others'.

271 269 

272```270```text theme={null}

273Users report the app exits after one message instead of staying connected.271Users report the app exits after one message instead of staying connected.

274Spawn 5 agent teammates to investigate different hypotheses. Have them talk to272Spawn 5 agent teammates to investigate different hypotheses. Have them talk to

275each other to try to disprove each other's theories, like a scientific273each other to try to disprove each other's theories, like a scientific

286 284 

287Teammates load project context automatically, including CLAUDE.md, MCP servers, and skills, but they don't inherit the lead's conversation history. See [Context and communication](#context-and-communication) for details. Include task-specific details in the spawn prompt:285Teammates load project context automatically, including CLAUDE.md, MCP servers, and skills, but they don't inherit the lead's conversation history. See [Context and communication](#context-and-communication) for details. Include task-specific details in the spawn prompt:

288 286 

289```287```text theme={null}

290Spawn a security reviewer teammate with the prompt: "Review the authentication module288Spawn a security reviewer teammate with the prompt: "Review the authentication module

291at src/auth/ for security vulnerabilities. Focus on token handling, session289at src/auth/ for security vulnerabilities. Focus on token handling, session

292management, and input validation. The app uses JWT tokens stored in290management, and input validation. The app uses JWT tokens stored in

293httpOnly cookies. Report any issues with severity ratings."291httpOnly cookies. Report any issues with severity ratings."

294```292```

295 293 

294### Choose an appropriate team size

295 

296There's no hard limit on the number of teammates, but practical constraints apply:

297 

298* **Token costs scale linearly**: each teammate has its own context window and consumes tokens independently. See [agent team token costs](/en/costs#agent-team-token-costs) for details.

299* **Coordination overhead increases**: more teammates means more communication, task coordination, and potential for conflicts

300* **Diminishing returns**: beyond a certain point, additional teammates don't speed up work proportionally

301 

302Start with 3-5 teammates for most workflows. This balances parallel work with manageable coordination. The examples in this guide use 3-5 teammates because that range works well across different task types.

303 

304Having 5-6 [tasks](/en/agent-teams#architecture) per teammate keeps everyone productive without excessive context switching. If you have 15 independent tasks, 3 teammates is a good starting point.

305 

306Scale up only when the work genuinely benefits from having teammates work simultaneously. Three focused teammates often outperform five scattered ones.

307 

296### Size tasks appropriately308### Size tasks appropriately

297 309 

298* **Too small**: coordination overhead exceeds the benefit310* **Too small**: coordination overhead exceeds the benefit

307 319 

308Sometimes the lead starts implementing tasks itself instead of waiting for teammates. If you notice this:320Sometimes the lead starts implementing tasks itself instead of waiting for teammates. If you notice this:

309 321 

310```322```text theme={null}

311Wait for your teammates to complete their tasks before proceeding323Wait for your teammates to complete their tasks before proceeding

312```324```

313 325 

343 355 

344### Teammates stopping on errors356### Teammates stopping on errors

345 357 

346Teammates may stop after encountering errors instead of recovering. Check their output using Shift+Up/Down in in-process mode or by clicking the pane in split mode, then either:358Teammates may stop after encountering errors instead of recovering. Check their output using Shift+Down in in-process mode or by clicking the pane in split mode, then either:

347 359 

348* Give them additional instructions directly360* Give them additional instructions directly

349* Spawn a replacement teammate to continue the work361* Spawn a replacement teammate to continue the work

11Before configuring Claude Code with Bedrock, ensure you have:11Before configuring Claude Code with Bedrock, ensure you have:

12 12 

13* An AWS account with Bedrock access enabled13* An AWS account with Bedrock access enabled

14* Access to desired Claude models (for example, Claude Sonnet 4.5) in Bedrock14* Access to desired Claude models (for example, Claude Sonnet 4.6) in Bedrock

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

16* Appropriate IAM permissions16* Appropriate IAM permissions

17 17 

18<Note>

19 If you are deploying Claude Code to multiple users, [pin your model versions](#4-pin-model-versions) to prevent breakage when Anthropic releases new models.

20</Note>

21 

18## Setup22## Setup

19 23 

20### 1. Submit use case details24### 1. Submit use case details

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

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

122 126 

123### 4. Model configuration127### 4. Pin model versions

128 

129<Warning>

130 Pin specific model versions for every deployment. If you use model aliases (`sonnet`, `opus`, `haiku`) without pinning, Claude Code may attempt to use a newer model version that isn't available in your Bedrock account, breaking existing users when Anthropic releases updates.

131</Warning>

132 

133Set these environment variables to specific Bedrock model IDs:

134 

135```bash theme={null}

136export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-6-v1'

137export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'

138export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

139```

140 

141These variables use cross-region inference profile IDs (with the `us.` prefix). If you use a different region prefix or application inference profiles, adjust accordingly. For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) for the full list of environment variables.

124 142 

125Claude Code uses these default models for Bedrock:143Claude Code uses these default models when no pinning variables are set:

126 144 

127| Model type | Default value |145| Model type | Default value |

128| :--------------- | :------------------------------------------------- |146| :--------------- | :-------------------------------------------- |

129| Primary model | `global.anthropic.claude-sonnet-4-5-20250929-v1:0` |147| Primary model | `global.anthropic.claude-sonnet-4-6` |

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

131 149 

132<Note>150To customize models further, use one of these methods:

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

134</Note>

135 

136To customize models, use one of these methods:

137 151 

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

139# Using inference profile ID153# Using inference profile ID

140export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-5-20250929-v1:0'154export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-6'

141export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'155export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

142 156 

143# Using application inference profile ARN157# Using application inference profile ARN

194For details, see [Bedrock IAM documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html).208For details, see [Bedrock IAM documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html).

195 209 

196<Note>210<Note>

197 We recommend creating a dedicated AWS account for Claude Code to simplify cost tracking and access control.211 Create a dedicated AWS account for Claude Code to simplify cost tracking and access control.

198</Note>212</Note>

199 213 

200## AWS Guardrails214## AWS Guardrails

4 4 

5# Authentication5# Authentication

6 6 

7> Learn how to configure user authentication and credential management for Claude Code in your organization.7> Log in to Claude Code and configure authentication for individuals, teams, and organizations.

8 8 

9## Authentication methods9Claude Code supports multiple authentication methods depending on your setup. Individual users can log in with a Claude.ai account, while teams can use Claude for Teams or Enterprise, the Claude Console, or a cloud provider like Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.

10 10 

11Setting up Claude Code requires access to Anthropic models. For teams, you can set up Claude Code access in one of these ways:11## Log in to Claude Code

12 12 

13* [Claude for Teams or Enterprise](#claude-for-teams-or-enterprise) (recommended)13After [installing Claude Code](/en/setup#install-claude-code), run `claude` in your terminal. On first launch, Claude Code opens a browser window for you to log in.

14 

15If the browser doesn't open automatically, press `c` to copy the login URL to your clipboard, then paste it into your browser.

16 

17You can authenticate with any of these account types:

18 

19* **Claude Pro or Max subscription**: log in with your Claude.ai account. Subscribe at [claude.com/pricing](https://claude.com/pricing).

20* **Claude for Teams or Enterprise**: log in with the Claude.ai account your team admin invited you to.

21* **Claude Console**: log in with your Console credentials. Your admin must have [invited you](#claude-console-authentication) first.

22* **Cloud providers**: if your organization uses [Amazon Bedrock](/en/amazon-bedrock), [Google Vertex AI](/en/google-vertex-ai), or [Microsoft Foundry](/en/microsoft-foundry), set the required environment variables before running `claude`. No browser login is needed.

23 

24To log out and re-authenticate, type `/logout` at the Claude Code prompt.

25 

26If you're having trouble logging in, see [authentication troubleshooting](/en/troubleshooting#authentication-issues).

27 

28## Set up team authentication

29 

30For teams and organizations, you can configure Claude Code access in one of these ways:

31 

32* [Claude for Teams or Enterprise](#claude-for-teams-or-enterprise), recommended for most teams

14* [Claude Console](#claude-console-authentication)33* [Claude Console](#claude-console-authentication)

15* [Amazon Bedrock](/en/amazon-bedrock)34* [Amazon Bedrock](/en/amazon-bedrock)

16* [Google Vertex AI](/en/google-vertex-ai)35* [Google Vertex AI](/en/google-vertex-ai)

49 <Step title="Add users">68 <Step title="Add users">

50 You can add users through either method:69 You can add users through either method:

51 70 

52 * Bulk invite users from within the Console (Console -> Settings -> Members -> Invite)71 * Bulk invite users from within the Console: Settings -> Members -> Invite

53 * [Set up SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)72 * [Set up SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)

54 </Step>73 </Step>

55 74 

65 84 

66 * Accept the Console invite85 * Accept the Console invite

67 * [Check system requirements](/en/setup#system-requirements)86 * [Check system requirements](/en/setup#system-requirements)

68 * [Install Claude Code](/en/setup#installation)87 * [Install Claude Code](/en/setup#install-claude-code)

69 * Log in with Console account credentials88 * Log in with Console account credentials

70 </Step>89 </Step>

71</Steps>90</Steps>

72 91 

73### Cloud provider authentication92### Cloud provider authentication

74 93 

75For teams using Amazon Bedrock, Google Vertex AI, or Microsoft Azure:94For teams using Amazon Bedrock, Google Vertex AI, or Microsoft Foundry:

76 95 

77<Steps>96<Steps>

78 <Step title="Follow provider setup">97 <Step title="Follow provider setup">

84 </Step>103 </Step>

85 104 

86 <Step title="Install Claude Code">105 <Step title="Install Claude Code">

87 Users can [install Claude Code](/en/setup#installation).106 Users can [install Claude Code](/en/setup#install-claude-code).

88 </Step>107 </Step>

89</Steps>108</Steps>

90 109 

92 111 

93Claude Code securely manages your authentication credentials:112Claude Code securely manages your authentication credentials:

94 113 

95* **Storage location**: on macOS, API keys, OAuth tokens, and other credentials are stored in the encrypted macOS Keychain.114* **Storage location**: on macOS, credentials are stored in the encrypted macOS Keychain.

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

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

98* **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.117* **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.

99 

100## See also

101 

102* [Permissions](/en/permissions): configure what Claude Code can access and do

103* [Settings](/en/settings): complete configuration reference

104* [Security](/en/security): security safeguards and best practices

148 Run `/init` to generate a starter CLAUDE.md file based on your current project structure, then refine over time.148 Run `/init` to generate a starter CLAUDE.md file based on your current project structure, then refine over time.

149</Tip>149</Tip>

150 150 

151CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context **it can't infer from code alone**.151CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it can't infer from code alone.

152 152 

153The `/init` command analyzes your codebase to detect build systems, test frameworks, and code patterns, giving you a solid foundation to refine.153The `/init` command analyzes your codebase to detect build systems, test frameworks, and code patterns, giving you a solid foundation to refine.

154 154 

194 194 

195You can place CLAUDE.md files in several locations:195You can place CLAUDE.md files in several locations:

196 196 

197* **Home folder (`~/.claude/CLAUDE.md`)**: Applies to all Claude sessions197* **Home folder (`~/.claude/CLAUDE.md`)**: applies to all Claude sessions

198* **Project root (`./CLAUDE.md`)**: Check into git to share with your team, or name it `CLAUDE.local.md` and `.gitignore` it198* **Project root (`./CLAUDE.md`)**: check into git to share with your team, or name it `CLAUDE.local.md` and `.gitignore` it

199* **Parent directories**: Useful for monorepos where both `root/CLAUDE.md` and `root/foo/CLAUDE.md` are pulled in automatically199* **Parent directories**: useful for monorepos where both `root/CLAUDE.md` and `root/foo/CLAUDE.md` are pulled in automatically

200* **Child directories**: Claude pulls in child CLAUDE.md files on demand when working with files in those directories200* **Child directories**: Claude pulls in child CLAUDE.md files on demand when working with files in those directories

201 201 

202### Configure permissions202### Configure permissions

207 207 

208By default, Claude Code requests permission for actions that might modify your system: file writes, Bash commands, MCP tools, etc. This is safe but tedious. After the tenth approval you're not really reviewing anymore, you're just clicking through. There are two ways to reduce these interruptions:208By default, Claude Code requests permission for actions that might modify your system: file writes, Bash commands, MCP tools, etc. This is safe but tedious. After the tenth approval you're not really reviewing anymore, you're just clicking through. There are two ways to reduce these interruptions:

209 209 

210* **Permission allowlists**: Permit specific tools you know are safe (like `npm run lint` or `git commit`)210* **Permission allowlists**: permit specific tools you know are safe (like `npm run lint` or `git commit`)

211* **Sandboxing**: Enable OS-level isolation that restricts filesystem and network access, allowing Claude to work more freely within defined boundaries211* **Sandboxing**: enable OS-level isolation that restricts filesystem and network access, allowing Claude to work more freely within defined boundaries

212 212 

213Alternatively, use `--dangerously-skip-permissions` to bypass all permission checks for contained workflows like fixing lint errors or generating boilerplate.213Alternatively, use `--dangerously-skip-permissions` to bypass all permission checks for contained workflows like fixing lint errors or generating boilerplate.

214 214 

216 Letting Claude run arbitrary commands can result in data loss, system corruption, or data exfiltration via prompt injection. Only use `--dangerously-skip-permissions` in a sandbox without internet access.216 Letting Claude run arbitrary commands can result in data loss, system corruption, or data exfiltration via prompt injection. Only use `--dangerously-skip-permissions` in a sandbox without internet access.

217</Warning>217</Warning>

218 218 

219Read more about [configuring permissions](/en/settings) and [enabling sandboxing](/en/sandboxing#sandboxing).219Read more about [configuring permissions](/en/permissions) and [enabling sandboxing](/en/sandboxing).

220 220 

221### Use CLI tools221### Use CLI tools

222 222 

356 356 

357Claude asks about things you might not have considered yet, including technical implementation, UI/UX, edge cases, and tradeoffs.357Claude asks about things you might not have considered yet, including technical implementation, UI/UX, edge cases, and tradeoffs.

358 358 

359```359```text theme={null}

360I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.360I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

361 361 

362Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.362Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

380 380 

381The best results come from tight feedback loops. Though Claude occasionally solves problems perfectly on the first attempt, correcting it quickly generally produces better solutions faster.381The best results come from tight feedback loops. Though Claude occasionally solves problems perfectly on the first attempt, correcting it quickly generally produces better solutions faster.

382 382 

383* **`Esc`**: Stop Claude mid-action with the `Esc` key. Context is preserved, so you can redirect.383* **`Esc`**: stop Claude mid-action with the `Esc` key. Context is preserved, so you can redirect.

384* **`Esc + Esc` or `/rewind`**: Press `Esc` twice or run `/rewind` to open the rewind menu and restore previous conversation and code state, or summarize from a selected message.384* **`Esc + Esc` or `/rewind`**: press `Esc` twice or run `/rewind` to open the rewind menu and restore previous conversation and code state, or summarize from a selected message.

385* **`"Undo that"`**: Have Claude revert its changes.385* **`"Undo that"`**: have Claude revert its changes.

386* **`/clear`**: Reset context between unrelated tasks. Long sessions with irrelevant context can reduce performance.386* **`/clear`**: reset context between unrelated tasks. Long sessions with irrelevant context can reduce performance.

387 387 

388If you've corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run `/clear` and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.388If you've corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run `/clear` and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.

389 389 

411 411 

412Since context is your fundamental constraint, subagents are one of the most powerful tools available. When Claude researches a codebase it reads lots of files, all of which consume your context. Subagents run in separate context windows and report back summaries:412Since context is your fundamental constraint, subagents are one of the most powerful tools available. When Claude researches a codebase it reads lots of files, all of which consume your context. Subagents run in separate context windows and report back summaries:

413 413 

414```414```text theme={null}

415Use subagents to investigate how our authentication system handles token415Use subagents to investigate how our authentication system handles token

416refresh, and whether we have any existing OAuth utilities I should reuse.416refresh, and whether we have any existing OAuth utilities I should reuse.

417```417```

420 420 

421You can also use subagents for verification after Claude implements something:421You can also use subagents for verification after Claude implements something:

422 422 

423```423```text theme={null}

424use a subagent to review this code for edge cases424use a subagent to review this code for edge cases

425```425```

426 426 

444 Run `claude --continue` to pick up where you left off, or `--resume` to choose from recent sessions.444 Run `claude --continue` to pick up where you left off, or `--resume` to choose from recent sessions.

445</Tip>445</Tip>

446 446 

447Claude Code saves conversations locally. When a task spans multiple sessions (you start a feature, get interrupted, come back the next day) you don't have to re-explain the context:447Claude Code saves conversations locally. When a task spans multiple sessions, you don't have to re-explain the context:

448 448 

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

450claude --continue # Resume the most recent conversation450claude --continue # Resume the most recent conversation

451claude --resume # Select from recent conversations451claude --resume # Select from recent conversations

452```452```

453 453 

454Use `/rename` to give sessions descriptive names (`"oauth-migration"`, `"debugging-memory-leak"`) so you can find them later. Treat sessions like branches. Different workstreams can have separate, persistent contexts.454Use `/rename` to give sessions descriptive names like `"oauth-migration"` or `"debugging-memory-leak"` so you can find them later. Treat sessions like branches: different workstreams can have separate, persistent contexts.

455 455 

456***456***

457 457 

458## Automate and scale458## Automate and scale

459 459 

460Once you're effective with one Claude, multiply your output with parallel sessions, headless mode, and fan-out patterns.460Once you're effective with one Claude, multiply your output with parallel sessions, non-interactive mode, and fan-out patterns.

461 461 

462Everything so far assumes one human, one Claude, and one conversation. But Claude Code scales horizontally. The techniques in this section show how you can get more done.462Everything so far assumes one human, one Claude, and one conversation. But Claude Code scales horizontally. The techniques in this section show how you can get more done.

463 463 

464### Run headless mode464### Run non-interactive mode

465 465 

466<Tip>466<Tip>

467 Use `claude -p "prompt"` in CI, pre-commit hooks, or scripts. Add `--output-format stream-json` for streaming JSON output.467 Use `claude -p "prompt"` in CI, pre-commit hooks, or scripts. Add `--output-format stream-json` for streaming JSON output.

468</Tip>468</Tip>

469 469 

470With `claude -p "your prompt"`, you can run Claude headlessly, without an interactive session. Headless mode is how you integrate Claude into CI pipelines, pre-commit hooks, or any automated workflow. The output formats (plain text, JSON, streaming JSON) let you parse results programmatically.470With `claude -p "your prompt"`, you can run Claude non-interactively, without a session. Non-interactive mode is how you integrate Claude into CI pipelines, pre-commit hooks, or any automated workflow. The output formats let you parse results programmatically: plain text, JSON, or streaming JSON.

471 471 

472```bash theme={null}472```bash theme={null}

473# One-off queries473# One-off queries

488 488 

489There are three main ways to run parallel sessions:489There are three main ways to run parallel sessions:

490 490 

491* [Claude Desktop](/en/desktop): Manage multiple local sessions visually. Each session gets its own isolated worktree.491* [Claude Code desktop app](/en/desktop#work-in-parallel-with-sessions): Manage multiple local sessions visually. Each session gets its own isolated worktree.

492* [Claude Code on the web](/en/claude-code-on-the-web): Run on Anthropic's secure cloud infrastructure in isolated VMs.492* [Claude Code on the web](/en/claude-code-on-the-web): Run on Anthropic's secure cloud infrastructure in isolated VMs.

493* [Agent teams](/en/agent-teams): Automated coordination of multiple sessions with shared tasks, messaging, and a team lead.493* [Agent teams](/en/agent-teams): Automated coordination of multiple sessions with shared tasks, messaging, and a team lead.

494 494 

539 539 

540Use `--verbose` for debugging during development, and turn it off in production.540Use `--verbose` for debugging during development, and turn it off in production.

541 541 

542### Safe Autonomous Mode542### Safe autonomous mode

543 543 

544Use `claude --dangerously-skip-permissions` to bypass all permission checks and let Claude work uninterrupted. This works well for workflows like fixing lint errors or generating boilerplate code.544Use `claude --dangerously-skip-permissions` to bypass all permission checks and let Claude work uninterrupted. This works well for workflows like fixing lint errors or generating boilerplate code.

545 545 

580 580 

581## Related resources581## Related resources

582 582 

583<CardGroup cols={2}>583* [How Claude Code works](/en/how-claude-code-works): the agentic loop, tools, and context management

584 <Card title="How Claude Code works" icon="gear" href="/en/how-claude-code-works">584* [Extend Claude Code](/en/features-overview): skills, hooks, MCP, subagents, and plugins

585 Understand the agentic loop, tools, and context management585* [Common workflows](/en/common-workflows): step-by-step recipes for debugging, testing, PRs, and more

586 </Card>586* [CLAUDE.md](/en/memory): store project conventions and persistent context

587 

588 <Card title="Extend Claude Code" icon="puzzle-piece" href="/en/features-overview">

589 Choose between skills, hooks, MCP, subagents, and plugins

590 </Card>

591 

592 <Card title="Common workflows" icon="list-check" href="/en/common-workflows">

593 Step-by-step recipes for debugging, testing, PRs, and more

594 </Card>

595 

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

597 Store project conventions and persistent context

598 </Card>

599</CardGroup>

33* [Google Chrome](https://www.google.com/chrome/) or [Microsoft Edge](https://www.microsoft.com/edge) browser33* [Google Chrome](https://www.google.com/chrome/) or [Microsoft Edge](https://www.microsoft.com/edge) browser

34* [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or higher, available in the Chrome Web Store for both browsers34* [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or higher, available in the Chrome Web Store for both browsers

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

36* A direct Anthropic plan (Pro, Max, Team, or Enterprise)36* A direct Anthropic plan (Pro, Max, Teams, or Enterprise)

37 37 

38<Note>38<Note>

39 Chrome integration is not available through third-party providers like Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Foundry. If you access Claude exclusively through a third-party provider, you need a separate claude.ai account to use this feature.39 Chrome integration is not available through third-party providers like Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Foundry. If you access Claude exclusively through a third-party provider, you need a separate claude.ai account to use this feature.

20* **Repositories not on your local machine**: Work on code you don't have checked out locally20* **Repositories not on your local machine**: Work on code you don't have checked out locally

21* **Backend changes**: Where Claude Code can write tests and then write code to pass those tests21* **Backend changes**: Where Claude Code can write tests and then write code to pass those tests

22 22 

23Claude Code is also available on the Claude iOS app for kicking off tasks on the go and monitoring work in progress.23Claude Code is also available on the Claude app for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) and [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) for kicking off tasks on the go and monitoring work in progress.

24 24 

25You can move between local and remote development: [send tasks from your terminal to run on the web](#from-terminal-to-web) with the `&` prefix, or [teleport web sessions back to your terminal](#from-web-to-terminal) to continue locally.25You can [kick off new tasks on the web from your terminal](#from-terminal-to-web) with `--remote`, or [teleport web sessions back to your terminal](#from-web-to-terminal) to continue locally. To use the web interface while running Claude Code on your own machine instead of cloud infrastructure, see [Remote Control](/en/remote-control).

26 26 

27## Who can use Claude Code on the web?27## Who can use Claude Code on the web?

28 28 

69 69 

70## Moving tasks between web and terminal70## Moving tasks between web and terminal

71 71 

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

73 73 

74<Note>74<Note>

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

76</Note>76</Note>

77 77 

78### From terminal to web78### From terminal to web

79 79 

80Start a message with `&` inside Claude Code to send a task to run on the web:80Start a web session from the command line with the `--remote` flag:

81 

82```

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

84```

85 

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

87 

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

89 81 

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

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

92```84```

93 85 

94#### Tips for background tasks86This creates a new web session on claude.ai. The task runs in the cloud while you continue working locally. Use `/tasks` to check progress, or open the session on claude.ai or the Claude mobile app to interact directly. From there you can steer Claude, provide feedback, or answer questions just like any other conversation.

87 

88#### Tips for remote tasks

95 89 

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

97 91 

98```bash theme={null}92```bash theme={null}

99claude --permission-mode plan93claude --permission-mode plan

100```94```

101 95 

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

103 97 

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

105& Execute the migration plan we discussed99claude --remote "Execute the migration plan in docs/migration-plan.md"

106```100```

107 101 

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

109 103 

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

111 105 

112```106```bash theme={null}

113& Fix the flaky test in auth.spec.ts107claude --remote "Fix the flaky test in auth.spec.ts"

114& Update the API documentation108claude --remote "Update the API documentation"

115& Refactor the logger to use structured output109claude --remote "Refactor the logger to use structured output"

116```110```

117 111 

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

232 226 

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

234 228 

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

236 230 

237<Note>231<Note>

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

239 233 

240 ```234 ```text theme={null}

241 API_KEY=your_api_key235 API_KEY=your_api_key

242 DEBUG=true236 DEBUG=true

243 ```237 ```

8 8 

9## CLI commands9## CLI commands

10 10 

11You can start sessions, pipe content, resume conversations, and manage updates with these commands:

12 

11| Command | Description | Example |13| Command | Description | Example |

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

13| `claude` | Start interactive REPL | `claude` |15| `claude` | Start interactive session | `claude` |

14| `claude "query"` | Start REPL with initial prompt | `claude "explain this project"` |16| `claude "query"` | Start interactive session with initial prompt | `claude "explain this project"` |

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

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

17| `claude -c` | Continue most recent conversation in current directory | `claude -c` |19| `claude -c` | Continue most recent conversation in current directory | `claude -c` |

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

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

20| `claude update` | Update to latest version | `claude update` |22| `claude update` | Update to latest version | `claude update` |

23| `claude auth login` | Sign in to your Anthropic account. Use `--email` to pre-fill your email address and `--sso` to force SSO authentication | `claude auth login --email user@example.com --sso` |

24| `claude auth logout` | Log out from your Anthropic account | `claude auth logout` |

25| `claude auth status` | Show authentication status as JSON. Use `--text` for human-readable output. Exits with code 0 if logged in, 1 if not | `claude auth status` |

26| `claude agents` | List all configured [subagents](/en/sub-agents), grouped by source | `claude agents` |

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

28| `claude remote-control` | Start a [Remote Control session](/en/remote-control) to control Claude Code from Claude.ai or the Claude app while running locally. See [Remote Control](/en/remote-control) for flags | `claude remote-control` |

22 29 

23## CLI flags30## CLI flags

24 31 

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

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

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

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

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

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

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

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

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

76| `--version`, `-v` | Output the version number | `claude -v` |83| `--version`, `-v` | Output the version number | `claude -v` |

84| `--worktree`, `-w` | Start Claude in an isolated [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) at `<repo>/.claude/worktrees/<name>`. If no name is given, one is auto-generated | `claude -w feature-auth` |

77 85 

78<Tip>86<Tip>

79 The `--output-format json` flag is particularly useful for scripting and87 The `--output-format json` flag is particularly useful for scripting and

127 135 

128**When to use each:**136**When to use each:**

129 137 

130* **`--system-prompt`**: Use when you need complete control over Claude's system prompt. This removes all default Claude Code instructions, giving you a blank slate.138* **`--system-prompt`**: use when you need complete control over Claude's system prompt. This removes all default Claude Code instructions, giving you a blank slate.

131 ```bash theme={null}139 ```bash theme={null}

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

133 ```141 ```

134 142 

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

136 ```bash theme={null}144 ```bash theme={null}

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

138 ```146 ```

139 147 

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

141 ```bash theme={null}149 ```bash theme={null}

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

143 ```151 ```

144 152 

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

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

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

148 ```156 ```

240 240 

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

242 242 

243If 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`. When an [agent team](/en/agent-teams) is active, the cycle also includes Delegate Mode.243If 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`.

244 244 

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

246 246 

540 540 

541**With other models**, thinking uses a fixed budget of up to 31,999 tokens from your output budget. You can limit this with the [`MAX_THINKING_TOKENS`](/en/settings#environment-variables) environment variable, or disable thinking entirely via `/config` or the `Option+T`/`Alt+T` toggle.541**With other models**, thinking uses a fixed budget of up to 31,999 tokens from your output budget. You can limit this with the [`MAX_THINKING_TOKENS`](/en/settings#environment-variables) environment variable, or disable thinking entirely via `/config` or the `Option+T`/`Alt+T` toggle.

542 542 

543`MAX_THINKING_TOKENS` is ignored when using Opus 4.6, since adaptive reasoning controls thinking depth instead. The one exception: setting `MAX_THINKING_TOKENS=0` still disables thinking entirely on any model.543`MAX_THINKING_TOKENS` is ignored on Opus 4.6 and Sonnet 4.6, since adaptive reasoning controls thinking depth instead. The one exception: setting `MAX_THINKING_TOKENS=0` still disables thinking entirely on any model. To disable adaptive thinking and revert to the fixed thinking budget, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`. See [environment variables](/en/settings#environment-variables).

544 544 

545<Warning>545<Warning>

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

642 642 

643## Run parallel Claude Code sessions with Git worktrees643## Run parallel Claude Code sessions with Git worktrees

644 644 

645Suppose you need to work on multiple tasks simultaneously with complete code isolation between Claude Code instances.645When working on multiple tasks at once, you need each Claude session to have its own copy of the codebase so changes don't collide. Git worktrees solve this by creating separate working directories that each have their own files and branch, while sharing the same repository history and remote connections. This means you can have Claude working on a feature in one worktree while fixing a bug in another, without either session interfering with the other.

646 

647Use the `--worktree` (`-w`) flag to create an isolated worktree and start Claude in it. The value you pass becomes the worktree directory name and branch name:

648 

649```bash theme={null}

650# Start Claude in a worktree named "feature-auth"

651# Creates .claude/worktrees/feature-auth/ with a new branch

652claude --worktree feature-auth

653 

654# Start another session in a separate worktree

655claude --worktree bugfix-123

656```

657 

658If you omit the name, Claude generates a random one automatically:

659 

660```bash theme={null}

661# Auto-generates a name like "bright-running-fox"

662claude --worktree

663```

664 

665Worktrees are created at `<repo>/.claude/worktrees/<name>` and branch from the default remote branch. The worktree branch is named `worktree-<name>`.

666 

667You can also ask Claude to "work in a worktree" or "start a worktree" during a session, and it will create one automatically.

668 

669### Subagent worktrees

670 

671Subagents can also use worktree isolation to work in parallel without conflicts. Ask Claude to "use worktrees for your agents" or configure it in a [custom subagent](/en/sub-agents#supported-frontmatter-fields) by adding `isolation: worktree` to the agent's frontmatter. Each subagent gets its own worktree that is automatically cleaned up when the subagent finishes without changes.

672 

673### Worktree cleanup

674 

675When you exit a worktree session, Claude handles cleanup based on whether you made changes:

676 

677* **No changes**: the worktree and its branch are removed automatically

678* **Changes or commits exist**: Claude prompts you to keep or remove the worktree. Keeping preserves the directory and branch so you can return later. Removing deletes the worktree directory and its branch, discarding all uncommitted changes and commits

679 

680To clean up worktrees outside of a Claude session, use [manual worktree management](#manage-worktrees-manually).

681 

682<Tip>

683 Add `.claude/worktrees/` to your `.gitignore` to prevent worktree contents from appearing as untracked files in your main repository.

684</Tip>

685 

686### Manage worktrees manually

687 

688For more control over worktree location and branch configuration, create worktrees with Git directly. This is useful when you need to check out a specific existing branch or place the worktree outside the repository.

689 

690```bash theme={null}

691# Create a worktree with a new branch

692git worktree add ../project-feature-a -b feature-a

693 

694# Create a worktree with an existing branch

695git worktree add ../project-bugfix bugfix-123

696 

697# Start Claude in the worktree

698cd ../project-feature-a && claude

699 

700# Clean up when done

701git worktree list

702git worktree remove ../project-feature-a

703```

704 

705Learn more in the [official Git worktree documentation](https://git-scm.com/docs/git-worktree).

706 

707<Tip>

708 Remember to initialize your development environment in each new worktree according to your project's setup. Depending on your stack, this might include running dependency installation (`npm install`, `yarn`), setting up virtual environments, or following your project's standard setup process.

709</Tip>

710 

711### Non-git version control

712 

713Worktree isolation works with git by default. For other version control systems like SVN, Perforce, or Mercurial, configure [WorktreeCreate and WorktreeRemove hooks](/en/hooks#worktreecreate) to provide custom worktree creation and cleanup logic. When configured, these hooks replace the default git behavior when you use `--worktree`.

714 

715For automated coordination of parallel sessions with shared tasks and messaging, see [agent teams](/en/agent-teams).

716 

717***

718 

719## Get notified when Claude needs your attention

720 

721When you kick off a long-running task and switch to another window, you can set up desktop notifications so you know when Claude finishes or needs your input. This uses the `Notification` [hook event](/en/hooks-guide#get-notified-when-claude-needs-input), which fires whenever Claude is waiting for permission, idle and ready for a new prompt, or completing authentication.

646 722 

647<Steps>723<Steps>

648 <Step title="Understand Git worktrees">724 <Step title="Open the hooks menu">

649 Git worktrees allow you to check out multiple branches from the same725 Type `/hooks` and select `Notification` from the list of events.

650 repository into separate directories. Each worktree has its own working

651 directory with isolated files, while sharing the same Git history. Learn

652 more in the [official Git worktree

653 documentation](https://git-scm.com/docs/git-worktree).

654 </Step>726 </Step>

655 727 

656 <Step title="Create a new worktree">728 <Step title="Configure the matcher">

657 ```bash theme={null}729 Select `+ Match all (no filter)` to fire on all notification types. To notify only for specific events, select `+ Add new matcher…` and enter one of these values:

658 # Create a new worktree with a new branch

659 git worktree add ../project-feature-a -b feature-a

660 

661 # Or create a worktree with an existing branch

662 git worktree add ../project-bugfix bugfix-123

663 ```

664 730 

665 This creates a new directory with a separate working copy of your repository.731 | Matcher | Fires when |

732 | :------------------- | :---------------------------------------------- |

733 | `permission_prompt` | Claude needs you to approve a tool use |

734 | `idle_prompt` | Claude is done and waiting for your next prompt |

735 | `auth_success` | Authentication completes |

736 | `elicitation_dialog` | Claude is asking you a question |

666 </Step>737 </Step>

667 738 

668 <Step title="Run Claude Code in each worktree">739 <Step title="Add your notification command">

669 ```bash theme={null}740 Select `+ Add new hook…` and enter the command for your OS:

670 # Navigate to your worktree 741 

671 cd ../project-feature-a742 <Tabs>

743 <Tab title="macOS">

744 Uses [`osascript`](https://ss64.com/mac/osascript.html) to trigger a native macOS notification through AppleScript:

672 745 

673 # Run Claude Code in this isolated environment

674 claude

675 ```746 ```

676 </Step>747 osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'

748 ```

749 </Tab>

750 

751 <Tab title="Linux">

752 Uses `notify-send`, which is pre-installed on most Linux desktops with a notification daemon:

677 753 

678 <Step title="Run Claude in another worktree">

679 ```bash theme={null}

680 cd ../project-bugfix

681 claude

682 ```754 ```

683 </Step>755 notify-send 'Claude Code' 'Claude Code needs your attention'

756 ```

757 </Tab>

684 758 

685 <Step title="Manage your worktrees">759 <Tab title="Windows (PowerShell)">

686 ```bash theme={null}760 Uses PowerShell to show a native message box through .NET's Windows Forms:

687 # List all worktrees

688 git worktree list

689 761 

690 # Remove a worktree when done

691 git worktree remove ../project-feature-a

692 ```762 ```

763 powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')"

764 ```

765 </Tab>

766 </Tabs>

693 </Step>767 </Step>

694</Steps>

695 768 

696<Tip>769 <Step title="Save to user settings">

697 Tips:770 Select `User settings` to apply the notification across all your projects.

698 771 </Step>

699 * Each worktree has its own independent file state, making it perfect for parallel Claude Code sessions772</Steps>

700 * Changes made in one worktree won't affect others, preventing Claude instances from interfering with each other

701 * All worktrees share the same Git history and remote connections

702 * For long-running tasks, you can have Claude working in one worktree while you continue development in another

703 * Use descriptive directory names to easily identify which task each worktree is for

704 * Remember to initialize your development environment in each new worktree according to your project's setup. Depending on your stack, this might include:

705 * JavaScript projects: Running dependency installation (`npm install`, `yarn`)

706 * Python projects: Setting up virtual environments or installing with package managers

707 * Other languages: Following your project's standard setup process

708</Tip>

709 773 

710For automated coordination of parallel sessions with shared tasks and messaging, see [agent teams](/en/agent-teams).774For the full walkthrough with JSON configuration examples, see [Automate workflows with hooks](/en/hooks-guide#get-notified-when-claude-needs-input). For the complete event schema and notification types, see the [Notification reference](/en/hooks#notification).

711 775 

712***776***

713 777 

8 8 

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

10 10 

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

12 12 

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

14 14 

22 22 

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

24 24 

25```25```text theme={null}

26Total cost: $0.5526Total cost: $0.55

27Total duration (API): 6m 19.7s27Total duration (API): 6m 19.7s

28Total duration (wall): 6h 33m 10.2s28Total duration (wall): 6h 33m 10.2s

51 51 

52## Data access52## Data access

53 53 

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

55 55 

56## Local Claude Code: Data flow and dependencies56## Local Claude Code: Data flow and dependencies

57 57 

58The diagram below shows how Claude Code connects to external services during installation and normal operation. Solid lines indicate required connections, while dashed lines represent optional or user-initiated data flows.58The diagram below shows how Claude Code connects to external services during installation and normal operation. Solid lines indicate required connections, while dashed lines represent optional or user-initiated data flows.

59 59 

60<img src="https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=9e77f476347e7c9983f6e211d27cf6a9" alt="Diagram showing Claude Code's external connections: install/update connects to NPM, and user requests connect to Anthropic services including Console auth, public-api, and optionally Statsig, Sentry, and bug reporting" data-og-width="720" width="720" data-og-height="520" height="520" data-path="images/claude-code-data-flow.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=280&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=94c033b9b6db3d10b9e2d7c6d681d9dc 280w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=560&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=430aaaf77c28c501d5753ffa456ee227 560w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=840&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=63c3c3f160b522220a8291fe2f93f970 840w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=1100&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=a7f6e838482f4a1a0a0b4683439369ea 1100w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=1650&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=5fbf749c2f94babb3ef72edfb7aba1e9 1650w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=2500&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=7a1babbdccc4986957698d9c5c30c4a8 2500w" />60<img src="https://mintcdn.com/claude-code/TBPmHzr19mDCuhZi/images/claude-code-data-flow.svg?fit=max&auto=format&n=TBPmHzr19mDCuhZi&q=85&s=e0239c69a0bbae485b726338e50f1082" alt="Diagram showing Claude Code's external connections: install/update connects to NPM, and user requests connect to Anthropic services including Console auth, public-api, and optionally Statsig, Sentry, and bug reporting" data-og-width="720" width="720" data-og-height="520" height="520" data-path="images/claude-code-data-flow.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/TBPmHzr19mDCuhZi/images/claude-code-data-flow.svg?w=280&fit=max&auto=format&n=TBPmHzr19mDCuhZi&q=85&s=06435e080df22e66a454e99af1b6040b 280w, https://mintcdn.com/claude-code/TBPmHzr19mDCuhZi/images/claude-code-data-flow.svg?w=560&fit=max&auto=format&n=TBPmHzr19mDCuhZi&q=85&s=8261c15b4ffc12504e0a6e3f0ccd8c7d 560w, https://mintcdn.com/claude-code/TBPmHzr19mDCuhZi/images/claude-code-data-flow.svg?w=840&fit=max&auto=format&n=TBPmHzr19mDCuhZi&q=85&s=163bfaa8d4727a1bbb492cb086e5f083 840w, https://mintcdn.com/claude-code/TBPmHzr19mDCuhZi/images/claude-code-data-flow.svg?w=1100&fit=max&auto=format&n=TBPmHzr19mDCuhZi&q=85&s=ea3c2f801dfa5ad956b18b5f72df5c50 1100w, https://mintcdn.com/claude-code/TBPmHzr19mDCuhZi/images/claude-code-data-flow.svg?w=1650&fit=max&auto=format&n=TBPmHzr19mDCuhZi&q=85&s=91d743def7a8d074c93001b351f23037 1650w, https://mintcdn.com/claude-code/TBPmHzr19mDCuhZi/images/claude-code-data-flow.svg?w=2500&fit=max&auto=format&n=TBPmHzr19mDCuhZi&q=85&s=df68b2dd6de83316f70fd7f61c3a3bbd 2500w" />

61 61 

62Claude Code is installed from [NPM](https://www.npmjs.com/package/@anthropic-ai/claude-code). Claude Code runs locally. In order to interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs. The data is encrypted in transit via TLS and is not encrypted at rest. Claude Code is compatible with most popular VPNs and LLM proxies.62Claude Code is installed from [NPM](https://www.npmjs.com/package/@anthropic-ai/claude-code). Claude Code runs locally. In order to interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs. The data is encrypted in transit via TLS and is not encrypted at rest. Claude Code is compatible with most popular VPNs and LLM proxies.

63 63 

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4 

5# Claude Code on desktop5# Use Claude Code Desktop

6 6 

7> Run Claude Code tasks locally or on secure cloud infrastructure with the Claude desktop app7> Get more out of Claude Code Desktop: parallel sessions with Git isolation, visual diff review, app previews, PR monitoring, permission modes, connectors, and enterprise configuration.

8 8 

9<Note>9The Code tab within the Claude Desktop app lets you use Claude Code through a graphical interface instead of the terminal.

10 Claude Code on desktop is currently in preview.

11</Note>

12 10 

13Claude Code is an AI coding assistant that works directly with your codebase. Unlike Claude.ai chat, it can read your project files, edit code, run terminal commands, and understand how different parts of your code connect. You watch changes happen in real time.11Desktop adds these capabilities on top of the standard Claude Code experience:

14 12 

15You can use Claude Code through the terminal ([CLI](/en/quickstart)) or through the desktop app described here. Both provide the same core capabilities. The desktop app adds a graphical interface and visual session management.13* Visual diff review with inline comments

14* Live app preview with dev servers

15* GitHub PR monitoring with auto-fix and auto-merge

16* Parallel sessions with automatic Git worktree isolation

17* Connectors for GitHub, Slack, Linear, and more

18* Local, [SSH](#ssh-sessions), and [cloud](#run-long-running-tasks-remotely) environments

16 19 

17<CardGroup cols={2}>20<Tip>

18 <Card title="New to Claude Code?" icon="rocket" href="#installation-and-setup">21 New to Desktop? Start with [Get started](/en/desktop-quickstart) to install the app and make your first edit.

19 Start here to install and make your first edit22</Tip>

20 </Card>

21 23 

22 <Card title="Coming from the CLI?" icon="terminal" href="#how-desktop-relates-to-cli">24This page covers [working with code](#work-with-code), [managing sessions](#manage-sessions), [extending Claude Code](#extend-claude-code), and [configuration](#environment-configuration). It also includes a [CLI comparison](#coming-from-the-cli) and [troubleshooting](#troubleshooting).

23 See what's shared and what's different

24 </Card>

25</CardGroup>

26 25 

27The desktop app has three tabs:26## Start a session

28 27 

29* **Chat**: A conversational interface for general questions and tasks (like Claude.ai)28Before you send your first message, configure four things in the prompt area:

30* **Cowork**: An autonomous agent that works on tasks in the background

31* **Code**: An AI coding assistant that reads and edits your project files directly

32 29 

33This documentation covers the **Code** tab. For the chat interface, see the [Claude Desktop support articles](https://support.claude.com/en/collections/16163169-claude-desktop).30* **Environment**: choose where Claude runs. Select **Local** for your machine, **Remote** for Anthropic-hosted cloud sessions, or an [**SSH connection**](#ssh-sessions) for a remote machine you manage. See [environment configuration](#environment-configuration).

31* **Project folder**: select the folder or repository Claude works in. For remote sessions, you can add [multiple repositories](#run-long-running-tasks-remotely).

32* **Model**: pick a [model](/en/model-config#available-models) from the dropdown next to the send button. The model is locked once the session starts.

33* **Permission mode**: choose how much autonomy Claude has from the [mode selector](#choose-a-permission-mode). You can change this during the session.

34 34 

35## Installation and setup35Type your task and press **Enter** to start. Each session tracks its own context and changes independently.

36 36 

37<Steps>37## Work with code

38 <Step title="Download the app">

39 Download Claude for your platform. You'll need an Anthropic account ([sign up at claude.ai](https://claude.ai) if you don't have one).

40 38 

41 <CardGroup cols={2}>39Give Claude the right context, control how much it does on its own, and review what it changed.

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

43 Universal build for Intel and Apple Silicon

44 </Card>

45 40 

46 <Card title="Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code&utm_medium=docs">41### Use the prompt box

47 For x64 processors

48 </Card>

49 </CardGroup>

50 42 

51 For Windows ARM64, [download here](https://claude.ai/api/desktop/win32/arm64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs). Local sessions are not available on ARM64 devices, so use remote sessions instead.43Type what you want Claude to do and press **Enter** to send. Claude reads your project files, makes changes, and runs commands based on your [permission mode](#choose-a-permission-mode). You can interrupt Claude at any point: click the stop button or type your correction and press **Enter**. Claude stops what it's doing and adjusts based on your input.

52 44 

53 Linux is not currently supported.45The **+** button next to the prompt box gives you access to file attachments, [skills](#use-skills), [connectors](#connect-external-tools), and [plugins](#install-plugins).

54 </Step>

55 46 

56 <Step title="Open the app and sign in">47### Add files and context to prompts

57 Launch Claude from your Applications folder (macOS) or Start menu (Windows). Sign in with your Anthropic account.

58 </Step>

59 48 

60 <Step title="Select the Code tab">49The prompt box supports two ways to bring in external context:

61 Click the **Code** tab in the top left. If clicking Code prompts you to sign in online, complete the sign-in and restart the app.

62 </Step>

63</Steps>

64 50 

65## Getting started51* **@mention files**: type `@` followed by a filename to add a file to the conversation context. Claude can then read and reference that file.

52* **Attach files**: attach images, PDFs, and other files to your prompt using the attachment button, or drag and drop files directly into the prompt. This is useful for sharing screenshots of bugs, design mockups, or reference documents.

66 53 

67If you already use the CLI, you can skip to [How Desktop relates to CLI](#how-desktop-relates-to-cli) for a quick overview of differences.54### Choose a permission mode

68 55 

69<Steps>56Permission modes control how much autonomy Claude has during a session: whether it asks before editing files, running commands, or both. You can switch modes at any time using the mode selector next to the send button. Start with Ask permissions to see exactly what Claude does, then move to Auto accept edits or Plan mode as you get comfortable.

70 <Step title="Choose a folder and environment">

71 Select **Local** to run Claude on your machine using your files directly. This is the best choice for getting started. Click **Select folder** and choose your project directory.

72 57 

73 You can also run [remote sessions](/en/claude-code-on-the-web) that continue in the cloud even if you close the app.58| Mode | Settings key | Behavior |

74 </Step>59| ---------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

60| **Ask permissions** | `default` | Claude asks before editing files or running commands. You see a diff and can accept or reject each change. Recommended for new users. |

61| **Auto accept edits** | `acceptEdits` | Claude auto-accepts file edits but still asks before running terminal commands. Use this when you trust file changes and want faster iteration. |

62| **Plan mode** | `plan` | Claude analyzes your code and creates a plan without modifying files or running commands. Good for complex tasks where you want to review the approach first. |

63| **Bypass permissions** | `bypassPermissions` | Claude runs without any permission prompts, equivalent to `--dangerously-skip-permissions` in the CLI. Enable in your Settings → Claude Code under "Allow bypass permissions mode". Only use this in sandboxed containers or VMs. Enterprise admins can disable this option. |

75 64 

76 <Step title="Start a session">65The `dontAsk` permission mode is available only in the [CLI](/en/permissions#permission-modes).

77 Type what you want Claude to do:

78 66 

79 * "Find a TODO comment and fix it"67<Tip title="Best practice">

80 * "Add tests for the main function"68 Start complex tasks in Plan mode so Claude maps out an approach before making changes. Once you approve the plan, switch to Auto accept edits or Ask permissions to execute it. See [explore first, then plan, then code](/en/best-practices#explore-first-then-plan-then-code) for more on this workflow.

81 * "Create a CLAUDE.md with instructions for this codebase"69</Tip>

82 70 

83 A **session** is a conversation with Claude about your code. Each session tracks its own context and changes, so you can work on multiple tasks without them interfering with each other.71Remote sessions support Auto accept edits and Plan mode. Ask permissions is not available because remote sessions auto-accept file edits by default, and Bypass permissions is not available because the remote environment is already sandboxed.

84 </Step>

85 72 

86 <Step title="Review and accept changes">73Enterprise admins can restrict which permission modes are available. See [enterprise configuration](#enterprise-configuration) for details.

87 By default, Code is in **Ask** mode, where Claude proposes changes and waits for your approval before applying them. You'll see:

88 74 

89 1. **A diff view** showing exactly what will change in each file75### Preview your app

90 2. **Accept/Reject buttons** to approve or decline each change

91 3. **Real-time updates** as Claude works through your request

92 76 

93 If you reject a change, Claude will ask how you'd like to proceed differently. Your files aren't modified until you accept.77Claude can start a dev server and open an embedded browser to verify its changes. This works for frontend web apps as well as backend servers: Claude can test API endpoints, view server logs, and iterate on issues it finds. In most cases, Claude starts the server automatically after editing project files. You can also ask Claude to preview at any time. By default, Claude [auto-verifies](#auto-verify-changes) changes after every edit.

94 </Step>

95</Steps>

96 78 

97The sections below cover commands, permission modes, parallel sessions, and ways to extend Claude Code with custom workflows and integrations.79From the preview panel, you can:

98 80 

99## What you can do81* Interact with your running app directly in the embedded browser

82* Watch Claude verify its own changes automatically: it takes screenshots, inspects the DOM, clicks elements, fills forms, and fixes issues it finds

83* Start or stop servers from the **Preview** dropdown in the session toolbar

84* Persist cookies and local storage across server restarts by selecting **Persist sessions** in the dropdown, so you don't have to re-login during development

85* Edit the server configuration or stop all servers at once

100 86 

101Claude Code can edit files, run terminal commands, and understand how your code connects. Try prompts like:87Claude creates the initial server configuration based on your project. If your app uses a custom dev command, edit `.claude/launch.json` to match your setup. See [Configure preview servers](#configure-preview-servers) for the full reference.

102 88 

103* `Fix the bug in the login function`89To clear saved session data, toggle **Persist preview sessions** off in Settings → Claude Code. To disable preview entirely, toggle off **Preview** in Settings → Claude Code.

104* `Run the tests and fix any failures`

105* `How does the authentication flow work?`

106 90 

107You can rename, resume, and archive sessions through the sidebar.91### Review changes with diff view

108 92 

109### Choose a permission mode93After Claude makes changes to your code, the diff view lets you review modifications file by file before creating a pull request.

110 94 

111Control how Claude works using the mode selector next to the send button:95When Claude changes files, a diff stats indicator appears showing the number of lines added and removed, such as `+12 -1`. Click this indicator to open the diff viewer, which displays a file list on the left and the changes for each file on the right.

112 96 

113* **Ask** (recommended for new users): Claude asks for your approval before each file edit or command. You see a diff view and can accept or reject each change.97To comment on specific lines, click any line in the diff to open a comment box. Type your feedback and press **Enter** to add the comment. After adding comments to multiple lines, submit all comments at once:

114* **Code**: Claude auto-accepts file edits but still asks before running terminal commands. Use this when you trust file changes and want faster iteration.

115* **Plan**: Claude creates a detailed plan for your approval before making any changes. Good for complex tasks where you want to review the approach first.

116* **Act**: Claude runs without permission checks, automatically executing file edits and terminal commands. Only use this mode in trusted environments.

117 98 

118<Warning title="Act mode">99* **macOS**: press **Cmd+Enter**

119 Act runs in `bypassPermissions` mode, which disables all permission checks and should only be used in isolated environments like containers or VMs where Claude Code cannot cause damage. This mode is disabled by default. For personal accounts, enable it in [Claude Code personal settings](https://claude.ai/settings/claude-code). For Team and Enterprise plans, admins must enable it in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code). Act mode does not persist across sessions.100* **Windows**: press **Ctrl+Enter**

120</Warning>

121 101 

122To stop Claude mid-task, click the stop button.102Claude reads your comments and makes the requested changes, which appear as a new diff you can review.

123 103 

124Remote sessions only support **Code** and **Plan** modes because they continue running in the background without requiring your active participation. See [permission modes](/en/permissions#permission-modes) for details on how these work internally.104### Review your code

125 105 

126### Work in parallel with sessions106In the diff view, click **Review code** in the top-right toolbar to ask Claude to evaluate the changes before you commit. Claude examines the current diffs and leaves comments directly in the diff view. You can respond to any comment or ask Claude to revise.

107 

108The review focuses on high-signal issues: compile errors, definite logic errors, security vulnerabilities, and obvious bugs. It does not flag style, formatting, pre-existing issues, or anything a linter would catch.

109 

110### Monitor pull request status

127 111 

128Click **+ New session** in the sidebar to work on multiple tasks in parallel. For Git repositories, each session gets its own isolated copy of your project using worktrees, so changes in one session don't affect another until you commit them. Worktrees are stored in `~/.claude-worktrees/` by default.112After you open a pull request, a CI status bar appears in the session. Claude Code uses the GitHub CLI to poll check results and surface failures.

113 

114* **Auto-fix**: when enabled, Claude automatically attempts to fix failing CI checks by reading the failure output and iterating.

115* **Auto-merge**: when enabled, Claude merges the PR once all checks pass. The merge method is squash. Auto-merge must be [enabled in your GitHub repository settings](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository) for this to work.

116 

117Use the **Auto-fix** and **Auto-merge** toggles in the CI status bar to enable either option. Claude Code also sends a desktop notification when CI finishes.

129 118 

130<Note>119<Note>

131 Session isolation requires [Git](https://git-scm.com/downloads). Without Git, sessions in the same directory edit the same files, so changes in one session are immediately visible in others.120 PR monitoring requires the [GitHub CLI (`gh`)](https://cli.github.com/) to be installed and authenticated on your machine. If `gh` is not installed, Desktop prompts you to install it the first time you try to create a PR.

132</Note>121</Note>

133 122 

134To include files listed in your `.gitignore` (like `.env`) in new worktrees, create a `.worktreeinclude` file in your project root listing the file patterns to copy.123## Manage sessions

135 124 

136To manage a session, click its dropdown in the sidebar to rename it, archive it, or check context usage. When context fills up, Claude automatically summarizes the conversation. You can also ask Claude to compact if you want to free up space earlier.125Each session is an independent conversation with its own context and changes. You can run multiple sessions in parallel or send work to the cloud.

126 

127### Work in parallel with sessions

128 

129Click **+ New session** in the sidebar to work on multiple tasks in parallel. For Git repositories, each session gets its own isolated copy of your project using [Git worktrees](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), so changes in one session don't affect other sessions until you commit them.

130 

131Worktrees are stored in `<project-root>/.claude/worktrees/` by default. You can change this to a custom directory in Settings → Claude Code under "Worktree location". You can also set a branch prefix that gets prepended to every worktree branch name, which is useful for keeping Claude-created branches organized. To remove a worktree when you're done, hover over the session in the sidebar and click the archive icon.

132 

133<Note>

134 Session isolation requires [Git](https://git-scm.com/downloads). Most Macs include Git by default. Run `git --version` in Terminal to check. On Windows, Git is required for the Code tab to work: [download Git for Windows](https://git-scm.com/downloads/win), install it, and restart the app. If you run into Git errors, try a Cowork session to help troubleshoot your setup.

135</Note>

136 

137Use the filter icon at the top of the sidebar to filter sessions by status (Active, Archived) and environment (Local, Cloud). To rename a session or check context usage, click the session title in the toolbar at the top of the active session. When context fills up, Claude automatically summarizes the conversation and continues working. You can also type `/compact` to trigger summarization earlier and free up context space. See [the context window](/en/how-claude-code-works#the-context-window) for details on how compaction works.

137 138 

138### Run long-running tasks remotely139### Run long-running tasks remotely

139 140 

140For large refactors, test suites, migrations, or other long-running tasks, select **Remote** instead of **Local** when starting a session. Remote sessions run on Anthropic's cloud infrastructure and continue even if you close the app or shut down your computer. Check back anytime to see progress or steer Claude in a different direction.141For large refactors, test suites, migrations, or other long-running tasks, select **Remote** instead of **Local** when starting a session. Remote sessions run on Anthropic's cloud infrastructure and continue even if you close the app or shut down your computer. Check back anytime to see progress or steer Claude in a different direction. You can also monitor remote sessions from [claude.ai/code](https://claude.ai/code) or the Claude iOS app.

141 142 

142Remote sessions support **Code** and **Plan** modes. See [Claude Code on the web](/en/claude-code-on-the-web) for details on configuring remote environments.143Remote sessions also support multiple repositories. After selecting a cloud environment, click the **+** button next to the repo pill to add additional repositories to the session. Each repo gets its own branch selector. This is useful for tasks that span multiple codebases, such as updating a shared library and its consumers.

143 144 

144### Review changes with diff view145See [Claude Code on the web](/en/claude-code-on-the-web) for more on how remote sessions work.

145 146 

146After Claude makes changes to your code, the diff view lets you review modifications file by file before creating a pull request.147### Continue in another surface

147 148 

148When Claude changes files, a diff stats indicator appears showing the number of lines added and removed (for example, `+12 -1`). Click this indicator to open the diff viewer, which displays a file list on the left and the changes for each file on the right.149The **Continue in** menu, accessible from the VS Code icon in the bottom right of the session toolbar, lets you move your session to another surface:

149 150 

150To comment on specific lines, click any line in the diff to open a comment box. Type your feedback and press **Enter** to send. In the full diff view, press **Enter** to accept each comment, then **Cmd+Enter** to send them all. Claude reads your comments and makes the requested changes, which appear as a new diff you can review.151* **Claude Code on the Web**: sends your local session to continue running remotely. Desktop pushes your branch, generates a summary of the conversation, and creates a new remote session with the full context. You can then choose to archive the local session or keep it. This requires a clean working tree, and is not available for SSH sessions.

152* **Your IDE**: opens your project in a supported IDE at the current working directory.

151 153 

152## Extend Claude Code154## Extend Claude Code

153 155 

154You can extend Claude Code with custom commands, automated workflows, and external integrations.156Connect external services, add reusable workflows, customize Claude's behavior, and configure preview servers.

155 157 

156### Connect external tools158### Connect external tools

157 159 

158For local sessions, click the **...** button before starting and select **Connectors** to add integrations like Google Calendar, Slack, GitHub, Linear, Notion, and more. Connectors must be configured before the session starts and are only available for local sessions. Once connected, Claude can read your calendar, send messages, create issues, and interact with your tools directly. You can ask Claude what connectors are configured in your session.160For local and [SSH](#ssh-sessions) sessions, click the **+** button next to the prompt box and select **Connectors** to add integrations like Google Calendar, Slack, GitHub, Linear, Notion, and more. You can add connectors before or during a session. Connectors are not available for remote sessions.

161 

162To manage or disconnect connectors, go to Settings → Connectors in the desktop app, or select **Manage connectors** from the Connectors menu in the prompt box.

163 

164Once connected, Claude can read your calendar, send messages, create issues, and interact with your tools directly. You can ask Claude what connectors are configured in your session.

159 165 

160Connectors are [MCP (Model Context Protocol) servers](/en/mcp) with built-in setup. You can also [create custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) or add MCP servers manually via [configuration files](/en/mcp#configure-mcp-servers).166Connectors are [MCP servers](/en/mcp) with a graphical setup flow. Use them for quick integration with supported services. For integrations not listed in Connectors, add MCP servers manually via [settings files](/en/mcp#installing-mcp-servers). You can also [create custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

161 167 

162### Create custom skills168### Use skills

163 169 

164[Skills](/en/skills) are reusable prompts that extend Claude's capabilities. For example, you could create a `review` skill that runs your standard code review checklist, or a `deploy` skill that walks through your deployment steps. Skills are defined as markdown files in `.claude/skills/` and can include instructions, context, and even call other tools. Ask Claude what skills are available or to run a specific skill. Claude can also help you create a skill if you describe what you want, or see [skills](/en/skills) to learn how to write them yourself.170[Skills](/en/skills) extend what Claude can do. Claude loads them automatically when relevant, or you can invoke one directly: type `/` in the prompt box or click the **+** button and select **Slash commands** to browse what's available. This includes [built-in commands](/en/interactive-mode#built-in-commands), your [custom skills](/en/skills#create-custom-skills), project skills from your codebase, and skills from any [installed plugins](/en/plugins). Select one and it appears highlighted in the input field. Type your task after it and send as usual.

165 171 

166### Automate workflows with hooks172### Install plugins

167 173 

168[Hooks](/en/hooks) run shell commands automatically in response to Claude Code events. For example, you could run a linter after every file edit, auto-format code, or send notifications when tasks complete. Hooks are configured in your [settings files](/en/settings). See [hooks](/en/hooks) for available events and configuration examples.174[Plugins](/en/plugins) are reusable packages that add skills, agents, hooks, MCP servers, and LSP configurations to Claude Code. You can install plugins from the desktop app without using the terminal.

175 

176For local and [SSH](#ssh-sessions) sessions, click the **+** button next to the prompt box and select **Plugins** to see your installed plugins and their commands. To add a plugin, select **Add plugin** from the submenu to open the plugin browser, which shows available plugins from your configured [marketplaces](/en/plugin-marketplaces) including the official Anthropic marketplace. Select **Manage plugins** to enable, disable, or uninstall plugins.

177 

178Plugins can be scoped to your user account, a specific project, or local-only. Plugins are not available for remote sessions. For the full plugin reference including creating your own plugins, see [plugins](/en/plugins).

179 

180### Configure preview servers

181 

182Claude automatically detects your dev server setup and stores the configuration in `.claude/launch.json` at the root of the folder you selected when starting the session. Preview uses this folder as its working directory, so if you selected a parent folder, subfolders with their own dev servers won't be detected automatically. To work with a subfolder's server, either start a session in that folder directly or add a configuration manually.

183 

184To customize how your server starts, for example to use `yarn dev` instead of `npm run dev` or to change the port, edit the file manually or click **Edit configuration** in the Preview dropdown to open it in your code editor. The file supports JSON with comments.

185 

186```json theme={null}

187{

188 "version": "0.0.1",

189 "configurations": [

190 {

191 "name": "my-app",

192 "runtimeExecutable": "npm",

193 "runtimeArgs": ["run", "dev"],

194 "port": 3000

195 }

196 ]

197}

198```

199 

200You can define multiple configurations to run different servers from the same project, such as a frontend and an API. See the [examples](#examples) below.

201 

202#### Auto-verify changes

203 

204When `autoVerify` is enabled, Claude automatically verifies code changes after editing files. It takes screenshots, checks for errors, and confirms changes work before completing its response.

205 

206Auto-verify is on by default. Disable it per-project by adding `"autoVerify": false` to `.claude/launch.json`, or toggle it from the **Preview** dropdown menu.

207 

208```json theme={null}

209{

210 "version": "0.0.1",

211 "autoVerify": false,

212 "configurations": [...]

213}

214```

215 

216When disabled, preview tools are still available and you can ask Claude to verify at any time. Auto-verify makes it automatic after every edit.

217 

218#### Configuration fields

219 

220Each entry in the `configurations` array accepts the following fields:

221 

222| Field | Type | Description |

223| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

224| `name` | string | A unique identifier for this server |

225| `runtimeExecutable` | string | The command to run, such as `npm`, `yarn`, or `node` |

226| `runtimeArgs` | string\[] | Arguments passed to `runtimeExecutable`, such as `["run", "dev"]` |

227| `port` | number | The port your server listens on. Defaults to 3000 |

228| `cwd` | string | Working directory relative to your project root. Defaults to the project root. Use `${workspaceFolder}` to reference the project root explicitly |

229| `env` | object | Additional environment variables as key-value pairs, such as `{ "NODE_ENV": "development" }`. Don't put secrets here since this file is committed to your repo. Secrets set in your shell profile are inherited automatically. |

230| `autoPort` | boolean | How to handle port conflicts. See below |

231| `program` | string | A script to run with `node`. See [when to use `program` vs `runtimeExecutable`](#when-to-use-program-vs-runtimeexecutable) |

232| `args` | string\[] | Arguments passed to `program`. Only used when `program` is set |

233 

234##### When to use `program` vs `runtimeExecutable`

235 

236Use `runtimeExecutable` with `runtimeArgs` to start a dev server through a package manager. For example, `"runtimeExecutable": "npm"` with `"runtimeArgs": ["run", "dev"]` runs `npm run dev`.

237 

238Use `program` when you have a standalone script you want to run with `node` directly. For example, `"program": "server.js"` runs `node server.js`. Pass additional flags with `args`.

239 

240#### Port conflicts

241 

242The `autoPort` field controls what happens when your preferred port is already in use:

243 

244* **`true`**: Claude finds and uses a free port automatically. Suitable for most dev servers.

245* **`false`**: Claude fails with an error. Use this when your server must use a specific port, such as for OAuth callbacks or CORS allowlists.

246* **Not set (default)**: Claude asks whether the server needs that exact port, then saves your answer.

247 

248When Claude picks a different port, it passes the assigned port to your server via the `PORT` environment variable.

249 

250#### Examples

251 

252These configurations show common setups for different project types:

253 

254<Tabs>

255 <Tab title="Next.js">

256 This configuration runs a Next.js app using Yarn on port 3000:

257 

258 ```json theme={null}

259 {

260 "version": "0.0.1",

261 "configurations": [

262 {

263 "name": "web",