About¶
Welcome to the WTQ docs!
WTQ runs in the background, and enables sliding applications on- and off the screen, Quake style.
Supports:
- Windows 10 and 11
- KDE Plasma 5 & 6 (Wayland only)
See Installation to get started.
Here's an example where WTQ runs on Windows 10, toggling Windows Terminal, Double Commander, Process Hacker and KeePassXC.
And here's one on KDE Plasma 6, toggling WezTerm, Dolphin System Monitor and KeePassXC.
Why "Quake" Style
The game Quake (by id Software) is generally considered the game that popularized toggling of the console onto the screen, by sliding it from the top. See this video for an example of what that looked like.
The "WTQ" Name
WTQ initially started as a companion app for Microsoft's thrilling sequel to the classic command prompt; Windows Terminal. Fit that with Quake-style toggling, and you get "Windows Terminal Quake".
Much later, support for other terminals was added, and support for toggling apps that were not terminals at all.
So now I refer to it as "WTQ", not having the balls to straight up rename it.
Installation¶
Windows¶
Scoop¶
A command-line installer for Windows.
Note
The WTQ Scoop packages has moved to the Scoop extras bucket.
scoop bucket add extras
scoop install extras/wtq
A shortcut is then available named WTQ - Windows Terminal Quake, or you can just run wtq
from a command line or Win+R.
Start menu entry after installation.
Update (just WTQ):
scoop update wtq
WinGet¶
winget install windows-terminal-quake
You can then call "wtq" from the command line.
After having done that at least once, a shortcut will appear in the start menu, called WTQ - Main Window.
Start menu entry after installation.
Update (just WTQ):
winget upgrade windows-terminal-quake
Where's WTQ Installed?
You can run
winget --info
To find out where apps are installed:
Windows Package Manager v1.10.340
(...)
Portable Package Root (User) %LOCALAPPDATA%\Microsoft\WinGet\Packages
Manual¶
See the latest release, and pick a zip.
- Self-Contained
Slightly larger, but does not require dependencies to be installed (i.e. .Net). - Framework-Dependent
Smaller, but requires .Net 9 to be installed.
Build From Source¶
Dependencies
- Requires the .Net 9 SDK to be installed
You can also clone the repo and run the Install build target, which will build and install WTQ: ~/AppData/Local/wtq
.
git clone https://github.com/flyingpie/windows-terminal-quake.git
cd windows-terminal-quake
./build.ps1 Install
Uninstall:
./build.ps1 Uninstall
You can also take a look at the build options, do see more options for building, including without actually installing:
./build.ps1 --help
Linux¶
Arch AUR¶
Multiple versions are published to the Arch User Repository (AUR):
wtq-bin (Recommended)¶
- Latest stable release, pre-built;
- Downloads from GitHub Releases;
- Quicker to install and minimal dependencies.
yay -S wtq-bin
or
paru -S wtq-bin
wtq¶
- Latest stable release, built from source;
- Purist open source, but takes a bit longer to install and has a bit more (build-time) dependencies.
yay -S wtq
or
paru -S wtq
Flatpak¶
Since WTQ only supports KDE Plasma on Linux, it's not a great fit for Flathub.
As an alternative, you can use the Flatpak remote hosted on the sister repository. It uses the Flatter GitHub Action for building the Flatpak itself, and everything is hosted on GitHub Pages.
The app itself and the Flatpaks are built entirely from source, using GitHub Actions, in the open.
Per-User¶
flatpak --user remote-add flyingpie https://flatpak.flyingpie.nl/index.flatpakrepo
flatpak --user install nl.flyingpie.wtq
System-Wide¶
flatpak remote-add flyingpie https://flatpak.flyingpie.nl/index.flatpakrepo
flatpak install nl.flyingpie.wtq
Manual¶
See the ~/linux/install-or-upgrade-wtq.sh script that downloads the latest version of WTQ, installs it to ~/.local/share/wtq
, and creates a wtq.desktop
file.
As a 1-liner:
bash <(curl -s https://raw.githubusercontent.com/flyingpie/windows-terminal-quake/refs/heads/master/linux/install-or-upgrade-wtq.sh)
And the ~/linux/uninstall-wtq.sh uninstall script.
bash <(curl -s https://raw.githubusercontent.com/flyingpie/windows-terminal-quake/refs/heads/master/linux/uninstall-wtq.sh)
Settings File Remains
The WTQ settings are not removed by this script. These are usually located at ~/.config/wtq
, also see Settings.
Build From Source¶
Dependencies
- Requires the .Net 9 SDK to be installed
- Requires webkit2gtk-4.1 to be installed
You can also clone the repo and run the Install build target, which will build and install WTQ at ~/.local/share/wtq
(respects XDG spec).
git clone https://github.com/flyingpie/windows-terminal-quake.git
cd windows-terminal-quake
./build.sh Install
Uninstall:
./build.sh Uninstall
You can also take a look at the build options, do see more options for building, including without actually installing:
./build.sh --help
App examples¶
TODO
Settings¶
Settings are stored in a JSON file, usually named wtq.jsonc
.
The file can use the extension .json
, .jsonc
or .json5
. The latter two are supported, so that editors like VSCode automatically switch to "JSON with Comments", making working with comments nicer.
Settings File Locations¶
Where's My Settings File?
The file can be in several places, to support different use cases and preferences.
You can quickly open either the settings file, or the directory that contains the settings file by clicking the tray icon -> Open Settings File, or Open Settings Directory.
Tray icon menu options.
Additionally, it's also displayed in the GUI, with a link for convenience.
Settings location in the GUI.
On Windows¶
These locations are considered, in order:
- A path defined by an environment variable named
WTQ_CONFIG_FILE
(regardless of filename or extension) - Next to the WTQ executable
- When using Scoop:
C:\Users\username\scoop\apps\wtq-latest\current
- When using WinGet:
C:\Users\username\AppData\Local\Microsoft\WinGet\Packages\flyingpie.windows-terminal-quake_Microsoft.Winget.Source_8wekyb3d8bbwe
- Or wherever else the
wtq.exe
file is
- When using Scoop:
- In %USERPROFILE%\.config
C:\users\username\.config\wtq.json
- In user home
C:\users\username\wtq.json
- In user home, as a dot file
C:\users\username\.wtq.json
- In app data
C:\users\username\AppData\Roaming\wtq\wtq.json
If no settings were found at any of these locations, WTQ creates a settings file at C:\Users\username\AppData\Roaming\wtq\wtq.jsonc
.
On Linux¶
These locations are considered, in order:
- A path defined by an environment variable named
WTQ_CONFIG_FILE
(regardless of filename or extension) - Next to the WTQ executable
- When using the install script:
/home/username/.local/share/wtq
- When using the install script:
- In
$XDG_CONFIG_HOME
, if defined (following to the XDG spec)/home/username/.config/wtq.json
- In ~/.config (the default for XDG_CONFIG_HOME, if is it not defined)
/home/username/.config/wtq.json
- In user home
/home/username/wtq.json
- In user home, as a dot file
/home/username/.wtq.json
If no settings were found at any of these locations, WTQ creates a settings file at $XDG_CONFIG_HOME
: /home/username/.config/wtq/wtq.jsonc
.
TODO
TODO: Mention wtq.schema.json
TODO
TODO: Mention GUI
Global options¶
Defines WTQ-wide options, including the list of configured apps.
General¶
Apps¶
Applications to enable Quake-style dropdown for.
{
"Apps": [
{ "Name": "App 1" },
{ "Name": "App 2" },
// ...
]
}
Hotkeys¶
Global hotkeys, that toggle either the first, or the most recently toggled app.
Defaults to None
{
"Hotkeys": [
{ "Modifiers": "Control", "Key": "Q" }
]
}
Feature flags¶
Sometimes functionality is added or changed that carries more risk of introducing bugs.
For these cases, such functionality can be put behind a "feature flag", which makes them opt-in or opt-out.
That way, we can still merge to master, and make it part of the stable release version (reducing branches and dev builds and what not), but still have a way back should things go awry.
Defaults to None
{
"FeatureFlags": "None",
// ...
}
Show UI on start¶
Whether to show the GUI when WTQ is started.
Defaults to False
{
"ShowUiOnStart": "False",
// ...
}
Tray icon (color) style¶
The tray icon (color) style (dark/light).
Defaults to Auto
-
Auto
Attempt to detect the OS theme and use the appropriate style based on that. -
Dark
Dark icon, works best on lighter themes. -
Light
Light icon, works best on darker themes.
{
"TrayIconStyle": "Auto",
// ...
}
Animation¶
Animation target FPS¶
How many frames per second the animation should be.
Note that this may not be hit if moving windows takes too long, hence "target" fps.
Must be between 5 and 120, to prevent issues that can arise with values that are too low or too high.
Defaults to 40
{
"AnimationTargetFps": "40",
// ...
}
None¶
Api¶
Options related to the HTTP API, that can be used to control WTQ programmatically.
Defaults to None
{
"Api": "None",
// ...
}
App options¶
Defines the options for a single toggleable app (eg. Windows Terminal, some other terminal, a file browser, etc.).
App¶
Name¶
A logical name for the app, used to identify it across config reloads.
Appears in logs.
{
"Name": "Terminal",
// ...
}
Hotkeys¶
One or more keyboard shortcuts that toggle in- and out this particular app.
Defaults to None
{
"Apps": [
{
"Hotkeys": "None"
// ...
}
]
}
Process¶
Filename¶
The filename to use when starting a new process for the app.
E.g. notepad, dolphin, etc.
Note that you can also put absolute paths in here.
{
"Apps": [
{
"FileName": "wt"
// ...
}
]
}
Arguments¶
Command-line arguments that should be passed to the app when it's started.
Note that this only applies when using an AttachMode that starts the app.
Defaults to None
{
"Apps": [
{
"Arguments": "None"
// ...
}
]
}
Argument list¶
Command-line arguments that should be passed to the app when it's started.
Note that this only applies when using an AttachMode that starts the app.
Defaults to None
{
"Apps": [
{
"ArgumentList": [
"--allow-screencapture",
"--debug-info",
],
// ...
}
]
}
Working directory¶
Working directory when starting a new process.
Useful if the filename isn't available through PATH.
Defaults to None
{
"Apps": [
{
"WorkingDirectory": "None"
// ...
}
]
}
Process name¶
Apps sometimes have process names different from their filenames. This field can be used to look for the process name in such cases. Windows Terminal is an example, with filename wt, and process name WindowsTerminal.
Supports regular expressions.
Defaults to None
{
// Using with Windows Terminal requires both "Filename" and "ProcessName".
"Apps": {
"Filename": "wt",
"ProcessName": "^WindowsTerminal$"
}
}
Main window¶
(Windows only) Matches only "main" windows; the initial window a process spawns.
When a process spawns multiple windows, 1 is usually the "main" window. In many cases, this is also the window that you'd want to use WTQ with. Non-main-windows are usually child windows like popups and such. When the other (non-main) windows cannot be easily differentiated from the main window (for example through the window class or -title), the "is-main-window"-property can be very useful to home in on the desired window.
A common example of an app where this would not help, is a browser, that can spawn tons of windows on the same process name.
Defaults to Either
-
MainWindowOnly
Match main windows only. -
NonMainWindowOnly
Match non-main windows only. -
Either
Match main- and non-main windows.
{
"Apps": [
{
"MainWindow": "Either"
// ...
}
]
}
Window class¶
(Windows only) Matches windows based on their Win32 Window Class.
Supports regular expressions.
Defaults to None
{
"Apps": [
{
"WindowClass": "^ApplicationFrameWindow$"
// ...
}
]
}
Window title¶
Match windows based on their title (sometimes referred to as "caption").
Supports regular expressions.
Defaults to None
{
"Apps": [
{
"WindowTitle": "^Mozilla Firefox - WhatsApp$"
// ...
}
]
}
Behavior¶
Window title override¶
Attempt to set the window title to a specific value.
Useful for cases where multiple programs control window placement (such as when using WTQ together with a window manager) and the window title can be used to opt-out in the other program.
Defaults to None
{
"Apps": [
{
"WindowTitleOverride": "None"
// ...
}
]
}
Shared options¶
Options that are available both in global- and per-app options.
Process¶
Attach mode¶
How WTQ should get to an instance of a running app.
I.e. whether to start an app instance if one cannot be found.
Defaults to FindOrStart
-
Find
Only look for existing app instances (but don't create one). -
FindOrStart
Look for an existing app instance, create one if one does not exist yet. -
Manual
Attach to whatever app is in the foreground when pressing an assigned hotkey.
{
// Globally:
"AttachMode": "FindOrStart",
// For one app only:
"Apps": [
{
"AttachMode": "FindOrStart"
}
]
}
Behavior¶
Always on top¶
Whether the app should always be on top of other windows, regardless of whether it has focus.
Defaults to False
{
// Globally:
"AlwaysOnTop": "False",
// For one app only:
"Apps": [
{
"AlwaysOnTop": "False"
}
]
}
Hide on focus lost¶
Whether the app should be toggled off when another app gets focus.
Defaults to Always
-
Always
Toggle off the app when focus is lost. -
Never
Do not toggle off the app when focus is lost.
{
// Globally:
"HideOnFocusLost": "Always",
// For one app only:
"Apps": [
{
"HideOnFocusLost": "Always"
}
]
}
Taskbar icon visibility¶
When to show the app window icon on the taskbar.
Defaults to AlwaysHidden
-
AlwaysHidden
Never show the taskbar icon. -
AlwaysVisible
Always show the taskbar icon (note that this can look a bit weird when the app is toggled off). -
WhenAppVisible
Only show the taskbar icon when the app is toggled on.
{
// Globally:
"TaskbarIconVisibility": "AlwaysHidden",
// For one app only:
"Apps": [
{
"TaskbarIconVisibility": "AlwaysHidden"
}
]
}
Opacity¶
Make the window see-through (applies to the entire window, including the title bar).
0 (invisible) - 100 (opaque).
Defaults to 100
{
// Globally:
"Opacity": "80",
// For one app only:
"Apps": [
{
"Opacity": "80"
}
]
}
Position¶
Horizontal screen coverage¶
Horizontal screen coverage, as a percentage.
Defaults to 95
{
// Globally:
"HorizontalScreenCoverage": "95",
// For one app only:
"Apps": [
{
"HorizontalScreenCoverage": "95"
}
]
}
Horizontal align¶
Where to position an app on the chosen monitor, horizontally.
Defaults to Center
-
Center
Center of the screen. -
Left
Left of the screen. -
Right
Right of the screen.
{
// Globally:
"HorizontalAlign": "Center",
// For one app only:
"Apps": [
{
"HorizontalAlign": "Center"
}
]
}
Vertical screen coverage¶
Vertical screen coverage as a percentage (0-100).
Defaults to 95
{
// Globally:
"VerticalScreenCoverage": "95",
// For one app only:
"Apps": [
{
"VerticalScreenCoverage": "95"
}
]
}
Vertical offset¶
How much room to leave between the top of the app window and the top of the screen, in pixels.
Defaults to 0
{
// Globally:
"VerticalOffset": "0",
// For one app only:
"Apps": [
{
"VerticalOffset": "0"
}
]
}
Off-screen locations¶
When moving an app off the screen, WTQ looks for an empty space to move the window to.
Depending on your monitor setup, this may be above the screen, but switches to below if another monitor exists there.
By default, WTQ looks for empty space in this order: Above, Below, Left, Right.
Defaults to None
{
// Globally:
"OffScreenLocations": ["Above", "Below", "Left", "Right"],
// For one app only:
"Apps": [
{
"OffScreenLocations": ["Above", "Below", "Left", "Right"],
}
]
}
Monitor¶
Prefer monitor¶
Which monitor to preferably drop the app.
Defaults to WithCursor
-
WithCursor
The monitor where the mouse cursor is currently at. -
AtIndex
The monitor at the index as specified by MonitorIndex (0-based). -
Primary
The monitor considered primary by the OS.
{
// Globally:
"PreferMonitor": "WithCursor",
// For one app only:
"Apps": [
{
"PreferMonitor": "WithCursor"
}
]
}
Monitor index¶
If PreferMonitor is set to AtIndex, this setting determines what monitor to choose.
Zero based, e.g. 0, 1, etc.
Defaults to 0
{
// Globally:
"MonitorIndex": "0",
// For one app only:
"Apps": [
{
"MonitorIndex": "0"
}
]
}
Animation¶
Animation duration¶
How long the animation should take, in milliseconds.
Defaults to 250
{
// Globally:
"AnimationDurationMs": "250",
// For one app only:
"Apps": [
{
"AnimationDurationMs": "250"
}
]
}
Animation type (toggle ON)¶
The animation type to use when toggling on an application.
Defaults to EaseOutQuart
-
Linear
-
EaseInOutSine
-
EaseInBack
-
EaseInCubic
-
EaseInQuart
-
EaseOutBack
-
EaseOutCubic
-
EaseOutQuart
{
// Globally:
"AnimationTypeToggleOn": "EaseOutQuart",
// For one app only:
"Apps": [
{
"AnimationTypeToggleOn": "EaseOutQuart"
}
]
}
Animation type (toggle OFF)¶
The animation type to use when toggling off an application.
Defaults to EaseInQuart
-
Linear
-
EaseInOutSine
-
EaseInBack
-
EaseInCubic
-
EaseInQuart
-
EaseOutBack
-
EaseOutCubic
-
EaseOutQuart
{
// Globally:
"AnimationTypeToggleOff": "EaseInQuart",
// For one app only:
"Apps": [
{
"AnimationTypeToggleOff": "EaseInQuart"
}
]
}
Events¶
Event hooks¶
Execute a program when some event occurs.
Defaults to None
{
// Globally:
"EventHooks": "None",
// For one app only:
"Apps": [
{
"EventHooks": "None"
}
]
}
Building From Source¶
TODO
Architecture¶
TODO
graph LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];