Better Categorizer and Timewarrior Companion

Problem: ActivityWatch collects great data, but it's hard to get useful insights from it.

Solution: Rule-based categorization that transforms raw ActivityWatch events into meaningful tags with multiple output options.

Currently this script exports data from ActivityWatch into TimeWarrior, but I'm planning to let this be a general categorization/tagging tool with possibility to store things in different backends, possibly including to work as a watcher and reexport data back into ActivityWatch.

What it does

• Categorizes ActivityWatch events using configurable rules (browser URLs, editor files, app names, tmux sessions)
• Exports categorized activity to TimeWarrior for time tracking
• Report and analyze commands to aid the user into tweaking the rules and configuration and reexporting the data.

Installation

Let me know if you try it or start using it. Following the SemVer standard, I'm free to break backward compatibility in the 0.x-series - and if I believe I'm the only user, I will most likely do that without any notice.

Installation from PyPI

pip install aw-export-timewarrior

Installation from Source

git clone https://github.com/tobixen/aw-export-timewarrior
cd aw-export-timewarrior
make install

Running as a Systemd Service

For continuous sync mode, you can run as a systemd user service:

make enable-service    # Install and start the service

Check status and logs:

systemctl --user status aw-export-timewarrior
journalctl --user -u aw-export-timewarrior -f

Requirements

• Python - It's currently only tested with 3.13. If you want to use it with other versions, let me know.
• ActivityWatch with aw-watcher-window running
• TimeWarrior installed

Optional Watchers

For richer tag extraction, install additional watchers:

• aw-watcher-web - Extract tags from browser URLs
• aw-watcher-vim - Extract tags from Vim file paths
• activity-watch-mode - Extract tags from Emacs file paths
• aw-watcher-tmux - Extract tags from tmux sessions
• aw-watcher-afk-prompt - Prompt for activity description after AFK periods (legacy name: aw-watcher-ask-away)
• aw-watcher-lid - Track AFK based on laptop lid state

Support for other watchers may be considered, reach out by email or add an issue or pull request for it.

Quick Start

# Continuous sync mode
aw-export-timewarrior sync

# Compare ActivityWatch data with TimeWarrior (dry-run)
aw-export-timewarrior diff --day yesterday

# Apply suggested changes
aw-export-timewarrior diff --day yesterday --apply

# Gain insight into events and rules
aw-export-timewarrior report --from '2 hours ago' --show-rule
aw-export-timewarrior analyze --day yesterday --limit 30

Configuration

Configuration is stored in ~/.config/activitywatch/aw-export-timewarrior/aw-export-timewarrior.toml.

Rule Types

• Browser rules (rules.browser.*): Match URLs with url_regexp
• Editor rules (rules.editor.*): Match by project name or path_regexp
• App rules (rules.app.*): Match by app_names and title_regexp
• Tmux rules (rules.tmux.*): Match by session, window, command, path
• Tag rules (tags.*): Transform tags with add, remove, replace operations
• Exclusive rules (exclusive.*): Prevent conflicting tags from combining

Example Configuration

[rules.browser.github]
url_regexp = "github\\.com"
tags = ["coding", "github"]

[rules.editor.myproject]
path_regexp = "/home/user/projects/myproject"
tags = ["myproject", "coding"]

[rules.app.slack]
app_names = ["slack", "Slack"]
tags = ["communication", "slack"]

[tags.coding-is-work]
source_tags = ["coding"]
add = ["4WORK"]

[exclusive.afk]
tags = ["afk", "not-afk"]

Reusable Lists

A [lists] section defines named lists that can be referenced as @name elsewhere in the config. In list fields (tags, app_names, source_tags, etc.) the reference is replaced by the list items inline. In regexp fields (url_regexp, title_regexp, path_regexp, ...) it expands to a non-capturing alternation (?:item1|item2|...); items are not regex-escaped, so they may themselves be regexp fragments. Lists may reference other lists.

[lists]
customers = ["acme", "emca"]

[rules.editor.customer-work]
path_regexp = "^/home/user/(@customers)/"
tags = ["4WORK", "$1"]

[app_groups] is an older alias for the same mechanism.

Commands

Use --help with any command for detailed options.

Development

make install-dev      # Install with dev dependencies
make test             # Run tests
make lint             # Run ruff check
make format           # Run ruff format
make clean            # Remove build artifacts
make help             # Show all available targets

Documentation

• Tracking Algorithm - How events are processed and exported
• Testing Guide - Running and writing tests
• TODO / Changelog - Completed features and planned work

Background

This tool bridges ActivityWatch (automatic activity tracking) and TimeWarrior (manual time tracking). See the blog posts for rationale:

• General thoughts on time tracking
• Comparison of different software
• Early experiences on combinging AW and TW

License

MIT