wingather 0.2.2a0

Windows admin and security tool for discovering, recovering, and managing hidden or inaccessible windows

wingather

Windows admin and security tool for discovering, recovering, and managing hidden or inaccessible windows.

Finds hidden, minimized, off-screen, and obscured windows -- restores them and centers them on your chosen monitor. Useful for:

• Security investigation -- surface suspicious hidden dialogs or message boxes
• Window rescue -- recover windows lost off-screen after monitor disconnect
• Desktop cleanup -- quickly gather all windows to one spot (including from other desktops)

Installation

# From PyPI (coming soon)
pip install wingather

# From source
git clone https://github.com/DazzleTools/wingather.git
cd wingather
pip install -e .

Usage

# Find and surface suspicious windows (default: only acts on flagged windows)
wingather --dry-run

# Gather ALL windows to center of primary monitor
wingather --all

# List what's out there without taking action
wingather --list-only

# Reveal suspicious hidden windows (with educational banner)
wingather --show-hidden
wingather --show-hidden --all   # reveal ALL hidden windows (use with caution)
wingather --undo                # re-hide them (see docs/hidden-windows.md)

# Center on a specific monitor (0=primary, 1=secondary, etc.)
wingather --monitor 1

# Filter by window title or process name (fnmatch patterns)
wingather --filter "*chrome*"
wingather --exclude "*spotify*"

# JSON output for scripting
wingather --json

# Verbose logging
wingather -v

See docs/parameters.md for the full CLI reference with all options, filtering, trust configuration, and output modes.

Running as Administrator

For best results, run as Administrator. Without elevation, windows belonging to elevated processes (e.g., Task Manager, Process Explorer) cannot be moved.

What It Does

1. Sets DPI awareness for accurate multi-monitor coordinate handling
2. Enumerates all top-level windows via Win32 EnumWindows
3. Identifies window state: normal, minimized, hidden, off-screen, cloaked (virtual desktop)
4. Scores windows for suspicious indicators (off-screen, shrunk, dialog, cloaked)
5. By default, only acts on suspicious windows (use --all for everything)
6. Restores, shows, and centers affected windows on the target monitor
7. Reports what was found and what action was taken

Window States

State	Description	Default Action
normal	Visible, on-screen	Skip (use --all to center)
minimized	In taskbar	Restore + Center (if suspicious)
maximized	Full-screen normal	Skip (use --all to center)
hidden	WS_VISIBLE not set	Skip (use --show-hidden)
off-screen	Beyond monitor bounds	Center (flagged suspicious)
cloaked	On another virtual desktop	Skip (OS limitation)

Suspicious Window Detection

wingather flags windows that exhibit suspicious behavior using a weighted concern scoring system:

Level	Label	Example Triggers	Action
[!1]	ALERT	Off-screen + dialog, trust verification failed	Set TOPMOST
[!2]	ALERT	Off-screen window	Set TOPMOST
[!3]	CONCERN	Heavily shrunk window	Set TOPMOST
[!4]	NOTE	Dialog, partially off-screen	Flagged only
[!5]	NOTE	Cloaked on another desktop	Flagged only

See docs/parameters.md for indicator weights and scoring details.

Trust Verification

Built-in trusted processes (explorer.exe, etc.) are verified by checking their file path and Microsoft Authenticode signature before suppressing flags. A process masquerading as a trusted name but failing verification triggers an immediate level 1 ALERT.

# Bypass default trust list -- flag everything
wingather --no-default-trust --dry-run

# Trust additional processes
wingather -tp myapp.exe -tp "custom*"

Cross-Platform

Designed with a platform abstraction layer. Currently implemented for Windows only. macOS and Linux stubs are in place for future development. See docs/platform-support.md for details, requirements, and how to help.

Platform	Status
Windows	Implemented
macOS	Stub (PyObjC/Quartz planned)
Linux/X11	Stub (python-xlib/wmctrl planned)
Linux/Wayland	Not feasible (compositor security model)

Requirements

• Python 3.8+
• Windows: pywin32, psutil

Related Tools

• process-delta -- Process and service snapshot comparison tool
• NirCmd -- win center alltop does partial centering (no hidden/minimized restore)
• GUIPropView -- GUI window inspector with manual center action

Contributing

Contributions welcome! See CONTRIBUTING.md.

Like the project?

License

wingather, Copyright (C) 2026 Dustin Darcy

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.