Quick Terminal

The quick terminal is a single terminal window that slides in from a screen edge when you press a global keybinding, and slides back out when you press it again or shift focus. It's the same idea as the classic Quake-engine console: a fast, always-available terminal that doesn't interrupt whatever you were doing.

It's distinct from a regular Wintty window:

• There is only one quick terminal across the entire app.
• It is hidden by default and only appears on demand.
• It can be summoned from any focused application via a global keybind.
• Its state (running shell, scrollback) is preserved between appearances.

Note

The quick terminal ships on Windows and on Linux Wayland. On Windows it is a hidden singleton window created at startup and summoned by a global hotkey that Wintty registers with the OS.

On Windows the quick terminal is available with no configuration: press Ctrl+backquote (Ctrl plus the backtick/tilde key) to toggle it. That chord is registered with the OS as a global hotkey, so it works even when another application is in the foreground.

To use a different chord, set the Wintty-only quick-terminal-key option:

quick-terminal-key = alt+space

Values use Ghostty's trigger vocabulary: the modifiers ctrl, alt, shift, and super (cmd and win are accepted as aliases for super), joined with + to a single key such as backquote, space, f12, or a literal character. A chord with no modifier is rejected unless the key is a function key (F1 to F24), because binding a bare printable key system-wide is almost never what you want. If the value is missing or can't be parsed, Wintty falls back to Ctrl+backquote, so you're never left without a hotkey. Reloading the config re-registers the chord without a restart.

You can also toggle the quick terminal from a focused Wintty window by binding toggle_quick_terminal:

keybind = ctrl+shift+backquote=toggle_quick_terminal

Note

The wintty toggle-quick-terminal command does not work on Windows. The CLI accepts it, but it is delivered over the cross-process IPC path, and the Windows build's runtime declines every IPC action, so the command prints "not supported on this platform" and exits with a non-zero status. Use quick-terminal-key for a system-wide chord and toggle_quick_terminal for an in-app one.

Note

The global: keybind prefix does not work on Windows. Wintty strips flag prefixes when it parses a trigger, so the binding becomes an ordinary in-app keybind that only fires while a Wintty window is focused. quick-terminal-key is the only way to get a system-wide chord on Windows.

quick-terminal-position controls which edge of the screen the quick terminal slides in from:

Value	Behavior
top (default)	Slides down from the top
bottom	Slides up from the bottom
left	Slides in from the left
right	Slides in from the right
center	Appears centered

quick-terminal-size sets the size as a percentage or pixel value, separately for each axis:

quick-terminal-position = top
# 30% of the screen height, full screen width
quick-terminal-size = 30%
# Or, mix percentages and pixels:
quick-terminal-size = 50%,600px

When only one value is given, it controls the primary axis, which is the axis the terminal slides along (height for top/bottom, width for left/right). For a center position the primary axis follows the monitor instead: height on a landscape monitor, width on a portrait one. The other axis is maximized, for non-center positions, unless a second value is supplied after a comma.

quick-terminal-screen controls which display the quick terminal appears on:

Value	Behavior
main (default)	The OS-designated main screen
mouse	The screen the mouse is currently hovering over

mouse is useful in multi-monitor setups where you want the quick terminal to follow your attention.

By default, the quick terminal hides itself when it loses focus. Disable this with quick-terminal-autohide:

quick-terminal-autohide = false

On Windows this defaults to true, which is the classic quake behavior. On Linux it defaults to false, because Wayland global shortcuts are harder to set up and you usually want the terminal to stay visible while you switch to a docs window or similar.

quick-terminal-animation-duration sets the slide-in/out animation in seconds. Set it to 0 to disable animation:

quick-terminal-animation-duration = 0.15

Note

Animations are implemented natively on Windows. On Windows the value is clamped to at most 2 seconds, so a typo can't leave the window stuck mid-slide. On Linux/KDE Wayland, slide animations also require the "Sliding Popups" KWin effect plugin to be enabled in System Settings.

• The global hotkey is registered by Wintty with the OS and is configured by quick-terminal-key, not by a global: keybind.
• The window is created hidden at startup. It stays out of the taskbar and out of Alt+Tab, and closing it hides it rather than destroying the shell.
• quick-terminal-position, quick-terminal-size, quick-terminal-screen, quick-terminal-autohide, and quick-terminal-animation-duration are all read and applied.
• The Wayland-only options have no effect on Windows.

• The quick terminal only works on Wayland, not X11.
• The Wayland compositor must support the wlr-layer-shell-v1 protocol. KDE Plasma, Hyprland, sway, river, and most non-GNOME compositors do. GNOME does not, so quick terminal is not available there.
• The layer the quick terminal sits on is configured by gtk-quick-terminal-layer (overlay, top, bottom, background).
• Keyboard input behavior is controlled by quick-terminal-keyboard-interactivity.
• Quick terminal tabs are supported on Linux.

• Only one quick terminal can exist at a time.
• Unlike normal Wintty windows, the quick terminal is not restored automatically on app restart, even on platforms with session restoration. You will need to summon it again with your global key.

Option	Purpose
quick-terminal-key	Wintty-only: the system-wide chord that toggles the quick terminal (default ctrl+backquote)
quick-terminal-position	Which edge the quick terminal slides in from
quick-terminal-size	Size in percent or pixels
quick-terminal-screen	Which display to use
quick-terminal-animation-duration	Slide animation in seconds (0 = off)
quick-terminal-autohide	Hide when focus is lost
quick-terminal-keyboard-interactivity	Wayland keyboard focus mode
gtk-quick-terminal-layer	Wayland layer for the quick terminal
gtk-quick-terminal-namespace	Wayland namespace for compositor rules

Action	Purpose
toggle_quick_terminal	Show or hide the quick terminal