Perch

First stable release of Perch — a persistent, compositor-aware window geometry manager for Linux desktops.

Sits in the system tray, remembers where each window belongs, and restores position / size / monitor / virtual desktop when a window reopens. Ships a rules engine, named layouts, per-monitor profiles, snap presets, and global hotkeys.

Highlights

• Tray + PySide6 config dialog (General / Windows / Rules / Layouts / Profiles / Hotkeys / Exclusions / Import-Export) with dark-theme support, keyboard navigation, and accessible labels.
• Windows pane — live table of tracked windows with per-row Save-as-last-seen / Forget-last-seen / Apply-preset buttons.
• Tray "Snap focused window" submenu — maximise, half-halves, quarters, Centre (keep size), Centre (60 %).
• Rules engine — match by app_id / wm_class / title (regex) / PID / type, apply geometry / snap / monitor / desktop / maximized. 100 % line-covered evaluator.
• Full backends for X11 (any EWMH WM) and KWin / Plasma Wayland (bundled JS script + long-poll IPC). Community stubs for Mutter, Sway, Hyprland.
• Global hotkeys via the xdg-desktop-portal GlobalShortcuts interface, with KGlobalAccel and XGrabKey as platform fallbacks.
• Autostart via XDG .desktop files (non-Flatpak) or the Background portal (Flatpak).
• Packaging for Flathub, openSUSE OBS, Fedora COPR, AUR (perch stable + perch-git), and the KDE Store.

What's new since the design-complete snapshot

Everything. See CHANGELOG.md for the full per-milestone history, including the post-smoke-test fixes (M9.f.1…M9.f.15) that wired every dialog pane to real functionality, fixed the KWin script's Qt is not defined bug, and shipped the intent-dispatch audit that gates CI against future shipped-stub regressions.

Install

Packaging artefacts are authored in packaging/ — Flathub, OBS, COPR, AUR, KDE Store. Flathub submission, OBS project, and AUR push follow from this tag.

From source:

git clone https://github.com/milnet01/perch.git
cd perch && git checkout v1.0.0
pip install --user --break-system-packages -e ".[dev]"
perch

Requires Python 3.12+ and PySide6 ≥ 6.8.

License

GPL-3.0-or-later.

Perch

Persistent, compositor-aware window geometry manager with a system-tray UI for Linux desktops.

Status: v1.0.0 — see CHANGELOG.md and docs/11-roadmap.md for the per-milestone history.

What Perch does

• Runs in the system tray; launches automatically at login.
• Remembers position, size, monitor, and virtual desktop of every managed window.
• Restores windows to their remembered spot when they reopen.
• Provides a live-editable list of open windows (x, y, width, height).
• One-click snap presets: center, left half, right half, top-left, top-right, bottom-left, bottom-right, plus quarter snaps and "maximize on this monitor".
• Named layouts ("coding", "media", "writing") switchable from the tray.
• Rules engine: "always open Firefox on monitor 2, maximized".
• Per-monitor-layout profiles — separate positions for docked vs. laptop-only.
• Global hotkeys for snap presets (via xdg-desktop-portal GlobalShortcuts, with KGlobalAccel / XGrabKey fallbacks).
• Exclusion list for windows that shouldn't be managed (splash screens, transient dialogs).
• Export / import configs so layouts survive a reinstall.

Supported display servers

Perch uses a backend-plugin architecture so it can target any mainstream Linux display server / compositor.

Backend	Status	How it works
X11 (any EWMH window manager)	full	python-xlib + an in-tree EWMH helper
KWin / Plasma Wayland	full	KWin D-Bus + a bundled KWin JavaScript script
Mutter / GNOME Wayland	stub	GNOME Shell extension (contributor-welcome)
Sway / wlroots	stub	swaymsg
Hyprland	stub	hyprctl

Writing a new backend means implementing the WindowBackend interface described in docs/03-backend-interface.md — no core changes required.

Installation

Perch is distributed through:

• Flathub (Flatpak) — primary cross-distro channel
• openSUSE OBS — RPM
• AUR — Arch / Manjaro (perch stable, perch-git HEAD)
• Fedora COPR — RPM
• KDE Store (store.kde.org) — links at the Flatpak

Packaging recipes live under packaging/. See docs/10-packaging.md for the per-channel installation commands.

Building from source

Perch targets Python 3.12+ with PySide6 ≥ 6.8.

git clone https://github.com/milnet01/perch.git
cd perch
pip install --user --break-system-packages -e ".[dev]"
perch --version

See docs/contributing-dev-setup.md for the full dev workflow (system packages, test commands, pre-commit expectations).

License

GPL-3.0-or-later. See LICENSE.

Contributing

Design-first: please read CONTRIBUTING.md and the relevant file in docs/ before opening a PR. Any behavior change should be reflected in the docs either before or in the same PR as the code.