KWin PixelShift

KWin script for Plasma 6 that re-randomizes the focused window to an almost maximized size with small, configurable gaps on each side.

The goal is to keep windows close to full-screen while shifting their exact position slightly on every trigger to reduce the chance of static OLED wear patterns.

Note On Plasma 6.6.x, changing PixelShift settings in the KWin Scripts UI may not take effect immediately. The current workaround is: change the settings, disable the PixelShift script, then enable it again.

Features

• Meta+Shift+Up resizes the focused window
• rerolls fresh gaps on every trigger
• keeps the result roughly centered instead of drifting wildly
• respects KWin's maximize area, so panels and reserved screen space are preserved
• configurable minGap, maxGap, and balanceJitter in KWin Scripts settings
• optional auto-apply for exact app ids such as firefox and org.kde.konsole
• optional periodic re-apply for matching apps at a configurable interval in minutes

Repository Layout

.
├── package/
│   ├── contents/
│   └── metadata.json
├── scripts/
│   ├── build.sh
│   └── install.sh
└── .github/workflows/build.yml

Requirements

• KDE Plasma 6
• KWin scripting support
• kpackagetool6
• gdbus

scripts/install.sh also uses kwriteconfig6, kreadconfig6, and qdbus6 when available.

Install From Source

./scripts/install.sh

That script:

• installs or upgrades the KWin script package
• enables it in kwinrc
• reloads KWin configuration
• assigns Meta+Shift+Up through KGlobalAccel

Manual Install

kpackagetool6 --type=KWin/Script --install ./package
kwriteconfig6 --file kwinrc --group Plugins --key kwin_pixelshiftEnabled true
qdbus6 org.kde.KWin /KWin reconfigure

If you also want to assign the shortcut manually through D-Bus:

gdbus call \
  --session \
  --dest org.kde.kglobalaccel \
  --object-path /kglobalaccel \
  --method org.kde.KGlobalAccel.setShortcut \
  "['kwin', 'PixelShift', 'KWin', 'Resize the focused window with fresh near-centered random gaps']" \
  "[318767123]" \
  6

Configuration

Open System Settings -> Window Management -> KWin Scripts -> PixelShift.

Available settings:

• minGap: minimum inset per side in pixels
• maxGap: maximum inset per side in pixels
• balanceJitter: how far opposite sides may differ while still staying roughly centered
• autoApplyEnabled: automatically apply PixelShift when a matching app first opens
• autoApplyApps: comma-separated exact app ids matched against desktopFileName, resourceClass, and resourceName
• periodicApplyEnabled: re-apply PixelShift to currently open matching apps on a timer-like interval
• periodicApplyMinutes: minutes between periodic re-application for matching apps, default 30

Recommended defaults:

• minGap = 6
• maxGap = 24
• balanceJitter = 4

Build Artifacts

Create distributable archives with:

./scripts/build.sh

This writes to dist/:

• kwin-pixelshift.zip
• kwin-pixelshift.kwinscript
• kwin-pixelshift.zip.sha256

The GitHub Actions workflow builds and uploads the same artifacts on pushes, pull requests, manual runs, and version tags.

Changelog

See CHANGELOG.md.

Notes

• The script is intentionally silent during normal use.
• On runtimes without JavaScript timer APIs in KWin, periodic re-apply happens on the next relevant KWin activity after the interval has elapsed.
• If KWin API behavior changes across Plasma releases, the shortcut can still be debugged by watching journalctl -b for kwin_pixelshift messages.

License

GPL-3.0-or-later