# VS Code Integration

> **Last verified**: 2026-09-18 · 📄 Per official docs (VS Code 1.138.0, released 2026-09-16)

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ✅ (extension via Anthropic protocol / Copilot via Messages) · GPT ✅ · Chinese models ✅ (Copilot custom endpoint) · Gemini ❌ |
| Protocol & Base URL | Claude Code extension: environment variables at `https://api.qcode.cc/api` · Copilot: full URLs in `chatLanguageModels.json` |
| Where to configure | `~/.claude/config.json` + environment variables; Copilot uses `chatLanguageModels.json` |
| Official docs | [Claude Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) · [language models](https://code.visualstudio.com/docs/agent-customization/language-models) |

> **Using Trae IDE?** Trae is a VS Code fork, so most steps here apply directly. For Trae-specific details — marketplace differences, offline `.vsix` installation, coexisting with Trae's built-in AI — see the [Trae Integration Guide](/docs/ide/trae).

In addition to using Claude Code CLI in the terminal, you can use the VS Code extension to access Claude Code directly in the editor for a more convenient development experience.

## Prerequisites

Before configuring the VS Code extension, ensure:

1. **Claude Code CLI is installed and working**
   - See [Installation Guide](/docs/getting-started/installation) to complete installation
   - See [Environment Configuration](/docs/getting-started/environment) to complete setup

2. **VS Code version >= 1.98.0**

## Installation Steps

### Step 1: Install VS Code

If VS Code is not installed, visit the [VS Code website](https://code.visualstudio.com/) to download and install.

### Step 2: Install Claude Code Extension

In VS Code:

1. Open the Extensions panel (`Ctrl+Shift+X` / `Cmd+Shift+X`)

2. Search for **"Claude Code for VS Code"**

3. Click **Install**

Or install via command line:

```bash
code --install-extension anthropic.claude-code
```

### Step 3: Configure primaryApiKey

This is a critical step! The Claude Code extension requires `primaryApiKey` in the configuration file.

<div data-os="windows" markdown="1">

#### Windows

Edit or create the config file `C:\Users\YourUsername\.claude\config.json`:

```json
{
  "primaryApiKey": "qcode"
}
```

</div>

<div data-os="macos" markdown="1">

#### macOS

Edit or create the config file `~/.claude/config.json`:

```bash
# Create directory (if it doesn't exist)
mkdir -p ~/.claude

# Create config file
cat > ~/.claude/config.json << 'EOF'
{
  "primaryApiKey": "qcode"
}
EOF
```

</div>

<div data-os="linux" markdown="1">

#### Linux

Edit or create the config file `~/.claude/config.json`:

```bash
# Create directory (if it doesn't exist)
mkdir -p ~/.claude

# Create config file
cat > ~/.claude/config.json << 'EOF'
{
  "primaryApiKey": "qcode"
}
EOF
```

</div>

> **Note**: The value of `primaryApiKey` can be anything (like `qcode`). You just need to have this field configured. The actual API authentication still uses the `ANTHROPIC_AUTH_TOKEN` you configured in environment variables.

> **Important**: The config file is `config.json`, NOT `settings.json`. Please distinguish between these two files carefully.

### Step 4: Restart VS Code

After configuration, restart VS Code for changes to take effect.

## Usage

### Keyboard Shortcuts

| Shortcut | Function |
|----------|----------|
| `Cmd+Esc` / `Ctrl+Esc` | Open/Close Claude Code panel |
| `Cmd+Shift+P` / `Ctrl+Shift+P` | Open command palette, search for Claude commands |

### Common Features

1. **Code Explanation**
   - Select code
   - Right-click and choose "Ask Claude" or use shortcut
   - Enter your question, e.g., "Explain this code"

2. **Code Generation**
   - Open Claude panel
   - Describe the feature you need
   - Claude will generate code with insert options

3. **Code Refactoring**
   - Select code to refactor
   - Ask Claude to help refactor
   - Preview and apply changes

4. **Error Fixing**
   - When code has errors
   - Select the error code or message
   - Ask Claude to analyze and provide fixes

## Configuration Options

In VS Code settings, you can configure Claude Code extension behavior:

1. Open Settings (`Ctrl+,` / `Cmd+,`)

2. Search for "Claude Code"

3. Adjust options as needed

### Common Settings

```json
{
  "claude-code.autoSuggest": true,
  "claude-code.inlineChat": true
}
```

## Using with Terminal CLI

The VS Code extension and terminal CLI can be used together:

| Scenario | Recommended Tool |
|----------|-----------------|
| Quick code edits | VS Code extension |
| Complex project analysis | Terminal CLI |
| Code review | Either |
| Git operations | Terminal CLI |
| File generation | Either |

## GitHub Copilot custom endpoints

Since VS Code 1.122 the built-in Copilot Custom Endpoint lets you plug QCode's protocol legs straight into Copilot (Claude only via `messages`, `url` takes the full path). Minimal config:

```json
[
  { "name": "QCode Claude", "vendor": "customendpoint", "apiKey": "cr_your-QCode-key",
    "apiType": "messages",
    "url": "https://api.qcode.cc/api/v1/messages",
    "toolCalling": true,
    "models": [ { "id": "claude-sonnet-5" } ] }
]
```

The complete three-leg setup, Copilot CLI BYOK and known limits (inline completions still run through GitHub) are on the dedicated page: [GitHub Copilot Integration](/docs/ide/github-copilot).

## Troubleshooting

### Extension Won't Start

1. Confirm Claude Code CLI is properly installed

2. Check environment variable configuration

3. Verify `config.json` file format is correct

### primaryApiKey Error

1. Confirm file path is correct:
   - Windows: `C:\Users\YourUsername\.claude\config.json`
   - macOS/Linux: `~/.claude/config.json`

2. Confirm it's `config.json` not `settings.json`

3. Confirm JSON format is valid

### Connection Timeout

1. Check network connection

2. Verify `ANTHROPIC_BASE_URL` environment variable

3. Try running `claude` in terminal to confirm CLI works

## Next Steps

- Explore [CLI Tips](/docs/usage/cli-tips) to boost efficiency

- Learn [Workflow Tips](/docs/usage/workflow-tips) to optimize development flow