Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ActivityWatch/activitywatch/llms.txt

Use this file to discover all available pages before exploring further.

Most ActivityWatch issues fall into a few categories: the server is not running, a watcher lacks the permissions it needs, or there is a port conflict. This guide walks through each scenario step by step.

​
Check that ActivityWatch is running

The system tray icon (from aw-qt) should be visible. Open http://localhost:5600 in your browser — if the page doesn’t load, the server isn’t running.
1

Start ActivityWatch manually

  • Windows / macOS: Launch ActivityWatch from the Start Menu or Applications folder.
  • Linux: Run aw-qt from the terminal, or python -m aw_qt if installed via pip.
2

Verify the server responds

Open http://localhost:5600/api/0/info — a JSON response confirms the server is up.

​
Watcher not recording data

Go to http://localhost:5600 → Buckets and check whether a bucket for aw-watcher-window exists with recent events.
Grant Accessibility permission: System Settings → Privacy & Security → Accessibility → ActivityWatch. On macOS 14+, you may also need Screen Recording permission.

​
Port 5600 already in use

Find what is using the port, then either stop that process or change ActivityWatch’s port. 
# Linux / macOS
lsof -i :5600

# Windows (PowerShell)
netstat -ano | findstr :5600
To change the port, edit the config file:
~/.config/activitywatch/aw-server/aw-server.toml
[server]
port = 5601
Restart ActivityWatch after saving.

​
Checking log files

ls ~/.local/share/activitywatch/log/
Look for Python tracebacks or PermissionError messages, which usually indicate a missing system permission or a locked database file.

​
Data appears missing or incomplete

  • Verify the date selector in the dashboard shows the correct day.
  • Check that the watcher bucket has events for that period.
  • The AFK filter in the Activity view may be hiding idle time — toggle it off to see all events.

​
Getting help

Forum

Post questions and search existing threads

Discord

Real-time chat with the community

GitHub Issues

Report bugs with the issue template

Build docs developers (and LLMs) love

Get started for freeTalk to us