Anthropic - Claude Code Docs Changes 2026-02-04 03:45 UTC → 2026-02-23 21:13 UTC

1> ## Documentation Index

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

4 

5# Orchestrate teams of Claude Code sessions

6 

7> Coordinate multiple Claude Code instances working together as a team, with shared tasks, inter-agent messaging, and centralized management.

8 

9<Warning>

10 Agent teams are experimental and disabled by default. Enable them by adding `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to your [settings.json](/en/settings) or environment. Agent teams have [known limitations](#limitations) around session resumption, task coordination, and shutdown behavior.

11</Warning>

12 

13Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other.

14 

15Unlike [subagents](/en/sub-agents), which run within a single session and can only report back to the main agent, you can also interact with individual teammates directly without going through the lead.

16 

17This page covers:

18 

19* [When to use agent teams](#when-to-use-agent-teams), including best use cases and how they compare with subagents

20* [Starting a team](#start-your-first-agent-team)

21* [Controlling teammates](#control-your-agent-team), including display modes, task assignment, and delegation

22* [Best practices for parallel work](#best-practices)

23 

24## When to use agent teams

25 

26Agent teams are most effective for tasks where parallel exploration adds real value. See [use case examples](#use-case-examples) for full scenarios. The strongest use cases are:

27 

28* **Research and review**: multiple teammates can investigate different aspects of a problem simultaneously, then share and challenge each other's findings

29* **New modules or features**: teammates can each own a separate piece without stepping on each other

30* **Debugging with competing hypotheses**: teammates test different theories in parallel and converge on the answer faster

31* **Cross-layer coordination**: changes that span frontend, backend, and tests, each owned by a different teammate

32 

33Agent teams add coordination overhead and use significantly more tokens than a single session. They work best when teammates can operate independently. For sequential tasks, same-file edits, or work with many dependencies, a single session or [subagents](/en/sub-agents) are more effective.

34 

35### Compare with subagents

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:

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 

45| | Subagents | Agent teams |

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

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

48| **Communication** | Report results back to the main agent only | Teammates message each other directly |

49| **Coordination** | Main agent manages all work | Shared task list with self-coordination |

50| **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |

51| **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance |

52 

53Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.

54 

55## Enable agent teams

56 

57Agent teams are disabled by default. Enable them by setting the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` environment variable to `1`, either in your shell environment or through [settings.json](/en/settings):

58 

59```json settings.json theme={null}

60{

61 "env": {

62 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"

63 }

64}

65```

66 

67## Start your first agent team

68 

69After enabling agent teams, tell Claude to create an agent team and describe the task and the team structure you want in natural language. Claude creates the team, spawns teammates, and coordinates work based on your prompt.

70 

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

72 

73```

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

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

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

77```

78 

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.

80 

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.

82 

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

84 

85## Control your agent team

86 

87Tell the lead what you want in natural language. It handles team coordination, task assignment, and delegation based on your instructions.

88 

89### Choose a display mode

90 

91Agent teams support two display modes:

92 

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.

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.

95 

96<Note>

97 `tmux` has known limitations on certain operating systems and traditionally works best on macOS. Using `tmux -CC` in iTerm2 is the suggested entrypoint into `tmux`.

98</Note>

99 

100The default is `"auto"`, which uses split panes if you're already running inside a tmux session, and in-process otherwise. The `"tmux"` setting enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal. To override, set `teammateMode` in your [settings.json](/en/settings):

101 

102```json theme={null}

103{

104 "teammateMode": "in-process"

105}

106```

107 

108To force in-process mode for a single session, pass it as a flag:

109 

110```bash theme={null}

111claude --teammate-mode in-process

112```

113 

114Split-pane mode requires either [tmux](https://github.com/tmux/tmux/wiki) or iTerm2 with the [`it2` CLI](https://github.com/mkusaka/it2). To install manually:

115 

116* **tmux**: install through your system's package manager. See the [tmux wiki](https://github.com/tmux/tmux/wiki/Installing) for platform-specific instructions.

117* **iTerm2**: install the [`it2` CLI](https://github.com/mkusaka/it2), then enable the Python API in **iTerm2 → Settings → General → Magic → Enable Python API**.

118 

119### Specify teammates and models

120 

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

122 

123```

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

125Use Sonnet for each teammate.

126```

127 

128### Require plan approval for teammates

129 

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:

131 

132```

133Spawn an architect teammate to refactor the authentication module.

134Require plan approval before they make any changes.

135```

136 

137When a teammate finishes planning, it sends a plan approval request to the lead. The lead reviews the plan and either approves it or rejects it with feedback. If rejected, the teammate stays in plan mode, revises based on the feedback, and resubmits. Once approved, the teammate exits plan mode and begins implementation.

138 

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

140 

141### Talk to teammates directly

142 

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.

144 

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.

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.

147 

148### Assign and claim tasks

149 

150The shared task list coordinates work across the team. The lead creates tasks and teammates work through them. Tasks have three states: pending, in progress, and completed. Tasks can also depend on other tasks: a pending task with unresolved dependencies cannot be claimed until those dependencies are completed.

151 

152The lead can assign tasks explicitly, or teammates can self-claim:

153 

154* **Lead assigns**: tell the lead which task to give to which teammate

155* **Self-claim**: after finishing a task, a teammate picks up the next unassigned, unblocked task on its own

156 

157Task claiming uses file locking to prevent race conditions when multiple teammates try to claim the same task simultaneously.

158 

159### Shut down teammates

160 

161To gracefully end a teammate's session:

162 

163```

164Ask the researcher teammate to shut down

165```

166 

167The lead sends a shutdown request. The teammate can approve, exiting gracefully, or reject with an explanation.

168 

169### Clean up the team

170 

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

172 

173```

174Clean up the team

175```

176 

177This removes the shared team resources. When the lead runs cleanup, it checks for active teammates and fails if any are still running, so shut them down first.

178 

179<Warning>

180 Always use the lead to clean up. Teammates should not run cleanup because their team context may not resolve correctly, potentially leaving resources in an inconsistent state.

181</Warning>

182 

183### Enforce quality gates with hooks

184 

185Use [hooks](/en/hooks) to enforce rules when teammates finish work or tasks complete:

186 

187* [`TeammateIdle`](/en/hooks#teammateidle): runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working.

188* [`TaskCompleted`](/en/hooks#taskcompleted): runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback.

189 

190## How agent teams work

191 

192This section covers the architecture and mechanics behind agent teams. If you want to start using them, see [Control your agent team](#control-your-agent-team) above.

193 

194### How Claude starts agent teams

195 

196There are two ways agent teams get started:

197 

198* **You request a team**: give Claude a task that benefits from parallel work and explicitly ask for an agent team. Claude creates one based on your instructions.

199* **Claude proposes a team**: if Claude determines your task would benefit from parallel work, it may suggest creating a team. You confirm before it proceeds.

200 

201In both cases, you stay in control. Claude won't create a team without your approval.

202 

203### Architecture

204 

205An agent team consists of:

206 

207| Component | Role |

208| :------------ | :----------------------------------------------------------------------------------------- |

209| **Team lead** | The main Claude Code session that creates the team, spawns teammates, and coordinates work |

210| **Teammates** | Separate Claude Code instances that each work on assigned tasks |

211| **Task list** | Shared list of work items that teammates claim and complete |

212| **Mailbox** | Messaging system for communication between agents |

213 

214See [Choose a display mode](#choose-a-display-mode) for display configuration options. Teammate messages arrive at the lead automatically.

215 

216The system manages task dependencies automatically. When a teammate completes a task that other tasks depend on, blocked tasks unblock without manual intervention.

217 

218Teams and tasks are stored locally:

219 

220* **Team config**: `~/.claude/teams/{team-name}/config.json`

221* **Task list**: `~/.claude/tasks/{team-name}/`

222 

223The team config contains a `members` array with each teammate's name, agent ID, and agent type. Teammates can read this file to discover other team members.

224 

225### Permissions

226 

227Teammates start with the lead's permission settings. If the lead runs with `--dangerously-skip-permissions`, all teammates do too. After spawning, you can change individual teammate modes, but you can't set per-teammate modes at spawn time.

228 

229### Context and communication

230 

231Each teammate has its own context window. When spawned, a teammate loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills. It also receives the spawn prompt from the lead. The lead's conversation history does not carry over.

232 

233**How teammates share information:**

234 

235* **Automatic message delivery**: when teammates send messages, they're delivered automatically to recipients. The lead doesn't need to poll for updates.

236* **Idle notifications**: when a teammate finishes and stops, they automatically notify the lead.

237* **Shared task list**: all agents can see task status and claim available work.

238 

239**Teammate messaging:**

240 

241* **message**: send a message to one specific teammate

242* **broadcast**: send to all teammates simultaneously. Use sparingly, as costs scale with team size.

243 

244### Token usage

245 

246Agent teams use significantly more tokens than a single session. Each teammate has its own context window, and token usage scales with the number of active teammates. For research, review, and new feature work, the extra tokens are usually worthwhile. For routine tasks, a single session is more cost-effective. See [agent team token costs](/en/costs#agent-team-token-costs) for usage guidance.

247 

248## Use case examples

249 

250These examples show how agent teams handle tasks where parallel exploration adds value.

251 

252### Run a parallel code review

253 

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:

255 

256```

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

258- One focused on security implications

259- One checking performance impact

260- One validating test coverage

261Have them each review and report findings.

262```

263 

264Each reviewer works from the same PR but applies a different filter. The lead synthesizes findings across all three after they finish.

265 

266### Investigate with competing hypotheses

267 

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

269 

270```

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

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

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

274debate. Update the findings doc with whatever consensus emerges.

275```

276 

277The debate structure is the key mechanism here. Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it.

278 

279With multiple independent investigators actively trying to disprove each other, the theory that survives is much more likely to be the actual root cause.

280 

281## Best practices

282 

283### Give teammates enough context

284 

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:

286 

287```

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

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

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

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

292```

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 

308### Size tasks appropriately

309 

310* **Too small**: coordination overhead exceeds the benefit

311* **Too large**: teammates work too long without check-ins, increasing risk of wasted effort

312* **Just right**: self-contained units that produce a clear deliverable, such as a function, a test file, or a review

313 

314<Tip>

315 The lead breaks work into tasks and assigns them to teammates automatically. If it isn't creating enough tasks, ask it to split the work into smaller pieces. Having 5-6 tasks per teammate keeps everyone productive and lets the lead reassign work if someone gets stuck.

316</Tip>

317 

318### Wait for teammates to finish

319 

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

321 

322```

323Wait for your teammates to complete their tasks before proceeding

324```

325 

326### Start with research and review

327 

328If you're new to agent teams, start with tasks that have clear boundaries and don't require writing code: reviewing a PR, researching a library, or investigating a bug. These tasks show the value of parallel exploration without the coordination challenges that come with parallel implementation.

329 

330### Avoid file conflicts

331 

332Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files.

333 

334### Monitor and steer

335 

336Check in on teammates' progress, redirect approaches that aren't working, and synthesize findings as they come in. Letting a team run unattended for too long increases the risk of wasted effort.

337 

338## Troubleshooting

339 

340### Teammates not appearing

341 

342If teammates aren't appearing after you ask Claude to create a team:

343 

344* In in-process mode, teammates may already be running but not visible. Press Shift+Down to cycle through active teammates.

345* Check that the task you gave Claude was complex enough to warrant a team. Claude decides whether to spawn teammates based on the task.

346* If you explicitly requested split panes, ensure tmux is installed and available in your PATH:

347 ```bash theme={null}

348 which tmux

349 ```

350* For iTerm2, verify the `it2` CLI is installed and the Python API is enabled in iTerm2 preferences.

351 

352### Too many permission prompts

353 

354Teammate permission requests bubble up to the lead, which can create friction. Pre-approve common operations in your [permission settings](/en/permissions) before spawning teammates to reduce interruptions.

355 

356### Teammates stopping on errors

357 

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:

359 

360* Give them additional instructions directly

361* Spawn a replacement teammate to continue the work

362 

363### Lead shuts down before work is done

364 

365The lead may decide the team is finished before all tasks are actually complete. If this happens, tell it to keep going. You can also tell the lead to wait for teammates to finish before proceeding if it starts doing work instead of delegating.

366 

367### Orphaned tmux sessions

368 

369If a tmux session persists after the team ends, it may not have been fully cleaned up. List sessions and kill the one created by the team:

370 

371```bash theme={null}

372tmux ls

373tmux kill-session -t <session-name>

374```

375 

376## Limitations

377 

378Agent teams are experimental. Current limitations to be aware of:

379 

380* **No session resumption with in-process teammates**: `/resume` and `/rewind` do not restore in-process teammates. After resuming a session, the lead may attempt to message teammates that no longer exist. If this happens, tell the lead to spawn new teammates.

381* **Task status can lag**: teammates sometimes fail to mark tasks as completed, which blocks dependent tasks. If a task appears stuck, check whether the work is actually done and update the task status manually or tell the lead to nudge the teammate.

382* **Shutdown can be slow**: teammates finish their current request or tool call before shutting down, which can take time.

383* **One team per session**: a lead can only manage one team at a time. Clean up the current team before starting a new one.

384* **No nested teams**: teammates cannot spawn their own teams or teammates. Only the lead can manage the team.

385* **Lead is fixed**: the session that creates the team is the lead for its lifetime. You can't promote a teammate to lead or transfer leadership.

386* **Permissions set at spawn**: all teammates start with the lead's permission mode. You can change individual teammate modes after spawning, but you can't set per-teammate modes at spawn time.

387* **Split panes require tmux or iTerm2**: the default in-process mode works in any terminal. Split-pane mode isn't supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.

388 

389<Tip>

390 **`CLAUDE.md` works normally**: teammates read `CLAUDE.md` files from their working directory. Use this to provide project-specific guidance to all teammates.

391</Tip>

392 

393## Next steps

394 

395Explore related approaches for parallel work and delegation:

396 

397* **Lightweight delegation**: [subagents](/en/sub-agents) spawn helper agents for research or verification within your session, better for tasks that don't need inter-agent coordination

398* **Manual parallel sessions**: [Git worktrees](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) let you run multiple Claude Code sessions yourself without automated team coordination

399* **Compare approaches**: see the [subagent vs agent team](/en/features-overview#compare-similar-features) comparison for a side-by-side breakdown

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:

124 134 

125Claude Code uses these default models for Bedrock: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.

142 

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

149 163 

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

151 165 

152### 5. Output token configuration

153 

154These are the recommended token settings for Claude Code with Amazon Bedrock:

155 

156```bash theme={null}

157# Recommended output token settings for Bedrock

158export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096

159export MAX_THINKING_TOKENS=1024

160```

161 

162**Why these values:**

163 

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

165 

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

167 

168## IAM configuration166## IAM configuration

169 167 

170Create an IAM policy with the required permissions for Claude Code:168Create an IAM policy with the required permissions for Claude Code:

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

211 209 

212<Note>210<Note>

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

214</Note>212</Note>

215 213 

216## AWS Guardrails214## AWS Guardrails

34 34 

35You need the Owner role to configure analytics settings. A GitHub admin must install the GitHub app.35You need the Owner role to configure analytics settings. A GitHub admin must install the GitHub app.

36 36 

37<Warning>

38 Contribution metrics are not available for organizations with [Zero Data Retention](/en/data-usage#data-retention) enabled. The analytics dashboard will show usage metrics only.

39</Warning>

40 

37<Steps>41<Steps>

38 <Step title="Install the GitHub app">42 <Step title="Install the GitHub app">

39 A GitHub admin installs the Claude GitHub app on your organization's GitHub account at [github.com/apps/claude](https://github.com/apps/claude).43 A GitHub admin installs the Claude GitHub app on your organization's GitHub account at [github.com/apps/claude](https://github.com/apps/claude).

20 20 

21Claude's context window holds your entire conversation, including every message, every file Claude reads, and every command output. However, this can fill up fast. A single debugging session or codebase exploration might generate and consume tens of thousands of tokens.21Claude's context window holds your entire conversation, including every message, every file Claude reads, and every command output. However, this can fill up fast. A single debugging session or codebase exploration might generate and consume tens of thousands of tokens.

22 22 

23This matters since LLM performance degrades as context fills. When the context window is getting full, Claude may start "forgetting" earlier instructions or making more mistakes. The context window is the most important resource to manage. For detailed strategies on reducing token usage, see [Reduce token usage](/en/costs#reduce-token-usage).23This matters since LLM performance degrades as context fills. When the context window is getting full, Claude may start "forgetting" earlier instructions or making more mistakes. The context window is the most important resource to manage. Track context usage continuously with a [custom status line](/en/statusline), and see [Reduce token usage](/en/costs#reduce-token-usage) for strategies on reducing token usage.

24 24 

25***25***

26 26 

40| **Verify UI changes visually** | *"make the dashboard look better"* | *"\[paste screenshot] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them"* |40| **Verify UI changes visually** | *"make the dashboard look better"* | *"\[paste screenshot] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them"* |

41| **Address root causes, not symptoms** | *"the build is failing"* | *"the build fails with this error: \[paste error]. fix it and verify the build succeeds. address the root cause, don't suppress the error"* |41| **Address root causes, not symptoms** | *"the build is failing"* | *"the build fails with this error: \[paste error]. fix it and verify the build succeeds. address the root cause, don't suppress the error"* |

42 42 

43UI changes can be verified using the [Claude in Chrome extension](/en/chrome). It opens a browser, tests the UI, and iterates until the code works.43UI changes can be verified using the [Claude in Chrome extension](/en/chrome). It opens new tabs in your browser, tests the UI, and iterates until the code works.

44 44 

45Your verification can also be a test suite, a linter, or a Bash command that checks output. Invest in making your verification rock-solid.45Your verification can also be a test suite, a linter, or a Bash command that checks output. Invest in making your verification rock-solid.

46 46 

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

400* Use `/clear` frequently between tasks to reset the context window entirely400* Use `/clear` frequently between tasks to reset the context window entirely

401* When auto compaction triggers, Claude summarizes what matters most, including code patterns, file states, and key decisions401* When auto compaction triggers, Claude summarizes what matters most, including code patterns, file states, and key decisions

402* For more control, run `/compact <instructions>`, like `/compact Focus on the API changes`402* For more control, run `/compact <instructions>`, like `/compact Focus on the API changes`

403* To compact only part of the conversation, use `Esc + Esc` or `/rewind`, select a message checkpoint, and choose **Summarize from here**. This condenses messages from that point forward while keeping earlier context intact.

403* Customize compaction behavior in CLAUDE.md with instructions like `"When compacting, always preserve the full list of modified files and any test commands"` to ensure critical context survives summarization404* Customize compaction behavior in CLAUDE.md with instructions like `"When compacting, always preserve the full list of modified files and any test commands"` to ensure critical context survives summarization

404 405 

405### Use subagents for investigation406### Use subagents for investigation

429 Every action Claude makes creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint.430 Every action Claude makes creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint.

430</Tip>431</Tip>

431 432 

432Claude automatically checkpoints before changes. Double-tap `Escape` or run `/rewind` to open the checkpoint menu. You can restore conversation only (keep code changes), restore code only (keep conversation), or restore both.433Claude automatically checkpoints before changes. Double-tap `Escape` or run `/rewind` to open the rewind menu. You can restore conversation only, restore code only, restore both, or summarize from a selected message. See [Checkpointing](/en/checkpointing) for details.

433 434 

434Instead of carefully planning every move, you can tell Claude to try something risky. If it doesn't work, rewind and try a different approach. Checkpoints persist across sessions, so you can close your terminal and still rewind later.435Instead of carefully planning every move, you can tell Claude to try something risky. If it doesn't work, rewind and try a different approach. Checkpoints persist across sessions, so you can close your terminal and still rewind later.

435 436 

485 Run multiple Claude sessions in parallel to speed up development, run isolated experiments, or start complex workflows.486 Run multiple Claude sessions in parallel to speed up development, run isolated experiments, or start complex workflows.

486</Tip>487</Tip>

487 488 

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

489 490 

490* [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.

491* [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.

492 494 

493Beyond parallelizing work, multiple sessions enable quality-focused workflows. A fresh context improves code review since Claude won't be biased toward code it just wrote.495Beyond parallelizing work, multiple sessions enable quality-focused workflows. A fresh context improves code review since Claude won't be biased toward code it just wrote.

494 496 

4 4 

5# Checkpointing5# Checkpointing

6 6 

7> Automatically track and rewind Claude's edits to quickly recover from unwanted changes.7> Track, rewind, and summarize Claude's edits and conversation to manage session state.

8 8 

9Claude Code automatically tracks Claude's file edits as you work, allowing you to quickly undo changes and rewind to previous states if anything gets off track.9Claude Code automatically tracks Claude's file edits as you work, allowing you to quickly undo changes and rewind to previous states if anything gets off track.

10 10 

20* Checkpoints persist across sessions, so you can access them in resumed conversations20* Checkpoints persist across sessions, so you can access them in resumed conversations

21* Automatically cleaned up along with sessions after 30 days (configurable)21* Automatically cleaned up along with sessions after 30 days (configurable)

22 22 

23### Rewinding changes23### Rewind and summarize

24 24 

25Press `Esc` twice (`Esc` + `Esc`) or use the `/rewind` command to open up the rewind menu. You can choose to restore:25Press `Esc` twice (`Esc` + `Esc`) or use the `/rewind` command to open the rewind menu. A scrollable list shows each of your prompts from the session. Select the point you want to act on, then choose an action:

26 26 

27* **Conversation only**: Rewind to a user message while keeping code changes27* **Restore code and conversation**: revert both code and conversation to that point

28* **Code only**: Revert file changes while keeping the conversation28* **Restore conversation**: rewind to that message while keeping current code

29* **Both code and conversation**: Restore both to a prior point in the session29* **Restore code**: revert file changes while keeping the conversation

30* **Summarize from here**: compress the conversation from this point forward into a summary, freeing context window space

31* **Never mind**: return to the message list without making changes

32 

33After restoring the conversation or summarizing, the original prompt from the selected message is restored into the input field so you can re-send or edit it.

34 

35#### Restore vs. summarize

36 

37The three restore options revert state: they undo code changes, conversation history, or both. "Summarize from here" works differently:

38 

39* Messages before the selected message stay intact

40* The selected message and all subsequent messages get replaced with a compact AI-generated summary

41* No files on disk are changed

42* The original messages are preserved in the session transcript, so Claude can reference the details if needed

43 

44This is similar to `/compact`, but targeted: instead of summarizing the entire conversation, you keep early context in full detail and only compress the parts that are using up space. You can type optional instructions to guide what the summary focuses on.

45 

46<Note>

47 Summarize keeps you in the same session and compresses context. If you want to branch off and try a different approach while preserving the original session intact, use [fork](/en/how-claude-code-works#resume-or-fork-sessions) instead (`claude --continue --fork-session`).

48</Note>

30 49 

31## Common use cases50## Common use cases

32 51 

33Checkpoints are particularly useful when:52Checkpoints are particularly useful when:

34 53 

35* **Exploring alternatives**: Try different implementation approaches without losing your starting point54* **Exploring alternatives**: try different implementation approaches without losing your starting point

36* **Recovering from mistakes**: Quickly undo changes that introduced bugs or broke functionality55* **Recovering from mistakes**: quickly undo changes that introduced bugs or broke functionality

37* **Iterating on features**: Experiment with variations knowing you can revert to working states56* **Iterating on features**: experiment with variations knowing you can revert to working states

57* **Freeing context space**: summarize a verbose debugging session from the midpoint forward, keeping your initial instructions intact

38 58 

39## Limitations59## Limitations

40 60 

4 4 

5# Use Claude Code with Chrome (beta)5# Use Claude Code with Chrome (beta)

6 6 

7> Connect Claude Code to your browser to test web apps, debug with console logs, and automate browser tasks.7> Connect Claude Code to your Chrome browser to test web apps, debug with console logs, automate form filling, and extract data from web pages.

8 8 

9<Note>9Claude Code integrates with the Claude in Chrome browser extension to give you browser automation capabilities from the CLI or the [VS Code extension](/en/vs-code#automate-browser-tasks-with-chrome). Build your code, then test and debug in the browser without switching contexts.

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

11</Note>

12 10 

13Claude Code integrates with the Claude in Chrome browser extension to give you browser automation capabilities directly from your terminal. Build in your terminal, then test and debug in your browser without switching contexts.11Claude opens new tabs for browser tasks and shares your browser's login state, so it can access any site you're already signed into. Browser actions run in a visible Chrome window in real time. When Claude encounters a login page or CAPTCHA, it pauses and asks you to handle it manually.

14 12 

15## What the integration enables13<Note>

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

15</Note>

16 16 

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

18 18 

19Key capabilities include:19With Chrome connected, you can chain browser actions with coding tasks in a single workflow:

20 20 

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

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

23* **Web app testing**: Test form validation, check for visual regressions, or verify user flows work correctly23* **Web app testing**: test form validation, check for visual regressions, or verify user flows

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

25* **Data extraction**: Pull structured information from web pages and save it locally25* **Data extraction**: pull structured information from web pages and save it locally

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

27* **Session recording**: Record browser interactions as GIFs to document or share what happened27* **Session recording**: record browser interactions as GIFs to document or share what happened

28 28 

29## Prerequisites29## Prerequisites

30 30 

31Before using Claude Code with Chrome, you need:31Before using Claude Code with Chrome, you need:

32 32 

33* [Google Chrome](https://www.google.com/chrome/) 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 higher34* [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 CLI](/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 paid Claude plan (Pro, Team, or Enterprise)36* A direct Anthropic plan (Pro, Max, Teams, or Enterprise)

37 

38## How the integration works

39 

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

41 

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

43 

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

45 37 

46<Note>38<Note>

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

48</Note>40</Note>

49 41 

50## Set up the integration42## Get started in the CLI

51 43 

52<Steps>44<Steps>

53 <Step title="Update Claude Code">45 <Step title="Launch Claude Code with Chrome">

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

55 47 

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

57 claude update49 claude --chrome

58 ```50 ```

51 

52 You can also enable Chrome from within an existing session by running `/chrome`.

59 </Step>53 </Step>

60 54 

61 <Step title="Start Claude Code with Chrome enabled">55 <Step title="Ask Claude to use the browser">

62 Launch Claude Code with the `--chrome` flag:56 This example navigates to a page, interacts with it, and reports what it finds, all from your terminal or editor:

63 57 

64 ```bash theme={null}58 ```text theme={null}

65 claude --chrome59 Go to code.claude.com/docs, click on the search box,

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

66 ```61 ```

67 </Step>62 </Step>

68 

69 <Step title="Verify the connection">

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

71 </Step>

72</Steps>63</Steps>

73 64 

74You can also enable Chrome integration from within an existing session using the `/chrome` command.65Run `/chrome` at any time to check the connection status, manage permissions, or reconnect the extension.

75 66 

76## Try it out67For VS Code, see [browser automation in VS Code](/en/vs-code#automate-browser-tasks-with-chrome).

77 68 

78Once connected, type this into Claude to see the integration in action:69### Enable Chrome by default

79 70 

80```71To avoid passing `--chrome` each session, run `/chrome` and select "Enabled by default".

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

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

83```

84 72 

85Claude opens the page, clicks into the search field, types the query, and reports the autocomplete results. This shows navigation, clicking, and typing in a single workflow.73In the [VS Code extension](/en/vs-code#automate-browser-tasks-with-chrome), Chrome is available whenever the Chrome extension is installed. No additional flag is needed.

86 74 

87## Example workflows75<Note>

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

77</Note>

78 

79### Manage site permissions

80 

81Site-level permissions are inherited from the Chrome extension. Manage permissions in the Chrome extension settings to control which sites Claude can browse, click, and type on.

88 82 

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

90 84 

91The following examples show common patterns for browser automation.85These examples show common ways to combine browser actions with coding tasks. Run `/mcp` and select `claude-in-chrome` to see the full list of available browser tools.

92 86 

93### Test a local web application87### Test a local web application

94 88 

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

96 90 

97```91```text theme={null}

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

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

100messages appear correctly?94messages appear correctly?

104 98 

105### Debug with console logs99### Debug with console logs

106 100 

107If your app has issues, Claude can read console output to help diagnose problems:101Claude can read console output to help diagnose problems. Tell Claude what patterns to look for rather than asking for all console output, since logs can be verbose:

108 102 

109```103```text theme={null}

110Open the dashboard page and check the console for any errors when104Open the dashboard page and check the console for any errors when

111the page loads.105the page loads.

112```106```

117 111 

118Speed up repetitive data entry tasks:112Speed up repetitive data entry tasks:

119 113 

120```114```text theme={null}

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

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

123name, email, and phone fields.117name, email, and phone fields.

124```118```

125 119 

129 123 

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

131 125 

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

133Draft a project update based on our recent commits and add it to my127Draft a project update based on the recent commits and add it to my

134Google Doc at docs.google.com/document/d/abc123128Google Doc at docs.google.com/document/d/abc123

135```129```

136 130 

140 134 

141Pull structured information from websites:135Pull structured information from websites:

142 136 

143```137```text theme={null}

144Go to the product listings page and extract the name, price, and138Go to the product listings page and extract the name, price, and

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

146```140```

151 145 

152Coordinate tasks across multiple websites:146Coordinate tasks across multiple websites:

153 147 

154```148```text theme={null}

155Check my calendar for meetings tomorrow, then for each meeting with149Check my calendar for meetings tomorrow, then for each meeting with

156an external attendee, look up their company on LinkedIn and add a150an external attendee, look up their company website and add a note

157note about what they do.151about what they do.

158```152```

159 153 

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

163 157 

164Create shareable recordings of browser interactions:158Create shareable recordings of browser interactions:

165 159 

166```160```text theme={null}

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

168an item to the cart through to the confirmation page.162an item to the cart through to the confirmation page.

169```163```

170 164 

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

172 166 

173## Best practices

174 

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

176 

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

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

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

180 

181## Troubleshooting167## Troubleshooting

182 168 

183### Extension not detected169### Extension not detected

184 170 

185If Claude Code shows "Chrome extension not detected":171If Claude Code shows "Chrome extension not detected":

186 172 

1871. Verify the Chrome extension (version 1.0.36 or higher) is installed1731. Verify the Chrome extension is installed and enabled in `chrome://extensions`

1882. Verify Claude Code is version 2.0.73 or higher by running `claude --version`1742. Verify Claude Code is up to date by running `claude --version`

1893. Check that Chrome is running1753. Check that Chrome is running

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

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

192 178 

179The first time you enable Chrome integration, Claude Code installs a native messaging host configuration file. Chrome reads this file on startup, so if the extension isn't detected on your first attempt, restart Chrome to pick up the new configuration.

180 

181If the connection still fails, verify the host configuration file exists at:

182 

183For Chrome:

184 

185* **macOS**: `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`

186* **Linux**: `~/.config/google-chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`

187* **Windows**: check `HKCU\Software\Google\Chrome\NativeMessagingHosts\` in the Windows Registry

188 

189For Edge:

190 

191* **macOS**: `~/Library/Application Support/Microsoft Edge/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`

192* **Linux**: `~/.config/microsoft-edge/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`

193* **Windows**: check `HKCU\Software\Microsoft\Edge\NativeMessagingHosts\` in the Windows Registry

194 

193### Browser not responding195### Browser not responding

194 196 

195If Claude's browser commands stop working:197If Claude's browser commands stop working:

196 198 

1971. Check if a modal dialog (alert, confirm, prompt) is blocking the page1991. Check if a modal dialog (alert, confirm, prompt) is blocking the page. JavaScript dialogs block browser events and prevent Claude from receiving commands. Dismiss the dialog manually, then tell Claude to continue.

1982. Ask Claude to create a new tab and try again2002. Ask Claude to create a new tab and try again

1993. Restart the Chrome extension by disabling and re-enabling it2013. Restart the Chrome extension by disabling and re-enabling it in `chrome://extensions`

200 202 

201### First-time setup203### Connection drops during long sessions

202 204 

203The first time you use the integration, Claude Code installs a native messaging host that allows communication between the CLI and Chrome. If you encounter permission errors, you may need to restart Chrome for the installation to take effect.205The Chrome extension's service worker can go idle during extended sessions, which breaks the connection. If browser tools stop working after a period of inactivity, run `/chrome` and select "Reconnect extension".

204 206 

205## Enable by default207### Windows-specific issues

206 208 

207Chrome integration requires the `--chrome` flag each time you start Claude Code. To enable it by default, run `/chrome` and select "Enabled by default".209On Windows, you may encounter:

208 210 

209<Note>211* **Named pipe conflicts (EADDRINUSE)**: if another process is using the same named pipe, restart Claude Code. Close any other Claude Code sessions that might be using Chrome.

210 Enabling Chrome by default increases context usage since browser tools are always loaded. If you notice increased context consumption, disable this setting and use `--chrome` only when needed.212* **Native messaging host errors**: if the native messaging host crashes on startup, try reinstalling Claude Code to regenerate the host configuration.

211</Note>213 

214### Common error messages

215 

216These are the most frequently encountered errors and how to resolve them:

212 217 

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

219| ------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------- |

220| "Browser extension is not connected" | Native messaging host cannot reach the extension | Restart Chrome and Claude Code, then run `/chrome` to reconnect |

221| "Extension not detected" | Chrome extension is not installed or is disabled | Install or enable the extension in `chrome://extensions` |

222| "No tab available" | Claude tried to act before a tab was ready | Ask Claude to create a new tab and retry |

223| "Receiving end does not exist" | Extension service worker went idle | Run `/chrome` and select "Reconnect extension" |

214 224 

215## See also225## See also

216 226 

217* [CLI reference](/en/cli-reference) - Command-line flags including `--chrome`227* [Use Claude Code in VS Code](/en/vs-code#automate-browser-tasks-with-chrome): browser automation in the VS Code extension

218* [Common workflows](/en/common-workflows) - More ways to use Claude Code228* [CLI reference](/en/cli-reference): command-line flags including `--chrome`

219* [Getting started with Claude for Chrome](https://support.anthropic.com/en/articles/12012173-getting-started-with-claude-for-chrome) - Full documentation for the Chrome extension, including shortcuts, scheduling, and permissions229* [Common workflows](/en/common-workflows): more ways to use Claude Code

230* [Data and privacy](/en/data-usage): how Claude Code handles your data

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

30 30 

31* **Pro users**31* **Pro users**

32* **Max users**32* **Max users**

33* **Team premium seat users**33* **Team users**

34* **Enterprise premium seat users**34* **Enterprise users** with premium seats or Chat + Claude Code seats

35 35 

36## Getting started36## Getting started

37 37 

245 245 

246### Dependency management246### Dependency management

247 247 

248Configure automatic dependency installation using [SessionStart hooks](/en/hooks#sessionstart). This can be configured in your repository's `.claude/settings.json` file:248Custom environment images and snapshots are not yet supported. As a workaround, you can use [SessionStart hooks](/en/hooks#sessionstart) to install packages when a session starts. This approach has [known limitations](#dependency-management-limitations).

249 

250To configure automatic dependency installation, add a SessionStart hook to your repository's `.claude/settings.json` file:

249 251 

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

251{253{

269 271 

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

271#!/bin/bash273#!/bin/bash

272npm install

273pip install -r requirements.txt

274exit 0

275```

276 

277Make it executable: `chmod +x scripts/install_pkgs.sh`

278 

279#### Local vs remote execution

280 

281By default, all hooks execute both locally and in remote (web) environments. To run a hook only in one environment, check the `CLAUDE_CODE_REMOTE` environment variable in your hook script.

282 274 

283```bash theme={null}275# Only run in remote environments

284#!/bin/bash

285 

286# Example: Only run in remote environments

287if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then276if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then

288 exit 0277 exit 0

289fi278fi

290 279 

291npm install280npm install

292pip install -r requirements.txt281pip install -r requirements.txt

282exit 0

293```283```

294 284 

295#### Persisting environment variables285Make it executable: `chmod +x scripts/install_pkgs.sh`

286 

287#### Persist environment variables

288 

289SessionStart hooks can persist environment variables for subsequent Bash commands by writing to the file specified in the `CLAUDE_ENV_FILE` environment variable. For details, see [SessionStart hooks](/en/hooks#sessionstart) in the hooks reference.

290 

291#### Dependency management limitations

296 292 

297SessionStart hooks can persist environment variables for subsequent bash commands by writing to the file specified in the `CLAUDE_ENV_FILE` environment variable. For details, see [SessionStart hooks](/en/hooks#sessionstart) in the hooks reference.293* **Hooks fire for all sessions**: SessionStart hooks run in both local and remote environments. There is no hook configuration to scope a hook to remote sessions only. To skip local execution, check the `CLAUDE_CODE_REMOTE` environment variable in your script as shown above.

294* **Requires network access**: Install commands need network access to reach package registries. If your environment is configured with "No internet" access, these hooks will fail. Use "Limited" (the default) or "Full" network access. The [default allowlist](#default-allowed-domains) includes common registries like npm, PyPI, RubyGems, and crates.io.

295* **Proxy compatibility**: All outbound traffic in remote environments passes through a [security proxy](#security-proxy). Some package managers do not work correctly with this proxy. Bun is a known example.

296* **Runs on every session start**: Hooks run each time a session starts or resumes, adding startup latency. Keep install scripts fast by checking whether dependencies are already present before reinstalling.

298 297 

299## Network access and security298## Network access and security

300 299 

9## CLI commands9## CLI commands

10 10 

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

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

13| `claude` | Start interactive REPL | `claude` |13| `claude` | Start interactive REPL | `claude` |

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

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

18| `claude -c -p "query"` | Continue via SDK | `claude -c -p "Check for type errors"` |18| `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"` |19| `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` |20| `claude update` | Update to latest version | `claude update` |

21| `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). |22| `claude mcp` | Configure Model Context Protocol (MCP) servers | See the [Claude Code MCP documentation](/en/mcp). |

22 23 

23## CLI flags24## CLI flags

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"` |54| `--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"` |55| `--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` |56| `--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` |57| `--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` |58| `--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"` |59| `--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` |60| `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |

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

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

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

74| `--teammate-mode` | Set how [agent team](/en/agent-teams) teammates display: `auto` (default), `in-process`, or `tmux`. See [set up agent teams](/en/agent-teams#set-up-agent-teams) | `claude --teammate-mode in-process` |

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

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

75| `--version`, `-v` | Output the version number | `claude -v` |77| `--version`, `-v` | Output the version number | `claude -v` |

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

76 79 

77<Tip>80<Tip>

78 The `--output-format json` flag is particularly useful for scripting and81 The `--output-format json` flag is particularly useful for scripting and

84The `--agents` flag accepts a JSON object that defines one or more custom subagents. Each subagent requires a unique name (as the key) and a definition object with the following fields:87The `--agents` flag accepts a JSON object that defines one or more custom subagents. Each subagent requires a unique name (as the key) and a definition object with the following fields:

85 88 

86| Field | Required | Description |89| Field | Required | Description |

87| :------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------- |90| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

90| `tools` | No | Array of specific tools the subagent can use (for example, `["Read", "Edit", "Bash"]`). If omitted, inherits all tools |93| `tools` | No | Array of specific tools the subagent can use, for example `["Read", "Edit", "Bash"]`. If omitted, inherits all tools. Supports [`Task(agent_type)`](/en/sub-agents#restrict-which-subagents-can-be-spawned) syntax |

91| `model` | No | Model alias to use: `sonnet`, `opus`, `haiku`, or `inherit`. If omitted, defaults to `inherit` (uses the main conversation's model) |94| `disallowedTools` | No | Array of tool names to explicitly deny for this subagent |

95| `model` | No | Model alias to use: `sonnet`, `opus`, `haiku`, or `inherit`. If omitted, defaults to `inherit` |

96| `skills` | No | Array of [skill](/en/skills) names to preload into the subagent's context |

97| `mcpServers` | No | Array of [MCP servers](/en/mcp) for this subagent. Each entry is a server name string or a `{name: config}` object |

98| `maxTurns` | No | Maximum number of agentic turns before the subagent stops |

92 99 

93Example:100Example:

94 101 

509 509 

510## Use extended thinking (thinking mode)510## Use extended thinking (thinking mode)

511 511 

512[Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) is enabled by default, reserving a portion of the output token budget (up to 31,999 tokens) for Claude to reason through complex problems step-by-step. This reasoning is visible in verbose mode, which you can toggle on with `Ctrl+O`.512[Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) is enabled by default, giving Claude space to reason through complex problems step-by-step before responding. This reasoning is visible in verbose mode, which you can toggle on with `Ctrl+O`.

513 513 

514Extended thinking is particularly valuable for complex architectural decisions, challenging bugs, multi-step implementation planning, and evaluating tradeoffs between different approaches. It provides more space for exploring multiple solutions, analyzing edge cases, and self-correcting mistakes.514Additionally, Opus 4.6 introduces adaptive reasoning: instead of a fixed thinking token budget, the model dynamically allocates thinking based on your [effort level](/en/model-config#adjust-effort-level) setting. Extended thinking and adaptive reasoning work together to give you control over how deeply Claude reasons before responding.

515 

516Extended thinking is particularly valuable for complex architectural decisions, challenging bugs, multi-step implementation planning, and evaluating tradeoffs between different approaches.

515 517 

516<Note>518<Note>

517 Phrases like "think", "think hard", "ultrathink", and "think more" are interpreted as regular prompt instructions and don't allocate thinking tokens.519 Phrases like "think", "think hard", "ultrathink", and "think more" are interpreted as regular prompt instructions and don't allocate thinking tokens.

522Thinking is enabled by default, but you can adjust or disable it.524Thinking is enabled by default, but you can adjust or disable it.

523 525 

524| Scope | How to configure | Details |526| Scope | How to configure | Details |

525| ---------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |527| ---------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |

526| **Toggle shortcut** | Press `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle thinking on/off for the current session. May require [terminal configuration](/en/terminal-config) to enable Option key shortcuts |528| **Effort level** | Adjust in `/model` or set [`CLAUDE_CODE_EFFORT_LEVEL`](/en/settings#environment-variables) | Control thinking depth for Opus 4.6: low, medium, high (default). See [Adjust effort level](/en/model-config#adjust-effort-level) |

527| **Global default** | Use `/config` to toggle thinking mode | Sets your default across all projects.<br />Saved as `alwaysThinkingEnabled` in `~/.claude/settings.json` |529| **Toggle shortcut** | Press `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle thinking on/off for the current session (all models). May require [terminal configuration](/en/terminal-config) to enable Option key shortcuts |

528| **Limit token budget** | Set [`MAX_THINKING_TOKENS`](/en/settings#environment-variables) environment variable | Limit the thinking budget to a specific number of tokens. Example: `export MAX_THINKING_TOKENS=10000` |530| **Global default** | Use `/config` to toggle thinking mode | Sets your default across all projects (all models).<br />Saved as `alwaysThinkingEnabled` in `~/.claude/settings.json` |

531| **Limit token budget** | Set [`MAX_THINKING_TOKENS`](/en/settings#environment-variables) environment variable | Limit the thinking budget to a specific number of tokens (ignored on Opus 4.6 unless set to 0). Example: `export MAX_THINKING_TOKENS=10000` |

529 532 

530To view Claude's thinking process, press `Ctrl+O` to toggle verbose mode and see the internal reasoning displayed as gray italic text.533To view Claude's thinking process, press `Ctrl+O` to toggle verbose mode and see the internal reasoning displayed as gray italic text.

531 534 

532### How extended thinking token budgets work535### How extended thinking works

533 

534Extended thinking uses a **token budget** that controls how much internal reasoning Claude can perform before responding.

535 

536A larger thinking token budget provides:

537 

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

539* Room to analyze edge cases and evaluate tradeoffs thoroughly

540* Ability to revise reasoning and self-correct mistakes

541 536 

542Token budgets for thinking mode:537Extended thinking controls how much internal reasoning Claude performs before responding. More thinking provides more space to explore solutions, analyze edge cases, and self-correct mistakes.

543 538 

544* When thinking is **enabled**, Claude can use up to **31,999 tokens** from your output budget for internal reasoning539**With Opus 4.6**, thinking uses adaptive reasoning: the model dynamically allocates thinking tokens based on the [effort level](/en/model-config#adjust-effort-level) you select (low, medium, high). This is the recommended way to tune the tradeoff between speed and reasoning depth.

545* When thinking is **disabled** (via toggle or `/config`), Claude uses **0 tokens** for thinking

546 540 

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

548 542 

549* Use the [`MAX_THINKING_TOKENS` environment variable](/en/settings#environment-variables) to cap the thinking budget543`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.

550* When set, this value limits the maximum tokens Claude can use for thinking

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

552 544 

553<Warning>545<Warning>

554 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

650 642 

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

652 644 

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

654 722 

655<Steps>723<Steps>

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

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

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

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

660 more in the [official Git worktree

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

662 </Step>726 </Step>

663 727 

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

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

666 # Create a new worktree with a new branch

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

668 

669 # Or create a worktree with an existing branch

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

671 ```

672 730 

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

674 </Step>737 </Step>

675 738 

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

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

678 # Navigate to your worktree 741 

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

680 745 

681 # Run Claude Code in this isolated environment

682 claude

683 ```746 ```

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

685 753 

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

687 ```bash theme={null}

688 cd ../project-bugfix

689 claude

690 ```754 ```

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

756 ```

757 </Tab>

692 758 

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

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

695 # List all worktrees

696 git worktree list

697 761 

698 # Remove a worktree when done

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

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

701 </Step>767 </Step>

702</Steps>

703 768 

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

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

771 </Step>

772</Steps>

706 773 

707 * Each worktree has its own independent file state, making it perfect for parallel Claude Code sessions774For 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).

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

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

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

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

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

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

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

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

716</Tip>

717 775 

718***776***

719 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 

37 When you first authenticate Claude Code with your Claude Console account, a workspace called "Claude Code" is automatically created for you. This workspace provides centralized cost tracking and management for all Claude Code usage in your organization. You cannot create API keys for this workspace; it is exclusively for Claude Code authentication and usage.37 When you first authenticate Claude Code with your Claude Console account, a workspace called "Claude Code" is automatically created for you. This workspace provides centralized cost tracking and management for all Claude Code usage in your organization. You cannot create API keys for this workspace; it is exclusively for Claude Code authentication and usage.

38</Note>38</Note>

39 39 

40On Bedrock, Vertex, and Foundry, Claude Code does not send metrics from your cloud. To get cost metrics, several large enterprises reported using [LiteLLM](/en/llm-gateway#litellm-configuration), which is an open-source tool that helps companies [track spend by key](https://docs.litellm.ai/docs/proxy/virtual_keys#tracking-spend). This project is unaffiliated with Anthropic and we have not audited its security.40On Bedrock, Vertex, and Foundry, Claude Code does not send metrics from your cloud. To get cost metrics, several large enterprises reported using [LiteLLM](/en/llm-gateway#litellm-configuration), which is an open-source tool that helps companies [track spend by key](https://docs.litellm.ai/docs/proxy/virtual_keys#tracking-spend). This project is unaffiliated with Anthropic and has not been audited for security.

41 41 

42### Rate limit recommendations42### Rate limit recommendations

43 43 

54 54 

55For example, if you have 200 users, you might request 20k TPM for each user, or 4 million total TPM (200\*20,000 = 4 million).55For example, if you have 200 users, you might request 20k TPM for each user, or 4 million total TPM (200\*20,000 = 4 million).

56 56 

57The TPM per user decreases as team size grows because we expect fewer users to use Claude Code concurrently in larger organizations. These rate limits apply at the organization level, not per individual user, which means individual users can temporarily consume more than their calculated share when others aren't actively using the service.57The TPM per user decreases as team size grows because fewer users tend to use Claude Code concurrently in larger organizations. These rate limits apply at the organization level, not per individual user, which means individual users can temporarily consume more than their calculated share when others aren't actively using the service.

58 58 

59<Note>59<Note>

60 If you anticipate scenarios with unusually high concurrent usage (such as live training sessions with large groups), you may need higher TPM allocations per user.60 If you anticipate scenarios with unusually high concurrent usage (such as live training sessions with large groups), you may need higher TPM allocations per user.

61</Note>61</Note>

62 62 

63### Agent team token costs

64 

65[Agent teams](/en/agent-teams) spawn multiple Claude Code instances, each with its own context window. Token usage scales with the number of active teammates and how long each one runs.

66 

67To keep agent team costs manageable:

68 

69* Use Sonnet for teammates. It balances capability and cost for coordination tasks.

70* Keep teams small. Each teammate runs its own context window, so token usage is roughly proportional to team size.

71* Keep spawn prompts focused. Teammates load CLAUDE.md, MCP servers, and skills automatically, but everything in the spawn prompt adds to their context from the start.

72* Clean up teams when work is done. Active teammates continue consuming tokens even if idle.

73* Agent teams are disabled by default. Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your [settings.json](/en/settings) or environment to enable them. See [enable agent teams](/en/agent-teams#enable-agent-teams).

74 

63## Reduce token usage75## Reduce token usage

64 76 

65Token costs scale with context size: the more context Claude processes, the more tokens you use. Claude Code automatically optimizes costs through prompt caching (which reduces costs for repeated content like system prompts) and auto-compaction (which summarizes conversation history when approaching context limits).77Token costs scale with context size: the more context Claude processes, the more tokens you use. Claude Code automatically optimizes costs through prompt caching (which reduces costs for repeated content like system prompts) and auto-compaction (which summarizes conversation history when approaching context limits).

153 165 

154### Adjust extended thinking166### Adjust extended thinking

155 167 

156Extended thinking is enabled by default with a budget of 31,999 tokens because it significantly improves performance on complex planning and reasoning tasks. However, thinking tokens are billed as output tokens, so for simpler tasks where deep reasoning isn't needed, you can reduce costs by disabling it in `/config` or lowering the budget (for example, `MAX_THINKING_TOKENS=8000`).168Extended thinking is enabled by default with a budget of 31,999 tokens because it significantly improves performance on complex planning and reasoning tasks. However, thinking tokens are billed as output tokens, so for simpler tasks where deep reasoning isn't needed, you can reduce costs by lowering the [effort level](/en/model-config#adjust-effort-level) in `/model` for Opus 4.6, disabling thinking in `/config`, or lowering the budget (for example, `MAX_THINKING_TOKENS=8000`).

157 169 

158### Delegate verbose operations to subagents170### Delegate verbose operations to subagents

159 171 

160Running tests, fetching documentation, or processing log files can consume significant context. Delegate these to [subagents](/en/sub-agents#isolate-high-volume-operations) so the verbose output stays in the subagent's context while only a summary returns to your main conversation.172Running tests, fetching documentation, or processing log files can consume significant context. Delegate these to [subagents](/en/sub-agents#isolate-high-volume-operations) so the verbose output stays in the subagent's context while only a summary returns to your main conversation.

161 173 

174### Manage agent team costs

175 

176Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, because each teammate maintains its own context window and runs as a separate Claude instance. Keep team tasks small and self-contained to limit per-teammate token usage. See [agent teams](/en/agent-teams) for details.

177 

162### Write specific prompts178### Write specific prompts

163 179 

164Vague requests like "improve this codebase" trigger broad scanning. Specific requests like "add input validation to the login function in auth.ts" let Claude work efficiently with minimal file reads.180Vague requests like "improve this codebase" trigger broad scanning. Specific requests like "add input validation to the login function in auth.ts" let Claude work efficiently with minimal file reads.

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