VS Code

The Claude Code extension gives VS Code (and forks such as Cursor) a native chat panel for Claude Code. You can review and edit plans before they run, accept edits change by change, mention files with exact line ranges, keep several conversations open in tabs, and browse your history, all without leaving the editor. It is the recommended way to use Claude Code inside VS Code, and it is where I spend most of my front-end time.

Requirements

• VS Code 1.94.0 or later.
• A paid Claude plan (Pro, Max, Team or Enterprise) or a Claude Console account. No API key needed; you sign in the first time you open the panel. For Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, see third-party providers.

Tip: The extension bundles its own private copy of Claude Code for the chat panel. It does not put claude on your PATH. To run claude in the integrated terminal you also need the standalone install described in advanced setup.

Installing

• In VS Code, open Extensions (Cmd+Shift+X on macOS, Ctrl+Shift+X elsewhere), search for "Claude Code" and click Install. Cursor works the same way.
• Other forks such as Devin Desktop or Kiro can install it from their Extensions view or the Open VSX registry. If your editor cannot install it, install the CLI and use claude in its terminal.
• For dev containers, see development containers.

The extension's version number is the Claude Code version it bundles, so a feature needing v2.1.286 needs extension version 2.1.286 or later. If it does not appear after installing, restart VS Code or run Developer: Reload Window.

First steps

1. Open the panel

The Spark icon marks Claude Code throughout VS Code. Ways in:

• The Spark icon in the Editor Toolbar at the top right (only shown with a file open).
• The Spark icon in the Activity Bar, which opens the sessions list (always visible).
• The Command Palette (Cmd+Shift+P / Ctrl+Shift+P), typing "Claude Code" and choosing, for example, Open in New Tab.
• ✻ Claude Code in the Status Bar at the bottom right, which works with no file open.

2. Sign in

Click Sign in and finish in your browser. If you later see Not logged in · Please run /login, the sign-in screen reopens automatically (if not, reload the window). If you have ANTHROPIC_API_KEY set but still get the sign-in prompt, VS Code probably did not inherit your shell environment: launch it with code . from a terminal, or sign in with your Claude account.

A Learn Claude Code checklist follows; click Show me on each item or dismiss it. To bring it back, untick Hide Onboarding under Extensions → Claude Code. Claude Code: Open Walkthrough in the Command Palette gives a guided tour.

3. Ask something

Claude sees your selected text automatically. Press Option+K (macOS) or Alt+K (Windows and Linux) to insert an explicit reference like @checkout.ts#40-62.

@checkout.ts#40-62 why does this recalculate shipping twice?

4. Review changes

What happens depends on the permission mode shown under the prompt box:

• Auto or Edit automatically: most workspace files are edited without asking.
• Manual: each edit shows a side-by-side diff and asks for approval. Accept, reject, or tell Claude what to do instead. If you tweak the proposed content in the diff before accepting, Claude is told so it does not assume its original version landed.

With v2.1.275 or later you can review hunk by hunk using Accept this change and Reject this change under each change (also available at the cursor via the context menu or Claude Code: Accept Change at Cursor / Reject Change at Cursor). Rejecting reverts that hunk in the proposal; accepting or rejecting the whole file still finishes the review. Diffs with more than 100 changes skip the per-change buttons.

The prompt box

Permission modes

Click the mode indicator to switch. From v2.1.283, Auto is the built-in starting mode (earlier, only on Pro, Max and Team). Permission modes explains how the extension picks the starting mode.

• Auto: a classifier reviews most actions instead of you.
• Manual: asks before edits and most shell commands.
• Plan: Claude describes what it will do and waits. The plan opens as a full Markdown document where you can leave inline comments. With v2.1.280 or later you can also type /plan (switch to plan mode, or show the current plan if already there), /plan <task> (switch and start planning), or /plan open (open the plan file in the editor).
• Edit automatically: edits without asking.

Model and effort

Pick Switch model… from the command menu, click the model name under the prompt box, or (v2.1.284 or later) type /model. When the model supports effort levels, the picker shows an Effort row and the button shows the chosen level (v2.1.257 or later). Any level except max is saved as your default for that model under modelSettings in user settings; max lasts for the session only.

With dynamic workflows enabled and a supporting model, an Ultracode switch under Effort has Claude plan a workflow for each substantive task in the session; the button then shows · Ultracode (v2.1.284 or later).

The command menu

Click or type / to open it. Besides attaching files, switching model and toggling extended thinking, its sections include:

Items with a terminal icon open in the integrated terminal.

Other prompt box features

• Side questions: /btw <question> asks about the session without adding to the conversation. The answer opens in a side panel for follow-ups, survives reloads, keeps the latest 20 exchanges and expires on the cleanupPeriodDays schedule. Clear it with the trash icon (v2.1.227).
• Copy: hover a reply and click Copy response, or /copy (latest) and /copy 2 (second-to-last) (v2.1.277).
• Bookmarks: hover a reply and click Bookmark response; review them via the bookmark icon at the top of the panel, Bookmarks in the menu, or /bookmarks (v2.1.286).
• Context indicator: shows how full the context window is. Compaction is automatic, or run /compact.
• Prompt cache clock: next to the context indicator, a countdown of how long the prompt cache probably has left (five minutes or one hour), restarting with each cached response. When it hits zero, or right after compaction, it turns red with no minutes until the next reply, warning that the next message will be slower and dearer. Cache-breaking actions other than compaction do not reset it, so it may still show time after a model switch.
• Agent map: when subagents are involved, an agent count (such as 2 agents) appears with a status dot. Click it to see the subagent tree with status, elapsed time and tokens; click one to see its prompt and tool calls, open its read-only transcript or stop it (v2.1.269). Background shell commands and monitors are listed underneath, and /tasks opens the map when no count is showing (v2.1.277). From v2.1.286, Stop or Esc ends the turn but background agents keep going until they finish or you stop them here.
• Extended thinking: toggle in the command menu. Thinking appears as collapsed blocks; Ctrl+O expands or collapses them all.
• Multi-line input: Shift+Enter, including in a question dialog's "Other" box.

Mentioning files and folders

Type @ and part of a name; matching is fuzzy:

how does @PaymentSer handle retries?
summarise everything in @src/emails/

Add a trailing slash for folders. For large PDFs you can ask for specific pages (one page, a range, or from a page onwards), which needs poppler-utils installed where Claude Code runs.

Selected text is shared automatically and the prompt footer shows how many lines. Click the X on the selection indicator to withhold it; it returns when you select something else. Claude also sees which file is open even with nothing selected; turn off Attach Open File (attachOpenFile, v2.1.271) to send only selections.

The chat panel withholds selections from some files: workspace files matching files.exclude or search.exclude (Claude gets the path at most), and gitignored files when both search.useIgnoreFiles and the extension's respectGitIgnore are on (the default). This filter only covers the chat panel. When Claude Code runs in the integrated terminal, selections are sent regardless, so use a Read deny rule to protect a file there.

Paste images straight into the prompt box, or hold Shift while dragging files in. Click the X on an attachment to remove it.

Pasting

Pasted text stays visible rather than collapsing to a placeholder as it does in the terminal, though Claude still knows a large paste was pasted. Invisible Unicode characters are stripped from pastes and from anything you send. A notice like Removed 3 invisible characters from the pasted text on paste means they were removed; a similar notice on send means nothing was sent and the cleaned text is back in the box for you to send again.

Account and usage

/usage opens Account & usage. On a claude.ai plan it shows usage bars with reset times, flags behaviours behind 10% or more of recent usage (cache misses, long context, heavy subagent or parallel use) with tips, and breaks usage down by skill, subagent, plugin and MCP server, over the last day or week. Figures are approximate and only cover sessions on this machine. On a third-party provider or API key it shows session cost and tokens instead, also visible under Account & usage in the Activity Bar sessions list (v2.1.277). See costs.

Sessions

History

Click Session history at the top of the panel to search or browse by time. Clicking a conversation resumes it with full history (or switches to its tab if already open). New sessions get AI-generated titles. Hover to Rename or Archive.

If the conversation is open in another Claude Code process (a terminal or another window), you see This conversation is still open somewhere else. Using it in two places at once can mix up its messages. Close it elsewhere, then click Open here anyway. With claudeProcessWrapper set, this check is skipped.

Sessions idle for 14 days move to Archived sessions automatically unless open, unread or grouped (v2.1.265); change this with archiveInactiveSessions (1, 2, 7 or 14 days, or 0 to disable). Restore one with Unarchive session, or all at once from the Archived sessions header in the Activity Bar list (v2.1.277). Before v2.1.257 the action was Delete session; those sessions reappear as archived after upgrading.

A conversation that ended in plan mode resumes in plan mode (v2.1.246), except when the starting mode comes from initialPermissionMode or a carried-over pick, or when claudeProcessWrapper is set. Sessions covers resuming generally.

Cloud sessions

If you use cloud sessions and signed in with a claude.ai subscription (not Console), open Session history, choose the Web tab and pick a session to continue it locally. If your open folder is a GitHub repository, only that repo's sessions are listed. The extension downloads a copy; changes do not sync back to claude.ai. If any part fails to download, nothing is saved and you can retry.

The Web tab also lists Remote Control sessions. One that ran in your open folder opens as the local conversation itself (focusing its tab if open), unless another process might have it open, in which case you get a copy.

After a reload

After Developer: Reload Window or a restart, a conversation in an editor tab comes back with its tab; one in the sidebar comes back only if there was activity in the last 10 minutes (otherwise use Session history). If a reload interrupted Claude mid-step, it continues that step with a notice (v2.1.274), unless the interruption was over an hour ago or the session is open elsewhere. Turn this off with continueAfterReload. CLAUDE_CODE_RESUME_INTERRUPTED_TURN and other CLAUDE_CODE_RESUME_ variables are stripped from the panel's environment and have no effect there.

Several conversations

Open in New Tab and Open in New Window start more conversations, each with its own context. A dot on a tab's Spark icon is blue for a pending permission request and orange when Claude finished while the tab was hidden.

Groups and filters

From v2.1.229, right-click sessions in the Activity Bar list to create groups, move sessions between them or remove them. Cmd/Ctrl-click or Shift-click to move several. Claude Code: Add Session Tab to Group works from a tab (v2.1.257). Right-click a group header to rename or delete it (sessions return to the ungrouped list). Groups are saved per workspace folder. Searching shows a flat list.

From v2.1.271, two filters sit at the top of the list: Active (sessions needing input, working, unread, plus the last focused one) and a funnel for Needs input, Working, Completed, Open and Closed. "Open" means it has a tab here or is running in another Claude Code process on the machine. Archived sessions are hidden while filtering. Filters persist across reloads.

Panel placement

Drag the panel's tab or title bar to the secondary sidebar (right), primary sidebar (left) or editor area. When Claude opens a tab in a new editor group it locks that group so your files open elsewhere; turn off lockEditorGroups to stop that (v2.1.274). I keep my main session in the right sidebar and open tabs for side tasks.

Terminal mode

Prefer the CLI look? Tick Use Terminal (useTerminal) under Extensions → Claude Code.

Plugins

Type /plugins to open Manage plugins, which drives the same CLI commands underneath, so anything configured here also appears in the CLI.

Plugins tab. Installed plugins have toggles; turning off one that the shared .claude/settings.json enables asks whether to Disable for me or Disable for everyone. A plugin that failed to load shows a reason you can click for next steps. Available plugins are listed below with search. Click Install and choose a scope: Install for you (user), Install for this project (project) or Install locally (local). A form then asks for any unset configuration options; sensitive fields are masked and a saved secret shows (unchanged) (leave blank to keep it). Change options later with the gear icon. After saving, sessions reload their plugins and the dialog shows Restart Claude to apply plugin changes.

Uninstalling. Each row names its scope; click the trash icon to remove that installation (dimmed when you cannot, such as managed plugins or ones installed for another project). For a plugin enabled by the shared project settings you choose Disable for me or Uninstall for everyone (which uses --keep-data). For the last installation of a plugin with saved data, you choose whether to keep the data (the default) or delete it.

Marketplaces tab. Add a GitHub repo, URL or local path; refresh to update the list; the trash icon removes a marketplace and uninstalls every plugin from it after confirming. Changes apply immediately to sessions in that window; if a session cannot reload, you are offered a retry or a restart.

Sharing an install link

Send someone straight to a plugin with:

vscode://anthropic.claude-code/install-plugin?plugin=commit-helper&marketplace=acme/claude-plugins

Opening it focuses VS Code, opens the panel and the dialog at the scope choice; nothing installs until a scope is picked, and an unknown marketplace must be added first. Bad links show Invalid plugin installation URL. The dialog stops with a message if the plugin is not found, is already installed, or a different marketplace with the same name exists. Many Markdown hosts (GitHub included) strip non-http links, so put the URL in a code block there. See deep links and installing plugins.

Browser automation

With the Claude in Chrome extension (1.0.36 or later), type @browser and a task:

@browser open localhost:5173, log in as the demo user and check the console for errors on the dashboard

The attachment menu also lets you pick specific browser tools. Claude opens new tabs and shares your browser's logins. To connect at session start without typing @browser, enable Chrome by default. The Chrome page covers setup, permission prompts in VS Code sessions and troubleshooting.

Commands and shortcuts

Shortcuts depend on focus: the editor when your cursor is in a file, Claude when it is in the prompt box. Cmd+Esc / Ctrl+Esc toggles. Type "Claude Code" in the Command Palette to see everything.

Opening a tab from other tools

The extension handles vscode://anthropic.claude-code/open. Open it with open (macOS), xdg-open (Linux, from xdg-utils), Start-Process (PowerShell) or start "" "<url>" (CMD, where the empty title is required). It launches VS Code if needed, otherwise uses the focused window.

For example, a shell alias I use:

alias cr='open "vscode://anthropic.claude-code/open?prompt=review%20my%20uncommitted%20changes"'

To open a terminal session instead, use the CLI's claude-cli:// links (deep links).

Settings

Two kinds:

• Extension settings in VS Code (Cmd+, / Ctrl+,, then Extensions → Claude Code, or General config… from the / menu).
• Claude Code settings in ~/.claude/settings.json, shared with the CLI: permissions, environment variables, hooks, MCP servers. They also feed into the starting permission mode. See settings.

Tip: Add "$schema": "https://json.schemastore.org/claude-code-settings.json" to your settings.json for autocomplete and validation in VS Code.

Screen readers

From v2.1.236 the chat panel works with screen readers with nothing to enable (separate from the CLI's opt-in accessibility mode). It announces:

• Each reply once it is complete (code blocks as a line-count summary, links by label, tables cell by cell).
• Permission requests (naming the tool), questions from Claude, and plans awaiting review.
• When Claude starts working, is ready for input, or starts compacting.
• "Message queued." for messages sent while Claude works.
• Errors, the usage-credits consent prompt and the flagged-request prompt.

A text label replaces the spinner. Reopening or switching sessions is silent until something new happens.

Each turn starts with a hidden heading named after its prompt, so heading navigation jumps between turns. Within a turn, messages are announced as "You", "Claude", "Claude, Bash" (tool steps) or "Claude, thinking". Tab reaches the transcript region; Claude Code: Focus last message jumps to the newest message or prompt. Where a permission option saves a rule, its label names the destination (such as "all projects"), and Left/Right changes it (v2.1.268).

Extension versus CLI

Checkpoints

Hover a message and use the rewind button: Fork conversation from here (new branch, code untouched), Rewind code to here (revert files, keep history) or Fork conversation and rewind code. See checkpointing.

Using the CLI inside VS Code

Open the integrated terminal and run claude (after the standalone install); it connects to the editor automatically for diffs and diagnostics. From an external terminal, run /ide inside Claude Code. If claude is still not found, check your PATH (troubleshoot installation).

The extension and CLI share history: claude --resume in a terminal lists extension conversations too.

Reference a terminal's output with @terminal:name, where name is the terminal's title.

Background work

From v2.1.287, when a command has run for about two seconds, or as soon as a subagent starts, a Run in background button appears under its tool call. Click it and Claude stops waiting and carries on; the task notifies Claude when done. /tasks opens the agent map to check or stop it, and a background command's card shows its latest output live (v2.1.277).

MCP

/mcp in the chat panel adds and removes servers at local, user or project scope, enables, disables and reconnects them, and handles OAuth (adding and removing from v2.1.261). claude mcp add in the terminal writes to the same configuration; changes apply to conversations started afterwards.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

claude mcp add does not validate credentials, so check with /mcp in a new conversation that the server shows Connected rather than Failed. See MCP.

Git

Ask Claude to commit, open pull requests or summarise changes; descriptions are based on the actual diff. For isolated parallel work, see worktrees.

Third-party providers

To use Bedrock, Google Cloud's Agent Platform or Foundry:

1. Tick Disable Login Prompt (disableLoginPrompt).
2. Configure the provider in ~/.claude/settings.json so the CLI and extension share it: Amazon Bedrock, Google Vertex AI, Microsoft Foundry.

Features needing a claude.ai account (plan usage bars, voice dictation, the Web tab) are unavailable, and any leftover claude.ai login is ignored.

Security

Your code is not used to train models; see data usage. With auto-edit permissions, Claude could modify VS Code files such as settings.json or tasks.json that VS Code may execute. For untrusted code, use VS Code's Restricted Mode, prefer Manual mode for edits, and review changes before accepting.

The built-in IDE MCP server

While active, the extension runs a local MCP server named ide that the CLI connects to for diffs, selections and, in Jupyter notebooks, running cells. It is hidden from /mcp, but matters if you allowlist MCP tools with a PreToolUse hook.

• Context: each prompt carries your selection and the active file's path (shown as ⧉ Selected N lines from <file>). Queued messages keep the selection from when you pressed Enter. A Read deny rule blocks both for a file. With attachOpenFile off, the path is only sent while text is selected.
• Transport: bound to 127.0.0.1 on a random port between 10000 and 65535 (not configurable), unencrypted ws://. Each activation writes a fresh token to ~/.claude/ide/<port>.lock (or under CLAUDE_CONFIG_DIR), with 0600 permissions in a 0700 folder; the CLI sends it in X-Claude-Code-Ide-Authorization.
• Model-visible tools: of about a dozen tools, only two reach Claude.

In the chat panel (v2.1.285 or later), diagnostics come from a separate built-in server, claude-vscode, as mcp__claude-vscode__getDiagnostics, which can cover one file or all files with diagnostics. A Read deny rule does not block either diagnostics tool, so deny both by name if needed:

{
  "permissions": {
    "deny": ["mcp__ide__getDiagnostics", "mcp__claude-vscode__getDiagnostics"]
  }
}

mcp__ide__executeCode never runs silently: the code is added as a new cell at the end of the active notebook, scrolled into view, and a Quick Pick asks Execute or Cancel. Cancelling or pressing Esc returns an error. It refuses outright without an active notebook, the Jupyter extension (ms-toolsai.jupyter), or a Python kernel. A hook allowlist entry only lets Claude propose a cell; the Quick Pick is what lets it run.

Troubleshooting

Extension will not install. Check VS Code is 1.94.0 or later and allowed to install extensions, or install from the Visual Studio Marketplace directly.

No Spark icon. Open a file (a folder alone is not enough), check the VS Code version, reload the window, temporarily disable other AI extensions such as Cline or Continue, and make sure the workspace is not in Restricted Mode. The Status Bar item and Command Palette work regardless.

Cmd+Esc does nothing on macOS. On macOS Tahoe and later, the Game Overlay shortcut grabs Cmd+Esc. Clear it under System Settings → Keyboard → Keyboard Shortcuts → Game Controllers, or rebind Claude Code: Focus input in VS Code's Keyboard Shortcuts editor.

No response at all. Check your connection, start a new conversation, and try claude in a terminal for more detailed errors. If it persists, file an issue on the Claude Code GitHub repository.

Uninstalling

Uninstall from the Extensions view. Running claude in a VS Code terminal reinstalls it automatically unless you turn off Auto-install IDE extension in /config, set autoInstallIdeExtension to false, or set CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1.

To wipe its data and settings too:

# macOS
rm -rf ~/Library/"Application Support"/Code/User/globalStorage/anthropic.claude-code
# Linux
rm -rf ~/.config/Code/User/globalStorage/anthropic.claude-code

# Windows
Remove-Item -Recurse -Force "$env:APPDATA\Code\User\globalStorage\anthropic.claude-code"

Related

• JetBrains IDEs
• Permission modes
• Claude in Chrome
• Settings
• Common workflows