Copy quake.ps1 anywhere on Windows.
Requires PowerShell 7 (pwsh.exe) and WezTerm.
Windows PowerShell 5.1 reports the PowerShell 7 requirement instead of attempting to run the controller.
No Lua adapter, Nushell, or personal dotfiles required unless normal WezTerm config requires them.
Launcher
Invoke quake.ps1 with PowerShell 7.
Default invocation runs controller in foreground; -Background starts it hidden.
WezTerm GUI starts only on first toggle.
Option
Purpose
-Background
Start hidden controller
-Stop
Stop controller; restore hidden quake window without closing it
-Check
Compile, check discovery/shortcuts, print effective launch args; never launch GUI
-WezTermPath <path>
Select actual wezterm-gui.exe, including portable installs
-ConfigFile <path>
Select explicit normal WezTerm config; otherwise use native discovery
-InstallTask
Register hidden, non-elevated controller at current user's logon
Win + physical key below Esc summons/hides dedicated window (standard PC scan code 0x29).
Virtual key is resolved from active foreground keyboard layout at controller startup; restart controller after changing layouts if mapping differs.
Ctrl+Alt+Shift+F11 stops controller.
Windows Terminal's quake shortcut may conflict; controller reports registration failure instead of silently stealing an existing registration.
Task registration is explicit; launching controller never registers a task.
Task action pins discovered executable, script, and optional explicit config paths.
Uninstall task before relocating launcher; reinstall afterward.
If already moved, inspect/remove old WezTerm Quake Prototype task in Task Scheduler, then install from new location.
Dependency checks happen before hidden launch or task registration.
Task removal and controller stop remain available if WezTerm is uninstalled.
Discovery and isolation
WezTerm executable search: PATH (wezterm-gui.exe, or GUI beside wezterm.exe), launcher directory, Program Files, per-user Programs/WezTerm.
Use -WezTermPath for other portable locations.
Scoop-style launcher shims are rejected: select actual installed executable, not shim, so process identity remains strict.
Relative executable/config paths resolve against PowerShell's current filesystem location.
WezTerm loads normal config itself; native metadata, helpers, titles, and reload behavior remain intact.
Inherited WEZTERM_CONFIG_FILE is preserved; unrelated mux/pane routing variables are removed.
Normal config files remain untouched.
Global CLI overrides: use_resize_increments=false, default_workspace='quake', window_close_confirmation='AlwaysPrompt'.
These overrides survive normal config reloads.
Dedicated GUI process/local mux stays separate from ordinary windows; automatic shared-domain connections are disabled.
Normal session-save slots remain shared if normal config uses shared storage.
Controller targets exact dedicated window class and executable image; titles are irrelevant.
Exactly one matching window, including hidden windows, is required.
Multiple matching windows → refuse toggle instead of guessing.
WezTerm's own error/SSH windows can share this identity: a sole such window is targeted; multiple windows require manual resolution.
This is dedicated-window control, not semantic identification of terminal content.
Cold-start restore waits up to 15 seconds; placement must reach requested geometry before summon is logged.
Each summon requests repaint without background erasure, then one additional request after 250 ms.
Hide/new summon cancels stale retries; this is an empirical workaround for observed white-until-click rendering, not a renderer root-cause fix.
Runtime state
Logs and pending-launch guard live under Windows Local Application Data: wezterm/quake-prototype/.
No runtime state is written beside launcher.
Controller refuses duplicate pending launches.
Interrupted launch without recorded PID fails closed; inspect quake processes before removing launch.guard.
Virtual-desktop behavior remains unverified.
# WezTerm Quake prototype
Copy `quake.ps1` anywhere on Windows.
Requires PowerShell 7 (`pwsh.exe`) and WezTerm.
Windows PowerShell 5.1 reports the PowerShell 7 requirement instead of attempting to run the controller.
No Lua adapter, Nushell, or personal dotfiles required unless normal WezTerm config requires them.
## Launcher
Invoke `quake.ps1` with PowerShell 7.
Default invocation runs controller in foreground; `-Background` starts it hidden.
WezTerm GUI starts only on first toggle.
| Option | Purpose |
|---|---|
| `-Background` | Start hidden controller |
| `-Stop` | Stop controller; restore hidden quake window without closing it |
| `-Check` | Compile, check discovery/shortcuts, print effective launch args; never launch GUI |
| `-WezTermPath <path>` | Select actual `wezterm-gui.exe`, including portable installs |
| `-ConfigFile <path>` | Select explicit normal WezTerm config; otherwise use native discovery |
| `-InstallTask` | Register hidden, non-elevated controller at current user's logon |
| `-UninstallTask` | Remove logon task; leave running controller unchanged |
| `-WhatIf` | Preview task registration/removal |
Win + physical key below Esc summons/hides dedicated window (standard PC scan code `0x29`).
Virtual key is resolved from active foreground keyboard layout at controller startup; restart controller after changing layouts if mapping differs.
`Ctrl+Alt+Shift+F11` stops controller.
Windows Terminal's quake shortcut may conflict; controller reports registration failure instead of silently stealing an existing registration.
Task registration is explicit; launching controller never registers a task.
Task action pins discovered executable, script, and optional explicit config paths.
Uninstall task before relocating launcher; reinstall afterward.
If already moved, inspect/remove old `WezTerm Quake Prototype` task in Task Scheduler, then install from new location.
Dependency checks happen before hidden launch or task registration.
Task removal and controller stop remain available if WezTerm is uninstalled.
## Discovery and isolation
WezTerm executable search: PATH (`wezterm-gui.exe`, or GUI beside `wezterm.exe`), launcher directory, Program Files, per-user `Programs/WezTerm`.
Use `-WezTermPath` for other portable locations.
Scoop-style launcher shims are rejected: select actual installed executable, not shim, so process identity remains strict.
Relative executable/config paths resolve against PowerShell's current filesystem location.
WezTerm loads normal config itself; native metadata, helpers, titles, and reload behavior remain intact.
Inherited `WEZTERM_CONFIG_FILE` is preserved; unrelated mux/pane routing variables are removed.
Normal config files remain untouched.
Global CLI overrides: `use_resize_increments=false`, `default_workspace='quake'`, `window_close_confirmation='AlwaysPrompt'`.
These overrides survive normal config reloads.
Dedicated GUI process/local mux stays separate from ordinary windows; automatic shared-domain connections are disabled.
Normal session-save slots remain shared if normal config uses shared storage.
Controller targets exact dedicated window class and executable image; titles are irrelevant.
Exactly one matching window, including hidden windows, is required.
Multiple matching windows → refuse toggle instead of guessing.
WezTerm's own error/SSH windows can share this identity: a sole such window is targeted; multiple windows require manual resolution.
This is dedicated-window control, not semantic identification of terminal content.
Cold-start restore waits up to 15 seconds; placement must reach requested geometry before summon is logged.
Each summon requests repaint without background erasure, then one additional request after 250 ms.
Hide/new summon cancels stale retries; this is an empirical workaround for observed white-until-click rendering, not a renderer root-cause fix.
## Runtime state
Logs and pending-launch guard live under Windows Local Application Data: `wezterm/quake-prototype/`.
No runtime state is written beside launcher.
Controller refuses duplicate pending launches.
Interrupted launch without recorded PID fails closed; inspect quake processes before removing `launch.guard`.
Virtual-desktop behavior remains unverified.