aw-watcher-web

aw-watcher-web

A cross-browser WebExtension that serves as a web browser watcher for ActivityWatch.

It enables detailed browser tracking by recording the active tab’s title, URL, audible state, and incognito state. Without it, ActivityWatch can usually only see the browser window title from desktop window watchers.

On Chromium browsers, grouped tabs also include optional tab_group (the group name, including an empty name) and tab_group_color fields. This uses the tabGroups permission. Ungrouped tabs and browsers without that API omit both fields. Group names and colors are sampled with each heartbeat, so renaming a group appears by the next normal heartbeat; moving a tab between groups also triggers an update. As with tab titles and URLs, group names may contain sensitive information and are recorded in your local ActivityWatch data. These fields capture context only: they do not automatically create categories or task reports.

Learn more: Watchers • Architecture • Buckets and events

Installation

Official Releases

Install from official stores:

• Chrome Web Store
• Firefox Add-ons

Development Build

Download the latest development build from our GitHub Actions:

1. Click on the latest successful workflow run
2. Scroll down to “Artifacts”
3. Download either firefox.zip or chrome.zip

Firefox Enterprise Policy

Due to the above issue, a privacy notice must be displayed to comply with the Mozilla Add-on Policy. This can be pre-accepted by setting the following Firefox Enterprise Policy (More about Firefox Policies):

{
    "policies": {
        "3rdparty": {
            "Extensions": {
                "{ef87d84c-2127-493f-b952-5b4e744245bc}": {
                    "consentOfflineDataCollection": true
                }
            }
        }
    }
}

Building from Source

Prerequisites

• Node.js (23 or higher)
• Git
• Make

Build Steps

1. Clone the repository with submodules:

git clone --recurse-submodules https://github.com/ActivityWatch/aw-watcher-web.git
cd aw-watcher-web

2. Install dependencies:

make install

3. Build the extension:

# For Firefox:
make build-firefox

# For Chrome:
make build-chrome

This will create zip files in the artifacts directory:

• artifacts/firefox.zip for Firefox
• artifacts/chrome.zip for Chrome

if you want to build safari version

1. First follow the steps above to build the extension:

make install
make build-safari

2. Convert the extension to Safari format:

xcrun safari-web-extension-converter ./build

after finished, xcode will open automatically.

3. In Xcode:

• Select build target of macOS
• Build the project (⌘B)
• Run the extension (⌘R)

4. Enable the extension in Safari:
   • Open Safari
   • Go to Safari > Settings > Extensions
   • Enable “aw-watcher-web”

Installing the Development Build

Chrome

1. Extract artifacts/chrome.zip to a folder
2. Go to chrome://extensions
3. Enable “Developer mode”
4. Click “Load unpacked” and select the extracted folder

Firefox

1. Go to about:addons
2. Click the gear icon (⚙️) and select “Install Add-on From File…”
3. Navigate to and select the artifacts/firefox.zip file

[!NOTE] For Firefox, installing unsigned extensions requires Firefox Developer Edition or Nightly. In Firefox Developer Edition, you need to set xpinstall.signatures.required to false in about:config.