Skip to main content

Overview

The Analog WakaTime Desktop Agent is a background program that tracks which desktop application is focused and how long it stays in focus. Unlike the VS Code extension (which tracks coding inside the editor), the agent covers the whole desktop session: browsers, terminals, IDEs, design tools, chat apps, and anything else that owns an active window.

It runs as a small local worker, stores activity offline when the network is down, and syncs batches to the Analog WakaTime gateway when you are authenticated.

How it differs from the VS Code extension
Desktop AgentVS Code Extension
ScopeEntire desktop (active window)Files inside VS Code
MetricsProgram name, path, focused timeKeystrokes, lines, language, project
RuntimeStandalone binary / daemonExtension host inside the editor
LoginCLI device flow or email/passwordBrowser device flow / API token

You can use both at the same time. They report different kinds of activity to the same account.

What the agent does​

  1. Detects the currently focused window on a supported OS / desktop stack.
  2. Samples focus every few seconds and buckets time by program, date, and hour.
  3. Writes unfinished activity into a local SQLite queue (data/agent.db).
  4. Uploads pending rows to the gateway in batches.
  5. Keeps running in the background until you stop it.

Architecture at a glance​

┌────────────────────┐
│  CLI (start/stop/  │
│  login/status)     │
└─────────┬──────────┘
          │ spawns / signals
          ▼
┌────────────────────┐     poll active window
│  Background worker │──────────────────────────► OS / compositor backend
│  (--worker)        │
└─────────┬──────────┘
          │ flush buckets
          ▼
┌────────────────────┐
│  Local SQLite      │  data/agent.db
│  offline queue     │
└─────────┬──────────┘
          │ sync batches + auth token
          ▼
┌────────────────────┐
│  Analog gateway    │
│  + dashboard       │
└────────────────────┘

On Linux Wayland sessions where the compositor does not expose focus APIs to normal apps (GNOME, KDE Plasma), the agent installs a small helper (GNOME Shell extension or KWin script) so it can still read the focused window. Details are in Linux desktops.

When to use it​

  • You want desktop-wide productivity stats, not only editor time.
  • You work across multiple apps (browser + IDE + terminal + Figma, etc.).
  • You need offline collection with automatic retry when the API is back.
  • You run Linux (GNOME / KDE / Hyprland / Sway / X11), Windows, or macOS.

Next steps​