ActivityWatch’s watcher system is open — any process that can send HTTP requests can act as a watcher. The PythonDocumentation 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.
aw-client library makes this straightforward with a high-level ActivityWatchClient class and heartbeat helpers.
Prerequisites
- ActivityWatch running locally (server on port 5600)
- Python 3.8+
aw-clientinstalled:pip install aw-client
Minimal watcher example
The following watcher polls every 5 seconds and reports the current time as a custom event:my_watcher.py
Create an ActivityWatchClient
Pass your watcher’s name as the first argument. The client connects to
http://localhost:5600 by default.Create a bucket
Call
client.create_bucket(bucket_id, event_type) on startup. This is idempotent — if the bucket already exists, nothing happens.Heartbeat vs. insert_events
| Method | When to use |
|---|---|
client.heartbeat() | Ongoing activity that changes infrequently — the server merges identical heartbeats |
client.insert_events() | Discrete historical events with known timestamps and durations |
Testing your watcher
Usetesting=True when creating the client — this connects to a separate test server instance on port 5666 and uses a _testing suffix on bucket IDs, keeping test data separate from real data.
aw-client Reference
Full API reference for the ActivityWatchClient class
Examples
Real-world watcher examples from the community
