User Manual

EasyContextSwitch orchestrates your Windows development environments via workspace profiles — JSON files stored in %APPDATA%\EasyContextSwitch\workspaces\. When you activate a workspace, the engine runs your launch sequence (processes, apps, URLs) and tears down the previous workspace automatically.

All application data is stored locally on your machine — no cloud dependencies.

Workspace profile JSON files. Each file is named <workspace_id>.json.

Global application settings (Docker auto-start, app auto-start, trigger rules).

Trial timing, license key, and per-workspace activation counts.

Persisted window position and size — restored automatically on next launch.

Auto-generated Docker Compose file for the built-in EasyEditor service.

Understanding the exact order of operations helps you design reliable workspace sequences.

These top-level fields define a workspace profile's identity and global shortcut.

The launch_sequence array defines every operation that runs when activating this workspace. Steps execute in strictly ascending step order.

The type field on each launch step determines how the engine executes it.

// background_process — run docker-compose, blocking next step
{
  "step": 1,
  "type": "background_process",
  "executable": "docker",
  "arguments": ["compose", "up", "-d"],
  "wait_for_completion": true
}

// health_check — wait for API to be ready
{
  "step": 2,
  "type": "health_check",
  "executable": "http://localhost:8080/health",
  "timeout_seconds": 30
}

// application — launch VS Code, snap to monitor 1
{
  "step": 3,
  "type": "application",
  "executable": "C:\\Users\\you\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe",
  "arguments": ["C:\\dev\\myproject"],
  "window_rules": { /* see Window Rules */ }
}

// url — open multiple tabs
{
  "step": 4,
  "type": "url",
  "executable": "",
  "arguments": ["http://localhost:8080", "https://github.com"]
}

The window_rules object, nested inside an application launch step, instructs the Win32 engine to find and reposition the launched application's window on the target monitor.

{
  "title_match": "myproject",
  "monitor": 1,
  "x": 0,
  "y": 0,
  "width": 960,
  "height": 1080
}

The teardown_sequence array defines cleanup steps that run when switching away from this workspace. Use it to shut down services, kill processes, and reverse any changes made during activation.

The optional virtual_desktop field maps the workspace to a Windows Virtual Desktop. Set it to a positive integer to switch to that virtual desktop during activation.

Templates provide pre-configured workspace profiles that you can install with a single click. Each template includes a complete launch sequence, teardown steps, hotkeys, and window rules — ready to use as-is or customised to your environment.

EasyContextSwitch ships with 8 built-in workspace templates covering common development scenarios. Each template is a fully functional example — install it, tweak the paths, and start working.

Stored in settings.json under the key auto_start_docker. When enabled, EasyContextSwitch automatically starts Docker Desktop on application launch if the Docker daemon is not already running.

{
  "auto_start_docker": true,
  "trigger_rules": []
}

Stored in settings.json under the key auto_start_app. When enabled, EasyContextSwitch automatically launches when Windows starts by adding an entry to the Windows Registry under HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run.

{
  "auto_start_docker": true,
  "auto_start_app": true,
  "trigger_rules": []
}

The Capture Current Layout button in the workspace editor reads the position, size, and title of every visible window on your desktop. Use it to quickly fill in window_rules values without manually measuring pixels.

Trigger rules automatically activate a workspace when a specific application gains focus. The engine polls the active foreground window every 3 seconds and activates the mapped workspace if the focused process matches a rule.

Example trigger rule mappings:

{
  "auto_start_docker": false,
  "trigger_rules": [
    {
      "process_name": "code.exe",
      "workspace_id": "proj_alpha_backend"
    },
    {
      "process_name": "devenv.exe",
      "workspace_id": "dotnet_frontend"
    }
  ]
}

The hotkey field uses a +-delimited string of one or more modifier keys followed by a regular key. Hotkeys are registered system-wide and fire regardless of which window is in focus.

Workspace configurations can be backed up and shared as ZIP archives containing all .json workspace files.

EasyContextSwitch starts with a 14-day free trial on first install. During the trial, all features are fully unlocked with no limitations.

Stores trial start time, last-checked timestamp, license key, and per-workspace activation counts.

License keys are validated offline using a cryptographic checksum algorithm — no internet connection or account required. Enter your key in the Settings panel to unlock the application permanently.

EasyContextSwitch is distributed under a balanced open-source license combining the GNU AGPL-3.0 with the Commons Clause v1.0 (Non-Commercial restriction) and a Trademark Clause.

Allowed vs. Prohibited Uses

GNU AFFERO GENERAL PUBLIC LICENSE
Version 3, 19 November 2007

Copyright (C) 2026 EasyEditor, EasyAI, EasyGit, EasyNotes Contributors

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

---

ADDITIONAL TERMS - COMMONS CLAUSE + TRADEMARK

1. COMMONS CLAUSE - NON-COMMERCIAL USE ONLY

The Software is provided to you by the Licensor under the License, as defined
below, subject to the following condition.

Without limiting other conditions in the License, the grant of rights under the
License will not include, and the License does not grant to you, the right to
Sell the Software.

For purposes of the foregoing, "Sell" means practicing any or all of the rights
granted to you under the License to provide to third parties, for a fee or other
consideration (including without limitation fees for hosting or consulting/
support services related to the Software), a product or service whose value
derives, entirely or substantially, from the functionality of the Software.

Any license notice or attribution required by the License must also include
this Commons Clause License Condition notice.

2. TRADEMARK CLAUSE

The names EasyContextSwitch and its logo are trademark of the project.

You may NOT:
1. Use the names "EasyContextSwitch" or any confusingly similar names for derivative works
2. Use the project's logos or any similar branding for derivative works
3. Claim that your derivative work is endorsed by or affiliated with EasyContextSwitch
4. Redistribute EasyContextSwitch under a different name as if it were your own product
5. Sell EasyContextSwitch or any derivative work

You MAY:
1. Modify the source code and use it internally
2. Distribute modified versions for non-commercial purposes (with attribution)
3. Use EasyContextSwitch as a component in your project (with proper attribution)
4. Create forks for development purposes (clearly labeled as forks)
5. Contribute improvements back to the project

---

For Commons Clause information, see:
https://commonsclause.com/

For the full AGPL-3.0 license text, visit:
https://www.gnu.org/licenses/agpl-3.0.html

A complete, production-ready workspace profile for a Go backend project demonstrating all available configuration fields.

{
  "workspace_id": "proj_alpha_backend",
  "name": "Project Alpha — Go Backend",
  "hotkey": "Ctrl+Alt+A",
  "virtual_desktop": 2,

  "launch_sequence": [
    {
      "step": 1,
      "type": "background_process",
      "executable": "docker",
      "arguments": ["compose", "-f", "C:\\dev\\alpha\\docker-compose.yml", "up", "-d"],
      "wait_for_completion": true
    },
    {
      "step": 2,
      "type": "health_check",
      "executable": "http://localhost:5432",
      "timeout_seconds": 30
    },
    {
      "step": 3,
      "type": "application",
      "executable": "C:\\Users\\you\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe",
      "arguments": ["C:\\dev\\alpha"],
      "window_rules": {
        "title_match": "alpha",
        "monitor": 1,
        "x": 0,
        "y": 0,
        "width": 1280,
        "height": 1440
      }
    },
    {
      "step": 4,
      "type": "url",
      "executable": "",
      "arguments": [
        "http://localhost:8080/health",
        "https://github.com/your-org/alpha"
      ]
    }
  ],

  "teardown_sequence": [
    {
      "type": "command",
      "executable": "docker",
      "arguments": ["compose", "-f", "C:\\dev\\alpha\\docker-compose.yml", "down"]
    },
    {
      "type": "kill_process",
      "process_name": "Code.exe"
    }
  ]
}