Examples

This section provides practical examples for working with ActivityWatch, from retrieving your data to extending functionality with custom watchers.

Getting Your Data Out

Most users should start here:

• Working with ActivityWatch Data

This comprehensive guide covers:

• Canonical Events - Get processed activity data (what the web UI uses)

• Custom Queries - Write your own analysis using the query language

• Raw Events - Advanced direct access to bucket data

• Safety Best Practices - Avoiding data corruption with proper testing and dry-run modes

The guide includes links to production-ready examples from the aw-client repository.

Writing Your Own Watchers

Want to collect custom data? See:

• Writing your first watcher in Python
• Writing your first watcher in Rust

These guides cover:

• Minimal watcher example - Get started with a simple template

• Full-featured watcher - Complete example with heartbeats and proper structure

• Best practices - Error handling, bucket management, and testing modes

• Rust examples - Alternative implementation for performance-critical watchers

Watchers are small programs that collect data and send it to ActivityWatch. You can track anything with a timestamp!

Example Code Repository

The aw-client examples contain comprehensive, well-documented examples including:

• Time analysis - time_spent_today.py, working_hours.py

• Data export - load_dataframe.py for pandas integration

• Data management - redact_sensitive.py with safe dry-run mode

• Advanced analysis - suggest_categories.py with AI categorization

All examples follow safety best practices with testing modes and error handling.