Workspace Spectrum — Dynamic Folder & Repo Rules for VS Code

Workspace Spectrum customizes your VS Code settings (status bar & window colors, fonts, tab sizes, linters, or any setting that can live in settings.json) dynamically based on repository and folder matching—with 100% per-window isolation, zero Git working tree modifications, and zero pollution of your global User settings.json.

✨ Features

🧼 Zero Repo Footprint: Never touches or creates .vscode/settings.json in your project. Your Git working tree remains 100% clean.
🪟 True Per-Window Isolation: Have Window A open to project Blue and Window B open to project Orange simultaneously across monitors without any color crosstalk!
🛡️ Zero User Settings Pollution: Never writes project-specific colors or settings into your global User/settings.json.
🗂️ Seamless External Workspace: Automatically runs matched projects from a private external workspace file in extension storage (context.globalStorageUri).
🔄 Live Hot-Reload: Changes saved to ~/.workspace-spectrum/rules.json update open windows within ~1.5 seconds.
⚙️ Apply Any Setting: Not limited to colors! Apply workbench.colorCustomizations, editor.tabSize, editor.fontSize, workbench.iconTheme, terminal profiles, or any setting supported by VS Code.
🐧 Cross-Platform & WSL Ready: Works independently on Windows and WSL, with each environment having its own local rules file and storage.
🎨 Starter Template: Pre-populated with 4 generic color samples (this-project-will-be-blue, this-project-will-be-orange, this-project-will-be-purple, this-project-will-be-green).
📜 Real-time Diagnostics: Inspect active matches and rules with a dedicated status bar button and Output channel (Output > Workspace Spectrum).

🚀 Quick Start

Install the extension.
Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) to open the Command Palette.

Run:

Workspace Spectrum: Open Rules Configuration File

If ~/.workspace-spectrum/rules.json does not exist yet, Workspace Spectrum will automatically create it with 4 sample color rules and open it in your editor!

📋 Rules Configuration File

The default location for your rules file is:

Windows: %USERPROFILE%\.workspace-spectrum\rules.json (e.g. C:\Users\YourName\.workspace-spectrum\rules.json)
WSL / Linux: ~/.workspace-spectrum/rules.json (e.g. /home/username/.workspace-spectrum/rules.json)

You can customize this path in VS Code Settings under workspaceSpectrum.rulesPath.

Standard Array Format

Supports standard JSON or JSONC (JSON with comments):

{
  "$schema": "https://raw.githubusercontent.com/workspace-spectrum/workspace-spectrum/master/schemas/rules.schema.json",
  "version": 1,
  "rules": [
    {
      "name": "Blue Project",
      "match": {
        "type": "contains",
        "value": "this-project-will-be-blue",
        "target": "any",
        "caseSensitive": false
      },
      "settings": {
        "workbench.colorCustomizations": {
          "statusBar.background": "#0b3060",
          "statusBar.inactiveBackground": "#001838",
          "statusBar.foreground": "#ffffff",
          "titleBar.activeBackground": "#0b3060",
          "titleBar.activeForeground": "#ffffff",
          "titleBar.inactiveBackground": "#072040"
        }
      }
    },
    {
      "name": "Orange Project",
      "match": "this-project-will-be-orange",
      "settings": {
        "workbench.colorCustomizations": {
          "statusBar.background": "#b33c00",
          "statusBar.inactiveBackground": "#802b00",
          "statusBar.foreground": "#ffffff",
          "titleBar.activeBackground": "#b33c00",
          "titleBar.activeForeground": "#ffffff",
          "titleBar.inactiveBackground": "#5c1f00"
        }
      }
    },
    {
      "name": "Purple Project",
      "match": "this-project-will-be-purple",
      "settings": {
        "workbench.colorCustomizations": {
          "statusBar.background": "#5c2d91",
          "statusBar.inactiveBackground": "#3c1e5f",
          "statusBar.foreground": "#ffffff",
          "titleBar.activeBackground": "#5c2d91",
          "titleBar.activeForeground": "#ffffff",
          "titleBar.inactiveBackground": "#281440"
        }
      }
    },
    {
      "name": "Green Project",
      "match": "this-project-will-be-green",
      "settings": {
        "workbench.colorCustomizations": {
          "statusBar.background": "#107c41",
          "statusBar.inactiveBackground": "#0b552c",
          "statusBar.foreground": "#ffffff",
          "titleBar.activeBackground": "#107c41",
          "titleBar.activeForeground": "#ffffff",
          "titleBar.inactiveBackground": "#083a1e"
        },
        "editor.tabSize": 2
      }
    }
  ]
}

Key-Value Map Format (Shorthand)

For quick setups, you can also define rules as a dictionary where keys are matching substrings:

{
  "this-project-will-be-blue": {
    "workbench.colorCustomizations": {
      "statusBar.background": "#0b3060",
      "statusBar.inactiveBackground": "#001838",
      "statusBar.foreground": "#ffffff"
    }
  },
  "this-project-will-be-orange": {
    "workbench.colorCustomizations": {
      "statusBar.background": "#b33c00",
      "statusBar.inactiveBackground": "#802b00",
      "statusBar.foreground": "#ffffff"
    }
  }
}

🎯 Matching Options

Option	Values	Default	Description
`type`	`"contains"` \| `"equals"` \| `"glob"`	`"contains"`	Matching algorithm.
`value`	`string`	`""`	Pattern or string to test.
`target`	`"any"` \| `"folder"` \| `"root"` \| `"workspace"`	`"any"`	Whether to match folder basename, workspace name, or full path.
`caseSensitive`	`boolean`	`false`	Case sensitivity of the match.

Matching Examples

Substring (contains): "match": "frontend" matches /repos/my-frontend-service.
Glob pattern: "match": { "type": "glob", "value": "*-service" }.
Exact match: "match": { "type": "equals", "value": "core-api" }.

⌨️ Commands

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Workspace Spectrum: Open Rules Configuration File: Opens (or creates from starter template) your rules.json file.
Workspace Spectrum: Choose Rules File...: Browse the filesystem to select a custom rules file.
Workspace Spectrum: Reload and Re-apply Rules: Force immediate evaluation and update of active rules.
Workspace Spectrum: Return to Original Folder (Remove Overrides): Reverts the current window to the original unmanaged folder and pauses overrides for this folder.
Workspace Spectrum: Resume Overrides for This Project: Resumes external workspace overrides for the current project.
Workspace Spectrum: Show Status and Diagnostics: Displays the active matches, rules path, and external workspace diagnostic info.
Workspace Spectrum: Show Logs (Output > Workspace Spectrum): Opens the real-time logging output channel.

🔧 Extension Settings

Setting	Default	Description
`workspaceSpectrum.enabled`	`true`	Enable or disable automatic rule application.
`workspaceSpectrum.rulesPath`	`"~/.workspace-spectrum/rules.json"`	Path to the rules file. Supports `~`, `%USERPROFILE%`, `$HOME`, and `${env:VAR}`.
`workspaceSpectrum.autoOpen`	`true`	Automatically reopen matching projects in an external isolated workspace.

📦 Packaging to VSIX

To build a standalone .vsix file for installation:

pnpm run package

This generates workspace-spectrum-0.2.0.vsix.

Installing the VSIX:

In Windows:

code --install-extension workspace-spectrum-0.2.0.vsix --force

In WSL (from inside your WSL terminal or via Windows CLI):

wsl code --install-extension /mnt/c/_Repos/vscolor/workspace-spectrum-0.2.0.vsix --force

📄 License

MIT License. Free and open source.

Workspace Spectrum

RelLabs