Skip to main content

Linux desktops (GNOME & KDE)

On modern Linux Wayland sessions, normal applications cannot freely ask “which window is focused?” the way they could on X11. GNOME and KDE therefore need a small helper that runs inside the compositor and exports focus over D-Bus.

The Desktop Agent installs those helpers automatically when it detects the matching session.

Detection​

The agent looks at XDG_CURRENT_DESKTOP / XDG_SESSION_DESKTOP:

  • contains GNOME → GNOME path
  • contains KDE or PLASMA → KDE Plasma path

Hyprland and Sway are handled separately via their own CLI tools and do not need these helpers.

GNOME​

Helper​

GNOME Shell extension UUID:

analog-waketime-focused@analogwaketime

It exports a D-Bus method that returns JSON for the focused window:

  • title
  • wm_class / wm_class_instance
  • pid

What the agent does on start​

  1. Checks whether the D-Bus API already answers
  2. If not, copies the extension into
    ~/.local/share/gnome-shell/extensions/analog-waketime-focused@analogwaketime/
  3. Enables it via gsettings / Shell Extensions D-Bus
  4. If still unavailable, may restart GNOME Shell once (Wayland-safe path with a local marker file so it does not loop)

Fallback​

On X11 GNOME sessions, xprop may work even without the extension. On Wayland, the extension is effectively required.

Manual checks​

# Extension directory present?
ls ~/.local/share/gnome-shell/extensions/analog-waketime-focused@analogwaketime

# Agent status hint
./Analog-WakaTime-Agent status

If status still says the GNOME extension is not active:

  1. ./Analog-WakaTime-Agent stop && ./Analog-WakaTime-Agent start
  2. Open Extensions, confirm Analog WakaTime Focused Window is enabled
  3. Log out/in of the GNOME session if the Shell did not pick it up

KDE Plasma​

Helper​

KWin script id:

analogwaketimefocused

Installed under:

~/.local/share/kwin/scripts/analogwaketimefocused/

The script listens for window activation and calls the agent’s session D-Bus name:

org.analogwaketime.Focused → method ReportJSON

Payload example:

{
  "title": "Document — Kate",
  "wm_class": "kate",
  "wm_class_instance": "kate",
  "pid": 22110
}

The worker also mirrors the last payload to $XDG_RUNTIME_DIR/analog-waketime-focused.json.

What the agent does on start​

  1. Claims the D-Bus service inside the worker
  2. Copies the KWin script package into the user scripts directory
  3. Sets analogwaketimefocusedEnabled=true in kwinrc (kwriteconfig6 / kwriteconfig5)
  4. Loads / starts the script through org.kde.KWin Scripting, then reconfigures KWin

Fallback​

On X11 Plasma, xprop / xdotool may work without the script. On Wayland Plasma, the KWin script is the supported path.

Manual checks​

ls ~/.local/share/kwin/scripts/analogwaketimefocused/contents/code/main.js
./Analog-WakaTime-Agent status

If KDE still shows as not ready:

  1. Restart the agent (stop → start)
  2. Focus any normal window once (so the script emits ReportJSON)
  3. Open System Settings → Window Management → KWin Scripts and enable Analog WakaTime Focused
  4. Optionally run qdbus org.kde.KWin /Scripting org.kde.kwin.Scripting.start

Hyprland & Sway​

No helper install step.

  • Hyprland: hyprctl must be available to the same user session
  • Sway: swaymsg must be available

If those tools work in your terminal, the agent can use them.

X11 utilities​

When DISPLAY is set, the agent may use:

  • xprop — _NET_ACTIVE_WINDOW, WM_CLASS, _NET_WM_PID
  • xdotool — getactivewindow / name / pid

Install them from your distro if you rely on generic X11 tracking (for example Arch: xorg-xprop, xdotool).

Unsupported desktops​

Environments such as XFCE, Cinnamon, MATE, and most other DEs are not wired with a dedicated Wayland helper. See Supported platforms.