Couchwarden Guide

Everything lives in the tray icon. This page explains what each guard does, and the hotkeys and gestures that drive them.

First run

Couchwarden starts as a single icon in the system tray — no window, no console. Right-click the icon to open the menu: every feature can be toggled there, and every change is saved immediately and remembered across restarts. The menu always shows the current hotkey next to each item, so if you ever forget a binding, the tray is the answer.

The icon itself tells you the current state at a glance — a green check when all is normal, lock marks while a lockdown is active, and a sleeping "Zz" while the keyboard guard is armed after idle.

Hotkeys at a glance

Hotkey	What it does
`Ctrl`+`Alt`+`G`	Cycle the keyboard guard mode: sliding → fixed → disabled.
`Alt`+`F1`	Mouse lockdown on/off — freezes movement, clicks, and wheel.
`Alt`+`F2`	Keyboard lockdown on/off — swallows every keystroke.
`Alt`+`F3`	Cursor auto-hide on/off.
`Ctrl`+`Alt`+`Z`	Restore the last moved or resized window to where it started.

Every toggle confirms with a short beep — higher pitches mean on, lower pitches mean off. All hotkeys can be rebound (see Settings).

The keyboard guard

The problem Couchwarden was built for: a wireless keyboard goes to sleep, its backlight turns off, and the first key you press wakes it up and lands in whatever window has focus — or a cat, a toddler, or your sleeve types for you while you're not looking. The keyboard guard watches how long the keyboard has been idle; once it's been quiet past the idle delay, the next keystroke is treated as suspect and suppressed.

Set the idle delay from the tray (Idle delay submenu, in minutes). A good value is the same as your keyboard's own backlight or sleep timeout — that way the suppressed key is exactly the invisible wake-up key.

The three modes

Sliding — every suppressed key extends the grace window. Best against sustained mashing (a cat settling onto the keys): nothing gets through until the keyboard has been genuinely quiet.
Fixed — only the trigger key (and its own modifiers) is eaten; a short fixed grace follows, then everything passes. Best when you type fast and only want the single invisible wake-up key gone.
Disabled — the guard stands down entirely. Use for gaming, where the first keypress matters.

Cycle modes with Ctrl+Alt+G or pick one — and its grace duration — from the tray. Each mode has its own distinct beep so you know where you landed without looking.

Lockdowns

Mouse lockdown (Alt+F1) freezes the pointer completely — movement, clicks, and wheel. Wipe the screen, hand the room to the kids, foil the cat. Keyboard lockdown (Alt+F2) does the same for keys.

While a lockdown is active, a small LOCKED pill sits in the corner of the screen — red for keyboard, amber for mouse — so a locked input is never a mystery, even if the tray icon is hidden. The pill is click-through and never steals focus. The release hotkey always works; that's the whole point of it being a hotkey.

Cursor auto-hide

The pointer disappears after a couple of seconds of mouse stillness and immediately when you start typing; it returns the instant the mouse moves or a button is pressed. Pick the delay in the tray (Cursor idle delay), toggle with Alt+F3.

Window control

Hold Alt and act on any point of a window — no hunting for title bars or edges. You can let go of Alt once the drag has started.

Gesture	What it does
`Alt` + left-drag	Move the window from anywhere inside it.
`Alt` + right-drag	Resize — the quadrant you start in picks which corner or edges move.
`Alt` + middle-drag	Hand tool: scroll the window under the cursor, browser-style, without focusing it.
`Alt` + wheel	Fade the window under the cursor toward transparent or back — clamped so it can never vanish entirely.
`Ctrl`+`Alt` + middle-click	Reset that window to fully opaque.
Double-tap `Alt`, left-click	Minimize the window under the cursor.
Double-tap `Alt`, right-click	Restore — brings back the last minimized window, or un-maximizes.
Double-tap `Alt`, middle-click	Close the window under the cursor — politely, so save prompts still appear.
`Esc` during a drag	Cancel: the window snaps back to where the gesture started.
`Ctrl`+`Alt`+`Z`	Restore the last-manipulated window to its position and size from before you started rearranging it.

Maximized windows are left alone, and all gestures stand down while mouse lockdown is on. The whole suite toggles from the tray (Window drag/resize), and the modifier can be changed from Alt to Ctrl, Shift, or Win in settings.

Hand-tool tip for terminal apps: full-screen terminal programs that capture the mouse ignore scroll input that arrives with a modifier key held. The gesture only needs Alt at the moment you press the middle button — so grab, let go of Alt, and keep dragging. Everything else scrolls fine with Alt held the whole time.

Settings

Day-to-day options — modes, delays, feature toggles — live in the tray menu and persist on their own. Deeper preferences, including every hotkey binding, live in config.json in the app's folder. Hotkeys use the format Mod+Mod+Key (modifiers: Ctrl, Alt, Shift, Win), and the file documents every option inline. Restart Couchwarden after editing hotkeys; everything else applies live.

Stuck or surprised by something? The support page covers the common cases — or email paul@deskwarden.io.