Edit Excel VBA projects directly in VS Code. XLIDE turns macro workbooks into first-class development projects: browse workbook modules, edit writable xlide-vba documents, use Smart Enter and IntelliSense, run deterministic analysis, sync modules with files, execute macros and workbook tests through Excel when needed, and give AI agents workbook-aware tools.

Highlights of What's New In Version 2

Version 2 turns XLIDE from a workbook module browser into a fuller VBA development environment for VS Code:

• Dedicated XLIDE Activity Bar/sidebar with setup health, selected-workbook actions, global settings, and support commands.
• Expanded deterministic VBA language service: Smart Enter, block snippets, completions, hover, signature help, semantic type coloring, navigation, rename, and focused code actions.
• Live, current-module, and workbook-wide analysis with stable rule codes, severity controls, suppressions, workbook/global settings, and a dedicated analysis results panel.
• Stronger project-aware understanding for visible identifiers, type names, source-backed class members, UDT fields, known runtime signatures, and the first generated Excel host-member surfaces.
• Previewable import/export sync for workbook modules, backed by the current <workbook>.xlide_settings.json sidecar model.
• Workbook test runner for marked @xlide-test procedures, including XlideAssert, read-only Excel test execution, artifacts, and CI status output.
• AI-agent tools for workbook discovery, VBA reads/writes, analysis, tests, sheet/cell I/O, formula reads, module export, and openpyxl automation.
• Safety and support hardening: explicit workbook mutation, write summaries, settings validation, support bundles, setup diagnostics, and recovery notes.

Start Here

If you are new to using XLIDE, start with the user guides:

The sections below are primarily for extension contributors and packagers.

What XLIDE Does

• Opens .xlsm, .xlsb, and .xlam VBA modules as editable VS Code documents.
• Saves module edits back to the workbook with normal VS Code save behavior.
• Provides VBA syntax highlighting, Smart Enter, block snippets, completions, hover, signature help, Go to Definition, Find All References, Rename Symbol, semantic type coloring, and deterministic code actions where XLIDE can prove the edit.
• Runs live diagnostics, current-module analysis, and workbook-wide analysis with stable rule codes, severity controls, suppressions, and a dedicated analysis results panel.
• Imports and exports workbook modules through previewable sync GUIs so .bas and .cls files can be reviewed or source-controlled.
• Runs macros and marked workbook tests through explicit Excel COM workflows on Windows.
• Exposes workbook discovery, module editing, analysis, tests, sheet/cell I/O, formula reads, module export, and openpyxl automation as VS Code language model tools.
• Keeps setup health, global settings, workbook actions, and support commands discoverable from the XLIDE Activity Bar view.

Requirements

• VS Code 1.95+
• Python 3.10+ -- the VBA read/write backend runs as a child process
• Python packages: pyOpenVBA >= 3.0.1, openpyxl >= 3.1.0

Reading, editing, analyzing, importing, exporting, and sheet/cell inspection use the Python backend and do not require Excel COM automation.

Microsoft Excel COM is required for workflows that execute VBA, such as running a macro or running workbook tests. Those execution workflows are Windows-only and require the workbook's macro security state to allow execution.

Development setup

git clone https://github.com/WilliamSmithEdward/xlide_vscode.git
cd xlide_vscode

# TypeScript side
npm install
npm run compile        # type-check + esbuild bundle -> out/extension.js

# Python side (optional venv)
python -m venv .venv
.venv\Scripts\activate   # or: source .venv/bin/activate
pip install -r python/requirements.txt

Press F5 in VS Code to launch an Extension Development Host with the extension loaded and the watch compiler running.

Repository Map

xlide_vscode/
  src/
    extension.ts              # Activation entry point
    pythonBridge.ts           # JSON-RPC client for the Python backend
    xlideFileSystem.ts        # xlide-vba:// writable virtual filesystem
    xlsmExplorer.ts           # Explorer-hosted workbook/module tree
    xlideSidebar.ts           # XLIDE Activity Bar/sidebar webview
    commands.ts               # Workbook, module, analysis, sync, run/test commands
    agentTools.ts             # VS Code language model tool registrations
    workbookSettings.ts       # Strict <workbook>.xlide_settings.json owner
    vbaLanguageProviders.ts   # Editor providers, diagnostics, Smart Enter
    analyzer/                 # Lexer, parser, binder, diagnostics, completion
  python/
    server.py                 # JSON-RPC 2.0 server
    xlide/
      vba_io.py               # pyOpenVBA workbook/module operations
      excel_io.py             # openpyxl sheet/cell/formula operations
  syntaxes/
    vba.tmLanguage.json       # TextMate grammar
  language-configuration/
    vba-language-configuration.json
  user_guides/                # Public user guides
  docs/
    architecture.md           # Full architecture reference
    roadmap_version_2.x.md    # Closed v2 launch-hardening roadmap
    roadmap_version_2.1.0.md  # v2.1.0 red-squiggle roadmap

Key design decisions

VBA language ID

Registered as vba in package.json with extensions .bas, .cls, .frm. The TextMate grammar in syntaxes/vba.tmLanguage.json is scoped to source.vba and covers all reserved identifiers from MS-VBAL v20250520 (section 3.3.5.2: statement-keywords, marker-keywords, operator-identifiers, reserved-names, special-forms, reserved-type-identifiers, literal-identifiers, def-type directives, and implementation-reserved identifiers).

See docs/architecture.md for the full architecture, Python bridge method list, workbook settings schema, import/export planning, and agent-tool implementation notes.

Build commands

AI Agent Tools

XLIDE contributes VS Code language model tools so Copilot and compatible agents can inspect, edit, analyze, test, and sync workbooks without guessing where VBA source lives. The workbook and xlide-vba virtual modules are the source of truth; exported .bas and .cls files are sync artifacts unless the user asks to work with them directly.

Recommended flow:

1. Discover the workbook with xlide_listWorkbooks or xlide_getWorkbookInfo.
2. Read workbook VBA with xlide_readModule.
3. Write workbook VBA with xlide_writeModule when an edit is approved.
4. Run xlide_analyzeWorkbook.
5. Run xlide_runVbaTests when Excel COM is available and workbook tests exist.

Most workbook-mutating agent tools request explicit VS Code confirmation before writing modules, cells, files, or workbook settings. See the Automation and CI guide for the supported agent/CI workflow.

Workbook Settings

Workbook-specific settings are stored beside the workbook as <workbook>.xlide_settings.json, for example Budget.xlsm.xlide_settings.json. Prefer the XLIDE import/export, analysis, test, and settings GUIs for normal editing; they preserve unrelated settings and show the effective source of each value.

{
  "exportFolder": "C:/absolute/path/to/export",
  "exportMode": "exportAll",
  "importMode": "updateOnly",
  "analysis": {
    "visibleSeverities": ["error", "warning", "information"],
    "untrackedRules": [],
    "ruleSeverityOverrides": {}
  },
  "tests": {
    "artifactFolder": "tests",
    "artifactRetention": 20
  }
}

Malformed workbook settings are reported as explicit XLIDE settings errors instead of being ignored. Global defaults live in VS Code machine/profile settings; workbook sidecars contain only workbook-specific overrides.

Live Share

XLIDE VBA browsing for Live Share guests is currently not supported. Microsoft's Live Share platform restricts the shared-service RPC channel (vsls.shareService) to extensions on a curated first-party allowlist, so third-party extensions like XLIDE cannot proxy VBA read/write calls from a guest to the host. The XLIDE Explorer therefore returns an empty tree for guests and shows an informational welcome view.

What still works in a Live Share session:

Related upstream issue: microsoft/live-share#4877 (third-party shareService allowlist, closed as Not Planned).

Further reading

• User guides README -- public guide index
• Getting started guide -- first-hour XLIDE workflow
• Analysis and ignores guide -- diagnostics, settings, suppressions, and tracking
• Import and export guide -- previewable .bas/.cls module sync
• Testing guide -- workbook test authoring and execution
• Automation guide -- agent and CI workflows
• Safety and support guide -- trust model, Excel setup, and recovery
• docs/architecture.md -- full architecture reference
• MS-VBAL specification
• pyOpenVBA

Support Open Source

XLIDE is open-source software. If it saves you time or helps your team keep VBA workbooks maintainable, support helps keep the project moving.

• GitHub Sponsors
• PayPal
• Cash App