VS Code Integration

📚 Series Navigation: The previous article 07 First Use guided you to run through the first example in the terminal. This article moves Claude Code into VS Code—the same abilities, switched to a gameplay with a graphical interface.

When I first switched to using the VS Code extension, it was easy to do something pretty silly.

Claude Code was running perfectly fine in the terminal. After installing the extension to try the graphical interface, I opened an empty folder and searched high and low but just couldn't find the "Spark icon" (the spark-shaped icon in the toolbar, Claude Code's entry point in the IDE) the official guide mentioned. At this time it's easy to think the installation failed, uninstall and reinstall, restart, clear cache, tossing about for almost twenty minutes. Finally looking at the docs I realized—that icon only appears when you have a specific file open, just opening a folder is not enough. Looking for an icon in an empty workspace, you wouldn't find it in a lifetime.

Frankly, VS Code integration is not hard, but its interaction logic is a different set from the terminal, some "taking it for granted" will get you stuck on the very first step. This article will mark these pitfalls out for you in advance.

After reading this article, you will get:

• The complete steps to install the Claude Code extension in VS Code (including forks like Cursor), plus a troubleshooting checklist for "can't find the icon"
• How to use the three graphical interface-exclusive cool features: side-by-side diff (line-by-line review of changes), @ mention, and plan review
• A "Extension vs CLI which to use" comparison table, plus a set of common keyboard shortcuts

---

01 First Understand: What is the Relationship Between the Extension and the CLI

"I already know how to use claude in the terminal, do I still need to install the extension?" Conclusion first: The extension does not replace the CLI, it wraps a graphical interface around it. Installing the extension will bring the CLI along with it, both share the same ~/.claude/settings.json configuration; conversation history can be resumed, but it's not real-time sync—if you chat halfway in the extension, you can turn around and run claude --resume in the terminal to actively continue that conversation.

Analogy: The same back kitchen, two ordering windows. The CLI is shouting orders at the kitchen window—fast, complete, you can order anything; the extension is the lobby waiter, making the menu illustrated and visual, ordering and watching progress is more intuitive, but there are a few "hidden menu items" that can only be ordered by shouting at the window. The kitchen is the same one, the dishes are exactly the same.

When exactly to use which? The official guide gave a capability comparison, compiled as follows:

Feature	CLI (Terminal)	VS Code Extension
Commands and skills	All	Subset (Type / to see available)
MCP server config	Full	Partial (Add via CLI, manage via /mcp in panel)
Checkpoints	Supported	Supported
! bash shortcut	Supported	Not Supported
Tab completion	Supported	Not Supported
Side-by-side diff, select code as context	Needs connecting to IDE	Native, out of the box

In a word: Jobs like writing code, reviewing changes that "deal with files", the extension is obviously better to use; bash shortcuts like !ls and Tab completion are only in the CLI. The general usage is main force open in the extension, if you need to batch run commands or use commands not in the extension, just type claude directly in the integrated terminal—the history is connected, seamless switching.

💡 One-sentence summary: The extension and CLI are two faces of the same engine, sharing history and configuration, switch at any time according to the job at hand, no need to pick one or the other.

---

02 Installation: Three Postures, Plus Troubleshooting for Icon Not Found

Look at the Version First Before Installing

Official hard requirement: VS Code 1.98.0 or higher, below this version it won't install or won't work (Click "Help → About" to see the version number). Upon opening the extension for the first time it will ask you to log into your Anthropic account; for companies going through Bedrock, Vertex AI and other third-party providers, the configuration method is different, mentioned separately at the end.

Three Installation Methods

Method One: Search in the Extension Marketplace (Most stable, recommended for beginners)

In VS Code press Cmd+Shift+X (Mac) or Ctrl+Shift+X (Windows/Linux) to open the Extensions view, search Claude Code, click Install.

The image above is what it looks like searching Claude Code in the Extensions view: The one in the red box "Claude Code for VS Code", published by Anthropic with a blue verified checkmark is the official one, identify it and click in to install.

There is a pitfall beginners are most likely to step on here: searching Claude Code will pop up a bunch of extensions with similar names, make sure the publisher is Anthropic, don't mistakenly install a third-party fake.

Method Two: Click the link to install directly

While VS Code is open, clicking the link vscode:extension/anthropic.claude-code will jump directly to the extension installation page (Cursor replaces vscode: with cursor:).

Method Three: Non-mainstream editors / When it won't install

The extension can also be installed in other branches of VS Code (Cursor, Devin Desktop, Kiro, etc.)—search Claude Code in their extension view, or install from the Open VSX Registry. In case it absolutely won't install, don't bang your head against it, the official fallback solution is to directly run claude in the integrated terminal.

Domestic reminder: Installation, login authorization, and letting Claude work later all need to connect to Anthropic services, requiring a proxy throughout, consistent with the terminal version.

Icon Not Found After Installing? Follow This Checklist to Troubleshoot

This is the pitfall at the beginning. After installing, the extension defaults to not pop up a window, you have to call out the panel yourself. The fastest way: first open a specific file, then click the Spark icon in the toolbar at the top right of the editor (a little icon like a spark).

The image above marked the locations of three entries: The Spark icon at the top right of the editor (②, fastest but only appears when a file is open), the Spark in the Activity Bar (①, always there), ✱ Claude Code in the Status Bar (③, clickable even when no file is open).

The key is just one sentence: The Spark icon only appears when you have opened a file, just opening a folder is not enough. If you still can't see it, check in this official order:

Phenomenon	Troubleshooting Action
No icon at top right of editor	Open a file first (not just open a folder)
Opened file still nothing	Confirm VS Code ≥ 1.98.0 (Help → About)
Version is sufficient too	Run Developer: Reload Window in Command Palette to reload window
Reload useless too	Temporarily disable other AI extensions (Cline, Continue, etc.), might conflict
Workspace is in "Restricted Mode"	Extension does not work in restricted mode, need to trust workspace

If you really can't find the Spark icon, there are two alternative entries:

• Activity Bar (the vertical row of icons on the far left) Spark icon — This one is always there, clicking it opens the conversation list.
• Status Bar (bottom right of the window) ✱ Claude Code — Clickable even when no file is open, this one is usually more handy normally, saves worrying about whether a file is open. Can also go through Command Palette (Cmd+Shift+P / Ctrl+Shift+P) type Claude Code.

Clicking to open the panel for the first time will show the login screen, click Log In, complete authorization in the browser. (If you set ANTHROPIC_API_KEY but are still asked to log in, most likely VS Code didn't inherit the terminal environment variables, the official fix is to launch VS Code from the terminal using code . to bring the variables in.)

💡 One-sentence summary: Look for the Anthropic publisher when installing the extension, the Spark icon must have a file open to appear—if you can't find it open a file first, if still no go use the bottom right status bar entry.

---

03 diff View: Confront Changes Face to Face, Nod After Seeing Clearly

This is the feature that made many people fans of the extension earliest. When the terminal version modifies a file, the diff is drawn with text characters, which becomes strenuous to read when the file is large and changes are many. The extension moved this matter into VS Code's native diff view—red and green highlights mark additions and deletions, the same visual feel as you normally reading Git diffs.

Analogy: "Track Changes" comparison before signing a contract. The other party sends back the revised contract, original draft on the left, revised version on the right, every addition and deletion marked clearly—you are not signing with your eyes closed, you are putting pen to paper only after reading item by item. Claude modifying code is the same, laying out the changes to request permission, you have three choices: accept, reject, or directly tell it to change it to something else.

There is also a detail easily overlooked, which you will only notice after using it for a while: Before accepting, you can directly manually modify Claude's suggestion in the diff view, after modification it will know "you touched it" and won't proceed based on the old version. For example, asking it to refactor a 200+ line function, it changed seven or eight places in one breath, if scanning the diff you spot a place where boundary checking is written backwards, correct it on the spot on the right side and then accept, saving a round of back-and-forth.

💡 One-sentence summary: The diff view lays every change out in front of you, see clearly, can modify on the spot, then decide whether to accept, much safer than terminal text diffs.

---

04 @ Mention and Select Code: Feed Context Accurately

The biggest waste when letting Claude work, is it "doesn't know which piece of code you're talking about" so it goes in circles guessing. The extension has two tricks to feed context both fast and accurately.

Trick One: @ Mention file / folder

Type @ in the prompt box, followed by the file name or folder name, and Claude will go read that content. It supports fuzzy matching, no need to type the full name:

> Explain the logic in @auth (will auto-match auth.js, AuthService.ts, etc.)
> What is in @src/components/ ? (Remember to add the trailing slash / for folders)

Analogy: Throwing documents into the group chat before a meeting. Instead of verbally describing "that file related to login", it's better to directly @ toss the file to it, saving it from rummaging through the whole project and finding the wrong one. For super large PDFs you can even let it only read specific pages (like pages 1-10), no need to chew through the whole book.

Trick Two: Select code, it automatically sees it

This trick is even less trouble than @: Directly select a piece of code in the editor, and Claude automatically sees it, below the prompt box will show "2 lines selected". You directly ask "why does this section error", it knows which section you mean.

A few commonly used companion skills:

• Insert citation with line numbers: Press Option+K / Alt+K, automatically inserts a mention with path and line numbers like @app.ts#5-10 (requires editor focus).
• Temporarily don't let it see selection: Click the "Selection Indicator" at the bottom of the prompt box to toggle, if a "slashed eye" icon appears it means this section is hidden from Claude—selection is only for when you want to copy.
• Drag file as attachment: When dragging a file to the prompt box hold down Shift; click the × on the attachment to remove it.

For example, troubleshooting a style bug, CSS nested five or six layers. Directly select that suspicious rule section toss a sentence "why does this not take effect here", it pinpoints in two rounds that it's the parent element's overflow: hidden that clipped the child element—if you just used words to describe that nesting, you'd be typing for a long time.

⚠️ Selected text and the currently open file are sent to Claude along with the prompt by default. For sensitive files like .env, the official recommendation is to add a Read deny rule for the path, once matched it will not reach Claude (subject to official documentation).

💡 One-sentence summary: @ mention feeds files, select code automatically feeds context—directly eliminating the biggest guessing cost of "which section are you talking about".

---

05 Plan Review: Let It Submit a Proposal First, You Approve Before It Acts

This section is probably where the extension improves experience the most compared to the terminal. Let's talk about permission modes first: click the Mode Indicator at the bottom of the prompt box to switch, Claude Code has these few gears:

Mode	Claude's Behavior	When to Use
Normal Mode (Default)	Asks for your consent before every operation	Unfamiliar tasks, want to gatekeep throughout
Plan Mode	Describes what it plans to do first, waits for your approval to act	Large changes, multiple files, want to see plan first
Auto-Accept Mode	Directly modifies, no longer asks one by one	Trustworthy small batch repetitive changes

There is also a fourth gear bypassPermissions (bypasses all permission checks), requires enabling allowDangerouslySkipPermissions in settings, only suitable for completely isolated sandbox environments, not recommended for daily use.

Analogy: Whether the intern asks you before taking action. Normal mode is "raise hand and ask before every step", auto-accept is "let go and let him work"—and plan mode is the most special, like the intern first handing you a "here's what I plan to do" proposal for you to look over, and you nod before he starts work.

Plan mode has a treatment in VS Code that the terminal can't give: Claude will automatically open the plan as a complete Markdown document, and you can add inline comments on it. Instead of generally replying "step two is wrong", you can directly write "don't touch the database here, add cache first" next to the "step two" line, and it will absorb your opinion before starting work—much more precise than verbal rework.

The image above is the Markdown plan document opened by plan mode: Claude lists out every step, you write an inline comment next to the "Step 2" line ("don't touch database, add memory cache first"), and it absorbs this opinion before getting approval to start work.

Want to make it the default? Change claudeCode.initialPermissionMode in settings to plan. A safe habit is any change that is "multi-file, over 50 lines", switch to plan mode first. There is a common lesson here: for convenience, keeping auto-accept on the whole time, letting it add logging to a module, it might conveniently "optimize" the import order of several files along the way, later you have to spend ten minutes sorting out which places it touched. For major changes, always look at the plan first, bounding it at the proposal stage, much cleaner than cleaning up afterwards.

💡 One-sentence summary: Plan mode = Look at proposal before acting, can also comment item by item on the Markdown plan—switch to it before multi-file large changes, saves tons of rework.

---

06 Hands-on Segment: 10 Minutes to Run Through Graphical Interface Full Process

Below we walk through from scratch, every step gives "what you should see", just follow along to self-verify if you installed it right and know how to use it.

Step 0: Create a minimal practice project

No need for a real project, just a new empty folder with a file. Run in terminal:

mkdir vscode-claude-demo && cd vscode-claude-demo
printf 'def greet(name):\n    return "Hello " + name\n\nprint(greet("world"))\n' > demo.py
code .

Expected: VS Code opens this folder, in the left Explorer you can see demo.py. (If code CLI tool is not installed, open this folder manually.)

Step 1: Open Claude Panel and Log In

Click open demo.py (remember, must have a file open), click the Spark icon at top right, first time login screen appears click Log In, complete authorization in browser.

Expected: Claude Code chat panel appears on the right, top no longer shows "Not Logged In".

Step 2: Select Code + Let it modify, see inline diff

Select those two lines of greet function in demo.py, below prompt box should show "2 lines selected". Then type:

Help me change it to use f-string, and add type annotations

Expected: Claude doesn't ask you "which function" (meaning selected context was fed in), directly pops up side-by-side diff—right side changed return "Hello " + name to return f"Hello {name}", signature added type annotations, bottom shows Accept / Reject prompt. See clearly then click Accept.

Step 3: Try Plan Mode once

Click mode indicator at bottom of prompt box to switch to Plan Mode, input a slightly larger requirement:

Add command line argument support to this file, letting user pass in name from terminal

Expected: Claude doesn't modify file directly, first opens a Markdown plan document listing what it intends to do (e.g. import argparse). You confirm or write comments next to a step, then it executes. Running to this step, you have used all three core features: inline diff, mention selection, and plan review once.

---

07 Handy Collection: Common Shortcuts and "Switch to CLI"

A set of common shortcuts (from official, platform differences marked):

Operation	Shortcut	Note
Toggle Focus (Editor ↔ Claude)	Cmd+Esc / Ctrl+Esc	Whichever panel cursor is in, shortcut acts there
Open chat in new tab	Cmd+Shift+Esc / Ctrl+Shift+Esc	Open several chats to work in parallel
Insert @ mention citation	Option+K / Alt+K	Requires editor focus
Reopen just closed session	Cmd+Shift+T / Ctrl+Shift+T	Enabled by default
Start new conversation	Cmd+N / Ctrl+N	Disabled by default, need to enable enableNewConversationShortcut in settings

macOS Tahoe+ has a pitfall: System "Game Overlay" occupies Cmd+Esc by default, intercepting it. Go to "System Settings → Keyboard → Keyboard Shortcuts → Game Controller" and clear that checkmark, or rebind Claude Code: Focus input to another key.

Want to go back to CLI style interface? Open integrated terminal (Cmd+` / Ctrl+`) and run claude—CLI will automatically connect to VS Code, can still use native diff (external terminal runs /ide to manually connect); or check Use Terminal (useTerminal) in settings to let extension directly launch in terminal mode.

Third-party providers (Bedrock / Vertex AI / Foundry): First check Disable Login Prompt (disableLoginPrompt), then configure ~/.claude/settings.json according to provider guide (subject to official docs).

💡 One-sentence summary: Cmd+Esc toggle focus most used, Option+K insert citation, want terminal flavor run claude or check useTerminal—graphic and command line switch as you please.

---

08 Summary

This article moved Claude Code from the terminal into VS Code, the core is just these few things:

• Extension ≠ Replace CLI: Same engine, shared history and config, write code use extension, want CLI exclusive features switch to terminal.
• First hurdle of installing is finding the icon: Identify Anthropic publisher, Spark icon must have file open to appear, if can't find use bottom right status bar entry.
• Three graphical interface sweet spots: Side-by-side diff (nod after seeing clearly, can modify on spot), @ mention / select code (feed accurate context), plan review (see proposal first, can comment item by item).

You should now be able to independently install the extension, use side-by-side diff to review changes, use @ and selection to feed accurate context, switch to plan mode before major changes. Once this flow runs smoothly, you can stably rely on it for daily coding.

---

Next article 09 JetBrains Integration—if your main force is the JetBrains family like IntelliJ IDEA, PyCharm, Claude Code also has a native plugin. We will see what's the same and different between it and the VS Code extension, as well as a few configuration points unique to JetBrains users.

---

Recommended Reading

• Voice Mode: Speak your prompts instead of typing them
• Web and Cloud: Put Claude Code in your browser and phone
• Images and Multimodal: Paste a screenshot, it understands