---
title: VS Code Plugin
description: Install the Archgate VS Code extension for AI-assisted development with architecture guardrails. Real-time ADR compliance checking in your editor.
---

The Archgate VS Code plugin gives AI agents working in [VS Code](https://code.visualstudio.com/) built-in guardrails. Agents read your ADRs before writing code, validate after, and capture new patterns for the team -- the same workflow available in the [Claude Code plugin](/guides/claude-code-plugin/).

## How it works

VS Code supports **agent plugins** installed from git-based marketplaces. The Archgate plugin is served from a git repository at `plugins.archgate.dev/archgate/vscode.git`. When you add this marketplace to your VS Code user settings, VS Code discovers and installs the plugin automatically.

The plugin is served in VS Code Copilot's native `.github/plugin/` manifest format, separate from the Claude Code `.claude-plugin/` format.

## Installation

:::caution[VS Code version requirement]
Agent plugins require **VS Code 1.110 (February 2026 release) or later**. Earlier versions do not support git-based agent plugin marketplaces. Check your version with `code --version`.
:::

:::note[Beta access required]
The VS Code plugin is currently in beta. Run `archgate login` to sign in before following the steps below.
:::

### 1. Log in to the Archgate platform

Log in to obtain plugin access:

```bash
archgate login
```

This starts an OAuth 2.0 Device Authorization Grant against the Archgate platform. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, the resulting tokens are handed to your configured git credential helper via `git credential approve`; an OS-backed helper keeps them encrypted, while git's built-in `store` helper writes them in plain text.

### 2. Initialize your project with the plugin

Run `archgate init` with the `--editor vscode` flag:

```bash
archgate init --editor vscode
```

If you are already logged in, this command:

1. Creates the `.archgate/` directory with ADRs and lint rules
2. Adds the marketplace URL to your VS Code **user settings**

`archgate init` does not download the VS Code extension. To install the extension itself, run `archgate plugin install --editor vscode` (see below).

The `chat.plugins.marketplaces` setting is application-scoped in VS Code, so it cannot be set per-workspace. The CLI automatically writes it to your user-level `settings.json`:

| Platform | User settings path                                      |
| -------- | ------------------------------------------------------- |
| Windows  | `%APPDATA%\Code\User\settings.json`                     |
| macOS    | `~/Library/Application Support/Code/User/settings.json` |
| Linux    | `~/.config/Code/User/settings.json`                     |
| WSL      | The Windows-side path above (VS Code runs on Windows)   |

### 3. Install the extension

To install or reinstall the extension on an already-initialized project:

```bash
archgate plugin install --editor vscode
```

Without `--editor`, an interactive run detects the editors installed on your machine and lets you pick; a non-interactive run (an agent or CI) defaults to Claude Code.

This re-writes the marketplace URL into your user settings and, when the `code` CLI is on your PATH, downloads the Archgate VS Code extension from the plugins service and installs it via `code --install-extension`. If the `code` CLI is not available, manual installation instructions are printed. If the install itself fails, the downloaded `.vsix` is kept at `~/.archgate/archgate.vsix` so you can install it by hand.

### Generated files

The commands create or update the following:

| File                 | Scope       | Purpose                                                                |
| -------------------- | ----------- | ---------------------------------------------------------------------- |
| User `settings.json` | User        | `chat.plugins.marketplaces` with the Archgate marketplace URL (`init`) |
| Archgate extension   | Application | VS Code extension installed via `.vsix` (`archgate plugin install`)    |

The user settings file is merged additively -- existing settings are never overwritten. VS Code's built-in default marketplaces (`github/copilot-plugins`, `github/awesome-copilot`) are preserved when the key is set for the first time.

The user-level marketplace setting (added to your `settings.json`):

```json
{
  "chat.plugins.marketplaces": [
    "https://plugins.archgate.dev/archgate/vscode.git"
  ]
}
```

The URL carries no credentials. `archgate credential` is the credential helper; `archgate login` registers it for `plugins.archgate.dev`. Git asks it on each request and receives a valid access token, renewed only when the cached one has lapsed.

### Manual setup

If you prefer not to let the CLI modify your user settings, you can set things up manually:

**Marketplace URL:** Open VS Code's user settings JSON (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") and add the `chat.plugins.marketplaces` entry shown above. You can print the URL by running `archgate plugin url --editor vscode`.

**Extension:** Download and install the `.vsix` file directly:

```bash
printf 'protocol=https\nhost=plugins.archgate.dev\n\n' |
  archgate credential get |
  sed -n 's|^password=\(.*\)|header = "Authorization: Bearer \1"|p' |
  curl --config - --fail --silent --show-error --output archgate.vsix https://plugins.archgate.dev/api/vscode &&
  code --install-extension archgate.vsix
rm -f archgate.vsix
```

`archgate credential get` emits a git credential response, so the `password=` line is reshaped into a `curl --config` directive and piped in. The token never reaches the command line, where it would be visible in the process list and your shell history. `--fail` makes curl exit non-zero on a 401 rather than writing the error body over `archgate.vsix`, and `&&` keeps `code` from installing anything curl did not finish downloading; the final `rm -f` cleans up either way.

Prefer the marketplace setup above where you can: it lets git ask the helper on every request, so no token is handled by hand at all.

## What the plugin provides

The plugin adds agents and role-based skills to VS Code's AI. The developer agent orchestrates the guardrails workflow, invoking skills as needed.

### Agents

| Agent                | Purpose                                                                     |
| -------------------- | --------------------------------------------------------------------------- |
| `archgate:developer` | General development agent that reads ADRs before coding and validates after |
| `archgate:planner`   | Planning agent for scoping work and breaking tasks into ADR-compliant steps |

The `archgate:developer` agent is set as the default agent via the plugin settings. It orchestrates the skills below automatically as part of its workflow.

### Skills

| Skill                      | Purpose                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `archgate:reviewer`        | Validates code changes against all project ADRs for structural compliance             |
| `archgate:lessons-learned` | Captures learnings and proposes new ADRs when patterns emerge                         |
| `archgate:adr-author`      | Creates and edits ADRs following project conventions                                  |
| `archgate:onboard`         | One-time setup: explores the codebase, interviews the developer, creates initial ADRs |
| `archgate:cli-reference`   | Internal reference for AI agents with the complete Archgate CLI command guide         |

## Initial setup with onboard

After installation, run the `archgate:onboard` skill in your project once. This skill:

1. Explores your codebase structure (directories, key files, package configuration)
2. Interviews you about your team's conventions, constraints, and architectural decisions
3. Creates an initial set of ADRs based on your responses
4. Sets up the `.archgate/` directory with your first rules

The onboard skill is designed to run once per project. After onboarding, the other skills handle day-to-day development.

## How it works in practice

The plugin follows a structured workflow for every coding task:

### 1. Read applicable ADRs

When the developer gives a coding task, the agent runs `archgate review-context` to read all ADRs that apply to the files being changed. This provides a condensed briefing with the **Decision** and **Do's and Don'ts** sections from each relevant ADR.

### 2. Write code following ADR constraints

The agent writes code that complies with the constraints from the ADRs. The Do's and Don'ts sections serve as concrete guardrails.

### 3. Validate changes

After writing code, the agent runs `archgate check` to execute automated rules against the changes. Any violations are fixed before proceeding.

### 4. Review changes

The agent invokes `archgate:reviewer` to validate structural ADR compliance beyond what automated rules catch.

### 5. Capture learnings

The agent invokes `archgate:lessons-learned` to review the work and identify patterns worth capturing as new ADRs.

## Tips

- **Each developer runs `archgate init --editor vscode`** after `archgate login` to configure their user-level marketplace URL, then `archgate plugin install --editor vscode` to install the extension.
- **Run onboard once per project** to generate your initial ADRs from your actual codebase.
- **Keep ADR rule files up to date** -- the agent enforces what the rules check for.