Claude Code is Anthropic's agentic coding tool, built to operate directly within a developer's terminal and editor environment. For developers working in VS Code, setting up Claude Code correctly means the difference between a context-aware AI pair programmer and a frustrating, context-blind assistant. This guide walks through the full 2025 installation flow, including CLI setup, VS Code extension integration, optimized settings.json configuration, and the context-management techniques that determine output quality.

How to Set Up Claude Code in VS Code

1. Install Node.js 18+ and VS Code 1.85+ (Windows users must use WSL2)
2. Create an Anthropic account and set up API access via OAuth or an API key
3. Run npm install -g @anthropic-ai/[email protected] to install the CLI globally
4. Authenticate by launching claude in your terminal and completing OAuth or setting your API key securely
5. Install the official Claude Code VS Code extension from the marketplace and configure keybindings
6. Optimize your settings.json with auto-save, file watcher exclusions, and terminal configuration
7. Create a CLAUDE.md file at your project root with coding conventions and a .claudeignore to scope context
8. Verify the setup by running a real task and confirming diff review and Git integration work correctly

Table of Contents

• Prerequisites: What You Need Before Installing Claude Code
• Installing Claude Code via the CLI
• Integrating Claude Code into VS Code
• Optimizing VS Code Settings for Claude Code
• Setting Up Project Context for Better Results
• Verifying Your Setup: A Quick Test Drive
• Troubleshooting Common Setup Issues
• Summary and Next Steps

Prerequisites: What You Need Before Installing Claude Code

System Requirements

Claude Code runs natively on macOS 10.15+ and Linux (Ubuntu 20.04+/Debian 10+). Windows users must operate through WSL2 with a Linux distribution (e.g., Ubuntu 22.04); Anthropic does not provide native Windows support. Node.js must be installed inside the WSL2 Linux environment, not on Windows itself. The runtime dependency is Node.js version 18 or higher, which provides the JavaScript engine and npm package manager that Claude Code relies on. VS Code version 1.85 or later is required for the extension to work correctly, including inline Git blame decorations and the integrated terminal features Claude Code uses.

Anthropic Account and API Access

Two authentication paths exist. The first is a direct API key generated through the Anthropic Console at console.anthropic.com. After creating an account, navigate to "API Keys" and generate a new key. This path requires adding a payment method and operates on usage-based billing. The second path is through a Claude Pro ($20/month) or Claude Max subscription, which provides access through OAuth without separate API billing. Pricing is subject to change; verify current plans and tier details at anthropic.com/pricing before subscribing. The Max plan matters most for heavy Claude Code usage because agentic coding workflows can involve dozens of API calls per task; check current rate-limit thresholds at docs.anthropic.com/en/docs/rate-limits to confirm the tier fits your workload.

Before proceeding, verify system readiness:

# Check Node.js version (must be 18+)
node -v

# Check npm version (this guide assumes npm v8 or higher)
npm --version

# Verify VS Code CLI is available in PATH
code --version

If node -v returns a version below 18, upgrade via nvm (nvm install 20) or the official Node.js installer. If code --version is not recognized, open VS Code, press Ctrl+Shift+P, type "Shell Command: Install 'code' command in PATH," and execute it.

Installing Claude Code via the CLI

Global Installation with npm

Anthropic distributes Claude Code as an npm package under the @anthropic-ai/claude-code scope. Global installation makes the claude command available system-wide. Pin to a specific version to ensure reproducibility and avoid unexpected breaking changes:

# Install Claude Code globally, pinned to a specific version.
# Check the current stable version at: https://www.npmjs.com/package/@anthropic-ai/claude-code
# Replace X.Y.Z with the version you have validated.
npm install -g @anthropic-ai/[email protected]

# Verify installation — output should match the pinned version
claude --version

A common stumbling block is the EACCES permission error, which occurs when root owns the global npm directory. The recommended fix is to reconfigure npm's prefix to a user-owned directory rather than using sudo:

# Step 1: Create user-owned npm global directory
mkdir -p ~/.npm-global
ls -la ~ | grep npm-global   # Verify directory is owned by current user

# Step 2: Configure npm prefix
npm config set prefix '~/.npm-global'

# Step 3: Persist PATH to shell profile (choose the correct file for your shell)
SHELL_PROFILE="${HOME}/.zshrc"   # Change to ~/.bashrc for bash
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> "$SHELL_PROFILE"

# Step 4: Apply immediately to current session
source "$SHELL_PROFILE"

# Step 5: Verify persistence — open a NEW terminal, then run:
which claude   # Expected: /home/<user>/.npm-global/bin/claude

Authenticating Claude Code

The first run of claude triggers the authentication flow:

# Navigate to your project directory first
cd ~/projects/my-app

# Launch Claude Code for the first time
claude

# For Max/Pro subscribers: a browser window opens for OAuth authentication
# Follow the prompts to authorize Claude Code with your Anthropic account

OAuth authentication opens a browser window where the user authorizes Claude Code against their Anthropic account. This is the default for Max subscribers and requires no manual key management. Consult Anthropic's documentation for details on OAuth token lifetime and refresh behavior.

For API key authentication, set ANTHROPIC_API_KEY as an environment variable. Do NOT write the raw key to your shell profile, as this exposes it to all child processes, logging tools, and any process that calls env. Instead, use one of the following secure approaches:

# SECURE: Store the API key using your OS keychain or a secrets manager.
# Do NOT write the raw key to your shell profile.

# Option A: Set for the current session only (key read from a protected file):
export ANTHROPIC_API_KEY="$(cat ~/.secrets/anthropic_key)"

# Option B: Use a secrets manager (e.g., 1Password CLI):
export ANTHROPIC_API_KEY="$(op read 'op://Private/Anthropic/api-key')"

# Option C: Use a .env file managed by direnv (never commit .env):
# Add to .envrc:  export ANTHROPIC_API_KEY="sk-ant-..."
# Run:            direnv allow

# Verify the variable is set (value is intentionally hidden):
echo "Key set: $([ -n "$ANTHROPIC_API_KEY" ] && echo YES || echo NO)"

# Then launch Claude Code:
claude

Both OAuth and API key methods result in a fully authenticated session. API keys persist until revoked.

For developers working in VS Code, setting up Claude Code correctly means the difference between a context-aware AI pair programmer and a frustrating, context-blind assistant.

Integrating Claude Code into VS Code

Option 1: Using Claude Code as a VS Code Extension

Anthropic publishes the official Claude Code extension on the VS Code marketplace. To install it, open VS Code, go to the Extensions panel (Ctrl+Shift+X), search for "Claude Code" by Anthropic, and click Install. Alternatively, use the CLI:

# Step 1: Verify the exact extension ID in the VS Code Marketplace BEFORE installing.
# Visit: https://marketplace.visualstudio.com/search?term=Claude+Code&target=VSCode
# The publisher.extensionname format is case-sensitive.

# Step 2: Install using the verified ID
code --install-extension anthropic.claude-code

# Step 3: Confirm installation — ID in output must exactly match Marketplace listing
code --list-extensions | grep -i claude
# Expected output (example — verify against current Marketplace ID):
# anthropic.claude-code

Once installed, open Claude Code via the command palette: press Ctrl+Shift+P (or Cmd+Shift+P on macOS), then type "Claude Code: Open" and select it. The extension provides a dedicated panel that embeds Claude Code's interface within VS Code, including diff viewing, file navigation awareness, and inline accept/reject controls. You can select models and control terminal behavior in the extension's settings, found under VS Code's standard Settings UI in the "Claude Code" section.

Option 2: Using Claude Code in the VS Code Integrated Terminal

Some developers prefer running claude directly in VS Code's integrated terminal (Ctrl+`). This approach exposes the full CLI interface, including all flags and options that the extension may abstract away. It also enables scripting, piping, and combining Claude Code with other terminal tools in a single workflow. The trade-off is losing the extension's GUI-based diff review, inline diff accept/reject buttons, and file-navigation sidebar.

The extension approach suits developers who want point-and-click diff management and visual context. If you work primarily in the terminal, want full CLI flag access (such as --print for non-interactive mode or --model for explicit model selection), or need to integrate Claude Code into shell scripts, the terminal approach is the better fit.

Configuring Keybindings for Fast Access

Custom keybindings eliminate the friction of repeatedly navigating the command palette. Add the following to keybindings.json (accessible via Ctrl+Shift+P then "Preferences: Open Keyboard Shortcuts (JSON)"). Important: verify the command IDs below against your installed extension version by opening the Keyboard Shortcuts editor (Ctrl+K Ctrl+S) and searching for "Claude Code" — command IDs may differ between extension versions, and VS Code silently ignores bindings that reference nonexistent commands:

[
  {
    "key": "ctrl+shift+l",
    "command": "claude-code.open",
    "when": "editorTextFocus"
  },
  {
    "key": "ctrl+shift+a",
    "command": "claude-code.acceptDiff",
    "when": "claude-code.diffVisible"
  },
  {
    "key": "ctrl+shift+r",
    "command": "claude-code.rejectDiff",
    "when": "claude-code.diffVisible"
  }
]

These bindings map Ctrl+Shift+L to open Claude Code from any editor tab, Ctrl+Shift+A to accept a proposed diff, and Ctrl+Shift+R to reject it. Adjust the key combinations to avoid conflicts with existing shortcuts in your configuration.

Optimizing VS Code Settings for Claude Code

Recommended settings.json Configuration

The following settings.json block represents a configuration optimized for Claude Code integration. Before copying, confirm available settings keys in the extension's Settings UI (search "Claude Code" in VS Code Settings), as keys may change between versions. Access this file via Ctrl+Shift+P then "Preferences: Open Settings (JSON)":

{
  // --- Terminal Configuration ---
  // Larger font for reading Claude Code's detailed output
  "terminal.integrated.fontSize": 14,
  // Scrollback for long agent conversations (higher values increase memory usage)
  "terminal.integrated.scrollback": 5000,
  // Use a monospace font with ligature support for clean diffs
  "terminal.integrated.fontFamily": "'Fira Code', 'Cascadia Code', monospace",

  // --- Auto-Save (Critical for Claude Code) ---
  // Claude Code works best when files are saved automatically
  // It reads and writes files directly; stale buffers cause conflicts
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000,

  // --- File Watcher Settings ---
  // Exclude heavy directories from file watching to reduce overhead
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/.git/objects/**": true,
    "**/dist/**": true,
    "**/build/**": true,
    "**/.next/**": true
  },

  // --- Git Integration ---
  // Enable Git auto-fetch so Claude Code sees latest remote state
  // May trigger credential prompts in corporate environments; disable if fetch failures occur.
  "git.autofetch": true,
  // Confirm before committing (safety net for agent-generated commits)
  "git.confirmSync": true,
  // Show inline blame for context during reviews.
  // Requires VS Code >= 1.85. Remove this line if running VS Code 1.84 or earlier.
  "git.blame.editorDecoration.enabled": true,

  // --- Editor Settings for Diff Review ---
  // Enable inline diff view for reviewing Claude Code changes
  "diffEditor.renderSideBySide": true,
  // Word wrap in diff view for long lines
  "diffEditor.wordWrap": "on",

  // --- Claude Code Extension Settings ---
  // Set preferred model — find current model IDs at:
  // docs.anthropic.com/en/docs/models-overview
  // REQUIRED: Replace with a real model ID before use.
  // Leaving this as a placeholder will cause all model-selection requests to fail.
  // Example (verify currency): "claude-sonnet-4-20250514"
  // Remove this key entirely to use the extension's default model.
  // "claude-code.model": "claude-sonnet-4-20250514",

  // Enable automatic context detection from workspace
  "claude-code.contextFromWorkspace": true,

  // --- Workspace Trust ---
  // Keeps workspace trust feature enabled (VS Code default).
  // To trust this workspace, use Ctrl+Shift+P → "Workspaces: Manage Workspace Trust".
  "security.workspace.trust.enabled": true
}

The auto-save configuration at 1000ms is particularly important. Claude Code reads and modifies files on disk; if VS Code holds unsaved buffer changes, the agent operates on stale content and its edits can collide with unsaved editor state. Adjust if needed for your workflow -- lower values save more frequently but may cause issues on slow disks or with large files. The file watcher exclusions reduce CPU overhead in large repositories, which cuts down on repeated file-indexing pauses when Claude Code triggers file system operations.

Workspace vs. User Settings: Where to Put What

Settings that apply across all projects, such as terminal font, scrollback, and auto-save behavior, belong in User settings. Project-specific configuration, particularly model selection, context file paths, and any team-shared conventions, should live in Workspace settings (.vscode/settings.json in the repository root). This separation ensures that project-specific Claude Code behavior travels with the repo while personal preferences remain global.

The auto-save configuration at 1000ms is particularly important. Claude Code reads and modifies files on disk; if VS Code holds unsaved buffer changes, the agent operates on stale content and its edits can collide with unsaved editor state.

Setting Up Project Context for Better Results

Creating a CLAUDE.md File

CLAUDE.md is a project-level instruction file that Claude Code reads automatically when it starts in a directory. It functions as persistent context, eliminating the need to repeat project conventions in every prompt. Place it at the repository root for project-wide instructions, or in subdirectories for scope-specific guidance. Note: the filename is case-sensitive on Linux; use CLAUDE.md in all capitals.

# CLAUDE.md

## Project Overview
This is a Next.js 14 e-commerce application using the App Router, TypeScript, and Tailwind CSS.
The API layer uses tRPC with Prisma ORM connecting to PostgreSQL.

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS v3.4
- State Management: Zustand
- Database: PostgreSQL via Prisma
- Testing: Vitest + React Testing Library

## Coding Conventions
- Use named exports, not default exports
- Prefer `interface` over `type` for object shapes
- All components must be functional (no class components)
- Use `async/await`, never raw `.then()` chains
- Error handling: use Result types from `src/lib/result.ts`, not try/catch

## File Structure
- `src/app/` — Next.js routes and layouts
- `src/components/` — Shared UI components
- `src/server/` — tRPC routers and server-side logic
- `src/lib/` — Utility functions and shared types
- `prisma/` — Database schema and migrations

## Rules
- DO NOT modify files in `prisma/migrations/` directly
- DO NOT install new dependencies without noting it in the response
- Always run `pnpm lint` before considering a task complete
- Keep components under 150 lines; extract sub-components if needed

This file gives Claude Code the constraints and conventions it needs to generate code that matches existing project patterns. Without it, the agent defaults to generic conventions that may clash with the codebase.

Using .claudeignore to Control File Access

The .claudeignore file controls which files Claude Code includes in its context window. It follows .gitignore syntax. Verify Anthropic's documentation on whether this enforces filesystem-level access restrictions or operates as a context filter only, especially for sensitive files:

# Dependencies
node_modules/

# Build outputs
dist/
build/
.next/
out/

# Sensitive files — broad patterns to cover all .env variants
.env
.env.*
*.env
*.pem
*.key
*.p12
*.pfx

# Large generated files
package-lock.json
# pnpm-lock.yaml intentionally NOT excluded:
# Claude Code needs lockfile visibility to detect dependency conflicts.
*.min.js
*.map

# IDE and OS files
.idea/
.DS_Store
Thumbs.db

A well-scoped .claudeignore serves two purposes. First, it reduces the risk of Claude Code reading sensitive data like environment variables and private keys (though you should verify whether this constitutes a hard access restriction or a context filter). Second, it keeps the context window lean by excluding large, irrelevant files like lock files and build artifacts. In large repositories, this directly impacts response speed and quality, as the agent spends less time processing irrelevant content. For sensitive secrets, always use additional protective measures such as a secrets manager rather than relying solely on .claudeignore.

Verifying Your Setup: A Quick Test Drive

Running Your First Claude Code Task

Open a real project in VS Code, launch Claude Code (via the extension or terminal), and issue a simple, verifiable task. The goal is to confirm the full pipeline works: file reading, code generation, and diff presentation.

The following is an illustrative example of a typical interaction. Actual output formatting may vary by Claude Code version and configuration.

You: Add JSDoc comments to all exported functions in src/utils.js

Claude Code: I'll analyze src/utils.js and add JSDoc comments to all exported functions.

[Reading file: src/utils.js]
[Generating changes...]

I've added JSDoc comments to 4 exported functions in src/utils.js:
- formatCurrency(): Formats a number as a USD currency string
- debounce(): Creates a debounced version of the provided function
- parseQueryString(): Parses a URL query string into a key-value object
- slugify(): Converts a string into a URL-friendly slug

[Diff displayed — Accept / Reject]

Review the diff carefully. If the changes appear in VS Code's diff viewer and the accept/reject controls function, the setup is complete.

Confirming Git Integration

Claude Code is Git-aware by default. It reads the repository's Git status, understands which files are staged or modified, and can create commits when permitted. Claude Code will prompt for confirmation before creating commits by default. To verify, ask Claude Code to describe the current Git state of the project. It should accurately report the current branch, uncommitted changes, and recent commit history. If it cannot access Git information, check that you have granted workspace trust for the current project folder (via Ctrl+Shift+P → "Workspaces: Manage Workspace Trust") and that the .claudeignore file is not excluding .git/.

Troubleshooting Common Setup Issues

"Command not found" After Installation

The fix: run npm config get prefix to find the npm global prefix, then check whether $(npm config get prefix)/bin appears in your PATH. Nine times out of ten, it does not. Add it to your shell profile (~/.zshrc or ~/.bashrc), then either run source on that file or open a new terminal session. If the binary still does not resolve, confirm you persisted the PATH entry to the profile file and did not just export it in a single session.

Authentication Failures

For OAuth users, expired sessions require re-running claude to trigger a fresh browser-based authentication flow. API key users should verify the ANTHROPIC_API_KEY environment variable by running echo "Key set: $([ -n "$ANTHROPIC_API_KEY" ] && echo YES || echo NO)" in the terminal (avoid printing the actual key value). Firewall or corporate proxy configurations can block the OAuth callback; in these environments, API key authentication is more reliable.

Claude Code Not Reading Project Files

Start by checking your .claudeignore for overly broad patterns that accidentally exclude source files. Next, confirm that VS Code's workspace trust has been granted for the current project folder (use Ctrl+Shift+P → "Workspaces: Manage Workspace Trust"). Permission issues on the file system, particularly in WSL2 environments where Windows and Linux permissions interact, can also block file access.

Slow or Unresponsive Behavior

Large repositories without a .claudeignore force Claude Code to process excessive context. Adding appropriate ignore patterns is the single most effective fix. Lower subscription tiers also impose stricter rate limits that surface as slowness during multi-step agentic tasks; check your tier's limits at docs.anthropic.com/en/docs/rate-limits to confirm whether you are hitting a ceiling.

A well-scoped .claudeignore serves two purposes. First, it reduces the risk of Claude Code reading sensitive data like environment variables and private keys. Second, it keeps the context window lean by excluding large, irrelevant files like lock files and build artifacts.

Summary and Next Steps

The complete setup path is: install the CLI via npm (pinned to a specific version), authenticate through OAuth or a securely managed API key, integrate into VS Code via the extension or terminal, configure settings.json for auto-save and optimal terminal behavior, create CLAUDE.md and .claudeignore for project context, and verify with a real task.

From this foundation, explore advanced prompting strategies for multi-file refactoring. Integrate Claude Code into CI/CD pipelines using its non-interactive --print mode, which outputs Claude Code's response to stdout and exits, making it suitable for scripting and automation. Refine your CLAUDE.md files as you discover which instructions produce the most consistent results for your specific stack.