VS Code

The Archgate VS Code extension brings architecture governance directly into your editor. It does two things at once: it surfaces ADR violations as native VS Code diagnostics the moment you save a file, and it adds AI governance skills to Copilot Chat so agents read your decisions before writing code.

It pairs with the VS Code agent plugin (the archgate:developer agent and skills installed from the Archgate marketplace). The extension covered here is the diagnostics surface; the agent plugin is the AI workflow. archgate init --editor vscode sets up both.

Authoritative CLI reference

This page covers VS Code setup and configuration. For the exact syntax of archgate init, archgate login, and archgate plugin install, see the CLI reference at cli.archgate.dev.

Requirements

• Archgate CLI — install via the CLI install guide. The extension shells out to the CLI; it does not bundle it.
• A project initialized with archgate init — the extension activates only when your workspace contains a .archgate/ directory.
• VS Code agent plugins (for the Copilot Chat skills) require VS Code 1.110 (February 2026) or later. The diagnostics half of the extension has no such floor.

What the extension provides

Real-time diagnostics

ADR violations appear in the Problems tab as you code — errors, warnings, and info with precise file and line locations. No separate CLI run, no waiting for CI.

Scoped checks

Only the ADRs relevant to the saved file are evaluated, so feedback is fast and focused. Violations clear automatically when you fix them.

Governance skills

Copilot Chat gains skills for authoring ADRs, reviewing changes, onboarding a project, and capturing lessons learned.

Manual check command

Trigger a full compliance check on demand from the Command Palette.

Installation

The extension is distributed as a .vsix package through the Archgate plugins service. The recommended path installs it automatically; manual .vsix install is available if you prefer.

Recommended (CLI)

1. Log in to obtain a plugin token (the extension is in closed beta):

   archgate login

2. Initialize your project with the VS Code editor target:

   archgate init --editor vscode

   When you are logged in and the code CLI is on your PATH, this creates the .archgate/ directory, registers the authenticated Archgate marketplace in your VS Code user settings, and downloads and installs the extension .vsix.

3. Open your project in VS Code. The extension activates on the .archgate/ directory and begins running checks on save.

See the CLI guide for the exact flags (--install-plugin) and the user-settings paths per platform.

Manual .vsix install

If you would rather not let the CLI modify your user settings, install the .vsix directly. Retrieve your authenticated download URL and token with archgate plugin url vscode, then:

curl -H "Authorization: Bearer <token>" https://plugins.archgate.dev/api/vscode -o archgate.vsix
code --install-extension archgate.vsix
rm archgate.vsix

You can also install a downloaded .vsix from VS Code’s UI: open the Extensions view, click the ... menu, choose Install from VSIX…, and select the file.

Tip

The full syntax for archgate plugin url and the manual marketplace setup live in the CLI reference.

How diagnostics work

The extension is a thin surface over the Archgate CLI. The flow on every save is:

1. The extension activates when the workspace contains a .archgate/ directory.
2. On file save, it runs archgate check --json scoped to the saved file.
3. The CLI evaluates the ADR rules (.rules.ts files) that apply to that file.
4. Violations are mapped to VS Code diagnostics with precise locations and severities, shown in the Problems tab and inline in the editor.

Because checks are scoped to the saved file, only the ADRs whose files globs match are evaluated — you get targeted feedback rather than a whole-project scan on every keystroke. Diagnostics clear as soon as the underlying violation is fixed and the file is saved again.

For a full-project pass, run the Archgate: Check ADR Compliance command from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).

Configuration

The extension reads these settings (set them per-workspace in .vscode/settings.json or globally in your user settings):

Setting	Default	Description
archgate.runOnSave	true	Run an ADR compliance check when a file is saved.
archgate.debounceMs	1000	Debounce delay, in milliseconds, for on-save checks.
archgate.cliPath	"archgate"	Path to the archgate CLI executable. Override if the CLI is not on your PATH.
archgate.timeoutMs	60000	Timeout, in milliseconds, for check commands.

The extension does not bundle the CLI

Diagnostics depend on the archgate CLI being resolvable. If checks silently produce no diagnostics, confirm archgate --version works in your shell and that archgate.cliPath points at the right binary.

Governance skills in Copilot Chat

The accompanying agent plugin adds the archgate:developer agent plus role skills to VS Code’s AI. The agent orchestrates a read-validate-capture workflow: it reads applicable ADRs before writing code, runs archgate check after, reviews structural compliance, and captures new patterns. The skills cover authoring ADRs, reviewing changes, one-time project onboarding, and lessons learned.

These map to the same roles documented in Skills and Agents. The plugin’s agent and skill setup is described in full in the CLI VS Code plugin guide.

Next steps

All editor plugins Compare the six supported editors and what each one provides.

Skills The governance skills the agent invokes during the workflow.

CLI: VS Code plugin Authoritative setup, flags, and manual configuration.