Some of these questions are technically not frequently asked.
How do I interpret the raw data?¶
How can I use ActivityWatch with my own code?¶
See the Examples for different ways to use ActivityWatch programmatically.
How does ActivityWatch know when I am AFK?¶
On Windows and macOS, we use functionality offered by those platforms to give us the time since last input.
On Linux, we monitor all mouse and keyboard activity to calculate the time since last input. We do not store what that activity was, just that it happened.
Using this data (seconds since last input) we check if more than 3 minutes have passed without any input. If that is the case, we assume that you’ve been AFK since the last input was received. You’ll be assumed to be active again on next input.
Why is the active window logged as “unknown” when using Wayland?¶
The Wayland protocol does not have a notion of an active window, and it is unlikely to ever have. Wayland is also developed in security in mind, so access should be handed out on an app-by-app basis. This is a good idea, any application shouldn’t just give that privacy-sensitive information away freely.
Unfortunately, in Wayland compositors like Gnome’s Mutter there is no way at all to get the current window, this leaves the window watcher completely disabled in Wayland.
Solution: Switch to using X11 (the best option), and if you can’t: bother the developer of your Wayland compositor.
You can see the general status of the ability of getting the active window in Wayland on StackOverflow or follow the issue for ActivityWatch tracking the problem.
What happens if it is down or crashes?¶
ActivityWatch consists of several processes running independently, so one thing crashing will have limited impact on the rest of the system.
If the server crashes or is unavailable, watchers which use the heartbeat queue will queue heartbeats until the server becomes available.
If a watcher crashes, its bucket will simply remain untouched until it is restarted.
Some events have 0 duration. What does this mean?¶
Watchers most commonly use a polling method called Heartbeats in order to store information on the server.
Heartbeats are received regularly with some data, and when two consecutive heartbeats have identical data they get merged and the duration of the new one becomes the time difference between the previous two.
Sometimes, a single heartbeat doesn’t get a following event with identical data. It is then impossible to know the exact duration of that event, so the assumption about when it really started/ended will be postponed until the analysis stage (usually handled with
The assumption could be made to consider all zero-duration events actually have a duration equal to the time of the next event, but all such assumptions are left to the analysis stage.