Skip to content

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.

scoop install https://raw.githubusercontent.com/flyingpie/windows-terminal-quake/master/scoop/wtq-latest.json
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-latest

WinGet

The Windows package manager.

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.

Linux

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.

Flatpak

TODO

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:

  1. A path defined by an environment variable named WTQ_CONFIG_FILE (regardless of filename or extension)
  2. 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
  3. In %USERPROFILE%\.config
    • C:\users\username\.config\wtq.json
  4. In user home
    • C:\users\username\wtq.json
  5. In user home, as a dot file
    • C:\users\username\.wtq.json
  6. 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:

  1. A path defined by an environment variable named WTQ_CONFIG_FILE (regardless of filename or extension)
  2. Next to the WTQ executable
    • When using the install script: /home/username/.local/share/wtq
  3. In $XDG_CONFIG_HOME, if defined (following to the XDG spec)
    • /home/username/.config/wtq.json
  4. In ~/.config (the default for XDG_CONFIG_HOME, if is it not defined)
    • /home/username/.config/wtq.json
  5. In user home
    • /home/username/wtq.json
  6. 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. Optional.

Defaults to None

{
    "Hotkeys": [
        { "Modifiers": "Control", "Key": "Q" }
    ]
}
Show UI on start

Whether to show the GUI when WTQ is started.

Defaults to False

{
    "ShowUiOnStart": "False",
    // ...
}

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",
    // ...
}

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.

{
    "Apps": [
        {
            "FileName": "wt"
            // ...
        }
    ]
}
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.

Defaults to None

{
    // Using with Windows Terminal requires both "Filename" and "ProcessName".
    "Apps": {
        "Filename": "wt",
        "ProcessName": "WindowsTerminal"
    }
}
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

Defaults to None

{
    "Apps": [
        {
            "ArgumentList": [
                "--allow-screencapture",
                "--debug-info",
            ],
            // ...
        }
    ]
}
Window title

TODO

Defaults to None

{
    "Apps": [
        {
            "WindowTitle": "Mozilla Firefox - WhatsApp"
            // ...
        }
    ]
}

Behavior

Window title override

Attempt to set the window title to a specific value.

Defaults to None

{
    "Apps": [
        {
            "WindowTitleOverride": "None"
            // ...
        }
    ]
}

Shared options

Options that are both in global WtqOptions and per-app WtqAppOptions.

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": "None",
    // ...
}

For one app only:

{
    "Apps": [
        {
            "OffScreenLocations": "None"
            // ...
        }
    ]
}

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"
            // ...
        }
    ]
}

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!];