MAID for VS Code
VS Code extension for MAID (Manifest-driven AI Development) with comprehensive IDE integration for manifest validation, exploration, and test execution.
Features
Manifest Explorer & Navigation
- ✅ Manifest Explorer Sidebar - Browse all manifests in your workspace with expandable sections
- ✅ Tracked Files View - See all files tracked by the selected manifest
- ✅ Knowledge Graph View - Visualize entity relationships defined in manifests
Test Execution
- ✅ Run Tests - Execute tests directly from the manifest explorer
- ✅ Per-Manifest Testing - Run tests for specific manifests via context menu
- ✅ Watch Mode - Continuous test execution during development
Validation & Diagnostics
- ✅ Real-time Validation - Instant feedback as you edit
.manifest.json files via LSP
- ✅ Auto-install Detection - Automatically detects if
maid-lsp is installed and guides you through installation
- ✅ Code Actions - Quick fixes for common validation errors
- ✅ Hover Information - Detailed artifact information on hover
- ✅ Diagnostics - Validation errors and warnings in Problems panel
- ✅ Debounced Updates - Efficient 100ms debouncing for smooth editing experience
Requirements
- Python 3.10+ (for
maid-lsp server)
maid-lsp Python package (will be prompted to install if missing)
Installation
From VS Code Marketplace
- Open VS Code or Cursor
- Go to Extensions (
Ctrl+Shift+X / Cmd+Shift+X)
- Search for "MAID" or "MAID for VS Code"
- Click Install
Manual Installation
- Download the
.vsix file from Releases
- Open VS Code/Cursor
- Go to Extensions → "..." → "Install from VSIX..."
- Select the downloaded file
First-Time Setup
When you first open a .manifest.json file, the extension will:
- Check if
maid-lsp is installed
- If not found, show a prompt with installation options:
- Install via pip -
pip install --user maid-lsp
- Install via pipx -
pipx install maid-lsp (recommended)
- Install via uv -
uv tool install maid-lsp
- Manual installation - Instructions provided
After installation, restart VS Code/Cursor and the extension will activate automatically.
Usage
- Open any
.manifest.json file
- The extension activates automatically
- Validation errors appear in the Problems panel
- Hover over manifest elements for detailed information
- Use Quick Fix (
Ctrl+. / Cmd+.) for code actions
Configuration
The extension can be configured in VS Code settings:
{
"maid-lsp.path": "maid-lsp",
"maid-lsp.args": ["--stdio"]
}
Custom Server Path
If maid-lsp is not in your PATH, specify the full path:
{
"maid-lsp.path": "/home/user/.local/bin/maid-lsp"
}
On Windows:
{
"maid-lsp.path": "C:\\Users\\YourName\\AppData\\Local\\Programs\\Python\\Python310\\Scripts\\maid-lsp.exe"
}
Commands
- MAID: Check MAID LSP Installation - Verify installation status and get help if needed
Access via Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
Troubleshooting
Extension doesn't activate
- Check that
maid-lsp is installed: Run maid-lsp --version in terminal
- If not installed, use the command "MAID: Check MAID LSP Installation"
- Verify Python is in PATH:
python --version
No diagnostics appearing
- Check Output panel → Select "MAID LSP" for errors
- Verify
maid-runner is installed: maid --version
- Ensure you're editing a file ending with
.manifest.json
- Restart VS Code/Cursor after installing
maid-lsp
Installation issues
- pip not found: Install Python from python.org
- Permission errors: Use
--user flag with pip or install via pipx
- Command not found after install: Restart VS Code/Cursor or add Python Scripts to PATH
Development
Building from Source
# Clone repository
git clone https://github.com/mamertofabian/vscode-maid.git
cd vscode-maid
# Install dependencies
npm install
# Compile TypeScript
npm run compile
# Package extension
npm install -g @vscode/vsce
vsce package
Testing Locally
- Open the
vscode-maid folder in VS Code
- Press
F5 to launch Extension Development Host
- In the new window, open a workspace with
.manifest.json files
- Test validation and features
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
License
MIT License - see LICENSE for details.
Support
