Guardian

Protect your project architecture from AI agents and accidental restructuring.

Guardian is a VS Code extension that acts as a protective middleware between coding agents (GitHub Copilot, Cursor, Cline, Aider, etc.) and your file system. It enforces a user-defined architecture configuration so that AI agents cannot arbitrarily restructure, move, delete, or create files/folders in ways that violate the project's intended architecture.

Features

• Protected Paths — Prevent deletion, renaming, or moving files out of critical directories
• Locked Files — Lock specific files or glob patterns against deletion/renaming
• Folder Structure Enforcement — Block forbidden folder names, prevent new top-level directories
• Naming Conventions — Enforce PascalCase, camelCase, kebab-case, or custom patterns
• Boundary Rules — Prevent architectural boundary violations in imports (e.g., Core cannot import from Infrastructure)
• Multiple Enforcement Modes — Block, Warn, Ask, or Log violations
• Structure Snapshots — Capture and compare directory structure baselines
• Configuration Wizard — Interactive webview for generating .guardian.json

Getting Started

1. Install the extension
2. Open a project in VS Code
3. Run Guardian: Initialize Configuration from the Command Palette (Cmd+Shift+P)
4. Edit the generated .guardian.json to customize your rules
5. The guardian activates automatically and watches for violations

Configuration (.guardian.json)

Place a .guardian.json file in your project root:

{
  "version": "1.0",
  "projectName": "MyApp",
  "rules": {
    "protectedPaths": [
      {
        "path": "src/core",
        "rules": {
          "noDelete": true,
          "noRename": true,
          "noMoveOut": true,
          "allowedFileTypes": [".ts", ".py"],
          "maxDepth": 3
        }
      }
    ],
    "lockedFiles": ["src/core/interfaces/*.ts", "docker-compose.yml"],
    "folderStructure": {
      "enforceExisting": true,
      "allowNewTopLevel": false,
      "forbiddenFolderNames": ["temp", "tmp", "scratch", "old", "backup"]
    },
    "namingConventions": {
      "files": {
        "src/core/**": "PascalCase",
        "src/api/**": "camelCase"
      },
      "folders": "kebab-case"
    },
    "boundaryRules": [
      {
        "description": "Core must not import from Infrastructure",
        "from": "src/core/**",
        "cannotImport": ["src/infrastructure/**"]
      }
    ]
  },
  "enforcement": "warn",
  "notifications": true
}

Enforcement Modes

Commands

MCP Server

Guardian includes a built-in Model Context Protocol (MCP) server that lets AI agents query and respect your architecture rules programmatically. This means agents like Claude Code, Cursor, and other MCP-compatible clients can check whether a file operation is allowed before making changes.

Available Tools

The MCP server exposes three tools:

Available Resources

Setup

VS Code / Cursor (automatic)

When Guardian is installed as a VS Code extension, the MCP server is automatically registered — no manual configuration needed. MCP-compatible agents running inside VS Code (such as GitHub Copilot agent mode or Cursor) can discover and use it out of the box.

Claude Code

Add the following to your project's .mcp.json file (create it in the project root if it doesn't exist):

{
  "mcpServers": {
    "architecture-guardian": {
      "type": "stdio",
      "command": "node",
      "args": ["<path-to-extension>/bin/guardian-mcp.js"]
    }
  }
}

To find <path-to-extension>, locate where VS Code installed the Guardian extension:

• macOS: ~/.vscode/extensions/sceletonlabs.guardian-<version>/
• Linux: ~/.vscode/extensions/sceletonlabs.guardian-<version>/
• Windows: %USERPROFILE%\.vscode\extensions\sceletonlabs.guardian-<version>\

For example on macOS:

{
  "mcpServers": {
    "architecture-guardian": {
      "type": "stdio",
      "command": "node",
      "args": ["~/.vscode/extensions/sceletonlabs.guardian-0.1.0/bin/guardian-mcp.js"]
    }
  }
}

Tip: If you clone the Guardian repo locally, you can also point directly to that clone instead of the extension install path.

Other MCP Clients

The server uses stdio transport. Any MCP-compatible client can launch it by running:

node /path/to/guardian/bin/guardian-mcp.js

The server reads .guardian.json from the workspacePath argument provided in each tool call, or falls back to the current working directory.

Tool Examples

Check if deleting a file is allowed:

{
  "tool": "check_path",
  "arguments": {
    "workspacePath": "/path/to/project",
    "path": "src/core/auth.ts",
    "action": "delete"
  }
}

Get all architecture rules:

{
  "tool": "get_project_structure",
  "arguments": {
    "workspacePath": "/path/to/project"
  }
}

Scan for boundary violations:

{
  "tool": "get_boundary_rules",
  "arguments": {
    "workspacePath": "/path/to/project",
    "scan": true
  }
}

How It Works

Guardian uses VS Code's workspace file system events (onDidCreateFiles, onDidDeleteFiles, onDidRenameFiles) to intercept changes in real-time. When a file operation matches a rule violation, the configured enforcement action is taken.

For boundary rules, the extension also watches for file saves and analyzes import statements to detect cross-boundary dependencies.

Compatibility

Works in VS Code, VS Code Insiders, and Cursor.

License

MIT