What does the Linux agent need from my desktop session?

On Linux, what the app can see depends on two things: whether your desktop session is X11 or Wayland, and which desktop environment you are using. Your working time is recorded either way. Application names, websites and screenshots are the parts that differ.

First, find out which session you are on

Open a terminal and run this:

echo $XDG_SESSION_TYPE

It prints x11 or wayland. Most current distributions log you in to a Wayland session by default, and many login screens let you pick an X11 session instead before you type your password. If the command prints nothing at all, read the section on undetected sessions further down.

On an X11 session

Everything works with no extra setup. The app reads the focused window straight from the window manager, and screenshots are taken directly, with no permission prompt, because X11 has no screen permission to ask for: any application may read the screen.

This is true on every desktop environment. GNOME, KDE Plasma, XFCE, Cinnamon and MATE all behave the same way on an X11 session.

Two system libraries carry it: libx11-6 for reading the window and the screen, and libxss1 for the idle timer that decides when you have stepped away from the keyboard. Both are listed as dependencies of the .deb and the .rpm, so installing with apt or dnf brings them in for you.

On a Wayland session

Wayland deliberately stops applications from looking at each other, so two things change.

• Application names. GNOME does not let an application ask which window is focused, and there is no permission it can request. The Worktivity Window Tracker GNOME Shell extension is the way around that, and it is covered in the next section.
• Screenshots. They go through the desktop portal instead of being taken directly. You are asked once, when you clock in, and your desktop remembers the answer.

Websites are not affected. The domain name is read from your browser's own history file, and that works identically on X11 and Wayland, with or without the extension.

The GNOME Shell extension

On a GNOME Wayland session the extension is the only way to record which application you are using. It runs inside GNOME Shell itself and reports three things about the focused window: the application id, the window class and the process id. It never reads window titles.

You do not have to find it or download it. It travels inside the .deb and the .rpm and is installed into a system directory, so one copy serves every account on the machine.

You do not have to switch it on either. The app enables it for you, once, and only when two things are true: you have agreed to tracking on the consent screen, and your organization actually records applications. If your organization records websites only, nothing on your desktop is touched.

One step is left to you, and no button can do it for you. GNOME loads extensions when the Shell starts, and on Wayland the Shell cannot be restarted while you are logged in. Sign out and back in once, and application tracking starts working.

The Track tab tells you which state you are in:

• "The Worktivity GNOME extension is installed but switched off." The app switches it on as soon as tracking starts. Nothing for you to do.
• "The Worktivity GNOME extension is switched on but GNOME has not loaded it yet." Sign out and back in to finish.
• "Install the Worktivity GNOME extension to record which applications are used." The extension files are not on this machine, which is what you see when the app did not come from the .deb or the .rpm.

Every one of those messages ends the same way, and that is the important half: time, websites and activity level are still being recorded. You can switch the extension off whenever you like, in GNOME's own Extensions app.

Screenshots on Linux

Screenshots are taken only if your organization has them switched on. Where they come from depends on the session type.

• X11: taken directly, with no dialog, because there is no permission to grant.
• Wayland: taken through the desktop portal. The request is made at clock-in, while the app's own window is in front, because the desktop will only show that dialog to the application you are currently using. Once you allow it, later screenshots need no dialog.

If you decline, no screenshots are taken and you are not asked again for as long as the app keeps running. Your working time and activity level are still recorded, and the Settings tab says so on screen. To change your mind, allow screen sharing for Worktivity in your desktop's own privacy settings, or restart the app to be asked again.

If the Settings tab says that this Wayland session has no desktop portal, then the xdg-desktop-portal package is missing and screenshots cannot be taken at all. The .deb recommends that package, which means apt installs it for you by default and dpkg does not. That is one of the reasons to install with apt rather than with dpkg.

Whichever route the image takes, it is scaled down to 820 pixels wide and compressed before it is sent, and it is blurred first if your organization asked for blurred screenshots.

KDE Plasma, XFCE and other desktops

• KDE Plasma on X11, XFCE, Cinnamon, MATE: application tracking works exactly as on any other X11 session.
• KDE Plasma on Wayland: application tracking is off in this version. The Track tab says "Reading the active window on KDE Plasma is not supported by this version yet. Time, websites and activity are still tracked."
• Sway, Hyprland and other Wayland compositors: application tracking is off, with the message "This desktop session cannot report which application is in front."

There is a reason the app switches the feature off rather than guessing. On a Wayland session the older X11 calls still answer; they simply cannot see Wayland applications. Guessing would produce a full day of records that quietly leaves out most of what you actually did, which is worse than an honest gap. For the same reason, when application tracking is off the app sends the name "Worktivity" rather than inventing an application name.

When the session type cannot be detected

If neither the session type nor the desktop environment can be read, application tracking and screenshots are both switched off, and the Settings tab says the session type could not be detected. Time, activity level and websites keep being recorded. The app does not fall back to X11 here, for the reason above.

What is never recorded

• Window titles. The extension never asks GNOME for one, and the server has no field to store one in.
• Full web addresses. Only the domain name is kept. The path, the query string and anything after a # are discarded the moment the address is read, and the full address is never written anywhere, not even to the local log file.
• What you type. Keystrokes are not read and nothing resembling key logging happens. The app asks the desktop one question once a second: has there been any keyboard or mouse input. It never learns which key, or where the pointer went.
• Anything outside a running shift. Nothing is collected while the clock is stopped.
• The screenshots themselves in the log. The log records that a screenshot could not be taken and why, never the image.

The complete list, for every platform, is in the privacy section of this help centre.

When something is not being recorded

Start with the app's own screens. Whenever application tracking is off, the Track tab carries a card that says so in your own language, and the Settings tab has one sentence about screen capture and one about the keyring. Between them they name the exact state you are in.

If support asks for the details, the log files are here:

ls ~/.local/state/worktivity/

There is one file per day, named worktivity- followed by the date, and the last seven days are kept. It records what the app tried and what answered. It never contains passwords, session tokens or screenshots.

Do not delete the ~/.local/share/worktivity directory. That is where recorded minutes wait while your machine is offline, and they are real working time that has not reached the server yet.

Problems seen most often

Launching the app appears to do nothing. It is already running: only one copy runs per user session, and closing the window leaves the clock running instead of quitting.

The install fails saying the package cannot be found. apt reads an argument with no slash in it as a package name and looks for it in your configured repositories, where it does not exist. Put ./ in front of the file name:

sudo apt install ./worktivity-<version>-amd64.deb

Type the exact name of the file you downloaded; in a shell you can press Tab to complete it. On Fedora and RHEL the same rule applies to the .rpm:

sudo dnf install ./worktivity-<version>-x86_64.rpm

Dependencies were not resolved. Refresh the package index first and install again:

sudo apt update

If you used dpkg -i and the install stopped half way, the package is left partly configured and dependencies are still missing. Finish it with:

sudo apt --fix-broken install

The Settings tab says no keyring was found. libsecret-tools is missing, so your session token is kept in a file with 0600 permissions rather than in the desktop keyring, which is weaker than intended. That package is recommended by the .deb, so apt installs it and dpkg does not.

On openSUSE the package installs with zypper, but it never updates itself. The update repository is registered in /etc/yum.repos.d, and zypper does not read that directory. On openSUSE, install each new version by hand.

What the Linux app does not have

Background mode, where the app runs with no window and no icon at all, is a Windows feature and is not part of the Linux app.

Updates work differently too. The .deb and the .rpm register an update repository with your system, so new versions arrive through apt or dnf like any other package rather than through a button inside the app.

And the package starts nothing by itself. Installing it does not enable a service and does not add anything to your session's startup. The app runs when you launch it, and it adds its own startup entry only when you switch on "Start with the desktop session" in Settings.