Smart Workspace Launcher

A powerful, directory-based workspace manager for Windows. It treats a folder as a configuration file, allowing you to organize, sort, and launch groups of applications with complex rules just by renaming files and folders.

---

🚀 Features

• Zero Config: No JSON/XML files. Just drag, drop, and rename shortcuts.
• Smart Tracking: Tracks PIDs, Window Handles, or Process Names to ensure clean shutdowns.
• Safety First: Includes Session ID validation to prevent using stale logs after a reboot, and System Process Protection to prevent accidental termination of critical Windows components.
• Idempotent: Automatically skips apps that are already running (unless overridden).
• Session Management: Tracks every window launched. Press Shift on launch to close only the apps from that specific session.
• Dependency Chaining: Launch App B only after App A is fully loaded ([Wait]).
• Magic Folders: Subfolders act as rules (e.g., everything in \minimized launches minimized).

---

📦 Installation & Setup

Note: This script is designed to run as a compiled executable (.exe) for maximum stability and process tracking.

Automatic Build (Recommended)

1. Install AutoHotkey v2.
2. Open a terminal (Command Prompt or PowerShell) in the script's folder.
3. Run the script with the build flag:

   AutoHotkey.exe WorkspaceLauncher.ahk --build

4. The script will automatically locate your compiler (Ahk2Exe) and produce WorkspaceLauncher.exe.
   • If it can't find the compiler, a file dialog will open asking you to locate Ahk2Exe.exe manually.

Manual Build

Right-click WorkspaceLauncher.ahk > Compile Script.

---

⚙️ Usage & Modes

Once you have WorkspaceLauncher.exe, simply double-click it to start. By default, it creates and looks for a folder named Workspace next to itself.

GUI Dashboard (Default)

When you double-click the exe without any modifier keys or arguments, a GUI dashboard opens instead of immediately launching. The dashboard provides clickable access to all features:

Section	Controls	Description
Workspace	Path field + Browse button	Set or browse to your workspace folder.
Workspace Contents	ListView	Preview all items in the workspace with their order, name, state, and mode.
Launch	🚀 Launch All, ☑ Select & Launch	Launch the entire workspace or pick specific items.
Session	🧹 Close All, ☑ Sel. Close, 👁 Toggle Hidden, ☑ Sel. Toggle	Manage the active session — close tracked apps or toggle visibility.
Tools	💾 Save Workspace, 📂 Open Folder, ❓ Help	Save current windows as a workspace, open the folder in Explorer, or view help.
Status Bar	Session status + Workspace item count	Shows how many apps are tracked and how many items are in the workspace.

Modifier Key Modes

Hold a modifier key while double-clicking the exe to bypass the dashboard and go directly to a specific mode:

Modifier Key	Mode	Description
None	Dashboard	Opens the GUI dashboard (see above).
Hold Shift	Cleanup	Closes only the apps tracked in the current session (plus specific "Cleanup" folders).
Hold Ctrl	Selective Launch	Shows a checklist GUI to choose which apps to launch.
Hold Alt	Toggle Visibility	Hides or Shows background apps (only those launched with [Hide]).
Hold Ctrl+Alt	Selective Toggle	Shows a checklist GUI to Show/Hide any app in the session.
Hold Ctrl+Shift	Save Workspace	Captures currently open windows and saves them as a workspace folder of shortcuts with auto-detected tags.

Command Line Arguments

You can manage multiple workspaces by passing the folder path or flags as arguments.

; Launch a specific gaming workspace
WorkspaceLauncher.exe "D:\Workspaces\Gaming"

; Trigger cleanup for the default workspace
WorkspaceLauncher.exe --close

; Trigger visibility toggle
WorkspaceLauncher.exe --toggle

; Save current open windows as a workspace (interactive GUI)
WorkspaceLauncher.exe --save

; Save workspace to the default Workspace/ folder, skip GUI
WorkspaceLauncher.exe --save --here --auto

; Save workspace into a timestamped subfolder
WorkspaceLauncher.exe --save "D:\Workspaces" --timestamp

; Save workspace with a custom name, replace existing shortcuts
WorkspaceLauncher.exe --save "D:\Workspaces" --name=MyProject --replace

; Save workspace including tray/background apps in expanded view
WorkspaceLauncher.exe --save --tray

Save Mode Flags

Flag	Description
--save	Enter Save Workspace mode (capture open windows).
--here	Use the default Workspace/ folder next to the exe instead of a folder picker.
--auto	Skip the GUI and capture all detected windows automatically.
--timestamp	Create a timestamped subfolder (YYYYMMDD_HHmmss/) inside the target.
--name=X	Create a named subfolder (X/) inside the target.
--merge	If the target folder already has shortcuts, silently add new ones alongside them.
--replace	If the target folder already has shortcuts, silently delete them first.
--tray	Show the Background/Tray Apps section expanded by default in the Save GUI.

---

🏷️ Filename Tags

Rename your files/shortcuts to apply rules. Tags are case-insensitive and support [], {}, or <>.

Note on Aliases: Some tags support multiple names (Aliases) for convenience. You can use either the Short or Long version.

Primary Tag	Aliases	Function	Example
[N]	(None)	Sets launch order (Natural Sort).	[1] Chrome.lnk
[Multi]	[Dup], [AllowDup]	Allow Duplicates. Forces a new instance even if one is already running.	[2] Notepad [Multi].lnk
[Wait]	(None)	Waits for this app's window to appear before launching the next item.	[1] Server [Wait].bat
[Wait=N]	(None)	Waits for the item with Order N to finish launching.	[5] Client [Wait=1].exe
[Delay=T]	(None)	Sleeps after launching. Supports ms, s, m.	[3] DB [Delay=5s].lnk
[Admin]	(None)	Runs the file as Administrator.	CMD [Admin].lnk
[Min]	[Minimized]	Launches minimized.	Spotify [Min].lnk
[Max]	[Maximized]	Launches maximized.	Code [Max].lnk
[Hide]	[Hidden]	Launches hidden (background processes).	Script [Hide].ahk
[ForceKill]	[Kill], [KillForce]	Forces killing the app instead of graceful closing. Required if you want to forcefully terminate apps in cleanup folders or in cleanup mode.	Steam [ForceKill].lnk
[WaitWindow]	[WaitWin]	Crucial fix for modern apps. Waits for the app to fully load its UI before applying Min/Max/Hide.	OneNote [Max] [WaitWin].lnk
[WaitWin=T]	(None)	Same as above, but specifying a custom wait duration.	[WaitWindow=500ms]

---

🧩 Advanced Tracking

Different apps behave differently. Use these tags to ensure the script tracks the correct window/process for cleanup.

Tag	Behavior & Use Case	Cleanup Action
Standard (Default)	Tracks the Process ID (PID) returned by Windows. Good for standard apps (Notepad, Paint).	Closes specific PID.
[Match=Name]	Wrapper Scripts. If you launch a .bat, use this to track the actual app it starts. [Match=wt.exe] ignores the .bat PID and waits for wt.exe.	Closes specific window/PID of the matched app.
[HWND]	Specific Windows. Forces tracking by Window Handle instead of PID. Useful if an app changes PIDs rapidly but keeps the window open.	Closes specific Window Handle.
[TrackExe]	Electron / Multi-Process Apps. Tracks by Executable Name. Use this for Discord, Slack, VS Code.	Kills ALL instances of that executable name found on the system.

Tag Aliases:

• [HWND] can also be written as [Win] or [Window].
• [TrackExe] can also be written as [Exe] or [ByExe].

---

📂 Magic Folders

Create subfolders inside your workspace to apply rules to everything inside them. Note: Folder names are Strict (no aliases allowed) but Case-Insensitive.

Folder Name	Launch Behavior	Cleanup Behavior	Use Case
Minimized	Launch Minimized.	Standard Close.	Background music/chats.
Maximized	Launch Maximized.	Standard Close.	Main work tools.
Hidden	Launch Hidden.	Standard Close.	Servers/Scripts.
Monitor2	Move to Monitor 2.	Standard Close.	Secondary screen apps.
CloseOnLaunch	Gracefully Close these apps.	Ignored.	"Close Steam when I start Work".
AlwaysClose	Gracefully Close app.	Gracefully Close app.	Ensure app is closed on Start AND Stop.
CloseOnCleanup	Ignored.	Gracefully Close app.	Close apps only when finishing session.
Ignore	Ignored.	Ignored.	Storage / Assets.

Pro Tip: To Kill (Force Terminate) an app in a Close folder instead of gracefully closing it, add the [ForceKill] tag to the shortcut filename.

2. If you place a Folder Shortcut inside a Close magic folder, the script will attempt to close the specific Explorer window matching that folder's name. It will not kill explorer.exe.

---

🔧 Technical Details & Safety

Session Log (%Temp%\Workspace_Session.log)

The script creates a session log to track what it launched.

• Session ID: The log is stamped with the computer's Boot Time. If you restart your PC, the script detects the timestamp mismatch and discards the old log to prevent killing incorrect PIDs (BSOD prevention).
• Format: TYPE | ID | TARGET | FORCE_FLAG | HIDDEN_FLAG

Cleanup Logic

• Interactive (Ctrl+Shift): Reads the log and presents a GUI to uncheck apps you want to save.
• Standard: Reads the log in reverse order (LIFO).
  • PID/HWND: Sends WinClose. If [ForceKill] is used, sends ProcessClose.
  • EXE: Kills all processes matching that name.
• Safety: Critical system processes (e.g., svchost.exe, csrss.exe) are blacklisted and cannot be killed by this script.

---

💾 Save Workspace Mode

Save Workspace is the reverse workflow: instead of launching apps from shortcuts, it captures your currently open windows and generates a workspace folder of .lnk shortcuts with auto-detected tags.

How It Works

1. Trigger Save mode via Ctrl+Shift on launch, or with --save flag.
2. Choose a target folder (folder picker, --here, or pass a path argument).
3. Review detected windows in the Save GUI — each app shows its auto-detected tags (e.g., [Max], [TrackExe], [Monitor2]).
4. Edit tags inline if needed, uncheck apps you don't want.
5. Click Save — shortcuts are created with [N] AppName [Tags].lnk naming.

Smart Detection

• Window State: Automatically detects Minimized, Maximized, Hidden, or Normal state.
• Multi-Monitor: Detects windows on Monitor 2 and applies [Monitor2] tag.
• Electron Apps: Known multi-process apps (VS Code, Discord, Slack, etc.) automatically get [TrackExe] suggested.
• Generic Host Resolution: Apps running via interpreters (e.g., Anki → pythonw.exe, or Java apps → javaw.exe) are automatically resolved by scanning Start Menu shortcuts. The shortcut's real target, args, and working directory are used instead of the generic host executable. A [Match=pythonw.exe] tag is added so WorkspaceLauncher can match the window at launch time.
• Explorer Folders: Each open Explorer folder window is captured as a separate folder shortcut.
• Tray/Background Apps: Optionally include background processes (collapsed by default, expand with --tray flag or click the toggle in the GUI).

Save GUI Layout

The interactive GUI shows two sections:

• Window Apps — Visible windows, checked by default with auto-detected tags in an editable text field.
• Background/Tray Apps — Background processes (collapsed by default), unchecked, with [Hide] tag.

Each row has a checkbox and an editable tags field, allowing you to customize before saving.

Conflict Handling

If the target folder already contains .lnk files:

• Interactive prompt (default): Choose Merge, Replace All, or Cancel.
• --merge: Silently add new shortcuts alongside existing ones.
• --replace: Silently delete all existing .lnk files first.

---

🛠 Troubleshooting & Tips

1. App launches but Min/Max/Hide doesn't work?

• Cause: The app takes too long to initialize its window, or the script acted too fast on a splash screen/helper window.
• Fix: Add [WaitWindow] tag. This forces the script to wait until the app is "Input Idle" (ready) before sending window commands.

2. Script tracks the wrong thing (e.g., a Batch file instead of the App)?

• Cause: You are launching a wrapper script/launcher.
• Fix: Add [Match=RealApp.exe]. The script will ignore the Batch file PID and wait for RealApp.exe to appear.

3. Electron Apps (Discord, VS Code, Slack) behaving weirdly?

• Cause: These apps spawn multiple processes and invisible utility windows.
• Fix: Use [TrackExe]. This tells the script to stop worrying about specific PIDs and just manage the "Application" as a whole.
• Example: [TrackExe] [Match=Discord.exe] Discord.lnk

4. Background/Tray Apps not closing?

• Cause: Apps that minimize to tray often ignore standard "Close" commands.
• Fix: Add [ForceKill]. This uses ProcessClose which terminates them instantly.

5. Some Modern Apps showing "Phantom Windows" or blocked inputs?

• Cause: The script grabbed a hidden 1x1 pixel helper window instead of the main UI.
• Fix: Add [WaitWindow]. The script uses intelligent logic to filter out invisible windows, but it needs the main window to actually exist first.

6. General Stability

• If your PC is slow or apps launch heavily, use [Delay=1s] between heavy items to prevent CPU choking.

7. Save mode shows fewer apps than expected?

• Cause: Some apps run as Administrator. The launcher cannot inspect elevated processes from a non-admin context.
• Fix: Run WorkspaceLauncher.exe --save as Administrator, or manually add missing shortcuts after saving.

8. Save mode captured too many tray/background processes?

• Cause: Windows has many background services. The Background/Tray section lists all non-system processes.
• Fix: Tray apps default to unchecked in the GUI. Only check the ones you actually want. Common OS services are already filtered out.

9. Saved shortcuts not working correctly when launched?

• Cause: Some apps (especially UWP/Store apps) may need additional tags like [WaitWindow] or [TrackExe].
• Fix: The save feature auto-detects common Electron apps and suggests [TrackExe]. For other apps, manually edit the shortcut filename to add the appropriate tags after saving.

10. App detected as "pythonw" or "javaw" instead of its real name?

• Cause: The app runs via a generic host process (Python, Java, Node.js, etc.) and no matching Start Menu shortcut was found.
• Fix: The save feature automatically scans Start Menu for matching shortcuts. If the match isn't found, rename the generated shortcut to the real app name and ensure a Start Menu shortcut exists for the app.