Anthropic - Claude Code Docs Changes 2026-02-04 03:45 UTC → 2026-02-10 03:56 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| | Subagents | Agent teams |

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

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

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

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

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

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

46 

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

48 

49## Enable agent teams

50 

51Agent 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):

52 

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

54{

55 "env": {

56 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"

57 }

58}

59```

60 

61## Start your first agent team

62 

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

64 

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

66 

67```

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

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

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

71```

72 

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

74 

75The lead's terminal lists all teammates and what they're working on. Use Shift+Up/Down to select a teammate and message them directly.

76 

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

78 

79## Control your agent team

80 

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

82 

83### Choose a display mode

84 

85Agent teams support two display modes:

86 

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

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

89 

90<Note>

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

92</Note>

93 

94The 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):

95 

96```json theme={null}

97{

98 "teammateMode": "in-process"

99}

100```

101 

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

103 

104```bash theme={null}

105claude --teammate-mode in-process

106```

107 

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

109 

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

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

112 

113### Specify teammates and models

114 

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

116 

117```

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

119Use Sonnet for each teammate.

120```

121 

122### Require plan approval for teammates

123 

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

125 

126```

127Spawn an architect teammate to refactor the authentication module.

128Require plan approval before they make any changes.

129```

130 

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

132 

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

134 

135### Use delegate mode

136 

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

138 

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

140 

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

142 

143### Talk to teammates directly

144 

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

146 

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

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

149 

150### Assign and claim tasks

151 

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

153 

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

155 

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

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

158 

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

160 

161### Shut down teammates

162 

163To gracefully end a teammate's session:

164 

165```

166Ask the researcher teammate to shut down

167```

168 

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

170 

171### Clean up the team

172 

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

174 

175```

176Clean up the team

177```

178 

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

180 

181<Warning>

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

183</Warning>

184 

185### Enforce quality gates with hooks

186 

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

188 

189* [`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.

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

191 

192## How agent teams work

193 

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

195 

196### How Claude starts agent teams

197 

198There are two ways agent teams get started:

199 

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

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

202 

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

204 

205### Architecture

206 

207An agent team consists of:

208 

209| Component | Role |

210| :------------ | :----------------------------------------------------------------------------------------- |

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

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

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

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

215 

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

217 

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

219 

220Teams and tasks are stored locally:

221 

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

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

224 

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

226 

227### Permissions

228 

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

230 

231### Context and communication

232 

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

234 

235**How teammates share information:**

236 

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

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

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

240 

241**Teammate messaging:**

242 

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

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

245 

246### Token usage

247 

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

249 

250## Use case examples

251 

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

253 

254### Run a parallel code review

255 

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

257 

258```

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

260- One focused on security implications

261- One checking performance impact

262- One validating test coverage

263Have them each review and report findings.

264```

265 

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

267 

268### Investigate with competing hypotheses

269 

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

271 

272```

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

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

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

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

277```

278 

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

280 

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

282 

283## Best practices

284 

285### Give teammates enough context

286 

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

288 

289```

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

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

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

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

294```

295 

296### Size tasks appropriately

297 

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

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

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

301 

302<Tip>

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

304</Tip>

305 

306### Wait for teammates to finish

307 

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

309 

310```

311Wait for your teammates to complete their tasks before proceeding

312```

313 

314### Start with research and review

315 

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

317 

318### Avoid file conflicts

319 

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

321 

322### Monitor and steer

323 

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

325 

326## Troubleshooting

327 

328### Teammates not appearing

329 

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

331 

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

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

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

335 ```bash theme={null}

336 which tmux

337 ```

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

339 

340### Too many permission prompts

341 

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

343 

344### Teammates stopping on errors

345 

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

347 

348* Give them additional instructions directly

349* Spawn a replacement teammate to continue the work

350 

351### Lead shuts down before work is done

352 

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

354 

355### Orphaned tmux sessions

356 

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

358 

359```bash theme={null}

360tmux ls

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

362```

363 

364## Limitations

365 

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

367 

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

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

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

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

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

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

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

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

376 

377<Tip>

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

379</Tip>

380 

381## Next steps

382 

383Explore related approaches for parallel work and delegation:

384 

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

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

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

149 149 

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

151 151 

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 configuration152## IAM configuration

169 153 

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

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 Desktop](/en/desktop): 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 

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 

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.

8 12 

9<Note>13<Note>

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.14 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>15</Note>

12 16 

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.17## Capabilities

14 

15## What the integration enables

16 18 

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.19With Chrome connected, you can chain browser actions with coding tasks in a single workflow:

18 20 

19Key capabilities include:21* **Live debugging**: read console errors and DOM state directly, then fix the code that caused them

20 22* **Design verification**: build a UI from a Figma mock, then open it in the browser to verify it matches

21* **Live debugging**: Claude reads console errors and DOM state directly, then fixes the code that caused them23* **Web app testing**: test form validation, check for visual regressions, or verify user flows

22* **Design verification**: Build a UI from a Figma mock, then have Claude open it in the browser and verify it matches24* **Authenticated web apps**: interact with Google Docs, Gmail, Notion, or any app you're logged into without API connectors

23* **Web app testing**: Test form validation, check for visual regressions, or verify user flows work correctly25* **Data extraction**: pull structured information from web pages and save it locally

24* **Authenticated web apps**: Interact with Google Docs, Gmail, Notion, or any app you're logged into without needing API connectors26* **Task automation**: automate repetitive browser tasks like data entry, form filling, or multi-site workflows

25* **Data extraction**: Pull structured information from web pages and save it locally27* **Session recording**: record browser interactions as GIFs to document or share what happened

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

28 28 

29## Prerequisites29## Prerequisites

30 30 

32 32 

33* [Google Chrome](https://www.google.com/chrome/) browser33* [Google Chrome](https://www.google.com/chrome/) 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

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, Team, 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>

88 78 

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.79### Manage site permissions

90 80 

91The following examples show common patterns for browser automation.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.

82 

83## Example workflows

84 

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 

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

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

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

186 

193### Browser not responding187### Browser not responding

194 188 

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

196 190 

1971. Check if a modal dialog (alert, confirm, prompt) is blocking the page1911. 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 again1922. Ask Claude to create a new tab and try again

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

200 194 

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

202 196 

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.197The 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 198 

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

206 200 

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

208 202 

209<Note>203* **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.204* **Native messaging host errors**: if the native messaging host crashes on startup, try reinstalling Claude Code to regenerate the host configuration.

211</Note>205 

206### Common error messages

207 

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

212 209 

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.210| Error | Cause | Fix |

211| ------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------- |

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

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

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

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

214 216 

215## See also217## See also

216 218 

217* [CLI reference](/en/cli-reference) - Command-line flags including `--chrome`219* [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 Code220* [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 permissions221* [Common workflows](/en/common-workflows): more ways to use Claude Code

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

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

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"` |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-file` | Load system prompt from a file, replacing the default prompt (print mode only) | `claude -p --system-prompt-file ./custom-prompt.txt "query"` |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| `--teleport` | Resume a [web session](/en/claude-code-on-the-web) in your local terminal | `claude --teleport` |72| `--teleport` | Resume a [web session](/en/claude-code-on-the-web) in your local terminal | `claude --teleport` |

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

74| `--verbose` | Enable verbose logging, shows full turn-by-turn output (helpful for debugging in both print and interactive modes) | `claude --verbose` |75| `--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` |76| `--version`, `-v` | Output the version number | `claude -v` |

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:85The `--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 86 

86| Field | Required | Description |87| Field | Required | Description |

87| :------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------- |88| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

89| `prompt` | Yes | The system prompt that guides the subagent's behavior |90| `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 |91| `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) |92| `disallowedTools` | No | Array of tool names to explicitly deny for this subagent |

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

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

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

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

92 97 

93Example:98Example:

94 99 

240 240 

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

242 242 

243If you are in Normal Mode, **Shift+Tab** first switches into Auto-Accept Mode, indicated by `⏵⏵ accept edits on` at the bottom of the terminal. A subsequent **Shift+Tab** will switch into Plan Mode, indicated by `⏸ plan mode on`.243If you are in Normal Mode, **Shift+Tab** first switches into Auto-Accept Mode, indicated by `⏵⏵ accept edits on` at the bottom of the terminal. A subsequent **Shift+Tab** will switch into Plan Mode, indicated by `⏸ plan mode on`. When an [agent team](/en/agent-teams) is active, the cycle also includes Delegate Mode.

244 244 

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

246 246 

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 536 

538* More space to explore multiple solution approaches step-by-step537Extended 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.

539* Room to analyze edge cases and evaluate tradeoffs thoroughly

540* Ability to revise reasoning and self-correct mistakes

541 538 

542Token budgets for thinking mode:539**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.

543 540 

544* When thinking is **enabled**, Claude can use up to **31,999 tokens** from your output budget for internal reasoning541**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.

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

546 542 

547**Limit the thinking budget:**543`MAX_THINKING_TOKENS` is ignored when using Opus 4.6, since adaptive reasoning controls thinking depth instead. The one exception: setting `MAX_THINKING_TOKENS=0` still disables thinking entirely on any model.

548 

549* Use the [`MAX_THINKING_TOKENS` environment variable](/en/settings#environment-variables) to cap the thinking budget

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

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

716</Tip>708</Tip>

717 709 

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

711 

718***712***

719 713 

720## Use Claude as a unix-style utility714## Use Claude as a unix-style utility

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.

113* **Ask** (recommended for new users): Claude asks for your approval before each file edit or command. You see a diff view and can accept or reject each change.113* **Ask** (recommended for new users): Claude asks for your approval before each file edit or command. You see a diff view and can accept or reject each change.

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

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

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

117 

118<Warning title="Act mode">

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

120</Warning>

116 121 

117To stop Claude mid-task, click the stop button.122To stop Claude mid-task, click the stop button.

118 123 

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# Speed up responses with fast mode

6 

7> Get faster Opus 4.6 responses in Claude Code by toggling fast mode.

8 

9<Note>

10 Fast mode is in [research preview](#research-preview). The feature, pricing, and availability may change based on feedback.

11</Note>

12 

13Fast mode delivers faster Opus 4.6 responses at a higher cost per token. Toggle it on with `/fast` when you need speed for interactive work like rapid iteration or live debugging, and toggle it off when cost matters more than latency.

14 

15Fast mode is not a different model. It uses the same Opus 4.6 with a different API configuration that prioritizes speed over cost efficiency. You get identical quality and capabilities, just faster responses.

16 

17What to know:

18 

19* Use `/fast` to toggle on fast mode in Claude Code CLI. Also available via `/fast` in Claude Code VS Code Extension.

20* Fast mode for Opus 4.6 pricing starts at \$30/150 MTok. Fast mode is available at a 50% discount for all plans until 11:59pm PT on February 16.

21* Available to all Claude Code users on subscription plans (Pro/Max/Team/Enterprise) and Claude Console.

22* For Claude Code users on subscription plans (Pro/Max/Team/Enterprise), fast mode is available via extra usage only and not included in the subscription rate limits.

23 

24This page covers how to [toggle fast mode](#toggle-fast-mode), its [cost tradeoff](#understand-the-cost-tradeoff), [when to use it](#decide-when-to-use-fast-mode), [requirements](#requirements), and [rate limit behavior](#handle-rate-limits).

25 

26## Toggle fast mode

27 

28Toggle fast mode in either of these ways:

29 

30* Type `/fast` and press Tab to toggle on or off

31* Set `"fastMode": true` in your [user settings file](/en/settings)

32 

33Fast mode persists across sessions. For the best cost efficiency, enable fast mode at the start of a session rather than switching mid-conversation. See [understand the cost tradeoff](#understand-the-cost-tradeoff) for details.

34 

35When you enable fast mode:

36 

37* If you're on a different model, Claude Code automatically switches to Opus 4.6

38* You'll see a confirmation message: "Fast mode ON"

39* A small `↯` icon appears next to the prompt while fast mode is active

40* Run `/fast` again at any time to check whether fast mode is on or off

41 

42When you disable fast mode with `/fast` again, you remain on Opus 4.6. The model does not revert to your previous model. To switch to a different model, use `/model`.

43 

44## Understand the cost tradeoff

45 

46Fast mode has higher per-token pricing than standard Opus 4.6:

47 

48| Mode | Input (MTok) | Output (MTok) |

49| ------------------------------ | ------------ | ------------- |

50| Fast mode on Opus 4.6 (\<200K) | \$30 | \$150 |

51| Fast mode on Opus 4.6 (>200K) | \$60 | \$225 |

52 

53Fast mode is compatible with the 1M token extended context window.

54 

55When you switch into fast mode mid-conversation, you pay the full fast mode uncached input token price for the entire conversation context. This costs more than if you had enabled fast mode from the start.

56 

57## Decide when to use fast mode

58 

59Fast mode is best for interactive work where response latency matters more than cost:

60 

61* Rapid iteration on code changes

62* Live debugging sessions

63* Time-sensitive work with tight deadlines

64 

65Standard mode is better for:

66 

67* Long autonomous tasks where speed matters less

68* Batch processing or CI/CD pipelines

69* Cost-sensitive workloads

70 

71### Fast mode vs effort level

72 

73Fast mode and effort level both affect response speed, but differently:

74 

75| Setting | Effect |

76| ---------------------- | -------------------------------------------------------------------------------- |

77| **Fast mode** | Same model quality, lower latency, higher cost |

78| **Lower effort level** | Less thinking time, faster responses, potentially lower quality on complex tasks |

79 

80You can combine both: use fast mode with a lower [effort level](/en/model-config#adjust-effort-level) for maximum speed on straightforward tasks.

81 

82## Requirements

83 

84Fast mode requires all of the following:

85 

86* **Not available on third-party cloud providers**: fast mode is not available on Amazon Bedrock, Google Vertex AI, or Microsoft Azure Foundry. Fast mode is available through the Anthropic Console API and for Claude subscription plans using extra usage.

87* **Extra usage enabled**: your account must have extra usage enabled, which allows billing beyond your plan's included usage. For individual accounts, enable this in your [Console billing settings](https://platform.claude.com/settings/organization/billing). For Teams and Enterprise, an admin must enable extra usage for the organization.

88 

89<Note>

90 Fast mode usage is billed directly to extra usage, even if you have remaining usage on your plan. This means fast mode tokens do not count against your plan's included usage and are charged at the fast mode rate from the first token.

91</Note>

92 

93* **Admin enablement for Teams and Enterprise**: fast mode is disabled by default for Teams and Enterprise organizations. An admin must explicitly [enable fast mode](#enable-fast-mode-for-your-organization) before users can access it.

94 

95<Note>

96 If your admin has not enabled fast mode for your organization, the `/fast` command will show "Fast mode has been disabled by your organization."

97</Note>

98 

99### Enable fast mode for your organization

100 

101Admins can enable fast mode in:

102 

103* **Console** (API customers): [Claude Code preferences](https://platform.claude.com/claude-code/preferences)

104* **Claude AI** (Teams and Enterprise): [Admin Settings > Claude Code](https://claude.ai/admin-settings/claude-code)

105 

106## Handle rate limits

107 

108Fast mode has separate rate limits from standard Opus 4.6. When you hit the fast mode rate limit or run out of extra usage credits:

109 

1101. Fast mode automatically falls back to standard Opus 4.6

1112. The `↯` icon turns gray to indicate cooldown

1123. You continue working at standard speed and pricing

1134. When the cooldown expires, fast mode automatically re-enables

114 

115To disable fast mode manually instead of waiting for cooldown, run `/fast` again.

116 

117## Research preview

118 

119Fast mode is a research preview feature. This means:

120 

121* The feature may change based on feedback

122* Availability and pricing are subject to change

123* The underlying API configuration may evolve

124 

125Report issues or feedback through your usual Anthropic support channels.

126 

127## See also

128 

129* [Model configuration](/en/model-config): switch models and adjust effort levels

130* [Manage costs effectively](/en/costs): track token usage and reduce costs

131* [Status line configuration](/en/statusline): display model and context information

22* **[Skills](/en/skills)** add reusable knowledge and invocable workflows22* **[Skills](/en/skills)** add reusable knowledge and invocable workflows

23* **[MCP](/en/mcp)** connects Claude to external services and tools23* **[MCP](/en/mcp)** connects Claude to external services and tools

24* **[Subagents](/en/sub-agents)** run their own loops in isolated context, returning summaries24* **[Subagents](/en/sub-agents)** run their own loops in isolated context, returning summaries

25* **[Agent teams](/en/agent-teams)** coordinate multiple independent sessions with shared tasks and peer-to-peer messaging

25* **[Hooks](/en/hooks)** run outside the loop entirely as deterministic scripts26* **[Hooks](/en/hooks)** run outside the loop entirely as deterministic scripts

26* **[Plugins](/en/plugins)** and **[marketplaces](/en/plugin-marketplaces)** package and distribute these features27* **[Plugins](/en/plugins)** and **[marketplaces](/en/plugin-marketplaces)** package and distribute these features

27 28 

32Features range from always-on context that Claude sees every session, to on-demand capabilities you or Claude can invoke, to background automation that runs on specific events. The table below shows what's available and when each one makes sense.33Features range from always-on context that Claude sees every session, to on-demand capabilities you or Claude can invoke, to background automation that runs on specific events. The table below shows what's available and when each one makes sense.

33 34 

34| Feature | What it does | When to use it | Example |35| Feature | What it does | When to use it | Example |

35| ------------- | ---------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------- |36| ---------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |

36| **CLAUDE.md** | Persistent context loaded every conversation | Project conventions, "always do X" rules | "Use pnpm, not npm. Run tests before committing." |37| **CLAUDE.md** | Persistent context loaded every conversation | Project conventions, "always do X" rules | "Use pnpm, not npm. Run tests before committing." |

37| **Skill** | Instructions, knowledge, and workflows Claude can use | Reusable content, reference docs, repeatable tasks | `/review` runs your code review checklist; API docs skill with endpoint patterns |38| **Skill** | Instructions, knowledge, and workflows Claude can use | Reusable content, reference docs, repeatable tasks | `/review` runs your code review checklist; API docs skill with endpoint patterns |

38| **Subagent** | Isolated execution context that returns summarized results | Context isolation, parallel tasks, specialized workers | Research task that reads many files but returns only key findings |39| **Subagent** | Isolated execution context that returns summarized results | Context isolation, parallel tasks, specialized workers | Research task that reads many files but returns only key findings |

40| **[Agent teams](/en/agent-teams)** | Coordinate multiple independent Claude Code sessions | Parallel research, new feature development, debugging with competing hypotheses | Spawn reviewers to check security, performance, and tests simultaneously |

39| **MCP** | Connect to external services | External data or actions | Query your database, post to Slack, control a browser |41| **MCP** | Connect to external services | External data or actions | Query your database, post to Slack, control a browser |

40| **Hook** | Deterministic script that runs on events | Predictable automation, no LLM involved | Run ESLint after every file edit |42| **Hook** | Deterministic script that runs on events | Predictable automation, no LLM involved | Run ESLint after every file edit |

41 43 

82 **Rule of thumb:** Keep CLAUDE.md under \~500 lines. If it's growing, move reference content to skills.84 **Rule of thumb:** Keep CLAUDE.md under \~500 lines. If it's growing, move reference content to skills.

83 </Tab>85 </Tab>

84 86 

87 <Tab title="Subagent vs Agent team">

88 Both parallelize work, but they're architecturally different:

89 

90 * **Subagents** run inside your session and report results back to your main context

91 * **Agent teams** are independent Claude Code sessions that communicate with each other

92 

93 | Aspect | Subagent | Agent team |

94 | ----------------- | ------------------------------------------------ | --------------------------------------------------- |

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

96 | **Communication** | Reports results back to the main agent only | Teammates message each other directly |

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

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

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

100 

101 **Use a subagent** when you need a quick, focused worker: research a question, verify a claim, review a file. The subagent does the work and returns a summary. Your main conversation stays clean.

102 

103 **Use an agent team** when teammates need to share findings, challenge each other, and coordinate independently. Agent teams are best for research with competing hypotheses, parallel code review, and new feature development where each teammate owns a separate piece.

104 

105 **Transition point:** If you're running parallel subagents but hitting context limits, or if your subagents need to communicate with each other, agent teams are the natural next step.

106 

107 <Note>

108 Agent teams are experimental and disabled by default. See [agent teams](/en/agent-teams) for setup and current limitations.

109 </Note>

110 </Tab>

111 

85 <Tab title="MCP vs Skill">112 <Tab title="MCP vs Skill">

86 MCP connects Claude to external services. Skills extend what Claude knows, including how to use those services effectively.113 MCP connects Claude to external services. Skills extend what Claude knows, including how to use those services effectively.

87 114 

229 Offload work to isolated context256 Offload work to isolated context

230 </Card>257 </Card>

231 258 

259 <Card title="Agent teams" icon="network" href="/en/agent-teams">

260 Coordinate multiple sessions working in parallel

261 </Card>

262 

232 <Card title="MCP" icon="plug" href="/en/mcp">263 <Card title="MCP" icon="plug" href="/en/mcp">

233 Connect Claude to external services264 Connect Claude to external services

234 </Card>265 </Card>

16</Note>16</Note>

17 17 

18<Info>18<Info>

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

20</Info>20</Info>

21 21 

22## Why use Claude Code GitHub Actions?22## Why use Claude Code GitHub Actions?

193 with:193 with:

194 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}194 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

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

196 claude_args: "--model claude-opus-4-5-20251101"196 claude_args: "--model opus"

197```197```

198 198 

199### Common use cases199### Common use cases

109To customize models:109To customize models:

110 110 

111```bash theme={null}111```bash theme={null}

112export ANTHROPIC_MODEL='claude-opus-4-1@20250805'112export ANTHROPIC_MODEL='claude-opus-4-6'

113export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'113export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'

114```114```

115 115 

18 18 

19<div style={{maxWidth: "500px", margin: "0 auto"}}>19<div style={{maxWidth: "500px", margin: "0 auto"}}>

20 <Frame>20 <Frame>

21 <img src="https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=5c25fedbc3db6f8882af50c3cc478c32" alt="Hook lifecycle diagram showing the sequence of hooks from SessionStart through the agentic loop to SessionEnd" data-og-width="8876" width="8876" data-og-height="12492" height="12492" data-path="images/hooks-lifecycle.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?w=280&fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=62406fcd5d4a189cc8842ee1bd946b84 280w, https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?w=560&fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=fa3049022a6973c5f974e0f95b28169d 560w, https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?w=840&fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=bd2890897db61a03160b93d4f972ff8e 840w, https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?w=1100&fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=7ae8e098340479347135e39df4a13454 1100w, https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?w=1650&fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=848a8606aab22c2ccaa16b6a18431e32 1650w, https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?w=2500&fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=f3a9ef7feb61fa8fe362005aa185efbc 2500w" />21 <img src="https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=7a351ea1cc3d5da7a2176bf51196bc1a" alt="Hook lifecycle diagram showing the sequence of hooks from SessionStart through the agentic loop to SessionEnd" data-og-width="520" width="520" data-og-height="960" height="960" data-path="images/hooks-lifecycle.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?w=280&fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=8f32c67d025f0a318d5ed10a4f8ff2e6 280w, https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?w=560&fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=896fc424e39ff8d590720331a77e3d80 560w, https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?w=840&fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=a1c1c9739cde965e1eade843cee567c5 840w, https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?w=1100&fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=5bb083988de020e7d568e8dd8f1422fc 1100w, https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?w=1650&fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=343e9883c1e3172f08096c352aa46f12 1650w, https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?w=2500&fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=4de37b29de0f6df8b0c3e937a76c3bc6 2500w" />

22 </Frame>22 </Frame>

23</div>23</div>

24 24 

25The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one.25The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one.

26 26 

27| Event | When it fires |27| Event | When it fires |

28| :------------------- | :--------------------------------------------------- |28| :------------------- | :----------------------------------------------------------------- |

29| `SessionStart` | When a session begins or resumes |29| `SessionStart` | When a session begins or resumes |

30| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |30| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |

31| `PreToolUse` | Before a tool call executes. Can block it |31| `PreToolUse` | Before a tool call executes. Can block it |

36| `SubagentStart` | When a subagent is spawned |36| `SubagentStart` | When a subagent is spawned |

37| `SubagentStop` | When a subagent finishes |37| `SubagentStop` | When a subagent finishes |

38| `Stop` | When Claude finishes responding |38| `Stop` | When Claude finishes responding |

39| `TeammateIdle` | When an [agent team](/en/agent-teams) teammate is about to go idle |

40| `TaskCompleted` | When a task is being marked as completed |

39| `PreCompact` | Before context compaction |41| `PreCompact` | Before context compaction |

40| `SessionEnd` | When a session terminates |42| `SessionEnd` | When a session terminates |

41 43 

165| `SubagentStart` | agent type | `Bash`, `Explore`, `Plan`, or custom agent names |167| `SubagentStart` | agent type | `Bash`, `Explore`, `Plan`, or custom agent names |

166| `PreCompact` | what triggered compaction | `manual`, `auto` |168| `PreCompact` | what triggered compaction | `manual`, `auto` |

167| `SubagentStop` | agent type | same values as `SubagentStart` |169| `SubagentStop` | agent type | same values as `SubagentStart` |

168| `UserPromptSubmit`, `Stop` | no matcher support | always fires on every occurrence |170| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCompleted` | no matcher support | always fires on every occurrence |

169 171 

170The matcher is a regex, so `Edit|Write` matches either tool and `Notebook.*` matches any tool starting with Notebook. The matcher runs against a field from the [JSON input](#hook-input-and-output) that Claude Code sends to your hook on stdin. For tool events, that field is `tool_name`. Each [hook event](#hook-events) section lists the full set of matcher values and the input schema for that event.172The matcher is a regex, so `Edit|Write` matches either tool and `Notebook.*` matches any tool starting with Notebook. The matcher runs against a field from the [JSON input](#hook-input-and-output) that Claude Code sends to your hook on stdin. For tool events, that field is `tool_name`. Each [hook event](#hook-events) section lists the full set of matcher values and the input schema for that event.

171 173 

441Exit code 2 is the way a hook signals "stop, don't do this." The effect depends on the event, because some events represent actions that can be blocked (like a tool call that hasn't happened yet) and others represent things that already happened or can't be prevented.443Exit code 2 is the way a hook signals "stop, don't do this." The effect depends on the event, because some events represent actions that can be blocked (like a tool call that hasn't happened yet) and others represent things that already happened or can't be prevented.

442 444 

443| Hook event | Can block? | What happens on exit 2 |445| Hook event | Can block? | What happens on exit 2 |

444| :------------------- | :--------- | :-------------------------------------------------------- |446| :------------------- | :--------- | :----------------------------------------------------------------- |

445| `PreToolUse` | Yes | Blocks the tool call |447| `PreToolUse` | Yes | Blocks the tool call |

446| `PermissionRequest` | Yes | Denies the permission |448| `PermissionRequest` | Yes | Denies the permission |

447| `UserPromptSubmit` | Yes | Blocks prompt processing and erases the prompt |449| `UserPromptSubmit` | Yes | Blocks prompt processing and erases the prompt |

448| `Stop` | Yes | Prevents Claude from stopping, continues the conversation |450| `Stop` | Yes | Prevents Claude from stopping, continues the conversation |

449| `SubagentStop` | Yes | Prevents the subagent from stopping |451| `SubagentStop` | Yes | Prevents the subagent from stopping |

452| `TeammateIdle` | Yes | Prevents the teammate from going idle (teammate continues working) |

453| `TaskCompleted` | Yes | Prevents the task from being marked as completed |

450| `PostToolUse` | No | Shows stderr to Claude (tool already ran) |454| `PostToolUse` | No | Shows stderr to Claude (tool already ran) |

451| `PostToolUseFailure` | No | Shows stderr to Claude (tool already failed) |455| `PostToolUseFailure` | No | Shows stderr to Claude (tool already failed) |

452| `Notification` | No | Shows stderr to user only |456| `Notification` | No | Shows stderr to user only |

491| Events | Decision pattern | Key fields |495| Events | Decision pattern | Key fields |

492| :-------------------------------------------------------------------- | :------------------- | :---------------------------------------------------------------- |496| :-------------------------------------------------------------------- | :------------------- | :---------------------------------------------------------------- |

493| UserPromptSubmit, PostToolUse, PostToolUseFailure, Stop, SubagentStop | Top-level `decision` | `decision: "block"`, `reason` |497| UserPromptSubmit, PostToolUse, PostToolUseFailure, Stop, SubagentStop | Top-level `decision` | `decision: "block"`, `reason` |

498| TeammateIdle, TaskCompleted | Exit code only | Exit code 2 blocks the action, stderr is fed back as feedback |

494| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask), `permissionDecisionReason` |499| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask), `permissionDecisionReason` |

495| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |500| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |

496 501 

498 503 

499<Tabs>504<Tabs>

500 <Tab title="Top-level decision">505 <Tab title="Top-level decision">

501 Used by `UserPromptSubmit`, `PostToolUse`, `PostToolUseFailure`, `Stop`, and `SubagentStop`. The only value is `"block"` — to allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:506 Used by `UserPromptSubmit`, `PostToolUse`, `PostToolUseFailure`, `Stop`, and `SubagentStop`. The only value is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:

502 507 

503 ```json theme={null}508 ```json theme={null}

504 {509 {

1134}1139}

1135```1140```

1136 1141 

1142### TeammateIdle

1143 

1144Runs when an [agent team](/en/agent-teams) teammate is about to go idle after finishing its turn. Use this to enforce quality gates before a teammate stops working, such as requiring passing lint checks or verifying that output files exist.

1145 

1146When a `TeammateIdle` hook exits with code 2, the teammate receives the stderr message as feedback and continues working instead of going idle. TeammateIdle hooks do not support matchers and fire on every occurrence.

1147 

1148#### TeammateIdle input

1149 

1150In addition to the [common input fields](#common-input-fields), TeammateIdle hooks receive `teammate_name` and `team_name`.

1151 

1152```json theme={null}

1153{

1154 "session_id": "abc123",

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

1156 "cwd": "/Users/...",

1157 "permission_mode": "default",

1158 "hook_event_name": "TeammateIdle",

1159 "teammate_name": "researcher",

1160 "team_name": "my-project"

1161}

1162```

1163 

1164| Field | Description |

1165| :-------------- | :-------------------------------------------- |

1166| `teammate_name` | Name of the teammate that is about to go idle |

1167| `team_name` | Name of the team |

1168 

1169#### TeammateIdle decision control

1170 

1171TeammateIdle hooks use exit codes only, not JSON decision control. This example checks that a build artifact exists before allowing a teammate to go idle:

1172 

1173```bash theme={null}

1174#!/bin/bash

1175 

1176if [ ! -f "./dist/output.js" ]; then

1177 echo "Build artifact missing. Run the build before stopping." >&2

1178 exit 2

1179fi

1180 

1181exit 0

1182```

1183 

1184### TaskCompleted

1185 

1186Runs when a task is being marked as completed. This fires in two situations: when any agent explicitly marks a task as completed through the TaskUpdate tool, or when an [agent team](/en/agent-teams) teammate finishes its turn with in-progress tasks. Use this to enforce completion criteria like passing tests or lint checks before a task can close.

1187 

1188When a `TaskCompleted` hook exits with code 2, the task is not marked as completed and the stderr message is fed back to the model as feedback. TaskCompleted hooks do not support matchers and fire on every occurrence.

1189 

1190#### TaskCompleted input

1191 

1192In addition to the [common input fields](#common-input-fields), TaskCompleted hooks receive `task_id`, `task_subject`, and optionally `task_description`, `teammate_name`, and `team_name`.

1193 

1194```json theme={null}

1195{

1196 "session_id": "abc123",

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

1198 "cwd": "/Users/...",

1199 "permission_mode": "default",

1200 "hook_event_name": "TaskCompleted",

1201 "task_id": "task-001",

1202 "task_subject": "Implement user authentication",

1203 "task_description": "Add login and signup endpoints",

1204 "teammate_name": "implementer",

1205 "team_name": "my-project"

1206}

1207```

1208 

1209| Field | Description |

1210| :----------------- | :------------------------------------------------------ |

1211| `task_id` | Identifier of the task being completed |

1212| `task_subject` | Title of the task |

1213| `task_description` | Detailed description of the task. May be absent |

1214| `teammate_name` | Name of the teammate completing the task. May be absent |

1215| `team_name` | Name of the team. May be absent |

1216 

1217#### TaskCompleted decision control

1218 

1219TaskCompleted hooks use exit codes only, not JSON decision control. This example runs tests and blocks task completion if they fail:

1220 

1221```bash theme={null}