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.

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

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.

Build From Source

Dependencies

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):

  • 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:

  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.

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