Install ActivityWatch for Local Time Tracking

ActivityWatch is a free, open-source, privacy-respecting time tracker that runs entirely on your machine. No cloud sync, no subscription—raw data stays in a local SQLite database you own. It tracks active windows, browser tabs (via extension), and anything else you wire up through its watcher system. This guide covers installation from the official release bundle, systemd auto-start, configuring categories, connecting the browser extension, and reading the built-in reports.

Download and Install ActivityWatch

ActivityWatch ships as a self-contained tarball—no package manager integration needed, though community packages exist for Arch. The official release is the safest cross-distro choice.

Fetch the latest release

Check the releases page for the current version. At time of writing that is 0.13.x. Replace the version string below as needed.

cd ~/Downloads
wget https://github.com/ActivityWatch/activitywatch/releases/download/v0.13.3/activitywatch-v0.13.3-linux-x86_64.zip
unzip activitywatch-v0.13.3-linux-x86_64.zip -d ~/opt/activitywatch

If ~/opt does not exist yet, create it first with mkdir -p ~/opt. The extracted directory contains the aw-server, aw-watcher-afk, and aw-watcher-window binaries along with shared libraries.

Arch Linux (AUR)

Arch users can install directly from the AUR. Use your preferred AUR helper:

paru -S activitywatch-bin

The AUR package places binaries in /opt/activitywatch and installs systemd user units automatically. Skip the manual systemd section below if you use this path.

Set Up systemd User Services for Auto-Start

Running ActivityWatch as a systemd user service means it starts on login without root and restarts on crash. You need three units: the server, the window watcher, and the AFK watcher.

Create the service directory

mkdir -p ~/.config/systemd/user

aw-server unit

cat > ~/.config/systemd/user/aw-server.service << 'EOF'
[Unit]
Description=ActivityWatch Server
After=graphical-session.target

[Service]
ExecStart=%h/opt/activitywatch/aw-server/aw-server
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

aw-watcher-window unit

cat > ~/.config/systemd/user/aw-watcher-window.service << 'EOF'
[Unit]
Description=ActivityWatch Window Watcher
After=aw-server.service
Requires=aw-server.service

[Service]
ExecStart=%h/opt/activitywatch/aw-watcher-window/aw-watcher-window
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

aw-watcher-afk unit

cat > ~/.config/systemd/user/aw-watcher-afk.service << 'EOF'
[Unit]
Description=ActivityWatch AFK Watcher
After=aw-server.service
Requires=aw-server.service

[Service]
ExecStart=%h/opt/activitywatch/aw-watcher-afk/aw-watcher-afk
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

Enable and start all three units

systemctl --user daemon-reload
systemctl --user enable --now aw-server.service aw-watcher-window.service aw-watcher-afk.service

Wayland note: aw-watcher-window uses XWayland by default on Wayland compositors because the Wayland protocol does not expose active window info to unprivileged clients. On KDE Plasma 6 and GNOME 45+, window tracking will work through XWayland but may miss native Wayland windows. A pure-Wayland watcher is tracked upstream but not yet stable.

Verify the Server Is Running

systemctl --user status aw-server.service aw-watcher-window.service aw-watcher-afk.service

All three should show active (running). Then open the web UI:

xdg-open http://localhost:5600

The dashboard loads in your browser. If you see event counts climbing under Activity, the watchers are reporting correctly.

Configure Categories

Categories let you label buckets of window titles or URLs as Work, Personal, Coding, etc. Navigate to Settings → Categories in the web UI, or edit the config file directly for repeatable setups.

The category config lives at:

~/.config/activitywatch/aw-server/aw-server.toml

Categories are defined in the web UI as regex rules matched against window titles and app names. For example, to tag anything with "code" or "vim" in the title as Coding:

• Go to Settings → Categories in the web UI.
• Click Add category, name it Coding.
• Add a rule: Type = regex, Match = title, Pattern = (?i)(code|vim|nvim|emacs|intellij|pycharm).
• Save and navigate to the Activity view—you will see the category applied retroactively to existing data.

Category rules are evaluated top-down; more specific rules should appear first. Parent categories (e.g., Work) can contain children (e.g., Work > Coding) for nested reporting.

Install the Browser Extension

The window watcher only sees the browser process name, not individual URLs or tab titles. The browser extension fixes that by sending tab events to a dedicated bucket.

• Firefox: aw-watcher-web on AMO
• Chrome / Chromium / Brave: aw-watcher-web on Chrome Web Store

After installing, click the extension icon and verify it shows Connected to localhost:5600. A new bucket named aw-watcher-web-firefox (or -chrome) will appear in Settings → Buckets within a few seconds of browsing.

If it shows Disconnected, confirm aw-server is running and that your browser is not blocking localhost connections (some hardened profiles do this—check about:config in Firefox for network.proxy.no_proxies_on).

Reading Reports

The web UI at http://localhost:5600 has three main views:

• Activity: Timeline view for a selected day. Shows window, AFK, and browser events stacked. Click any segment to see the raw event detail.
• Timeline: Gantt-style multi-day overview. Useful for spotting patterns across a week.
• Summary: Category totals for a date range—the most useful view for weekly reviews. Drill down into subcategories with the expand arrows.

Export raw data via the REST API if you want to feed it into a spreadsheet or custom script:

curl -s "http://localhost:5600/api/0/buckets/aw-watcher-window_$(hostname)/events?limit=100" \
  | python3 -m json.tool | head -60

Output will vary based on your hostname and current events. The full API docs are served at http://localhost:5600/api/.

Troubleshooting

Watcher shows no window events

Check the watcher log for permission errors:

journalctl --user -u aw-watcher-window.service -n 50

On Wayland without XWayland available, the watcher exits immediately. Confirm XWayland is running with xlsclients or enable it in your compositor settings.

Server port conflict

If port 5600 is taken, edit ~/.config/activitywatch/aw-server/aw-server.toml and set port = 5700 (or any free port), then restart the service:

systemctl --user restart aw-server.service

Services do not start on login

Systemd user services require lingering to be enabled if you want them to start before your first login session (rare, but relevant on headless setups):

loginctl enable-linger $USER

For normal desktop logins this is not necessary—the units start when your user session initialises.

Database grows too large

The SQLite database is at ~/.local/share/activitywatch/aw-server/. ActivityWatch does not auto-prune. If storage becomes a concern, use the REST API to delete old buckets or simply remove the database files and restart (you lose history).