llms.txt@03-IDE-Integrations · git:20261024.48b8a60 · 2026-10-24 · sha256 1a16caac4c98a2e4
llms.txt@03-IDE-Integrations git:20261024.48b8a60F
Immutable. This exact content never changes and is served at /api/v1/blob/1a16caac4c98a2e4.
# IDE Integrations
> Every page below, concatenated. Each section gives the page title, its upstream source and its path in this repository.
---
## Use Claude Code with Chrome - Claude Code Docs
Source: https://code.claude.com/docs/en/chrome
Path: 03-IDE-Integrations/chrome.md
## On this page
- [Capabilities](#capabilities)
- [Prerequisites](#prerequisites)
- [Get started in the CLI](#get-started-in-the-cli)
- [Install the extension when Claude asks](#install-the-extension-when-claude-asks)
- [Enable Chrome by default](#enable-chrome-by-default)
- [Manage site permissions](#manage-site-permissions)
- [Permission prompts in VS Code sessions](#permission-prompts-in-vs-code-sessions)
- [Browser tools in plan mode](#browser-tools-in-plan-mode)
- [Example workflows](#example-workflows)
- [Test a local web application](#test-a-local-web-application)
- [Debug with console logs](#debug-with-console-logs)
- [Automate form filling](#automate-form-filling)
- [Upload files to web pages](#upload-files-to-web-pages)
- [Draft content in Google Docs](#draft-content-in-google-docs)
- [Extract data from web pages](#extract-data-from-web-pages)
- [Run multi-site workflows](#run-multi-site-workflows)
- [Record a demo GIF](#record-a-demo-gif)
- [Save screenshots to disk](#save-screenshots-to-disk)
- [Troubleshooting](#troubleshooting)
- [Extension not detected](#extension-not-detected)
- [Project settings can’t turn on Chrome](#project-settings-can%E2%80%99t-turn-on-chrome)
- [Browser not responding](#browser-not-responding)
- [Connection drops during long sessions](#connection-drops-during-long-sessions)
- [Extension signed in to a different organization](#extension-signed-in-to-a-different-organization)
- [Windows-specific issues](#windows-specific-issues)
- [Common error messages](#common-error-messages)
- [See also](#see-also)
Platforms and integrations
# Use Claude Code with Chrome
Copy pageCopy page
Connect Claude Code to your Chrome browser to test web apps, debug with console logs, automate form filling, and extract data from web pages.
Copy pageCopy page
Claude Code integrates with the [Claude in Chrome browser extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) to give you browser automation capabilities from the CLI or the [VS Code extension](vs-code.md#automate-browser-tasks-with-chrome). Build your code, then test and debug in the browser without switching contexts. Claude opens new tabs for browser tasks and shares your browser’s login state, so it can access any site you’re already signed into. Browser actions run in a visible Chrome window in real time. When Claude encounters a login page or CAPTCHA, it pauses and asks you to handle it manually. The extension collects the tabs Claude opens into a Chrome tab group tied to your session. In local sessions, whether Claude Code closes that group when the session ends depends on how it ends:
- When you type `/clear`, Claude Code closes the group, open pages included, unless work that survives the clear is still running
- When you switch sessions with a command like `/resume`, exit Claude Code, or run a `/clear` while work that survives it is still running, Claude Code closes the group only if it holds nothing but empty new tabs, so pages you may still be reading stay open
Chrome integration works with Google Chrome and Microsoft Edge. Claude Code also detects the extension and sets up the connection in other Chromium-based browsers, including Brave, Arc, Vivaldi, and Opera. Chrome integration isn’t supported in Windows Subsystem for Linux (WSL).
[](#capabilities)
Capabilities
With Chrome connected, you can chain browser actions with coding tasks in a single workflow:
- **Live debugging**: read console errors and DOM state directly, then fix the code that caused them
- **Design verification**: build a UI from a Figma mock, then open it in the browser to verify it matches
- **Web app testing**: test form validation, check for visual regressions, or verify user flows
- **Authenticated web apps**: interact with Google Docs, Gmail, Notion, or any app you’re logged into without API connectors
- **Data extraction**: pull structured information from web pages and save it locally
- **Task automation**: automate repetitive browser tasks like data entry, form filling, or multi-site workflows
- **File uploads**: attach files from your machine to upload fields on web pages
- **Session recording**: record browser interactions as GIFs to document or share what happened
[](#prerequisites)
Prerequisites
Before using Claude Code with Chrome, you need:
- [Google Chrome](https://www.google.com/chrome/), [Microsoft Edge](https://www.microsoft.com/edge), or another Chromium-based browser such as Brave, Arc, Vivaldi, or Opera
- [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or later, available in the Chrome Web Store
- [Claude Code](../01-Getting-Started/quickstart.md#step-1-install-claude-code)
- A direct Anthropic plan (Pro, Max, Team, or Enterprise)
In Enterprise organizations that have HIPAA enabled, Claude in Chrome is off by default, and an [Owner](../13-Enterprise-Admin/server-managed-settings.md#access-control) can turn it on in [**Organization settings \> Claude in Chrome**](https://claude.ai/admin-settings/browser-extension). Your Business Associate Agreement (BAA) with Anthropic doesn’t cover data sent to third-party sites through Claude in Chrome. See the [Implementation Guide](https://trust.anthropic.com/resources?s=l1wrssd9hsbi4gak0tp5a6&name=%5Banthropic%5D-hipaa-ready-offering-implementation-guide) for a list of Eligible Services. Chrome integration also requires signing in with `/login`. If you authenticate with an API key or a long-lived token from [`claude setup-token`](../02-Claude-Code-CLI/authentication.md#generate-a-long-lived-token), Claude Code keeps Chrome integration off, even when you pass `--chrome`, because the browser extension can’t authenticate with those credentials. Before v2.1.216, these sessions could enable Chrome integration, but every attempt to connect to the browser extension failed with a 403 error.
Chrome integration is not available through third-party providers like Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry. If you access Claude exclusively through a third-party provider, you need a separate claude.ai account to use this feature.
[](#get-started-in-the-cli)
Get started in the CLI
1
Launch Claude Code with Chrome
Start Claude Code with the `--chrome` flag:
```python
claude --chrome
```
The first time you launch with Chrome, Claude Code shows a one-time dialog that introduces the integration and explains how site permissions work. Press Enter to continue.To enable Chrome for future sessions without the flag, see [Enable Chrome by default](#enable-chrome-by-default).
2
Ask Claude to use the browser
This example navigates to a page, interacts with it, and reports what it finds, all from your terminal or editor:
```python
Go to code.claude.com/docs, click on the search box,
type "hooks", and tell me what results appear
```
If Claude Code asks for permission before a browser action, approve it. The dialog starts with `Claude in Chrome wants to` and offers an option to allow all actions on that site for the session. Claude opens a new tab and starts the task.
Run `/chrome` at any time to check the connection status, manage permissions, reconnect the extension, or choose which connected browser to use. The integration is working when the status panel shows “Status: Enabled” and “Extension: Installed”. If more than one browser is connected, you choose which one Claude uses. When a browser action starts before you’ve chosen, Claude prompts you to pick one. To switch browsers later, run `/chrome` and select **Select browser…**. Claude keeps using your choice even when another browser connects. For VS Code, see [browser automation in VS Code](vs-code.md#automate-browser-tasks-with-chrome).
[](#install-the-extension-when-claude-asks)
Install the extension when Claude asks
When Claude needs your browser in an interactive session and Claude Code doesn’t detect the extension, Claude Code shows an install prompt titled “Claude wants to use your browser”. Claude Code asks at most once per session. The prompt offers three choices:
- **Install extension**: opens the extension install page in your browser and starts a guided setup. Claude Code waits for the install, connects the extension, and enables browser tools in the same session. When the connection is ready, select “Continue with browser tools” and Claude resumes the task in your browser. You can leave setup by selecting “Continue without browser tools” and finish later with `/chrome`.
- **Not now**: continues the task without browser tools. Claude Code can ask again in a later session.
- **Don’t ask again**: stops the prompt in future sessions. You can still set up the integration anytime with `/chrome`.
Two managed MCP policies turn the prompt off:
- If your organization blocks the `claude-in-chrome` MCP server with the [`deniedMcpServers` managed setting](../06-MCP-Tools/General/managed-mcp.md#policy-based-control-with-allowlists-and-denylists), Claude Code doesn’t show the install prompt.
- If your organization deploys a [`managed-mcp.json`](../06-MCP-Tools/General/managed-mcp.md#exclusive-control-with-managed-mcp-json) file without [allowing Claude in Chrome alongside the managed set](../06-MCP-Tools/General/managed-mcp.md#allow-claude-in-chrome-alongside-the-managed-set), Claude Code doesn’t show the install prompt.
[](#enable-chrome-by-default)
Enable Chrome by default
To connect Chrome without passing `--chrome` each time, run `/chrome` in a CLI session and select **Enabled by default**. In the [VS Code extension](vs-code.md#automate-browser-tasks-with-chrome), type `/chrome` in the prompt box and turn on the **Enabled by default** switch. The two share one setting, so turning it on in either place turns it on for both the CLI and VS Code. With the setting on and Claude Code v2.1.287 or later, each VS Code session connects to your browser as it starts, so Claude can use it before you type `@browser`. On earlier versions, or with the setting off, a VS Code session connects when you type `@browser`. Claude Code starts normally when Chrome isn’t running.
Enabling Chrome by default increases context usage since the browser tools and their instructions are always loaded. If you notice increased context consumption, turn the setting off and connect only when needed, with `--chrome` in the CLI or by typing [`@browser`](vs-code.md#automate-browser-tasks-with-chrome) in the VS Code prompt box.
[](#manage-site-permissions)
Manage site permissions
Site-level permissions are inherited from the Chrome extension. Manage permissions in the Chrome extension settings to control which sites Claude can browse, click, and type on. In [auto mode](../02-Claude-Code-CLI/permission-modes.md#eliminate-prompts-with-auto-mode), when the auto mode classifier itself approves a browser call to a site, the extension skips its own per-site check for that call, unless your permission rules deny any site to Claude in Chrome.
[](#permission-prompts-in-vs-code-sessions)
Permission prompts in VS Code sessions
In a VS Code session, when Claude Code asks before a browser action, the prompt appears as a card in the chat panel. When the action targets a site you haven’t allowed, the card also offers to allow that site. In a session that connected to your browser at start because [Enabled by default](#enable-chrome-by-default) is on, Claude Code asks you before browser actions on a site you haven’t allowed, in Manual, Edit automatically, Auto, and Bypass permissions modes. In Auto and Bypass permissions modes, this applies until you type `@browser` in that session.
[](#browser-tools-in-plan-mode)
Browser tools in plan mode
In [plan mode](../02-Claude-Code-CLI/permission-modes.md#analyze-before-you-edit-with-plan-mode), a permission prompt appears before Claude records a GIF, opens a new tab, or runs a shortcut. In an interactive CLI session, if [bypass permissions mode is available](../02-Claude-Code-CLI/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) and [feature-flag fetching](../02-Claude-Code-CLI/env-vars.md#features-that-need-feature-flag-fetching) is off, these calls run without a prompt. A `tabs_context_mcp` call also prompts when it sets `createIfEmpty`, and so does a `browser_batch` call that includes any of these actions.
[](#example-workflows)
Example workflows
These examples show common ways to combine browser actions with coding tasks. Run `/mcp`, select `claude-in-chrome`, then select **View tools** to see the full list of available browser tools.
[](#test-a-local-web-application)
Test a local web application
When developing a web app, ask Claude to verify your changes work correctly:
```python
I just updated the login form validation. Can you open localhost:3000,
try submitting the form with invalid data, and check if the error
messages appear correctly?
```
Claude navigates to your local server, interacts with the form, and reports what it observes.
[](#debug-with-console-logs)
Debug with console logs
Claude can read console output to help diagnose problems. Tell Claude what patterns to look for rather than asking for all console output, since logs can be verbose:
```python
Open the dashboard page and check the console for any errors when
the page loads.
```
Claude reads the console messages and can filter for specific patterns or error types.
[](#automate-form-filling)
Automate form filling
Speed up repetitive data entry tasks:
```python
I have a spreadsheet of customer contacts in contacts.csv. For each row,
go to the CRM at crm.example.com, click "Add Contact", and fill in the
name, email, and phone fields.
```
Claude reads your local file, navigates the web interface, and enters the data for each record.
[](#upload-files-to-web-pages)
Upload files to web pages
Claude can attach files from your machine to upload fields on a page. Claude Code reads the file and sends its contents to the browser, so uploads work in both local and remote sessions. This example attaches a log file to a form:
```python
Open the bug tracker at bugs.example.com, create a new issue,
and attach logs/session.log to it
```
If Claude refuses to attach a file or an upload fails, check for these causes:
- **Permissions**: Claude can upload a file only when the session is allowed to read it, so [permission rules](../02-Claude-Code-CLI/settings-reference.md#permission-settings) that deny `Read` access to a file also block uploading it.
- **Size**: a single upload can include up to 10 MB of files in total.
- **Hard links**: Claude refuses files that have multiple hard links, which is common inside package-manager stores like `node_modules`. Copy the file and upload the copy.
- **Credential names**: Claude refuses a file whose name or folder is one that credentials are kept under, such as `.env`, a `.pem` or `.key` file, or anything under `.ssh`. Requires Claude Code v2.1.293 or later.
[](#draft-content-in-google-docs)
Draft content in Google Docs
Use Claude to write directly in your documents without API setup:
```python
Draft a project update based on the recent commits and add it to my
Google Doc at docs.google.com/document/d/abc123
```
Claude opens the document, clicks into the editor, and types the content. This works with any web app you’re logged into: Gmail, Notion, Sheets, and more.
[](#extract-data-from-web-pages)
Extract data from web pages
Pull structured information from websites:
```python
Go to the product listings page and extract the name, price, and
availability for each item. Save the results as a CSV file.
```
Claude navigates to the page, reads the content, and compiles the data into a structured format.
[](#run-multi-site-workflows)
Run multi-site workflows
Coordinate tasks across multiple websites:
```python
Check my calendar for meetings tomorrow, then for each meeting with
an external attendee, look up their company website and add a note
about what they do.
```
Claude works across tabs to gather information and complete the workflow.
[](#record-a-demo-gif)
Record a demo GIF
Create shareable recordings of browser interactions:
```python
Record a GIF showing how to complete the checkout flow, from adding
an item to the cart through to the confirmation page.
```
Claude records the interaction sequence and saves it as a GIF file. The recording captures everything visible in the browser, including account details on logged-in pages, so review it before sharing it outside your team.
[](#save-screenshots-to-disk)
Save screenshots to disk
Ask Claude to keep a screenshot as a file:
```python
Take a screenshot of the checkout page and save it to disk
```
Claude saves the image to disk and reports the file path.
[](#troubleshooting)
Troubleshooting
[](#extension-not-detected)
Extension not detected
If Claude Code can’t detect the Chrome extension:
1. Verify the Chrome extension is installed and enabled in `chrome://extensions`
2. Verify Claude Code is up to date by running `claude --version`
3. Check that Chrome is running
4. Run `/chrome` and select “Reconnect extension” to re-establish the connection
5. If the issue persists, restart both Claude Code and Chrome
The first time you enable Chrome integration, Claude Code installs a native messaging host configuration file. Chrome reads this file on startup, so if the extension isn’t detected on your first attempt, restart Chrome to pick up the new configuration. Claude Code opens a browser tab prompting you to connect the extension only on that first install. Claude Code doesn’t reopen it when a later session rewrites the configuration file, for example after switching builds or config directories. If the connection still fails, verify the host configuration file exists at: For Chrome:
- **macOS**: `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`
- **Linux**: `~/.config/google-chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`
- **Windows**: check `HKCU\Software\Google\Chrome\NativeMessagingHosts\` in the Windows Registry
For Edge:
- **macOS**: `~/Library/Application Support/Microsoft Edge/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`
- **Linux**: `~/.config/microsoft-edge/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`
- **Windows**: check `HKCU\Software\Microsoft\Edge\NativeMessagingHosts\` in the Windows Registry
Other Chromium-based browsers read the same file from their own configuration directory, named after the browser. For example, Brave on macOS uses `~/Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts/`, and on Windows each browser has its own registry key, such as `HKCU\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\`.
[](#project-settings-can’t-turn-on-chrome)
Project settings can’t turn on Chrome
This warning in your terminal means the project you’re working in tried to turn on Chrome integration, and Claude Code didn’t allow it:
```python
Claude Code ignored CLAUDE_CODE_ENABLE_CFC in this project's settings: a project can't turn on Claude in Chrome. To turn it on yourself, run /chrome or start with --chrome.
```
The project’s `.claude/settings.json` or `.claude/settings.local.json` sets [`CLAUDE_CODE_ENABLE_CFC`](../02-Claude-Code-CLI/env-vars.md#variables) to `1` in its `env` block to turn Chrome integration on. Claude Code didn’t apply that setting, so Chrome integration is off in this session and Claude has no browser tools. Claude Code skips the setting because those files are stored in the project directory, and a repository you check out must not be able to connect Claude to your browser. You can keep working as you are. If you want browser tools, or want the warning gone, do one of these:
- **To get browser tools now**: exit and start again with `claude --chrome` in your shell.
- **To get browser tools in later sessions**: run `/chrome` at the Claude Code prompt and select [**Enabled by default**](#enable-chrome-by-default). This applies to sessions you start afterward, not the one that’s running.
- **To stop the warning without browser tools**: remove the `CLAUDE_CODE_ENABLE_CFC` line from the project’s settings file.
[](#browser-not-responding)
Browser not responding
If Claude’s browser commands stop working:
1. Check if a modal dialog (alert, confirm, prompt) is blocking the page. JavaScript dialogs block browser events and prevent Claude from receiving commands. Dismiss the dialog manually, then tell Claude to continue.
2. Ask Claude to create a new tab and try again
3. Restart the Chrome extension by disabling and re-enabling it in `chrome://extensions`
[](#connection-drops-during-long-sessions)
Connection drops during long sessions
The Chrome extension’s service worker can go idle during extended sessions, which breaks the connection. If browser tools stop working after a period of inactivity, run `/chrome` and select “Reconnect extension”. When you run `/chrome`, check its `Status` line. If it reads “Not connected”, the running session’s own connection to Chrome has failed. Select “Reconnect extension” to restart that connection. After the connection succeeds, the extension’s reconnect page opens in Chrome. Before v2.1.290, “Reconnect extension” only opened that page and didn’t restart a failed connection, so if browser tools don’t return on an earlier version, update Claude Code.
[](#extension-signed-in-to-a-different-organization)
Extension signed in to a different organization
If you belong to more than one claude.ai organization, the extension must be signed in to the same organization as Claude Code. If the two differ, Claude’s browser tools return “Browser extension is not connected”, even when both use the same claude.ai account. To see which organization Claude Code is signed in to, run [`/status`](../02-Claude-Code-CLI/commands.md) at the Claude Code prompt and read the `Organization` row.
If you log out of the extension, you lose the shortcuts and scheduled tasks saved in it. Try the other fixes under [Common error messages](#common-error-messages) first.
To change the extension’s organization, log out in the extension’s settings, then log in and select the organization that `/status` shows.
[](#windows-specific-issues)
Windows-specific issues
On Windows, you may encounter:
- **Named pipe conflicts (EADDRINUSE)**: if another process is using the same named pipe, restart Claude Code. Close any other Claude Code sessions that might be using Chrome.
- **Native messaging host errors**: if the native messaging host crashes on startup, try reinstalling Claude Code to regenerate the host configuration.
- **Setup pages fail to open**: update Claude Code. Before v2.1.211, the browser tab prompting you to connect the extension could fail to open on Windows.
[](#common-error-messages)
Common error messages
These are the most frequently encountered errors and how to resolve them:
| Error | Cause | Fix |
|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ”Browser extension is not connected” | The extension isn’t installed and running in Chrome, the extension is signed in to a different claude.ai account or organization than Claude Code, or your organization’s IP allowlist rejects the connection to `bridge.claudeusercontent.com` | Check that the extension is signed in to the same claude.ai account and [organization](#extension-signed-in-to-a-different-organization) as Claude Code, restart Chrome and Claude Code, then run `/chrome` to reconnect. If your organization uses IP allowlisting and the error persists, see [Organization IP allowlists and proxy egress](../13-Enterprise-Admin/network-config.md#organization-ip-allowlists-and-proxy-egress) |
| Extension shows “Not detected” in `/chrome` | Chrome extension is not installed or is disabled | Install or enable the extension in `chrome://extensions` |
| ”No tab available” | Claude tried to act before a tab was ready | Ask Claude to create a new tab and retry |
| ”Receiving end does not exist” | Extension service worker went idle | Run `/chrome` and select “Reconnect extension" |
| "No browsers are connected” | Chrome isn’t open with the extension signed in to the same claude.ai account and organization as Claude Code, or Claude Code can’t reach `bridge.claudeusercontent.com` | Confirm Chrome is open and the extension is signed in to the same claude.ai account and [organization](#extension-signed-in-to-a-different-organization) as Claude Code. If so, check that your network lets Claude Code reach `bridge.claudeusercontent.com`, listed under [Network access requirements](../13-Enterprise-Admin/network-config.md#network-access-requirements) |
[](#see-also)
See also
- [Computer use](../02-Claude-Code-CLI/computer-use.md): control native macOS apps when a task can’t be done in a browser
- [Use Claude Code in VS Code](vs-code.md#automate-browser-tasks-with-chrome): browser automation in the VS Code extension
- [CLI reference](../02-Claude-Code-CLI/cli-reference.md): command-line flags including `--chrome`
- [Common workflows](../02-Claude-Code-CLI/common-workflows.md): more ways to use Claude Code
- [Data and privacy](../13-Enterprise-Admin/data-usage.md): how Claude Code handles your data
- [Getting started with Claude in Chrome](https://support.claude.com/en/articles/12012173-getting-started-with-claude-in-chrome): full documentation for the Chrome extension, including shortcuts, scheduling, and permissions
---
## Claude in Chrome | Claude by Anthropic
Source: https://www.claude.com/claude-for-chrome
Path: 03-IDE-Integrations/claude-for-chrome.md
# Claude in Chrome
## A helping hand across all your tabs
Claude in Chrome reads the page you’re signed in to, then clicks, types, and fills forms while you decide what happens next.
[Add to Chrome (opens in new tab)](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn)
Available on all paid plans. Not on a paid plan? [Upgrade now](../17-Billing-Plans/pricing.md)
## A refreshing way to work on the web
No more copying, pasting, and switching tabs.
Claude Cowork
Claude Code
Everyday tools
Background tasks
### From browser research to finished deliverables
Pair Claude in Chrome with Claude Cowork to turn web research into polished content. Chrome navigates and gathers information, Claude Cowork produces Excel models, comparison decks, and reports without having to copy and paste.
### Works with Claude Code
Connect development workflows to Chrome for a partner that tests and iterates with you.
### Uses your everyday tools
Bring Claude into your workflow to make apps work better, without leaving the browser.
### Runs tasks in the background
Start a workflow and move on. Claude completes tasks while you focus elsewhere.
## Speed up everyday tasks with Claude in Chrome
### Pull metrics from analytics dashboards
Claude can navigate your analytics dashboard, extract the numbers you need, and compile them into a summary. No exports, no tab-switching, no manual copying.
[Learn more (opens in new tab)](https://academy.claude.com/use-cases/pull-metrics-from-analytics-dashboards)
### Organize files in Google Drive
Claude can sort through your Drive, create a folder structure, move files where they belong, and flag duplicates and old files for you to review. You approve the changes instead of doing the sorting yourself.
[Learn more (opens in new tab)](https://academy.claude.com/use-cases/organize-files-in-google-drive)
### Prepare and plan from your calendar
Claude can read your calendar, pull context from email threads, flag which meetings you need to prepare for, and book rooms if they’re missing. Run it every evening and start each day knowing what's coming.
[Learn more (opens in new tab)](https://academy.claude.com/use-cases/prepare-and-plan-from-your-calendar)
### Research competitors, get a comparison deck
Claude in Chrome visits competitor sites and pulls pricing, features, and positioning. Claude Cowork compiles everything into a formatted PowerPoint ready for your next strategy meeting.
[Learn more (opens in new tab)](https://academy.claude.com/use-cases/size-a-market-using-your-research)
### Log sales calls to your CRM
Claude can read your calendar, match attendees to Salesforce contacts, and draft activity logs for each call. You add notes and approve before anything gets created.
[Learn more (opens in new tab)](https://academy.claude.com/use-cases/log-sales-calls-to-your-crm)
### Clean up promotional emails
Claude can scan through your inbox, identify marketing emails, newsletters, and automated notifications, then present them as a list for you to review before deleting in bulk.
[Learn more (opens in new tab)](https://academy.claude.com/use-cases/clean-up-promotional-emails)
## Core capabilities
Reach the web that has no API
Access internal tools, legacy portals, admin consoles, and invoice systems. Claude works with the logins you have, on the tab in front of you. Drag more tabs into Claude’s tab group and Claude works across all of them.
Your whole setup, in the side panel
The side panel now runs a full [Claude Cowork](../15-Claude-AI-Features/product-cowork.md) session. The [skills](https://claude.com/skills), [plugins](../08-Plugins-Skills/claude-com-plugins.md), and [connectors](../04-API-Reference/Other/partners-mcp.md) you've already built are there, with nothing to set up in the browser.
### Your session follows you
Every conversation saves to your history. Sessions live with your account, not the machine, so you can start in Chrome and pick it up on desktop or mobile without needing to re-explain. A skill you save in the panel runs from any surface too.
### Three ways to access the extension
Access Claude in Chrome through the side panel when the work is on the page in front of you and nothing else needs to be open, in Claude Cowork when the browser is one step in a longer job, or in Claude Code when you’re building the site you’re testing.
## Stay in control
Hidden instructions on a page can try to redirect Claude’s actions. Though Claude in Chrome has built-in defenses that have been tested against real attacks, we recommend the habits below as a best practice.
[Read the safety blog (opens in new tab)](https://www.anthropic.com/news/prompt-injection-defenses)
### What we built
#### Automatically approve actions with guardrails
If you choose to, Claude can work through a task without asking you to approve each step. Before it acts on a page, a separate safety check reviews the action for risk and for instructions hidden by the site. It will surface to you if anything seems off.
#### Give permissions, site by site
If you prefer more control, switch to Permissions Mode. You grant access one site at a time.
#### Claude stops before taking sensitive actions
Purchases, financial actions, and other one-way doors wait for you.
#### Admins decide for the organization
On Team and Enterprise, admins turn the extension on or off org-wide and set site allowlists and blocklists.
Guide
Mitigating the risk of prompt injections in browser use
[Read more (opens in new tab)](../19-Reference/prompt-injection-defenses.md)
Guide
Using Claude in Chrome Safely
[Read more (opens in new tab)](https://support.claude.com/en/articles/12902428-using-claude-for-chrome-safely)
Guide
Claude in Chrome Permissions Guide
[Read more (opens in new tab)](https://support.claude.com/en/articles/12902446-claude-for-chrome-permissions-guide)
1 of 3
### What we recommend
#### Don’t use on sensitive workflows
Skip banking, health records, and anything with credentials you wouldn't share. Start with workflows you already know well.
#### Review Claude prompts
Claude asks before financial, personal, or work-critical actions. Review its prompts carefully.
#### Watch for unusual behavior
Some sites hide instructions that override yours. Our classifiers provide a defense, but if Claude acts unexpectedly, pause and review.
#### Tell us when something looks wrong
Report issues through the feedback options. It’s how we catch attacks we haven’t seen.
## FAQ
### How does Claude Cowork work with the Chrome extension?
Claude Cowork now includes its own built-in browser — nothing to install, and fully separate from your own browsing. If you're new to browser use, Claude uses the built-in browser by default. If you already use Claude in Chrome, that stays your default and Claude keeps working in your browser, where you're already signed in. Switch anytime in Settings → Cowork → Preferred browser.
### Can Enterprise plans enable Claude Cowork in the panel for Claude in Chrome?
Yes. [Learn how to set up in Enterprise plans](../13-Enterprise-Admin/claude-for-chrome-admin-controls.md).
### What browser activity is not recommended?
Avoid financial transactions, password management, or anything involving sensitive personal data. Start with trusted sites and familiar workflows where you're comfortable having Claude take actions. Make sure your use complies with our [acceptable use policy](../22-Safety-Policy/using-agents-according-to-our-usage-policy.md). [Learn more.](https://support.claude.com/en/articles/12902428-using-claude-for-chrome-safely)
### What are the security risks?
Browser AI faces unique security risks, like prompt injection attacks, where malicious actors might try to trick Claude into unintended actions, such as sharing your bank information or deleting important files. While we’ve implemented protections, they aren’t foolproof. Attack vectors are constantly evolving and Claude may hallucinate, leading to actions that you did not intend. We’ve shared our testing results, including possible attack scenarios, so you can make informed decisions, and strongly encourage you to [read about the risks (opens in new tab)](https://support.claude.com/en/articles/12902428-using-claude-for-chrome-safely) before using this product. [Read blog post. (opens in new tab)](../19-Reference/prompt-injection-defenses.md)
### What’s the difference between using Claude in Chrome alone vs. with Claude Cowork?
On its own, Claude in Chrome helps you navigate, extract information, and take actions in your browser. Paired with Claude Cowork, Chrome becomes the research layer for larger tasks. Claude gathers information from the web, then Claude Cowork produces finished files like Excel workbooks, PowerPoint decks, and formatted reports. Both remain available in Cowork. Claude uses the built-in browser by default unless you already use Claude in Chrome; you can pick your default in Settings → Cowork → Preferred browser.
Claude in Chrome Troubleshooting
This article helps you resolve common issues with Claude in Chrome and explains how to provide feedback.
[Read more (opens in new tab)](https://support.claude.com/en/articles/12902405-claude-for-chrome-troubleshooting)
Claude in Chrome Troubleshooting
This article helps you resolve common issues with Claude in Chrome and explains how to provide feedback.
[Read more (opens in new tab)](https://support.claude.com/en/articles/12902405-claude-for-chrome-troubleshooting)
Start on the page you’re already on
[Add to Chrome (opens in new tab)](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn)
This is a Google extension. The use of information received from Google APIs will adhere to the Chrome Web Store User Data Policy, including the Limited Use requirements.
[](https://www.claude.com/)
© 2026 Anthropic PBC
## Products
- [Claude](../15-Claude-AI-Features/product-overview.md)
- [Claude Code](../15-Claude-AI-Features/product-claude-code-fad1ab4b.md)
- [Claude Cowork](../15-Claude-AI-Features/product-cowork.md)
- [Claude Duet](../15-Claude-AI-Features/product-claude-duet.md)
- [Claude Tag](../15-Claude-AI-Features/product-tag.md)
- [Claude Science](../15-Claude-AI-Features/product-claude-science.md)
- [Claude Security](../15-Claude-AI-Features/product-claude-security.md)
- [Download app](https://www.claude.com/download)
- [Pricing](../17-Billing-Plans/pricing.md)
- [Log in](https://claude.ai/login)
## Capabilities
- [Artifacts](https://www.claude.com/features/artifacts)
- [Design](../15-Claude-AI-Features/product-design.md)
- [Connectors](https://www.claude.com/marketplace/connectors-plugins)
- [Plugins](https://www.claude.com/marketplace/plugins)
- [Skills](https://www.claude.com/skills)
## Extensions
- [Claude in Chrome](https://www.claude.com/claude-in-chrome)
- [Claude for Google Workspace](https://www.claude.com/claude-for-google-workspace)
- [Claude for Microsoft 365](https://www.claude.com/claude-for-microsoft-365)
## Models
- [Mythos (including Fable)](../15-Claude-AI-Features/claude-mythos.md)
- [Opus](../15-Claude-AI-Features/claude-opus.md)
- [Sonnet](../15-Claude-AI-Features/claude-sonnet.md)
- [Haiku](../15-Claude-AI-Features/claude-haiku.md)
## Enterprise
- [Overview](../17-Billing-Plans/pricing-enterprise.md)
- [Claude Code for Enterprise](../15-Claude-AI-Features/product-claude-code-enterprise.md)
## Departments
- [Customer support](../18-Industry-UseCases/customer-support.md)
- [Cybersecurity](../18-Industry-UseCases/cybersecurity.md)
- [Legal](../18-Industry-UseCases/legal.md)
- [Sales](../18-Industry-UseCases/sales.md)
## Industries
- [Financial advisors](../18-Industry-UseCases/financial-advisors.md)
- [Financial services](../18-Industry-UseCases/finance.md)
- [Government](../18-Industry-UseCases/government.md)
- [Healthcare](../18-Industry-UseCases/healthcare.md)
- [Higher education](../18-Industry-UseCases/education.md)
- [K-12 teachers](../18-Industry-UseCases/teachers.md)
- [Life sciences](../18-Industry-UseCases/life-sciences.md)
- [Nonprofits](../18-Industry-UseCases/nonprofits.md)
- [Small business](../18-Industry-UseCases/small-business.md)
## Programs
- [Campus](../15-Claude-AI-Features/programs-campus.md)
- [Frontier Academy](../15-Claude-AI-Features/programs-frontier-academy.md)
- [Scientists](../15-Claude-AI-Features/programs-team-plan-for-scientists.md)
- [Startups](../15-Claude-AI-Features/programs-startups.md)
## Developers
- [Developer docs](../02-Claude-Code-CLI/code-home.md)
- [Developer blog](https://claude.dev)
- [Community](https://www.claude.com/community)
- [Console](../04-API-Reference/Other/home.md)
- [Engineering at Anthropic](https://www.anthropic.com/engineering)
## Platform
- [Overview](https://www.claude.com/platform/api)
- [Marketplace](https://www.claude.com/marketplace)
- [Claude on AWS](../04-API-Reference/Other/partners-claude-on-aws.md)
- [Google Cloud](../04-API-Reference/Other/partners-google-cloud.md)
- [Microsoft Foundry](../04-API-Reference/Other/partners-microsoft-foundry.md)
- [Managed Agents](https://www.claude.com/platform/claude-managed-agents)
## Resources
- [Overview](https://www.claude.com/resources)
- [Articles](https://www.claude.com/resources/articles)
- [Webinars](https://www.claude.com/resources/webinars)
- [Claude partner network](../04-API-Reference/Other/partners.md)
- [Claude Academy](https://academy.claude.com/)
- [Customer stories](../18-Industry-UseCases/customers.md)
- [Events](https://www.anthropic.com/events)
- [Powered by Claude](../04-API-Reference/Other/partners-powered-by-claude.md)
- [Service partners](https://www.claude.com/marketplace/service-partners)
## Help and security
- [Availability](https://www.anthropic.com/legal/supported-regions)
- [Check files](https://www.claude.com/check-files)
- [Regional compliance](https://www.claude.com/regional-compliance)
- [Report abuse](https://www.claude.com/form/anthropic-content-reporting)
- [Security and compliance](https://trust.anthropic.com/)
- [Status](https://status.anthropic.com/)
- [Support center](https://support.claude.com/en/)
## Company
- [Anthropic](https://www.anthropic.com/)
- [Careers](https://www.anthropic.com/careers)
- [Policy](https://www.anthropic.com/policy)
- [Research](../19-Reference/anthropic-com-research.md)
- [Anthropic news](../19-Reference/news.md)
- [Policy on the AI Exponential](https://www.anthropic.com/policy-on-the-ai-exponential)
- [Responsible Scaling Policy](../19-Reference/announcing-our-updated-responsible-scaling-policy.md)
- [Transparency](https://anthropic.com/transparency)
## Terms and policies
- Privacy choices
- [Privacy policy](https://www.anthropic.com/legal/privacy)
- [Responsible disclosure policy](https://www.anthropic.com/responsible-disclosure-policy)
- [Terms of service: Commercial](https://www.anthropic.com/legal/commercial-terms)
- [Terms of service: Consumer](https://www.anthropic.com/legal/consumer-terms)
- [Terms of Service: US K-12](https://anthropic.com/legal/k12-terms)
- [Data Processing Agreement: US K-12](https://anthropic.com/legal/k12-dpa)
- [Usage Policy](https://www.anthropic.com/legal/aup)
## Products
- [Claude](../15-Claude-AI-Features/product-overview.md)
- [Claude Code](../15-Claude-AI-Features/product-claude-code-fad1ab4b.md)
- [Claude Cowork](../15-Claude-AI-Features/product-cowork.md)
- [Claude Duet](../15-Claude-AI-Features/product-claude-duet.md)
- [Claude Tag](../15-Claude-AI-Features/product-tag.md)
- [Claude Science](../15-Claude-AI-Features/product-claude-science.md)
- [Claude Security](../15-Claude-AI-Features/product-claude-security.md)
- [Download app](https://www.claude.com/download)
- [Pricing](../17-Billing-Plans/pricing.md)
- [Log in](https://claude.ai/login)
## Capabilities
- [Artifacts](https://www.claude.com/features/artifacts)
- [Design](../15-Claude-AI-Features/product-design.md)
- [Connectors](https://www.claude.com/marketplace/connectors-plugins)
- [Plugins](https://www.claude.com/marketplace/plugins)
- [Skills](https://www.claude.com/skills)
## Extensions
- [Claude in Chrome](https://www.claude.com/claude-in-chrome)
- [Claude for Google Workspace](https://www.claude.com/claude-for-google-workspace)
- [Claude for Microsoft 365](https://www.claude.com/claude-for-microsoft-365)
## Models
- [Mythos (including Fable)](../15-Claude-AI-Features/claude-mythos.md)
- [Opus](../15-Claude-AI-Features/claude-opus.md)
- [Sonnet](../15-Claude-AI-Features/claude-sonnet.md)
- [Haiku](../15-Claude-AI-Features/claude-haiku.md)
## Enterprise
- [Overview](../17-Billing-Plans/pricing-enterprise.md)
- [Claude Code for Enterprise](../15-Claude-AI-Features/product-claude-code-enterprise.md)
## Departments
- [Customer support](../18-Industry-UseCases/customer-support.md)
- [Cybersecurity](../18-Industry-UseCases/cybersecurity.md)
- [Legal](../18-Industry-UseCases/legal.md)
- [Sales](../18-Industry-UseCases/sales.md)
## Industries
- [Financial advisors](../18-Industry-UseCases/financial-advisors.md)
- [Financial services](../18-Industry-UseCases/finance.md)
- [Government](../18-Industry-UseCases/government.md)
- [Healthcare](../18-Industry-UseCases/healthcare.md)
- [Higher education](../18-Industry-UseCases/education.md)
- [K-12 teachers](../18-Industry-UseCases/teachers.md)
- [Life sciences](../18-Industry-UseCases/life-sciences.md)
- [Nonprofits](../18-Industry-UseCases/nonprofits.md)
- [Small business](../18-Industry-UseCases/small-business.md)
## Programs
- [Campus](../15-Claude-AI-Features/programs-campus.md)
- [Frontier Academy](../15-Claude-AI-Features/programs-frontier-academy.md)
- [Scientists](../15-Claude-AI-Features/programs-team-plan-for-scientists.md)
- [Startups](../15-Claude-AI-Features/programs-startups.md)
## Developers
- [Developer docs](../02-Claude-Code-CLI/code-home.md)
- [Developer blog](https://claude.dev)
- [Community](https://www.claude.com/community)
- [Console](../04-API-Reference/Other/home.md)
- [Engineering at Anthropic](https://www.anthropic.com/engineering)
## Platform
- [Overview](https://www.claude.com/platform/api)
- [Marketplace](https://www.claude.com/marketplace)
- [Claude on AWS](../04-API-Reference/Other/partners-claude-on-aws.md)
- [Google Cloud](../04-API-Reference/Other/partners-google-cloud.md)
- [Microsoft Foundry](../04-API-Reference/Other/partners-microsoft-foundry.md)
- [Managed Agents](https://www.claude.com/platform/claude-managed-agents)
## Resources
- [Overview](https://www.claude.com/resources)
- [Articles](https://www.claude.com/resources/articles)
- [Webinars](https://www.claude.com/resources/webinars)
- [Claude partner network](../04-API-Reference/Other/partners.md)
- [Claude Academy](https://academy.claude.com/)
- [Customer stories](../18-Industry-UseCases/customers.md)
- [Events](https://www.anthropic.com/events)
- [Powered by Claude](../04-API-Reference/Other/partners-powered-by-claude.md)
- [Service partners](https://www.claude.com/marketplace/service-partners)
## Help and security
- [Availability](https://www.anthropic.com/legal/supported-regions)
- [Check files](https://www.claude.com/check-files)
- [Regional compliance](https://www.claude.com/regional-compliance)
- [Report abuse](https://www.claude.com/form/anthropic-content-reporting)
---
## JetBrains IDEs - Claude Code Docs
Source: https://code.claude.com/docs/en/jetbrains
Path: 03-IDE-Integrations/jetbrains.md
## On this page
- [Supported IDEs](#supported-ides)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Run Claude Code from your IDE](#run-claude-code-from-your-ide)
- [Connect from an external terminal](#connect-from-an-external-terminal)
- [Configuration](#configuration)
- [Claude Code settings](#claude-code-settings)
- [Plugin settings](#plugin-settings)
- [General settings](#general-settings)
- [ESC key configuration](#esc-key-configuration)
- [Special configurations](#special-configurations)
- [Remote development](#remote-development)
- [WSL configuration](#wsl-configuration)
- [Allow WSL2 traffic through Windows Firewall](#allow-wsl2-traffic-through-windows-firewall)
- [Switch WSL2 to mirrored networking](#switch-wsl2-to-mirrored-networking)
- [Troubleshooting](#troubleshooting)
- [Plugin not working](#plugin-not-working)
- [IDE not detected](#ide-not-detected)
- [Command not found](#command-not-found)
- [Security considerations](#security-considerations)
- [The built-in IDE MCP server](#the-built-in-ide-mcp-server)
Platforms and integrations
# JetBrains IDEs
Copy pageCopy page
Use Claude Code with JetBrains IDEs including IntelliJ, PyCharm, WebStorm, and more
Copy pageCopy page
Claude Code integrates with JetBrains IDEs through a dedicated plugin, providing features like interactive diff viewing, selection context sharing, and more.
[](#supported-ides)
Supported IDEs
The Claude Code plugin works with most JetBrains IDEs, including:
- IntelliJ IDEA
- PyCharm
- Android Studio
- WebStorm
- PhpStorm
- GoLand
[](#features)
Features
- **Quick launch**: use `Cmd+Esc` (Mac) or `Ctrl+Esc` (Windows/Linux) to open Claude Code directly from your editor, or click the Claude Code button in the UI
- **Diff viewing**: Claude Code opens code changes in the IDE diff viewer instead of the terminal; change this with the **Diff tool** setting in `/config`
- **Selection context**: the current selection or tab in the IDE is automatically shared with Claude Code. [`Read` deny rules](../02-Claude-Code-CLI/permissions.md#read-and-edit) block this sharing for matching files
- **File reference shortcuts**: use `Cmd+Option+K` (Mac) or `Alt+Ctrl+K` (Linux/Windows) to insert file references such as `@src/auth.ts#L1-99`
- **Diagnostic sharing**: Claude reads the IDE’s inspection diagnostics, such as lint and syntax errors, by calling the [`getDiagnostics` tool](#the-built-in-ide-mcp-server); Claude Code doesn’t request diagnostics from the plugin on its own after edits
[](#installation)
Installation
The plugin runs the `claude` command in your IDE’s integrated terminal and connects to it. It does not bundle its own copy of the CLI, so install both pieces:
1
Install the Claude Code CLI
Follow the [quickstart](../01-Getting-Started/quickstart.md) to install the CLI if you haven’t already. The plugin shows a “Cannot launch Claude Code” notification when `claude` isn’t on your PATH.
2
Install the JetBrains plugin
Install the [Claude Code plugin](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) from the JetBrains Marketplace and restart your IDE.
If `claude` is installed somewhere your IDE can’t find, set the full path in the plugin’s [Claude command setting](#general-settings). Claude Code works with any paid Claude subscription (Pro, Max, Team, or Enterprise) or a Claude Console account, and no API key is required. You’ll be prompted to [log in](../02-Claude-Code-CLI/authentication.md#log-in-to-claude-code) the first time you run `claude`.
[](#usage)
Usage
[](#run-claude-code-from-your-ide)
Run Claude Code from your IDE
Run `claude` from your IDE’s integrated terminal, and all integration features will be active.
[](#connect-from-an-external-terminal)
Connect from an external terminal
Use the `/ide` command in any external terminal to connect Claude Code to your JetBrains IDE and activate all features:
```python
claude
```
```python
/ide
```
When the connection succeeds, Claude Code confirms with a message like `Connected to IntelliJ IDEA.` If Claude Code detects a running IDE that doesn’t have the plugin, `/ide` installs the plugin for you and asks you to restart the IDE. If you want Claude to have access to the same files as your IDE, start Claude Code from the same directory as your IDE project root.
[](#configuration)
Configuration
[](#claude-code-settings)
Claude Code settings
Configure IDE integration through Claude Code’s settings:
1. Run `claude`
2. Enter the `/config` command
3. Set **Diff tool** to `auto` to show diffs in the IDE, or `terminal` to keep them in the terminal
The **Diff tool** entry appears in `/config` only when Claude Code is connected to the IDE, so run `claude` from the JetBrains terminal or run [`/ide`](../02-Claude-Code-CLI/commands.md) first from an external terminal. See [`diffTool`](../02-Claude-Code-CLI/settings-reference.md#difftool) for the underlying setting.
[](#plugin-settings)
Plugin settings
Configure the Claude Code plugin by going to **Settings → Tools → Claude Code \[Beta\]**:
[](#general-settings)
General settings
- **Claude command**: specify a custom command to run Claude, for example `claude`, `/usr/local/bin/claude`, or `npx @anthropic-ai/claude-code`
- **Suppress notification for when Claude Command is not found**: skip notifications about not finding the Claude command
- **Enable using Option+Enter for multi-line prompts**: on macOS only. When enabled, Option+Enter inserts new lines in Claude Code prompts. Disable if the Option key is being captured unexpectedly. Requires a terminal restart.
- **Enable automatic updates**: automatically check for and install plugin updates, applied on restart
For WSL users: Set `wsl -d Ubuntu -- bash -lic "claude"` as your Claude command (replace `Ubuntu` with your WSL distribution name)
[](#esc-key-configuration)
ESC key configuration
If the ESC key doesn’t interrupt Claude Code operations in JetBrains terminals:
1. Go to **Settings → Tools → Terminal**
2. Either:
- Uncheck “Move focus to the editor with Escape”, or
- Click “Configure terminal keybindings” and delete the “Switch focus to Editor” shortcut
3. Apply the changes
This allows the ESC key to properly interrupt Claude Code operations.
[](#special-configurations)
Special configurations
[](#remote-development)
Remote development
When using JetBrains Remote Development, you must install the plugin on the remote host via **Settings → Plugin (Host)**, not on your local client machine.
[](#wsl-configuration)
WSL configuration
If you’re using Claude Code on WSL2 with a JetBrains IDE and see “No available IDEs detected”, the cause is usually WSL2’s NAT networking or Windows Firewall blocking the connection between WSL2 and the IDE running on the Windows host. WSL1 uses the host’s network directly and isn’t affected.
[](#allow-wsl2-traffic-through-windows-firewall)
Allow WSL2 traffic through Windows Firewall
This is the recommended fix because it keeps your existing WSL2 networking mode.
1
Find your WSL2 IP address
From inside your WSL shell, run:
```python
hostname -I
```
Note your subnet: take the first two segments of the address and follow them with `.0.0/16`. For example, if the address is `172.21.123.45`, your subnet is `172.21.0.0/16`.
2
Create a firewall rule
Open PowerShell as Administrator and run the following, adjusting the IP range to match your subnet:
```python
New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
```
3
Restart your IDE and Claude Code
Close and reopen both so the new rule takes effect.
[](#switch-wsl2-to-mirrored-networking)
Switch WSL2 to mirrored networking
Mirrored networking requires Windows 11 22H2 or later. If you’re on Windows 10, use the firewall rule above instead. Add this to `.wslconfig` in your Windows user directory:
```python
[wsl2]
networkingMode=mirrored
```
Then restart WSL with `wsl --shutdown` from PowerShell.
[](#troubleshooting)
Troubleshooting
[](#plugin-not-working)
Plugin not working
If the plugin is installed but Claude Code features don’t appear in your IDE:
- Ensure you’re running Claude Code from the project root directory
- Check that the JetBrains plugin is enabled in the IDE settings
- Completely restart the IDE (you may need to do this multiple times)
- For Remote Development, ensure the plugin is installed in the remote host
[](#ide-not-detected)
IDE not detected
If the `/ide` command shows “No available IDEs detected”:
- Verify the plugin is installed and enabled
- Restart the IDE completely
- If you expected an automatic connection without running `/ide`, check that you launched `claude` from the IDE’s integrated terminal
- For WSL users, see [WSL configuration](#wsl-configuration) above
[](#command-not-found)
Command not found
If clicking the Claude icon shows “command not found”:
1. Verify Claude Code is installed by running `claude --version` in a terminal
2. Configure the Claude command path in plugin settings
3. For WSL users, use the WSL command format mentioned in the configuration section
[](#security-considerations)
Security considerations
When Claude Code runs in a JetBrains IDE in [`acceptEdits` permission mode](../02-Claude-Code-CLI/permission-modes.md#auto-approve-file-edits-with-acceptedits-mode), 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 `acceptEdits` mode and allow bypassing Claude Code’s permission prompts for Bash execution. When running in JetBrains IDEs, consider:
- Using Manual mode for edits, because `acceptEdits` and auto mode both approve edits inside your working directory without asking, except in [protected paths](../02-Claude-Code-CLI/permission-modes.md#protected-paths)
- Taking extra care to ensure Claude is only used with trusted prompts
- Being aware of which files Claude Code has access to modify
For Claude Code installation or login problems outside the IDE, see [Troubleshoot installation and login](../02-Claude-Code-CLI/troubleshoot-install.md).
[](#the-built-in-ide-mcp-server)
The built-in IDE MCP server
When the plugin is active, it runs a local MCP server that the CLI connects to automatically. This is how the CLI opens diffs in the IDE’s native diff viewer, reads your current selection for `@`-mentions, and lets Claude read inspection diagnostics. The server is named `ide` and is hidden from `/mcp` because there’s nothing to configure. If your organization uses a [`PreToolUse` hook](../07-Hooks/hooks.md#pretooluse) to allowlist MCP tools, though, you’ll need to know it exists. **Selection and open-file context.** While connected, the CLI includes your current editor selection and the path of the active file as context on each prompt you send. The transcript shows a `⧉ Selected N lines from <file>` line when this happens. If you [queue a message while Claude works](../02-Claude-Code-CLI/interactive-mode.md#queue-messages-while-claude-works), it keeps the selection you had when you pressed `Enter`, whatever you select afterward. To exclude a sensitive file such as `.env`, add a [`Read` deny rule](../02-Claude-Code-CLI/permissions.md#read-and-edit) for its path. A matching deny rule prevents both the selected text and the open-file notice for that file from reaching Claude. **Transport and authentication.** The server listens on an OS-assigned ephemeral port, and the port is not configurable. The transport is unencrypted `ws://`; on loopback, any process that could capture the traffic can also read the token from the lock file, so TLS would not add protection against a local attacker. Each IDE start generates a fresh random auth token, writes it to a lock file at `~/.claude/ide/<port>.lock`, and the CLI must present it as the `X-Claude-Code-Ide-Authorization` header to connect. If `CLAUDE_CONFIG_DIR` is set, the lock file is written to `$CLAUDE_CONFIG_DIR/ide/` instead. **Tools exposed to the model.** The server hosts several tools, but only one is visible to the model. The rest are internal RPC the CLI uses for its own UI, such as opening diffs and reading selections, and are filtered out before the tool list reaches Claude.
| Tool name (as seen by hooks) | What it does | Read-only |
|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
| `mcp__ide__getDiagnostics` | Returns the IDE’s inspection diagnostics, the errors and warnings shown in the editor. Each call covers one file: the file Claude specifies, or the file in your active editor if Claude doesn’t specify one. | Yes |
The JetBrains plugin does not expose a code-execution tool to the model. **Listening interface.** Which network interface the server binds to is controlled by **Accept connections from all network interfaces** under **Settings → Tools → Claude Code \[Beta\] → Networking (Advanced)**. With the setting disabled, the server listens on `127.0.0.1` only and is not reachable from other hosts. With it enabled, the port is reachable from your local network. The setting exists for cases where the CLI cannot reach the IDE over loopback, such as WSL2 with default NAT networking or a remote-IDE setup; see [WSL configuration](#wsl-configuration) for that scenario.
Enabling **Accept connections from all network interfaces** makes the IDE MCP port reachable from your local network. Connections still require the auth token from the lock file, but because the transport is unencrypted `ws://`, both the session traffic and that token cross the network in cleartext when the setting is on. Only turn it on when loopback can’t work. For WSL2, prefer [mirrored networking](#switch-wsl2-to-mirrored-networking) so the Windows loopback interface is shared with the Linux VM and the socket can stay on loopback.
---
## Use Claude Code in VS Code - Claude Code Docs
Source: https://code.claude.com/docs/en/vs-code
Path: 03-IDE-Integrations/vs-code.md
## On this page
- [Prerequisites](#prerequisites)
- [Install the extension](#install-the-extension)
- [Get started](#get-started)
- [Use the prompt box](#use-the-prompt-box)
- [Reference files and folders](#reference-files-and-folders)
- [Include terminal output in prompts](#include-terminal-output-in-prompts)
- [Paste text](#paste-text)
- [LaTeX math in responses](#latex-math-in-responses)
- [Resume past conversations](#resume-past-conversations)
- [The conversation is still open somewhere else](#the-conversation-is-still-open-somewhere-else)
- [Resume cloud sessions from claude.ai](#resume-cloud-sessions-from-claude-ai)
- [Check account and usage](#check-account-and-usage)
- [Rewind with checkpoints](#rewind-with-checkpoints)
- [Customize your workflow](#customize-your-workflow)
- [Choose where Claude lives](#choose-where-claude-lives)
- [Continue conversations after a reload](#continue-conversations-after-a-reload)
- [Interrupted steps after a reload](#interrupted-steps-after-a-reload)
- [Turn off continuation after a reload](#turn-off-continuation-after-a-reload)
- [A conversation was not reopened](#a-conversation-was-not-reopened)
- [Run multiple conversations](#run-multiple-conversations)
- [Organize sessions into groups](#organize-sessions-into-groups)
- [Filter the sessions list](#filter-the-sessions-list)
- [Switch to terminal mode](#switch-to-terminal-mode)
- [Manage plugins](#manage-plugins)
- [Install plugins](#install-plugins)
- [Uninstall plugins](#uninstall-plugins)
- [Share a plugin install link](#share-a-plugin-install-link)
- [Manage marketplaces](#manage-marketplaces)
- [Plugins that draw in the panel](#plugins-that-draw-in-the-panel)
- [Automate browser tasks with Chrome](#automate-browser-tasks-with-chrome)
- [Work with git](#work-with-git)
- [Create commits and pull requests](#create-commits-and-pull-requests)
- [Run work in the background](#run-work-in-the-background)
- [Move a running command or subagent to the background](#move-a-running-command-or-subagent-to-the-background)
- [The Run in background action is missing under a subagent](#the-run-in-background-action-is-missing-under-a-subagent)
- [Monitor background processes](#monitor-background-processes)
- [See a background subagent’s tool calls](#see-a-background-subagent%E2%80%99s-tool-calls)
- [VS Code commands and shortcuts](#vs-code-commands-and-shortcuts)
- [Launch a VS Code tab from other tools](#launch-a-vs-code-tab-from-other-tools)
- [Configure settings](#configure-settings)
- [Extension settings](#extension-settings)
- [Use third-party providers](#use-third-party-providers)
- [Use a screen reader](#use-a-screen-reader)
- [Use the chat panel from the keyboard](#use-the-chat-panel-from-the-keyboard)
- [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli)
- [Run CLI in VS Code](#run-cli-in-vs-code)
- [Switch between extension and CLI](#switch-between-extension-and-cli)
- [Connect to external tools with MCP](#connect-to-external-tools-with-mcp)
- [The built-in IDE MCP server](#the-built-in-ide-mcp-server)
- [Fix common issues](#fix-common-issues)
- [Extension won’t install](#extension-won%E2%80%99t-install)
- [Spark icon not visible](#spark-icon-not-visible)
- [Cmd+Esc does nothing on macOS](#cmd%2Besc-does-nothing-on-macos)
- [Ctrl+J adds a new line in the prompt box](#ctrl%2Bj-adds-a-new-line-in-the-prompt-box)
- [The Claude Code panel is blank or couldn’t load](#the-claude-code-panel-is-blank-or-couldn%E2%80%99t-load)
- [A resumed conversation is blank at first](#a-resumed-conversation-is-blank-at-first)
- [The panel stops responding each time a reload reopens a conversation](#the-panel-stops-responding-each-time-a-reload-reopens-a-conversation)
- [A formula shows as raw LaTeX](#a-formula-shows-as-raw-latex)
- [Dictation or the Web tab fails behind a TLS-inspecting proxy](#dictation-or-the-web-tab-fails-behind-a-tls-inspecting-proxy)
- [Claude Code never responds](#claude-code-never-responds)
- [Uninstall the extension](#uninstall-the-extension)
- [Next steps](#next-steps)
Platforms and integrations
# Use Claude Code in VS Code
Copy pageCopy page
Install and configure the Claude Code extension for VS Code. Get AI coding assistance with inline diffs, @-mentions, plan review, and keyboard shortcuts.
Copy pageCopy page
The 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. With 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
- Open multiple conversations in separate tabs or windows
[](#prerequisites)
Prerequisites
Before installing, make sure you have:
- VS Code 1.94.0 or later
- An Anthropic account: any paid Claude subscription (Pro, Max, Team, or Enterprise) or a Claude Console account works, and no API key is required. You’ll [sign in](../02-Claude-Code-CLI/authentication.md#log-in-to-claude-code) with this account when you first open the extension. If you access Claude through a third-party provider like Amazon Bedrock or Google Cloud’s Agent Platform, see [Use third-party providers](#use-third-party-providers) for setup instructions.
The extension bundles its own copy of the CLI (command-line interface) for the chat panel. To run `claude` in VS Code’s integrated terminal, you also need the [standalone CLI install](../01-Getting-Started/setup.md). See [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) for details.
[](#install-the-extension)
Install the extension
Click the link for your IDE to install directly:
- [Install for VS Code](vscode:extension/anthropic.claude-code)
- [Install for Cursor](cursor:extension/anthropic.claude-code)
Or 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**. The extension’s version number is the Claude Code version it bundles. For example, a feature that requires Claude Code v2.1.286 or later needs version 2.1.286 or later of the extension, which the Extensions view shows. Claude Code also runs in other editors and containers:
- **Other VS Code forks**: the extension also installs in forks like Devin Desktop or Kiro. Search for “Claude Code” in the editor’s Extensions view, or install from the [Open VSX registry](https://open-vsx.org/extension/Anthropic/claude-code).
- **Editors that can’t install the extension**: [install the CLI](../01-Getting-Started/quickstart.md) and run `claude` in the editor’s integrated terminal instead. The CLI works in any terminal.
- **Dev containers**: to run Claude Code inside a dev container, see [Development containers](../02-Claude-Code-CLI/devcontainer.md).
If the extension doesn’t appear after installation, restart VS Code or run “Developer: Reload Window” from the Command Palette.
[](#get-started)
Get started
Once installed, you can start using Claude Code through the VS Code interface:
1
Open the Claude Code panel
Throughout VS Code, the Spark icon indicates Claude Code:
The quickest way to open Claude is to click the Spark icon in the **Editor Toolbar** (top-right corner of the editor). The icon only appears when you have a file open.
Other ways to open Claude Code:
- **Activity Bar**: click the Spark icon in the left sidebar to open the sessions list. Click any session to open it in your [preferred location](#extension-settings), or start a new one. This icon is always visible in the Activity Bar.
- **Command Palette**: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux), type “Claude Code”, and select an option like “Open in New Tab”
- **Status Bar**: click **✻ Claude Code** in the bottom-right corner of the window. This works even when no file is open.
You can drag the Claude panel to reposition it anywhere in VS Code. See [Customize your workflow](#customize-your-workflow) for details.
2
Sign in
The first time you open the panel, a sign-in screen appears. Click **Sign in** and complete authorization in your browser.If you see **Not logged in · Please run /login** later, the extension reopens the sign-in screen automatically. If it doesn’t appear, reload the window from the Command Palette with **Developer: Reload Window**.If you have `ANTHROPIC_API_KEY` set in your shell but still see the sign-in prompt, VS Code may not have inherited your shell environment. Launch VS Code from a terminal with `code .` so it inherits your environment variables, or sign in with your Claude account instead.After you sign in, a **Learn Claude Code** checklist appears. Work through each item by clicking **Show me**, or dismiss it with the X. To reopen it later, uncheck **Hide Onboarding** in VS Code settings under **Extensions \> Claude Code**.
3
Send a prompt
Ask Claude to help with your code or files, whether that’s explaining how something works, debugging an issue, or making changes.
Claude automatically sees your selected text. Press `Option+K` (Mac) / `Alt+K` (Windows/Linux) to also insert an @-mention reference (like `@file.ts#5-10`) into your prompt.
Here’s an example of asking about a particular line in a file:
4
Review changes
Check the [permission mode](../02-Claude-Code-CLI/permission-modes.md#which-mode-a-session-starts-in) shown at the bottom of the prompt box:
- In Auto or Edit automatically mode, Claude edits [most files](../02-Claude-Code-CLI/permission-modes.md#protected-paths) in your workspace without asking.
- In Manual mode, when Claude wants to edit a file, it shows a side-by-side comparison of the original and proposed changes, then asks for permission. You can accept, reject, or tell Claude what to do instead. If you edit the proposed content directly in the diff view before accepting, Claude is told that you modified it so it doesn’t assume the file matches its original proposal.
To review a proposed edit one change at a time, use the **Accept this change** and **Reject this change** buttons under each change in the diff. Rejecting a change reverts it in the proposed content; accepting marks it as reviewed. Per-change review requires Claude Code v2.1.275 or later.Accepting or rejecting the whole file still finishes the review. A diff with more than 100 changes opens without the per-change buttons, so review it as a whole file.The same actions are available at the cursor from the editor’s context menu and from the Command Palette as **Claude Code: Accept Change at Cursor** and **Claude Code: Reject Change at Cursor**.
For more ideas on what you can do with Claude Code, see [Common workflows](../02-Claude-Code-CLI/common-workflows.md).
Run “Claude Code: Open Walkthrough” from the Command Palette for a guided tour of the basics.
[](#use-the-prompt-box)
Use the prompt box
The prompt box supports several features:
- **Permission modes**: click the mode indicator at the bottom of the prompt box to switch permission modes. With Claude Code v2.1.283 or later, Auto is the built-in starting permission mode, and on earlier versions only on Pro, Max, and Team plans. See [how the extension chooses the starting permission mode](../02-Claude-Code-CLI/permission-modes.md#switch-permission-modes) for what changes that, and every permission mode the indicator offers.
- **Auto**: a classifier reviews most actions instead of asking you. See [auto mode](../02-Claude-Code-CLI/permission-modes.md#eliminate-prompts-with-auto-mode) for what it reviews and blocks.
- **Manual**: Claude asks permission before file edits and most shell commands.
- **Plan**: Claude describes what it will do and waits for approval before making changes. VS Code automatically opens the plan as a full Markdown document where you can add inline comments to give feedback before Claude begins. You can also type `/plan` in the prompt box. Requires Claude Code v2.1.280 or later.
- `/plan`: switches to plan mode. If you’re already in plan mode, shows the current plan instead.
- `/plan` with a task, such as `/plan fix the auth bug`: switches to plan mode and starts planning that task.
- `/plan open`: when you’re already in plan mode, opens the plan file in the editor.
- **Edit automatically**: Claude makes edits without asking.
- **Model**: select **Switch model…** from the command menu to change the model mid-session. You can also click the model name at the bottom of the prompt box to open the same picker. With Claude Code v2.1.284 or later, typing `/model` on its own in the prompt box opens the picker too. When the current model supports [effort levels](../02-Claude-Code-CLI/model-config.md#adjust-effort-level), the picker also shows an **Effort** row and the model name button shows the selected level. When you pick a level other than `max`, Claude Code saves it for the current model as your default, under [`modelSettings`](../02-Claude-Code-CLI/settings-reference.md#modelsettings) in your user settings; `max` applies to the current session only. The model name button and the **Effort** row require Claude Code v2.1.257 or later. When [dynamic workflows](../02-Claude-Code-CLI/workflows.md) are enabled and the current model supports it, an **Ultracode** switch appears under the **Effort** row. Turn it on to have Claude plan a [workflow](../02-Claude-Code-CLI/workflows.md#let-claude-decide-with-ultracode) for each substantive task in this session, at the selected effort level. While it’s on, the model name button shows `· Ultracode` after the level. The switch requires Claude Code v2.1.284 or later.
- **Command menu**: click `/` or type `/` to open the command menu. Options include attaching files, switching models, and toggling extended thinking. The Customize section includes entries such as MCP servers, commands, output styles, hooks, memory, instructions, permissions, and plugins. Items with a terminal icon open in the integrated terminal.
- To browse commands such as `/usage` or [`/remote-control`](../02-Claude-Code-CLI/remote-control.md), select **Slash commands** in the Customize section. A dialog lists them with a filter box. Pick one to run it. Typing `/` in the prompt box still suggests commands inline. Requires Claude Code v2.1.257 or later. Typing `/skills` also opens this dialog. Each [skill](../08-Plugins-Skills/skills.md) row shows its [visibility](../08-Plugins-Skills/skills.md#override-skill-visibility-from-settings), such as **On** or **Name only**. Click the visibility to change it, except on rows marked **locked**, such as plugin skills. The `/skills` shortcut and the visibility controls require Claude Code v2.1.280 or later.
- Select **Output styles** in the Customize section to pick an [output style](../02-Claude-Code-CLI/output-styles.md), including your custom styles. Requires Claude Code v2.1.257 or later. To create a custom style instead, select **Build a custom style** from the **Output styles** menu. Claude Code writes the [style file](../02-Claude-Code-CLI/output-styles.md#create-a-custom-output-style) for you at the project or user level. Requires Claude Code v2.1.261 or later.
- Select **Hooks** in the Customize section to view the [hooks](../07-Hooks/hooks.md) loaded in the session, grouped by event. You can add, edit, or remove hooks saved in your user, project, and local settings files. Hooks from other sources, such as managed settings or plugins, are read-only. Requires Claude Code v2.1.269 or later.
- Select **Permissions** in the Customize section to view the session’s [permission rules](../02-Claude-Code-CLI/permissions.md), grouped into Allow, Ask, and Deny. You can add rules to your user, project, or local settings and remove rules saved there. Rules from other sources, such as managed settings or approvals made for this session only, are read-only. Requires Claude Code v2.1.269 or later.
- Select **Memory** in the Customize section to turn [auto memory](../02-Claude-Code-CLI/memory.md#auto-memory) on or off. While it’s on, you can also browse the memories Claude has saved and reveal the folders that store them in your file manager. Requires Claude Code v2.1.274 or later. Click a saved memory to read it in the dialog, where you can edit the text, delete the memory, or open its file in the editor. Viewing, editing, and deleting a memory in the dialog require Claude Code v2.1.275 or later.
- Select **Instructions** in the Customize section to edit the [CLAUDE.md files](../02-Claude-Code-CLI/memory.md#claude-md-files) Claude reads. Pick a file to open it in the editor. If the file doesn’t exist yet, Claude Code creates it first. Requires Claude Code v2.1.274 or later.
- Select **Status** in the Customize section, or type `/status`, to check the session’s Claude Code version, account, model, and MCP server details. Requires Claude Code v2.1.280 or later.
- Select **Sandbox** in the Customize section, or type `/sandbox`, to see whether Claude’s Bash commands run [sandboxed](../02-Claude-Code-CLI/sandboxing.md). You can switch the sandbox mode and add [excluded commands](../02-Claude-Code-CLI/settings-reference.md#sandbox-excludedcommands) there. Requires Claude Code v2.1.280 or later.
- Select **Claude in Chrome** in the Customize section, or type `/chrome`, to check and manage the [Claude in Chrome](chrome.md) connection. Both require signing in with a claude.ai account. Requires Claude Code v2.1.280 or later.
- Select **Export conversation** in the Context section, or type `/export`, to copy the conversation as plain text or save it to a file. Add a file name, such as `/export notes.txt`, to skip the dialog and choose where to save the file. Requires Claude Code v2.1.280 or later.
- The Settings section includes **Enable Remote Control for all sessions**, which sets [`remoteControlAtStartup`](../02-Claude-Code-CLI/settings-reference.md#remotecontrolatstartup) to control whether [new interactive sessions connect to Remote Control automatically](../02-Claude-Code-CLI/remote-control.md#enable-remote-control-for-all-sessions). Requires Claude Code v2.1.203 or later. When you turn the toggle on or off in a VS Code window, the change isn’t limited to sessions you start afterwards. It also applies to the sessions already open in that VS Code window. If you turn it off, the open sessions disconnect. With Claude Code v2.1.261 or later, the change also reaches sessions open in your other VS Code windows.
- The Settings section also includes **Focus view**, which hides tool calls, tool results, and thinking behind expandable rows, leaving your prompts and Claude’s responses. Toggle it there, with `Ctrl+Option+F` (Mac) / `Ctrl+Alt+F` (Windows/Linux), or from the Command Palette with **Claude Code: Toggle Focus view**. The change applies to every open session and persists across sessions. Requires Claude Code v2.1.221 or later. Claude’s latest to-do list stays visible, and so does the text a pending question from Claude is asking about; this requires Claude Code v2.1.225 or later. While Claude runs [subagents](../09-Agents-Patterns/sub-agents.md), live progress rows with their latest activity appear under the tool-call group that started them. This requires Claude Code v2.1.269 or later.
- To sign out of your Anthropic account, select **Sign out** in the Settings section, or type `/logout`. On a [third-party provider](#use-third-party-providers), the menu doesn’t offer either. Requires Claude Code v2.1.277 or later.
- To report a bug, click **Report a problem** at the bottom of the menu, or type `/bug` or `/feedback` with an optional description that prefills the report. When you submit the report and you’re signed in to Anthropic on a first-party connection, Claude Code sends it to Anthropic. Requires Claude Code v2.1.229 or later. On a third-party provider, or without Anthropic credentials, nothing is sent. The dialog says so before you write. Submitting saves the report as a [local archive under `~/.claude/feedback-bundles/`](../13-Enterprise-Admin/data-usage.md#telemetry-services) with known API key and token patterns redacted. Saving the report on your computer requires Claude Code v2.1.284 or later. After the report is saved, the confirmation names the file and includes a **Show folder** button. Send that file to your Anthropic account representative or attach it to a support request. If your organization’s policy turns product feedback off, **Report a problem** doesn’t appear in the menu, and `/bug` and `/feedback` show a `Feedback is turned off by your organization's policy or this environment's settings.` notice instead of opening the report. With Claude Code v2.1.284 or later, if you set the `DISABLE_FEEDBACK_COMMAND` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` environment variable, feedback is also turned off and opening the report shows that notice instead.
- **Side questions**: type `/btw` followed by a question to ask about your session [without adding to the conversation](../02-Claude-Code-CLI/interactive-mode.md#side-questions-with-%2Fbtw). The answer opens in a panel beside the chat, where you can ask follow-up questions. Requires Claude Code v2.1.227 or later. The thread survives window reloads. Claude Code keeps the newest 20 exchanges and expires stored threads on the [`cleanupPeriodDays`](../02-Claude-Code-CLI/settings-reference.md#cleanupperioddays) schedule, as long as Claude Code can [safely determine the retention period](../02-Claude-Code-CLI/claude-directory.md#cleaned-up-automatically). To clear a thread, click the trash icon in the panel.
- **Copy a response**: hover over a response and click **Copy response** to copy it to your clipboard, or type `/copy` to copy the latest response. `/copy 2` copies the second-to-last. Requires Claude Code v2.1.277 or later.
- **Bookmarks**: hover over a response and click **Bookmark response** to save it, or click **Remove bookmark** on a saved response to remove it. To review saved responses, open the Bookmarks panel. You can click the bookmark icon at the top of the Claude Code panel, select **Bookmarks** in the Context section of the command menu, or type `/bookmarks`. Requires Claude Code v2.1.286 or later.
- **Files Claude sends you**: when the session is connected to [Remote Control](../02-Claude-Code-CLI/remote-control.md#start-a-remote-control-session) and Claude sends you files with the [`SendUserFile` tool](../02-Claude-Code-CLI/tools-reference.md), the conversation shows a row such as **Sent report.md, chart.png**. Click a file’s name to open it in the editor. The row stays visible in Focus view. Requires Claude Code v2.1.295 or later. A file appears as a full path you can’t click, such as `\\server\share\report.md`, when its path names a network host. Claude Code doesn’t link that file because opening it would contact that host and, on Windows, [could send your Windows credentials to that host](../02-Claude-Code-CLI/permissions.md#read-only-commands).
- **Context indicator**: the prompt box shows how much of Claude’s context window you’re using. Claude automatically compacts when needed, or you can run `/compact` manually.
- **Prompt cache clock**: a clock icon next to the context indicator estimates how much time the conversation’s [prompt cache](../02-Claude-Code-CLI/prompt-caching.md) has left before it expires. It counts down from the cache’s five-minute or one-hour [lifetime](../02-Claude-Code-CLI/prompt-caching.md#cache-lifetime), and each response that uses the cache restarts the countdown. Apart from compaction, the [actions that invalidate the cache](../02-Claude-Code-CLI/prompt-caching.md#actions-that-invalidate-the-cache) don’t reset the clock, so it can still show minutes left after you switch models.
- Until the countdown runs out, the icon shows the minutes left, such as **12m**.
- When the countdown runs out, the minutes disappear and the icon turns red, or your theme’s error color, until the next response. The cache has likely expired, so expect a slower, more expensive response to your next message while the cache rebuilds. If the five-minute lifetime keeps running out between your messages, see [Choose the TTL yourself](../02-Claude-Code-CLI/prompt-caching.md#choose-the-ttl-yourself).
- Right after the conversation is [compacted](../02-Claude-Code-CLI/prompt-caching.md#compacting-the-conversation), the icon also turns red without minutes until the next response, because the cache doesn’t cover the compacted conversation yet.
- **Agent map**: when the conversation includes [subagents](../09-Agents-Patterns/sub-agents.md), an agent count such as **2 agents** appears at the bottom of the prompt box. Its dot shows whether any subagent is working or waiting for your permission. Click the agent count to open the agent map, which draws the conversation’s subagents as a tree under the main agent, each with its status, elapsed time, and token count. Click a subagent to see its prompt and tool calls, open its read-only transcript, or stop it while it runs. Requires Claude Code v2.1.269 or later. The map also lists the session’s other [background tasks](../02-Claude-Code-CLI/tools-reference.md#background-commands), such as background shell commands and [monitors](../02-Claude-Code-CLI/tools-reference.md#monitor-tool), below the agents. Click a row to open the task’s card and stop it there. To open the map when no agent count is showing, such as when Claude has started a background shell but no subagents, type `/tasks` in the prompt box. Background tasks in the map and the typed `/tasks` require Claude Code v2.1.277 or later. With Claude Code v2.1.286 or later, when you click **Stop** or press `Esc`, the current turn ends. Background agents keep running until they finish or you stop them from the map.
- **Extended thinking**: lets Claude spend more time reasoning through complex problems. Toggle it on via the command menu (`/`). Claude’s reasoning appears in the conversation as collapsed blocks: click a block to read it, or press `Ctrl+O` to expand or collapse every thinking block in the session. See [Extended thinking](../02-Claude-Code-CLI/model-config.md#extended-thinking) for details.
- **Multi-line input**: press `Shift+Enter` to add a new line without sending. This also works in the “Other” free-text input of question dialogs.
[](#reference-files-and-folders)
Reference files and folders
Use @-mentions to give Claude context about specific files or folders. When you type `@` followed by a file or folder name, Claude reads that content and can answer questions about it or make changes to it. Claude Code supports fuzzy matching, so you can type partial names to find what you need:
```python
Explain the logic in @auth (fuzzy matches auth.js, AuthService.ts, etc.)
What's in @src/components/ (include a trailing slash for folders)
```
For large PDFs, you can ask Claude to read specific pages instead of the whole file. Ask for a single page, a range like pages 1-10, or an open-ended range like page 3 onward. Reading specific pages requires [poppler-utils](../02-Claude-Code-CLI/tools-reference.md#read-tool-behavior) on the machine where Claude Code runs. When you select text in the editor, Claude can see your highlighted code automatically. The prompt box footer shows how many lines are selected. Press `Option+K` (Mac) / `Alt+K` (Windows/Linux) to insert an @-mention with the file path and line numbers, for example `@app.ts#5-10`. Click the **X** on the selection indicator to remove it so Claude doesn’t receive the selection. The indicator comes back when you select other text. The extension withholds selected text from some files:
- When the file is inside your workspace and matches your `files.exclude` or `search.exclude` settings, Claude receives at most the file’s path and not the text you selected.
- The same applies to a file git ignores, as long as VS Code’s `search.useIgnoreFiles` setting and the extension’s [`respectGitIgnore` setting](#extension-settings) are both on, which is the default.
This filter covers the chat panel only. When Claude Code runs in the integrated terminal, the CLI sends your selected text whatever the file. To keep a file’s contents from Claude there, add a [`Read` deny rule](#the-built-in-ide-mcp-server). Claude also sees which file you have open in the editor, even when nothing is selected, and the prompt box shows its name. To add only your selected text, turn off the [Attach Open File setting](vscode://settings/claudeCode.attachOpenFile). The setting requires Claude Code v2.1.271 or later. You can also attach images and files to your message:
- To attach an image, paste it from your clipboard into the prompt box.
- To attach files, hold `Shift` while dragging them into the prompt box.
- To remove an attachment from context, click the X on it.
[](#include-terminal-output-in-prompts)
Include terminal output in prompts
Reference terminal output in your prompts using `@terminal:name` where `name` is the terminal’s title. This lets Claude see command output, error messages, or logs without copy-pasting.
[](#paste-text)
Paste text
Text you paste stays visible in the prompt box, rather than collapsing to a placeholder as it does [in the terminal](../02-Claude-Code-CLI/terminal-config.md#paste-large-content). In sessions where Claude Code [marks pasted text](../02-Claude-Code-CLI/terminal-config.md#how-claude-treats-pasted-text), Claude still sees a large paste as text you pasted rather than typed. Claude Code also removes [invisible Unicode characters](../02-Claude-Code-CLI/interactive-mode.md#invisible-characters-in-prompts) from text you paste into the prompt box and from anything else you send:
- If a notice such as `Removed 3 invisible characters from the pasted text` appears when you paste, the text went in without those characters.
- If a notice about removed characters appears when you send, nothing was sent. The cleaned text is back in the prompt box. Send again to send the text as shown.
[](#latex-math-in-responses)
LaTeX math in responses
The chat panel shows LaTeX math in Claude’s responses as typeset formulas. Math rendering requires Claude Code v2.1.301 or later. In [terminal mode](#switch-to-terminal-mode), math isn’t typeset. The panel typesets both display math and inline math:
- **Display math**: a `$$ … $$` or `\[ … \]` block on a line or lines of its own, and a fenced code block with `math` as its language
- **Inline math**: `$…$` or `\(…\)` that opens and closes on the same line, such as `$E = mc^2$` or `\(a^2 + b^2 = c^2\)`
The panel tries to tell math apart from other uses of the same characters, so text such as `$HOME`, a price like `$5`, or `sed 's/\(foo\)/\1/'` isn’t typeset. Neither is text inside a code span or inside any code block other than a fenced `math` block. If a formula shows as written when you expected it typeset, see [A formula shows as raw LaTeX](#a-formula-shows-as-raw-latex). When you select and copy text that includes a typeset formula, you get the formula’s TeX source in `$…$` or `$$…$$` delimiters rather than the drawn symbols. [**Copy response**](#use-the-prompt-box) and `/copy` give you the response as Claude wrote it, TeX source included.
[](#resume-past-conversations)
Resume past conversations
Click the **Session history** button at the top of the Claude Code panel to access your conversation history. You can search by keyword or browse by time. Click any conversation to resume it. If the conversation is already open in another tab of the current window, clicking it switches to that tab. When a notice says the conversation is still open somewhere else, see [how to continue it in this window](#the-conversation-is-still-open-somewhere-else). If the conversation opens with no messages showing, see [why a resumed conversation is blank at first](#a-resumed-conversation-is-blank-at-first). For more on resuming sessions, see [Manage sessions](../02-Claude-Code-CLI/sessions.md).
- **Session titles**: new sessions receive AI-generated titles based on your first message.
- **Rename and archive**: hover over a session to reveal these actions. Rename to give it a descriptive title, or archive to move it to the **Archived sessions** group at the bottom of the list.
- **Conversations missing with [`claudeProcessWrapper`](#extension-settings) set**: update the extension to version 2.1.304 or later. The list then includes the conversations that were missing, along with sessions that `claude -p` or the [Agent SDK](../05-Agent-SDK/agent-sdk-overview.md) started in this workspace.
By default, a session with no activity for 14 days moves to **Archived sessions** automatically, unless it is open, unread, or in a [group](#organize-sessions-into-groups). Automatic archiving requires Claude Code v2.1.265 or later. To change the period or turn it off, open the [Archive Inactive Sessions setting](vscode://settings/claudeCode.archiveInactiveSessions) and select a number of days or **Never**. To restore archived sessions:
- **One session**: expand **Archived sessions** and click **Unarchive session**.
- **Every archived session at once**: hover over the **Archived sessions** header in the sessions list in the Activity Bar and click its unarchive icon. Requires Claude Code v2.1.277 or later.
Before v2.1.257, the action was **Delete session**, which hid a session with no way to restore it. Sessions you deleted then appear under **Archived sessions** after you upgrade. When the conversation you resume ended in plan mode, Claude Code restores plan mode. Requires Claude Code v2.1.246 or later. Claude Code doesn’t restore it in these cases:
- The extension [chooses the starting permission mode](../02-Claude-Code-CLI/permission-modes.md#switch-permission-modes) from `claudeCode.initialPermissionMode` or a pick that carries over from an earlier conversation
- You have `claudeCode.claudeProcessWrapper` configured
- A [deny rule](../02-Claude-Code-CLI/permissions.md#manage-permissions) removes the [`ExitPlanMode`](../02-Claude-Code-CLI/tools-reference.md) tool
[](#the-conversation-is-still-open-somewhere-else)
The conversation is still open somewhere else
To continue in this window when a notice says the conversation is still open somewhere else, click **Open here anyway** after the step for your case:
- **You have nothing else open**: a Claude process from before the extension restarted may still have the conversation open. That process usually ends on its own within about 10 minutes, so wait that long and then click. If you click before it ends, the conversation is open in two places until it does.
- **You have the conversation open somewhere else**: close it there first, for example by exiting `claude` in a terminal or closing its tab in another VS Code window
When the conversation is still open in another Claude Code process, this notice appears in place of the prompt box:
```python
This conversation is still open somewhere else. Using it in two places at once can mix up its messages. If the extension restarted recently, a Claude process from before the restart may still be finishing. It usually ends on its own within about 10 minutes. This notice stays until you choose Open here anyway.
```
With [`claudeProcessWrapper`](#extension-settings) set, the extension skips this check and opens the conversation directly.
[](#resume-cloud-sessions-from-claude-ai)
Resume cloud sessions from claude.ai
If you run [cloud sessions](../02-Claude-Code-CLI/claude-code-on-the-web.md), you can resume them directly in VS Code. This requires signing in with **Claude.ai Subscription**, not Anthropic Console.
1
Open session history
Click the **Session history** button at the top of the Claude Code panel.
2
Select the Web tab
The dialog shows two tabs: Local and Web. Click **Web** to see sessions from claude.ai.
3
Select a session to resume
Browse or search the sessions. Click one to continue the conversation locally.
When the folder you have open is a GitHub repository, the Web tab shows only sessions from that repository.When you resume a cloud session, the extension downloads a copy of the conversation history; changes don’t sync back to claude.ai.
The Web tab also lists your [Remote Control](../02-Claude-Code-CLI/remote-control.md) sessions. If you click one that ran in the folder you have open, the extension opens that local conversation instead of downloading a copy. The extension focuses the tab already showing it, if there is one. If the extension can’t rule out that another Claude process has the conversation open, you get a downloaded copy instead. If any part of a conversation fails to download, an error appears and no copy is saved. Select the session again to retry. If you select a session that has no conversation to download yet, an error tells you where to continue it instead.
[](#check-account-and-usage)
Check account and usage
Run `/usage` to open the Account & usage dialog, which shows your signed-in account and your usage. The usage figures match how you signed in:
- **claude.ai plan**: usage bars for your plan’s limits, such as the current session and the week. Each bar shows how long until its limit resets. The dialog also breaks down what is contributing to your plan limits:
- **Recommendations**: suggested changes, one per row, such as `Trim ~/code/api/CLAUDE.md · 49k tokens per request`
- **Fix button**: to have Claude Code apply the recommendations it can, click the button under them, such as **Fix both**. To learn which rows the button acts on and what then happens in your session, see [Apply recommendations with the fix shortcut](../17-Billing-Plans/costs.md#apply-recommendations-with-the-fix-shortcut). Requires Claude Code v2.1.305 or later. The button isn’t shown while [Remote Control](../02-Claude-Code-CLI/remote-control.md) is connected. If a warning reads `The usage fix wasn’t fully sent. Open usage and try again.` after Remote Control connected, [disconnect Remote Control](../02-Claude-Code-CLI/remote-control.md#check-connection-status) before you try again.
- **Attribution**: tables of how much usage came from each skill, subagent, plugin, and MCP server
Use the Day and Week toggle to switch between the last 24 hours and the last 7 days. The figures are approximate and computed from local sessions on this machine, so usage from other devices or claude.ai is not included.
- **Other sign-ins**: when plan limits don’t apply to your sign-in, such as on a [third-party provider](#use-third-party-providers) or with an API key, the Usage section shows the session’s own cost and token usage instead. The CLI’s `/usage` shows the same totals in its [Session block](../17-Billing-Plans/costs.md#track-your-costs). The sessions list in the Activity Bar also shows the active session’s totals under its **Account & usage** header. Requires Claude Code v2.1.277 or later.
For more on tracking and reducing usage, see [Track your costs](../17-Billing-Plans/costs.md#track-your-costs).
[](#rewind-with-checkpoints)
Rewind with checkpoints
The VS Code extension supports checkpoints, which track Claude’s file edits and let you rewind to a previous state. Hover over any message to reveal the rewind button, then choose from three options:
- **Fork conversation from here**: start a new conversation branch from this message while keeping all code changes intact
- **Rewind code to here**: revert file changes back to this point in the conversation while keeping the full conversation history
- **Fork conversation and rewind code**: start a new conversation branch and revert file changes to this point
For full details on how checkpoints work and their limitations, see [Checkpointing](../02-Claude-Code-CLI/checkpointing.md).
[](#customize-your-workflow)
Customize your workflow
You can reposition the Claude panel, run multiple conversations, group or filter the sessions list, or switch to terminal mode.
[](#choose-where-claude-lives)
Choose where Claude lives
You can drag the Claude panel to reposition it anywhere in VS Code. Grab the panel’s tab or title bar and drag it to:
- **Secondary sidebar**: the right side of the window. Keeps Claude visible while you code.
- **Primary sidebar**: the left sidebar with icons for Explorer, Search, etc.
- **Editor area**: opens Claude as a tab alongside your files. Useful for side tasks.
When Claude opens a tab in a new editor group, the extension locks that group. Files you open while the Claude tab is focused then go to another group instead of next to it. To stop the extension from locking groups, turn off the [Lock Editor Groups setting](vscode://settings/claudeCode.lockEditorGroups). Groups that are already locked stay locked until you unlock them. The setting requires Claude Code v2.1.274 or later.
Use the sidebar for your main Claude session and open additional tabs for side tasks. Claude remembers your preferred location. The Activity Bar sessions list icon is separate from the Claude panel. The sessions list is always visible in the Activity Bar, while the Claude panel icon only appears there when the panel is docked to the left sidebar.
[](#continue-conversations-after-a-reload)
Continue conversations after a reload
After you run **Developer: Reload Window** or restart VS Code, check where the conversation was open:
- **Editor tab**: the conversation comes back with its tab.
- **Sidebar**: the conversation comes back if you sent a message or Claude responded in it within the last 10 minutes. If it doesn’t come back, resume the conversation from [Session history](#resume-past-conversations).
If a notice in place of the prompt box says the conversation is still open somewhere else, see [how to continue the conversation here](#the-conversation-is-still-open-somewhere-else). If the messages stay blank at first, see [why they’re blank and when they appear](#a-resumed-conversation-is-blank-at-first).
[](#interrupted-steps-after-a-reload)
Interrupted steps after a reload
If the reload interrupted Claude mid-step, Claude continues that step when the conversation comes back, and a notice in the chat marks the continuation. Requires Claude Code v2.1.274 or later. If the step was interrupted more than an hour ago or the session is open elsewhere, the conversation comes back idle instead.
[](#turn-off-continuation-after-a-reload)
Turn off continuation after a reload
To stop Claude from continuing an interrupted step after a reload, open the [Continue After Reload setting](vscode://settings/claudeCode.continueAfterReload) and uncheck it. If you set [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](../02-Claude-Code-CLI/env-vars.md#variables) or any other `CLAUDE_CODE_RESUME_` variable in VS Code’s environment or in the [`environmentVariables` setting](#extension-settings), it has no effect in the panel. That’s because the extension removes those variables before it starts the panel’s sessions.
[](#a-conversation-was-not-reopened)
A conversation was not reopened
After a reload, a new chat with a notice like this above its prompt box means the panel left your conversation closed because the conversation’s last two opens didn’t finish:
```python
“Fix the login bug” was not reopened. It did not finish opening the last 2 times, and opening it again may stop Claude Code from responding here.
```
An open doesn’t finish when the panel crashes or stops responding while loading the conversation, or when you reload or close the window within about three seconds of it opening. The conversation is unchanged and stays in [Session history](#resume-past-conversations).
- **To open it anyway**: click **Open it anyway** or pick the conversation from Session history. Once the conversation finishes opening, it [comes back after later reloads as usual](#continue-conversations-after-a-reload).
- **If the panel stops responding while the conversation loads**: reload the window. A new chat opens.
- **To leave it closed**: keep working in the new chat. The notice disappears once you send a prompt.
[](#run-multiple-conversations)
Run multiple conversations
Use **Open in New Tab** or **Open in New Window** from the Command Palette to start additional conversations. Each conversation maintains its own history and context, allowing you to work on different tasks in parallel. When using tabs, a small colored dot on the spark icon indicates status: blue means a permission request is pending, orange means Claude finished while the tab was hidden.
[](#organize-sessions-into-groups)
Organize sessions into groups
In the sessions list in the Activity Bar, you can collect related sessions into named, collapsible groups. Requires Claude Code v2.1.229 or later.
- **Group or ungroup a session**: right-click a session to create a group from it, move it into an existing group, or remove it from its group. Each session belongs to one group at a time, so moving it into another group removes it from the first.
- **Move several sessions at once**: `Cmd`-click (Mac) / `Ctrl`-click (Windows/Linux) each session, or `Shift`-click to select a range, then right-click the selection.
- **Group a session from its tab**: run **Claude Code: Add Session Tab to Group** from the Command Palette, then pick or create a group. Requires Claude Code v2.1.257 or later.
- **Rename or delete a group**: right-click a group header. Deleting a group removes only the group, and its sessions return to the ungrouped list.
The extension saves groups per workspace folder, so they survive window reloads and appear in every window where you open the same folder. When you search the list, the extension shows matches in one flat list across all groups.
[](#filter-the-sessions-list)
Filter the sessions list
To narrow a long sessions list in the Activity Bar, use the two filter controls at the top of the list. Requires Claude Code v2.1.271 or later. Archived sessions don’t appear while either filter is on.
- **Active**: turn on this toggle to show only sessions that need your input, are working, or are unread, plus the session in the Claude tab you last focused.
- **Filter by status**: click the funnel icon, then check **Needs input**, **Working**, or **Completed** to show sessions in any of those states. Check **Open** or **Closed** to narrow by whether a session is open. A session counts as open when it has a tab in this window or is running in another Claude Code process on this machine, such as in a terminal.
When **Active** is on and you check a status, **Open**, or **Closed**, the list also shows every session that matches your checks. The filters you set persist across window reloads.
[](#switch-to-terminal-mode)
Switch to terminal mode
By 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. You can also press `Cmd+,` on Mac or `Ctrl+,` on Windows/Linux to open VS Code settings, go to **Extensions \> Claude Code**, and check **Use Terminal**.
[](#manage-plugins)
Manage plugins
The VS Code extension includes a graphical interface for installing and managing [plugins](../08-Plugins-Skills/plugins.md). Type `/plugins` in the prompt box to open the **Manage plugins** interface.
[](#install-plugins)
Install plugins
The plugin dialog shows two tabs: **Plugins** and **Marketplaces**. In the Plugins tab:
- **Installed plugins** appear at the top with toggle switches to enable or disable them.
- If you turn off a plugin that your project’s shared `.claude/settings.json` turns on, the extension asks first: **Disable for me** turns it off only for you, while **Disable for everyone** changes the shared file.
- A plugin that failed to load shows a short reason on its row. Click the reason for what you can do about it, including copying the full error message to look up in [Troubleshoot plugins](../08-Plugins-Skills/plugins-troubleshooting.md).
- **Available plugins** from your configured marketplaces appear below
- Search to filter plugins by name or description
- Click **Install** on any available plugin
When you install a plugin, choose the installation scope:
- **Install for you**: available in all your projects (user scope)
- **Install for this project**: shared with project collaborators (project scope)
- **Install locally**: only for you, only in this repository (local scope)
Once the install finishes, a form asks for any of the plugin’s [configuration options](../08-Plugins-Skills/plugins-components.md#user-configuration) that aren’t set yet. To review or change the options later, click the gear icon on the plugin’s row. Sensitive text fields are masked, and a secret you saved earlier shows **(unchanged)**. Leave the field blank to keep the saved value. After you save changes, the open sessions reload their plugins and the dialog shows **Restart Claude to apply plugin changes**.
[](#uninstall-plugins)
Uninstall plugins
Each installed row names the [scope](../08-Plugins-Skills/discover-plugins.md#choose-an-install-scope) it’s installed at. To uninstall that installation, click the row’s trash icon. A dimmed trash icon marks a row you can’t uninstall from this workspace, such as a plugin your organization manages or one installed for another project. The extension asks first in two cases:
- **A plugin your project’s shared `.claude/settings.json` turns on**: choose **Disable for me**, which keeps the plugin installed for your collaborators, or **Uninstall for everyone**, which removes the project’s installation with [`--keep-data`](../08-Plugins-Skills/plugins-cli-reference.md#what-an-uninstall-deletes-and-keeps), so the plugin’s saved data directory stays. If you already turned the plugin off for yourself, the trash icon removes your own installation without the question.
- **Otherwise, the last installation of a plugin with saved data**: choose whether to keep or delete the data; **Keep** is the default
[](#share-a-plugin-install-link)
Share a plugin install link
To send someone straight to installing a specific plugin, give them the extension’s `install-plugin` URL. Opening it launches or focuses VS Code, opens the Claude Code panel, and opens the **Manage plugins** dialog on that plugin’s scope choice. Nothing installs until the person picks a scope. If the plugin’s marketplace isn’t configured in their Claude Code yet, the dialog first asks them to add it.
```python
vscode://anthropic.claude-code/install-plugin?plugin=code-review&marketplace=anthropics/claude-plugins-official
```
The URL takes two query parameters:
| Parameter | Description |
|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `plugin` | The plugin’s name as its marketplace lists it. Required. |
| `marketplace` | The marketplace’s [source](../08-Plugins-Skills/discover-plugins.md#add-a-marketplace): a GitHub `owner/repo`, an `https://` URL, or a git SSH address such as `git@github.com:owner/repo.git`. Defaults to `anthropics/claude-plugins-official` when omitted. |
The extension checks both values before it opens anything:
- **Plugin name**: at most 100 characters, starting with an ASCII letter or digit and otherwise using only ASCII letters, digits, `.`, `_`, and `-`.
- **Marketplace source**: only the forms the `marketplace` parameter lists, so not a local path, an `http://` address, or the marketplace’s name, such as `claude-plugins-official`. An `https://` URL can’t contain a user name, password, or query string.
- **Git ref**: to pin the marketplace to a branch or tag, append the ref to the source after `%23`, the encoded form of `#`, as in `marketplace=owner/repo%23v1.0`. A link with an unencoded `#` fails. Marketplaces in the `anthropics` GitHub organization can’t be pinned in a link.
Someone who opens a link that breaks these rules sees an error that starts with `Invalid plugin installation URL`. The Claude Code panel and the dialog don’t open, and nothing installs. If your plugin’s name or marketplace can’t go in a link, tell people to add the marketplace in the **Marketplaces** tab and then install the plugin from the **Plugins** tab. These cases end at a message in the dialog instead of the scope choice:
- **The marketplace doesn’t list a plugin by that name**: the dialog reports that the plugin wasn’t found. Check the `plugin` value against the marketplace’s listing.
- **The plugin is already installed**: the dialog says so, and nothing changes.
- **A different marketplace with the same name is already added**: the dialog says the link’s marketplace wasn’t added, and nothing installs.
[](#manage-marketplaces)
Manage marketplaces
Switch to the **Marketplaces** tab to add or remove plugin sources:
- Enter a GitHub repo, URL, or local path to add a new marketplace
- Click the refresh icon to update a marketplace’s plugin list
- Click the trash icon to remove a marketplace. Removing it [uninstalls every plugin you installed from it](../08-Plugins-Skills/discover-plugins.md#manage-marketplaces), so a confirmation names those plugins first
Plugin changes you make in the dialog apply right away to the Claude Code sessions open in that VS Code window. If the session you opened the dialog from can’t reload its plugins, the dialog offers to try again or to restart Claude in that session.
The extension manages plugins by running the same commands as the CLI. Plugins and marketplaces you configure in the extension are also available in the CLI, and vice versa.
For more about the plugin system, see [Plugins](../08-Plugins-Skills/plugins.md) and [Plugin marketplaces](../08-Plugins-Skills/plugins.md).
[](#plugins-that-draw-in-the-panel)
Plugins that draw in the panel
A plugin that contains a [mod](../08-Plugins-Skills/plugins-mods-overview.md) can draw in the chat panel. Drawing requires extension version 2.1.299 or later. A session that [doesn’t fetch feature flags](../02-Claude-Code-CLI/env-vars.md#features-that-need-feature-flag-fetching), such as one on Amazon Bedrock, needs 2.1.304 or later. From such a plugin you can see:
- A pane beside the conversation or above the prompt box
- A toast or a status line above the prompt box
- A message or a tool call drawn the plugin’s own way
When a plugin you installed adds or changes something in the panel, a label names it, in phrases such as these:
- **From the token-chart plugin**: the plugin drew or printed this, or this card is the plugin asking you something
- **Edited by the token-chart plugin**: the plugin changed something Claude Code draws, such as a tool call
- **Prompt from the token-chart plugin**: the plugin sent this message on your behalf
To stop a plugin from drawing, turn the plugin off in the [plugin dialog](#install-plugins).
[](#automate-browser-tasks-with-chrome)
Automate browser tasks with Chrome
Connect Claude to your Chrome browser to test web apps, debug with console logs, and automate browser workflows without leaving VS Code. This requires the [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or later. Type `@browser` in the prompt box followed by what you want Claude to do:
```python
@browser go to localhost:3000 and check the console for errors
```
You can also open the attachment menu to select specific browser tools like opening a new tab or reading page content. Claude opens new tabs for browser tasks and shares your browser’s login state, so it can access any site you’re already signed into. For more on working with the browser, see:
- [Enable Chrome by default](chrome.md#enable-chrome-by-default): have each session connect to your browser as it starts, without typing `@browser`
- [Permission prompts in VS Code sessions](chrome.md#permission-prompts-in-vs-code-sessions): when Claude Code asks you before a browser action
- [Use Claude Code with Chrome](chrome.md): setup instructions, the full list of capabilities, and troubleshooting
[](#work-with-git)
Work with git
Claude Code integrates with git to help with version control workflows directly in VS Code. Ask Claude to commit changes, create pull requests, or work across branches. To start Claude in an isolated worktree with its own files and branch, see [Run parallel sessions with worktrees](../02-Claude-Code-CLI/worktrees.md).
[](#create-commits-and-pull-requests)
Create commits and pull requests
Claude can stage changes, write commit messages, and create pull requests based on your work:
```python
commit my changes with a descriptive message
create a pr for this feature
summarize the changes I've made to the auth module
```
When creating pull requests, Claude generates descriptions based on the actual code changes and can add context about testing or implementation decisions.
[](#run-work-in-the-background)
Run work in the background
Send a long-running command or subagent to the background, then check on it from the prompt box.
[](#move-a-running-command-or-subagent-to-the-background)
Move a running command or subagent to the background
When a command or a [subagent](../09-Agents-Patterns/sub-agents.md) keeps Claude waiting longer than you want, click **Run in background** below its tool call in the conversation. Requires Claude Code v2.1.287 or later.
- **Timing**: the action appears once a command has run for about two seconds, or as soon as Claude starts waiting for a [subagent](../09-Agents-Patterns/sub-agents.md#run-subagents-in-foreground-or-background) it spawned from the main conversation.
- **After you click**: Claude stops waiting and continues the turn. The command or subagent keeps running as a [background task](../02-Claude-Code-CLI/tools-reference.md#background-commands) that notifies Claude when done.
To check on the task or stop it in the meantime, type `/tasks` in the prompt box to open the [agent map](#use-the-prompt-box). A subagent keeps its place in the tree of agents there, and a command is listed below the agents with its [latest output on its card](#monitor-background-processes).
[](#the-run-in-background-action-is-missing-under-a-subagent)
The Run in background action is missing under a subagent
By default in VS Code, subagents don’t show this action. To see why for one subagent, open its card in the [agent map](#use-the-prompt-box) and read the `Spawned by` line:
- **`Spawned by the main agent`**: the subagent started in the background, so Claude isn’t waiting for it and you don’t need to do anything. To have Claude wait for subagents instead, see [Let Claude wait for a subagent](../09-Agents-Patterns/sub-agents.md#let-claude-wait-for-a-subagent).
- **`Spawned by` names another subagent**: the action appears only for subagents the main agent spawned, not a [nested subagent](../09-Agents-Patterns/sub-agents.md#let-subagents-spawn-their-own-subagents) another subagent waits for. To end the nested subagent early, click **Stop agent** on its card. The waiting subagent then carries on without that result.
[](#monitor-background-processes)
Monitor background processes
Type `/tasks` in the prompt box to open the [agent map](#use-the-prompt-box), which lists the session’s background tasks, such as a dev server Claude left running as a background shell command. Click a task to open its card, where you can stop it. Requires Claude Code v2.1.277 or later. For a background shell command, or a [monitor](../02-Claude-Code-CLI/tools-reference.md#monitor-tool) that runs a command, the card also shows the command’s latest output and refreshes it while the command runs.
[](#see-a-background-subagent’s-tool-calls)
See a background subagent’s tool calls
When a subagent shows as one status line with no tool calls, type `/tasks` in the prompt box to open the [agent map](#use-the-prompt-box) and click the subagent there. The subagent is [running in the background](#the-run-in-background-action-is-missing-under-a-subagent), and its card shows its tool calls and a button that opens its transcript.
[](#vs-code-commands-and-shortcuts)
VS Code commands and shortcuts
To open the Command Palette, press `Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Windows/Linux. Type “Claude Code” there to see all available VS Code commands for the Claude Code extension. Some shortcuts depend on which panel is “focused” (receiving keyboard input). When your cursor is in a code file, the editor is focused. When your cursor is in Claude’s prompt box, Claude is focused. Use `Cmd+Esc` / `Ctrl+Esc` to toggle between them.
These are VS Code commands for controlling the extension. Not all built-in Claude Code commands are available in the extension. See [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) for details.
| Command | Shortcut | Description |
|----------------------------|----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Focus Input | `Cmd+Esc` (Mac) / `Ctrl+Esc` (Windows/Linux) | Toggle focus between editor and Claude |
| Focus last message | \- | Move keyboard focus to the newest message in the conversation, or to a waiting permission prompt, so you can read from there with the keyboard or a screen reader. Not available in [terminal mode](#switch-to-terminal-mode). Requires Claude Code v2.1.268 or later |
| Open in Side Bar | \- | Open Claude in the sidebar |
| Open in Terminal | \- | Open Claude in terminal mode |
| Open in New Tab | `Cmd+Shift+Esc` (Mac) / `Ctrl+Shift+Esc` (Windows/Linux) | Open a new conversation as an editor tab |
| Open in New Window | \- | Open a new conversation in a separate window |
| New Conversation | `Cmd+N` (Mac) / `Ctrl+N` (Windows/Linux) | Start a new conversation. Requires Claude to be focused and `enableNewConversationShortcut` set to `true` |
| Reopen Closed Session | `Cmd+Shift+T` (Mac) / `Ctrl+Shift+T` (Windows/Linux) | Reopen the most recently closed Claude session tab. Falls through to VS Code’s normal reopen-closed-editor when the last closed tab wasn’t a Claude session. Disable with `enableReopenClosedSessionShortcut` |
| Insert @-Mention Reference | `Option+K` (Mac) / `Alt+K` (Windows/Linux) | Insert a reference to the current file and selection (requires editor to be focused) |
| Accept Change at Cursor | \- | Accept the change at the cursor while [reviewing a proposed edit](#get-started) one change at a time. Requires Claude Code v2.1.275 or later |
| Reject Change at Cursor | \- | Revert the change at the cursor while reviewing a proposed edit one change at a time. Requires Claude Code v2.1.275 or later |
| Toggle Focus view | `Ctrl+Option+F` (Mac) / `Ctrl+Alt+F` (Windows/Linux) | Hide or show tool activity in the conversation. Works while a Claude panel or sidebar is visible. Requires Claude Code v2.1.221 or later |
| Rename Session Tab | \- | Rename the session in the active Claude tab. Requires Claude Code v2.1.257 or later |
| Add Session Tab to Group | \- | Add the session in the active Claude tab to a [session group](#organize-sessions-into-groups) you pick or create. Requires Claude Code v2.1.257 or later |
| Mark Session as Unread | \- | Mark the session in the active Claude tab as unread in the sessions list. Requires Claude Code v2.1.257 or later |
| Show Logs | \- | View extension debug logs |
| Logout | \- | Sign out of your Anthropic account |
[](#launch-a-vs-code-tab-from-other-tools)
Launch a VS Code tab from other tools
The extension registers a URI handler at `vscode://anthropic.claude-code/open`. Use it to open a new Claude Code tab from your own tooling: a shell alias, a browser bookmarklet, or any script that can open a URL. If VS Code isn’t already running, opening the URL launches it first. If VS Code is already running, the URL opens in whichever window is currently focused. Invoke the handler with your operating system’s URL opener.
- macOS
- Linux
- Windows
```python
open "vscode://anthropic.claude-code/open"
```
```python
xdg-open "vscode://anthropic.claude-code/open"
```
The `xdg-open` command comes from the `xdg-utils` package. If the shell reports it isn’t found, see [xdg-open is not found on Linux](../02-Claude-Code-CLI/deep-links.md#xdg-open-is-not-found-on-linux).
In PowerShell:
```python
Start-Process "vscode://anthropic.claude-code/open"
```
In `cmd.exe`, `start` treats its first quoted argument as a window title, so pass an empty title before the URL:
```python
start "" "vscode://anthropic.claude-code/open"
```
The handler accepts two optional query parameters:
| Parameter | Description |
|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `prompt` | Text to pre-fill in the prompt box. Must be URL-encoded. The prompt is pre-filled but not submitted automatically. |
| `session` | A session ID to resume instead of starting a new conversation. The session must belong to the workspace currently open in VS Code. If the session isn’t found, a fresh conversation starts instead. If the session is already open in a tab, that tab is focused. To capture a session ID programmatically, see [Continue conversations](../02-Claude-Code-CLI/headless.md#continue-conversations). |
For example, to open a tab pre-filled with “review my changes”:
```python
vscode://anthropic.claude-code/open?prompt=review%20my%20changes
```
The extension also handles `vscode://anthropic.claude-code/install-plugin`, which [opens the plugin dialog on one plugin](#share-a-plugin-install-link). To launch a terminal session instead of a VS Code tab, use the CLI’s `claude-cli://` handler. See [Launch sessions from links](../02-Claude-Code-CLI/deep-links.md).
[](#configure-settings)
Configure settings
You configure the extension in two places, VS Code’s extension settings and the Claude Code settings file:
- **Extension settings** in VS Code: control the extension’s behavior within VS Code. Open with `Cmd+,` (Mac) or `Ctrl+,` (Windows/Linux), then go to **Extensions \> Claude Code**. You can also type `/` and select **General config…** to open settings.
- **Claude Code settings** in `~/.claude/settings.json`: shared between the extension and CLI. Use it for allowed commands, environment variables, hooks, and MCP servers. With Claude Code v2.1.283 or later, it’s also one input to the permission mode conversations start in, and on earlier versions only on Pro, Max, and Team plans. [Switch permission modes](../02-Claude-Code-CLI/permission-modes.md#switch-permission-modes) lists the order. See [Settings](../02-Claude-Code-CLI/settings.md) for details.
Add `"$schema": "https://json.schemastore.org/claude-code-settings.json"` to your `settings.json` to get autocomplete and inline validation for all available settings directly in VS Code.
[](#extension-settings)
Extension settings
VS Code reads `initialPermissionMode` from your user settings and ignores workspace values. Before v2.1.225, VS Code defaulted the setting to `default` and applied workspace values.
| Setting | Default | Description |
|-------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `useTerminal` | `false` | Launch Claude in terminal mode instead of graphical panel |
| `initialPermissionMode` | \- | Controls approval prompts for new conversations: `default`, `plan`, `acceptEdits`, or `bypassPermissions`. `manual` is an alias for `default` and selects the mode labeled **Manual** in the mode indicator. When you leave it unset, the extension chooses the starting permission mode as described in [Switch permission modes](../02-Claude-Code-CLI/permission-modes.md#switch-permission-modes). |
| `preferredLocation` | `panel` | Where Claude opens: `sidebar` (right) or `panel` (new tab) |
| `lockEditorGroups` | `true` | [Lock the editor groups Claude starts for its tabs](#choose-where-claude-lives), so files you open while a Claude tab is focused go to another group. When off, the extension never locks an editor group. Requires Claude Code v2.1.274 or later |
| `autosave` | `true` | Auto-save files before Claude reads or writes them |
| `attachOpenFile` | `true` | Add the file that is open in the editor to your messages and show it in the prompt box. When off, only your selected text is added. Requires Claude Code v2.1.271 or later |
| `useCtrlEnterToSend` | `false` | Use Ctrl/Cmd+Enter instead of Enter to send prompts |
| `scrollToBottomOnSend` | `true` | Scroll the conversation to the bottom when you send a message. When off, the conversation stays where you left it. Requires Claude Code v2.1.275 or later |
| `showMessageTimestamps` | `true` | Show when each message was sent. A date line marks where the day changes. Requires Claude Code v2.1.284 or later. Before v2.1.290, the default was `false` |
| `spinnerVerbs` | `{"mode": "append", "verbs": []}` | Set the verbs the conversation spinner rotates through while a turn runs, with the same `mode` and `verbs` fields as the CLI’s [`spinnerVerbs`](../02-Claude-Code-CLI/settings-reference.md#spinnerverbs). |
| `enableNewConversationShortcut` | `false` | Enable Cmd/Ctrl+N to start a new conversation |
| `enableReopenClosedSessionShortcut` | `true` | Use Cmd/Ctrl+Shift+T to reopen the most recently closed Claude session tab. When the last closed tab wasn’t a Claude session, the shortcut runs VS Code’s normal reopen-closed-editor command instead. |
| `archiveInactiveSessions` | `14` | [Archive a session automatically](#resume-past-conversations) after this many days without activity: `1`, `2`, `7`, or `14`. Set `0` to turn it off. Requires Claude Code v2.1.265 or later |
| `continueAfterReload` | `true` | After a window reload, Claude [continues the step that was interrupted](#continue-conversations-after-a-reload) in the restored session. Requires Claude Code v2.1.274 or later |
| `hideOnboarding` | `false` | Hide the onboarding checklist (graduation cap icon) |
| `focusView` | `false` | Hide tool calls, tool results, and thinking behind expandable rows, leaving your prompts and Claude’s responses. Claude’s latest to-do list stays visible; this requires Claude Code v2.1.225 or later. You can also toggle Focus view from the command menu. Requires Claude Code v2.1.221 or later |
| `respectGitIgnore` | `true` | Exclude .gitignore patterns from file searches and from [selection context](#reference-files-and-folders) |
| `usePythonEnvironment` | `true` | Activate the workspace’s Python environment when running Claude. Requires the Python extension. |
| `environmentVariables` | `[]` | Set environment variables for the Claude process. Use Claude Code settings instead for shared config. A [`CLAUDE_CONFIG_DIR`](../02-Claude-Code-CLI/env-vars.md) entry applies only when its value is an absolute path; the extension doesn’t expand `~` and ignores a relative value. |
| `disableLoginPrompt` | `false` | Skip authentication prompts (for third-party provider setups) |
| `allowDangerouslySkipPermissions` | `false` | Adds Bypass permissions to the mode selector. Use it only in sandboxes with no internet access. |
| `claudeProcessWrapper` | \- | Executable used to launch the Claude process. The bundled binary path is passed as an argument when present. Set this to a separately installed `claude` binary if the extension build doesn’t include one for your platform. |
[](#use-third-party-providers)
Use third-party providers
By default, Claude Code connects directly to Anthropic’s API. If your organization uses Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry to access Claude, configure the extension to use your provider instead:
1
Disable login prompt
Open the [Disable Login Prompt setting](vscode://settings/claudeCode.disableLoginPrompt) and check the box.You can also press `Cmd+,` on Mac or `Ctrl+,` on Windows/Linux to open VS Code settings, search for “Claude Code login”, and check **Disable Login Prompt**.
2
Configure your provider
Follow the setup guide for your provider:
- [Claude Code on Amazon Bedrock](../02-Claude-Code-CLI/amazon-bedrock.md)
- [Claude Code on Google Cloud’s Agent Platform](../02-Claude-Code-CLI/google-vertex-ai.md)
- [Claude Code on Microsoft Foundry](../02-Claude-Code-CLI/microsoft-foundry.md)
These guides cover configuring your provider in `~/.claude/settings.json`, which ensures your settings are shared between the VS Code extension and the CLI.
On a third-party provider, the extension doesn’t offer features that require a claude.ai account, such as plan usage bars, [voice dictation](../02-Claude-Code-CLI/voice-dictation.md), and the Web tab for [cloud sessions](#resume-cloud-sessions-from-claude-ai). For what the Account & usage dialog shows on these sign-ins, see [Check account and usage](#check-account-and-usage). A claude.ai sign-in left over from an earlier `/login` stays unused: the extension doesn’t send it with any request.
[](#use-a-screen-reader)
Use a screen reader
The extension’s chat panel works with screen readers. You don’t need to turn anything on: the extension announces conversation activity for every user, with no visual change. This is separate from the CLI’s opt-in [screen reader mode](../02-Claude-Code-CLI/accessibility.md), which adapts the terminal interface. Screen reader support in the chat panel requires Claude Code v2.1.236 or later. During a conversation, the extension announces:
- **Claude’s replies**: the extension announces each reply once, when it’s complete, and stays silent while text streams in. Your screen reader reads code blocks as a line-count summary, reads links by their label, and reads tables cell by cell; the full reply stays readable in the transcript.
- **Permission requests and questions**: the extension announces a request when its permission prompt appears, naming the tool Claude wants to use. It announces in the same way when Claude asks you a question and when Claude finishes a plan and waits for your review.
- **Status changes**: the extension announces when Claude starts working, when Claude is ready for your input, and when Claude Code starts compacting the conversation. If you send a prompt while the session’s [SessionStart](../07-Hooks/hooks.md#sessionstart) hooks are still running, your screen reader also says “Running start-up hooks.”
- **Queued messages**: when you send a message while Claude is working, the extension announces “Message queued.” for that message.
- **Errors and model prompts**: the extension announces errors in the conversation, and announces when the [usage-credits consent prompt](../02-Claude-Code-CLI/model-config.md#fable-and-usage-credits) or the [flagged-request prompt](../02-Claude-Code-CLI/model-config.md#ask-before-switching) appears.
While Claude works, your screen reader reads a text label in place of the progress spinner’s animation. When you reopen a session or switch to another one, the extension announces nothing: restored history, pending permission prompts, and in-progress status stay silent until something new happens.
[](#use-the-chat-panel-from-the-keyboard)
Use the chat panel from the keyboard
Each turn in the transcript starts with a visually hidden heading labeled with the prompt that started the turn. Use your screen reader’s heading navigation to jump between turns. Within a turn, your screen reader announces whose message you’re on as you move through it:
- **Your messages**: “You”
- **Claude’s messages**: “Claude”
- **Tool steps**: “Claude” plus the tool name, such as “Claude, Bash”
- **Thinking blocks**: “Claude, thinking”
Because the extension exposes the transcript as a labeled region, you can also move focus to the transcript itself with `Tab` and read it at your own pace. To move focus to the newest message or a waiting permission prompt instead, run **Claude Code: Focus last message** from the [Command Palette](#vs-code-commands-and-shortcuts). When a permission prompt option saves a permission rule or directory access, its label ends by naming where the approval is saved, such as “all projects” or “this session”. To change the destination:
- With that option focused, press the `Left` or `Right` arrow key. The extension announces each destination as you move to it. The arrow keys require Claude Code v2.1.268 or later.
- Click the destination in the label.
[](#vs-code-extension-vs-claude-code-cli)
VS Code extension vs. Claude Code CLI
Claude Code is available as both a VS Code extension (graphical panel) and a CLI (command-line interface in the terminal). Some features are only available in the CLI. If you need a CLI-only feature, run `claude` in VS Code’s integrated terminal. This requires the [standalone CLI install](../01-Getting-Started/setup.md): the extension does not add `claude` to your PATH. See [Run CLI in VS Code](#run-cli-in-vs-code).
| Feature | CLI | VS Code Extension |
|---------------------|--------------------------|--------------------------------------------------------------------------------------------------|
| Commands and skills | [All](../02-Claude-Code-CLI/commands.md) | Subset (type `/` to see available) |
| MCP server config | Yes | Yes: [add and manage servers](#connect-to-external-tools-with-mcp) with `/mcp` in the chat panel |
| Checkpoints | Yes | Yes |
| `!` Bash shortcut | Yes | No |
| Tab completion | Yes | No |
[](#run-cli-in-vs-code)
Run CLI in VS Code
To use the CLI while staying in VS Code, press `` Ctrl+` `` on Windows/Linux or `` Cmd+` `` on Mac to open the integrated terminal, then run `claude`. The CLI automatically integrates with your IDE for features like diff viewing and diagnostic sharing. If you use an external terminal, run `/ide` inside Claude Code to connect it to VS Code. Installing the extension does not put `claude` on your shell PATH. The extension bundles a private copy of the CLI for its chat panel, but typing `claude` in a terminal requires the [standalone CLI install](../01-Getting-Started/setup.md). Run the install once and the commands on this page, including `claude mcp add` and `claude --resume`, work in any terminal. If `claude` is still not found after installing, [verify your PATH](../02-Claude-Code-CLI/troubleshoot-install.md#verify-your-path).
[](#switch-between-extension-and-cli)
Switch between extension and CLI
The 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.
[](#connect-to-external-tools-with-mcp)
Connect to external tools with MCP
MCP (Model Context Protocol) servers give Claude access to external tools, databases, and APIs. To manage MCP servers without leaving VS Code, type `/mcp` in the chat panel. From the dialog that opens, you can:
- Add servers
- Remove servers saved at the local, user, or project [scope](../06-MCP-Tools/General/mcp.md#mcp-installation-scopes)
- Enable or disable servers
- Reconnect to a server
- Manage OAuth authentication
Adding and removing servers in the dialog requires Claude Code v2.1.261 or later. You can also run `claude mcp add` in VS Code’s integrated terminal (`` Ctrl+` `` or `` Cmd+` ``). The dialog and the terminal command save to the same MCP configuration, and changes from either take effect in conversations you start afterwards. The example below adds GitHub’s remote MCP server, which authenticates with a [personal access token](https://github.com/settings/personal-access-tokens) passed as a header:
```python
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_GITHUB_PAT"
```
Replace `YOUR_GITHUB_PAT` with your personal access token. The `claude mcp add` command saves the configuration without validating credentials, so a placeholder value is accepted here but the server fails to connect later. To verify the connection, start a new conversation, type `/mcp`, and check that the server shows **Connected**. A server with bad credentials shows **Failed**. Once configured, ask Claude to use the tools (for example, “Review PR \#456”).
To find servers to connect, see [Find and build MCP servers](../06-MCP-Tools/General/mcp.md#find-and-build-mcp-servers).
[](#the-built-in-ide-mcp-server)
The built-in IDE MCP server
When the extension is active, it runs a local MCP server that the CLI connects to automatically. Through this server, the CLI:
- Opens diffs in VS Code’s native diff viewer
- Reads your current selection for `@`-mentions
- Asks VS Code to execute cells when you’re working in a Jupyter notebook
The server is named `ide` and is hidden from `/mcp` because there’s nothing to configure. If your organization uses a `PreToolUse` hook to allowlist MCP tools, though, you’ll need to know it exists. **Selection and open-file context.** While connected, the CLI includes your current editor selection and the path of the active file as context on each prompt you send. The transcript shows a `⧉ Selected N lines from <file>` line when this happens. These cases change that context:
- **Queued messages**: if you [queue a message while Claude works](../02-Claude-Code-CLI/interactive-mode.md#queue-messages-while-claude-works), it keeps the selection you had when you pressed `Enter`, whatever you select afterward.
- **Sensitive files**: to exclude a sensitive file such as `.env`, add a [`Read` deny rule](../02-Claude-Code-CLI/permissions.md#read-and-edit) for its path. A matching deny rule prevents both the selected text and the open-file notice for that file from reaching Claude.
- **Attach Open File turned off**: if you turn off the [Attach Open File setting](#extension-settings), the CLI receives the active file’s path only while you have text selected in it.
**Transport and authentication.** The server binds to `127.0.0.1` on a random port in the range 10000–65535, and the port is not configurable. The transport and the auth token work as follows:
- **Transport**: unencrypted `ws://`. Because the socket is loopback-only, any process that could capture the traffic can also read the token from the lock file, so TLS would not add protection.
- **Auth token**: each extension activation generates a fresh random auth token and writes it to a lock file at `~/.claude/ide/<port>.lock`. The CLI must present the token as the `X-Claude-Code-Ide-Authorization` header to connect.
- **Lock file permissions**: the lock file has `0600` permissions in a `0700` directory, so only the user running VS Code can read it. If `CLAUDE_CONFIG_DIR` is set, the lock file is written to `$CLAUDE_CONFIG_DIR/ide/` instead.
**Tools exposed to the model.** The server hosts a dozen tools, but only two are visible to the model. The rest are internal RPC the CLI uses for its own UI, such as opening diffs, reading selections, and saving files. They are filtered out before the tool list reaches Claude.
| Tool name (as seen by hooks) | What it does | Read-only |
|------------------------------|--------------------------------------------------------------------------------------------------------------------------|-----------|
| `mcp__ide__getDiagnostics` | Returns language-server diagnostics: the errors and warnings in VS Code’s Problems panel. Optionally scoped to one file. | Yes |
| `mcp__ide__executeCode` | Runs Python code in the active Jupyter notebook’s kernel. See confirmation flow below. | No |
**Diagnostics in the chat panel.** In the chat panel, with Claude Code v2.1.285 or later, Claude reads VS Code’s Problems panel through a separate built-in server named `claude-vscode`. Claude can ask it for the current errors and warnings in one file, or in every file VS Code has diagnostics for. Hooks and permission rules see the chat panel’s diagnostics tool as `mcp__claude-vscode__getDiagnostics`. To cover diagnostics in both the CLI and the chat panel, name both `mcp__ide__getDiagnostics` and `mcp__claude-vscode__getDiagnostics` in your hook or rule. This `settings.json` example denies both tools:
```python
{
"permissions": {
"deny": [
"mcp__ide__getDiagnostics",
"mcp__claude-vscode__getDiagnostics"
]
}
}
```
A `Read` deny rule covers neither tool, so block them by name with a [deny rule](../02-Claude-Code-CLI/permissions.md#mcp) as the example does. **Jupyter execution always asks first.** `mcp__ide__executeCode` can’t run anything silently. Each call goes through these steps:
1. The code is inserted as a new cell at the end of the active notebook.
2. VS Code scrolls the cell into view.
3. A native Quick Pick asks you to **Execute** or **Cancel**.
Cancelling, or dismissing the picker with `Esc`, returns an error to Claude and nothing runs. The tool also refuses outright when there’s no active notebook, when the Jupyter extension (`ms-toolsai.jupyter`) isn’t installed, or when the kernel isn’t Python.
The Quick Pick confirmation is separate from `PreToolUse` hooks. An allowlist entry for `mcp__ide__executeCode` lets Claude *propose* running a cell; the Quick Pick inside VS Code is what lets it *actually* run.
[](#fix-common-issues)
Fix common issues
Sign-in, network, and launch errors have their own entries on the install troubleshooting and error reference pages. Find what you see in the table, then follow the link.
| What you see | Where to go |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| `API Error: 403 Request not allowed` after you sign in | [403 Forbidden after login](../02-Claude-Code-CLI/troubleshoot-install.md#403-forbidden-after-login) |
| You’re asked to sign in again after you already signed in | [Not logged in or token expired](../02-Claude-Code-CLI/troubleshoot-install.md#not-logged-in-or-token-expired) |
| Cloud provider credentials work in your terminal but not in the extension | [Bedrock, Agent Platform, or Foundry credentials not loading](../02-Claude-Code-CLI/troubleshoot-install.md#bedrock-agent-platform-or-foundry-credentials-not-loading) |
| `SSL certificate verification failed` or `Self-signed certificate detected` | [SSL certificate errors](../02-Claude-Code-CLI/errors.md#ssl-certificate-errors) |
| `Dictation error: WebSocket error:` followed by a certificate error such as `unable to get local issuer certificate`, or `Remote server is not connected` on the Web tab | [Dictation or the Web tab fails behind a TLS-inspecting proxy](#dictation-or-the-web-tab-fails-behind-a-tls-inspecting-proxy) |
| `Claude Code process exited with code 1`, or another code | [Claude Code process exited with code N](../02-Claude-Code-CLI/errors.md#claude-code-process-exited-with-code-n) |
| `Could not locate the Claude CLI on PATH` | [Could not locate the Claude CLI on PATH](../02-Claude-Code-CLI/errors.md#could-not-locate-the-claude-cli-on-path) |
| `The connection to Claude Code ended before this message completed` | [The connection to Claude Code ended before this message completed](../02-Claude-Code-CLI/errors.md#the-connection-to-claude-code-ended-before-this-message-completed) |
| `claude` isn’t found in VS Code’s integrated terminal | [Run CLI in VS Code](#run-cli-in-vs-code) |
[](#extension-won’t-install)
Extension won’t install
- Ensure you have a compatible version of VS Code (1.94.0 or later)
- Check that VS Code has permission to install extensions
- Try installing directly from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code)
[](#spark-icon-not-visible)
Spark icon not visible
The Spark icon appears in the **Editor Toolbar** (top-right of editor) when you have a file open. If you don’t see it:
1. **Open a file**: The icon requires a file to be open. Having only a folder open isn’t enough.
2. **Check VS Code version**: Requires 1.94.0 or later. Check under **Help \> About**
3. **Restart VS Code**: Run “Developer: Reload Window” from the Command Palette
4. **Disable conflicting extensions**: Temporarily disable other AI extensions (Cline, Continue, etc.)
5. **Check workspace trust**: The extension doesn’t work in Restricted Mode
Alternatively, click **✻ Claude Code** in the **Status Bar** at the bottom-right corner of the window. This works even without a file open. You can also use the **Command Palette** (`Cmd+Shift+P` / `Ctrl+Shift+P`) and type “Claude Code”.
[](#cmd+esc-does-nothing-on-macos)
Cmd+Esc does nothing on macOS
On macOS Tahoe and later, the system Game Overlay shortcut is bound to `Cmd+Esc` by default and intercepts the keypress before it reaches VS Code. To free the shortcut:
1. Open System Settings
2. Go to Keyboard, then Keyboard Shortcuts, then Game Controllers
3. Clear the Game Overlay checkbox
Alternatively, rebind the extension to a different key: open the VS Code [Keyboard Shortcuts editor](https://code.visualstudio.com/docs/configure/keybindings) (`Cmd+K Cmd+S`), search for `Claude Code: Focus input`, and assign a new binding.
[](#ctrl+j-adds-a-new-line-in-the-prompt-box)
Ctrl+J adds a new line in the prompt box
To stop `Ctrl+J` from adding a new line in the prompt box, [unbind the key](../02-Claude-Code-CLI/keybindings.md#unbind-default-shortcuts) in Claude Code’s `keybindings.json` file. The extension reads this file in version 2.1.309 or later, so update an older extension in the Extensions view first. This example is the whole file with the one entry that unbinds the key, `"ctrl+j": null` in a `Chat` block:
```python
{
"bindings": [
{
"context": "Chat",
"bindings": {
"ctrl+j": null
}
}
]
}
```
The file goes in your Claude Code configuration directory, which is `~/.claude` unless you moved it with `CLAUDE_CONFIG_DIR`. Look in that directory and take the step that matches what you find:
- **No `keybindings.json` yet**: create it with exactly the content of the example
- **A `keybindings.json` with no `Chat` block**: add the example’s `Chat` block to the top-level `bindings` array, at any position
- **A `Chat` block with no `"ctrl+j"` line**: add `"ctrl+j": null` to that block’s `bindings`
- **A `Chat` block that already has a `"ctrl+j"` line**: change that line’s value to `null`
After you save the file, pressing `Ctrl+J` in the prompt box adds no new line. If `Ctrl+J` still adds a line in the prompt box, run these two commands from the Command Palette in order:
1. **Developer: Reload Window**, then press `Ctrl+J` in the prompt box again
2. **Claude Code: Show Logs**, then look for a warning that includes `Ctrl+J in the chat input still inserts a newline`. Correct the problem it reports in the file it names, save the file, and press `Ctrl+J` again.
If the log has no such warning, check that the file is in your Claude Code configuration directory and that its `Chat` block sets `"ctrl+j"` to `null`. [Report the issue](https://github.com/anthropics/claude-code/issues) if `Ctrl+J` still adds a line.
[](#the-claude-code-panel-is-blank-or-couldn’t-load)
The Claude Code panel is blank or couldn’t load
If the Claude Code panel opens but shows nothing at all, not even the prompt box, update the extension to v2.1.309 or later in the Extensions view. Then run **Developer: Reload Window** from the Command Palette. If you then see a `Claude Code couldn’t load` notice, work through the steps it lists in order. If the panel still doesn’t load, open the extension’s log and [report the issue](https://github.com/anthropics/claude-code/issues) with a copy of it:
- **Still blank on v2.1.309 or later**: open the log with **Claude Code: Show Logs** from the Command Palette
- **The notice’s steps didn’t help**: click **Show logs** in the notice to open the log
[](#a-resumed-conversation-is-blank-at-first)
A resumed conversation is blank at first
When you [resume a past conversation](#resume-past-conversations) or one [comes back after a reload](#continue-conversations-after-a-reload), its messages can stay blank while the conversation’s Claude Code process starts. After about a second, `Waiting for your plugins…` appears in the empty space. You don’t need to do anything. The messages appear once the process has started and confirmed that no plugin needs to check them first, or after 20 seconds if starting takes longer.
[](#the-panel-stops-responding-each-time-a-reload-reopens-a-conversation)
The panel stops responding each time a reload reopens a conversation
If the whole panel crashes, freezes, or shows only `Something went wrong` each time you reload and your conversation comes back, update the extension to v2.1.301 or later. Then reload the window or restart VS Code again. After the conversation fails to finish opening twice in a row, you get a new chat in its place, with a notice that [it was not reopened](#a-conversation-was-not-reopened).
[](#a-formula-shows-as-raw-latex)
A formula shows as raw LaTeX
If none of the math in Claude’s responses is typeset, check the extension’s version in the Extensions view, because [math rendering](#latex-math-in-responses) requires version 2.1.301 or later. If you use [terminal mode](#switch-to-terminal-mode), which doesn’t typeset math whatever the version, uncheck the [Use Terminal setting](vscode://settings/claudeCode.useTerminal) so that Claude Code opens in the chat panel instead. If one formula shows as written while others near it are typeset, check it for these causes:
- **The formula is inline and the panel doesn’t treat it as math**: ask Claude to send it again as a `$$` block on its own lines. The panel leaves an inline formula as written when the text between its `$…$` delimiters:
- Is more than simple arithmetic yet has no character such as `=`, `+`, or `^` to mark it as math, as in `$O(n log n)$`
- Starts with a digit and has no such character, as in `$30$` and `$1/N$`
- Has spaces inside the dollar signs, as in `$ x^2 $`
- Is longer than 60 characters
- Is split across two lines. A `\(…\)` formula split across two lines isn’t typeset either.
- **The formula has a TeX syntax error**: ask Claude to rewrite it with the error corrected.
- **The formula defines a macro**: a formula with a macro definition such as `\newcommand` or `\def` shows as written. Ask Claude to rewrite it without the macro.
- **The formula contains an unescaped `%`**: ask Claude to rewrite it with `\%` for a percent sign.
- **The formula is too large**: a formula longer than 8,192 characters, or one whose typeset output would be far larger than its TeX source, shows as written. Ask Claude to split it into smaller formulas or to write it more compactly.
- **The formula follows a large amount of math**: within one block of text in a response, the panel typesets formulas in order up to a limit. A later formula that would go past the limit shows as written. Ask Claude to send the formula you need again by itself.
[](#dictation-or-the-web-tab-fails-behind-a-tls-inspecting-proxy)
Dictation or the Web tab fails behind a TLS-inspecting proxy
When dictation or the Web tab fails with a certificate error such as `unable to get local issuer certificate`, set [`NODE_EXTRA_CA_CERTS`](../13-Enterprise-Admin/network-config.md#custom-ca-certificates) in the `env` block of `~/.claude/settings.json`. Set it to the path of a PEM file with your proxy’s root CA certificate, which your IT team can give you. That error text is on the microphone button or in the extension’s logs:
- **Dictation**: the microphone button shows the error text after `Dictation error: WebSocket error:`.
- **Web tab**: the tab that lists [cloud sessions](#resume-cloud-sessions-from-claude-ai) shows `Remote server is not connected` without the error text. To read it in the logs:
1. Run **Claude Code: Show Logs** from the [Command Palette](#vs-code-commands-and-shortcuts) to open the `Claude VSCode` output channel.
2. Click **Reconnect** on the tab and wait until it stops showing `Connecting…`.
3. Search the channel for `Error fetching remote sessions:` or `Failed to fetch organization UUID:`, then read the error text after that prefix on the newest matching line.
This fix requires extension version 2.1.307 or later, so update the extension first. Then set `NODE_EXTRA_CA_CERTS` to the certificate file’s full path, written without `~`. For a Windows path, write each backslash twice in `settings.json`, as in `C:\\certs\\example-ca.pem`. This example names a certificate file at the Linux or macOS path `/etc/ssl/certs/example-ca.pem`:
~/.claude/settings.json
```python
{
"env": {
"NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/example-ca.pem"
}
}
```
Save `settings.json`, then start a recording or click **Reconnect** again. If the error comes back, open the output channel with **Claude Code: Show Logs** and search it for `use the CA certificates file`. Such a warning gives the reason the extension can’t use your file and says where it read the path. Then find each place you set `NODE_EXTRA_CA_CERTS` in this table and do what its row says:
| Where you set it | What to do |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| The environment VS Code was started with | A value set here takes precedence over one in `~/.claude/settings.json`, even when the file it names can’t be used. Correct or remove it, then restart VS Code |
| `env` in `~/.claude/settings.json` | Correct the value or the file it names, then start a recording or click **Reconnect** again |
| VS Code’s [`claudeCode.environmentVariables`](#extension-settings) setting, `~/.claude.json`, a project’s `.claude/settings.json` or `.claude/settings.local.json`, or managed settings | A value set here doesn’t apply to dictation or the Web tab. Set the variable in `env` in `~/.claude/settings.json` as well |
[](#claude-code-never-responds)
Claude Code never responds
If Claude Code isn’t responding to your prompts:
1. **Check your internet connection**: Ensure you have a stable internet connection
2. **Start a new conversation**: Try starting a fresh conversation to see if the issue persists
3. **Try the CLI**: Run `claude` from the terminal to see if you get more detailed error messages
If problems persist, [file an issue on GitHub](https://github.com/anthropics/claude-code/issues) with details about the error.
[](#uninstall-the-extension)
Uninstall the extension
To uninstall the Claude Code extension:
1. Press `Cmd+Shift+X` on Mac or `Ctrl+Shift+X` on Windows/Linux to open the Extensions view
2. Search for “Claude Code”
3. Click **Uninstall**
If you run `claude` in a VS Code integrated terminal, Claude Code reinstalls the extension automatically. To keep it uninstalled, turn off **Auto-install IDE extension** in `/config`, or set [`autoInstallIdeExtension`](../02-Claude-Code-CLI/settings-reference.md#autoinstallideextension) to `false`. You can also set the [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](../02-Claude-Code-CLI/env-vars.md) environment variable to `1`. To also remove extension data and reset all settings, delete the extension’s storage directory for your platform. On macOS:
```python
rm -rf ~/Library/"Application Support"/Code/User/globalStorage/anthropic.claude-code
```
On Linux:
```python
rm -rf ~/.config/Code/User/globalStorage/anthropic.claude-code
```
On Windows, in PowerShell:
```python
Remove-Item -Recurse -Force "$env:APPDATA\Code\User\globalStorage\anthropic.claude-code"
```
For additional help, see the [troubleshooting guide](../02-Claude-Code-CLI/troubleshooting.md).
[](#next-steps)
Next steps
Now that you have Claude Code set up in VS Code:
- [Explore common workflows](../02-Claude-Code-CLI/common-workflows.md) to get the most out of Claude Code
- [Set up MCP servers](../06-MCP-Tools/General/mcp.md) to extend Claude’s capabilities with external tools. Add and manage them with `/mcp` in the chat panel.
- [Configure Claude Code settings](../02-Claude-Code-CLI/settings.md) to customize allowed commands, hooks, and more. These settings are shared between the extension and CLI.
- [Review security safeguards](../13-Enterprise-Admin/security.md) and [data usage](../13-Enterprise-Admin/data-usage.md) for Claude Code