https://github.com/rdicosmo/kwin-focus
List and focus application windows on KDE Plasma 6 (X11 & Wayland), fully Activities-aware — a CLI + Plasma applet replacement for wmctrl/xdotool.
https://github.com/rdicosmo/kwin-focus
activities kde kwin plasma wayland window-management x11
Last synced: 23 days ago
JSON representation
List and focus application windows on KDE Plasma 6 (X11 & Wayland), fully Activities-aware — a CLI + Plasma applet replacement for wmctrl/xdotool.
- Host: GitHub
- URL: https://github.com/rdicosmo/kwin-focus
- Owner: rdicosmo
- License: other
- Created: 2026-05-31T16:21:54.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-31T16:38:26.000Z (about 2 months ago)
- Last Synced: 2026-05-31T18:21:42.046Z (about 2 months ago)
- Topics: activities, kde, kwin, plasma, wayland, window-management, x11
- Language: QML
- Size: 22.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# kwin-focus
List and focus application windows on **KDE Plasma 6** (X11 *and* Wayland),
fully **Activities-aware**. A replacement for `wmctrl` / `xdotool` workflows,
which are broken on Plasma 6 (no Wayland support, no Activities).
Two front-ends share one idea — *talk to KWin, enumerate every window across all
virtual desktops and Activities, and focus the one you want*:
| | |
|---|---|
| **`cli/kwin-focus`** | a self-contained bash tool: list (`-l`), JSON (`-j`), pattern-focus (`-p RE`, ideal for global keybindings), and an interactive picker (fzf or a numbered menu). |
| **`applet/`** ("Window Filter") | a Plasma 6 panel/dock applet: a search box over a live window list, **fully keyboard-driven** (the search field always keeps focus — type to filter, arrow to move the highlight, never lose your place). Filter by title / application / **Activity name**; **per-row actions** (close, minimise/maximise, keep-above, full-screen, move to desktop/activity) via right-click or the **Menu** key; focus a window with Enter (KWin switches desktop **and** Activity for free). Toggle the sort order (Most-recently-used by default / Alphabetical / By-activity), **pin** the list open to keep navigating, and show each window's Activity. Assign a **global shortcut** to summon it on whatever Activity you're on (see below). Press **F1** for the in-app keyboard cheat-sheet. |
### Applet keyboard map
The search field owns every key (single-focus, KRunner/rofi style), so type-to-filter
never breaks:
| Key | Action |
|---|---|
| `↑` / `↓` | Move the highlight |
| `Home` / `End` | First / last window |
| `PgUp` / `PgDn` | Move by a page |
| `Enter` | Focus the highlighted window (closes unless pinned) |
| `Esc` | Clear the filter, then (if empty) dismiss back to where you were |
| `Menu` / `Shift+F10` | Open the per-row action menu |
| `Ctrl+W` / `Del`¹ | Close the highlighted window (list stays open to keep triaging) |
| `Ctrl+M` / `Ctrl+Shift+M` | Minimise / maximise the highlighted window |
| `Ctrl+S` / `Ctrl+Shift+S` | Cycle the sort order forward / backward |
| `Ctrl+P` | Toggle pin |
| `F1` | Toggle the keyboard cheat-sheet |
¹ `Del` closes the window only when the filter is empty; while typing it edits text.
### Global shortcut
The applet ships with **no default global shortcut** — it won't claim a key behind
your back. To summon the list from anywhere, assign one yourself: right-click the
widget → **Configure Window Filter…** → **Keyboard Shortcut**, or via *System
Settings → Keyboard → Shortcuts*. **`Meta+Shift+W`** is a good pick — `Meta`
combos never clash with application shortcuts, and it avoids KWin's own `Meta+W`
(Overview). Plasma remembers it across sessions.
## How it works (the interesting part)
KWin exposes **no** direct "list windows" D-Bus method, and the two front-ends
solve the data problem very differently:
- **The CLI** is *outside* Plasma, so it injects a JavaScript snippet via
`org.kde.KWin /Scripting loadScript`, and reads the script's `print()` output
back from the **systemd user journal** (`journalctl --user`, where it lands as
`kwin_x11[…]: js: …`). A common dead end is filtering with
`journalctl --user -u plasma-kwin_x11.service` — kwin is *not* a user systemd
unit, so that matches nothing; drop the `-u` filter. Focusing sets
`workspace.activeWindow` (write-deferred — don't read it back in the same
tick) after `raiseWindow()`, switches the virtual desktop, and switches the
Activity via `org.kde.ActivityManager … SetCurrentActivity`.
- **The applet** runs *inside* plasmashell, so it needs none of that: it uses
`TaskManager.TasksModel` directly and `requestActivate()`, which switches
desktop **and** Activity for free.
## Install
```sh
make install # links ~/bin/kwin-focus onto PATH + installs the applet
make dev # run the applet standalone (plasmawindowed) to try it
make upgrade # redeploy the applet after edits
make uninstall # remove both
```
Then add the applet to a panel/dock: right-click the panel → **Add Widgets…** →
search **"Window Filter"**.
## Requirements
- **CLI:** `qdbus6` (or `qdbus`), `journalctl`, `awk`, `sed`. Optional: `fzf`.
- **Applet:** KDE Plasma 6 (`kpackagetool6` to install). Uses the stock
`org.kde.taskmanager` and `org.kde.kitemmodels` QML modules.
## Layout
```
cli/kwin-focus the command-line tool
applet/metadata.json Plasma applet manifest (id: org.dicosmo.windowfilter)
applet/contents/ui/main.qml root: models, dispatcher, keyboard, menu host
applet/contents/ui/WindowDelegate.qml one row of the list
applet/contents/ui/WindowContextMenu.qml the per-row action menu
applet/contents/ui/code/actions.js the window-action catalog
```
See [CHANGELOG.md](CHANGELOG.md) for release notes.
## License
MIT. See [LICENSE](LICENSE).