Skip to main content

Installation

This page covers how to get the Desktop Agent binary onto a machine and run it for the first time.

Requirements​

  • A supported OS (see Supported platforms)
  • Outbound HTTPS access to the Analog WakaTime gateway
  • For Linux Wayland GNOME / KDE: ability to install a user-level Shell extension or KWin script (the agent does this automatically when possible)

Build tools (if you compile from source)​

  • Go 1.22+ (the agent module targets a recent Go toolchain)
  • On Linux for GNOME helpers: session bus access (dbus-session)
  • On macOS: Accessibility / Automation permission for System Events when prompted
  • On Windows: a normal user session (no special service install required)

Get the binary​

Option A — build from the repository​

From the monorepo root:

cd agent
go build -o Analog-WakaTime-Agent .

Cross-compile examples:

# Linux amd64
GOOS=linux GOARCH=amd64 go build -o Analog-WakaTime-Agent .

# Windows amd64
GOOS=windows GOARCH=amd64 go build -o Analog-WakaTime-Agent.exe .

# macOS Apple Silicon
GOOS=darwin GOARCH=arm64 go build -o Analog-WakaTime-Agent .

Option B — use a prebuilt release​

If your team ships packaged binaries, place Analog-WakaTime-Agent (or .exe on Windows) in any directory you can write to. The agent creates data/ and logs/ next to the working directory you start it from, so pick a stable folder (for example ~/Analog-WakaTime-Agent/ or C:\Analog-WakaTime-Agent\).

Working directory matters

Local state lives in relative paths (data/, logs/). Always start the agent from the same folder, or wrap it in a small script that cds there first.

First run​

./Analog-WakaTime-Agent start
# or simply:
./Analog-WakaTime-Agent

On first start the agent will:

  1. Create data/ and logs/ if they do not exist
  2. Launch the background worker
  3. Prompt for login if no auth session is stored yet

Login options:

  1. Browser verification code (OAuth Device Flow) — default and recommended
  2. Email and password — classical login against the gateway

After a successful login, tracking continues in the background even if you close the terminal that ran start (the worker is detached).

Verify it is running​

./Analog-WakaTime-Agent status

Typical healthy output:

Agent: running (pid 12345)
Account: authenticated
Logs: logs/agent.log
Offline sync queue: 0

If you are on GNOME or KDE Wayland and the helper is not active yet, status prints a short hint. See Linux desktops.

Stop tracking​

./Analog-WakaTime-Agent stop

This writes data/agent.disabled and asks the worker to shut down. Start again with start when you want tracking back.

Upgrade​

  1. ./Analog-WakaTime-Agent stop
  2. Replace the binary
  3. ./Analog-WakaTime-Agent start

Your data/agent.db (auth + offline queue) is kept unless you delete the data/ directory on purpose.

Uninstall (manual)​

  1. Stop the agent
  2. Remove the binary
  3. Optionally delete data/ and logs/
  4. On Linux GNOME / KDE, remove the helper if you no longer need it:
    • GNOME: disable/remove analog-waketime-focused@analogwaketime in Extensions
    • KDE: disable Analog WakaTime Focused under Window Management → KWin Scripts, and delete ~/.local/share/kwin/scripts/analogwaketimefocused/