Documentation 2025-12-15 21:01 UTC to 2025-12-16 21:01 UTC

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

111```111```

112 112 

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

114 

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

116 114 

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

167 167 

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

169 169 

170### Enterprise managed policy settings170### Enterprise managed settings

171 171 

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

173 173 

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

175 

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

177 175 

178### Settings precedence176### Settings precedence

179 177 

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

181 179 

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

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

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

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

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

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

187 186 

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

189 188 

10 10 

11**Install Claude Code:**11**Install Claude Code:**

12 12 

13To install Claude Code, use one of the following methods:

14 

13<Tabs>15<Tabs>

14 <Tab title="macOS/Linux">16 <Tab title="Native Install (Recommended)">

17 **macOS, Linux, WSL:**

18 

15 ```bash theme={null}19 ```bash theme={null}

16 curl -fsSL https://claude.ai/install.sh | bash20 curl -fsSL https://claude.ai/install.sh | bash

17 ```21 ```

18 </Tab>

19 22 

20 <Tab title="Homebrew">23 **Windows PowerShell:**

21 ```bash theme={null}

22 brew install --cask claude-code

23 ```

24 </Tab>

25 24 

26 <Tab title="Windows">

27 ```powershell theme={null}25 ```powershell theme={null}

28 irm https://claude.ai/install.ps1 | iex26 irm https://claude.ai/install.ps1 | iex

29 ```27 ```

28 

29 **Windows CMD:**

30 

31 ```batch theme={null}

32 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

33 ```

34 </Tab>

35 

36 <Tab title="Homebrew">

37 ```sh theme={null}

38 brew install --cask claude-code

39 ```

30 </Tab>40 </Tab>

31 41 

32 <Tab title="NPM">42 <Tab title="NPM">

33 ```bash theme={null}43 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):

44 

45 ```sh theme={null}

34 npm install -g @anthropic-ai/claude-code46 npm install -g @anthropic-ai/claude-code

35 ```47 ```

36 

37 Requires [Node.js 18+](https://nodejs.org/en/download/)

38 </Tab>48 </Tab>

39</Tabs>49</Tabs>

40 50 

103 103 

104When team members trust the repository folder, Claude Code automatically installs these marketplaces and any plugins specified in the `enabledPlugins` field.104When team members trust the repository folder, Claude Code automatically installs these marketplaces and any plugins specified in the `enabledPlugins` field.

105 105 

106## Enterprise marketplace restrictions

107 

108For organizations requiring strict control over plugin sources, enterprise administrators can restrict which plugin marketplaces users are allowed to add using the `strictKnownMarketplaces` setting in managed settings.

109 

110**Managed settings file locations**:

111 

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

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

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

115 

116**Restriction behavior**:

117 

118When `strictKnownMarketplaces` is configured in managed settings:

119 

120* **Undefined** (default): No restrictions - users can add any marketplace

121* **Empty array `[]`**: Complete lockdown - users cannot add any new marketplaces

122* **List of sources**: Users can only add marketplaces that match the allowlist exactly

123 

124**Basic examples**:

125 

126Disable all marketplace additions:

127 

128```json theme={null}

129{

130 "strictKnownMarketplaces": []

131}

132```

133 

134Allow specific marketplaces only:

135 

136```json theme={null}

137{

138 "strictKnownMarketplaces": [

139 {

140 "source": "github",

141 "repo": "company/approved-plugins"

142 },

143 {

144 "source": "github",

145 "repo": "company/security-tools",

146 "ref": "v2.0"

147 },

148 {

149 "source": "url",

150 "url": "https://internal.company.com/plugins/marketplace.json"

151 }

152 ]

153}

154```

155 

156**Key characteristics**:

157 

158* Enforced BEFORE network/filesystem operations

159* Uses exact matching (including optional `ref` and `path` fields for git sources)

160* Cannot be overridden by user or project settings

161* Only affects adding NEW marketplaces (previously installed marketplaces still work)

162 

163See [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces) for complete configuration details, including all six supported source types, exact matching rules, and comparison with `extraKnownMarketplaces`.

164 

106***165***

107 166 

108## Create your own marketplace167## Create your own marketplace

495* [Plugins reference](/en/plugins-reference) - Complete technical specifications and schemas554* [Plugins reference](/en/plugins-reference) - Complete technical specifications and schemas

496* [Plugin development](/en/plugins#develop-more-complex-plugins) - Creating your own plugins555* [Plugin development](/en/plugins#develop-more-complex-plugins) - Creating your own plugins

497* [Settings](/en/settings#plugin-configuration) - Plugin configuration options556* [Settings](/en/settings#plugin-configuration) - Plugin configuration options

557* [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces) - Complete configuration reference for enterprise marketplace restrictions

498 558 

499 559 

500---560---

18 18 

19<Tabs>19<Tabs>

20 <Tab title="Native Install (Recommended)">20 <Tab title="Native Install (Recommended)">

21 **Homebrew (macOS, Linux):**

22 

23 ```sh theme={null}

24 brew install --cask claude-code

25 ```

26 

27 **macOS, Linux, WSL:**21 **macOS, Linux, WSL:**

28 22 

29 ```bash theme={null}23 ```bash theme={null}

43 ```37 ```

44 </Tab>38 </Tab>

45 39 

40 <Tab title="Homebrew">

41 ```sh theme={null}

42 brew install --cask claude-code

43 ```

44 </Tab>

45 

46 <Tab title="NPM">46 <Tab title="NPM">

47 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):47 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):

48 48 

113 113 

114### Team security114### Team security

115 115 

116* Use [enterprise managed policies](/en/iam#enterprise-managed-policy-settings) to enforce organizational standards116* Use [enterprise managed settings](/en/iam#enterprise-managed-settings) to enforce organizational standards

117* Share approved permission configurations through version control117* Share approved permission configurations through version control

118* Train team members on security best practices118* Train team members on security best practices

119* Monitor Claude Code usage through [OpenTelemetry metrics](/en/monitoring-usage)119* Monitor Claude Code usage through [OpenTelemetry metrics](/en/monitoring-usage)

14* **Project settings** are saved in your project directory:14* **Project settings** are saved in your project directory:

15 * `.claude/settings.json` for settings that are checked into source control and shared with your team15 * `.claude/settings.json` for settings that are checked into source control and shared with your team

16 * `.claude/settings.local.json` for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore `.claude/settings.local.json` when it is created.16 * `.claude/settings.local.json` for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore `.claude/settings.local.json` when it is created.

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

18 managed policy settings**. These take precedence over user and project18 

19 settings. System administrators can deploy policies to:19 For organizations that prefer file-based policy distribution, Claude Code also supports `managed-settings.json` and `managed-mcp.json` files that can be deployed to system directories:

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

21 * Linux and WSL: `/etc/claude-code/managed-settings.json`21 * macOS: `/Library/Application Support/ClaudeCode/`

22 * Windows: `C:\Program Files\ClaudeCode\managed-settings.json`22 * Linux and WSL: `/etc/claude-code/`

23 * `C:\ProgramData\ClaudeCode\managed-settings.json` will be deprecated in a future version.23 * Windows: `C:\Program Files\ClaudeCode\`

24* Enterprise deployments can also configure **managed MCP servers** that override24 

25 user-configured servers. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration):25 See [Enterprise managed settings](/en/iam#enterprise-managed-settings) and [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) for details.

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

27 * Linux and WSL: `/etc/claude-code/managed-mcp.json`27 <Note>

28 * Windows: `C:\Program Files\ClaudeCode\managed-mcp.json`28 Enterprise deployments can also restrict **plugin marketplace additions** using

29 * `C:\ProgramData\ClaudeCode\managed-mcp.json` will be deprecated in a future version.29 `strictKnownMarketplaces`. For more information, see [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions).

30 </Note>

30* **Other configuration** is stored in `~/.claude.json`. This file contains your preferences (theme, notification settings, editor mode), OAuth session, [MCP server](/en/mcp) configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in `.mcp.json`.31* **Other configuration** is stored in `~/.claude.json`. This file contains your preferences (theme, notification settings, editor mode), OAuth session, [MCP server](/en/mcp) configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in `.mcp.json`.

31 32 

32```JSON Example settings.json theme={null}33```JSON Example settings.json theme={null}

61`settings.json` supports a number of options:62`settings.json` supports a number of options:

62 63 

63| Key | Description | Example |64| Key | Description | Example |

64| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |65| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- |

65| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests | `/bin/generate_temp_api_key.sh` |66| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests | `/bin/generate_temp_api_key.sh` |

66| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup. Setting to `0` immediately deletes all sessions. (default: 30 days) | `20` |67| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup. Setting to `0` immediately deletes all sessions. (default: 30 days) | `20` |

67| `companyAnnouncements` | Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |68| `companyAnnouncements` | Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |

81| `disabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to reject | `["filesystem"]` |82| `disabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to reject | `["filesystem"]` |

82| `allowedMcpServers` | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "github" }]` |83| `allowedMcpServers` | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "github" }]` |

83| `deniedMcpServers` | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including enterprise servers. Denylist takes precedence over allowlist. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "filesystem" }]` |84| `deniedMcpServers` | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including enterprise servers. Denylist takes precedence over allowlist. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "filesystem" }]` |

85| `strictKnownMarketplaces` | When set in managed-settings.json, allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions) | `[{ "source": "github", "repo": "company/plugins" }]` |

84| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |86| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

85| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |87| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

86| `alwaysThinkingEnabled` | Enable [extended thinking](/en/common-workflows#use-extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly | `true` |88| `alwaysThinkingEnabled` | Enable [extended thinking](/en/common-workflows#use-extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly | `true` |

94| `deny` | Array of [permission rules](/en/iam#configuring-permissions) to deny tool use. Use this to also exclude sensitive files from Claude Code access. **Note:** Bash patterns are prefix matches and can be bypassed (see [Bash permission limitations](/en/iam#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |96| `deny` | Array of [permission rules](/en/iam#configuring-permissions) to deny tool use. Use this to also exclude sensitive files from Claude Code access. **Note:** Bash patterns are prefix matches and can be bypassed (see [Bash permission limitations](/en/iam#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |

95| `additionalDirectories` | Additional [working directories](/en/iam#working-directories) that Claude has access to | `[ "../docs/" ]` |97| `additionalDirectories` | Additional [working directories](/en/iam#working-directories) that Claude has access to | `[ "../docs/" ]` |

96| `defaultMode` | Default [permission mode](/en/iam#permission-modes) when opening Claude Code | `"acceptEdits"` |98| `defaultMode` | Default [permission mode](/en/iam#permission-modes) when opening Claude Code | `"acceptEdits"` |

97| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed policy settings](/en/iam#enterprise-managed-policy-settings) | `"disable"` |99| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed settings](/en/iam#enterprise-managed-settings) | `"disable"` |

98 100 

99### Sandbox settings101### Sandbox settings

100 102 

190 192 

191Settings apply in order of precedence. From highest to lowest:193Settings apply in order of precedence. From highest to lowest:

192 194 

1931. **Enterprise managed policies** (`managed-settings.json`)1951. **Managed settings** (Enterprise)

194 * Deployed by IT/DevOps196 * Remote settings configured via the [Claude.ai admin console](https://claude.ai/admin-settings/claude-code)

195 * Can't be overridden197 * Fetched automatically when users authenticate

198 * Cannot be overridden

199 

2002. **File-based managed settings** (`managed-settings.json`)

201 * Policies deployed by IT/DevOps to system directories

202 * Cannot be overridden by user or project settings

203 * Ignored when remote managed settings are configured

196 204 

1972. **Command line arguments**2053. **Command line arguments**

198 * Temporary overrides for a specific session206 * Temporary overrides for a specific session

199 207 

2003. **Local project settings** (`.claude/settings.local.json`)2084. **Local project settings** (`.claude/settings.local.json`)

201 * Personal project-specific settings209 * Personal project-specific settings

202 210 

2034. **Shared project settings** (`.claude/settings.json`)2115. **Shared project settings** (`.claude/settings.json`)

204 * Team-shared project settings in source control212 * Team-shared project settings in source control

205 213 

2065. **User settings** (`~/.claude/settings.json`)2146. **User settings** (`~/.claude/settings.json`)

207 * Personal global settings215 * Personal global settings

208 216 

209This hierarchy ensures that enterprise security policies are always enforced while still allowing teams and individuals to customize their experience.217This hierarchy ensures that enterprise security policies are always enforced while still allowing teams and individuals to customize their experience.

336* `git`: Any git URL (uses `url`)344* `git`: Any git URL (uses `url`)

337* `directory`: Local filesystem path (uses `path`, for development only)345* `directory`: Local filesystem path (uses `path`, for development only)

338 346 

347#### `strictKnownMarketplaces`

348 

349**Enterprise-only setting**: Controls which plugin marketplaces users are allowed to add. This setting can only be configured in `managed-settings.json` and provides enterprise administrators with strict control over marketplace sources.

350 

351**Managed settings file locations**:

352 

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

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

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

356 

357**Key characteristics**:

358 

359* Only available in enterprise managed settings (`managed-settings.json`)

360* Cannot be overridden by user or project settings (highest precedence)

361* Enforced BEFORE network/filesystem operations (blocked sources never execute)

362* Uses exact matching for source specifications (including `ref`, `path` for git sources)

363 

364**Allowlist behavior**:

365 

366* `undefined` (default): No restrictions - users can add any marketplace

367* Empty array `[]`: Complete lockdown - users cannot add any new marketplaces

368* List of sources: Users can only add marketplaces that match exactly

369 

370**All supported source types**:

371 

372The allowlist supports six marketplace source types. Each source must match exactly for a user's marketplace addition to be allowed.

373 

3741. **GitHub repositories**:

375 

376```json theme={null}

377{ "source": "github", "repo": "company/approved-plugins" }

378{ "source": "github", "repo": "company/security-tools", "ref": "v2.0" }

379{ "source": "github", "repo": "team/plugins", "ref": "main", "path": "marketplace" }

380```

381 

382Fields: `repo` (required), `ref` (optional: branch/tag/SHA), `path` (optional: subdirectory)

383 

3842. **Git repositories**:

385 

386```json theme={null}

387{ "source": "git", "url": "https://gitlab.company.com/tools/plugins.git" }

388{ "source": "git", "url": "https://bitbucket.org/company/plugins.git", "ref": "production" }

389{ "source": "git", "url": "ssh://git@internal.company.com/plugins.git", "ref": "v3.1", "path": "approved" }

390```

391 

392Fields: `url` (required), `ref` (optional: branch/tag/SHA), `path` (optional: subdirectory)

393 

3943. **URL-based marketplaces**:

395 

396```json theme={null}

397{ "source": "url", "url": "https://internal.company.com/plugins/marketplace.json" }

398{ "source": "url", "url": "https://cdn.company.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

399```

400 

401Fields: `url` (required), `headers` (optional: HTTP headers for authenticated access)

402 

4034. **NPM packages**:

404 

405```json theme={null}

406{ "source": "npm", "package": "@company/claude-plugins" }

407{ "source": "npm", "package": "@company-internal/approved-marketplace" }

408```

409 

410Fields: `package` (required, supports scoped packages)

411 

4125. **File paths**:

413 

414```json theme={null}

415{ "source": "file", "path": "/usr/local/share/claude/company-marketplace.json" }

416{ "source": "file", "path": "/opt/company/plugins/marketplace.json" }

417```

418 

419Fields: `path` (required: absolute path to marketplace.json file)

420 

4216. **Directory paths**:

422 

423```json theme={null}

424{ "source": "directory", "path": "/usr/local/share/claude/company-plugins" }

425{ "source": "directory", "path": "/opt/company/approved-marketplaces" }

426```

427 

428Fields: `path` (required: absolute path to directory containing `.claude-plugin/marketplace.json`)

429 

430**Configuration examples**:

431 

432Example - Allow specific marketplaces only:

433 

434```json theme={null}

435{

436 "strictKnownMarketplaces": [

437 {

438 "source": "github",

439 "repo": "company/approved-plugins"

440 },

441 {

442 "source": "github",

443 "repo": "company/security-tools",

444 "ref": "v2.0"

445 },

446 {

447 "source": "url",

448 "url": "https://internal.company.com/plugins/marketplace.json"

449 },

450 {

451 "source": "npm",

452 "package": "@company/compliance-plugins"

453 }

454 ]

455}

456```

457 

458Example - Disable all marketplace additions:

459 

460```json theme={null}

461{

462 "strictKnownMarketplaces": []

463}

464```

465 

466**Exact matching requirements**:

467 

468Marketplace sources must match **exactly** for a user's addition to be allowed. For git-based sources (`github` and `git`), this includes all optional fields:

469 

470* The `repo` or `url` must match exactly

471* The `ref` field must match exactly (or both be undefined)

472* The `path` field must match exactly (or both be undefined)

473 

474Examples of sources that **do NOT match**:

475 

476```json theme={null}

477// These are DIFFERENT sources:

478{ "source": "github", "repo": "company/plugins" }

479{ "source": "github", "repo": "company/plugins", "ref": "main" }

480 

481// These are also DIFFERENT:

482{ "source": "github", "repo": "company/plugins", "path": "marketplace" }

483{ "source": "github", "repo": "company/plugins" }

484```

485 

486**Comparison with `extraKnownMarketplaces`**:

487 

488| Aspect | `strictKnownMarketplaces` | `extraKnownMarketplaces` |

489| --------------------- | ------------------------------------ | ------------------------------------ |

490| **Purpose** | Enterprise policy enforcement | Team convenience |

491| **Settings file** | `managed-settings.json` only | Any settings file |

492| **Behavior** | Blocks non-allowlisted additions | Auto-installs missing marketplaces |

493| **When enforced** | Before network/filesystem operations | After user trust prompt |

494| **Can be overridden** | No (highest precedence) | Yes (by higher precedence settings) |

495| **Source format** | Direct source object | Named marketplace with nested source |

496| **Use case** | Compliance, security restrictions | Onboarding, standardization |

497 

498**Format difference**:

499 

500`strictKnownMarketplaces` uses direct source objects:

501 

502```json theme={null}

503{

504 "strictKnownMarketplaces": [

505 { "source": "github", "repo": "company/plugins" }

506 ]

507}

508```

509 

510`extraKnownMarketplaces` requires named marketplaces:

511 

512```json theme={null}

513{

514 "extraKnownMarketplaces": {

515 "company-tools": {

516 "source": { "source": "github", "repo": "company/plugins" }

517 }

518 }

519}

520```

521 

522**Important notes**:

523 

524* Restrictions are checked BEFORE any network requests or filesystem operations

525* When blocked, users see clear error messages indicating the source is blocked by enterprise policy

526* The restriction applies only to adding NEW marketplaces; previously installed marketplaces remain accessible

527* Enterprise managed settings have the highest precedence and cannot be overridden

528 

529See [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions) for user-facing documentation.

530 

339### Managing plugins531### Managing plugins

340 532 

341Use the `/plugin` command to manage plugins interactively:533Use the `/plugin` command to manage plugins interactively:

516## See also708## See also

517 709 

518* [Identity and Access Management](/en/iam#configuring-permissions) - Learn about Claude Code's permission system710* [Identity and Access Management](/en/iam#configuring-permissions) - Learn about Claude Code's permission system

519* [IAM and access control](/en/iam#enterprise-managed-policy-settings) - Enterprise policy management711* [IAM and access control](/en/iam#enterprise-managed-settings) - Enterprise policy management

520* [Troubleshooting](/en/troubleshooting#auto-updater-issues) - Solutions for common configuration issues712* [Troubleshooting](/en/troubleshooting#auto-updater-issues) - Solutions for common configuration issues

521 713 

522 714 

21 21 

22<Tabs>22<Tabs>

23 <Tab title="Native Install (Recommended)">23 <Tab title="Native Install (Recommended)">

24 **Homebrew (macOS, Linux):**

25 

26 ```sh theme={null}

27 brew install --cask claude-code

28 ```

29 

30 **macOS, Linux, WSL:**24 **macOS, Linux, WSL:**

31 25 

32 ```bash theme={null}26 ```bash theme={null}

46 ```40 ```

47 </Tab>41 </Tab>

48 42 

43 <Tab title="Homebrew">

44 ```sh theme={null}

45 brew install --cask claude-code

46 ```

47 </Tab>

48 

49 <Tab title="NPM">49 <Tab title="NPM">

50 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):50 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):

51 51 

129 **Alpine Linux and other musl/uClibc-based distributions**: The native build requires `libgcc`, `libstdc++`, and `ripgrep`. For Alpine: `apk add libgcc libstdc++ ripgrep`. Set `USE_BUILTIN_RIPGREP=0`.129 **Alpine Linux and other musl/uClibc-based distributions**: The native build requires `libgcc`, `libstdc++`, and `ripgrep`. For Alpine: `apk add libgcc libstdc++ ripgrep`. Set `USE_BUILTIN_RIPGREP=0`.

130</Note>130</Note>

131 131 

132<Note>

133 Claude Code installed via Homebrew will auto-update outside of the brew directory unless explicitly disabled with the `DISABLE_AUTOUPDATER` environment variable (see [Auto updates](#auto-updates) section).

134</Note>

135 

136**Windows PowerShell:**132**Windows PowerShell:**

137 133 

138```powershell theme={null}134```powershell theme={null}

62 "context_window": {62 "context_window": {

63 "total_input_tokens": 15234,63 "total_input_tokens": 15234,

64 "total_output_tokens": 4521,64 "total_output_tokens": 4521,

65 "context_window_size": 20000065 "context_window_size": 200000,

66 "current_usage": {

67 "input_tokens": 8500,

68 "output_tokens": 1200,

69 "cache_creation_input_tokens": 5000,

70 "cache_read_input_tokens": 2000

71 }

66 }72 }

67}73}

68```74```

198 204 

199### Context Window Usage205### Context Window Usage

200 206 

201Display the percentage of context window consumed:207Display the percentage of context window consumed. The `context_window` object contains:

208 

209* `total_input_tokens` / `total_output_tokens`: Cumulative totals across the entire session

210* `current_usage`: Current context window usage from the last API call (may be `null` if no messages yet)

211 * `input_tokens`: Input tokens in current context

212 * `output_tokens`: Output tokens generated

213 * `cache_creation_input_tokens`: Tokens written to cache

214 * `cache_read_input_tokens`: Tokens read from cache

215 

216For accurate context percentage, use `current_usage` which reflects the actual context window state:

202 217 

203```bash theme={null}218```bash theme={null}

204#!/bin/bash219#!/bin/bash

205input=$(cat)220input=$(cat)

206 221 

207INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens')

208OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens')

209CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')

210MODEL=$(echo "$input" | jq -r '.model.display_name')222MODEL=$(echo "$input" | jq -r '.model.display_name')

211 223CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')

212TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS))224USAGE=$(echo "$input" | jq '.context_window.current_usage')

213PERCENT_USED=$((TOTAL_TOKENS * 100 / CONTEXT_SIZE))225 

214 226if [ "$USAGE" != "null" ]; then

215echo "[$MODEL] Context: ${PERCENT_USED}%"227 # Calculate current context from current_usage fields

228 CURRENT_TOKENS=$(echo "$USAGE" | jq '.input_tokens + .cache_creation_input_tokens + .cache_read_input_tokens')

229 PERCENT_USED=$((CURRENT_TOKENS * 100 / CONTEXT_SIZE))

230 echo "[$MODEL] Context: ${PERCENT_USED}%"

231else

232 echo "[$MODEL] Context: 0%"

233fi

216```234```

217 235 

218## Tips236## Tips

62 62 

63Claude Code has a native installation that doesn't depend on npm or Node.js.63Claude Code has a native installation that doesn't depend on npm or Node.js.

64 64 

65<Note>

66 The native Claude Code installer is currently in beta.

67</Note>

68 

69Use the following command to run the native installer.65Use the following command to run the native installer.

70 66 

71**macOS, Linux, WSL:**67**macOS, Linux, WSL:**

1# Visual Studio Code1# Use Claude Code in VS Code

2 2 

3> Use Claude Code with Visual Studio Code through the native extension or CLI integration3> Install and configure the Claude Code extension for VS Code. Get AI coding assistance with inline diffs, @-mentions, plan review, and keyboard shortcuts.

4 4 

5<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=300652d5678c63905e6b0ea9e50835f8" alt="Claude Code VS Code Extension Interface" data-og-width="2500" width="2500" data-og-height="1155" height="1155" data-path="images/vs-code-extension-interface.jpg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=280&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=87630c671517a3d52e9aee627041696e 280w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=560&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=716b093879204beec8d952649ef75292 560w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=840&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=c1525d1a01513acd9d83d8b5a8fe2fc8 840w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1100&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=1d90021d58bbb51f871efec13af955c3 1100w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1650&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=7babdd25440099886f193cfa99af88ae 1650w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=2500&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=08c92eedfb56fe61a61e480fb63784b6 2500w" />5<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=300652d5678c63905e6b0ea9e50835f8" alt="VS Code editor with the Claude Code extension panel open on the right side, showing a conversation with Claude" data-og-width="2500" width="2500" data-og-height="1155" height="1155" data-path="images/vs-code-extension-interface.jpg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=280&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=87630c671517a3d52e9aee627041696e 280w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=560&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=716b093879204beec8d952649ef75292 560w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=840&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=c1525d1a01513acd9d83d8b5a8fe2fc8 840w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1100&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=1d90021d58bbb51f871efec13af955c3 1100w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1650&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=7babdd25440099886f193cfa99af88ae 1650w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=2500&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=08c92eedfb56fe61a61e480fb63784b6 2500w" />

6 6 

7## VS Code Extension (Beta)7The VS Code extension provides a native graphical interface for Claude Code, integrated directly into your IDE. This is the recommended way to use Claude Code in VS Code.

8 8 

9The VS Code extension, available in beta, lets you see Claude's changes in real-time through a native graphical interface integrated directly into your IDE. The VS Code extension makes it easier to access and interact with Claude Code for users who prefer a visual interface over the terminal.9With the extension, you can review and edit Claude's plans before accepting them, auto-accept edits as they're made, @-mention files with specific line ranges from your selection, access conversation history, and open multiple conversations in separate tabs or windows.

10 10 

11### Features11## Prerequisites

12 12 

13The VS Code extension provides:13* VS Code 1.98.0 or higher

14* An Anthropic account (you'll sign in when you first open the extension). If you're using a third-party provider like Amazon Bedrock or Google Vertex AI, see [Use third-party providers](#use-third-party-providers) instead.

14 15 

15* **Native IDE experience**: Dedicated Claude Code sidebar panel accessed via the Spark icon16You don't need to install the Claude Code CLI first. However, some features like MCP server configuration require the CLI. See [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) for details.

16* **Plan mode with editing**: Review and edit Claude's plans before accepting them

17* **Auto-accept edits mode**: Automatically apply Claude's changes as they're made

18* **Extended thinking**: Toggle extended thinking on/off using the Extended Thinking button in the bottom-right corner of the prompt input

19* **File management**: @-mention files or attach files and images using the system file picker

20* **MCP server usage**: Use Model Context Protocol servers configured through the CLI

21* **Conversation history**: Access to past conversations

22* **Multiple sessions**: Run multiple Claude Code sessions simultaneously

23* **Keyboard shortcuts**: Support for most shortcuts from the CLI

24* **Slash commands**: Access most CLI slash commands directly in the extension

25 17 

26### Requirements18## Install the extension

27 19 

28* VS Code 1.98.0 or higher20Click the link for your IDE to install directly:

21 

22* [Install for VS Code](vscode:extension/anthropic.claude-code)

23* [Install for Cursor](cursor:extension/anthropic.claude-code)

29 24 

30### Installation25Or in VS Code, press `Cmd+Shift+X` (Mac) or `Ctrl+Shift+X` (Windows/Linux) to open the Extensions view, search for "Claude Code", and click **Install**.

31 26 

32Download and install the extension from the [Visual Studio Code Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code).27<Note>You may need to restart VS Code or run "Developer: Reload Window" from the Command Palette after installation.</Note>

33 28 

34### How it works29## Get started

35 30 

36Once installed, you can start using Claude Code through the VS Code interface:31Once installed, you can start using Claude Code through the VS Code interface:

37 32 

381. Click the Spark icon in your editor's sidebar to open the Claude Code panel33<Steps>

392. Prompt Claude Code in the same way you would in the terminal34 <Step title="Open the Claude Code panel">

403. Watch as Claude analyzes your code and suggests changes35 Throughout VS Code, the Spark icon indicates Claude Code: <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=a734d84e785140016672f08e0abb236c" alt="Spark icon" style={{display: "inline", height: "0.85em", verticalAlign: "middle"}} data-og-width="16" width="16" data-og-height="16" height="16" data-path="images/vs-code-spark-icon.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=280&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=9a45aad9a84b9fa1701ac99a1f9aa4e9 280w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=560&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=3f4cb9254c4d4e93989c4b6bf9292f4b 560w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=840&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=e75ccc9faa3e572db8f291ceb65bb264 840w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=1100&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=f147bd81a381a62539a4ce361fac41c7 1100w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=1650&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=78fe68efaee5d6e844bbacab1b442ed5 1650w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=2500&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=efb8dbe1dfa722d094edc6ad2ad4bedb 2500w" />

414. Review and accept edits directly in the interface

42 * **Tip**: Drag the sidebar wider to see inline diffs, then click them to expand for full details

43 36 

44### Configuration37 The quickest way to open Claude is to click this icon in the **Editor Toolbar** (top-right corner of the editor). Note: This icon only appears when you have a file open—opening just a folder isn't enough.

45 38 

46The VS Code extension reads the same `settings.json` files as the CLI. See the [settings documentation](/en/settings) for details.39 <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=eb4540325d94664c51776dbbfec4cf02" alt="VS Code editor showing the Spark icon in the Editor Toolbar" data-og-width="2796" width="2796" data-og-height="734" height="734" data-path="images/vs-code-editor-icon.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=280&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=56f218d5464359d6480cfe23f70a923e 280w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=560&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=344a8db024b196c795a80dc85cacb8d1 560w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=840&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=f30bf834ee0625b2a4a635d552d87163 840w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=1100&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=81fdf984840e43a9f08ae42729d1484d 1100w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=1650&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=8b60fb32de54717093d512afaa99785c 1650w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=2500&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=893e6bda8f2e9d42c8a294d394f0b736 2500w" />

47 40 

48#### Third-party providers and gateways41 Other ways to open Claude Code:

49 42 

50To use the VS Code extension with third-party providers (Amazon Bedrock, Google Vertex AI, Microsoft Foundry) or gateways that handle authentication:43 * **Command Palette**: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux), type "Claude Code", and select an option like "Open in New Tab"

44 * **Activity Bar**: Run "Claude Code: Open in Side Bar" from the Command Palette once, and a Spark icon will appear in the left sidebar. This is useful if you want quick access without having a file open.

51 45 

521. Add the appropriate environment variables for your provider or gateway to your Claude Code `settings.json`:46 You can drag the Claude panel to reposition it anywhere in VS Code, including to the Activity Bar if the Spark icon isn't showing there. See [Customize your workflow](#customize-your-workflow) for details.

53 ```json theme={null}47 </Step>

54 {

55 "env": {

56 "CLAUDE_CODE_USE_BEDROCK": "1",

57 "AWS_REGION": "us-east-2",

58 "AWS_PROFILE": "your-profile"

59 }

60 }

61 ```

62 48 

632. Disable the VS Code extension login prompt via [`vscode://settings/claudeCode.disableLoginPrompt`](vscode://settings/claudeCode.disableLoginPrompt) or in VS Code's settings:49 <Step title="Send a prompt">

64 ```json theme={null}50 Prompt Claude Code in the same way you would in the terminal.

65 {51 </Step>

66 "claudeCode.disableLoginPrompt": true

67 }

68 ```

69 52 

70For detailed setup instructions and additional configuration options, see:53 <Step title="Review changes">

54 Watch as Claude analyzes your code and suggests changes. Review and accept edits directly in the interface.

55 </Step>

56</Steps>

71 57 

72* [Claude Code on Amazon Bedrock](/en/amazon-bedrock)58## Customize your workflow

73* [Claude Code on Google Vertex AI](/en/google-vertex-ai)

74* [Claude Code on Microsoft Foundry](/en/microsoft-foundry)

75 59 

76### Not yet implemented60Once you're up and running, you can reposition the Claude panel or switch to terminal mode.

77 61 

78The following features aren't yet available in the VS Code extension:62### Change the layout

79 63 

80* **MCP server and Plugin configuration UI**: Type `/mcp` to open the terminal-based MCP server configuration, or `/plugin` for Plugin configuration. Once configured, MCP servers and Plugins work in the extension. You can also [configure MCP servers through the CLI](/en/mcp) first, then the extension will use them.64You can drag the Claude panel to reposition it anywhere in VS Code. Grab the panel's tab or title bar and drag it to:

81* **Subagents configuration**: Configure [subagents through the CLI](/en/sub-agents) to use them in VS Code

82* **Checkpoints**: Save and restore conversation state at specific points

83* **Conversation rewinding**: The `/rewind` command is coming soon

84* **Advanced shortcuts**:

85 * `#` shortcut to add to memory (not supported)

86 * `!` shortcut to run bash commands directly (not supported)

87* **Tab completion**: File path completion with tab key

88* **Model selection UI for older models**: To use older model versions like `claude-sonnet-4-20250514`, open VS Code settings for Claude Code (the `/General Config` command) and insert the model string directly into the 'Selected Model' field

89 65 

90These features are planned for future updates.66* **Activity Bar**: The left sidebar with icons for Explorer, Search, etc.

67* **Secondary sidebar**: The right side of the window

68* **Editor area**: Opens Claude as a tab alongside your files

91 69 

92## Security considerations70This lets you position Claude wherever works best for your workflow.

71 

72### Switch to terminal mode

73 

74By default, the extension opens a graphical chat panel. If you prefer the CLI-style interface, open the [Use Terminal setting](vscode://settings/claudeCode.useTerminal) and check the box.

75 

76You can also open VS Code settings (`Cmd+,` on Mac or `Ctrl+,` on Windows/Linux), go to Extensions → Claude Code, and check **Use Terminal**.

77 

78<Note>

79 In terminal mode, the Activity Bar icon (left vertical menu) still opens the graphical panel, while the Editor Toolbar icon (top-right of editor) opens terminal mode. You can use both entry points to switch between interfaces without changing settings.

80</Note>

81 

82## VS Code commands and shortcuts

83 

84Open the Command Palette (`Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Windows/Linux) and type "Claude Code" to see all available VS Code commands for the Claude Code extension:

85 

86<Note>

87 These are VS Code commands for controlling the extension. For Claude Code slash commands (like `/help` or `/compact`), not all CLI commands are available in the extension yet. See [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) for details.

88</Note>

89 

90| Command | Shortcut | Description |

91| -------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------- |

92| Focus Input | `Cmd+Esc` (Mac) / `Ctrl+Esc` (Windows/Linux) | Toggle focus between editor and Claude |

93| Open in Side Bar | — | Open Claude in the left sidebar |

94| Open in Terminal | — | Open Claude in terminal mode |

95| Open in New Tab | `Cmd+Shift+Esc` (Mac) / `Ctrl+Shift+Esc` (Windows/Linux) | Open a new conversation as an editor tab |

96| Open in New Window | — | Open a new conversation in a separate window |

97| New Conversation | `Cmd+N` (Mac) / `Ctrl+N` (Windows/Linux) | Start a new conversation (when Claude is focused) |

98| Insert @-Mention Reference | `Alt+K` | Insert a reference to the current file (includes line numbers if text is selected) |

99| Show Logs | — | View extension debug logs |

100| Logout | — | Sign out of your Anthropic account |

101 

102Use **Open in New Tab** or **Open in New Window** to run multiple conversations simultaneously. Each tab or window maintains its own conversation history and context.

103 

104## Configure settings

105 

106The extension has two types of settings:

107 

108* **Extension settings**: Open with `Cmd+,` (Mac) or `Ctrl+,` (Windows/Linux), then go to Extensions → Claude Code.

109 

110 | Setting | Description |

111 | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

112 | Selected Model | Default model for new conversations. Change per-session with `/model`. |

113 | Use Terminal | Launch Claude in terminal mode instead of graphical panel |

114 | Initial Permission Mode | Controls approval prompts for file edits and commands. Defaults to `default` (ask before each action). |

115 | Preferred Location | Default location: sidebar (right) or panel (new tab) |

116 | Autosave | Auto-save files before Claude reads or writes them |

117 | Use Ctrl+Enter to Send | Use Ctrl/Cmd+Enter instead of Enter to send prompts |

118 | Enable New Conversation Shortcut | Enable Cmd/Ctrl+N to start a new conversation |

119 | Respect Git Ignore | Exclude .gitignore patterns from file searches |

120 | Environment Variables | Set environment variables for the Claude process. **Not recommended**—use [Claude Code settings](/en/settings) instead so configuration is shared between extension and CLI. |

121 | Disable Login Prompt | Skip authentication prompts (for third-party provider setups) |

122 | Allow Dangerously Skip Permissions | Bypass all permission prompts. **Use with extreme caution**—recommended only for isolated sandboxes with no internet access. |

123 | Claude Process Wrapper | Executable path used to launch the Claude process |

124 

125* **Claude Code settings** (`~/.claude/settings.json`): These settings are shared between the VS Code extension and the CLI. Use this file for allowed commands and directories, environment variables, hooks, and MCP servers. See the [settings documentation](/en/settings) for details.

126 

127## Use third-party providers

128 

129By default, Claude Code connects directly to Anthropic's API. If your organization uses Amazon Bedrock, Google Vertex AI, or Microsoft Foundry to access Claude, configure the extension to use your provider instead:

130 

131<Steps>

132 <Step title="Disable login prompt">

133 Open the [Disable Login Prompt setting](vscode://settings/claudeCode.disableLoginPrompt) and check the box.

134 

135 You can also open VS Code settings (`Cmd+,` on Mac or `Ctrl+,` on Windows/Linux), search for "Claude Code login", and check **Disable Login Prompt**.

136 </Step>

93 137 

94When Claude Code runs in VS Code with auto-edit permissions enabled, it may be able to modify IDE configuration files that can be automatically executed by your IDE. This may increase the risk of running Claude Code in auto-edit mode and allow bypassing Claude Code's permission prompts for bash execution.138 <Step title="Configure your provider">

139 Follow the setup guide for your provider:

95 140 

96When running in VS Code, consider:141 * [Claude Code on Amazon Bedrock](/en/amazon-bedrock)

142 * [Claude Code on Google Vertex AI](/en/google-vertex-ai)

143 * [Claude Code on Microsoft Foundry](/en/microsoft-foundry)

97 144 

98* Enabling [VS Code Restricted Mode](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode) for untrusted workspaces145 These guides cover configuring your provider in `~/.claude/settings.json`, which ensures your settings are shared between the VS Code extension and the CLI.

99* Using manual approval mode for edits146 </Step>

100* Taking extra care to ensure Claude is only used with trusted prompts147</Steps>

101 148 

102## Legacy CLI integration149## VS Code extension vs. Claude Code CLI

103 150 

104The original VS Code integration allows Claude Code running in the terminal to interact with your IDE. It provides selection context sharing (current selection/tab is automatically shared with Claude Code), diff viewing in the IDE instead of terminal, file reference shortcuts (`Cmd+Option+K` on Mac or `Alt+Ctrl+K` on Windows/Linux to insert file references like @File#L1-99), and automatic diagnostic sharing (lint and syntax errors).151The extension doesn't yet have full feature parity with the CLI. If you need CLI-only features, you can run `claude` directly in VS Code's integrated terminal.

105 152 

106The legacy integration auto-installs when you run `claude` from VS Code's integrated terminal. Run `claude` from the terminal and all features activate. For external terminals, use the `/ide` command to connect Claude Code to your VS Code instance. To configure, run `claude`, enter `/config`, and set the diff tool to `auto` for automatic IDE detection.153| Feature | CLI | VS Code Extension |

154| ------------------- | ------------------------------ | ---------------------------------------- |

155| Slash commands | [Full set](/en/slash-commands) | Subset (type `/` to see available) |

156| MCP server config | Yes | No (configure via CLI, use in extension) |

157| Checkpoints | Yes | Coming soon |

158| `#` memory shortcut | Yes | No |

159| `!` bash shortcut | Yes | No |

160| Tab completion | Yes | No |

107 161 

108Both the extension and CLI integration work with Visual Studio Code, Cursor, Windsurf, and VSCodium.162### Run CLI in VS Code

109 163 

110## Troubleshooting164To use the CLI while staying in VS Code, open the integrated terminal (`` Ctrl+` `` on Windows/Linux or `` Cmd+` `` on Mac) and run `claude`. The CLI automatically integrates with your IDE for features like diff viewing and diagnostic sharing.

111 165 

112### Extension not installing166If using an external terminal, run `/ide` inside Claude Code to connect it to VS Code.

113 167 

114* Ensure you have a compatible version of VS Code (1.85.0 or later)168### Switch between extension and CLI

169 

170The extension and CLI share the same conversation history. To continue an extension conversation in the CLI, run `claude --resume` in the terminal. This opens an interactive picker where you can search for and select your conversation.

171 

172## Security considerations

173 

174With auto-edit permissions enabled, Claude Code can modify VS Code configuration files (like `settings.json` or `tasks.json`) that VS Code may execute automatically. This could potentially bypass Claude Code's normal permission prompts.

175 

176To reduce risk when working with untrusted code:

177 

178* Enable [VS Code Restricted Mode](https://code.visualstudio.com/docs/editor/workspace-trust#_restricted-mode) for untrusted workspaces

179* Use manual approval mode instead of auto-accept for edits

180* Review changes carefully before accepting them

181 

182## Fix common issues

183 

184### Extension won't install

185 

186* Ensure you have a compatible version of VS Code (1.98.0 or later)

115* Check that VS Code has permission to install extensions187* Check that VS Code has permission to install extensions

116* Try installing directly from the Marketplace website188* Try installing directly from the Marketplace website

117 189 

190### Spark icon not visible

191 

192There are two places the Spark icon can appear:

193 

194* **Editor Toolbar** (top-right of editor): Only visible when a file is open

195* **Activity Bar** (left sidebar): Only visible after running "Claude Code: Open in Side Bar" from the Command Palette

196 

197If you don't see the icon:

198 

1991. **Open a file**: The Editor Toolbar icon requires a file to be open—having just a folder open isn't enough

2002. **Enable the Activity Bar icon**: Run "Claude Code: Open in Side Bar" from the Command Palette once, and the icon will appear in the Activity Bar permanently

2013. **Check VS Code version**: Requires 1.98.0 or higher (Help → About)

2024. **Restart VS Code**: Run "Developer: Reload Window" from the command palette

2035. **Disable conflicting extensions**: Temporarily disable other AI extensions (Cline, Continue, etc.)

2046. **Check workspace trust**: The extension doesn't work in Restricted Mode

2057. **Use the Command Palette**: Open with `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux), then type "Claude Code: Open in Side Bar"

206 

118### Claude Code never responds207### Claude Code never responds

119 208 

120If Claude Code isn't responding to your prompts:209If Claude Code isn't responding to your prompts:

1243. **Try the CLI**: Run `claude` from the terminal to see if you get more detailed error messages2133. **Try the CLI**: Run `claude` from the terminal to see if you get more detailed error messages

1254. **File a bug report**: If the problem continues, [file an issue on GitHub](https://github.com/anthropics/claude-code/issues) with details about the error2144. **File a bug report**: If the problem continues, [file an issue on GitHub](https://github.com/anthropics/claude-code/issues) with details about the error

126 215 

127### Legacy integration not working216### Standalone CLI not connecting to IDE

128 217 

129* Ensure you're running Claude Code from VS Code's integrated terminal218* Ensure you're running Claude Code from VS Code's integrated terminal (not an external terminal)

130* Ensure the CLI for your IDE variant is installed:219* Ensure the CLI for your IDE variant is installed:

131 * VS Code: `code` command should be available220 * VS Code: `code` command should be available

132 * Cursor: `cursor` command should be available221 * Cursor: `cursor` command should be available

133 * Windsurf: `windsurf` command should be available222 * Windsurf: `windsurf` command should be available

134 * VSCodium: `codium` command should be available223 * VSCodium: `codium` command should be available

135* If the command isn't installed:224* If the command isn't available, install it from the Command Palette → "Shell Command: Install 'code' command in PATH"

136 1. Open command palette with `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)225 

137 2. Search for `Shell Command: Install 'code' command in PATH` (or equivalent for your IDE)226## Uninstall the extension

227 

228To uninstall the Claude Code extension:

229 

2301. Open the Extensions view (`Cmd+Shift+X` on Mac or `Ctrl+Shift+X` on Windows/Linux)

2312. Search for "Claude Code"

2323. Click **Uninstall**

233 

234To also remove extension data and reset all settings:

235 

236```bash theme={null}

237rm -rf ~/.vscode/globalStorage/anthropic.claude-code

238```

138 239 

139For additional help, see the [troubleshooting guide](/en/troubleshooting).240For additional help, see the [troubleshooting guide](/en/troubleshooting).

140 241 

242## Next steps

243 

244Now that you have Claude Code set up in VS Code:

245 

246* [Explore common workflows](/en/common-workflows) to get the most out of Claude Code

247* [Set up MCP servers](/en/mcp) to extend Claude's capabilities with external tools. Configure servers using the CLI, then use them in the extension.

248* [Configure Claude Code settings](/en/settings) to customize allowed commands, hooks, and more. These settings are shared between the extension and CLI.

249 

141 250 

142---251---

143 252