# 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 ` | Select actual `wezterm-gui.exe`, including portable installs | | `-ConfigFile ` | 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.