Home Docs Claude Code CLI

One capture · claude-code

One read of Claude Code CLIclaude-code-20261030T180701Z

88 pages moved out of 228 read.

Pages moved 88 significant first

Pages read 228 in this capture

Captured 30 Oct 2026 18:07 UTC

Corpus hash 49664f3a50da corpus-hash

What this read moved

26-50 of 88, page 2 of 4

This capture is too large to show at once. Changes 26-50 of 88 are below, significant first; the rest are on the following screens.

fast-mode Changed · +5 / -5 lines

from line 16

1616

1717* Use `/fast` to toggle on fast mode in the Claude Code CLI. The [VS Code extension](https://code.claude.com/docs/en/vs-code.md) offers a **Toggle fast mode** command when the selected model supports fast mode. Claude Code saves that toggle to your [`fastMode` setting](#toggle-fast-mode).

1818* Fast mode pricing per MTok input/output is \$8/\$40 on Opus 5.5 and \$10/\$50 on Opus 5 and Opus 4.8.

19* Available to Claude Code users on subscription plans (Pro/Max/Team/Enterprise) and on Claude Console. Team and Enterprise organizations need an Owner to enable it first, and Console organizations need access provisioned first to use it with Opus 5 or Opus 4.8. [Requirements](#requirements) describes both.

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

19* Available to Claude Code users on subscription plans (Pro/Max/Ultra/Team/Enterprise) and on Claude Console. Team and Enterprise organizations need an Owner to enable it first, and Console organizations need access provisioned first to use it with Opus 5 or Opus 4.8. [Requirements](#requirements) describes both.

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

2121

2222## Toggle fast mode

2323

from line 82

8282

8383You see fast mode spend in a different place depending on how you signed in, so first run [`/status`](https://code.claude.com/docs/en/commands) to check. If it shows a `Login method` row such as `Claude Max account`, you signed in with a Claude subscription. If it shows an `API key` row instead, your requests bill to a Claude Console organization.

8484

85* **Pro and Max**: you pay for fast mode from your usage credits. Go to [**Settings > Usage**](https://claude.ai/settings/usage) on claude.ai, where the **Usage credits** section shows how much you've spent in usage credits this month. That figure includes fast mode but doesn't break it out separately.

85* **Pro, Max, and Ultra**: you pay for fast mode from your usage credits. Go to [**Settings > Usage**](https://claude.ai/settings/usage) on claude.ai, where the **Usage credits** section shows how much you've spent in usage credits this month. That figure includes fast mode but doesn't break it out separately.

8686* **Team and Enterprise**: your organization pays for your fast mode usage from its usage credits. To see your own usage-credits spend, run [`/usage`](https://code.claude.com/docs/en/costs#check-your-usage-credits-spend). For where your organization sees that spend, see [Claude for Teams and Enterprise](https://code.claude.com/docs/en/costs.md#claude-for-teams-and-enterprise).

8787* **Claude Console**: your organization pays for fast mode with the rest of its API usage. On the Console [Usage](https://platform.claude.com/usage) and [Cost](https://platform.claude.com/cost) pages, select **Speed (Research Preview)** in the **Group by** menu to separate fast mode from standard-speed usage. You see that option only when the selected date range includes fast mode usage.

8888

from line 116

116116Fast mode requires all of the following:

117117

118118* **Anthropic API or subscription only**: fast mode is available through the Anthropic Console API and for Claude subscription plans using usage credits. It is not available on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or Claude Platform on AWS. Console organizations must also have [fast mode access provisioned](#enable-fast-mode-for-your-organization) to use it with Opus 5 or Opus 4.8.

119* **Usage credits turned on for subscription plans**: on a Pro, Max, Team, or Enterprise plan, your account must have [usage credits](https://code.claude.com/docs/en/costs.md#add-usage-credits-to-your-subscription) turned on, which allows billing beyond your plan's included usage. Until they're on, `/fast` reports "Fast mode requires usage credits". How you turn them on depends on your plan:

120 * On Pro and Max, turn them on in the **Usage credits** section of [**Settings > Usage**](https://claude.ai/settings/usage) on claude.ai, or run `/usage-credits` to open that page.

119* **Usage credits turned on for subscription plans**: on a Pro, Max, Ultra, Team, or Enterprise plan, your account must have [usage credits](https://code.claude.com/docs/en/costs.md#add-usage-credits-to-your-subscription) turned on, which allows billing beyond your plan's included usage. Until they're on, `/fast` reports "Fast mode requires usage credits". To turn them on, follow the step for your plan:

120 * On Pro, Max, and Ultra, turn them on in the **Usage credits** section of [**Settings > Usage**](https://claude.ai/settings/usage) on claude.ai, or run `/usage-credits` to open that page.

121121 * On Team and Enterprise, a member with billing access turns them on for the organization at [**Organization settings > Usage**](https://claude.ai/admin-settings/usage), and a member without it runs `/usage-credits` to send the organization's admins a request.

122122

123123> [!NOTE]

feature-availability Changed · +88 / -82 lines

### Ultra plan

from line 10

1010

1111How you authenticate determines which features Claude Code can reach. For a single list of what is missing on your provider, see the [summary by provider](#summary-by-provider) tabs. To find your column in the tables:

1212

13* **Claude subscription**: you sign in with a claude.ai account on the Pro, Max, Team, or Enterprise plan

13* **Claude subscription**: you sign in with a claude.ai account on the Pro, Max, Ultra, Team, or Enterprise plan

1414* **Anthropic Console**: you authenticate with an Anthropic API key or by [signing in to a Console account without one](https://code.claude.com/docs/en/authentication.md#sign-in-without-an-api-key)

1515* **Amazon Bedrock**: you use Claude models from the Amazon Bedrock model catalog and set `CLAUDE_CODE_USE_BEDROCK`. The [Mantle endpoint](https://code.claude.com/docs/en/amazon-bedrock.md#use-the-mantle-endpoint) (`CLAUDE_CODE_USE_MANTLE`) is covered by this column

1616* **Claude Platform on AWS**: you bought Claude through AWS Marketplace but call the Anthropic API, and set `CLAUDE_CODE_USE_ANTHROPIC_AWS`

from line 42

4242These require signing in with a claude.ai account and are not reachable with an Anthropic Console API key or from a third-party provider:

4343

4444* [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) and Claude Code on mobile

45* [Claude Code in Slack](https://code.claude.com/docs/en/slack.md): Pro and Max plans

45* [Claude Code in Slack](https://code.claude.com/docs/en/slack.md): Pro, Max, and Ultra plans

4646* [Claude Code Desktop](https://code.claude.com/docs/en/desktop.md)

4747* [Cloud scheduled tasks](https://code.claude.com/docs/en/routines.md) (`/schedule`)

4848* [Ultrareview](https://code.claude.com/docs/en/ultrareview.md)

from line 49

4949* [Code Review](https://code.claude.com/docs/en/code-review.md): Team and Enterprise plans

5050* [Remote Control](https://code.claude.com/docs/en/remote-control.md)

5151* [Chrome extension](https://code.claude.com/docs/en/chrome.md)

52* [Computer use](https://code.claude.com/docs/en/computer-use.md): Pro and Max plans

53* [Artifacts](https://code.claude.com/docs/en/artifacts.md): Pro, Max, Team, and Enterprise plans

52* [Computer use](https://code.claude.com/docs/en/computer-use.md): Pro, Max, and Ultra plans

53* [Artifacts](https://code.claude.com/docs/en/artifacts.md): Pro, Max, Ultra, Team, and Enterprise plans

5454* [Voice dictation](https://code.claude.com/docs/en/voice-dictation.md)

5555

5656Desktop is the partial exception: [gateway routing can be configured in the app or by an administrator](https://code.claude.com/docs/en/llm-gateway-connect.md#desktop-app). [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview) also runs the Code tab on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or a self-hosted LLM gateway. It also runs the Code tab on the [Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api) with an Anthropic Console API key. For per-plan availability of these features, see [Availability by subscription plan](#availability-by-subscription-plan).

from line 225

225225

226226Each tab lists what is unavailable or partially supported on that provider, with alternatives where one exists. Everything not listed works the same as on a Claude subscription, apart from the [provider-specific differences](#features-available-on-every-provider) noted above. On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and Claude Platform on AWS, error reporting and telemetry to Anthropic are off by default. See [default behaviors by API provider](https://code.claude.com/docs/en/data-usage.md#default-behaviors-by-api-provider) for what traffic still reaches Anthropic and how to opt out.

227227

228**Amazon Bedrock**

228> [tab] Amazon Bedrock

229>

230> **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior), [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

231>

232> **Partial support:**

233>

234> * [Desktop](https://code.claude.com/docs/en/desktop.md): only via [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

235> * [Auto mode](https://code.claude.com/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

236> * [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

237> * [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md): subject to your AWS agreement

238>

239> **Alternatives:** for scheduling, use [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](https://code.claude.com/docs/en/github-actions.md) or [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md). For web lookups, use the [WebFetch tool](https://code.claude.com/docs/en/tools-reference.md#webfetch-tool-behavior) with a specific URL.

229240

230**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior), [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

241> [tab] Claude Platform on AWS

242>

243> **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), [GitHub Actions](https://code.claude.com/docs/en/github-actions.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

244>

245> **Available where Amazon Bedrock is not:** [web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior).

246>

247> **Partial support:**

248>

249> * [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

250>

251> **Alternatives:** for scheduling, use [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md).

231252

232**Partial support:**

253> [tab] Google Cloud's Agent Platform

254>

255> **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

256>

257> **Partial support:**

258>

259> * [Desktop](https://code.claude.com/docs/en/desktop.md): via [managed settings](https://claude.com/docs/third-party/claude-desktop/configuration) or [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

260> * [Web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior): Opus 4, Sonnet 4, Haiku 4.5, and later models

261> * [Auto mode](https://code.claude.com/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

262> * [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

263> * [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md): subject to your Google Cloud agreement

264>

265> **Alternatives:** for scheduling, use [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](https://code.claude.com/docs/en/github-actions.md) or [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md).

233266

234* [Desktop](https://code.claude.com/docs/en/desktop.md): only via [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

235* [Auto mode](https://code.claude.com/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

236* [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

237* [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md): subject to your AWS agreement

267> [tab] Microsoft Foundry

268>

269> **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

270>

271> **Partial support:**

272>

273> * [Desktop](https://code.claude.com/docs/en/desktop.md): only via [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

274> * [Auto mode](https://code.claude.com/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

275> * [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

276> * [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md): subject to your Azure agreement

277>

278> **Alternatives:** for scheduling, use [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](https://code.claude.com/docs/en/github-actions.md).

238279

239**Alternatives:** for scheduling, use [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](https://code.claude.com/docs/en/github-actions.md) or [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md). For web lookups, use the [WebFetch tool](https://code.claude.com/docs/en/tools-reference.md#webfetch-tool-behavior) with a specific URL.

280> [tab] Anthropic Console

281>

282> **Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription).

283>

284> Everything in [CLI capabilities that vary by provider](#cli-capabilities-that-vary-by-provider) is available, except that [fast mode](https://code.claude.com/docs/en/fast-mode.md) with Claude Opus 5 or Claude Opus 4.8 requires [provisioned access](https://code.claude.com/docs/en/fast-mode.md#enable-fast-mode-for-your-organization). [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) that you configure in a claude.ai Team or Enterprise organization don't reach a session that authenticates with a Console API key. See [Platform availability](https://code.claude.com/docs/en/server-managed-settings.md#platform-availability) for how to cover those sessions.

285>

286> **Partial support:**

287>

288> * [Desktop](https://code.claude.com/docs/en/desktop.md): via [Claude Desktop on 3P with the Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api)

240289

241**Claude Platform on AWS**

242

243**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), [GitHub Actions](https://code.claude.com/docs/en/github-actions.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

244

245**Available where Amazon Bedrock is not:** [web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior).

246

247**Partial support:**

248

249* [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

250

251**Alternatives:** for scheduling, use [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md).

252

253**Google Cloud's Agent Platform**

254

255**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

256

257**Partial support:**

258

259* [Desktop](https://code.claude.com/docs/en/desktop.md): via [managed settings](https://claude.com/docs/third-party/claude-desktop/configuration) or [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

260* [Web search](https://code.claude.com/docs/en/tools-reference.md#websearch-tool-behavior): Opus 4, Sonnet 4, Haiku 4.5, and later models

261* [Auto mode](https://code.claude.com/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

262* [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

263* [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md): subject to your Google Cloud agreement

264

265**Alternatives:** for scheduling, use [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](https://code.claude.com/docs/en/github-actions.md) or [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md).

266

267**Microsoft Foundry**

268

269**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription), plus [fast mode](https://code.claude.com/docs/en/fast-mode.md), [Advisor](https://code.claude.com/docs/en/advisor.md), [Channels](https://code.claude.com/docs/en/channels.md), [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md), the [analytics dashboard](https://code.claude.com/docs/en/analytics.md), [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md), and the [`/design-sync` and `/import` commands](https://code.claude.com/docs/en/commands#all-commands).

270

271**Partial support:**

272

273* [Desktop](https://code.claude.com/docs/en/desktop.md): only via [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

274* [Auto mode](https://code.claude.com/docs/en/auto-mode-config.md): Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5, and Fable models only

275* [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md): between your sessions on this machine only [5](#fn5)

276* [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md): subject to your Azure agreement

277

278**Alternatives:** for scheduling, use [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) instead of `/schedule`. For cloud sessions, use [GitHub Actions](https://code.claude.com/docs/en/github-actions.md).

279

280**Anthropic Console**

281

282**Not available:** all [features that require a Claude subscription](#features-that-require-a-claude-subscription).

283

284Everything in [CLI capabilities that vary by provider](#cli-capabilities-that-vary-by-provider) is available, except that [fast mode](https://code.claude.com/docs/en/fast-mode.md) with Claude Opus 5 or Claude Opus 4.8 requires [provisioned access](https://code.claude.com/docs/en/fast-mode.md#enable-fast-mode-for-your-organization). [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) that you configure in a claude.ai Team or Enterprise organization don't reach a session that authenticates with a Console API key. See [Platform availability](https://code.claude.com/docs/en/server-managed-settings.md#platform-availability) for how to cover those sessions.

285

286**Partial support:**

287

288* [Desktop](https://code.claude.com/docs/en/desktop.md): via [Claude Desktop on 3P with the Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api)

289

290290## Availability by subscription plan

291291

292292If you authenticate through Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or an Anthropic Console API key, this section does not apply to you. When you sign in with a claude.ai account, your plan determines which of the features below are available.

from line 293

293293

294294In Enterprise organizations with the [HIPAA configuration](https://code.claude.com/docs/en/hipaa-setup.md) applied, some features in this table are turned off.

295295

296| Feature | Pro | Max | Team | Enterprise |

297| :- | :- | :- | :- | :- |

298| [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) | ✓ | ✓ | ✓ | ✓ [6](#fn6) |

299| [Cloud scheduled tasks](https://code.claude.com/docs/en/routines.md) | ✓ | ✓ | ✓ | ✓ |

300| [Remote Control](https://code.claude.com/docs/en/remote-control.md) | ✓ | ✓ | Admin-enabled | Admin-enabled |

301| [Channels](https://code.claude.com/docs/en/channels.md) | ✓ | ✓ | Admin-enabled | Admin-enabled |

302| [Computer use](https://code.claude.com/docs/en/computer-use.md) | ✓ | ✓ | ✗ | ✗ |

303| Dispatch ([Desktop](https://code.claude.com/docs/en/desktop.md#sessions-from-dispatch)) | ✓ | ✓ | ✗ | ✗ |

304| [Code Review](https://code.claude.com/docs/en/code-review.md) | ✗ | ✗ | ✓ | ✓ |

305| [Artifacts](https://code.claude.com/docs/en/artifacts.md) | ✓ | ✓ | ✓ | ✓ |

306| [Analytics dashboard and contribution metrics](https://code.claude.com/docs/en/analytics.md) | ✗ | ✗ | ✓ | ✓ |

307| [Enterprise Analytics API](https://code.claude.com/docs/en/analytics.md#access-data-programmatically) | ✗ | ✗ | ✗ | ✓ |

308| [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) | ✗ | ✗ | ✓ | ✓ |

309| [SSO](https://support.claude.com/en/articles/9266767-what-is-the-team-plan) | ✗ | ✗ | ✓ | ✓ |

310| SCIM | ✗ | ✗ | ✗ | ✓ |

311| [Compliance API](https://platform.claude.com/docs/en/api/compliance) | ✗ | ✗ | ✗ | ✓ |

312| [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md) | ✗ | ✗ | ✗ | ✓ [7](#fn7) |

296| Feature | Pro | Max | Ultra | Team | Enterprise |

297| :- | :- | :- | :- | :- | :- |

298| [Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) | ✓ | ✓ | ✓ | ✓ | ✓ [6](#fn6) |

299| [Cloud scheduled tasks](https://code.claude.com/docs/en/routines.md) | ✓ | ✓ | ✓ | ✓ | ✓ |

300| [Remote Control](https://code.claude.com/docs/en/remote-control.md) | ✓ | ✓ | ✓ | Admin-enabled | Admin-enabled |

301| [Channels](https://code.claude.com/docs/en/channels.md) | ✓ | ✓ | ✓ | Admin-enabled | Admin-enabled |

302| [Computer use](https://code.claude.com/docs/en/computer-use.md) | ✓ | ✓ | ✓ | ✗ | ✗ |

303| Dispatch ([Desktop](https://code.claude.com/docs/en/desktop.md#sessions-from-dispatch)) | ✓ | ✓ | ✓ | ✗ | ✗ |

304| [Code Review](https://code.claude.com/docs/en/code-review.md) | ✗ | ✗ | ✗ | ✓ | ✓ |

305| [Artifacts](https://code.claude.com/docs/en/artifacts.md) | ✓ | ✓ | ✓ | ✓ | ✓ |

306| [Analytics dashboard and contribution metrics](https://code.claude.com/docs/en/analytics.md) | ✗ | ✗ | ✗ | ✓ | ✓ |

307| [Enterprise Analytics API](https://code.claude.com/docs/en/analytics.md#access-data-programmatically) | ✗ | ✗ | ✗ | ✗ | ✓ |

308| [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) | ✗ | ✗ | ✗ | ✓ | ✓ |

309| [SSO](https://support.claude.com/en/articles/9266767-what-is-the-team-plan) | ✗ | ✗ | ✗ | ✓ | ✓ |

310| SCIM | ✗ | ✗ | ✗ | ✗ | ✓ |

311| [Compliance API](https://platform.claude.com/docs/en/api/compliance) | ✗ | ✗ | ✗ | ✗ | ✓ |

312| [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md) | ✗ | ✗ | ✗ | ✗ | ✓ [7](#fn7) |

313313

3143146 On Enterprise, requires a premium seat or a Chat + Claude Code seat. See [Use Claude Code in the cloud](https://code.claude.com/docs/en/claude-code-on-the-web.md).\

315315

from line 316

3163167 Not included in the standard Enterprise plan. Requires separate enablement by Anthropic for qualified accounts. See [Zero Data Retention](https://code.claude.com/docs/en/zero-data-retention.md).

317317

318318For pricing and the full plan comparison, see [Team plans](https://support.claude.com/en/articles/9266767-what-is-the-team-plan) and [Enterprise plans](https://support.claude.com/en/articles/9797531-what-is-the-enterprise-plan).

319

320### Ultra plan

321

322Ultra is the new name for the Max 20x plan, and Max is the new name for Max 5x. To check which plan you're on, see your subscription on claude.ai.

323

324In Claude Code, Max and Ultra have the same features, listed in the Max and Ultra columns of the [availability table](#availability-by-subscription-plan). For usage limits and pricing, see the [Claude pricing page](https://claude.com/pricing).

319325

320326## Model availability

321327

features-overview Changed · +210 / -210 lines

from line 68

6868

6969Some features can seem similar. For a deeper walkthrough of choosing between them, see [Steering Claude Code: when to use CLAUDE.md, skills, hooks, and subagents](https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more) on the blog. Here's how to tell them apart.

7070

71**Skill vs Subagent**

71> [tab] Skill vs Subagent

72>

73> Skills and subagents solve different problems:

74>

75> * **Skills** are reusable content you can load into any context

76> * **Subagents** are isolated workers that run separately from your main conversation

77>

78> | Aspect | Skill | Subagent |

79> | - | - | - |

80> | **What it is** | Reusable instructions, knowledge, or workflows | Isolated worker with its own context |

81> | **Key benefit** | Share content across contexts | Context isolation. Work happens separately, only summary returns |

82> | **[Context window](https://code.claude.com/docs/en/context-window.md) impact** | Adds to your main window | Uses a separate window with its own input and output tokens |

83> | **Best for** | Reference material, invocable workflows | Tasks that read many files, parallel work, specialized workers |

84>

85> **Skills can be reference or action.** Reference skills provide knowledge Claude uses throughout your session (like your API style guide). Action skills tell Claude to do something specific (like `/deploy` that runs your deployment workflow).

86>

87> **Use a subagent** when you need context isolation or when your context window is getting full. The subagent might read dozens of files or run extensive searches, but your main conversation only receives a summary. Since subagent work doesn't consume your main context, this is also useful when you don't need the intermediate work to remain visible. Custom subagents can have their own instructions and can preload skills.

88>

89> **They can combine.** A subagent can preload specific skills (`skills:` field). A skill can run in isolated context using `context: fork`. See [Skills](https://code.claude.com/docs/en/skills.md) for details.

7290

73Skills and subagents solve different problems:

91> [tab] CLAUDE.md vs Skill

92>

93> Both store instructions, but they load differently and serve different purposes.

94>

95> | Aspect | CLAUDE.md | Skill |

96> | - | - | - |

97> | **Loads** | Every session, automatically | On demand |

98> | **Can include files** | Yes, with `@path` imports | Yes, with `@path` imports |

99> | **Can trigger workflows** | No | Yes, with `/<name>` |

100> | **Best for** | "Always do X" rules | Reference material, invocable workflows |

101>

102> **Put it in CLAUDE.md** if Claude should always know it: coding conventions, build commands, project structure, "never do X" rules.

103>

104> **Put it in a skill** if it's reference material Claude needs sometimes (API docs, style guides) or a workflow you trigger with `/<name>` (deploy, review, release).

105>

106> **Rule of thumb:** Keep CLAUDE.md under 200 lines. If it's growing, move reference content to skills or split into [`.claude/rules/`](https://code.claude.com/docs/en/memory#organize-rules-with-claude/rules/) files.

74107

75* **Skills** are reusable content you can load into any context

76* **Subagents** are isolated workers that run separately from your main conversation

108> [tab] CLAUDE.md vs Output style

109>

110> Both give Claude standing instructions. CLAUDE.md carries what Claude should know, and an output style sets how Claude responds.

111>

112> | Aspect | CLAUDE.md | Output style |

113> | - | - | - |

114> | **Holds** | Facts and rules about your project | A role, tone, and response format |

115> | **Switching** | Always loaded | One active at a time; [switch styles](https://code.claude.com/docs/en/output-styles.md#change-your-output-style) whenever you want |

116> | **Best for** | Build commands, conventions, "never do X" rules | Shorter responses, explanations alongside code, a non-engineering role |

117>

118> **Put it in CLAUDE.md** if it's true of the project whatever style you're in: coding conventions, build commands, project structure.

119>

120> **Use an output style** if it's about the response itself and you might want it off again: length, format, how much Claude explains, or a different role such as a writing assistant. Claude Code includes [built-in styles](https://code.claude.com/docs/en/output-styles.md#built-in-output-styles), and you can write your own.

121>

122> **They combine.** CLAUDE.md stays loaded whichever style you pick. Claude follows both as instructions, so neither is enforced. For anything that has to happen every time, use a [hook](https://code.claude.com/docs/en/hooks-guide.md).

77123

78| Aspect | Skill | Subagent |

79| - | - | - |

80| **What it is** | Reusable instructions, knowledge, or workflows | Isolated worker with its own context |

81| **Key benefit** | Share content across contexts | Context isolation. Work happens separately, only summary returns |

82| **[Context window](https://code.claude.com/docs/en/context-window.md) impact** | Adds to your main window | Uses a separate window with its own input and output tokens |

83| **Best for** | Reference material, invocable workflows | Tasks that read many files, parallel work, specialized workers |

124> [tab] CLAUDE.md vs Rules vs Skills

125>

126> All three store instructions, but they load differently:

127>

129> | - | - | - | - |

133>

134> **Use CLAUDE.md** for instructions every session needs: build commands, test conventions, project architecture.

135>

136> **Use rules** to keep CLAUDE.md focused. Rules with [`paths` frontmatter](https://code.claude.com/docs/en/memory#path-specific-rules) only load when Claude works with matching files, saving context.

137>

138> **Use skills** for content Claude only needs sometimes, like API documentation or a deployment checklist you trigger with `/<name>`.

84139

85**Skills can be reference or action.** Reference skills provide knowledge Claude uses throughout your session (like your API style guide). Action skills tell Claude to do something specific (like `/deploy` that runs your deployment workflow).

140> [tab] Subagent vs Dynamic workflow

141>

142> Both do work outside your main conversation. With subagents, Claude decides turn by turn what runs next. In a workflow, the script decides:

143>

144> * **Subagents** are workers Claude spawns, each returning a summary to the conversation that spawned it

145> * **[Dynamic workflows](https://code.claude.com/docs/en/workflows.md)** are scripts Claude writes that run many subagents in the background and return one result

146>

147> **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, so your main conversation stays clean. Subagents that Claude [named](https://code.claude.com/docs/en/sub-agents.md#subagent-names) when it spawned them can also [message each other](https://code.claude.com/docs/en/sub-agents.md#what-loads-at-startup).

148>

149> **Use a dynamic workflow** when a job [outgrows a handful of subagents](https://code.claude.com/docs/en/workflows.md#when-to-use-a-workflow), or when you want the findings cross-checked before you see them, such as a codebase-wide audit, a large migration, or a plan drafted from several angles. To start one, [ask for a workflow in your prompt](https://code.claude.com/docs/en/workflows.md#ask-for-a-workflow-in-your-prompt).

150>

151> **To pass a finding from one of your sessions to another**, ask the first session's Claude to send it. Claude delivers it with [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md). [Run agents in parallel](https://code.claude.com/docs/en/agents.md) compares the other ways to run more than one Claude at once, including sessions you hand off and check back on later.

86152

87**Use a subagent** when you need context isolation or when your context window is getting full. The subagent might read dozens of files or run extensive searches, but your main conversation only receives a summary. Since subagent work doesn't consume your main context, this is also useful when you don't need the intermediate work to remain visible. Custom subagents can have their own instructions and can preload skills.

153> [tab] MCP vs Skill

154>

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

156>

157> | Aspect | MCP | Skill |

158> | - | - | - |

159> | **What it is** | Protocol for connecting to external services | Knowledge, workflows, and reference material |

160> | **Provides** | Tools and data access | Knowledge, workflows, reference material |

161> | **Examples** | Slack integration, database queries, browser control | Code review checklist, deploy workflow, API style guide |

162>

163> These solve different problems and work well together:

164>

165> **MCP** gives Claude purpose-built tools for an external system, with the connection and authentication handled by the server.

166>

167> **Skills** give Claude knowledge about how to use those tools effectively, plus workflows you can trigger with `/<name>`. A skill might include your team's database schema and query patterns, or a `/post-to-slack` workflow with your team's message formatting rules.

88168

89**They can combine.** A subagent can preload specific skills (`skills:` field). A skill can run in isolated context using `context: fork`. See [Skills](https://code.claude.com/docs/en/skills.md) for details.

169> [tab] Hook vs Skill

170>

171> Claude Code runs a hook at a lifecycle event; it loads a skill into context for Claude to apply.

172>

173> | Aspect | Hook | Skill |

174> | - | - | - |

175> | **Runs** | A shell command, HTTP request, MCP tool call, LLM prompt, or subagent | Instructions Claude reads and follows |

176> | **Triggered by** | [Lifecycle events](https://code.claude.com/docs/en/hooks.md#hook-events) such as `PostToolUse` or `SessionStart` | You typing `/<name>`, or Claude matching the description to your task |

177> | **Determinism** | Fires on its event without Claude deciding | Claude interprets the instructions; outcome can vary |

178> | **Context cost** | Zero unless the hook returns output | Description loads each session; full content loads when used |

179> | **Best for** | Linting after edits, blocking unsafe commands, logging, notifications | Workflows that need reasoning, reference material, multi-step tasks |

180>

181> **Use a hook** when the action must happen the same way every time and doesn't need Claude to think. For example: format on save, reject `rm -rf /`, post a Slack message when a session ends.

182>

183> **Use a skill** when Claude should decide how to apply the steps, or when the content is knowledge rather than a script. For example: a `/release` checklist, your API style guide, a debugging playbook.

184>

185> **Put guardrails in hooks.** An instruction like "never edit `.env`" in CLAUDE.md or a skill is a request, not a guarantee. A `PreToolUse` hook that blocks the edit is enforcement. If a rule must hold every time, make it a hook rather than a prompt instruction.

186>

187> **Hook output lands in context.** A `PostToolUse` hook that runs your linter feeds results back as text Claude reads; a `/fix-lint` skill tells Claude how to resolve them.

90188

91**CLAUDE.md vs Skill**

93Both store instructions, but they load differently and serve different purposes.

95| Aspect | CLAUDE.md | Skill |

96| - | - | - |

97| **Loads** | Every session, automatically | On demand |

98| **Can include files** | Yes, with `@path` imports | Yes, with `@path` imports |

99| **Can trigger workflows** | No | Yes, with `/<name>` |

100| **Best for** | "Always do X" rules | Reference material, invocable workflows |

101

102**Put it in CLAUDE.md** if Claude should always know it: coding conventions, build commands, project structure, "never do X" rules.

103

104**Put it in a skill** if it's reference material Claude needs sometimes (API docs, style guides) or a workflow you trigger with `/<name>` (deploy, review, release).

105

106**Rule of thumb:** Keep CLAUDE.md under 200 lines. If it's growing, move reference content to skills or split into [`.claude/rules/`](https://code.claude.com/docs/en/memory#organize-rules-with-claude/rules/) files.

107

108**CLAUDE.md vs Output style**

109

110Both give Claude standing instructions. CLAUDE.md carries what Claude should know, and an output style sets how Claude responds.

111

112| Aspect | CLAUDE.md | Output style |

113| - | - | - |

114| **Holds** | Facts and rules about your project | A role, tone, and response format |

115| **Switching** | Always loaded | One active at a time; [switch styles](https://code.claude.com/docs/en/output-styles.md#change-your-output-style) whenever you want |

116| **Best for** | Build commands, conventions, "never do X" rules | Shorter responses, explanations alongside code, a non-engineering role |

117

118**Put it in CLAUDE.md** if it's true of the project whatever style you're in: coding conventions, build commands, project structure.

119

120**Use an output style** if it's about the response itself and you might want it off again: length, format, how much Claude explains, or a different role such as a writing assistant. Claude Code includes [built-in styles](https://code.claude.com/docs/en/output-styles.md#built-in-output-styles), and you can write your own.

121

122**They combine.** CLAUDE.md stays loaded whichever style you pick. Claude follows both as instructions, so neither is enforced. For anything that has to happen every time, use a [hook](https://code.claude.com/docs/en/hooks-guide.md).

123

124**CLAUDE.md vs Rules vs Skills**

125

126All three store instructions, but they load differently:

127

129| - | - | - | - |

133

134**Use CLAUDE.md** for instructions every session needs: build commands, test conventions, project architecture.

135

136**Use rules** to keep CLAUDE.md focused. Rules with [`paths` frontmatter](https://code.claude.com/docs/en/memory#path-specific-rules) only load when Claude works with matching files, saving context.

137

138**Use skills** for content Claude only needs sometimes, like API documentation or a deployment checklist you trigger with `/<name>`.

139

140**Subagent vs Dynamic workflow**

141

142Both do work outside your main conversation. With subagents, Claude decides turn by turn what runs next. In a workflow, the script decides:

143

144* **Subagents** are workers Claude spawns, each returning a summary to the conversation that spawned it

145* **[Dynamic workflows](https://code.claude.com/docs/en/workflows.md)** are scripts Claude writes that run many subagents in the background and return one result

146

147**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, so your main conversation stays clean. Subagents that Claude [named](https://code.claude.com/docs/en/sub-agents.md#subagent-names) when it spawned them can also [message each other](https://code.claude.com/docs/en/sub-agents.md#what-loads-at-startup).

148

149**Use a dynamic workflow** when a job [outgrows a handful of subagents](https://code.claude.com/docs/en/workflows.md#when-to-use-a-workflow), or when you want the findings cross-checked before you see them, such as a codebase-wide audit, a large migration, or a plan drafted from several angles. To start one, [ask for a workflow in your prompt](https://code.claude.com/docs/en/workflows.md#ask-for-a-workflow-in-your-prompt).

150

151**To pass a finding from one of your sessions to another**, ask the first session's Claude to send it. Claude delivers it with [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md). [Run agents in parallel](https://code.claude.com/docs/en/agents.md) compares the other ways to run more than one Claude at once, including sessions you hand off and check back on later.

152

153**MCP vs Skill**

154

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

156

157| Aspect | MCP | Skill |

158| - | - | - |

159| **What it is** | Protocol for connecting to external services | Knowledge, workflows, and reference material |

160| **Provides** | Tools and data access | Knowledge, workflows, reference material |

161| **Examples** | Slack integration, database queries, browser control | Code review checklist, deploy workflow, API style guide |

162

163These solve different problems and work well together:

164

165**MCP** gives Claude purpose-built tools for an external system, with the connection and authentication handled by the server.

166

167**Skills** give Claude knowledge about how to use those tools effectively, plus workflows you can trigger with `/<name>`. A skill might include your team's database schema and query patterns, or a `/post-to-slack` workflow with your team's message formatting rules.

168

169**Hook vs Skill**

170

171Claude Code runs a hook at a lifecycle event; it loads a skill into context for Claude to apply.

172

173| Aspect | Hook | Skill |

174| - | - | - |

175| **Runs** | A shell command, HTTP request, MCP tool call, LLM prompt, or subagent | Instructions Claude reads and follows |

176| **Triggered by** | [Lifecycle events](https://code.claude.com/docs/en/hooks.md#hook-events) such as `PostToolUse` or `SessionStart` | You typing `/<name>`, or Claude matching the description to your task |

177| **Determinism** | Fires on its event without Claude deciding | Claude interprets the instructions; outcome can vary |

178| **Context cost** | Zero unless the hook returns output | Description loads each session; full content loads when used |

179| **Best for** | Linting after edits, blocking unsafe commands, logging, notifications | Workflows that need reasoning, reference material, multi-step tasks |

180

181**Use a hook** when the action must happen the same way every time and doesn't need Claude to think. For example: format on save, reject `rm -rf /`, post a Slack message when a session ends.

182

183**Use a skill** when Claude should decide how to apply the steps, or when the content is knowledge rather than a script. For example: a `/release` checklist, your API style guide, a debugging playbook.

184

185**Put guardrails in hooks.** An instruction like "never edit `.env`" in CLAUDE.md or a skill is a request, not a guarantee. A `PreToolUse` hook that blocks the edit is enforcement. If a rule must hold every time, make it a hook rather than a prompt instruction.

186

187**Hook output lands in context.** A `PostToolUse` hook that runs your linter feeds results back as text Claude reads; a `/fix-lint` skill tells Claude how to resolve them.

188

189189### Understand how features layer

190190

191191Features can be defined at multiple levels: user-wide, per-project, via plugins, or through managed policies. You can also nest CLAUDE.md files in subdirectories or place skills in specific packages of a monorepo. When the same feature exists at multiple levels, here's how they layer:

from line 234

234234

235235![Context loading: CLAUDE.md loads at session start and stays in every request. MCP tool names load at start with full schemas deferred until use. Skills load descriptions at start, full content on invocation. Subagents get isolated context. Hooks run externally.](https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/context-loading.svg?fit=max\&auto=format\&n=ikqp3_70mqIahteV\&q=85\&s=aab139e750494a237ae2e0c8f9139b0a)

236236

237**CLAUDE.md**

238

239**When:** Session start

240

241**What loads:** Full content of each CLAUDE.md file that loads at session start (managed, user, and project levels).

242

243**Inheritance:** Claude reads CLAUDE.md files from your working directory up to the root, and discovers nested ones in subdirectories as it accesses those files. See [How CLAUDE.md files load](https://code.claude.com/docs/en/memory.md#how-claude-md-files-load) for details. If a nested CLAUDE.md is over its [per-file size limit](https://code.claude.com/docs/en/memory.md#claude-ignores-the-end-of-my-subdirectory-claude-md), Claude receives only the start of the file.

244

245> [!TIP]

237> [tab] CLAUDE.md

246238>

247> Keep CLAUDE.md under 200 lines. Move reference material to skills, which load on demand. To get [trim proposals for a checked-in CLAUDE.md](https://code.claude.com/docs/en/memory.md#my-claude-md-is-too-large), run `/doctor`.

239> **When:** Session start

240>

241> **What loads:** Full content of each CLAUDE.md file that loads at session start (managed, user, and project levels).

242>

243> **Inheritance:** Claude reads CLAUDE.md files from your working directory up to the root, and discovers nested ones in subdirectories as it accesses those files. See [How CLAUDE.md files load](https://code.claude.com/docs/en/memory.md#how-claude-md-files-load) for details. If a nested CLAUDE.md is over its [per-file size limit](https://code.claude.com/docs/en/memory.md#claude-ignores-the-end-of-my-subdirectory-claude-md), Claude receives only the start of the file.

244>

245> > [!TIP]

246> >

247> > Keep CLAUDE.md under 200 lines. Move reference material to skills, which load on demand. To get [trim proposals for a checked-in CLAUDE.md](https://code.claude.com/docs/en/memory.md#my-claude-md-is-too-large), run `/doctor`.

248248

249**Skills**

250

251Skills are extra capabilities in Claude's toolkit. They can be reference material (like an API style guide) or invocable workflows you trigger with `/<name>` (like `/deploy`). Claude Code includes [bundled skills](https://code.claude.com/docs/en/commands.md) like `/code-review`, `/batch`, and `/debug` that work without setup. You can also create your own.

252

253**When:** Depends on the skill's configuration. By default, descriptions load at session start and full content loads when used. For user-only skills (`disable-model-invocation: true`), nothing loads until you invoke them.

254

255**What loads:** For model-invocable skills, Claude sees names and descriptions in every request. When you invoke a skill with `/<name>` or Claude loads it automatically, the full content loads into your conversation.

256

257**How Claude chooses skills:** Claude matches your task against skill descriptions to decide which are relevant. If descriptions are vague or overlap, Claude may load the wrong skill or miss one that would help. To tell Claude to use a specific skill, invoke it with `/<name>`.

258

259**Context cost:** Low until used. User-only skills have zero cost until invoked.

260

261**In subagents:** The full content of skills listed in a subagent's `skills` field [loads into its context at launch](https://code.claude.com/docs/en/sub-agents.md#preload-skills-into-subagents), rather than on demand. Subagents can still discover and invoke unlisted project, user, and plugin skills through the Skill tool.

262

263> [!TIP]

249> [tab] Skills

264250>

265> Use `disable-model-invocation: true` for skills with side effects. This saves context and ensures they run only when you name them.

251> Skills are extra capabilities in Claude's toolkit. They can be reference material (like an API style guide) or invocable workflows you trigger with `/<name>` (like `/deploy`). Claude Code includes [bundled skills](https://code.claude.com/docs/en/commands.md) like `/code-review`, `/batch`, and `/debug` that work without setup. You can also create your own.

252>

253> **When:** Depends on the skill's configuration. By default, descriptions load at session start and full content loads when used. For user-only skills (`disable-model-invocation: true`), nothing loads until you invoke them.

254>

255> **What loads:** For model-invocable skills, Claude sees names and descriptions in every request. When you invoke a skill with `/<name>` or Claude loads it automatically, the full content loads into your conversation.

256>

257> **How Claude chooses skills:** Claude matches your task against skill descriptions to decide which are relevant. If descriptions are vague or overlap, Claude may load the wrong skill or miss one that would help. To tell Claude to use a specific skill, invoke it with `/<name>`.

258>

259> **Context cost:** Low until used. User-only skills have zero cost until invoked.

260>

261> **In subagents:** The full content of skills listed in a subagent's `skills` field [loads into its context at launch](https://code.claude.com/docs/en/sub-agents.md#preload-skills-into-subagents), rather than on demand. Subagents can still discover and invoke unlisted project, user, and plugin skills through the Skill tool.

262>

263> > [!TIP]

264> >

265> > Use `disable-model-invocation: true` for skills with side effects. This saves context and ensures they run only when you name them.

266266

267**MCP servers**

268

269**When:** Session start.

270

271**What loads:** Tool names and server instructions from connected servers. Full JSON schemas stay deferred until Claude needs a specific tool.

272

273**Context cost:** [Tool search](https://code.claude.com/docs/en/mcp.md#scale-with-mcp-tool-search) is on by default, so idle MCP tools consume minimal context.

274

275> [!TIP]

267> [tab] MCP servers

276268>

277> Run `/mcp` to see each server's connection status. Run `/context all` to see how many tokens each loaded MCP tool uses. Claude Code [reconnects to remote servers automatically](https://code.claude.com/docs/en/mcp.md#automatic-reconnection) if they drop, and you can disconnect servers you're not actively using.

269> **When:** Session start.

270>

271> **What loads:** Tool names and server instructions from connected servers. Full JSON schemas stay deferred until Claude needs a specific tool.

272>

273> **Context cost:** [Tool search](https://code.claude.com/docs/en/mcp.md#scale-with-mcp-tool-search) is on by default, so idle MCP tools consume minimal context.

274>

275> > [!TIP]

276> >

277> > Run `/mcp` to see each server's connection status. Run `/context all` to see how many tokens each loaded MCP tool uses. Claude Code [reconnects to remote servers automatically](https://code.claude.com/docs/en/mcp.md#automatic-reconnection) if they drop, and you can disconnect servers you're not actively using.

278278

279**Code intelligence**

280

281**When:** After file edits, and on demand when Claude navigates code.

282

283**What loads:** Type errors and warnings after each file edit. Definition, reference, and type information when Claude looks up a symbol.

284

285**Context cost:** Low. Symbol lookups often replace broad file reads, so net context use can go down.

286

287> [!TIP]

279> [tab] Code intelligence

288280>

289> The LSP tool is inactive until you install a [code intelligence plugin](https://code.claude.com/docs/en/plugins/code-intelligence.md) for your language.

281> **When:** After file edits, and on demand when Claude navigates code.

282>

283> **What loads:** Type errors and warnings after each file edit. Definition, reference, and type information when Claude looks up a symbol.

284>

285> **Context cost:** Low. Symbol lookups often replace broad file reads, so net context use can go down.

286>

287> > [!TIP]

288> >

289> > The LSP tool is inactive until you install a [code intelligence plugin](https://code.claude.com/docs/en/plugins/code-intelligence.md) for your language.

290290

291**Subagents**

292

293**When:** On demand, when you or Claude spawns one for a task.

294

295**What loads:** Fresh, isolated context containing:

296

297* The agent's own system prompt, not the Claude Code system prompt

298* Full content of skills listed in the agent's `skills:` field

299* CLAUDE.md and git status. The built-in Explore and Plan agents [start with neither](https://code.claude.com/docs/en/sub-agents.md#what-loads-at-startup), and an agent whose definition sets [`omitClaudeMd`](https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields) starts without the user, project, and local CLAUDE.md files.

300* Whatever context the lead agent passes in the prompt

301

302For a [fork](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation), Claude Code loads the parent's conversation so far, system prompt, and tools instead.

303

304**Context cost:** Isolated from main session.

305

306> [!TIP]

291> [tab] Subagents

307292>

308> Use subagents for work that doesn't need your full conversation context. Their isolation prevents bloating your main session.

293> **When:** On demand, when you or Claude spawns one for a task.

294>

295> **What loads:** Fresh, isolated context containing:

296>

297> * The agent's own system prompt, not the Claude Code system prompt

298> * Full content of skills listed in the agent's `skills:` field

299> * CLAUDE.md and git status. The built-in Explore and Plan agents [start with neither](https://code.claude.com/docs/en/sub-agents.md#what-loads-at-startup), and an agent whose definition sets [`omitClaudeMd`](https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields) starts without the user, project, and local CLAUDE.md files.

300> * Whatever context the lead agent passes in the prompt

301>

302> For a [fork](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation), Claude Code loads the parent's conversation so far, system prompt, and tools instead.

303>

304> **Context cost:** Isolated from main session.

305>

306> > [!TIP]

307> >

308> > Use subagents for work that doesn't need your full conversation context. Their isolation prevents bloating your main session.

309309

310**Hooks**

311

312**When:** On trigger. Claude Code runs hooks at specific lifecycle events like tool execution, session boundaries, prompt submission, permission requests, and compaction. See [Hooks](https://code.claude.com/docs/en/hooks.md) for the full list.

313

314**What loads:** Nothing by default. Hooks execute outside the main conversation.

315

316**Context cost:** Zero, unless the hook returns output that gets added as messages to your conversation.

317

318> [!TIP]

310> [tab] Hooks

319311>

320> Hooks are ideal for side effects (linting, logging) that don't need to affect Claude's context.

312> **When:** On trigger. Claude Code runs hooks at specific lifecycle events like tool execution, session boundaries, prompt submission, permission requests, and compaction. See [Hooks](https://code.claude.com/docs/en/hooks.md) for the full list.

313>

314> **What loads:** Nothing by default. Hooks execute outside the main conversation.

315>

316> **Context cost:** Zero, unless the hook returns output that gets added as messages to your conversation.

317>

318> > [!TIP]

319> >

320> > Hooks are ideal for side effects (linting, logging) that don't need to affect Claude's context.

321321

322322## Learn more

323323

324324Each feature has its own guide with setup instructions, examples, and configuration options.

325325

326> **[CLAUDE.md](https://code.claude.com/docs/en/memory.md)**

326> [card] [CLAUDE.md](https://code.claude.com/docs/en/memory.md)

327327>

328328> Store project context, conventions, and instructions

329329

330> **[Skills](https://code.claude.com/docs/en/skills.md)**

330> [card] [Skills](https://code.claude.com/docs/en/skills.md)

331331>

332332> Give Claude domain expertise and reusable workflows

333333

334> **[Subagents](https://code.claude.com/docs/en/sub-agents.md)**

334> [card] [Subagents](https://code.claude.com/docs/en/sub-agents.md)

335335>

336336> Offload work to isolated context

337337

338> **[Dynamic workflows](https://code.claude.com/docs/en/workflows.md)**

338> [card] [Dynamic workflows](https://code.claude.com/docs/en/workflows.md)

339339>

340340> Run many subagents from one script

341341

342> **[Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md)**

342> [card] [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md)

343343>

344344> Let Claude message your other sessions

345345

346> **[MCP](https://code.claude.com/docs/en/mcp.md)**

346> [card] [MCP](https://code.claude.com/docs/en/mcp.md)

347347>

348348> Connect Claude to external services

349349

350> **[Hooks](https://code.claude.com/docs/en/hooks-guide.md)**

350> [card] [Hooks](https://code.claude.com/docs/en/hooks-guide.md)

351351>

352352> Automate actions with hooks

353353

354> **[Plugins](https://code.claude.com/docs/en/plugins/overview.md)**

354> [card] [Plugins](https://code.claude.com/docs/en/plugins/overview.md)

355355>

356356> Bundle and share feature sets

357357

358> **[Marketplaces](https://code.claude.com/docs/en/plugins/create-marketplace.md)**

358> [card] [Marketplaces](https://code.claude.com/docs/en/plugins/create-marketplace.md)

359359>

360360> Host and distribute plugin collections

361361

github-actions-cloud-providers Changed · +198 / -198 lines

from line 55

5555

5656Configure your cloud to trust the OIDC token that GitHub issues to the workflow, so each workflow run gets short-lived cloud credentials. The bullets in each tab summarize what to create, and each tab links the cloud vendor's own guide for the console-level steps.

5757

58**Amazon Bedrock**

58> [tab] Amazon Bedrock

59>

60> Create the trust configuration in your AWS account, following the [AWS guide to creating OIDC identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html):

61>

62> * Add a GitHub OIDC identity provider with provider URL `https://token.actions.githubusercontent.com` and audience `sts.amazonaws.com`

63> * Create an IAM role trusted by that provider as a web identity, and attach the scoped invocation policy from [IAM configuration](https://code.claude.com/docs/en/amazon-bedrock.md#iam-configuration), which grants `bedrock:InvokeModel`, `bedrock:InvokeModelWithResponseStream`, `bedrock:ListInferenceProfiles`, and `bedrock:GetInferenceProfile`, along with two `aws-marketplace` subscription actions

64> * Limit the role's trust policy to your repository with a subject condition such as `repo:your-org/your-repo:*`. See [GitHub's OIDC hardening guide](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) for the claim format

65>

66> Note the role's ARN. You add it as a secret in the next step.

5967

60Create the trust configuration in your AWS account, following the [AWS guide to creating OIDC identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html):

68> [tab] Google Cloud's Agent Platform

69>

70> Create the federation resources in your Google Cloud project, following the [Workload Identity Federation documentation](https://cloud.google.com/iam/docs/workload-identity-federation):

71>

72> * Enable three APIs: IAM Credentials, Security Token Service (STS), and the Agent Platform API, whose service name is `aiplatform.googleapis.com`

73> * Create a Workload Identity Pool with a GitHub OIDC provider whose issuer is `https://token.actions.githubusercontent.com`, and add an attribute condition that limits the pool to your repository

74> * Create a dedicated service account with only the `Vertex AI User` role, which is `roles/aiplatform.user`, and allow the pool to impersonate it

75>

76> Note the provider's full resource name and the service account's email address. You add them as secrets in the next step.

6177

62* Add a GitHub OIDC identity provider with provider URL `https://token.actions.githubusercontent.com` and audience `sts.amazonaws.com`

63* Create an IAM role trusted by that provider as a web identity, and attach the scoped invocation policy from [IAM configuration](https://code.claude.com/docs/en/amazon-bedrock.md#iam-configuration), which grants `bedrock:InvokeModel`, `bedrock:InvokeModelWithResponseStream`, `bedrock:ListInferenceProfiles`, and `bedrock:GetInferenceProfile`, along with two `aws-marketplace` subscription actions

64* Limit the role's trust policy to your repository with a subject condition such as `repo:your-org/your-repo:*`. See [GitHub's OIDC hardening guide](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) for the claim format

78> [tab] Microsoft Foundry

79>

80> Create a Microsoft Entra application with a federated credential for your repository, following [Microsoft's guide to authenticating from GitHub Actions](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect):

81>

82> * Register a Microsoft Entra application and add a federated identity credential that trusts tokens GitHub issues to your repository. A user-assigned managed identity works in place of an application. Both have the client ID you note below

83> * Assign the application the `Azure AI User` role on your Foundry resource. See [Azure RBAC configuration](https://code.claude.com/docs/en/microsoft-foundry.md#azure-rbac-configuration) for a narrower custom role

84>

85> Note the application's client ID, your tenant ID, and your subscription ID. You add them as secrets in the next step.

6586

66Note the role's ARN. You add it as a secret in the next step.

68**Google Cloud's Agent Platform**

70Create the federation resources in your Google Cloud project, following the [Workload Identity Federation documentation](https://cloud.google.com/iam/docs/workload-identity-federation):

72* Enable three APIs: IAM Credentials, Security Token Service (STS), and the Agent Platform API, whose service name is `aiplatform.googleapis.com`

73* Create a Workload Identity Pool with a GitHub OIDC provider whose issuer is `https://token.actions.githubusercontent.com`, and add an attribute condition that limits the pool to your repository

74* Create a dedicated service account with only the `Vertex AI User` role, which is `roles/aiplatform.user`, and allow the pool to impersonate it

76Note the provider's full resource name and the service account's email address. You add them as secrets in the next step.

78**Microsoft Foundry**

80Create a Microsoft Entra application with a federated credential for your repository, following [Microsoft's guide to authenticating from GitHub Actions](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure-openid-connect):

82* Register a Microsoft Entra application and add a federated identity credential that trusts tokens GitHub issues to your repository. A user-assigned managed identity works in place of an application. Both have the client ID you note below

83* Assign the application the `Azure AI User` role on your Foundry resource. See [Azure RBAC configuration](https://code.claude.com/docs/en/microsoft-foundry.md#azure-rbac-configuration) for a narrower custom role

85Note the application's client ID, your tenant ID, and your subscription ID. You add them as secrets in the next step.

8787**3. Add repository secrets**

8888

8989In the repository where the Claude Code GitHub Action runs, add the secrets for your provider, plus the two app secrets if you created a custom GitHub App in the first step. See GitHub's guide to [using secrets in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).

from line 112

112112>

113113> On public repositories, a comment containing the trigger phrase from any user starts this workflow. The credential steps run before the Claude Code GitHub Action checks the commenter's write access, so the action rejects unauthorized users only after the workflow has generated an App token and signed in to your cloud provider, which leaves audit-log entries and consumes Actions minutes. To avoid those runs, add a step that verifies the commenter's write access before the credential steps.

114114

115**Amazon Bedrock**

115> [tab] Amazon Bedrock

116>

117> Replace the `aws-region` value with your own. The credentials step exports it as `AWS_REGION` for the rest of the job.

118>

119> ```yaml theme={null}

120> name: Claude PR Action

121>

122> permissions:

123> contents: write

124> pull-requests: write

125> issues: write

126> id-token: write

127>

128> on:

129> issue_comment:

130> types: [created]

131> pull_request_review_comment:

132> types: [created]

133> issues:

134> types: [opened]

135>

136> jobs:

137> claude-pr:

138> if: |

139> (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||

140> (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||

141> (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

142> runs-on: ubuntu-latest

143> steps:

144> - name: Checkout repository

145> uses: actions/checkout@v6

146>

147> - name: Generate GitHub App token

148> id: app-token

149> uses: actions/create-github-app-token@v2

150> with:

151> app-id: ${{ secrets.APP_ID }}

152> private-key: ${{ secrets.APP_PRIVATE_KEY }}

153>

154> - name: Configure AWS Credentials (OIDC)

155> uses: aws-actions/configure-aws-credentials@v4

156> with:

157> role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}

158> aws-region: us-west-2

159>

160> - uses: anthropics/claude-code-action@v1

161> with:

162> github_token: ${{ steps.app-token.outputs.token }}

163> use_bedrock: "true"

164> claude_args: '--model us.anthropic.claude-sonnet-4-6'

165> ```

166>

167> > [!TIP]

168> >

169> > Bedrock model IDs include a cross-region inference profile prefix such as `us.`. Use the prefix for the region group where you granted model access.

116170

117Replace the `aws-region` value with your own. The credentials step exports it as `AWS_REGION` for the rest of the job.

118

119```yaml theme={null}

120name: Claude PR Action

121

122permissions:

123 contents: write

124 pull-requests: write

125 issues: write

126 id-token: write

127

128on:

129 issue_comment:

130 types: [created]

131 pull_request_review_comment:

132 types: [created]

133 issues:

134 types: [opened]

135

136jobs:

137 claude-pr:

138 if: |

139 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||

140 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||

141 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

142 runs-on: ubuntu-latest

143 steps:

144 - name: Checkout repository

145 uses: actions/checkout@v6

146

147 - name: Generate GitHub App token

148 id: app-token

149 uses: actions/create-github-app-token@v2

150 with:

151 app-id: ${{ secrets.APP_ID }}

152 private-key: ${{ secrets.APP_PRIVATE_KEY }}

153

154 - name: Configure AWS Credentials (OIDC)

155 uses: aws-actions/configure-aws-credentials@v4

156 with:

157 role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}

158 aws-region: us-west-2

159

160 - uses: anthropics/claude-code-action@v1

161 with:

162 github_token: ${{ steps.app-token.outputs.token }}

163 use_bedrock: "true"

164 claude_args: '--model us.anthropic.claude-sonnet-4-6'

165```

166

167> [!TIP]

171> [tab] Google Cloud's Agent Platform

168172>

169> Bedrock model IDs include a cross-region inference profile prefix such as `us.`. Use the prefix for the region group where you granted model access.

173> Replace the `CLOUD_ML_REGION` value with your own. You don't need to hardcode the project ID, because the workflow reads it from the `auth` step's output.

174>

175> ```yaml theme={null}

176> name: Claude PR Action

177>

178> permissions:

179> contents: write

180> pull-requests: write

181> issues: write

182> id-token: write

183>

184> on:

185> issue_comment:

186> types: [created]

187> pull_request_review_comment:

188> types: [created]

189> issues:

190> types: [opened]

191>

192> jobs:

193> claude-pr:

194> if: |

195> (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||

196> (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||

197> (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

198> runs-on: ubuntu-latest

199> steps:

200> - name: Checkout repository

201> uses: actions/checkout@v6

202>

203> - name: Generate GitHub App token

204> id: app-token

205> uses: actions/create-github-app-token@v2

206> with:

207> app-id: ${{ secrets.APP_ID }}

208> private-key: ${{ secrets.APP_PRIVATE_KEY }}

209>

210> - name: Authenticate to Google Cloud

211> id: auth

212> uses: google-github-actions/auth@v2

213> with:

214> workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}

215> service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

216>

217> - uses: anthropics/claude-code-action@v1

218> with:

219> github_token: ${{ steps.app-token.outputs.token }}

220> use_vertex: "true"

221> claude_args: '--model claude-sonnet-5'

222> env:

223> ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}

224> CLOUD_ML_REGION: us-east5

225> ```

170226

171**Google Cloud's Agent Platform**

172

173Replace the `CLOUD_ML_REGION` value with your own. You don't need to hardcode the project ID, because the workflow reads it from the `auth` step's output.

174

175```yaml theme={null}

176name: Claude PR Action

177

178permissions:

179 contents: write

180 pull-requests: write

181 issues: write

182 id-token: write

183

184on:

185 issue_comment:

186 types: [created]

187 pull_request_review_comment:

188 types: [created]

189 issues:

190 types: [opened]

191

192jobs:

193 claude-pr:

194 if: |

195 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||

196 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||

197 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

198 runs-on: ubuntu-latest

199 steps:

200 - name: Checkout repository

201 uses: actions/checkout@v6

202

203 - name: Generate GitHub App token

204 id: app-token

205 uses: actions/create-github-app-token@v2

206 with:

207 app-id: ${{ secrets.APP_ID }}

208 private-key: ${{ secrets.APP_PRIVATE_KEY }}

209

210 - name: Authenticate to Google Cloud

211 id: auth

212 uses: google-github-actions/auth@v2

213 with:

214 workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}

215 service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

216

217 - uses: anthropics/claude-code-action@v1

218 with:

219 github_token: ${{ steps.app-token.outputs.token }}

220 use_vertex: "true"

221 claude_args: '--model claude-sonnet-5'

222 env:

223 ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}

224 CLOUD_ML_REGION: us-east5

225```

226

227**Microsoft Foundry**

228

229Replace `your-resource-name` with your Foundry resource name. Claude Code builds the endpoint URL from it. The `azure/login` step signs in with the workflow's OIDC token, and Claude Code picks up the credentials through the Azure [default credential chain](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview).

230

231```yaml theme={null}

232name: Claude PR Action

233

234permissions:

235 contents: write

236 pull-requests: write

237 issues: write

238 id-token: write

239

240on:

241 issue_comment:

242 types: [created]

243 pull_request_review_comment:

244 types: [created]

245 issues:

246 types: [opened]

247

248jobs:

249 claude-pr:

250 if: |

251 (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||

252 (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||

253 (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

254 runs-on: ubuntu-latest

255 steps:

256 - name: Checkout repository

257 uses: actions/checkout@v6

258

259 - name: Generate GitHub App token

260 id: app-token

261 uses: actions/create-github-app-token@v2

262 with:

263 app-id: ${{ secrets.APP_ID }}

264 private-key: ${{ secrets.APP_PRIVATE_KEY }}

265

266 - name: Authenticate to Azure

267 uses: azure/login@v2

268 with:

269 client-id: ${{ secrets.AZURE_CLIENT_ID }}

270 tenant-id: ${{ secrets.AZURE_TENANT_ID }}

271 subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

272

273 - uses: anthropics/claude-code-action@v1

274 with:

275 github_token: ${{ steps.app-token.outputs.token }}

276 use_foundry: "true"

277 claude_args: '--model claude-sonnet-5'

278 env:

279 ANTHROPIC_FOUNDRY_RESOURCE: your-resource-name

280```

281

282> [!TIP]

227> [tab] Microsoft Foundry

283228>

284> Use a model ID that matches a Claude deployment in your Foundry resource. See [Claude Code on Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md) for model configuration and version pinning.

229> Replace `your-resource-name` with your Foundry resource name. Claude Code builds the endpoint URL from it. The `azure/login` step signs in with the workflow's OIDC token, and Claude Code picks up the credentials through the Azure [default credential chain](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview).

230>

231> ```yaml theme={null}

232> name: Claude PR Action

233>

234> permissions:

235> contents: write

236> pull-requests: write

237> issues: write

238> id-token: write

239>

240> on:

241> issue_comment:

242> types: [created]

243> pull_request_review_comment:

244> types: [created]

245> issues:

246> types: [opened]

247>

248> jobs:

249> claude-pr:

250> if: |

251> (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||

252> (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||

253> (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

254> runs-on: ubuntu-latest

255> steps:

256> - name: Checkout repository

257> uses: actions/checkout@v6

258>

259> - name: Generate GitHub App token

260> id: app-token

261> uses: actions/create-github-app-token@v2

262> with:

263> app-id: ${{ secrets.APP_ID }}

264> private-key: ${{ secrets.APP_PRIVATE_KEY }}

265>

266> - name: Authenticate to Azure

267> uses: azure/login@v2

268> with:

269> client-id: ${{ secrets.AZURE_CLIENT_ID }}

270> tenant-id: ${{ secrets.AZURE_TENANT_ID }}

271> subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

272>

273> - uses: anthropics/claude-code-action@v1

274> with:

275> github_token: ${{ steps.app-token.outputs.token }}

276> use_foundry: "true"

277> claude_args: '--model claude-sonnet-5'

278> env:

279> ANTHROPIC_FOUNDRY_RESOURCE: your-resource-name

280> ```

281>

282> > [!TIP]

283> >

284> > Use a model ID that matches a Claude deployment in your Foundry resource. See [Claude Code on Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry.md) for model configuration and version pinning.

285285

286286With any provider, you can bound run length and cost by adding `--max-turns` to `claude_args`. See [Manage costs](https://code.claude.com/docs/en/github-actions.md#manage-costs).

287287

gitlab-ci-cd Changed · +53 / -53 lines

### Prerequisites ### Setup instructions ### Prerequisites ### Setup instructions

from line 154

154154

155155For enterprise environments, you can run Claude Code entirely on your cloud infrastructure with the same developer experience.

156156

157**Amazon Bedrock**

157> [tab] Amazon Bedrock

158>

159> ### Prerequisites

160>

161> Before setting up Claude Code with Amazon Bedrock, you need:

162>

163> 1. An AWS account with Amazon Bedrock access to the desired Claude models

164> 2. GitLab configured as an OIDC identity provider in AWS IAM

165> 3. An IAM role with Amazon Bedrock permissions and a trust policy restricted to your GitLab project/refs

166> 4. GitLab CI/CD variables for role assumption:

167> * `AWS_ROLE_TO_ASSUME` (role ARN)

168> * `AWS_REGION` (Amazon Bedrock region)

169>

170> ### Setup instructions

171>

172> Configure AWS to allow GitLab CI jobs to assume an IAM role via OIDC (no static keys).

173>

174> **Required setup:**

175>

176> 1. Enable Amazon Bedrock and request access to your target Claude models

177> 2. Create an IAM OIDC provider for GitLab if not already present

178> 3. Create an IAM role trusted by the GitLab OIDC provider, restricted to your project and protected refs

179> 4. Attach least-privilege permissions for Amazon Bedrock invoke APIs

180>

181> Use the [Amazon Bedrock job example](#configuration-examples) to exchange the job's OIDC token for temporary AWS credentials at runtime.

158182

159### Prerequisites

160

161Before setting up Claude Code with Amazon Bedrock, you need:

162

1631. An AWS account with Amazon Bedrock access to the desired Claude models

1642. GitLab configured as an OIDC identity provider in AWS IAM

1653. An IAM role with Amazon Bedrock permissions and a trust policy restricted to your GitLab project/refs

1664. GitLab CI/CD variables for role assumption:

167 * `AWS_ROLE_TO_ASSUME` (role ARN)

168 * `AWS_REGION` (Amazon Bedrock region)

169

170### Setup instructions

171

172Configure AWS to allow GitLab CI jobs to assume an IAM role via OIDC (no static keys).

173

174**Required setup:**

175

1761. Enable Amazon Bedrock and request access to your target Claude models

1772. Create an IAM OIDC provider for GitLab if not already present

1783. Create an IAM role trusted by the GitLab OIDC provider, restricted to your project and protected refs

1794. Attach least-privilege permissions for Amazon Bedrock invoke APIs

180

181Use the [Amazon Bedrock job example](#configuration-examples) to exchange the job's OIDC token for temporary AWS credentials at runtime.

182

183**Google Cloud's Agent Platform**

184

185### Prerequisites

186

187Before setting up Claude Code with Google Cloud's Agent Platform, you need:

188

1891. A Google Cloud project with:

190 * Google Cloud's Agent Platform API enabled

191 * Workload Identity Federation configured to trust GitLab OIDC

1922. A dedicated service account with only the required Google Cloud's Agent Platform roles

1933. GitLab CI/CD variables:

194 * `GCP_WORKLOAD_IDENTITY_PROVIDER` (provider resource name without the `//iam.googleapis.com/` prefix, such as `projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider`)

195 * `GCP_SERVICE_ACCOUNT` (service account email)

196 * `GCP_PROJECT_ID` (Google Cloud project ID)

197

198### Setup instructions

199

200Configure Google Cloud to allow GitLab CI jobs to impersonate a service account via Workload Identity Federation.

201

202**Required setup:**

203

2041. Enable IAM Credentials API, STS API, and Google Cloud's Agent Platform API

2052. Create a Workload Identity Pool and provider for GitLab OIDC

2063. Create a dedicated service account with Google Cloud's Agent Platform roles

2074. Grant the WIF principal permission to impersonate the service account

208

209Use the [Agent Platform job example](#configuration-examples) to authenticate without storing keys.

183> [tab] Google Cloud's Agent Platform

184>

185> ### Prerequisites

186>

187> Before setting up Claude Code with Google Cloud's Agent Platform, you need:

188>

189> 1. A Google Cloud project with:

190> * Google Cloud's Agent Platform API enabled

191> * Workload Identity Federation configured to trust GitLab OIDC

192> 2. A dedicated service account with only the required Google Cloud's Agent Platform roles

193> 3. GitLab CI/CD variables:

194> * `GCP_WORKLOAD_IDENTITY_PROVIDER` (provider resource name without the `//iam.googleapis.com/` prefix, such as `projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider`)

195> * `GCP_SERVICE_ACCOUNT` (service account email)

196> * `GCP_PROJECT_ID` (Google Cloud project ID)

197>

198> ### Setup instructions

199>

200> Configure Google Cloud to allow GitLab CI jobs to impersonate a service account via Workload Identity Federation.

201>

202> **Required setup:**

203>

204> 1. Enable IAM Credentials API, STS API, and Google Cloud's Agent Platform API

205> 2. Create a Workload Identity Pool and provider for GitLab OIDC

206> 3. Create a dedicated service account with Google Cloud's Agent Platform roles

207> 4. Grant the WIF principal permission to impersonate the service account

208>

209> Use the [Agent Platform job example](#configuration-examples) to authenticate without storing keys.

210210

211211## Configuration examples

212212

glossary Changed · +5 / -2 lines

from line 50

5050

5151### Auto mode

5252

53A [permission mode](#permission-mode) where a separate classifier model reviews actions instead of you, so Claude Code runs most of them without asking you. Claude Code still asks you before actions your explicit ask rules match. With Claude Code v2.1.283 or later, auto mode is the [built-in starting permission mode](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in) for interactive terminal and VS Code sessions, and on earlier versions only on Pro, Max, and Team plans. The classifier blocks scope escalation, untrusted infrastructure, and [prompt injection](#prompt-injection). Tool results are stripped from what it sees, so hostile content in a file or web page can't manipulate it directly.

53A [permission mode](#permission-mode) where a separate classifier model reviews actions instead of you, so Claude Code runs most of them without asking you. Claude Code still asks you before actions your explicit ask rules match. The classifier blocks scope escalation, untrusted infrastructure, and [prompt injection](#prompt-injection). Tool results are stripped from what it sees, so hostile content in a file or web page can't manipulate it directly.

5454

55* **Claude Code v2.1.283 or later**: auto mode is the [built-in starting permission mode](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in) for interactive terminal and VS Code sessions

56* **Earlier versions**: auto mode is the built-in starting permission mode only on Pro, Max, Ultra, and Team plans

5558Learn more: [Eliminate prompts with auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode)

5659

5760## B

from line 139

136139

137140### Dispatch

138141

139A phone-initiated task router that spawns a Claude Code session in the Desktop app when you send a coding task from the Claude mobile app. Your prompt routes to the right tool automatically. Available on Pro and Max plans.

142A phone-initiated task router that spawns a Claude Code session in the Desktop app when you send a coding task from the Claude mobile app. Your prompt routes to the right tool automatically. Available on Pro, Max, and Ultra plans.

140143

141144Learn more: [Sessions from Dispatch](https://code.claude.com/docs/en/desktop.md#sessions-from-dispatch)

142145

hooks Changed · +414 / -414 lines

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.

from line 64

6464

6565To see how the event, the matcher, and the handler fit together, consider this `PreToolUse` hook that blocks destructive shell commands.

6666

67**macOS/Linux**

69The `matcher` narrows to Bash tool calls and the `if` condition narrows further to Bash subcommands matching `rm *`, so `block-rm.sh` only spawns when both filters match:

71```json theme={null}

72{

73 "hooks": {

74 "PreToolUse": [

75 {

76 "matcher": "Bash",

77 "hooks": [

78 {

79 "type": "command",

80 "if": "Bash(rm *)",

81 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",

82 "args": []

83 }

84 ]

85 }

86 ]

87 }

88}

89```

91The script reads the JSON input from stdin, extracts the command, and returns a `permissionDecision` of `"deny"` if it contains `rm -rf`. Save it to `.claude/hooks/block-rm.sh` in your project and make it executable with `chmod +x .claude/hooks/block-rm.sh` so Claude Code can run it:

93```bash theme={null}

94#!/bin/bash

95# .claude/hooks/block-rm.sh

96COMMAND=$(jq -r '.tool_input.command')

98if echo "$COMMAND" | grep -q 'rm -rf'; then

99 jq -n '{

100 hookSpecificOutput: {

101 hookEventName: "PreToolUse",

102 permissionDecision: "deny",

103 permissionDecisionReason: "Destructive command blocked by hook"

104 }

105 }'

106else

107 exit 0 # no decision; normal permission flow applies

108fi

109```

110

111This script, like the other Bash examples on this page that parse JSON input, uses `jq`, so install `jq` and make sure it is on your `PATH` before trying them.

112

113**Windows (PowerShell)**

114

115The matcher `Bash|PowerShell` covers the [PowerShell tool](#powershell) as well as Bash. A single `if` rule matches only one tool's calls, so each tool gets its own handler: the first narrows to Bash subcommands matching `rm *`, the second to PowerShell commands matching `Remove-Item *`. Both run the same script through `powershell.exe`:

116

117```json theme={null}

118{

119 "hooks": {

120 "PreToolUse": [

121 {

122 "matcher": "Bash|PowerShell",

123 "hooks": [

124 {

125 "type": "command",

126 "if": "Bash(rm *)",

127 "command": "powershell.exe",

128 "args": [

129 "-NoProfile",

130 "-ExecutionPolicy",

131 "Bypass",

132 "-File",

133 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"

134 ]

135 },

136 {

137 "type": "command",

138 "if": "PowerShell(Remove-Item *)",

139 "command": "powershell.exe",

140 "args": [

141 "-NoProfile",

142 "-ExecutionPolicy",

143 "Bypass",

144 "-File",

145 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"

146 ]

147 }

148 ]

149 }

150 ]

151 }

152}

153```

154

155The `-NoProfile` flag skips loading your PowerShell profile so the hook starts fast, and `-ExecutionPolicy Bypass` lets PowerShell run the local script file.

156

157The script reads the JSON input from stdin, extracts the command, and returns a `permissionDecision` of `"deny"` if it contains `rm -rf` or `Remove-Item` followed by `-Recurse`. Save it to `.claude/hooks/block-rm.ps1` in your project:

158

159```powershell theme={null}

160# .claude/hooks/block-rm.ps1

161$callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json

162$command = $callInput.tool_input.command

163

164if ($command -match 'rm -rf|Remove-Item.*-Recurse') {

165 @{

166 hookSpecificOutput = @{

167 hookEventName = "PreToolUse"

168 permissionDecision = "deny"

169 permissionDecisionReason = "Destructive command blocked by hook"

170 }

171 } | ConvertTo-Json

172} else {

173 exit 0 # no decision; normal permission flow applies

174}

175```

67> [tab] macOS/Linux

68>

69> The `matcher` narrows to Bash tool calls and the `if` condition narrows further to Bash subcommands matching `rm *`, so `block-rm.sh` only spawns when both filters match:

70>

71> ```json theme={null}

72> {

73> "hooks": {

74> "PreToolUse": [

75> {

76> "matcher": "Bash",

77> "hooks": [

78> {

79> "type": "command",

80> "if": "Bash(rm *)",

81> "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",

82> "args": []

83> }

84> ]

85> }

86> ]

87> }

88> }

89> ```

90>

91> The script reads the JSON input from stdin, extracts the command, and returns a `permissionDecision` of `"deny"` if it contains `rm -rf`. Save it to `.claude/hooks/block-rm.sh` in your project and make it executable with `chmod +x .claude/hooks/block-rm.sh` so Claude Code can run it:

92>

93> ```bash theme={null}

94> #!/bin/bash

95> # .claude/hooks/block-rm.sh

96> COMMAND=$(jq -r '.tool_input.command')

97>

98> if echo "$COMMAND" | grep -q 'rm -rf'; then

99> jq -n '{

100> hookSpecificOutput: {

101> hookEventName: "PreToolUse",

102> permissionDecision: "deny",

103> permissionDecisionReason: "Destructive command blocked by hook"

104> }

105> }'

106> else

107> exit 0 # no decision; normal permission flow applies

108> fi

109> ```

110>

111> This script, like the other Bash examples on this page that parse JSON input, uses `jq`, so install `jq` and make sure it is on your `PATH` before trying them.

112

113> [tab] Windows (PowerShell)

114>

115> The matcher `Bash|PowerShell` covers the [PowerShell tool](#powershell) as well as Bash. A single `if` rule matches only one tool's calls, so each tool gets its own handler: the first narrows to Bash subcommands matching `rm *`, the second to PowerShell commands matching `Remove-Item *`. Both run the same script through `powershell.exe`:

116>

117> ```json theme={null}

118> {

119> "hooks": {

120> "PreToolUse": [

121> {

122> "matcher": "Bash|PowerShell",

123> "hooks": [

124> {

125> "type": "command",

126> "if": "Bash(rm *)",

127> "command": "powershell.exe",

128> "args": [

129> "-NoProfile",

130> "-ExecutionPolicy",

131> "Bypass",

132> "-File",

133> "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"

134> ]

135> },

136> {

137> "type": "command",

138> "if": "PowerShell(Remove-Item *)",

139> "command": "powershell.exe",

140> "args": [

141> "-NoProfile",

142> "-ExecutionPolicy",

143> "Bypass",

144> "-File",

145> "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"

146> ]

147> }

148> ]

149> }

150> ]

151> }

152> }

153> ```

154>

155> The `-NoProfile` flag skips loading your PowerShell profile so the hook starts fast, and `-ExecutionPolicy Bypass` lets PowerShell run the local script file.

156>

157> The script reads the JSON input from stdin, extracts the command, and returns a `permissionDecision` of `"deny"` if it contains `rm -rf` or `Remove-Item` followed by `-Recurse`. Save it to `.claude/hooks/block-rm.ps1` in your project:

158>

159> ```powershell theme={null}

160> # .claude/hooks/block-rm.ps1

161> $callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json

162> $command = $callInput.tool_input.command

163>

164> if ($command -match 'rm -rf|Remove-Item.*-Recurse') {

165> @{

166> hookSpecificOutput = @{

167> hookEventName = "PreToolUse"

168> permissionDecision = "deny"

169> permissionDecisionReason = "Destructive command blocked by hook"

170> }

171> } | ConvertTo-Json

172> } else {

173> exit 0 # no decision; normal permission flow applies

174> }

175> ```

176176

177177Now suppose Claude Code decides to run `Bash "rm -rf /tmp/build"` against the macOS/Linux config. Here's what happens:

178178

from line 597

597597

598598Prefer [exec form](#exec-form-and-shell-form) for any hook that references a path placeholder. In shell form, wrap each placeholder in double quotes.

599599

600**Project scripts**

601

602This example uses `${CLAUDE_PROJECT_DIR}` to run a style checker from the project's `.claude/hooks/` directory after any `Write` or `Edit` tool call:

603

604```json theme={null}

605{

606 "hooks": {

607 "PostToolUse": [

608 {

609 "matcher": "Write|Edit",

610 "hooks": [

611 {

612 "type": "command",

613 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh",

614 "args": []

615 }

616 ]

617 }

618 ]

619 }

620}

621```

622

623**Plugin scripts**

624

625Define plugin hooks in `hooks/hooks.json` with an optional top-level `description` field. When a plugin is enabled, its hooks merge with your user and project hooks.

626

627This example runs a formatting script bundled with the plugin:

628

629```json theme={null}

630{

631 "description": "Automatic code formatting",

632 "hooks": {

633 "PostToolUse": [

634 {

635 "matcher": "Write|Edit",

636 "hooks": [

637 {

638 "type": "command",

639 "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",

640 "args": [],

641 "timeout": 30

642 }

643 ]

644 }

645 ]

646 }

647}

648```

649

650See the [plugin components reference](https://code.claude.com/docs/en/plugins/components.md#hooks) for details on creating plugin hooks.

600> [tab] Project scripts

601>

602> This example uses `${CLAUDE_PROJECT_DIR}` to run a style checker from the project's `.claude/hooks/` directory after any `Write` or `Edit` tool call:

603>

604> ```json theme={null}

605> {

606> "hooks": {

607> "PostToolUse": [

608> {

609> "matcher": "Write|Edit",

610> "hooks": [

611> {

612> "type": "command",

613> "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh",

614> "args": []

615> }

616> ]

617> }

618> ]

619> }

620> }

621> ```

622

623> [tab] Plugin scripts

624>

625> Define plugin hooks in `hooks/hooks.json` with an optional top-level `description` field. When a plugin is enabled, its hooks merge with your user and project hooks.

626>

627> This example runs a formatting script bundled with the plugin:

628>

629> ```json theme={null}

630> {

631> "description": "Automatic code formatting",

632> "hooks": {

633> "PostToolUse": [

634> {

635> "matcher": "Write|Edit",

636> "hooks": [

637> {

638> "type": "command",

639> "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",

640> "args": [],

641> "timeout": 30

642> }

643> ]

644> }

645> ]

646> }

647> }

648> ```

649>

650> See the [plugin components reference](https://code.claude.com/docs/en/plugins/components.md#hooks) for details on creating plugin hooks.

651651

652652### Hooks in skills and agents

653653

from line 1176

11761176

11771177Here are examples of each pattern in action:

11781178

1179**Top-level decision**

1180

1181The only value for `decision` is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:

1182

1183```json theme={null}

1184{

1185 "decision": "block",

1186 "reason": "Test suite must pass before proceeding"

1187}

1188```

1189

1190**PreToolUse**

1191

1192Uses `hookSpecificOutput` for richer control: allow, deny, or escalate to the user. You can also modify tool input before it runs or inject additional context for Claude. See [PreToolUse decision control](#pretooluse-decision-control) for the full set of options.

1193

1194```json theme={null}

1195{

1196 "hookSpecificOutput": {

1197 "hookEventName": "PreToolUse",

1198 "permissionDecision": "deny",

1199 "permissionDecisionReason": "Database writes are not allowed"

1200 }

1201}

1202```

1203

1204**PermissionRequest**

1205

1206Uses `hookSpecificOutput` to allow or deny a permission request on behalf of the user. When allowing, you can also modify the tool's input or apply permission rules so the user isn't prompted again. See [PermissionRequest decision control](#permissionrequest-decision-control) for the full set of options.

1207

1208```json theme={null}

1209{

1210 "hookSpecificOutput": {

1211 "hookEventName": "PermissionRequest",

1212 "decision": {

1213 "behavior": "allow",

1214 "updatedInput": {

1215 "command": "npm run lint"

1216 }

1217 }

1218 }

1219}

1220```

1179> [tab] Top-level decision

1180>

1181> The only value for `decision` is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:

1182>

1183> ```json theme={null}

1184> {

1185> "decision": "block",

1186> "reason": "Test suite must pass before proceeding"

1187> }

1188> ```

1189

1190> [tab] PreToolUse

1191>

1192> Uses `hookSpecificOutput` for richer control: allow, deny, or escalate to the user. You can also modify tool input before it runs or inject additional context for Claude. See [PreToolUse decision control](#pretooluse-decision-control) for the full set of options.

1193>

1194> ```json theme={null}

1195> {

1196> "hookSpecificOutput": {

1197> "hookEventName": "PreToolUse",

1198> "permissionDecision": "deny",

1199> "permissionDecisionReason": "Database writes are not allowed"

1200> }

1201> }

1202> ```

1203

1204> [tab] PermissionRequest

1205>

1206> Uses `hookSpecificOutput` to allow or deny a permission request on behalf of the user. When allowing, you can also modify the tool's input or apply permission rules so the user isn't prompted again. See [PermissionRequest decision control](#permissionrequest-decision-control) for the full set of options.

1207>

1208> ```json theme={null}

1209> {

1210> "hookSpecificOutput": {

1211> "hookEventName": "PermissionRequest",

1212> "decision": {

1213> "behavior": "allow",

1214> "updatedInput": {

1215> "command": "npm run lint"

1216> }

1217> }

1218> }

1219> }

1220> ```

12211221

12221222For extended examples including Bash command validation, prompt filtering, and auto-approval scripts, see [What you can automate](https://code.claude.com/docs/en/hooks-guide.md#what-you-can-automate) in the guide and the [Bash command validator reference implementation](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py).

12231223

from line 1652

16521652

16531653This example strips markdown formatting from Claude's responses for a plain-text display. The script reads each batch from stdin, removes bold markers and inline code backticks from `delta`, and returns the result as `displayContent`.

16541654

1655**macOS/Linux**

1656

1657Register a command hook for the event in your settings file:

1658

1659```json theme={null}

1660{

1661 "hooks": {

1662 "MessageDisplay": [

1663 {

1664 "hooks": [

1665 {

1666 "type": "command",

1667 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh",

1668 "args": []

1669 }

1670 ]

1671 }

1672 ]

1673 }

1674}

1675```

1676

1677Save this script to `.claude/hooks/plain-display.sh` in your project and make it executable with `chmod +x`:

1678

1679```bash theme={null}

1680#!/bin/bash

1681jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'

1682```

1683

1684**Windows (PowerShell)**

1685

1686Register a command hook that runs the script through PowerShell:

1687

1688```json theme={null}

1689{

1690 "hooks": {

1691 "MessageDisplay": [

1692 {

1693 "hooks": [

1694 {

1695 "type": "command",

1696 "command": "powershell.exe",

1697 "args": [

1698 "-NoProfile",

1699 "-ExecutionPolicy",

1700 "Bypass",

1701 "-File",

1702 "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1"

1703 ]

1704 }

1705 ]

1706 }

1707 ]

1708 }

1709}

1710```

1711

1712The `-NoProfile` flag skips loading your PowerShell profile so the hook starts fast, and `-ExecutionPolicy Bypass` lets PowerShell run the local script file.

1713

1714Save this script to `.claude/hooks/plain-display.ps1` in your project:

1715

1716```powershell theme={null}

1717$batch = [Console]::In.ReadToEnd() | ConvertFrom-Json

1718$text = $batch.delta -replace '\*\*', '' -replace '`', ''

1719@{

1720 hookSpecificOutput = @{

1721 hookEventName = "MessageDisplay"

1722 displayContent = $text

1723 }

1724} | ConvertTo-Json

1725```

1655> [tab] macOS/Linux

1656>

1657> Register a command hook for the event in your settings file:

1658>

1659> ```json theme={null}

1660> {

1661> "hooks": {

1662> "MessageDisplay": [

1663> {

1664> "hooks": [

1665> {

1666> "type": "command",

1667> "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh",

1668> "args": []

1669> }

1670> ]

1671> }

1672> ]

1673> }

1674> }

1675> ```

1676>

1677> Save this script to `.claude/hooks/plain-display.sh` in your project and make it executable with `chmod +x`:

1678>

1679> ```bash theme={null}

1680> #!/bin/bash

1681> jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'

1682> ```

1683

1684> [tab] Windows (PowerShell)

1685>

1686> Register a command hook that runs the script through PowerShell:

1687>

1688> ```json theme={null}

1689> {

1690> "hooks": {

1691> "MessageDisplay": [

1692> {

1693> "hooks": [

1694> {

1695> "type": "command",

1696> "command": "powershell.exe",

1697> "args": [

1698> "-NoProfile",

1699> "-ExecutionPolicy",

1700> "Bypass",

1701> "-File",

1702> "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1"

1703> ]

1704> }

1705> ]

1706> }

1707> ]

1708> }

1709> }

1710> ```

1711>

1712> The `-NoProfile` flag skips loading your PowerShell profile so the hook starts fast, and `-ExecutionPolicy Bypass` lets PowerShell run the local script file.

1713>

1714> Save this script to `.claude/hooks/plain-display.ps1` in your project:

1715>

1716> ```powershell theme={null}

1717> $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json

1718> $text = $batch.delta -replace '\*\*', '' -replace '`', ''

1719> @{

1720> hookSpecificOutput = @{

1721> hookEventName = "MessageDisplay"

1722> displayContent = $text

1723> }

1724> } | ConvertTo-Json

1725> ```

17261726

17271727Batches with no markdown pass through unchanged. If the script fails, for example because `jq` is missing, Claude Code displays the original text and notes the failure only in [debug output](#debug-hooks), not in the session.

17281728

from line 3353

33533353

33543354Write the matcher as an exact name, a `|`-separated list such as `claude-opus-4-6|claude-opus-5`, or a regular expression such as `.*opus.*`. This example uses an exact-name matcher and also checks `to_model` from the hook input, so it refuses a switch to Opus 4.6 by exiting with code 2 and lets any other target through:

33553355

3356**macOS/Linux**

3357

3358The command checks `to_model` with `jq`:

3359

3360```json theme={null}

3361{

3362 "hooks": {

3363 "PreModelSwitch": [

3364 {

3365 "matcher": "claude-opus-4-6",

3366 "hooks": [

3367 {

3368 "type": "command",

3369 "command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"

3370 }

3371 ]

3372 }

3373 ]

3374 }

3375}

3376```

3377

3378**Windows (PowerShell)**

3379

3380Register a command hook that runs a script through PowerShell:

3381

3382```json theme={null}

3383{

3384 "hooks": {

3385 "PreModelSwitch": [

3386 {

3387 "matcher": "claude-opus-4-6",

3388 "hooks": [

3389 {

3390 "type": "command",

3391 "command": "powershell.exe",

3392 "args": [

3393 "-NoProfile",

3394 "-ExecutionPolicy",

3395 "Bypass",

3396 "-File",

3397 "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"

3398 ]

3399 }

3400 ]

3401 }

3402 ]

3403 }

3404}

3405```

3406

3407Save this script to `.claude/hooks/block-opus-46.ps1` in your project:

3408

3409```powershell theme={null}

3410$hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json

3411if ($hookInput.to_model -match 'opus-4-6') {

3412 [Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')

3413 exit 2

3414}

3415exit 0

3416```

3356> [tab] macOS/Linux

3357>

3358> The command checks `to_model` with `jq`:

3359>

3360> ```json theme={null}

3361> {

3362> "hooks": {

3363> "PreModelSwitch": [

3364> {

3365> "matcher": "claude-opus-4-6",

3366> "hooks": [

3367> {

3368> "type": "command",

3369> "command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"

3370> }

3371> ]

3372> }

3373> ]

3374> }

3375> }

3376> ```

3377

3378> [tab] Windows (PowerShell)

3379>

3380> Register a command hook that runs a script through PowerShell:

3381>

3382> ```json theme={null}

3383> {

3384> "hooks": {

3385> "PreModelSwitch": [

3386> {

3387> "matcher": "claude-opus-4-6",

3388> "hooks": [

3389> {

3390> "type": "command",

3391> "command": "powershell.exe",

3392> "args": [

3393> "-NoProfile",

3394> "-ExecutionPolicy",

3395> "Bypass",

3396> "-File",

3397> "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"

3398> ]

3399> }

3400> ]

3401> }

3402> ]

3403> }

3404> }

3405> ```

3406>

3407> Save this script to `.claude/hooks/block-opus-46.ps1` in your project:

3408>

3409> ```powershell theme={null}

3410> $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json

3411> if ($hookInput.to_model -match 'opus-4-6') {

3412> [Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')

3413> exit 2

3414> }

3415> exit 0

3416> ```

34173417

34183418To confirm the hook works, run `/model claude-opus-4-6` from a session running a different model. Claude Code keeps the current model and reports that a PreModelSwitch hook blocked the switch, with your message as the reason.

34193419

from line 3701

37013701

37023702This example answers one recurring question for the user. An MCP server named `issue-tracker` asks for a project key in a form, and the hook fills in `DOCS`. The script accepts when `project_key` is the form's single field. For any other request it prints nothing, so the dialog appears.

37033703

3704**macOS/Linux**

3705

3706Register a command hook for the event in your settings file, with the server name as the matcher:

3707

3708```json theme={null}

3709{

3710 "hooks": {

3711 "Elicitation": [

3712 {

3713 "matcher": "issue-tracker",

3714 "hooks": [

3715 {

3716 "type": "command",

3717 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.sh",

3718 "args": []

3719 }

3720 ]

3721 }

3722 ]

3723 }

3724}

3725```

3726

3727Save this script to `.claude/hooks/answer-project-key.sh` in your project and make it executable with `chmod +x`:

3728

3729```bash theme={null}

3730#!/bin/bash

3731input=$(cat)

3732fields=$(jq -c '.requested_schema.properties // {} | keys' <<<"$input")

3733

3734if [ "$fields" = '["project_key"]' ]; then

3735 jq -n '{hookSpecificOutput: {hookEventName: "Elicitation", action: "accept", content: {project_key: "DOCS"}}}'

3736fi

3737```

3738

3739**Windows (PowerShell)**

3740

3741Register a command hook that runs the script through PowerShell, with the server name as the matcher:

3742

3743```json theme={null}

3744{

3745 "hooks": {

3746 "Elicitation": [

3747 {

3748 "matcher": "issue-tracker",

3749 "hooks": [

3750 {

3751 "type": "command",

3752 "command": "powershell.exe",

3753 "args": [

3754 "-NoProfile",

3755 "-ExecutionPolicy",

3756 "Bypass",

3757 "-File",

3758 "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.ps1"

3759 ]

3760 }

3761 ]

3762 }

3763 ]

3764 }

3765}

3766```

3767

3768Save this script to `.claude/hooks/answer-project-key.ps1` in your project:

3769

3770```powershell theme={null}

3771$request = [Console]::In.ReadToEnd() | ConvertFrom-Json

3772$fields = @($request.requested_schema.properties.PSObject.Properties.Name)

3773

3774if ($fields.Count -eq 1 -and $fields[0] -eq 'project_key') {

3775 @{

3776 hookSpecificOutput = @{

3777 hookEventName = "Elicitation"

3778 action = "accept"

3779 content = @{ project_key = "DOCS" }

3780 }

3781 } | ConvertTo-Json -Depth 3

3782}

3783```

3704> [tab] macOS/Linux

3705>

3706> Register a command hook for the event in your settings file, with the server name as the matcher:

3707>

3708> ```json theme={null}

3709> {

3710> "hooks": {

3711> "Elicitation": [

3712> {

3713> "matcher": "issue-tracker",

3714> "hooks": [

3715> {

3716> "type": "command",

3717> "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.sh",

3718> "args": []

3719> }

3720> ]

3721> }

3722> ]

3723> }

3724> }

3725> ```

3726>

3727> Save this script to `.claude/hooks/answer-project-key.sh` in your project and make it executable with `chmod +x`:

3728>

3729> ```bash theme={null}

3730> #!/bin/bash

3731> input=$(cat)

3732> fields=$(jq -c '.requested_schema.properties // {} | keys' <<<"$input")

3733>

3734> if [ "$fields" = '["project_key"]' ]; then

3735> jq -n '{hookSpecificOutput: {hookEventName: "Elicitation", action: "accept", content: {project_key: "DOCS"}}}'

3736> fi

3737> ```

3738

3739> [tab] Windows (PowerShell)

3740>

3741> Register a command hook that runs the script through PowerShell, with the server name as the matcher:

3742>

3743> ```json theme={null}

3744> {

3745> "hooks": {

3746> "Elicitation": [

3747> {

3748> "matcher": "issue-tracker",

3749> "hooks": [

3750> {

3751> "type": "command",

3752> "command": "powershell.exe",

3753> "args": [

3754> "-NoProfile",

3755> "-ExecutionPolicy",

3756> "Bypass",

3757> "-File",

3758> "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.ps1"

3759> ]

3760> }

3761> ]

3762> }

3763> ]

3764> }

3765> }

3766> ```

3767>

3768> Save this script to `.claude/hooks/answer-project-key.ps1` in your project:

3769>

3770> ```powershell theme={null}

3771> $request = [Console]::In.ReadToEnd() | ConvertFrom-Json

3772> $fields = @($request.requested_schema.properties.PSObject.Properties.Name)

3773>

3774> if ($fields.Count -eq 1 -and $fields[0] -eq 'project_key') {

3775> @{

3776> hookSpecificOutput = @{

3777> hookEventName = "Elicitation"

3778> action = "accept"

3779> content = @{ project_key = "DOCS" }

3780> }

3781> } | ConvertTo-Json -Depth 3

3782> }

3783> ```

37843784

37853785To confirm the hook works, start Claude Code with `claude --debug` and give Claude a task that makes the server ask for the project key. No dialog appears, and the [debug log](#debug-hooks) has a line that ends with `Elicitation resolved by hook: {"action":"accept","content":{"project_key":"DOCS"}}`.

37863786

37873787

hooks-guide Changed · +150 / -150 lines

from line 85

8585

8686Each tab below uses the platform's native notification command. Add this to `~/.claude/settings.json`:

8787

88**macOS**

90```json theme={null}

91{

92 "hooks": {

93 "Notification": [

94 {

95 "matcher": "",

96 "hooks": [

97 {

98 "type": "command",

99 "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"

100 }

101 ]

102 }

103 ]

104 }

105}

106```

107

108> **If no notification appears**

88> [tab] macOS

10989>

110> `osascript` routes notifications through the built-in Script Editor app. If Script Editor doesn't have notification permission, the command fails silently, and macOS won't prompt you to grant it.

111>

112> Run this in Terminal once to make Script Editor appear in your notification settings:

113>

114> ```bash theme={null}

115> osascript -e 'display notification "test"'

90> ```json theme={null}

91> {

92> "hooks": {

93> "Notification": [

94> {

95> "matcher": "",

96> "hooks": [

97> {

98> "type": "command",

99> "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"

100> }

101> ]

102> }

103> ]

104> }

105> }

116106> ```

117107>

118> Nothing will appear yet. Open **System Settings > Notifications**, find **Script Editor** in the list, and turn on **Allow Notifications**. Run the command again to confirm the test notification appears.

108> > [accordion] If no notification appears

109> >

110> > `osascript` routes notifications through the built-in Script Editor app. If Script Editor doesn't have notification permission, the command fails silently, and macOS won't prompt you to grant it.

111> >

112> > Run this in Terminal once to make Script Editor appear in your notification settings:

113> >

114> > ```bash theme={null}

115> > osascript -e 'display notification "test"'

116> > ```

117> >

118> > Nothing will appear yet. Open **System Settings > Notifications**, find **Script Editor** in the list, and turn on **Allow Notifications**. Run the command again to confirm the test notification appears.

119119

120**Linux**

121

122```json theme={null}

123{

124 "hooks": {

125 "Notification": [

126 {

127 "matcher": "",

128 "hooks": [

129 {

130 "type": "command",

131 "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"

132 }

133 ]

134 }

135 ]

136 }

137}

138```

139

140> **If no notification appears**

120> [tab] Linux

141121>

142> `notify-send` needs a desktop notification daemon, which headless servers, SSH sessions, and most containers don't have. Test the command directly first:

143>

144> ```bash theme={null}

145> notify-send 'Claude Code' 'test'

122> ```json theme={null}

123> {

124> "hooks": {

125> "Notification": [

126> {

127> "matcher": "",

128> "hooks": [

129> {

130> "type": "command",

131> "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"

132> }

133> ]

134> }

135> ]

136> }

137> }

146138> ```

147139>

148> If the command isn't found, install the `libnotify-bin` package on Debian and Ubuntu, or your distribution's equivalent.

140> > [accordion] If no notification appears

141> >

142> > `notify-send` needs a desktop notification daemon, which headless servers, SSH sessions, and most containers don't have. Test the command directly first:

143> >

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

145> > notify-send 'Claude Code' 'test'

146> > ```

147> >

148> > If the command isn't found, install the `libnotify-bin` package on Debian and Ubuntu, or your distribution's equivalent.

149149

150**Windows (PowerShell)**

151

152```json theme={null}

153{

154 "hooks": {

155 "Notification": [

156 {

157 "matcher": "",

158 "hooks": [

159 {

160 "type": "command",

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

162 }

163 ]

164 }

165 ]

166 }

167}

168```

169

170> **If no dialog appears**

150> [tab] Windows (PowerShell)

171151>

172> This command opens a dialog box rather than a notification in the corner of your screen, so the dialog can open behind your terminal window. Test the command directly in PowerShell first.

152> ```json theme={null}

153> {

154> "hooks": {

155> "Notification": [

156> {

157> "matcher": "",

158> "hooks": [

159> {

160> "type": "command",

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

162> }

163> ]

164> }

165> ]

166> }

167> }

168> ```

173169>

174> If you run Claude Code inside WSL, `powershell.exe` must be available on your `PATH` through Windows interop.

170> > [accordion] If no dialog appears

171> >

172> > This command opens a dialog box rather than a notification in the corner of your screen, so the dialog can open behind your terminal window. Test the command directly in PowerShell first.

173> >

174> > If you run Claude Code inside WSL, `powershell.exe` must be available on your `PATH` through Windows interop.

175175

176176The empty `matcher` fires on all notification types. To fire only on specific events, set it to one of these values:

177177

from line 701

701701

702702The tabs below show a few more matchers on different event types.

703703

704**Log every Bash command**

704> [tab] Log every Bash command

705>

706> Match only `Bash` tool calls and log each command to a file. The `PostToolUse` event fires after the command completes, so `tool_input.command` contains what ran. The hook receives the event data as JSON on stdin, and `jq -r '.tool_input.command'` extracts only the command string, which `>>` appends to the log file:

707>

708> ```json theme={null}

709> {

710> "hooks": {

711> "PostToolUse": [

712> {

713> "matcher": "Bash",

714> "hooks": [

715> {

716> "type": "command",

717> "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"

718> }

719> ]

720> }

721> ]

722> }

723> }

724> ```

705725

706Match only `Bash` tool calls and log each command to a file. The `PostToolUse` event fires after the command completes, so `tool_input.command` contains what ran. The hook receives the event data as JSON on stdin, and `jq -r '.tool_input.command'` extracts only the command string, which `>>` appends to the log file:

726> [tab] Match MCP tools

727>

728> MCP tools use a different naming convention than built-in tools: `mcp__<server>__<tool>`, where `<server>` is the MCP server name and `<tool>` is the tool it provides. For example, `mcp__github__search_repositories` or `mcp__filesystem__read_file`. Tools from a [plugin-bundled server](https://code.claude.com/docs/en/mcp.md#plugin-provided-mcp-servers) use a scoped server segment instead, such as `mcp__plugin_my-plugin_db__query`. Use a regex matcher to target all tools from a specific server, or match across servers with a pattern like `mcp__.*__write.*`. See [Match MCP tools](https://code.claude.com/docs/en/hooks.md#match-mcp-tools) in the reference for the full list of examples.

729>

730> The command below extracts the tool name from the hook's JSON input with `jq` and writes it to stderr. Writing to stderr keeps stdout clean for JSON output and sends the message to the [debug log](https://code.claude.com/docs/en/hooks.md#debug-hooks):

731>

732> ```json theme={null}

733> {

734> "hooks": {

735> "PreToolUse": [

736> {

737> "matcher": "mcp__github__.*",

738> "hooks": [

739> {

740> "type": "command",

741> "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"

742> }

743> ]

744> }

745> ]

746> }

747> }

748> ```

707749

708```json theme={null}

709{

710 "hooks": {

711 "PostToolUse": [

712 {

713 "matcher": "Bash",

714 "hooks": [

715 {

716 "type": "command",

717 "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"

718 }

719 ]

720 }

721 ]

722 }

723}

724```

725

726**Match MCP tools**

727

728MCP tools use a different naming convention than built-in tools: `mcp__<server>__<tool>`, where `<server>` is the MCP server name and `<tool>` is the tool it provides. For example, `mcp__github__search_repositories` or `mcp__filesystem__read_file`. Tools from a [plugin-bundled server](https://code.claude.com/docs/en/mcp.md#plugin-provided-mcp-servers) use a scoped server segment instead, such as `mcp__plugin_my-plugin_db__query`. Use a regex matcher to target all tools from a specific server, or match across servers with a pattern like `mcp__.*__write.*`. See [Match MCP tools](https://code.claude.com/docs/en/hooks.md#match-mcp-tools) in the reference for the full list of examples.

729

730The command below extracts the tool name from the hook's JSON input with `jq` and writes it to stderr. Writing to stderr keeps stdout clean for JSON output and sends the message to the [debug log](https://code.claude.com/docs/en/hooks.md#debug-hooks):

731

732```json theme={null}

733{

734 "hooks": {

735 "PreToolUse": [

736 {

737 "matcher": "mcp__github__.*",

738 "hooks": [

739 {

740 "type": "command",

741 "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"

742 }

743 ]

744 }

745 ]

746 }

747}

748```

749

750**Clean up on session end**

751

752The `SessionEnd` event supports matchers on the reason the session ended. This hook only fires on the `clear` reason, set when you run `/clear`, not on normal exits:

753

754```json theme={null}

755{

756 "hooks": {

757 "SessionEnd": [

758 {

759 "matcher": "clear",

760 "hooks": [

761 {

762 "type": "command",

763 "command": "rm -f /tmp/claude-scratch-*.txt"

764 }

765 ]

766 }

767 ]

768 }

769}

770```

750> [tab] Clean up on session end

751>

752> The `SessionEnd` event supports matchers on the reason the session ended. This hook only fires on the `clear` reason, set when you run `/clear`, not on normal exits:

753>

754> ```json theme={null}

755> {

756> "hooks": {

757> "SessionEnd": [

758> {

759> "matcher": "clear",

760> "hooks": [

761> {

762> "type": "command",

763> "command": "rm -f /tmp/claude-scratch-*.txt"

764> }

765> ]

766> }

767> ]

768> }

769> }

770> ```

771771

772772#### Filter by tool name and arguments with the `if` field

773773

how-claude-code-works Changed · +3 / -3 lines

from line 159

159159

160160Choose a permission mode to set what Claude can do without asking you. Press `Shift+Tab` to cycle through the permission modes:

161161

162* **Auto**: a classifier reviews most actions in the background and blocks the risky ones instead of asking you. With Claude Code v2.1.283 or later, it's the [built-in starting permission mode](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in) for interactive terminal and VS Code sessions, and on earlier versions only on Pro, Max, and Team plans

162* **Auto**: a classifier reviews most actions in the background and blocks the risky ones instead of asking you. With Claude Code v2.1.283 or later, it's the [built-in starting permission mode](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in) for interactive terminal and VS Code sessions. On earlier versions, it's the built-in starting permission mode only on Pro, Max, Ultra, and Team plans.

163163* **Manual**: Claude asks before file edits and shell commands

164164* **Accept edits**: Claude edits files and runs common filesystem commands like `mkdir` and `mv` without asking, still asks for other commands

165165* **Plan**: Claude explores and proposes a plan without editing your source files

from line 219

219219

220220## What's next

221221

222> **[Extend with features](https://code.claude.com/docs/en/features-overview.md)**

222> [card] [Extend with features](https://code.claude.com/docs/en/features-overview.md)

223223>

224224> Add skills and MCP connections

225225

226> **[Common workflows](https://code.claude.com/docs/en/common-workflows.md)**

226> [card] [Common workflows](https://code.claude.com/docs/en/common-workflows.md)

227227>

228228> Step-by-step guides for typical tasks

229229

interactive-mode Changed · +35 / -35 lines

from line 533

533533

534534Claude Code reads the [`spellcheck`](https://code.claude.com/docs/en/settings-reference#spellcheck) setting from three places, and ignores it in a project's `.claude/settings.json` and `.claude/settings.local.json`. Turn it on from whichever one you use:

535535

536**User settings**

536> [tab] User settings

537>

538> Add `spellcheck` to `~/.claude/settings.json`. It applies in every project you open, like the rest of your [user settings](https://code.claude.com/docs/en/settings.md#where-settings-live):

539>

540> ```json theme={null}

541> {

542> "spellcheck": { "enabled": true }

543> }

544> ```

537545

538Add `spellcheck` to `~/.claude/settings.json`. It applies in every project you open, like the rest of your [user settings](https://code.claude.com/docs/en/settings.md#where-settings-live):

546> [tab] Command line

547>

548> Save `spellcheck` in a JSON file, such as `spellcheck.json`:

549>

550> ```json theme={null}

551> {

552> "spellcheck": { "enabled": true }

553> }

554> ```

555>

556> Then pass the file to `--settings`. It applies to that session only:

557>

558> ```bash theme={null}

559> claude --settings spellcheck.json

560> ```

539561

540```json theme={null}

541{

542 "spellcheck": { "enabled": true }

543}

544```

545

546**Command line**

547

548Save `spellcheck` in a JSON file, such as `spellcheck.json`:

549

550```json theme={null}

551{

552 "spellcheck": { "enabled": true }

553}

554```

555

556Then pass the file to `--settings`. It applies to that session only:

557

558```bash theme={null}

559claude --settings spellcheck.json

560```

561

562**Managed settings**

563

564Add `spellcheck` to one of your organization's [managed settings sources](https://code.claude.com/docs/en/permissions.md#managed-settings). It applies to every user who receives those settings, and they can't turn it off:

565

566```json theme={null}

567{

568 "spellcheck": { "enabled": true }

569}

570```

562> [tab] Managed settings

563>

564> Add `spellcheck` to one of your organization's [managed settings sources](https://code.claude.com/docs/en/permissions.md#managed-settings). It applies to every user who receives those settings, and they can't turn it off:

565>

566> ```json theme={null}

567> {

568> "spellcheck": { "enabled": true }

569> }

570> ```

571571

572572To check that spell checking is on, type a misspelled word and a space. Claude Code underlines the word. If it doesn't, see [When Claude Code underlines nothing](#when-claude-code-underlines-nothing). To turn spell checking off again, set `enabled` to `false` in the same place, or remove `spellcheck`.

573573

legal-and-compliance Changed · +4 / -4 lines

from line 9

99Your use of Claude Code is subject to:

1010

1111* [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) - for Team, Enterprise, and Claude API users

12* [Consumer Terms of Service](https://www.anthropic.com/legal/consumer-terms) - for Free, Pro, and Max users

12* [Consumer Terms of Service](https://www.anthropic.com/legal/consumer-terms) - for Free, Pro, Max, and Ultra users

1313

1414### Commercial agreements

1515

from line 41

4141

4242### Acceptable use

4343

44Claude Code usage is subject to the [Anthropic Usage Policy](https://www.anthropic.com/legal/aup). Advertised usage limits for Pro and Max plans assume ordinary, individual usage of Claude Code and the Agent SDK.

44Claude Code usage is subject to the [Anthropic Usage Policy](https://www.anthropic.com/legal/aup). Advertised usage limits for Pro, Max, and Ultra plans assume ordinary, individual usage of Claude Code and the Agent SDK.

4545

4646### Authentication and credential use

4747

4848Claude Code authenticates with Anthropic's servers using OAuth tokens or API keys. These authentication methods serve different purposes:

4949

50* **OAuth authentication** is intended exclusively for purchasers of Claude Free, Pro, Max, Team, and Enterprise subscription plans and is designed to support ordinary use of Claude Code and other native Anthropic applications. For the sign-in steps, see [Logging in to your Claude account](https://support.claude.com/en/articles/13189465-logging-in-to-your-claude-account); for how Claude Code performs OAuth authentication, see [Authentication](https://code.claude.com/docs/en/authentication.md).

51* **Developers** building products or services that interact with Claude's capabilities, including those using the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md), should use API key authentication through [Claude Console](https://platform.claude.com/) or a supported cloud provider. Anthropic does not permit third-party developers to offer Claude.ai login into their own applications, or to route requests through Free, Pro, or Max plan credentials on behalf of their users. Moreover, developers may not collect, store, or intermediate Claude.ai credentials or session tokens — sign-in to a Claude account must complete through Anthropic's own flow.

50* **OAuth authentication** is intended exclusively for purchasers of Claude Free, Pro, Max, Ultra, Team, and Enterprise subscription plans and is designed to support ordinary use of Claude Code and other native Anthropic applications. For the sign-in steps, see [Logging in to your Claude account](https://support.claude.com/en/articles/13189465-logging-in-to-your-claude-account); for how Claude Code performs OAuth authentication, see [Authentication](https://code.claude.com/docs/en/authentication.md).

51* **Developers** building products or services that interact with Claude's capabilities, including those using the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md), should use API key authentication through [Claude Console](https://platform.claude.com/) or a supported cloud provider. Anthropic does not permit third-party developers to offer Claude.ai login into their own applications, or to route requests through Free, Pro, Max, or Ultra plan credentials on behalf of their users. Moreover, developers may not collect, store, or intermediate Claude.ai credentials or session tokens — sign-in to a Claude account must complete through Anthropic's own flow.

5252

5353This does not restrict how customers provision and manage their own API keys or third-party inference provider credentials — for example, configuring an API key in a development environment, secrets manager, or machine image for use by the customer's own authorized users — provided the resulting usage is billed to the key owner under their agreement with Anthropic (or the applicable provider) and is not resold or intermediated as described above. Nor does it prevent an end user from signing in to the unmodified Claude Code binary with their own Claude subscription, including where a platform hosts Claude Code as described under *Can customers offer Claude Code in their products?* above.

5454

llm-gateway-connect Changed · +151 / -151 lines

from line 69

6969

7070Replace the values with the ones your gateway team gave you:

7171

72**Bash or Zsh**

72> [tab] Bash or Zsh

73>

74> ```bash theme={null}

75> export ANTHROPIC_BASE_URL=https://llm-gateway.example.com

76> export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

77> ```

7378

74```bash theme={null}

75export ANTHROPIC_BASE_URL=https://llm-gateway.example.com

76export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

77```

79> [tab] PowerShell

80>

81> ```powershell theme={null}

82> $env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"

83> $env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"

84> ```

7885

79**PowerShell**

81```powershell theme={null}

82$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"

83$env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"

84```

8686Shell exports apply only to that terminal session and programs started from it. An editor launched from the dock or Start menu won't see them. To make the values persist across new terminals, add the same lines to your shell profile, such as `~/.zshrc`, `~/.bashrc`, or your PowerShell `$PROFILE`.

8787

8888If you export the gateway only in your shell, it doesn't reliably reach background agents hosted by the [supervisor](https://code.claude.com/docs/en/agent-view.md#how-background-sessions-are-hosted); see [how each background session sources its gateway](https://code.claude.com/docs/en/agent-view.md#llm-gateway). Use a settings file for any gateway that background agents must always route through.

from line 115

115115

116116With the variables exported in your shell, send a one-token request to the gateway directly. This confirms the URL and credential work before you open Claude Code, so a failure points at the gateway rather than your configuration. The commands below read the shell variables, so they need the [shell exports](#set-as-shell-environment-variables) even if you also put the values in a settings file.

117117

118**Bash or Zsh**

118> [tab] Bash or Zsh

119>

120> ```bash theme={null}

121> curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \

122> -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \

123> -H "anthropic-version: 2023-06-01" \

124> -H "content-type: application/json" \

125> -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

126> ```

119127

120```bash theme={null}

121curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \

122 -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \

123 -H "anthropic-version: 2023-06-01" \

124 -H "content-type: application/json" \

125 -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

126```

128> [tab] PowerShell

129>

130> ```powershell theme={null}

131> Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `

132> -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `

133> -ContentType "application/json" `

134> -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

135> ```

127136

128**PowerShell**

129

130```powershell theme={null}

131Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `

132 -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `

133 -ContentType "application/json" `

134 -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

135```

136

137137If your gateway expects keys in the `x-api-key` header, replace the `Authorization` header with `x-api-key: $ANTHROPIC_API_KEY` in the Bash command, or the `"Authorization"` hashtable entry with `"x-api-key" = "$env:ANTHROPIC_API_KEY"` in the PowerShell command.

138138

139139A JSON response that starts with `{"id":"msg_` and includes a `"content":[...]` field means the gateway is reachable and the credential works. An error naming an unknown model still proves the URL and credential work, since the gateway authenticated the request before rejecting the model name; you don't need to find a model your gateway serves for this test. A `401` means the credential was rejected: if you guessed the variable, switch to the other one and re-export.

from line 270

270270

271271Some gateways route or tag requests using a custom header in addition to the credential, for example a tenant identifier or a routing key. To send one, set [`ANTHROPIC_CUSTOM_HEADERS`](https://code.claude.com/docs/en/env-vars) with one `Name: Value` pair per line. The example below adds a routing header named `X-Org-Route`:

272272

273**Bash or Zsh**

273> [tab] Bash or Zsh

274>

275> ```bash theme={null}

276> export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"

277> ```

274278

275```bash theme={null}

276export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"

277```

279> [tab] PowerShell

280>

281> ```powershell theme={null}

282> $env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"

283> ```

278284

279**PowerShell**

280

281```powershell theme={null}

282$env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"

283```

284

285285You can also set `ANTHROPIC_CUSTOM_HEADERS` in the `env` block of a settings file. Use `\n` between pairs there, since JSON strings can't span multiple lines:

286286

287287```json theme={null}

from line 314

314314

315315The helper is any shell command that prints the current credential to stdout. Claude Code runs it through your system shell, so on Windows it can be an executable or a PowerShell invocation. Make the command print nothing but the credential. On Claude Code v2.1.227 or later, a banner or a log line printed alongside the key makes the [helper fail](https://code.claude.com/docs/en/errors.md#your-apikeyhelper-script-is-failing). Write the script, make it executable, and reference it from `apiKeyHelper` in your [settings file](https://code.claude.com/docs/en/settings.md):

316316

317**Bash or Zsh**

317> [tab] Bash or Zsh

318>

319> For example, a script that reads from a vault:

320>

321> ```bash theme={null}

322> #!/bin/bash

323> vault kv get -field=api_key secret/llm-gateway/claude-code

324> ```

325>

326> Reference its path in `~/.claude/settings.json`:

327>

328> ```json theme={null}

329> {

330> "apiKeyHelper": "~/bin/get-gateway-key.sh"

331> }

332> ```

318333

319For example, a script that reads from a vault:

334> [tab] PowerShell

335>

336> For example, a script that reads from a vault:

337>

338> ```powershell theme={null}

339> vault kv get -field=api_key secret/llm-gateway/claude-code

340> ```

341>

342> Reference the PowerShell invocation in `%USERPROFILE%\.claude\settings.json`, escaping the backslashes in the JSON string:

343>

344> ```json theme={null}

345> {

346> "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"

347> }

348> ```

320349

321```bash theme={null}

322#!/bin/bash

323vault kv get -field=api_key secret/llm-gateway/claude-code

324```

325

326Reference its path in `~/.claude/settings.json`:

327

328```json theme={null}

329{

330 "apiKeyHelper": "~/bin/get-gateway-key.sh"

331}

332```

333

334**PowerShell**

335

336For example, a script that reads from a vault:

337

338```powershell theme={null}

339vault kv get -field=api_key secret/llm-gateway/claude-code

340```

341

342Reference the PowerShell invocation in `%USERPROFILE%\.claude\settings.json`, escaping the backslashes in the JSON string:

343

344```json theme={null}

345{

346 "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"

347}

348```

349

350350Claude Code caches the helper's output for five minutes by default and re-runs the helper after the cache lifetime elapses. To change the lifetime, set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` in milliseconds, for example `CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000` for 15 minutes.

351351

352352See [`apiKeyHelper`](https://code.claude.com/docs/en/settings-reference#apikeyhelper) for the other cases in which Claude Code re-runs the helper.

from line 359

359359

360360To turn that traffic off, set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` alongside the gateway variables, in the same shell exports or settings-file `env` block:

361361

362**Bash or Zsh**

362> [tab] Bash or Zsh

363>

364> ```bash theme={null}

365> export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

366> ```

363367

364```bash theme={null}

365export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

366```

368> [tab] PowerShell

369>

370> ```powershell theme={null}

371> $env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"

372> ```

367373

368**PowerShell**

369

370```powershell theme={null}

371$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"

372```

373

374374Setting the variable has these effects and limits:

375375

376376* It disables auto-updates, so plan for another update path, such as your package manager or managed distribution.

from line 394

394394

395395Leave `AWS_BEARER_TOKEN_BEDROCK` unset when the gateway issues its own credential. If you set it, Claude Code sends that [Amazon Bedrock API key](https://code.claude.com/docs/en/amazon-bedrock.md#2-configure-aws-credentials) as the `Authorization` header instead of your gateway token, even with `CLAUDE_CODE_SKIP_BEDROCK_AUTH` set.

396396

397**Bash or Zsh**

397> [tab] Bash or Zsh

398>

399> ```bash theme={null}

400> export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock

401> export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

402> export CLAUDE_CODE_USE_BEDROCK=1

403> ```

398404

399```bash theme={null}

400export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock

401export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

402export CLAUDE_CODE_USE_BEDROCK=1

403```

405> [tab] PowerShell

406>

407> ```powershell theme={null}

408> $env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"

409> $env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"

410> $env:CLAUDE_CODE_USE_BEDROCK = "1"

411> ```

404412

405**PowerShell**

406

407```powershell theme={null}

408$env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"

409$env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"

410$env:CLAUDE_CODE_USE_BEDROCK = "1"

411```

412

413413#### Google Cloud's Agent Platform

414414

415415Replace the project ID and region with your own values. Claude Code includes both in the path of each request it sends to the gateway:

416416

417**Bash or Zsh**

417> [tab] Bash or Zsh

418>

419> ```bash theme={null}

420> export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex

421> export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id

422> export CLAUDE_CODE_SKIP_VERTEX_AUTH=1

423> export CLAUDE_CODE_USE_VERTEX=1

424> export CLOUD_ML_REGION=us-east5

425> ```

418426

419```bash theme={null}

420export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex

421export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id

422export CLAUDE_CODE_SKIP_VERTEX_AUTH=1

423export CLAUDE_CODE_USE_VERTEX=1

424export CLOUD_ML_REGION=us-east5

425```

427> [tab] PowerShell

428>

429> ```powershell theme={null}

430> $env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"

431> $env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"

432> $env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"

433> $env:CLAUDE_CODE_USE_VERTEX = "1"

434> $env:CLOUD_ML_REGION = "us-east5"

435> ```

426436

427**PowerShell**

428

429```powershell theme={null}

430$env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"

431$env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"

432$env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"

433$env:CLAUDE_CODE_USE_VERTEX = "1"

434$env:CLOUD_ML_REGION = "us-east5"

435```

436

437437The block covers routing and authentication. The region overrides and model pins from the [Agent Platform setup](https://code.claude.com/docs/en/google-vertex-ai.md#4-configure-claude-code) apply through a gateway as well:

438438

439439* **Per-model regions**: if your gateway serves some models from a region other than `CLOUD_ML_REGION`, set the matching `VERTEX_REGION_CLAUDE_*` variable for each, for example `VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1`. The [environment variables reference](https://code.claude.com/docs/en/env-vars.md) lists the exact names.

from line 446

446446

447447For a gateway that injects its own `Authorization` header, set `CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1` and leave both credential variables unset. Claude Code then sends requests without an Azure credential and preserves the `Authorization` header you supply, for example through `ANTHROPIC_CUSTOM_HEADERS`.

448448

449**Bash or Zsh**

449> [tab] Bash or Zsh

450>

451> ```bash theme={null}

452> export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry

453> export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key

454> export CLAUDE_CODE_USE_FOUNDRY=1

455> ```

450456

451```bash theme={null}

452export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry

453export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key

454export CLAUDE_CODE_USE_FOUNDRY=1

455```

457> [tab] PowerShell

458>

459> ```powershell theme={null}

460> $env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"

461> $env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"

462> $env:CLAUDE_CODE_USE_FOUNDRY = "1"

463> ```

456464

457**PowerShell**

458

459```powershell theme={null}

460$env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"

461$env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"

462$env:CLAUDE_CODE_USE_FOUNDRY = "1"

463```

464

465465#### Claude Platform on AWS

466466

467467See [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md) for the workspace ID.

468468

469**Bash or Zsh**

469> [tab] Bash or Zsh

470>

471> ```bash theme={null}

472> export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws

473> export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN

474> export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1

475> export CLAUDE_CODE_USE_ANTHROPIC_AWS=1

476> ```

470477

471```bash theme={null}

472export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws

473export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN

474export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1

475export CLAUDE_CODE_USE_ANTHROPIC_AWS=1

476```

477

478**PowerShell**

479

480```powershell theme={null}

481$env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"

482$env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"

483$env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"

484$env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"

485```

478> [tab] PowerShell

479>

480> ```powershell theme={null}

481> $env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"

482> $env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"

483> $env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"

484> $env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"

485> ```

486486

487487#### Confirm the provider route

488488

llm-gateway-rollout Changed · +69 / -69 lines

from line 58

5858* `<gateway-key>` is whatever credential lets you call the gateway right now: an administrative key, a test key, or your own developer key if you've already issued one. Not every gateway product has a separate admin credential; if yours doesn't, issue yourself a developer key in [Issue developer credentials](#issue-developer-credentials) first

5959* `model` is a Claude model name your gateway is configured to route. The example uses `claude-sonnet-4-6`; substitute a name you've configured

6060

61**Bash or Zsh**

61> [tab] Bash or Zsh

62>

63> ```bash theme={null}

64> curl -X POST "https://llm-gateway.example.com/v1/messages" \

65> -H "Authorization: Bearer <gateway-key>" \

66> -H "anthropic-version: 2023-06-01" \

67> -H "content-type: application/json" \

68> -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

69> ```

6270

63```bash theme={null}

64curl -X POST "https://llm-gateway.example.com/v1/messages" \

65 -H "Authorization: Bearer <gateway-key>" \

66 -H "anthropic-version: 2023-06-01" \

67 -H "content-type: application/json" \

68 -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

69```

71> [tab] PowerShell

72>

73> ```powershell theme={null}

74> Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `

75> -Headers @{ "Authorization" = "Bearer <gateway-key>"; "anthropic-version" = "2023-06-01" } `

76> -ContentType "application/json" `

77> -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

78> ```

7079

71**PowerShell**

73```powershell theme={null}

74Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `

75 -Headers @{ "Authorization" = "Bearer <gateway-key>"; "anthropic-version" = "2023-06-01" } `

76 -ContentType "application/json" `

77 -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

78```

8080**Checkpoint**: a `200` with a `content` field means the gateway reached the provider with that model name. A `404` means that name isn't routed at the gateway; a `401` from the provider means the gateway's provider credential is wrong.

8181

8282Repeat the request once per Claude model name in your gateway's routing configuration. A name the gateway doesn't route returns `404` to any developer who selects it, so test every name before rollout.

from line 91

9191

9292Confirm a freshly issued key works against the gateway with the same request as [Confirm the gateway routes your models](#confirm-the-gateway-routes-your-models), replacing `<gateway-key>` with the new `<developer-key>`:

9393

94**Bash or Zsh**

94> [tab] Bash or Zsh

95>

96> ```bash theme={null}

97> curl -X POST "https://llm-gateway.example.com/v1/messages" \

98> -H "Authorization: Bearer <developer-key>" \

99> -H "anthropic-version: 2023-06-01" \

100> -H "content-type: application/json" \

101> -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

102> ```

95103

96```bash theme={null}

97curl -X POST "https://llm-gateway.example.com/v1/messages" \

98 -H "Authorization: Bearer <developer-key>" \

99 -H "anthropic-version: 2023-06-01" \

100 -H "content-type: application/json" \

101 -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

102```

104> [tab] PowerShell

105>

106> ```powershell theme={null}

107> Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `

108> -Headers @{ "Authorization" = "Bearer <developer-key>"; "anthropic-version" = "2023-06-01" } `

109> -ContentType "application/json" `

110> -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

111> ```

103112

104**PowerShell**

105

106```powershell theme={null}

107Invoke-RestMethod -Method Post -Uri "https://llm-gateway.example.com/v1/messages" `

108 -Headers @{ "Authorization" = "Bearer <developer-key>"; "anthropic-version" = "2023-06-01" } `

109 -ContentType "application/json" `

110 -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

111```

112

113113**Checkpoint**: a `200` with a `content` field means the developer key reaches the gateway and the gateway forwards it. A `401` here, when [the previous step](#confirm-the-gateway-routes-your-models) succeeded, means the developer key is wrong or hasn't taken effect at the gateway yet.

114114

115115Issuing one key per developer rather than a shared key is what makes per-developer usage attribution and individual offboarding work. The environment variable that holds the key depends on which header the gateway reads. For a gateway that checks credentials in the `Authorization: Bearer` header, developers set their key in `ANTHROPIC_AUTH_TOKEN`. For a gateway that reads keys from the `x-api-key` header, developers set `ANTHROPIC_API_KEY` instead; the [credential table](https://code.claude.com/docs/en/llm-gateway-connect.md#set-the-credential-variable) covers the mapping.

from line 118

118118

119119Run Claude Code through the gateway yourself before distributing anything, using the same configuration the rollout will deliver fleet-wide. Type these directly in a terminal, not in a `.env` or settings file; they last only for this terminal session, so closing it returns your machine to its normal configuration. Use `ANTHROPIC_API_KEY` instead of `ANTHROPIC_AUTH_TOKEN` if your gateway reads the `x-api-key` header:

120120

121**Bash or Zsh**

121> [tab] Bash or Zsh

122>

123> ```bash theme={null}

124> export ANTHROPIC_BASE_URL=https://llm-gateway.example.com

125> export ANTHROPIC_AUTH_TOKEN="<developer-key>"

126> ```

122127

123```bash theme={null}

124export ANTHROPIC_BASE_URL=https://llm-gateway.example.com

125export ANTHROPIC_AUTH_TOKEN="<developer-key>"

126```

128> [tab] PowerShell

129>

130> ```powershell theme={null}

131> $env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"

132> $env:ANTHROPIC_AUTH_TOKEN = "<developer-key>"

133> ```

127134

128**PowerShell**

129

130```powershell theme={null}

131$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"

132$env:ANTHROPIC_AUTH_TOKEN = "<developer-key>"

133```

134

135135Then send a one-shot prompt through the gateway:

136136

137137```bash theme={null}

from line 220

220220

221221Confirm everything works from a developer machine, not the gateway host, so the test covers the network path developers use. Send a streaming request, which checks the endpoint, streaming pass-through, and model routing at once:

222222

223**Bash or Zsh**

223> [tab] Bash or Zsh

224>

225> ```bash theme={null}

226> curl -N -X POST "https://llm-gateway.example.com/v1/messages" \

227> -H "Authorization: Bearer <developer-key>" \

228> -H "anthropic-version: 2023-06-01" \

229> -H "content-type: application/json" \

230> -d '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

231> ```

224232

225```bash theme={null}

226curl -N -X POST "https://llm-gateway.example.com/v1/messages" \

227 -H "Authorization: Bearer <developer-key>" \

228 -H "anthropic-version: 2023-06-01" \

229 -H "content-type: application/json" \

230 -d '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

231```

232

233**PowerShell**

234

235```powershell theme={null}

236$body = '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

237$body | curl.exe -N -X POST "https://llm-gateway.example.com/v1/messages" `

238 -H "Authorization: Bearer <developer-key>" `

239 -H "anthropic-version: 2023-06-01" `

240 -H "content-type: application/json" `

241 --data-binary '@-'

242```

233> [tab] PowerShell

234>

235> ```powershell theme={null}

236> $body = '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

237> $body | curl.exe -N -X POST "https://llm-gateway.example.com/v1/messages" `

238> -H "Authorization: Bearer <developer-key>" `

239> -H "anthropic-version: 2023-06-01" `

240> -H "content-type: application/json" `

241> --data-binary '@-'

242> ```

243243

244244You should see `data:` lines arrive incrementally. The whole response arriving at once after a pause means the gateway is buffering, which stalls Claude Code; a `404` means the model name isn't routed. Repeat per model name.

245245

managed-mcp Changed · +5 / -5 lines

from line 399

399399

400400The accordions below walk through how a server is evaluated against other allowlist and denylist combinations.

401401

402> **URL-only allowlist**

402> [accordion] URL-only allowlist

403403>

404404> ```json theme={null}

405405> {

from line 417

417417> | HTTP server at `https://external.example.com/mcp` | Blocked: doesn't match any URL pattern |

418418> | Stdio server with any command | Blocked: no name or command entries to match |

419419

420> **Command-only allowlist**

420> [accordion] Command-only allowlist

421421>

422422> ```json theme={null}

423423> {

from line 433

433433> | Stdio server with `["node", "server.js"]` | Blocked: doesn't match command |

434434> | HTTP server named `my-api` | Blocked: no name entries to match |

435435

436> **Mixed name and command allowlist**

436> [accordion] Mixed name and command allowlist

437437>

438438> ```json theme={null}

439439> {

from line 452

452452> | HTTP server named `github` | Allowed: matches name |

453453> | HTTP server named `other-api` | Blocked: name doesn't match |

454454

455> **Name-only allowlist**

455> [accordion] Name-only allowlist

456456>

457457> ```json theme={null}

458458> {

from line 470

470470> | HTTP server named `github` | Allowed: matches name |

471471> | Any server named `other` | Blocked: name doesn't match |

472472

473> **Allowlist with denylist override**

473> [accordion] Allowlist with denylist override

474474>

475475> ```json theme={null}

476476> {

mcp Changed · +38 / -38 lines

from line 1035

10351035

10361036The tabs cover both commands: `claude mcp add` takes your client ID and callback port as flags, and `claude mcp add-json` takes them in an `oauth` object. If you registered a redirect URI, set the callback port to the port in that URI.

10371037

1038**claude mcp add**

1038> [tab] claude mcp add

1039>

1040> Use `--client-id` to pass your app's client ID. The `--client-secret` flag prompts for the secret with masked input:

1041>

1042> ```bash theme={null}

1043> claude mcp add --transport http \

1044> --client-id your-client-id --client-secret --callback-port 8080 \

1045> my-server https://mcp.example.com/mcp

1046> ```

10391047

1040Use `--client-id` to pass your app's client ID. The `--client-secret` flag prompts for the secret with masked input:

1048> [tab] claude mcp add-json

1049>

1050> Include the `oauth` object in the JSON config and pass `--client-secret` as a separate flag:

1051>

1052> ```bash theme={null}

1053> claude mcp add-json my-server \

1054> '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \

1055> --client-secret

1056> ```

10411057

1042```bash theme={null}

1043claude mcp add --transport http \

1044 --client-id your-client-id --client-secret --callback-port 8080 \

1045 my-server https://mcp.example.com/mcp

1046```

1058> [tab] claude mcp add-json (callback port only)

1059>

1060> To fix only the callback port and let Claude Code register the client automatically, set `callbackPort` on its own:

1061>

1062> ```bash theme={null}

1063> claude mcp add-json my-server \

1064> '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

1065> ```

10471066

1048**claude mcp add-json**

1049

1050Include the `oauth` object in the JSON config and pass `--client-secret` as a separate flag:

1051

1052```bash theme={null}

1053claude mcp add-json my-server \

1054 '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \

1055 --client-secret

1056```

1057

1058**claude mcp add-json (callback port only)**

1059

1060To fix only the callback port and let Claude Code register the client automatically, set `callbackPort` on its own:

1061

1062```bash theme={null}

1063claude mcp add-json my-server \

1064 '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

1065```

1066

1067**CI / env var**

1068

1069Set the secret via environment variable to skip the interactive prompt:

1070

1071```bash theme={null}

1072MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \

1073 --client-id your-client-id --client-secret --callback-port 8080 \

1074 my-server https://mcp.example.com/mcp

1075```

1067> [tab] CI / env var

1068>

1069> Set the secret via environment variable to skip the interactive prompt:

1070>

1071> ```bash theme={null}

1072> MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \

1073> --client-id your-client-id --client-secret --callback-port 8080 \

1074> my-server https://mcp.example.com/mcp

1075> ```

10761076

10771077**3. Authenticate in Claude Code**

10781078

mcp-quickstart Changed · +7 / -7 lines

from line 282

282282

283283If a server doesn't connect, check its status with `/mcp` inside a session or `claude mcp list` from your shell, then match the symptom below. The `/mcp` panel also lets you reconnect or authenticate without leaving the session.

284284

285> **/mcp shows No MCP servers configured**

285> [accordion] /mcp shows No MCP servers configured

286286>

287287> Claude Code didn't find any servers for the current directory. The most common causes:

288288>

from line 290

290290> * You edited a configuration file at the wrong path. The correct files are `~/.claude.json` and `<project>/.mcp.json`. Claude Code doesn't read paths such as `~/.claude/.mcp.json`, `~/.claude/config/mcp.json`, `~/.claude/mcp.json`, or `%APPDATA%\Claude\mcp.json`. For user-scoped servers, run `claude mcp add --scope user`, which writes to the `mcpServers` key in `~/.claude.json`; for project-scoped servers, edit `.mcp.json` at the project root.

291291> * You wrote a malformed entry in `.mcp.json`. Claude Code skips that entry and still loads the others. Run `claude mcp list` from your shell and look for the parse warning, which names the offending field.

292292

293> **Status shows Failed to connect or Connection error**

293> [accordion] Status shows Failed to connect or Connection error

294294>

295295> Both statuses mean the server didn't start or the URL didn't respond. They can also appear for HTTP servers that reject the token you configured in `headers.Authorization`; a server that wants a token you haven't configured shows `! Needs authentication` instead, covered in [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in).

296296>

from line 330

330330> Run `claude mcp get <name>` and confirm the command shown there matches what you just ran. If the command shown differs from what you typed, you likely omitted the `--` separator before the server command. Remove the server and re-add it with `--` in place. If you wrote `.mcp.json` by hand, check its syntax and location. Before v2.1.285, `claude mcp get` printed no `Command` line for a stdio entry saved without a `type` field, such as a hand-written `.mcp.json` entry. On those versions, run `claude mcp list` instead, which prints the command line either way.

331331> * The command errors: the message names what's missing, such as Node.js or a browser.

332332

333> **Connection timed out at startup**

333> [accordion] Connection timed out at startup

334334>

335335> The server took longer than the default 30-second startup timeout. A stdio server's first run can be slow while `npx` downloads the package. Increase the limit with the [`MCP_TIMEOUT`](https://code.claude.com/docs/en/env-vars) environment variable, in milliseconds:

336336>

from line 346

346346>

347347> Before v2.1.299, some connections to HTTP servers that were up timed out at startup regardless of `MCP_TIMEOUT`. If you use one of those versions and an HTTP server that is up still times out after you raise the limit, [update Claude Code](https://code.claude.com/docs/en/setup.md#update-claude-code).

348348

349> **Server already exists**

349> [accordion] Server already exists

350350>

351351> You've already added a server with that name at the same scope. Either remove the existing entry first or choose a different name:

352352>

from line 356

356356>

357357> If the name exists at more than one scope, `remove` reports `exists in multiple scopes`. Pass `--scope` to choose which copy to delete, for example `claude mcp remove claude-code-docs --scope local`.

358358

359> **Server connects but no tools appear**

359> [accordion] Server connects but no tools appear

360360>

361361> Run `/mcp` inside a session and select the server to see its tool list. If the list is empty, the server started but didn't register any tools, which usually means it's missing a required environment variable such as an API key.

362362>

from line 364

364364>

365365> Before v2.1.302, `/mcp` showed the status `tools fetch failed` for a server using [protocol revision 2026-07-28](https://code.claude.com/docs/en/mcp.md#mcp-client-runtimes) that left `resultType`, `ttlMs`, or `cacheScope` out of its replies. If you use one of those versions and a server shows that status, [update Claude Code](https://code.claude.com/docs/en/setup.md#update-claude-code).

366366

367> **Changes to .mcp.json don't take effect**

367> [accordion] Changes to .mcp.json don't take effect

368368>

369369> Claude Code reads `.mcp.json` at session start. Exit and restart the session after editing the file.

370370>

from line 376

376376> claude mcp reset-project-choices

377377> ```

378378

379> **OAuth sign-in fails or browser doesn't open**

379> [accordion] OAuth sign-in fails or browser doesn't open

380380>

381381> Run `/mcp`, select the server, and choose `Authenticate` again. If the browser doesn't open automatically, copy the URL shown in the terminal and open it manually. See [Authenticate with remote MCP servers](https://code.claude.com/docs/en/mcp.md#authenticate-with-remote-mcp-servers) for fixed callback ports and pre-configured credentials.

382382

model-config Changed · +4 / -4 lines

from line 451

451451

452452The behavior of `default` depends on your account type:

453453

454* **Pro, Max, Team, Enterprise, and Anthropic API**: defaults to Opus 5.5

454* **Pro, Max, Ultra, Team, Enterprise, and Anthropic API**: defaults to Opus 5.5

455455* **Claude Platform on AWS, Amazon Bedrock, and Google Cloud's Agent Platform**: defaults to Opus 5.5

456456* **Microsoft Foundry**: defaults to Sonnet 4.5

457457

458Before v2.1.280, `default` resolved to Sonnet 5 on Pro and Team Standard, and to Opus 5 on Max, Team Premium, Enterprise, the Anthropic API, Claude Platform on AWS, Amazon Bedrock, and Google Cloud's Agent Platform from v2.1.219. Before v2.1.219, `default` resolved to Opus 4.8 on the Anthropic API, Max, Team Premium, and Enterprise pay-as-you-go from v2.1.154, and on Claude Platform on AWS, Amazon Bedrock, and Google Cloud's Agent Platform from v2.1.207. Before v2.1.207, `default` resolved to Opus 4.7 on Claude Platform on AWS and to Sonnet 4.5 on Amazon Bedrock and Google Cloud's Agent Platform.

458Before v2.1.280, `default` resolved to Sonnet 5 on Pro and Team Standard, and to Opus 5 on Max, Ultra, Team Premium, Enterprise, the Anthropic API, Claude Platform on AWS, Amazon Bedrock, and Google Cloud's Agent Platform from v2.1.219. Before v2.1.219, `default` resolved to Opus 4.8 on the Anthropic API, Max, Ultra, Team Premium, and Enterprise pay-as-you-go from v2.1.154, and on Claude Platform on AWS, Amazon Bedrock, and Google Cloud's Agent Platform from v2.1.207. Before v2.1.207, `default` resolved to Opus 4.7 on Claude Platform on AWS and to Sonnet 4.5 on Amazon Bedrock and Google Cloud's Agent Platform.

459459

460460When an admin has set an [organization default model](#organization-default-model), `default` resolves to that model instead of the account-type default above. Requires Claude Code v2.1.196 or later. `default` can also resolve to the model you set with [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions), under the conditions listed in its section, or to the model [recorded on your account](#setting-your-model).

461461

from line 754

754754

755755Fable 5.1, Fable 5, Sonnet 5 and later, Haiku 5.5, and Opus 4.7 and later run with the 1M window by default, with no `[1m]` suffix needed. That includes sessions on Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, and [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) sessions. To run them with a 200K window instead, see [Turn off 1M context](#turn-off-1m-context).

756756

757Opus 4.6 and Sonnet 4.6 reach 1M only through their `[1m]` variant, and access to that variant depends on your plan. On Max, Team, and Enterprise plans, including both Team Standard and Team Premium seats, Opus 4.6 with 1M context is included with your subscription. Sonnet 4.6 with 1M context requires [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) on every subscription plan, including Max.

757Opus 4.6 and Sonnet 4.6 reach 1M only through their `[1m]` variant, and access to that variant depends on your plan. On Max, Ultra, Team, and Enterprise plans, including both Team Standard and Team Premium seats, Opus 4.6 with 1M context is included with your subscription. Sonnet 4.6 with 1M context requires [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) on every subscription plan, including Max and Ultra.

758758

759759| Plan | Opus 4.6 with 1M context | Sonnet 4.6 with 1M context |

760760| - | - | - |

761| Max, Team, and Enterprise | Included with subscription | Requires [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

761| Max, Ultra, Team, and Enterprise | Included with subscription | Requires [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

762762| Pro | Requires [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) | Requires [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

763763| API and pay-as-you-go | Full access | Full access |

764764

overview Changed · +127 / -127 lines

from line 8

99Claude Code runs on several surfaces: the terminal, IDE extensions, a desktop app, and the web. Choose one from the tabs below to get started. Most surfaces require a [Claude subscription](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_pricing) or [Anthropic Console](https://platform.claude.com/) account. The Terminal CLI, VS Code, and JetBrains also support [third-party providers](https://code.claude.com/docs/en/third-party-integrations.md).

1010

11**Terminal**

11> [tab] Terminal

12>

13> The full-featured CLI for working with Claude Code directly in your terminal. Edit files, run commands, and manage your entire project from the command line.

14>

15> To install Claude Code, open a terminal and run the command for your system. If you haven't used a terminal before, the [terminal guide](https://code.claude.com/docs/en/terminal-guide) shows how to open one and paste the command.

16>

17> > [tab] Native Install (Recommended)

18> >

19> > **macOS, Linux, WSL:**

20> >

21> > ```bash theme={null}

22> > curl -fsSL https://claude.ai/install.sh | bash

23> > ```

24> >

25> > On Windows, your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.

26> >

27> > **Windows PowerShell:**

28> >

29> > ```powershell theme={null}

30> > irm https://claude.ai/install.ps1 | iex

31> > ```

32> >

33> > **Windows CMD:**

34> >

35> > ```batch theme={null}

36> > curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

37> > ```

38> >

39> > The install command shows no progress while it downloads Claude Code. When the installer finishes, open a new terminal window and run `claude --version`. A working installation prints a version number. If your shell says `claude` isn't found or isn't recognized, the install directory isn't on your PATH yet: see [Fix your PATH](https://code.claude.com/docs/en/troubleshoot-install.md#command-not-found-claude-after-installation).

40> >

41> > If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell.

42> >

43> > If the install command fails with `syntax error near unexpected token '<'`, a `403`, or any other error, see [Troubleshoot installation](https://code.claude.com/docs/en/troubleshoot-install.md#find-your-error) to match the error to a fix and for alternative install methods.

44> >

45> > [Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.

46> >

47> > > [!NOTE]

48> > >

49> > > Native installations automatically update in the background to keep you on the latest version.

50>

51> > [tab] Homebrew

52> >

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

54> > brew install --cask claude-code

55> > ```

56> >

57> > Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.

58> >

59> > > [!NOTE]

60> > >

61> > > Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.

62>

63> > [tab] WinGet

64> >

65> > ```powershell theme={null}

66> > winget install Anthropic.ClaudeCode

67> > ```

68> >

69> > > [!NOTE]

70> > >

71> > > WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.

72>

73> You can also install with [apt, dnf, or apk](https://code.claude.com/docs/en/setup.md#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.

74>

75> Then start Claude Code in any project. Replace `your-project` with the path to a project directory on your machine:

76>

77> ```bash theme={null}

78> cd your-project

79> claude

80> ```

81>

82> Claude Code prompts you to log in on first use. If you've set the `ANTHROPIC_API_KEY` environment variable and you approve the key when Claude Code asks whether to use it, Claude Code skips the login prompt. [Continue with the Quickstart →](https://code.claude.com/docs/en/quickstart.md)

83>

84> > [!TIP]

85> >

86> > See [advanced setup](https://code.claude.com/docs/en/setup.md) for installation options, manual updates, or uninstallation instructions. Visit [installation troubleshooting](https://code.claude.com/docs/en/troubleshoot-install.md) if you hit issues.

1287

13The full-featured CLI for working with Claude Code directly in your terminal. Edit files, run commands, and manage your entire project from the command line.

15To install Claude Code, open a terminal and run the command for your system. If you haven't used a terminal before, the [terminal guide](https://code.claude.com/docs/en/terminal-guide) shows how to open one and paste the command.

17**Native Install (Recommended)**

19**macOS, Linux, WSL:**

21```bash theme={null}

22curl -fsSL https://claude.ai/install.sh | bash

23```

25On Windows, your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.

27**Windows PowerShell:**

29```powershell theme={null}

30irm https://claude.ai/install.ps1 | iex

31```

33**Windows CMD:**

35```batch theme={null}

36curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

37```

39The install command shows no progress while it downloads Claude Code. When the installer finishes, open a new terminal window and run `claude --version`. A working installation prints a version number. If your shell says `claude` isn't found or isn't recognized, the install directory isn't on your PATH yet: see [Fix your PATH](https://code.claude.com/docs/en/troubleshoot-install.md#command-not-found-claude-after-installation).

41If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell.

43If the install command fails with `syntax error near unexpected token '<'`, a `403`, or any other error, see [Troubleshoot installation](https://code.claude.com/docs/en/troubleshoot-install.md#find-your-error) to match the error to a fix and for alternative install methods.

45[Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.

47> [!NOTE]

88> [tab] VS Code

4889>

49> Native installations automatically update in the background to keep you on the latest version.

90> The VS Code extension provides inline diffs, @-mentions, plan review, and conversation history directly in your editor.

91>

92> * [Install for VS Code](vscode:extension/anthropic.claude-code)

93> * [Install for Cursor](cursor:extension/anthropic.claude-code)

94>

95> Or search for "Claude Code" in the Extensions view (`Cmd+Shift+X` on Mac, `Ctrl+Shift+X` on Windows/Linux). After installing, open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`), type "Claude Code", and select **Open in New Tab**.

96>

97> [Get started with VS Code →](https://code.claude.com/docs/en/vs-code.md#get-started)

5098

51**Homebrew**

53```bash theme={null}

54brew install --cask claude-code

55```

57Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.

59> [!NOTE]

99> [tab] Desktop app

60100>

61> Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.

101> A standalone app for running Claude Code outside your IDE or terminal. Review diffs visually, run multiple sessions side by side, schedule recurring tasks, and start cloud sessions.

102>

103> Download and install:

104>

105> * [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) (Intel and Apple Silicon)

106> * [Windows](https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs) (x64)

107> * [Windows ARM64](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs)

108> * On Ubuntu or Debian, where the app is in beta, install it with apt by following the [Linux install instructions](https://code.claude.com/docs/en/desktop-linux.md)

109>

110> After installing, launch Claude, sign in, and click the **Code** tab to start coding. The app includes Claude Code, so you don't need to install the CLI separately. A [paid subscription](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_desktop_pricing) is required.

111>

112> [Learn more about the desktop app →](https://code.claude.com/docs/en/desktop-quickstart.md)

62113

63**WinGet**

65```powershell theme={null}

66winget install Anthropic.ClaudeCode

67```

69> [!NOTE]

114> [tab] Web

70115>

71> WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.

116> Run Claude Code in your browser with no local setup. Kick off long-running tasks and check back when they're done, work on repos you don't have locally, or run multiple tasks in parallel. For a longer body of work, create a [project](https://code.claude.com/docs/en/claude-projects.md) and let Claude coordinate the parallel sessions for you. Available on desktop browsers and [the Claude app for iOS and Android](https://code.claude.com/docs/en/mobile.md).

117>

118> Start coding at [claude.ai/code](https://claude.ai/code).

119>

120> [Get started →](https://code.claude.com/docs/en/web-quickstart.md)

72121

73You can also install with [apt, dnf, or apk](https://code.claude.com/docs/en/setup.md#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.

75Then start Claude Code in any project. Replace `your-project` with the path to a project directory on your machine:

77```bash theme={null}

78cd your-project

79claude

80```

82Claude Code prompts you to log in on first use. If you've set the `ANTHROPIC_API_KEY` environment variable and you approve the key when Claude Code asks whether to use it, Claude Code skips the login prompt. [Continue with the Quickstart →](https://code.claude.com/docs/en/quickstart.md)

84> [!TIP]

122> [tab] JetBrains

85123>

86> See [advanced setup](https://code.claude.com/docs/en/setup.md) for installation options, manual updates, or uninstallation instructions. Visit [installation troubleshooting](https://code.claude.com/docs/en/troubleshoot-install.md) if you hit issues.

124> A plugin for IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs with interactive diff viewing and selection context sharing.

125>

126> Install the [Claude Code plugin](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) from the JetBrains Marketplace and restart your IDE. The plugin requires the Claude Code CLI, installed separately; see the [JetBrains setup steps](https://code.claude.com/docs/en/jetbrains.md#installation).

127>

128> [Get started with JetBrains →](https://code.claude.com/docs/en/jetbrains.md)

87129

88**VS Code**

90The VS Code extension provides inline diffs, @-mentions, plan review, and conversation history directly in your editor.

92* [Install for VS Code](vscode:extension/anthropic.claude-code)

93* [Install for Cursor](cursor:extension/anthropic.claude-code)

95Or search for "Claude Code" in the Extensions view (`Cmd+Shift+X` on Mac, `Ctrl+Shift+X` on Windows/Linux). After installing, open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`), type "Claude Code", and select **Open in New Tab**.

97[Get started with VS Code →](https://code.claude.com/docs/en/vs-code.md#get-started)

99**Desktop app**

100

101A standalone app for running Claude Code outside your IDE or terminal. Review diffs visually, run multiple sessions side by side, schedule recurring tasks, and start cloud sessions.

102

103Download and install:

104

105* [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) (Intel and Apple Silicon)

106* [Windows](https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs) (x64)

107* [Windows ARM64](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs)

108* On Ubuntu or Debian, where the app is in beta, install it with apt by following the [Linux install instructions](https://code.claude.com/docs/en/desktop-linux.md)

109

110After installing, launch Claude, sign in, and click the **Code** tab to start coding. The app includes Claude Code, so you don't need to install the CLI separately. A [paid subscription](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_desktop_pricing) is required.

111

112[Learn more about the desktop app →](https://code.claude.com/docs/en/desktop-quickstart.md)

113

114**Web**

115

116Run Claude Code in your browser with no local setup. Kick off long-running tasks and check back when they're done, work on repos you don't have locally, or run multiple tasks in parallel. For a longer body of work, create a [project](https://code.claude.com/docs/en/claude-projects.md) and let Claude coordinate the parallel sessions for you. Available on desktop browsers and [the Claude app for iOS and Android](https://code.claude.com/docs/en/mobile.md).

117

118Start coding at [claude.ai/code](https://claude.ai/code).

119

120[Get started →](https://code.claude.com/docs/en/web-quickstart.md)

121

122**JetBrains**

123

124A plugin for IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs with interactive diff viewing and selection context sharing.

125

126Install the [Claude Code plugin](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) from the JetBrains Marketplace and restart your IDE. The plugin requires the Claude Code CLI, installed separately; see the [JetBrains setup steps](https://code.claude.com/docs/en/jetbrains.md#installation).

127

128[Get started with JetBrains →](https://code.claude.com/docs/en/jetbrains.md)

129

130130## What you can do

131131

132132Here are some of the ways you can use Claude Code:

133133

134> **Automate the work you keep putting off**

134> [accordion] Automate the work you keep putting off

135135>

136136> Claude Code handles the tedious tasks that eat up your day: writing tests for untested code, fixing lint errors across a project, resolving merge conflicts, updating dependencies, and writing release notes.

137137>

from line 139

139139> claude "write tests for the auth module, run them, and fix any failures"

140140> ```

141141

142> **Build features and fix bugs**

142> [accordion] Build features and fix bugs

143143>

144144> Describe what you want in plain language. Claude Code plans the approach, writes the code across multiple files, and verifies it works.

145145>

146146> For bugs, paste an error message or describe the symptom. Claude Code traces the issue through your codebase, identifies the root cause, and implements a fix. See [common workflows](https://code.claude.com/docs/en/common-workflows.md) for more examples.

147147

148> **Create commits and pull requests**

148> [accordion] Create commits and pull requests

149149>

150150> Claude Code works directly with git. It stages changes, writes commit messages, creates branches, and opens pull requests.

151151>

from line 155

155155>

156156> In CI, you can automate code review and issue triage with [GitHub Actions](https://code.claude.com/docs/en/github-actions.md) or [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md).

157157

158> **Connect your tools with MCP**

158> [accordion] Connect your tools with MCP

159159>

160160> The [Model Context Protocol (MCP)](https://code.claude.com/docs/en/mcp.md) is an open standard for connecting AI tools to external data sources. With MCP, Claude Code can read your design docs in Google Drive, update tickets in Jira, pull data from Slack, or use your own custom tooling. The [MCP quickstart](https://code.claude.com/docs/en/mcp-quickstart.md) connects your first server end to end.

161161

162> **Customize with instructions, skills, and hooks**

162> [accordion] Customize with instructions, skills, and hooks

163163>

164164> [`CLAUDE.md`](https://code.claude.com/docs/en/memory) is a markdown file you add to your project root that Claude Code reads at the start of every session. Use it to set coding standards, architecture decisions, preferred libraries, and review checklists. If your repository already has an `AGENTS.md` for other coding agents, Claude Code [can read that](https://code.claude.com/docs/en/memory.md#agents-md) in place of a `CLAUDE.md`. Claude also builds [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) as it works, saving learnings across sessions without you writing anything.

165165>

from line 167

167167>

168168> [Hooks](https://code.claude.com/docs/en/hooks.md) let you run shell commands before or after Claude Code actions, like auto-formatting after every file edit or running lint before a commit.

169169

170> **Run agents in parallel and build custom agents**

170> [accordion] Run agents in parallel and build custom agents

171171>

172172> Spawn [multiple Claude Code agents](https://code.claude.com/docs/en/sub-agents.md) that work on different parts of a task simultaneously. A lead agent coordinates the work, assigns subtasks, and merges results.

173173>

174174> To run several full sessions in parallel and watch them from one screen, use [background agents](https://code.claude.com/docs/en/agent-view.md). For fully custom workflows, the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) lets you build your own agents powered by Claude Code's tools and capabilities, with full control over orchestration, tool access, and permissions.

175175

176> **Pipe, script, and automate with the CLI**

176> [accordion] Pipe, script, and automate with the CLI

177177>

178178> Claude Code is composable and follows the Unix philosophy. Pipe logs into it, run it in CI, or chain it with other tools:

179179>

from line 190

190190>

191191> See the [CLI reference](https://code.claude.com/docs/en/cli-reference.md) for the full set of commands and flags.

192192

193> **Schedule recurring tasks**

193> [accordion] Schedule recurring tasks

194194>

195195> Run Claude on a schedule to automate work that repeats: morning PR reviews, overnight CI failure analysis, weekly dependency audits, or syncing docs after PRs merge.

196196>

from line 198

198198> * [Desktop scheduled tasks](https://code.claude.com/docs/en/desktop-scheduled-tasks.md) run on your machine, with direct access to your local files and tools

199199> * [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) repeats a prompt within a CLI session for quick polling

200200

201> **Work from anywhere**

201> [accordion] Work from anywhere

202202>

203203> Sessions aren't tied to a single surface. Move work between them as your context changes:

204204>

permission-modes Changed · +148 / -143 lines

from line 4

55A permission mode sets which actions Claude can take in a session without asking you first. In Manual mode, Claude Code stops and asks you before most actions that edit files, run shell commands, or reach the network. In [auto mode](#eliminate-prompts-with-auto-mode), a second model, the classifier, reviews actions instead of you; [how the classifier evaluates actions](#how-the-classifier-evaluates-actions) lists which actions it reviews and which skip it.

7With Claude Code v2.1.283 or later, auto mode is the built-in starting permission mode for interactive terminal and VS Code sessions. On earlier versions, it's the built-in starting permission mode only on Pro, Max, and Team plans. [Which mode a session starts in](#which-mode-a-session-starts-in) covers the surfaces and settings that change the starting permission mode. You can also change a running session's permission mode at any time.

7With Claude Code v2.1.283 or later, auto mode is the built-in starting permission mode for interactive terminal and VS Code sessions. On earlier versions, it's the built-in starting permission mode only on Pro, Max, Ultra, and Team plans. [Which mode a session starts in](#which-mode-a-session-starts-in) covers the surfaces and settings that change the starting permission mode. You can also change a running session's permission mode at any time.

99## Available modes

1010

from line 76

7676| Any settings file sets `disableAutoMode` to `"disable"` | `default` |

7777| `claude -p` or the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/permissions.md#permission-modes) | `default` |

7878| Your organization has the [HIPAA configuration](#hipaa-configuration) applied and the session is [eligible for it](https://code.claude.com/docs/en/hipaa-setup.md#check-how-developers-sign-in-and-connect) | `default` with Claude Code v2.1.285 or later; auto mode stays available to switch to |

79| In a terminal or through the [VS Code extension](https://code.claude.com/docs/en/vs-code.md) | `auto` with Claude Code v2.1.283 or later; on earlier versions, `auto` on Pro, Max, or Team plans in sessions that [fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), and `default` otherwise |

79| In a terminal or through the [VS Code extension](https://code.claude.com/docs/en/vs-code.md) | `auto` with Claude Code v2.1.283 or later; on earlier versions, `auto` on Pro, Max, Ultra, or Team plans in sessions that [fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), and `default` otherwise |

8080

8181When the flag, a settings file, or the built-in default selects `auto` but auto mode isn't available to the session, Claude Code starts the session in Manual instead. Auto mode is unavailable when the session doesn't meet the [availability requirements](#eliminate-prompts-with-auto-mode), such as a settings file turning it off or a model that doesn't support it, or when Anthropic has temporarily turned it off server-side.

8282

from line 85

8585* In a terminal, once, at the top of the session

8686* In the VS Code extension, as a card on the new-conversation screen that stays until you dismiss it

8787

88If your `~/.claude/settings.json` sets a `defaultMode` other than `auto` and no other settings file sets one, your sessions keep starting in that mode. On Pro, Max, and Team plans, and in sessions that [don't fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), Claude Code asks once, in the terminal or in the VS Code extension, whether to change the setting to auto mode. If you decline, your setting stays as it is.

88If your `~/.claude/settings.json` sets a `defaultMode` other than `auto` and no other settings file sets one, your sessions keep starting in that mode.

8989

90On Pro, Max, Ultra, and Team plans, and in sessions that [don't fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), Claude Code asks once whether to change the setting to auto mode. The question appears in the terminal or in the VS Code extension, and if you decline, your setting stays as it is.

9092### Tool calls denied in `claude -p` and Agent SDK runs

9193

9294In Claude Code v2.1.302 or later, `claude -p` and [Agent SDK](https://code.claude.com/docs/en/agent-sdk/permissions.md#permission-modes) runs with [no permission mode set](#which-mode-a-session-starts-in) start in Manual mode. This mode appears as `default` in SDK options and settings. Calls needing approval are denied unless you approve them with an allow rule, hook, `canUseTool` callback, or `--permission-prompt-tool`.

from line 100

98100

99101These examples show the auto mode form for the CLI and each SDK:

100102

101**CLI**

103> [tab] CLI

104>

105> ```bash theme={null}

106> claude -p "Run the test suite and fix any failures" --permission-mode auto

107> ```

102108

103```bash theme={null}

104claude -p "Run the test suite and fix any failures" --permission-mode auto

105```

109> [tab] TypeScript

110>

111> ```typescript theme={null}

112> const options = {

113> permissionMode: "auto"

114> };

115> ```

106116

107**TypeScript**

117> [tab] Python

118>

119> ```python theme={null}

120> from claude_agent_sdk import ClaudeAgentOptions

121>

122> options = ClaudeAgentOptions(permission_mode="auto")

123> ```

108124

109```typescript theme={null}

110const options = {

111 permissionMode: "auto"

112};

113```

114

115**Python**

116

117```python theme={null}

118from claude_agent_sdk import ClaudeAgentOptions

119

120options = ClaudeAgentOptions(permission_mode="auto")

121```

122

123125Before v2.1.302, these runs could start in auto mode if they didn't [fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), for example on a [third-party provider](https://code.claude.com/docs/en/third-party-integrations.md) or with `DISABLE_TELEMETRY`.

124126

125127### Start in a different permission mode

from line 164

162164

163165Each interface has its own control for switching permission modes during a session and its own way of choosing the permission mode new sessions start in. Select your interface to see its controls.

164166

165**CLI**

167> [tab] CLI

168>

169> **During a session**: press `Shift+Tab` to cycle permission modes. From `auto`, the first press switches to `default`, and the cycle then runs `default` → `acceptEdits` → `plan`. Optional modes slot in after `plan`. The status bar shows the active mode as a gray `⏸ manual mode on` for `default`, or as `⏵⏵ accept edits on`, `⏸ plan mode on`, `⏵⏵ auto mode on`, `⏵⏵ don't ask on`, or `⏵⏵ bypass permissions on`.

170>

171> Watch the status bar in this clip of a session that started in auto mode. Each time you press `Shift+Tab`, it changes from `auto mode on` to `manual mode on`, `accept edits on`, `plan mode on`, and back to `auto mode on`.

172>

173> <video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/tA-x-5L2YsYSVdee/images/permission-modes-cycle-light.mp4?fit=max&auto=format&n=tA-x-5L2YsYSVdee&q=85&s=3927dd62d59b01efd81b3578f2a6f971" aria-label="The status bar under the Claude Code prompt changes with each press of Shift+Tab: auto mode on, manual mode on, accept edits on, plan mode on, then auto mode on again." />

174>

175> Not every mode is in the default cycle:

176>

177> * `auto`: appears when [auto mode is available](#eliminate-prompts-with-auto-mode); cycling to it switches permission modes without a confirmation prompt

178> * `bypassPermissions`: appears after you start with `--permission-mode bypassPermissions`, `--dangerously-skip-permissions`, `--allow-dangerously-skip-permissions`, or `permissions.defaultMode: "bypassPermissions"` in [user, `--settings`, or managed settings](https://code.claude.com/docs/en/settings-reference#permissions-defaultmode). The `--allow-` variant adds the permission mode to the cycle without activating it

179> * `dontAsk`: never appears in the cycle; set it with `--permission-mode dontAsk`

180>

181> Enabled optional modes slot in after `plan`, with `bypassPermissions` first and `auto` last. If you have both enabled, you will cycle through `bypassPermissions` on the way to `auto`.

182>

183> **From a Bash permission prompt**: in the Manual and `acceptEdits` permission modes, when [auto mode](#eliminate-prompts-with-auto-mode) is available, Claude Code adds **Yes, and switch to auto mode** to a Bash command's permission prompt. Select it to approve the command and switch the session to auto mode. [PowerShell tool](https://code.claude.com/docs/en/tools-reference.md#powershell-tool) prompts don't offer the option. Requires Claude Code v2.1.247 or later.

184>

185> Claude Code doesn't add the option to prompts forced by one of your [`ask` rules](https://code.claude.com/docs/en/permissions#manage-permissions) or by a [hook](https://code.claude.com/docs/en/hooks.md#pretooluse-decision-control), because auto mode still shows you those prompts, so switching wouldn't remove them.

186>

187> **At startup**: pass the permission mode as a flag.

188>

189> ```bash theme={null}

190> claude --permission-mode plan

191> ```

192>

193> **As a default**: set `permissions.defaultMode` at the scope you want, as described in [Start in a different permission mode](#start-in-a-different-mode).

194>

195> The same `--permission-mode` flag works with `-p` for [non-interactive runs](https://code.claude.com/docs/en/headless.md).

166196

167**During a session**: press `Shift+Tab` to cycle permission modes. From `auto`, the first press switches to `default`, and the cycle then runs `default` → `acceptEdits` → `plan`. Optional modes slot in after `plan`. The status bar shows the active mode as a gray `⏸ manual mode on` for `default`, or as `⏵⏵ accept edits on`, `⏸ plan mode on`, `⏵⏵ auto mode on`, `⏵⏵ don't ask on`, or `⏵⏵ bypass permissions on`.

197> [tab] VS Code

198>

199> **During a session**: click the mode indicator at the bottom of the prompt box. It uses these labels for the modes on this page:

200>

201> | UI label | Mode |

202> | :- | :- |

203> | Manual | `default` |

204> | Edit automatically | `acceptEdits` |

205> | Plan | `plan` |

206> | Auto | `auto` |

207> | Bypass permissions | `bypassPermissions` |

208>

209> **As a default**: to pin the permission mode conversations start in, set `claudeCode.initialPermissionMode` in your VS Code user settings to `default`, `manual`, `acceptEdits`, `plan`, or `bypassPermissions`. The setting doesn't accept `auto`; to start in Auto, leave it unset and pick **Auto** from the mode indicator once, as item 2 below describes. The extension starts each new conversation in the first of these that applies:

210>

211> 1. `claudeCode.initialPermissionMode`

212> 2. The mode you last picked from the mode indicator, if it was Manual, Edit automatically, or Auto. Picking Plan or Bypass permissions applies to that conversation only

213> 3. `permissions.defaultMode` from [managed settings](https://code.claude.com/docs/en/managed-settings.md) or `~/.claude/settings.json`

214> 4. The [built-in default](#which-mode-a-session-starts-in) for your plan, provider, and organization settings

215>

216> The extension never reads a project's `.claude/settings.json` or `.claude/settings.local.json` for the starting permission mode. When `claudeCode.claudeProcessWrapper` is set, items 3 and 4 don't apply: those conversations start in Manual unless item 1 or item 2 sets a permission mode.

217>

218> Before v2.1.283, item 3 applied only on Pro, Max, Ultra, and Team plans in sessions that [fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching).

219>

220> Auto appears in the mode indicator when [auto mode is available](#eliminate-prompts-with-auto-mode).

221>

222> Bypass permissions requires the **Allow dangerously skip permissions** toggle in the extension settings. Without it, the permission mode doesn't appear in the indicator, and a `bypassPermissions` value from item 1 or item 3 starts the conversation in Manual instead. Auto from any item likewise starts the conversation in Manual when auto mode isn't available.

223>

224> See the [VS Code guide](https://code.claude.com/docs/en/vs-code.md) for extension-specific details.

168225

169Watch the status bar in this clip of a session that started in auto mode. Each time you press `Shift+Tab`, it changes from `auto mode on` to `manual mode on`, `accept edits on`, `plan mode on`, and back to `auto mode on`.

226> [tab] JetBrains

227>

228> The JetBrains plugin runs Claude Code in the IDE terminal, so switching permission modes works the same as in the CLI: press `Shift+Tab` to cycle, or pass `--permission-mode` when launching.

170229

171<video autoPlay muted loop playsInline src="https://mintcdn.com/claude-code/tA-x-5L2YsYSVdee/images/permission-modes-cycle-light.mp4?fit=max&auto=format&n=tA-x-5L2YsYSVdee&q=85&s=3927dd62d59b01efd81b3578f2a6f971" aria-label="The status bar under the Claude Code prompt changes with each press of Shift+Tab: auto mode on, manual mode on, accept edits on, plan mode on, then auto mode on again." />

230> [tab] Desktop

231>

232> **During a session**: in the Code tab, use the mode selector in the row under the prompt box. Not every mode appears in the selector:

233>

234> * **Auto**: appears when [auto mode is available](#eliminate-prompts-with-auto-mode)

235> * **Bypass permissions**: requires the **Allow bypass permissions mode** toggle in Desktop settings on Pro, Max, and Ultra plans; on Team and Enterprise plans, organization policy controls it instead

236>

237> Cowork doesn't use these modes. It has its own permission modes, enabled separately, and shows no mode selector at all until a mode beyond its default is enabled for your account. See the [Cowork docs](https://claude.com/docs/cowork/overview).

238>

239> For desktop-specific details, see [Choose a permission mode](https://code.claude.com/docs/en/desktop.md#choose-a-permission-mode) in the Desktop guide.

240>

241> **As a default**: set `defaultMode` in [settings](https://code.claude.com/docs/en/settings.md#where-settings-live). The desktop app reads the same settings files as the CLI and applies the permission mode to new local sessions.

242>

243> A mode you pick in the mode selector is remembered per folder and takes precedence over `defaultMode` for that folder. Plan is the exception: picking it applies to the current session only.

244>

245> For where `defaultMode` goes in a settings file, see the example under [Start in a different permission mode](#start-in-a-different-mode).

172246

173Not every mode is in the default cycle:

247> [tab] Web and mobile

248>

249> On [claude.ai/code](https://claude.ai/code), use the mode dropdown in the row under the prompt box. In the mobile app, tap the **+** button in the prompt box, then **Permission**. Cloud sessions and Remote Control sessions offer different permission modes:

250>

251> * **[Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md)**: Accept edits, Plan, and Auto. Accept edits corresponds to `default` mode: cloud sessions pre-approve file edits regardless of mode, so the dropdown shows Accept edits instead of Manual. Cloud sessions still honor `defaultMode: "acceptEdits"` from settings. Auto mode appears only when your organization allows it and the selected model supports it. Bypass permissions isn't available.

252> * **[Remote Control](https://code.claude.com/docs/en/remote-control.md) sessions** on your local machine: Manual, Accept edits, Plan, and Auto for a session you started yourself, and you can't select Bypass permissions from the app. To use Auto, the session has to meet the auto mode [availability requirements](#eliminate-prompts-with-auto-mode). For a project thread running on your computer, see [Run a thread on your own computer](https://code.claude.com/docs/en/claude-projects.md#run-a-thread-on-your-own-computer).

253> * Except for Bypass permissions, the dropdown shows the permission mode the local session is in, including one set from the terminal. It updates when the permission mode changes in the app or in the terminal.

254> * Sessions hosted by the [desktop app](https://code.claude.com/docs/en/desktop.md) or the [VS Code extension](https://code.claude.com/docs/en/vs-code.md) report permission mode changes to claude.ai as they happen, the same as sessions hosted in a terminal.

255>

256> For Remote Control, the local machine running the session must be signed in with your claude.ai account; API keys aren't supported. You can also set the starting permission mode when launching that local session:

257>

258> ```bash theme={null}

259> claude remote-control --permission-mode acceptEdits

260> ```

174261

175* `auto`: appears when [auto mode is available](#eliminate-prompts-with-auto-mode); cycling to it switches permission modes without a confirmation prompt

176* `bypassPermissions`: appears after you start with `--permission-mode bypassPermissions`, `--dangerously-skip-permissions`, `--allow-dangerously-skip-permissions`, or `permissions.defaultMode: "bypassPermissions"` in [user, `--settings`, or managed settings](https://code.claude.com/docs/en/settings-reference#permissions-defaultmode). The `--allow-` variant adds the permission mode to the cycle without activating it

177* `dontAsk`: never appears in the cycle; set it with `--permission-mode dontAsk`

178

179Enabled optional modes slot in after `plan`, with `bypassPermissions` first and `auto` last. If you have both enabled, you will cycle through `bypassPermissions` on the way to `auto`.

180

181**From a Bash permission prompt**: in the Manual and `acceptEdits` permission modes, when [auto mode](#eliminate-prompts-with-auto-mode) is available, Claude Code adds **Yes, and switch to auto mode** to a Bash command's permission prompt. Select it to approve the command and switch the session to auto mode. [PowerShell tool](https://code.claude.com/docs/en/tools-reference.md#powershell-tool) prompts don't offer the option. Requires Claude Code v2.1.247 or later.

182

183Claude Code doesn't add the option to prompts forced by one of your [`ask` rules](https://code.claude.com/docs/en/permissions#manage-permissions) or by a [hook](https://code.claude.com/docs/en/hooks.md#pretooluse-decision-control), because auto mode still shows you those prompts, so switching wouldn't remove them.

184

185**At startup**: pass the permission mode as a flag.

186

187```bash theme={null}

188claude --permission-mode plan

189```

190

191**As a default**: set `permissions.defaultMode` at the scope you want, as described in [Start in a different permission mode](#start-in-a-different-mode).

192

193The same `--permission-mode` flag works with `-p` for [non-interactive runs](https://code.claude.com/docs/en/headless.md).

194

195**VS Code**

196

197**During a session**: click the mode indicator at the bottom of the prompt box. It uses these labels for the modes on this page:

198

199| UI label | Mode |

200| :- | :- |

201| Manual | `default` |

202| Edit automatically | `acceptEdits` |

203| Plan | `plan` |

204| Auto | `auto` |

205| Bypass permissions | `bypassPermissions` |

206

207**As a default**: to pin the permission mode conversations start in, set `claudeCode.initialPermissionMode` in your VS Code user settings to `default`, `manual`, `acceptEdits`, `plan`, or `bypassPermissions`. The setting doesn't accept `auto`; to start in Auto, leave it unset and pick **Auto** from the mode indicator once, as item 2 below describes. The extension starts each new conversation in the first of these that applies:

208

2091. `claudeCode.initialPermissionMode`

2102. The mode you last picked from the mode indicator, if it was Manual, Edit automatically, or Auto. Picking Plan or Bypass permissions applies to that conversation only

2113. `permissions.defaultMode` from [managed settings](https://code.claude.com/docs/en/managed-settings.md) or `~/.claude/settings.json`

2124. The [built-in default](#which-mode-a-session-starts-in) for your plan, provider, and organization settings

213

214The extension never reads a project's `.claude/settings.json` or `.claude/settings.local.json` for the starting permission mode. When `claudeCode.claudeProcessWrapper` is set, items 3 and 4 don't apply: those conversations start in Manual unless item 1 or item 2 sets a permission mode.

215

216Before v2.1.283, item 3 applied only on Pro, Max, and Team plans in sessions that [fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching).

217

218Auto appears in the mode indicator when [auto mode is available](#eliminate-prompts-with-auto-mode).

219

220Bypass permissions requires the **Allow dangerously skip permissions** toggle in the extension settings. Without it, the permission mode doesn't appear in the indicator, and a `bypassPermissions` value from item 1 or item 3 starts the conversation in Manual instead. Auto from any item likewise starts the conversation in Manual when auto mode isn't available.

221

222See the [VS Code guide](https://code.claude.com/docs/en/vs-code.md) for extension-specific details.

223

224**JetBrains**

225

226The JetBrains plugin runs Claude Code in the IDE terminal, so switching permission modes works the same as in the CLI: press `Shift+Tab` to cycle, or pass `--permission-mode` when launching.

227

228**Desktop**

229

230**During a session**: in the Code tab, use the mode selector in the row under the prompt box. Not every mode appears in the selector:

231

232* **Auto**: appears when [auto mode is available](#eliminate-prompts-with-auto-mode)

233* **Bypass permissions**: requires the **Allow bypass permissions mode** toggle in Desktop settings on Pro and Max plans; on Team and Enterprise plans, organization policy controls it instead

234

235Cowork doesn't use these modes. It has its own permission modes, enabled separately, and shows no mode selector at all until a mode beyond its default is enabled for your account. See the [Cowork docs](https://claude.com/docs/cowork/overview).

236

237For desktop-specific details, see [Choose a permission mode](https://code.claude.com/docs/en/desktop.md#choose-a-permission-mode) in the Desktop guide.

238

239**As a default**: set `defaultMode` in [settings](https://code.claude.com/docs/en/settings.md#where-settings-live). The desktop app reads the same settings files as the CLI and applies the permission mode to new local sessions.

240

241A mode you pick in the mode selector is remembered per folder and takes precedence over `defaultMode` for that folder. Plan is the exception: picking it applies to the current session only.

242

243For where `defaultMode` goes in a settings file, see the example under [Start in a different permission mode](#start-in-a-different-mode).

244

245**Web and mobile**

246

247On [claude.ai/code](https://claude.ai/code), use the mode dropdown in the row under the prompt box. In the mobile app, tap the **+** button in the prompt box, then **Permission**. Cloud sessions and Remote Control sessions offer different permission modes:

248

249* **[Cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md)**: Accept edits, Plan, and Auto. Accept edits corresponds to `default` mode: cloud sessions pre-approve file edits regardless of mode, so the dropdown shows Accept edits instead of Manual. Cloud sessions still honor `defaultMode: "acceptEdits"` from settings. Auto mode appears only when your organization allows it and the selected model supports it. Bypass permissions isn't available.

250* **[Remote Control](https://code.claude.com/docs/en/remote-control.md) sessions** on your local machine: Manual, Accept edits, Plan, and Auto for a session you started yourself, and you can't select Bypass permissions from the app. To use Auto, the session has to meet the auto mode [availability requirements](#eliminate-prompts-with-auto-mode). For a project thread running on your computer, see [Run a thread on your own computer](https://code.claude.com/docs/en/claude-projects.md#run-a-thread-on-your-own-computer).

251 * Except for Bypass permissions, the dropdown shows the permission mode the local session is in, including one set from the terminal. It updates when the permission mode changes in the app or in the terminal.

252 * Sessions hosted by the [desktop app](https://code.claude.com/docs/en/desktop.md) or the [VS Code extension](https://code.claude.com/docs/en/vs-code.md) report permission mode changes to claude.ai as they happen, the same as sessions hosted in a terminal.

253

254For Remote Control, the local machine running the session must be signed in with your claude.ai account; API keys aren't supported. You can also set the starting permission mode when launching that local session:

255

256```bash theme={null}

257claude remote-control --permission-mode acceptEdits

258```

259

260262## Auto-approve file edits with acceptEdits mode

261263

262264`acceptEdits` mode lets Claude create and edit files in your working directory without prompting. The status bar shows `⏵⏵ accept edits on` while this mode is active.

from line 325

323325

324326Auto mode lets Claude execute without routine permission prompts. A separate classifier model reviews actions before they run, blocking anything that escalates beyond your request, targets unrecognized infrastructure, or appears driven by hostile content Claude read. Explicit [ask rules](https://code.claude.com/docs/en/permissions.md#manage-permissions) still force a prompt.

325327

326With Claude Code v2.1.283 or later, auto mode is the [built-in starting permission mode](#which-mode-a-session-starts-in) for interactive terminal and VS Code sessions on every plan and provider. On earlier versions, it's the built-in starting permission mode only on Pro, Max, and Team plans.

328With Claude Code v2.1.283 or later, auto mode is the [built-in starting permission mode](#which-mode-a-session-starts-in) for interactive terminal and VS Code sessions on every plan and provider. On earlier versions, it's the built-in starting permission mode only on Pro, Max, Ultra, and Team plans.

327329

328330The classifier also reviews each message Claude sends to another agent with [`SendMessage`](https://code.claude.com/docs/en/tools-reference), whether plain text or a structured [agent team](https://code.claude.com/docs/en/agent-teams.md) message, before Claude Code delivers it, both in auto mode and in [plan mode while the classifier reviews commands](#analyze-before-you-edit-with-plan-mode); the send review requires Claude Code v2.1.222 or later.

329331

from line 365

363365

364366In auto mode, Claude Code can ask the server to check the actions that [the decision order](#how-the-classifier-evaluates-actions) sends for review, as part of the session's model requests, in place of sending its own classifier requests. These sessions ask:

365367

366* **A direct connection to the Anthropic API**: in interactive terminal sessions and in `-p`, Agent SDK, [VS Code extension](https://code.claude.com/docs/en/vs-code.md), and [desktop app](https://code.claude.com/docs/en/desktop.md) sessions, whatever your plan or account type, as Anthropic rolls it out. In interactive terminal sessions, this requires Claude Code v2.1.271 or later on Pro, Max, and Team plans, and v2.1.278 or later on Enterprise plans and Claude API accounts. In `-p`, Agent SDK, VS Code extension, and desktop app sessions, this requires Claude Code v2.1.281 or later. From v2.1.282, a session that [doesn't fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), for example because you turned telemetry off, asks the server by default in any kind of session.

368* **A direct connection to the Anthropic API**: in interactive terminal sessions and in `-p`, Agent SDK, [VS Code extension](https://code.claude.com/docs/en/vs-code.md), and [desktop app](https://code.claude.com/docs/en/desktop.md) sessions, whatever your plan or account type, as Anthropic rolls it out. Check your session type against these minimum Claude Code versions:

369 * In interactive terminal sessions, asking the server requires Claude Code v2.1.271 or later on Pro, Max, Ultra, and Team plans. On Enterprise plans and Claude API accounts, those sessions require v2.1.278 or later.

370 * In `-p`, Agent SDK, VS Code extension, and desktop app sessions, asking the server requires Claude Code v2.1.281 or later

371 * From v2.1.282, a session that [doesn't fetch feature flags](https://code.claude.com/docs/en/env-vars.md#features-that-need-feature-flag-fetching), for example because you turned telemetry off, asks the server by default in any kind of session

367372* **A cloud provider, or an LLM gateway or proxy**: on [Claude Platform on AWS](https://code.claude.com/docs/en/claude-platform-on-aws.md), Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, and whenever you point `ANTHROPIC_BASE_URL` at an [LLM gateway or proxy](https://code.claude.com/docs/en/llm-gateway), whatever your plan. Asking by default requires Claude Code v2.1.278 or later.

368373* **A signed-in [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway) session**: requires Claude Code v2.1.280 or later

369374* **A [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md) in an Anthropic-hosted environment**: whatever your plan, when you start it from the web, the mobile app, or the desktop app with **Cloud** selected. Sessions started by a [cloud scheduled task](https://code.claude.com/docs/en/routines.md) ask the server as Anthropic rolls it out.

from line 567

562567

563568The following sections cover the order Claude Code evaluates an action in, how the classifier reviews subagent work, and what classifier calls add in cost and latency.

564569

565> **How the classifier evaluates actions**

570> [accordion] How the classifier evaluates actions

566571>

567572> Each action goes through a fixed decision order. The first matching step wins:

568573>

from line 609

604609>

605610> A separate server-side probe scans incoming tool results and flags suspicious content before Claude reads it. For more on how these layers work together, see the [auto mode announcement](https://claude.com/blog/auto-mode) and the [engineering deep dive](https://www.anthropic.com/engineering/claude-code-auto-mode).

606611

607> **How auto mode handles subagents**

612> [accordion] How auto mode handles subagents

608613>

609614> The classifier checks [subagent](https://code.claude.com/docs/en/sub-agents.md) work at three points:

610615>

from line 617

612617> 2. While the subagent runs, each of its actions goes through the same [decision order](#how-the-classifier-evaluates-actions) as in the parent session, with the same block and allow rules. Any `permissionMode` in the subagent's frontmatter is ignored.

613618> 3. When the subagent finishes, the classifier reviews its work and its final report before the parent reads the report. When the classifier flags the subagent's work or report, or a separate API safety check refuses the review, the report is still delivered, prepended with a security warning. When the classifier is unavailable for the review, the report arrives with a note to verify the subagent's work before acting on it.

614619

615> **Cost and latency**

620> [accordion] Cost and latency

616621>

617622> Claude Code's classifier requests can run on a model other than your `/model` selection. See [which model they run on](#default-classifier-model).

618623>

from line 965

960965

961966To run Bash `rm` and `rmdir` commands that target [critical paths](#critical-paths) with no prompt in `bypassPermissions` mode, start Claude Code with [`CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS=1`](https://code.claude.com/docs/en/env-vars#variables) in its environment. This requires Claude Code v2.1.311 or later. Claude Code reads the variable from the launch environment only and [ignores it in a settings file's `env` block](https://code.claude.com/docs/en/settings-reference#variables-claude-code-ignores-in-env). For example, set it in [your shell](https://code.claude.com/docs/en/env-vars.md#set-variables-in-your-shell) and start `claude` from there:

962967

963**macOS, Linux, WSL**

968> [tab] macOS, Linux, WSL

969>

970> ```bash theme={null}

971> export CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS=1

972> claude --permission-mode bypassPermissions

973> ```

964974

965```bash theme={null}

966export CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS=1

967claude --permission-mode bypassPermissions

968```

975> [tab] Windows PowerShell

976>

977> ```powershell theme={null}

978> $env:CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS = "1"

979> claude --permission-mode bypassPermissions

980> ```

969981

970**Windows PowerShell**

971

972```powershell theme={null}

973$env:CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS = "1"

974claude --permission-mode bypassPermissions

975```

976

977**Windows CMD**

978

979```batch theme={null}

980set CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS=1

981claude --permission-mode bypassPermissions

982```

982> [tab] Windows CMD

983>

984> ```batch theme={null}

985> set CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS=1

986> claude --permission-mode bypassPermissions

987> ```

983988

984989> [!WARNING]

985990>

platforms Changed · +6 / -6 lines

from line 10

1010

1111| Platform | Best for | What you get |

1212| :- | :- | :- |

13| [CLI](https://code.claude.com/docs/en/quickstart.md) | Terminal workflows, scripting, remote servers | Full feature set, [Agent SDK](https://code.claude.com/docs/en/headless.md), [computer use](https://code.claude.com/docs/en/computer-use.md) on macOS (Pro and Max), third-party providers |

14| [Desktop](https://code.claude.com/docs/en/desktop.md) | Visual review, parallel sessions, managed setup | Diff viewer, app preview, [computer use](https://code.claude.com/docs/en/desktop.md#let-claude-use-your-computer) and [Dispatch](https://code.claude.com/docs/en/desktop.md#sessions-from-dispatch) on Pro and Max |

1515| [VS Code](https://code.claude.com/docs/en/vs-code.md) | Working inside VS Code without switching to a terminal | Inline diffs, integrated terminal, file context |

1616| [JetBrains](https://code.claude.com/docs/en/jetbrains.md) | Working inside IntelliJ, PyCharm, WebStorm, or other JetBrains IDEs | Diff viewer, selection sharing, terminal session |

1717| [Web](https://code.claude.com/docs/en/claude-code-on-the-web.md) | Long-running tasks that don't need much steering, or work that should continue when you're offline | Cloud, Anthropic-managed by default; continues after you disconnect |

18| [Mobile](https://code.claude.com/docs/en/mobile.md) | Starting and monitoring tasks while away from your computer | Cloud sessions from the Claude app for iOS and Android, [Remote Control](https://code.claude.com/docs/en/remote-control.md) for local sessions, [Dispatch](https://code.claude.com/docs/en/desktop.md#sessions-from-dispatch) to Desktop on Pro and Max |

1919

2020The CLI is the most complete surface for terminal-native work: scripting and the Agent SDK are CLI-only. Third-party providers also work in [VS Code](https://code.claude.com/docs/en/vs-code.md#use-third-party-providers) and in [JetBrains](https://code.claude.com/docs/en/feature-availability.md#features-available-on-every-provider), which runs the CLI in your IDE's terminal. Enterprise [Desktop](https://code.claude.com/docs/en/desktop.md) deployments support Google Cloud's Agent Platform, and Desktop supports [gateway providers](https://code.claude.com/docs/en/llm-gateway-connect.md#desktop-app); for Amazon Bedrock or Microsoft Foundry, use the CLI or an IDE extension, or [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview), which runs the Code tab on those providers. Desktop and the IDE extensions trade some CLI-only features for visual review and tighter editor integration. The web runs in the cloud, so tasks keep going after you disconnect. Mobile is a thin client into those same cloud sessions or into a local session via Remote Control, and can send tasks to Desktop with Dispatch.

2121

from line 31

3131| [GitHub Actions](https://code.claude.com/docs/en/github-actions.md) | Runs Claude in your CI pipeline | Automated PR reviews, issue triage, scheduled maintenance |

3232| [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md) | Same as GitHub Actions for GitLab | CI-driven automation on GitLab |

3333| [Code Review](https://code.claude.com/docs/en/code-review.md) | Reviews every PR automatically | Catching bugs before human review |

34| [Slack](https://code.claude.com/docs/en/slack.md) | Responds to `@Claude` mentions in your channels, under your own account | Turning bug reports into pull requests from team chat on Pro and Max plans |

3535| [Claude Tag](https://claude.com/docs/claude-tag) | Runs `@Claude` as your organization's shared identity with admin-configured access | Shared team access on Team and Enterprise plans, instead of per-user Slack sessions |

3636

3737For integrations not listed here, [MCP servers](https://code.claude.com/docs/en/mcp.md) and [connectors](https://code.claude.com/docs/en/desktop.md#connect-external-tools) let you connect almost anything: Linear, Notion, Google Drive, or your own internal APIs.

from line 45

4545| [Dispatch](https://code.claude.com/docs/en/desktop.md#sessions-from-dispatch) | Message a task from the Claude mobile app | Your machine (Desktop) | [Pair the mobile app with Desktop](https://support.claude.com/en/articles/13947068) | Delegating work while you're away, minimal setup |

4646| [Remote Control](https://code.claude.com/docs/en/remote-control.md) | Drive a running session from [claude.ai/code](https://claude.ai/code) or the Claude mobile app | Your machine (CLI, Desktop, or VS Code) | Run [`claude remote-control` or `/remote-control`](https://code.claude.com/docs/en/remote-control#start-a-remote-control-session) | Steering in-progress work from another device |

4747| [Channels](https://code.claude.com/docs/en/channels.md) | Push events from a chat app like Telegram or Discord, or your own server | Your machine (CLI) | [Install a channel plugin](https://code.claude.com/docs/en/channels.md#quickstart) or [build your own](https://code.claude.com/docs/en/channels-reference.md) | Reacting to external events like CI failures or chat messages |

48| [Slack](https://code.claude.com/docs/en/slack.md) | Mention `@Claude` in a team channel | Anthropic cloud | [Install the Slack app](https://code.claude.com/docs/en/slack.md#setting-up-claude-code-in-slack) with [Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web.md) enabled, on Pro and Max plans | PRs and reviews from team chat |

4949| [Self-hosted environments](https://code.claude.com/docs/en/self-hosted-environments) | Start a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md) and pick your organization's environment | Your organization's infrastructure | [Deploy runners](https://code.claude.com/docs/en/self-hosted-environments-quickstart.md), on Team and Enterprise plans | Cloud sessions that must run inside your network |

5050| [Scheduled tasks](https://code.claude.com/docs/en/scheduled-tasks.md) | Set a schedule | [CLI](https://code.claude.com/docs/en/scheduled-tasks.md), [Desktop](https://code.claude.com/docs/en/desktop-scheduled-tasks.md), or [cloud](https://code.claude.com/docs/en/routines.md) | Pick a frequency | Recurring automation like daily reviews |

5151

from line 70

7070* [GitHub Actions](https://code.claude.com/docs/en/github-actions.md): run Claude in your CI pipeline

7171* [GitLab CI/CD](https://code.claude.com/docs/en/gitlab-ci-cd.md): the same for GitLab

7272* [Code Review](https://code.claude.com/docs/en/code-review.md): automatic review on every pull request

73* [Slack](https://code.claude.com/docs/en/slack.md): send tasks from team chat and get PRs back, on Pro and Max plans

73* [Slack](https://code.claude.com/docs/en/slack.md): send tasks from team chat and get PRs back, on Pro, Max, and Ultra plans

7474* [Claude Tag](https://claude.com/docs/claude-tag): run `@Claude` as your organization's shared identity on Team and Enterprise plans

7575

7676### Remote access

plugins/install Changed · +99 / -99 lines

from line 23

2323

2424Pick the tab for where you run Claude Code.

2525

26**Terminal**

26> [tab] Terminal

27>

28> Start Claude Code with `claude` in your project, then:

29>

30> **1. Open the plugin's details with the install command**

31>

32> Run `/plugin install` with the plugin's name and marketplace. In a session, this command doesn't install right away: it opens the `/plugin` panel on that plugin's details so you can review it and choose a scope first.

33>

34> ```text theme={null}

35> /plugin install commit-commands@claude-plugins-official

36> ```

37>

38> To browse instead, run `/plugin` with no plugin name: the panel opens on the **Discover** tab, which lists the plugins from your marketplaces, and you can type to search, then press **Enter** on a plugin to open its details.

39>

40> **2. Review what the plugin adds**

41>

42> The details pane shows the plugin's description. It can also show:

43>

44> * **Will install**: the commands, agents, skills, hooks, and MCP and LSP servers the plugin adds.

45> * **Last updated**: shown for a plugin in Anthropic's official marketplace.

46> * **Context cost**: for a plugin in Anthropic's official marketplace, two token estimates. **Every turn** is what the plugin adds to each message you send, and **When invoked** is what its skills and agents add once Claude loads them. The estimates appear when you open the plugin by naming its marketplace, as the step 1 command does, or from the **Marketplaces** tab. The details pane you reach from the **Discover** list doesn't show them.

47>

48> Plugins from a local or custom marketplace can show `Components will be discovered at installation` instead.

49>

50> A plugin can run hooks and MCP servers, so read the pane before you install. See [Plugin security and trust](https://code.claude.com/docs/en/plugins/security.md).

51>

52> **3. Choose a scope**

53>

54> Select one of the three install options:

55>

56> * **Install for you (user scope)**: you get the plugin in every project on this machine

57> * **Install for all collaborators on this repository (project scope)**: it's enabled for everyone who works in this repository

58> * **Install for you, in this repo only (local scope)**: you get it in this repository only

59>

60> [Choose an install scope](#choose-an-install-scope) says which settings file each one writes to and which applies when the same plugin is set at more than one.

61>

62> After you select a scope, Claude Code installs the plugin along with any dependencies it declares, then prints an install summary.

63>

64> **4. Read the install summary**

65>

66> The last sentence of the summary tells you whether the plugin is usable in this session yet:

67>

68> * **Active now**: `Plugin is now active.` No reload is needed.

69> * **Active, but a server needs setup**: `Plugin is now active.` is followed by `Its bundled MCP server needs configuration before it can start`. The plugin's [bundled MCP server](https://code.claude.com/docs/en/plugins/components.md#include-a-packaged-mcpb-server) can't start until you set its options. Select the plugin on the **Installed** tab in `/plugin` and choose **Configure** to set the server's options.

70> * **Reload needed**: `Run /reload-plugins to apply.` The panel closes and Claude Code runs that reload for you. If the reload would [invalidate the prompt cache](https://code.claude.com/docs/en/prompt-caching.md#enabling-or-disabling-a-plugin), it warns and leaves the plugin pending instead. Run `/reload-plugins --force` to activate it anyway, which costs one uncached request.

71> * **Load failed**: `The plugin couldn't be loaded`. Open the **Errors** tab in `/plugin` for the reason, then see [After install: plugin not working](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-installed-but-not-working).

72>

73> **5. Confirm the plugin works**

74>

75> Type `/` and look for the plugin's skills under its name, in the form `/<plugin>:<skill>`. For `commit-commands`, `/commit-commands:commit` appears. Two other places list the plugin too:

76>

77> * Open the **Installed** tab in `/plugin`, which lists the plugin with its scope.

78> * In your shell, run `claude plugin list`, which prints the same list with `Version`, `Scope`, and `Status` lines.

79>

80> If `/commit-commands:commit` doesn't appear, see [After install: plugin not working](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-installed-but-not-working).

81>

82> Installing from any other marketplace requires one extra step first: [add the marketplace](#add-a-marketplace). Claude Code adds Anthropic's official marketplace for you the first time you start an interactive terminal session, which is why the example skips that step. If you found a plugin on [claude.com/marketplace](https://claude.com/marketplace), its **Claude Code** button copies the install command in its [shell form](#install-from-your-shell), `claude plugin install <name>@claude-plugins-official`.

2783

28Start Claude Code with `claude` in your project, then:

84> [tab] Desktop app

85>

86> In a local or SSH session in the desktop app's **Code** tab:

87>

88> **1. Open the plugin browser**

89>

90> Click the **+** button next to the prompt box and select **Add plugins**. If the **+** menu shows **Plugins** instead of **Add plugins**, select **Plugins**, then **Browse plugins**. The plugin browser opens with the plugins from your marketplaces.

91>

92> **2. Select the plugin**

93>

94> Find `commit-commands` and select it.

95>

96> **3. Choose a scope**

97>

98> Choose a [scope](#choose-an-install-scope): your user account, this project, or local-only.

99>

100> To enable, disable, or uninstall a plugin later, see [Install plugins in the desktop app](https://code.claude.com/docs/en/desktop.md#install-plugins).

29101

30**1. Open the plugin's details with the install command**

102> [tab] VS Code

103>

104> In the Claude Code panel in VS Code:

105>

106> **1. Open Manage plugins**

107>

108> Type `/plugins` in the prompt box to open **Manage plugins**.

109>

110> **2. Install the plugin**

111>

112> On the **Plugins** tab, search for `commit-commands` and click **Install**. If the tab lists no plugins, add `anthropics/claude-plugins-official` on the **Marketplaces** tab first.

113>

114> **3. Choose a scope**

115>

116> Choose a [scope](#choose-an-install-scope): **Install for you**, **Install for this project**, or **Install locally**.

117>

118> Your changes apply to open sessions without a restart. See [Manage plugins in VS Code](https://code.claude.com/docs/en/vs-code.md#manage-plugins).

31119

32Run `/plugin install` with the plugin's name and marketplace. In a session, this command doesn't install right away: it opens the `/plugin` panel on that plugin's details so you can review it and choose a scope first.

34```text theme={null}

35/plugin install commit-commands@claude-plugins-official

36```

38To browse instead, run `/plugin` with no plugin name: the panel opens on the **Discover** tab, which lists the plugins from your marketplaces, and you can type to search, then press **Enter** on a plugin to open its details.

40**2. Review what the plugin adds**

42The details pane shows the plugin's description. It can also show:

44* **Will install**: the commands, agents, skills, hooks, and MCP and LSP servers the plugin adds.

45* **Last updated**: shown for a plugin in Anthropic's official marketplace.

46* **Context cost**: for a plugin in Anthropic's official marketplace, two token estimates. **Every turn** is what the plugin adds to each message you send, and **When invoked** is what its skills and agents add once Claude loads them. The estimates appear when you open the plugin by naming its marketplace, as the step 1 command does, or from the **Marketplaces** tab. The details pane you reach from the **Discover** list doesn't show them.

48Plugins from a local or custom marketplace can show `Components will be discovered at installation` instead.

50A plugin can run hooks and MCP servers, so read the pane before you install. See [Plugin security and trust](https://code.claude.com/docs/en/plugins/security.md).

52**3. Choose a scope**

54Select one of the three install options:

56* **Install for you (user scope)**: you get the plugin in every project on this machine

57* **Install for all collaborators on this repository (project scope)**: it's enabled for everyone who works in this repository

58* **Install for you, in this repo only (local scope)**: you get it in this repository only

60[Choose an install scope](#choose-an-install-scope) says which settings file each one writes to and which applies when the same plugin is set at more than one.

62After you select a scope, Claude Code installs the plugin along with any dependencies it declares, then prints an install summary.

64**4. Read the install summary**

66The last sentence of the summary tells you whether the plugin is usable in this session yet:

68* **Active now**: `Plugin is now active.` No reload is needed.

69* **Active, but a server needs setup**: `Plugin is now active.` is followed by `Its bundled MCP server needs configuration before it can start`. The plugin's [bundled MCP server](https://code.claude.com/docs/en/plugins/components.md#include-a-packaged-mcpb-server) can't start until you set its options. Select the plugin on the **Installed** tab in `/plugin` and choose **Configure** to set the server's options.

70* **Reload needed**: `Run /reload-plugins to apply.` The panel closes and Claude Code runs that reload for you. If the reload would [invalidate the prompt cache](https://code.claude.com/docs/en/prompt-caching.md#enabling-or-disabling-a-plugin), it warns and leaves the plugin pending instead. Run `/reload-plugins --force` to activate it anyway, which costs one uncached request.

71* **Load failed**: `The plugin couldn't be loaded`. Open the **Errors** tab in `/plugin` for the reason, then see [After install: plugin not working](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-installed-but-not-working).

73**5. Confirm the plugin works**

75Type `/` and look for the plugin's skills under its name, in the form `/<plugin>:<skill>`. For `commit-commands`, `/commit-commands:commit` appears. Two other places list the plugin too:

77* Open the **Installed** tab in `/plugin`, which lists the plugin with its scope.

78* In your shell, run `claude plugin list`, which prints the same list with `Version`, `Scope`, and `Status` lines.

80If `/commit-commands:commit` doesn't appear, see [After install: plugin not working](https://code.claude.com/docs/en/plugins/troubleshooting.md#plugin-installed-but-not-working).

82Installing from any other marketplace requires one extra step first: [add the marketplace](#add-a-marketplace). Claude Code adds Anthropic's official marketplace for you the first time you start an interactive terminal session, which is why the example skips that step. If you found a plugin on [claude.com/marketplace](https://claude.com/marketplace), its **Claude Code** button copies the install command in its [shell form](#install-from-your-shell), `claude plugin install <name>@claude-plugins-official`.

84**Desktop app**

86In a local or SSH session in the desktop app's **Code** tab:

88**1. Open the plugin browser**

90Click the **+** button next to the prompt box and select **Add plugins**. If the **+** menu shows **Plugins** instead of **Add plugins**, select **Plugins**, then **Browse plugins**. The plugin browser opens with the plugins from your marketplaces.

92**2. Select the plugin**

94Find `commit-commands` and select it.

96**3. Choose a scope**

98Choose a [scope](#choose-an-install-scope): your user account, this project, or local-only.

100To enable, disable, or uninstall a plugin later, see [Install plugins in the desktop app](https://code.claude.com/docs/en/desktop.md#install-plugins).

101

102**VS Code**

103

104In the Claude Code panel in VS Code:

105

106**1. Open Manage plugins**

107

108Type `/plugins` in the prompt box to open **Manage plugins**.

109

110**2. Install the plugin**

111

112On the **Plugins** tab, search for `commit-commands` and click **Install**. If the tab lists no plugins, add `anthropics/claude-plugins-official` on the **Marketplaces** tab first.

113

114**3. Choose a scope**

115

116Choose a [scope](#choose-an-install-scope): **Install for you**, **Install for this project**, or **Install locally**.

117

118Your changes apply to open sessions without a restart. See [Manage plugins in VS Code](https://code.claude.com/docs/en/vs-code.md#manage-plugins).

119

120**Cloud session**

121

122A [cloud session](https://code.claude.com/docs/en/cloud-environments.md), including [the browser at claude.ai/code](https://code.claude.com/docs/en/claude-code-on-the-web.md), has no plugin browser and doesn't load the plugins you installed on your own machine or the ones your repository's `.claude/settings.json` turns on. For plugins your organization distributes through managed settings, see [Manage plugins for your organization](https://code.claude.com/docs/en/plugins/org.md).

123

124See [which parts of your setup are also available in a cloud session](https://code.claude.com/docs/en/cloud-environments.md#what-carries-over-from-your-setup) for the rest of your setup.

120> [tab] Cloud session

121>

122> A [cloud session](https://code.claude.com/docs/en/cloud-environments.md), including [the browser at claude.ai/code](https://code.claude.com/docs/en/claude-code-on-the-web.md), has no plugin browser and doesn't load the plugins you installed on your own machine or the ones your repository's `.claude/settings.json` turns on. For plugins your organization distributes through managed settings, see [Manage plugins for your organization](https://code.claude.com/docs/en/plugins/org.md).

123>

124> See [which parts of your setup are also available in a cloud session](https://code.claude.com/docs/en/cloud-environments.md#what-carries-over-from-your-setup) for the rest of your setup.

125125

126126### Choose an install scope

127127

plugins/mods/create Changed · +11 / -11 lines

from line 88

8888

8989Create the two directories that hold the files:

9090

91**Bash or Zsh**

91> [tab] Bash or Zsh

92>

93> ```bash theme={null}

94> mkdir -p first-mod/.claude-plugin first-mod/hooks

95> ```

9296

93```bash theme={null}

94mkdir -p first-mod/.claude-plugin first-mod/hooks

95```

97**PowerShell**

99```powershell theme={null}

100New-Item -ItemType Directory -Force first-mod\.claude-plugin, first-mod\hooks

101```

97> [tab] PowerShell

98>

99> ```powershell theme={null}

100> New-Item -ItemType Directory -Force first-mod\.claude-plugin, first-mod\hooks

101> ```

102102

103103**2. Write the manifest**

104104

plugins/mods/interface Changed · +132 / -132 lines

from line 177

177177

178178The pane and the band are empty until a mod fills them. Select a tab to see what each one is and how to draw in it:

179179

180**Pane**

180> [tab] Pane

181>

182> A pane is a sidebar beside the transcript in a wide fullscreen terminal, or a framed region above the prompt otherwise. With several panes open, each gets a tab that shows its title.

183>

184> A pane appears when your mod calls `$.ui.open` with an `id` you choose, as in `$.ui.open({ id: 'hello-tabs' })`. [Open a pane at the right time](#open-a-pane-at-the-right-time) covers the other fields and when a pane waits for a wider terminal.

185>

186> To draw in your pane, filter on `{ component: 'Pane' }` and check that `e.requestId` is your `id`.

181187

182A pane is a sidebar beside the transcript in a wide fullscreen terminal, or a framed region above the prompt otherwise. With several panes open, each gets a tab that shows its title.

188> [tab] Band above the prompt

189>

190> The band is a strip directly above the prompt input. It's always there, and every mod shares it.

191>

192> Your hook returns a tree to show something in the band, or `next(e)` to show nothing. A tree replaces what the mods [after yours](https://code.claude.com/docs/en/plugins/mods/events.md#the-order-mods-run-in) draw there. To keep theirs, put the result of `await next(e)` among the children of a [`Box`](#build-a-tree-from-elements) in your tree.

193>

194> To draw in the band, filter on `{ component: 'AbovePrompt' }`.

183195

184A pane appears when your mod calls `$.ui.open` with an `id` you choose, as in `$.ui.open({ id: 'hello-tabs' })`. [Open a pane at the right time](#open-a-pane-at-the-right-time) covers the other fields and when a pane waits for a wider terminal.

185

186To draw in your pane, filter on `{ component: 'Pane' }` and check that `e.requestId` is your `id`.

187

188**Band above the prompt**

189

190The band is a strip directly above the prompt input. It's always there, and every mod shares it.

191

192Your hook returns a tree to show something in the band, or `next(e)` to show nothing. A tree replaces what the mods [after yours](https://code.claude.com/docs/en/plugins/mods/events.md#the-order-mods-run-in) draw there. To keep theirs, put the result of `await next(e)` among the children of a [`Box`](#build-a-tree-from-elements) in your tree.

193

194To draw in the band, filter on `{ component: 'AbovePrompt' }`.

195

196196### Change what Claude Code already draws

197197

198198Claude Code draws most of its interface itself: messages, tool call rows, the spinner, and more. Each of those parts is a render site too, so a mod can restyle or replace it. To change one, filter your `ui.render` hook on its name from this table:

from line 210

210210

211211At a site Claude Code already draws, your hook can change a detail, replace the drawing, or leave it alone. Select a tab to see each one applied to the spinner. The examples read a `calls` variable that another hook counts, as in the [tutorial mod](https://code.claude.com/docs/en/plugins/mods/create.md#write-a-mod-yourself).

212212

213**Change a detail**

213> [tab] Change a detail

214>

215> To keep Claude Code's drawing and change one part of it, pass `next` a copy of the event with changed `props`. This hook changes the text after the spinner's word:

216>

217> ```javascript theme={null}

218> on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

219> // Keep Claude Code's spinner, and change the text after its word

220> return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

221> })

222> ```

223>

224> The spinner keeps its animation and its word, and your text follows the word:

225>

226> ```text theme={null}

227> Thinking · tool calls: 2…

228> ```

214229

215To keep Claude Code's drawing and change one part of it, pass `next` a copy of the event with changed `props`. This hook changes the text after the spinner's word:

230> [tab] Replace the drawing

231>

232> To draw something of your own in the site's place, return a tree and don't call `next`. This hook draws one line of text where the spinner would be:

233>

234> ```javascript theme={null}

235> on('ui.render', { component: 'Spinner' }, async ($, e) => {

236> const { Text } = $.ui.resolve(e)

237> // No call to next, so this line is drawn in the spinner's place

238> return Text({ children: ['Claude has made ' + calls + ' tool calls'] })

239> })

240> ```

241>

242> While Claude works, your line shows and Claude Code's spinner doesn't:

243>

244> ```text theme={null}

245> Claude has made 2 tool calls

246> ```

216247

217```javascript theme={null}

218on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

219 // Keep Claude Code's spinner, and change the text after its word

220 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

221})

222```

248> [tab] Leave it alone

249>

250> To leave the site as Claude Code draws it, return `next(e)`. A hook often does that for some events and not others. This hook leaves the spinner alone until there's a call to count:

251>

252> ```javascript theme={null}

253> on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

254> // Nothing to show yet, so pass the event on unchanged

255> if (calls === 0) return next(e)

256> return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

257> })

258> ```

259>

260> Before the first tool call, the spinner looks the way it does without the mod:

261>

262> ```text theme={null}

263> Thinking…

264> ```

223265

224The spinner keeps its animation and its word, and your text follows the word:

225

226```text theme={null}

227Thinking · tool calls: 2…

228```

229

230**Replace the drawing**

231

232To draw something of your own in the site's place, return a tree and don't call `next`. This hook draws one line of text where the spinner would be:

233

234```javascript theme={null}

235on('ui.render', { component: 'Spinner' }, async ($, e) => {

236 const { Text } = $.ui.resolve(e)

237 // No call to next, so this line is drawn in the spinner's place

238 return Text({ children: ['Claude has made ' + calls + ' tool calls'] })

239})

240```

241

242While Claude works, your line shows and Claude Code's spinner doesn't:

243

244```text theme={null}

245Claude has made 2 tool calls

246```

247

248**Leave it alone**

249

250To leave the site as Claude Code draws it, return `next(e)`. A hook often does that for some events and not others. This hook leaves the spinner alone until there's a call to count:

251

252```javascript theme={null}

253on('ui.render', { component: 'Spinner' }, async ($, e, next) => {

254 // Nothing to show yet, so pass the event on unchanged

255 if (calls === 0) return next(e)

256 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

257})

258```

259

260Before the first tool call, the spinner looks the way it does without the mod:

261

262```text theme={null}

263Thinking…

264```

265

266266At these sites, `next(e)` returns a reference to Claude Code's drawing, `{ type: 'engine', ref }`, unless a mod that runs after yours returned a tree of its own. To change what's in that drawing, pass `next` a copy of the event with different props, as the **Change a detail** tab does. You can return the reference as it is, or place it in a `Box` beside elements of your own:

267267

268268```javascript theme={null}

from line 353

353353

354354Select a tab to see each of the most common elements and how the terminal draws it:

355355

356**Text**

356> [tab] Text

357>

358> `Text` draws a string, with optional styling such as `bold` and `color`:

359>

360> ```javascript theme={null}

361> Text({ children: ['This is the first tab.'] })

362> ```

363>

364> ```text theme={null}

365> This is the first tab.

366> ```

357367

358`Text` draws a string, with optional styling such as `bold` and `color`:

368> [tab] Box

369>

370> `Box` arranges what's inside it, in a row or a column. This one puts a button and a line of text side by side, two columns apart:

371>

372> ```javascript theme={null}

373> Box({

374> flexDirection: 'row',

375> columnGap: 2,

376> children: [

377> Button({ key: 'more', label: 'Add one', onPress: addOne }),

378> Text({ children: ['Count: 0'] }),

379> ],

380> })

381> ```

382>

383> ```text theme={null}

384> [ Add one ] Count: 0

385> ```

359386

360```javascript theme={null}

361Text({ children: ['This is the first tab.'] })

362```

387> [tab] Button

388>

389> `Button` is a control the user can press. It runs your `onPress` callback. With `plain: true` it has no brackets and shows its hotkey:

390>

391> ```javascript theme={null}

392> Button({ key: 'more', label: 'Add one', onPress: addOne })

393> Button({ key: 'tab-one', label: 'One', hotkey: '1', plain: true, onPress: showTabOne })

394> ```

395>

396> ```text theme={null}

397> [ Add one ]

398> 1: One

399> ```

363400

364```text theme={null}

365This is the first tab.

366```

367

368**Box**

369

370`Box` arranges what's inside it, in a row or a column. This one puts a button and a line of text side by side, two columns apart:

371

372```javascript theme={null}

373Box({

374 flexDirection: 'row',

375 columnGap: 2,

376 children: [

377 Button({ key: 'more', label: 'Add one', onPress: addOne }),

378 Text({ children: ['Count: 0'] }),

379 ],

380})

381```

382

383```text theme={null}

384[ Add one ] Count: 0

385```

386

387**Button**

388

389`Button` is a control the user can press. It runs your `onPress` callback. With `plain: true` it has no brackets and shows its hotkey:

390

391```javascript theme={null}

392Button({ key: 'more', label: 'Add one', onPress: addOne })

393Button({ key: 'tab-one', label: 'One', hotkey: '1', plain: true, onPress: showTabOne })

394```

395

396```text theme={null}

397[ Add one ]

3981: One

399```

400

401**Input**

402

403`Input` is a text field. It runs your `onSubmit` callback with the text when the user presses Enter:

404

405```javascript theme={null}

406Input({

407 key: 'new-note',

408 label: 'Note',

409 placeholder: 'Type a note and press Enter',

410 value: '',

411 submitLabel: 'add',

412 onSubmit: addNote,

413})

414```

415

416```text theme={null}

417Note: Type a note and press Enter

418```

419

420Set `rows` to 2 or more for [a field that holds several lines](https://code.claude.com/docs/en/plugins/mods/gallery.md#input).

401> [tab] Input

402>

403> `Input` is a text field. It runs your `onSubmit` callback with the text when the user presses Enter:

404>

405> ```javascript theme={null}

406> Input({

407> key: 'new-note',

408> label: 'Note',

409> placeholder: 'Type a note and press Enter',

410> value: '',

411> submitLabel: 'add',

412> onSubmit: addNote,

413> })

414> ```

415>

416> ```text theme={null}

417> Note: Type a note and press Enter

418> ```

419>

420> Set `rows` to 2 or more for [a field that holds several lines](https://code.claude.com/docs/en/plugins/mods/gallery.md#input).

421421

422422The [interface gallery](https://code.claude.com/docs/en/plugins/mods/gallery.md) has samples and screenshots of most elements. This table lists every element:

423423

plugins/troubleshooting Changed · +22 / -22 lines

from line 298

298298

299299Cloning a marketplace, and re-cloning one to update it, gets 120 seconds by default. For a large repository or a slow connection, raise the limit. The value is in milliseconds:

300300

301**Bash or Zsh**

301> [tab] Bash or Zsh

302>

303> ```bash theme={null}

304> export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000

305> ```

302306

303```bash theme={null}

304export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000

305```

307> [tab] PowerShell

308>

309> ```powershell theme={null}

310> $env:CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS = "300000"

311> ```

306312

307**PowerShell**

308

309```powershell theme={null}

310$env:CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS = "300000"

311```

312

313313Then retry in the same shell.

314314

315315If the repository is a monorepo, limit the checkout to the directories you name with `claude plugin marketplace add <source> --sparse <paths>`.

from line 324

324324

325325Set this variable to skip the re-clone attempt and keep using the existing checkout when the check can't reach the host:

326326

327**Bash or Zsh**

327> [tab] Bash or Zsh

328>

329> ```bash theme={null}

330> export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

331> ```

328332

329```bash theme={null}

330export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

331```

332

333**PowerShell**

334

335```powershell theme={null}

336$env:CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE = "1"

337```

333> [tab] PowerShell

334>

335> ```powershell theme={null}

336> $env:CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE = "1"

337> ```

338338

339339With the variable set, Claude Code skips the re-clone only for a checkout that already contains `.claude-plugin/marketplace.json`. A marketplace that was never cloned or whose clone stopped partway still gets the clone attempt, so add it once while online.

340340

quickstart Changed · +61 / -61 lines

from line 10

1010

1111* A terminal or command prompt open

1212* A code project to work with

13* A [Claude subscription](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq) (Pro, Max, Team, or Enterprise), [Claude Console](https://platform.claude.com/) account, or access through a [supported cloud provider](https://code.claude.com/docs/en/third-party-integrations.md)

13* A [Claude subscription](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq) (Pro, Max, Ultra, Team, or Enterprise), [Claude Console](https://platform.claude.com/) account, or access through a [supported cloud provider](https://code.claude.com/docs/en/third-party-integrations.md)

1414

1515> [!NOTE]

1616>

from line 23

2323

2424To install Claude Code, open a terminal and run the command for your system. If you haven't used a terminal before, the [terminal guide](https://code.claude.com/docs/en/terminal-guide) shows how to open one and paste the command.

2525

26**Native Install (Recommended)**

28**macOS, Linux, WSL:**

30```bash theme={null}

31curl -fsSL https://claude.ai/install.sh | bash

32```

34On Windows, your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.

36**Windows PowerShell:**

38```powershell theme={null}

39irm https://claude.ai/install.ps1 | iex

40```

42**Windows CMD:**

44```batch theme={null}

45curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

46```

48The install command shows no progress while it downloads Claude Code. When the installer finishes, open a new terminal window and run `claude --version`. A working installation prints a version number. If your shell says `claude` isn't found or isn't recognized, the install directory isn't on your PATH yet: see [Fix your PATH](https://code.claude.com/docs/en/troubleshoot-install.md#command-not-found-claude-after-installation).

50If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell.

52If the install command fails with `syntax error near unexpected token '<'`, a `403`, or any other error, see [Troubleshoot installation](https://code.claude.com/docs/en/troubleshoot-install.md#find-your-error) to match the error to a fix and for alternative install methods.

54[Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.

56> [!NOTE]

26> [tab] Native Install (Recommended)

5727>

58> Native installations automatically update in the background to keep you on the latest version.

28> **macOS, Linux, WSL:**

29>

30> ```bash theme={null}

31> curl -fsSL https://claude.ai/install.sh | bash

32> ```

33>

34> On Windows, your prompt shows `PS C:\` when you're in PowerShell and `C:\` without the `PS` when you're in CMD.

35>

36> **Windows PowerShell:**

37>

38> ```powershell theme={null}

39> irm https://claude.ai/install.ps1 | iex

40> ```

41>

42> **Windows CMD:**

43>

44> ```batch theme={null}

45> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

46> ```

47>

48> The install command shows no progress while it downloads Claude Code. When the installer finishes, open a new terminal window and run `claude --version`. A working installation prints a version number. If your shell says `claude` isn't found or isn't recognized, the install directory isn't on your PATH yet: see [Fix your PATH](https://code.claude.com/docs/en/troubleshoot-install.md#command-not-found-claude-after-installation).

49>

50> If you see `The token '&&' is not a valid statement separator`, you're in PowerShell, not CMD. If you see `'irm' is not recognized as an internal or external command`, you're in CMD, not PowerShell.

51>

52> If the install command fails with `syntax error near unexpected token '<'`, a `403`, or any other error, see [Troubleshoot installation](https://code.claude.com/docs/en/troubleshoot-install.md#find-your-error) to match the error to a fix and for alternative install methods.

53>

54> [Git for Windows](https://git-scm.com/downloads/win) is recommended on native Windows so Claude Code can use the Bash tool. If Git for Windows is not installed, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need Git for Windows.

55>

56> > [!NOTE]

57> >

58> > Native installations automatically update in the background to keep you on the latest version.

5959

60**Homebrew**

62```bash theme={null}

63brew install --cask claude-code

64```

66Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.

68> [!NOTE]

60> [tab] Homebrew

6961>

70> Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.

62> ```bash theme={null}

63> brew install --cask claude-code

64> ```

65>

66> Homebrew offers two casks. `claude-code` tracks the stable release channel, which is typically about a week behind and skips releases with major regressions. `claude-code@latest` tracks the latest channel and receives new versions as soon as they ship.

67>

68> > [!NOTE]

69> >

70> > Homebrew installations do not auto-update. Run `brew upgrade claude-code` or `brew upgrade claude-code@latest`, depending on which cask you installed, to get the latest features and security fixes.

7171

72**WinGet**

74```powershell theme={null}

75winget install Anthropic.ClaudeCode

76```

78> [!NOTE]

72> [tab] WinGet

7973>

80> WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.

74> ```powershell theme={null}

75> winget install Anthropic.ClaudeCode

76> ```

77>

78> > [!NOTE]

79> >

80> > WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.

8181

8282You can also install with [apt, dnf, or apk](https://code.claude.com/docs/en/setup.md#install-with-linux-package-managers) on Debian, Fedora, RHEL, and Alpine.

8383

from line 104

104104

105105You can log in using any of these account types:

106106

107* [Claude Pro, Max, Team, or Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login) (recommended)

107* [Claude Pro, Max, Ultra, Team, or Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login) (recommended)

108108* [Claude Console](https://platform.claude.com/) (API access with pre-paid credits). On first login, a "Claude Code" workspace is automatically created in the Console for centralized cost tracking.

109109* [Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry](https://code.claude.com/docs/en/third-party-integrations.md) (enterprise cloud providers)

110110* A self-hosted [Claude apps gateway](https://code.claude.com/docs/en/claude-apps-gateway), if your organization runs one: your admin pre-configures the gateway URL, and `/login` opens directly on the **Cloud gateway** screen for you to sign in with corporate SSO

from line 263

263263

264264For more, see [best practices](https://code.claude.com/docs/en/best-practices.md) and [common workflows](https://code.claude.com/docs/en/common-workflows.md).

265265

266> **Be specific with your requests**

266> [accordion] Be specific with your requests

267267>

268268> Instead of: "fix the bug"

269269>

270270> Try: "fix the login bug where users see a blank screen after entering wrong credentials"

271271

272> **Use step-by-step instructions**

272> [accordion] Use step-by-step instructions

273273>

274274> Break complex tasks into steps:

275275>

from line 279

279279> 3. build a webpage that allows users to see and edit their information

280280> ```

281281

282> **Let Claude explore first**

282> [accordion] Let Claude explore first

283283>

284284> Before making changes, let Claude understand your code:

285285>

from line 291

291291> build a dashboard showing products that are most frequently returned by our UK customers

292292> ```

293293

294> **Save time with shortcuts**

294> [accordion] Save time with shortcuts

295295>

296296> * Type `/` to see the commands and skills available to you

297297> * Use Tab for command completion